fix(loop): record a durable prompt/blocked for every vetoed prompt

Address review on the interception-seams PR: PromptDecision.reason is documented as the durable record of why a prompt was blocked, but the loop only surfaced it via the fully-blocked batch's `rejected` turn/end. In a MIXED batch — one queued prompt blocked, another allowed — the turn does not end `rejected`, so the blocked prompt and its reason vanished from the session log entirely. Add a `prompt/blocked` SessionEventMap variant (content + source + reason), appended in the open turn at the veto point in place of the user/message the prompt would have become. It is a non-surface, turn-enclosed event (like todo/write): it never reaches deriveMessages(). The fully-blocked batch still also ends `rejected` for boundary balance + ACP settlement. Regression test drives a mixed batch and asserts the blocked prompt is recorded while the allowed one runs — proven red without the append.
2026-07-02 17:03:53 +08:00
parent d3be934a17
commit abe80cec68
10 changed files with 101 additions and 22 deletions
@@ -25,7 +25,7 @@ An agent was registered in the AgentRegistry and is ready to receive messages.

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:229`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:233`](../../packages/core/agent/src/types.ts)

 #### `agent/disposed` — emit

@@ -37,7 +37,7 @@ An agent was disposed and removed from the registry; its fiber and any in-flight

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:235`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:239`](../../packages/core/agent/src/types.ts)

 #### `agent/error` — emit

@@ -49,7 +49,7 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:354`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:358`](../../packages/core/agent/src/types.ts)

 #### `agent/pre-step` — serial

@@ -63,7 +63,7 @@ Serial (awaited in registration order), not a waterfall: a listener mutates the

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:301`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:305`](../../packages/core/agent/src/types.ts)

 #### `agent/prompt-submit` — waterfall

@@ -75,7 +75,7 @@ Waterfall: decide what happens to ONE drained queued message before it becomes a

 Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:311`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:315`](../../packages/core/agent/src/types.ts)

 #### `agent/queued` — emit

@@ -87,7 +87,7 @@ A message entered the agent's inbox (queued or steering). `source` is the resolv

 Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:248`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:252`](../../packages/core/agent/src/types.ts)

 #### `agent/request` — waterfall

@@ -99,7 +99,7 @@ Waterfall: mutate the fully-assembled GenerateOptions before the model call (hoo

 Types: [Agent](../core-data-structures/core.md) · [GenerateOptions](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:320`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:324`](../../packages/core/agent/src/types.ts)

 #### `agent/session-start` — emit

@@ -111,7 +111,7 @@ The agent's session lifecycle began, fired once before its first turn. `source`

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:261`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:265`](../../packages/core/agent/src/types.ts)

 #### `agent/status` — emit

@@ -123,7 +123,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). Drive lifecycle

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:242`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:246`](../../packages/core/agent/src/types.ts)

 #### `agent/steering` — emit

@@ -135,7 +135,7 @@ Steering content was injected into a running turn.

 Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:348`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:352`](../../packages/core/agent/src/types.ts)

 #### `agent/step-result` — waterfall

@@ -147,7 +147,7 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va

 Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:326`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:330`](../../packages/core/agent/src/types.ts)

 #### `agent/stream-chunk` — emit

@@ -159,7 +159,7 @@ A raw StreamChunk arrived from the model (token-level UI/log feed).

 Types: [Agent](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)

-Source: [`packages/core/agent/src/types.ts:343`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:347`](../../packages/core/agent/src/types.ts)

 #### `agent/turn-continuation` — waterfall

@@ -171,7 +171,7 @@ Waterfall: override the turn-continuation decision via a typed ContinuationDecis

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:336`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:340`](../../packages/core/agent/src/types.ts)

 ### `llm/*`

@@ -214,7 +214,7 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 }[T]
 ```

-The twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `context/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the turn-enclosure invariant are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
+The thirteen event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `prompt/blocked`, `context/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the turn-enclosure invariant are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.

 ## The agent handle

@@ -16,6 +16,17 @@ interface SessionEventMap {
  'step/end': { turn: number; step: number }
  /** A user-visible prompt (queued message drained at turn start). */
  'user/message': { content: ContentBlock[]; source: MessageSource }
+  /**
+   * A queued prompt an `agent/prompt-submit` listener VETOED — the durable
+   * record of a blocked prompt and why. Appended in place of the `user/message`
+   * the prompt would have become, so the block survives replay even in a MIXED
+   * batch where another queued prompt is allowed (there the turn does not end
+   * `rejected`, so the boundary reason alone would not preserve it). `content`
+   * is the original prompt the listener rejected; `reason` is the veto text
+   * ({@link PromptDecision} `block.reason`). NOT a {@link SurfaceEventType}: a
+   * blocked prompt produces no LLM message and never reaches `deriveMessages()`.
+   */
+  'prompt/blocked': { content: ContentBlock[]; source: MessageSource; reason: string }
  /**
   * In-session context injection (file-change notices, subdir AGENTS.md,
   * skill content, cron notifications, …). Rendered into the derived history
@@ -16,7 +16,7 @@ Add/reshape the interception seams so every one returns a small, seam-specifi

 **New `agent/*` events** (`dsh-agent`):
 - `agent/session-start(agent, source)` — emit, once before turn 1, carrying a `SessionStartSource` (`startup` for a fresh/forked create, `resume` for a reloaded persisted session; `clear`/`compact` reserved). A pure notification — it CANNOT block startup (a deliberate gap: a bridge logs/injects, it does not gate startup). A listener seeds context via `agent.inject()`.
- `agent/prompt-submit(agent, content, source, next) → PromptDecision` — waterfall, fired per drained queued message inside the open turn, before the `user/message` append. `allow` (optionally rewriting the prompt `content` or attaching `additionalContext`) or `block`.
+- `agent/prompt-submit(agent, content, source, next) → PromptDecision` — waterfall, fired per drained queued message inside the open turn, before the `user/message` append. `allow` (optionally rewriting the prompt `content` or attaching `additionalContext`) or `block` (dropping the prompt; the loop appends a durable `prompt/blocked` in its place — see the dispatch note below).

 **Reshaped** `agent/turn-continuation` from `(…, defaultDecision: boolean) → boolean` to `(…, defaultDecision: ContinuationDecision) → ContinuationDecision`. A `{action:'continue', reason?}` may carry model-facing context recorded as next-step steering in the same turn — the typed twin of the existing `/goal` step-end-steer pattern.

@@ -26,7 +26,7 @@ Add/reshape the interception seams so every one returns a small, seam-specifi

 ### Three load-bearing loop decisions

-1. **Always open the turn first; a fully-blocked batch is a zero-step `rejected` turn.** `prompt-submit` fires AFTER `turn/start`, per message. A batch whose every prompt is blocked does NOT skip the turn — it opens a zero-step turn that closes with `rejected`. This one move resolves three problems at once: (1) turn-enclosure holds (every event has an open turn to live in); (2) the durable `turn/end` is appended and the ACP bridge settles normally off it (mapping `rejected`→`cancelled`) instead of hanging; (3) the block reason is a durable in-turn fact. An `allow`'s `additionalContext` is `inject()`ed into this now-open turn.
+1. **Always open the turn first; a fully-blocked batch is a zero-step `rejected` turn; every veto is recorded as `prompt/blocked`.** `prompt-submit` fires AFTER `turn/start`, per message. A batch whose every prompt is blocked does NOT skip the turn — it opens a zero-step turn that closes with `rejected`. This one move resolves three problems at once: (1) turn-enclosure holds (every event has an open turn to live in); (2) the durable `turn/end` is appended and the ACP bridge settles normally off it (mapping `rejected`→`cancelled`) instead of hanging; (3) the block reason is a durable in-turn fact. Independently, each individual veto appends a `prompt/blocked` session event (the original `content`, `source`, and `reason`) in place of the `user/message` the prompt would have become — necessary because a MIXED batch (one prompt blocked, another allowed) does NOT end `rejected`, so the boundary reason alone would silently lose the blocked prompt on replay. An `allow`'s `additionalContext` is `inject()`ed into this now-open turn.

 2. **Post-tool `additionalContext` is buffered and appended AFTER all `tool/result`s.** `content`/`feedback` shape the result `execute()` returns, but `additionalContext` is a SEPARATE `context/message`, and a single step can carry multiple tool calls. Appending context right after each result would interleave `result(c1) → context → result(c2)` and break tool-call/result adjacency. So `execute()` surfaces `additionalContext` on its `ToolExecutionResult`, and the loop buffers every per-call context for the step and appends them as `context/message`(s) only after every `tool/result` is appended.

@@ -51,7 +51,7 @@ forever:
  TURN (error-contained):
    'turn/start'
    each queued: waterfall agent/prompt-submit → allow (→ session('user/message'),
-      inject additionalContext) | block (drop)
+      inject additionalContext) | block (→ session('prompt/blocked'), drop)
    if every prompt blocked: 'turn/end'(rejected), no step  ⟵ zero-step turn
    STEP loop:
      drain steering
@@ -385,6 +385,14 @@ async function runTurn(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle,
      )
      if (decision.kind === 'block') {
        lastBlockReason = decision.reason
+        // Record the veto durably: `PromptDecision.reason` is the durable record
+        // of why a prompt was blocked, but a fully-blocked batch's `rejected`
+        // turn/end only preserves the LAST reason, and a MIXED batch (this prompt
+        // blocked, another allowed) does not end `rejected` at all — so without
+        // this append a blocked prompt would vanish from the log whenever any
+        // sibling prompt is allowed. `prompt/blocked` sits in the open turn in
+        // place of the `user/message` this prompt would have become.
+        session.append('prompt/blocked', { content: message.content, source: message.source, reason: decision.reason })
        continue
      }
      anyAllowed = true
@@ -176,12 +176,57 @@ describe('agent/prompt-submit', () => {
    expect(log.some(e => e.type === 'turn/end')).toBe(true)
    expect(log.some(e => e.type === 'user/message')).toBe(false)
    expect(log.some(e => e.type === 'step/start')).toBe(false)
+    // the veto is recorded durably as a prompt/blocked in the open turn
+    const blocked = log.find(e => e.type === 'prompt/blocked')
+    expect(blocked?.type === 'prompt/blocked' && blocked.data).toMatchObject({
+      content: [{ type: 'text', text: 'do something' }],
+      reason: 'blocked by policy',
+    })
    // ended rejected with the block reason
    expect(reasons).toEqual([{ kind: 'rejected', reason: 'blocked by policy' }])
    const turnEnd = log.findLast(e => e.type === 'turn/end')
    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'rejected', reason: 'blocked by policy' })
  })

+  it('a mixed batch records a prompt/blocked for the vetoed prompt while the allowed one runs', async () => {
+    // Two prompts queued into ONE turn: block "secret", allow "safe". The turn is
+    // NOT rejected (a prompt was allowed), so without a durable prompt/blocked the
+    // vetoed prompt and its reason would vanish from the log entirely.
+    const adapter = new MockAdapter([textResponse('ran once')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    ctx.on('agent/prompt-submit', async (_agent, content, _source, next): Promise<PromptDecision> => {
+      const text = content.map(b => (b.type === 'text' ? b.text : '')).join('')
+      return text === 'secret' ? { kind: 'block', reason: 'policy: no secrets' } : next()
+    })
+
+    const reasons: TurnEndReason[] = []
+    ctx.on('session/event', (_s, event: SessionEvent) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
+
+    // both sends land before the loop drains → one batched turn
+    send(agent, 'secret')
+    send(agent, 'safe')
+    await waitForIdle(ctx, agent)
+
+    const log = events(agent)
+    // the allowed prompt became a user/message and drove exactly one model call
+    const userMsgs = log.filter(e => e.type === 'user/message')
+    expect(userMsgs).toHaveLength(1)
+    expect(userMsgs[0]?.type === 'user/message' && userMsgs[0].data.content).toEqual([{ type: 'text', text: 'safe' }])
+    expect(adapter.requests.length).toBeGreaterThanOrEqual(1)
+    // the blocked prompt is durably recorded, with its content + reason
+    const blocked = log.filter(e => e.type === 'prompt/blocked')
+    expect(blocked).toHaveLength(1)
+    expect(blocked[0]?.type === 'prompt/blocked' && blocked[0].data).toMatchObject({
+      content: [{ type: 'text', text: 'secret' }],
+      reason: 'policy: no secrets',
+    })
+    // the turn did NOT reject — a sibling was allowed — so the boundary reason
+    // alone would not have preserved the block
+    expect(reasons.some(r => r.kind === 'rejected')).toBe(false)
+  })
+
  it('a throwing prompt-submit listener ends the turn balanced (error), loop survives', async () => {
    const adapter = new MockAdapter([textResponse('after')])
    const ctx = await harness(adapter)
@@ -96,10 +96,14 @@ export interface HookContext {
 * - `allow` proceeds with the prompt; optional `content` REPLACES the prompt
 *   bytes (a rewrite), and optional `additionalContext` is `inject()`ed as a
 *   separate `context/message` the next request also sees.
- * - `block` drops the prompt entirely; `reason` is the durable record of why.
- *   A batch whose every prompt is blocked still opens a zero-step turn that ends
- *   with {@link TurnEndReason} `rejected` (so the boundary stays balanced and a
- *   UI can render "blocked by hook").
+ * - `block` drops the prompt (it never becomes a `user/message`); `reason` is
+ *   the durable record of why. The loop appends a `prompt/blocked` session event
+ *   (carrying the original content, source, and `reason`) in place of the
+ *   dropped `user/message`, so the veto survives replay even in a MIXED batch
+ *   where a sibling prompt is allowed. A batch whose EVERY prompt is blocked
+ *   additionally opens a zero-step turn that ends with {@link TurnEndReason}
+ *   `rejected` (so the boundary stays balanced and a UI can render "blocked by
+ *   hook").
 */
 export type PromptDecision =
  | { kind: 'allow'; content?: ContentBlock[]; additionalContext?: HookContext }
@@ -49,7 +49,7 @@ Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.

 ### Session event vocabulary (`types.ts`)

-The append-only log: `turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/message`, `assistant/chunk`, `tool/call`, `tool/result`, `steering/message`, `context/message`, `todo/write`. Token usage rides on `assistant/message.usage`; an operational error's step is on `turn/end.reason` for `kind: 'error'`.
+The append-only log: `turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `prompt/blocked`, `assistant/message`, `assistant/chunk`, `tool/call`, `tool/result`, `steering/message`, `context/message`, `todo/write`. Token usage rides on `assistant/message.usage`; an operational error's step is on `turn/end.reason` for `kind: 'error'`.

 Merge-extensible via `SessionEventMap` — the compaction seam adds `compact/start`, `compact/summary`, and `compact/end`.

@@ -204,6 +204,17 @@ export interface SessionEventMap {
  'step/end': { turn: number; step: number }
  /** A user-visible prompt (queued message drained at turn start). */
  'user/message': { content: ContentBlock[]; source: MessageSource }
+  /**
+   * A queued prompt an `agent/prompt-submit` listener VETOED — the durable
+   * record of a blocked prompt and why. Appended in place of the `user/message`
+   * the prompt would have become, so the block survives replay even in a MIXED
+   * batch where another queued prompt is allowed (there the turn does not end
+   * `rejected`, so the boundary reason alone would not preserve it). `content`
+   * is the original prompt the listener rejected; `reason` is the veto text
+   * ({@link PromptDecision} `block.reason`). NOT a {@link SurfaceEventType}: a
+   * blocked prompt produces no LLM message and never reaches `deriveMessages()`.
+   */
+  'prompt/blocked': { content: ContentBlock[]; source: MessageSource; reason: string }
  /**
   * In-session context injection (file-change notices, subdir AGENTS.md,
   * skill content, cron notifications, …). Rendered into the derived history