feat: settings toggle for AGENT_NOTIFY_SUMMARY contract injection (#1376)

* feat: settings toggle for AGENT_NOTIFY_SUMMARY contract injection

Add a hub-persisted, default-off Settings control so operators can opt agents into emitting the trailing AGENT_NOTIFY_SUMMARY line. Propagate the resolved flag on CLI session bootstrap and inject at call time for Claude, Codex, OpenCode, and Grok (Cursor still unsupported).

Closes #1375

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: lock hub settings RMW and restore abort deliveryMode

Serialize settings.json updates with the shared .lock protocol and unique
temp files so the new hub toggle cannot clobber CLI/relay fields under
concurrency. Also supply deliveryMode on abort send-error restore so web
typecheck (and CI) pass.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(web): wrap SettingsGeneralPage tests with QueryClientProvider

The hub-settings toggle uses TanStack Query; the settings page suite
was rendering without a QueryClient and blew up CI.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(web): defer summary-contract toggle until settings load

Avoid rendering an interactive false switch while the hub GET is still
in flight, which could overwrite an enabled preference on early click.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(web): clarify Grok coverage for summary-contract toggle

Local Grok has no instruction inject path; settings copy now matches
remote-only Grok support (and still excludes Cursor).

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
HeavyGee
2026-08-06 18:51:35 +08:00
committed by GitHub
co-authored by Cursor
parent 5e7e930713
commit 988f8f183f
30 changed files with 662 additions and 56 deletions
@@ -0,0 +1,66 @@
import { afterEach, describe, expect, it } from 'vitest'
import {
applyHubSessionSummaryContract,
buildSessionSummaryInstruction,
isSessionSummaryContractEnabled,
resetSessionSummaryContractForTests,
SESSION_SUMMARY_CONTRACT_LINE,
sessionSummaryInstructionOrEmpty,
withSessionSummaryInstruction
} from './sessionSummaryInstruction'
describe('sessionSummaryInstruction', () => {
afterEach(() => {
resetSessionSummaryContractForTests()
})
it('is disabled by default (upstream opt-in)', () => {
expect(isSessionSummaryContractEnabled({})).toBe(false)
expect(isSessionSummaryContractEnabled({ HAPI_SESSION_SUMMARY_CONTRACT: '' })).toBe(false)
expect(sessionSummaryInstructionOrEmpty({})).toBe('')
})
it('enables when hub preference is applied', () => {
applyHubSessionSummaryContract(true)
expect(isSessionSummaryContractEnabled({})).toBe(true)
expect(sessionSummaryInstructionOrEmpty({})).toContain(SESSION_SUMMARY_CONTRACT_LINE)
applyHubSessionSummaryContract(false)
expect(isSessionSummaryContractEnabled({})).toBe(false)
})
it('lets explicit env override hub preference', () => {
applyHubSessionSummaryContract(true)
expect(isSessionSummaryContractEnabled({ HAPI_SESSION_SUMMARY_CONTRACT: '0' })).toBe(false)
applyHubSessionSummaryContract(false)
expect(isSessionSummaryContractEnabled({ HAPI_SESSION_SUMMARY_CONTRACT: '1' })).toBe(true)
expect(isSessionSummaryContractEnabled({ HAPI_SESSION_SUMMARY_CONTRACT: 'true' })).toBe(true)
})
it('treats common falsy env spellings as off', () => {
for (const value of ['0', 'false', 'off', 'no', 'FALSE', ' Off ']) {
expect(isSessionSummaryContractEnabled({ HAPI_SESSION_SUMMARY_CONTRACT: value })).toBe(false)
}
})
it('builds the canonical contract line without surveillance framing', () => {
const body = buildSessionSummaryInstruction()
expect(body).toContain(SESSION_SUMMARY_CONTRACT_LINE)
expect(body.toLowerCase()).toContain('session tracking')
expect(body.toLowerCase()).not.toContain('overseer')
expect(body.toLowerCase()).not.toContain('surveillance')
})
it('appends to an existing base prompt when enabled', () => {
applyHubSessionSummaryContract(true)
const out = withSessionSummaryInstruction('Be helpful.', {})
expect(out.startsWith('Be helpful.')).toBe(true)
expect(out).toContain(SESSION_SUMMARY_CONTRACT_LINE)
})
it('leaves base unchanged when disabled', () => {
expect(withSessionSummaryInstruction('Be helpful.', {})).toBe('Be helpful.')
expect(withSessionSummaryInstruction('Be helpful.', { HAPI_SESSION_SUMMARY_CONTRACT: '0' }))
.toBe('Be helpful.')
})
})
@@ -0,0 +1,77 @@
/**
* Optional session-status summary instruction for non-Cursor agent flavors.
*
* Cursor ACP has no system-prompt / rules-overlay seam in upstream today, so
* it is intentionally not covered here. Claude / Codex / OpenCode / Grok get
* this text via their existing system-prompt / developer-instructions /
* one-shot instruction paths when the operator opts in.
*
* Resolution order:
* 1. Explicit `HAPI_SESSION_SUMMARY_CONTRACT` env (0|false|off|no → off; anything else → on)
* 2. Hub preference applied via `applyHubSessionSummaryContract` (from session bootstrap)
* 3. Default: off (matches A2A RFC — emission stays optional indefinitely)
*/
let hubPreference: boolean | undefined
/** Apply the hub-resolved toggle from session create/get bootstrap. */
export function applyHubSessionSummaryContract(enabled: boolean): void {
hubPreference = enabled
}
/** Test-only: clear hub preference between cases. */
export function resetSessionSummaryContractForTests(): void {
hubPreference = undefined
}
export function isSessionSummaryContractEnabled(
env: NodeJS.ProcessEnv = process.env
): boolean {
const raw = env.HAPI_SESSION_SUMMARY_CONTRACT
if (raw !== undefined && raw !== '') {
const normalized = raw.trim().toLowerCase()
return !(normalized === '0' || normalized === 'false' || normalized === 'off' || normalized === 'no')
}
return hubPreference === true
}
/**
* Canonical trailing-line contract. Matches the FCM / native-companion parser
* in `@hapi/protocol` (`extractNotifySummary`).
*/
export const SESSION_SUMMARY_CONTRACT_LINE =
'AGENT_NOTIFY_SUMMARY {"version":1,"agent":"<agent-id>","project":"<project>","status":"done|blocked|needs_review|needs_decision|failed|stalled","action":"<=12 words","summary":"one-line triage"}'
/**
* Body appended to flavor system / developer instructions when enabled.
* Keep short — rides every session's prompt budget.
*/
export function buildSessionSummaryInstruction(): string {
return [
'Session status summary:',
'End every response with a single machine-readable status line (no backticks)',
'so this workspace\'s session tracking can record progress. Put it on its own',
'final line after all other content:',
SESSION_SUMMARY_CONTRACT_LINE,
'Use status "blocked" if unsure. Keep action to 12 words or fewer when status',
'is "done" and follow-up remains.'
].join('\n')
}
/** Empty string when disabled so callers can append unconditionally. */
export function sessionSummaryInstructionOrEmpty(
env: NodeJS.ProcessEnv = process.env
): string {
return isSessionSummaryContractEnabled(env) ? buildSessionSummaryInstruction() : ''
}
/** Append instruction to an existing prompt block (blank line separator). */
export function withSessionSummaryInstruction(
base: string,
env: NodeJS.ProcessEnv = process.env
): string {
const extra = sessionSummaryInstructionOrEmpty(env)
if (!extra) return base
const trimmed = base.trimEnd()
return trimmed.length > 0 ? `${trimmed}\n\n${extra}` : extra
}