Merge origin/master into codex/provider-retry-policy

2026-07-25 10:35:22 +08:00
parent b58e33268a f7b36bd36d
commit a193ea7092
766 changed files with 19344 additions and 1424 deletions
--- a/packages/ui/acp/README.md
+++ b/packages/ui/acp/README.md
@@ -29,7 +29,7 @@ The `initialize` handshake reports a fixed server identity (`agentInfo: { name:
 | `session/new` | `ctx.agents.create({ sessionId, meta:{cwd} })` | creates a new session/agent; N concurrent sessions are allowed, keyed by id; advertises the effective command snapshot; `cwd` must be absolute (it becomes the session's workspace — see Per-session cwd); non-empty `additionalDirectories` and `mcpServers` rejected |
 | `session/load` | `ctx.agents.resume(...)` | reserves the id, verifies the persisted cwd, resumes, replays user, assistant, tool, and title events, and re-advertises commands |
 | `session/list` | `ctx.sessionQuery` | returns live-preferred newest-first sessions with absolute cwd and optional folded title; supports exact normalized cwd filtering, returns no cursor, and rejects supplied cursors |
-| `session/prompt` | `ctx.commands.execute()` or `agent.send()` | a flattened prompt beginning with `/` stays in the direct command plane; ordinary prompts support ACP `text` and `resource_link`; `dsh-session:` links and inline mentions are snapshotted through optional `ctx.sessionReferences` before enqueue; unsupported content, unavailable reference capability, failed snapshots, and empty prompts are rejected; one request is in flight per session and settles on the owning turn's end, with an error turn rejecting the RPC |
+| `session/prompt` | `ctx.commands.execute()` or `agent.followup()` | a flattened prompt beginning with `/` stays in the direct command plane; ordinary prompts support ACP `text` and `resource_link`; `dsh-session:` links and inline mentions are snapshotted through optional `ctx.sessionReferences` before enqueue; unsupported content, unavailable reference capability, failed snapshots, and empty prompts are rejected; one request is in flight per session and settles on the owning turn's end, with an error turn rejecting the RPC |
 | `session/cancel` | command `AbortSignal` or `agent.cancel()` | aborts the exact direct command, or applies the queue-aware agent cancel and settles its prompt `cancelled`; one session never cancels another |
 | `session/update` | `session/event` | streams user replay, assistant text/reasoning, retry/failure attempt markers, tool render intents, and `session_info_update` title revisions |
 | `elicitation/create` | `ctx.userInteraction.ask()` | maps `ask_user_question` questions to ACP form elicitations; option descriptions are shown in enum titles, `multi_select` uses ACP array enums, optionless requests use a required `custom` field, and a non-empty custom answer overrides any selected choice |
--- a/packages/ui/acp/acp-feature-support.md
+++ b/packages/ui/acp/acp-feature-support.md
@@ -23,7 +23,7 @@ The bridge implements the **core prompt-turn loop** for N concurrent sessions: i
 | `session/load` | S | ✅ | ✅ | ✅ | Maps to `agents.resume` + full event-log replay; validates persisted `cwd` before constructing the agent. |
 | `session/resume` | S | ❌ | ✅ | ✅ | Reconnect WITHOUT replay; gated by `sessionCapabilities.resume`. Not advertised. |
 | `session/close` | S | ❌ | ✅ | ✅ | No `session/close` handler — the SDK dispatch returns `method_not_found`. The bridge tears sessions down on client disconnect / Cordis disposal (cross-cutting, see [§8](#8-cross-cutting)), but that is not the on-demand per-session method. |
-| `session/prompt` | S | ✅ | ✅ | ✅ | A flattened prompt beginning with `/` dispatches through `ctx.commands` without a model request; ordinary input maps to `agent.send`. One request is in flight per session. |
+| `session/prompt` | S | ✅ | ✅ | ✅ | A flattened prompt beginning with `/` dispatches through `ctx.commands` without a model request; ordinary input maps to `agent.followup`. One request is in flight per session. |
 | `session/cancel` | S | ✅ | ✅ | ✅ | Aborts the exact direct command, or applies queue-aware `agent.cancel` and settles its prompt `cancelled`, scoped to one session. |
 | `session/set_mode` | S | ✅ | ✅ | ✅ | Composed opportunistically: with `@deepseek-ai/dsh-plan-mode` mounted, `session/new`/`session/load` advertise the fixed `default` / `plan` projection and `session/set_mode` records the boolean pending intent (optimistic `current_mode_update`; logged `plan/mode` lands at the turn boundary). Without the plugin: no `modes` advertised, `set_mode` rejected (see [§6 Modes](#6-session-modes--config-options--models)). |
 | `session/set_config_option` | S | ✅ | ✅ | ✅ | A provider/model select is present for a complete registered target; one `permission` select is added when `ctx.permission` is composed. Every response carries the complete refreshed state. |
--- a/packages/ui/acp/src/index.ts
+++ b/packages/ui/acp/src/index.ts
@@ -1056,7 +1056,7 @@ export function apply(ctx: Context, config: AcpConfig): void {
        }
        const { text } = referencedPrompt
        let preparedContent: ContentBlock[] = [{ type: 'text', text }]
-        let preparedContexts: NonNullable<Parameters<Agent['send']>[1]>['contexts'] = []
+        let preparedContexts: NonNullable<Parameters<Agent['followup']>[1]>['contexts'] = []
        if (referencedPrompt.references.length > 0) {
          const sessionReferences = ctx.get('sessionReferences')
          if (sessionReferences === undefined) {
@@ -1081,14 +1081,14 @@ export function apply(ctx: Context, config: AcpConfig): void {
          }
          assertOpen()
        }
-        // Install the in-flight slot BEFORE send() (send does not synchronously
+        // Install the in-flight slot BEFORE followup() (followup does not synchronously
        // flip status to running; the session/event listener records the turn
        // number and settle/rejects it). Capture the log length now as the
        // A turn that ends in error rejects this promise (the codec never
        // produces an error stop reason).
        const stopReason = await new Promise<StopReason>((resolve, reject) => {
          rec.inflight = { resolve, reject, turn: undefined }
-          rec.agent.send(preparedContent, { contexts: preparedContexts })
+          rec.agent.followup(preparedContent, { contexts: preparedContexts })
        })
        return { stopReason }
      },
@@ -1333,8 +1333,8 @@ function validateMcpServers(params: { mcpServers?: unknown[] }): void {
 * generic fallback (title = tool name, raw args as input) when no registry is
 * available (e.g. pure translator tests).
 *
- * Other event types (turn/step boundaries, context/message, …) produce
- * no client update.
+ * Other event types (turn/step boundaries, injected-context user messages, …)
+ * produce no client update.
 * @param sessionId - the ACP session id stamped on every emitted notification.
 * @param event - the harness session event to translate.
 * @param notify - sink for each produced `session/update` notification; called
@@ -1375,6 +1375,9 @@ export function streamSessionEventUpdate(
    }
    case 'user/message': {
      if (!includeUserMessages) return
+      // Only a direct human prompt replays as a user message; injected context
+      // (plugin/goal source) is not the user's turn and produces no update.
+      if (event.data.source.kind !== 'user') return
      // Replay the user's prompt so a loaded session shows both sides of each
      // turn. Live prompt turns suppress this path to avoid duplicating what
      // the client just sent.
@@ -1421,7 +1424,7 @@ export function streamSessionEventUpdate(
      notify({ sessionId, update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text } } })
      return
    }
-    // non-error turn/step boundaries, context/message, steering,
+    // non-error turn/step boundaries, injected-context user messages, steering,
    // assistant/message — no direct ACP client update.
    default:
      return
--- a/packages/ui/acp/tests/bridge.spec.ts
+++ b/packages/ui/acp/tests/bridge.spec.ts
@@ -383,7 +383,7 @@ describe('acp bridge', () => {
        },
      }],
    })
-    expect(target.events.some(event => event.type === 'context/message')).toBe(false)
+    expect(target.events.some(event => event.type === 'user/message' && event.data.source.kind !== 'user')).toBe(false)
    const request = JSON.stringify(harness.adapter.requests[0]?.messages)
    expect(request).toContain('untrusted, read-only snapshot')
    expect(request).toContain('source background')
--- a/packages/ui/acp/tests/dispose.spec.ts
+++ b/packages/ui/acp/tests/dispose.spec.ts
@@ -264,7 +264,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    const handle = await harness.ctx.agents.create({
      sessionId: SessionId('guard-a'), agentOptions: { provider: 'mock', model: 'mock' },
    })
-    handle.agent.send([{ type: 'text', text: 'go' }])
+    handle.agent.followup([{ type: 'text', text: 'go' }])
    await handle.agent.whenIdle()
    expect(harness.ctx.sessions.get(SessionId('guard-a'))).toBeDefined()

@@ -288,7 +288,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    // Drive a turn that hangs in the model stream, so the loop is mid-turn when
    // disposed — its exit runs a final session/flush we can gate to hold the
    // teardown observably in-flight.
-    handle.agent.send([{ type: 'text', text: 'go' }])
+    handle.agent.followup([{ type: 'text', text: 'go' }])
    await new Promise(r => setTimeout(r, 30))
    expect(handle.agent.status).toBe('running')
    let releaseFlush!: () => void
--- a/packages/ui/acp/tests/edges.spec.ts
+++ b/packages/ui/acp/tests/edges.spec.ts
@@ -30,7 +30,7 @@ describe('acp bridge — demux & config edges', () => {
    const before = harness.updates.length

    const { agent: foreign } = await harness.ctx.agents.create({ sessionId: SessionId('foreign-session'), agentOptions: { provider: 'mock', model: 'mock' } })
-    foreign.send([{ type: 'text', text: 'hi' }])
+    foreign.followup([{ type: 'text', text: 'hi' }])
    await foreign.whenIdle()
    await new Promise(r => setTimeout(r, 10))

--- a/packages/ui/acp/tests/turns.spec.ts
+++ b/packages/ui/acp/tests/turns.spec.ts
@@ -285,10 +285,10 @@ describe('acp bridge — turn outcomes', () => {
    const sessionId = await newSession(harness)
    const agent = harness.ctx.agents.get(SessionId(sessionId))!
    // On the queued prompt, synchronously inject a one-shot context turn (idle
-    // inject writes turn/start{injection} → context/message → turn/end). Fire
+    // inject writes turn/start{injection} → user/message → turn/end). Fire
    // once so it lands between install and the prompt turn.
    let injected = false
-    harness.ctx.on('agent/queued', (subject) => {
+    harness.ctx.on('agent/inbox/enqueue', (subject) => {
      if (subject === agent && !injected) {
        injected = true
        agent.inject([{ type: 'text', text: 'ctx note' }], { source: { kind: 'plugin', plugin: 'test' } })
--- a/packages/ui/jsonrpc/src/server.ts
+++ b/packages/ui/jsonrpc/src/server.ts
@@ -152,7 +152,7 @@ export class HarnessSdkServer {
    rec.activePrompt = true
    try {
      rec.lastTurnEnd = undefined
-      rec.handle.agent.send(params.contentBlocks)
+      rec.handle.agent.followup(params.contentBlocks)
      await rec.handle.agent.whenIdle()
      const status = this.finishedStatus(rec.lastTurnEnd)
      this.transport.notify('session.finished', {
--- a/packages/ui/jsonrpc/tests/server.spec.ts
+++ b/packages/ui/jsonrpc/tests/server.spec.ts
@@ -5,7 +5,7 @@ import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import { type Agent, type AgentHandle } from '@deepseek-ai/dsh-agent'
+import { AgentMessageId, type Agent, type AgentHandle } from '@deepseek-ai/dsh-agent'

 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
@@ -152,7 +152,7 @@ describe('HarnessSdkServer', () => {
        meta: { cwd: storageDir },
        agentOptions: { provider: 'deepseek', model: 'dsagent-model' },
      })
-      orphanHandle.agent.send([{ type: 'text', text: 'outside the sdk session map' }])
+      orphanHandle.agent.followup([{ type: 'text', text: 'outside the sdk session map' }])
      await orphanHandle.agent.whenIdle()
      await orphanHandle.dispose()
      expect(llmServer.requests).toHaveLength(3)
@@ -170,16 +170,16 @@ describe('HarnessSdkServer', () => {
    const mainWhenIdle = vi.fn<() => Promise<void>>()
      .mockReturnValueOnce(firstMainIdle)
      .mockResolvedValue(undefined)
-    const mainSend = vi.fn()
-    const mainAgent = {
-      send: mainSend,
+    const mainFollowup = vi.fn<Agent['followup']>().mockReturnValue(AgentMessageId('main-followup'))
+    const mainAgent = ({
+      followup: mainFollowup,
      whenIdle: mainWhenIdle,
-    } as unknown as Agent
-    const otherSend = vi.fn()
-    const otherAgent = {
-      send: otherSend,
+    } satisfies Pick<Agent, 'followup' | 'whenIdle'>) as unknown as Agent
+    const otherFollowup = vi.fn<Agent['followup']>().mockReturnValue(AgentMessageId('other-followup'))
+    const otherAgent = ({
+      followup: otherFollowup,
      whenIdle: vi.fn(() => Promise.resolve()),
-    } as unknown as Agent
+    } satisfies Pick<Agent, 'followup' | 'whenIdle'>) as unknown as Agent
    const mainHandle = { agent: mainAgent, dispose: vi.fn(() => Promise.resolve()) }
    const otherHandle = { agent: otherAgent, dispose: vi.fn(() => Promise.resolve()) }
    const create = vi.fn(async (options: { sessionId: SessionId }) =>
@@ -196,7 +196,7 @@ describe('HarnessSdkServer', () => {
    })

    const first = prompt('main', 'first')
-    await vi.waitFor(() => { expect(mainSend).toHaveBeenCalledOnce() })
+    await vi.waitFor(() => { expect(mainFollowup).toHaveBeenCalledOnce() })

    await expect(prompt('main', 'overlap')).rejects.toThrow('session already has an active prompt: main')
    await expect(prompt('other', 'independent')).resolves.toEqual({ accepted: true })
@@ -208,8 +208,8 @@ describe('HarnessSdkServer', () => {
    await expect(prompt('main', 'failing')).rejects.toThrow('turn wait failed')
    await expect(prompt('main', 'after failure')).resolves.toEqual({ accepted: true })

-    expect(mainSend).toHaveBeenCalledTimes(4)
-    expect(otherSend).toHaveBeenCalledOnce()
+    expect(mainFollowup).toHaveBeenCalledTimes(4)
+    expect(otherFollowup).toHaveBeenCalledOnce()
    await server.shutdown()
    expect(mainHandle.dispose).toHaveBeenCalledOnce()
    expect(otherHandle.dispose).toHaveBeenCalledOnce()
@@ -225,9 +225,9 @@ describe('HarnessSdkServer', () => {
      shutdown(): Promise<Record<string, never>>
    }
    const session = ctx.sessions.create(SessionId('message-outcome'))
-    const agent = {
+    const agent = ({
      session,
-      send(content: { type: 'text'; text: string }[]) {
+      followup(content: { type: 'text'; text: string }[]) {
        session.append('turn/start', {
          turn: 1,
          trigger: { kind: 'message', source: { kind: 'user' } },
@@ -241,14 +241,15 @@ describe('HarnessSdkServer', () => {
          turn: 2,
          trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'late-metadata' } },
        })
-        session.append('context/message', {
+        session.append('user/message', {
          content: [{ type: 'text', text: 'late metadata' }],
          source: { kind: 'plugin', plugin: 'late-metadata' },
        }, { surfaceOp: 'append' })
        session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
+        return AgentMessageId('message-outcome')
      },
      whenIdle: () => Promise.resolve(),
-    } as unknown as Agent
+    } satisfies Pick<Agent, 'session' | 'followup' | 'whenIdle'>) as unknown as Agent
    server.sessions.set('message-outcome', {
      handle: { agent, dispose: () => Promise.resolve() },
      lastTurnEnd: undefined,
--- a/packages/ui/tui/README.md
+++ b/packages/ui/tui/README.md
@@ -18,9 +18,9 @@ Before model output, session events, tool presenters, questions, configuration,

 Typing `@` at a token boundary searches files and directories under the session working directory. A bare fuzzy query uses a reusable bounded workspace index; a query containing `/` lists that directory directly, and selecting a folder keeps completion open for descent. Whitespace-bearing paths are inserted as `@"path with spaces"`. Selecting a file inserts only its path and a trailing space: the TUI does not read it, attach hidden context, or replace it with a reference object. When a model-facing `read` tool is registered, the TUI adds one fixed system-prompt instruction telling the model to read an explicit path when its contents are needed.

-When optional `ctx.sessionReferences` is mounted, the same `@` menu also offers metadata-only session candidates, inserts `@[label](dsh-session:<payload>)`, and prepares the selected snapshots before dispatch. Session references remain structured because the model has no filesystem-like tool for retrieving session snapshots later. Preparation disables duplicate submission and restores the editor input on failure. The TUI chooses `agent.steer()` or `agent.send()` from the status after that asynchronous preparation, so idle sends still dispatch `agent/prompt-submit` while in-turn steering joins at a checkpoint without that hook.
+When optional `ctx.sessionReferences` is mounted, the same `@` menu also offers metadata-only session candidates, inserts `@[label](dsh-session:<payload>)`, and prepares the selected snapshots before dispatch. Session references remain structured because the model has no filesystem-like tool for retrieving session snapshots later. Preparation disables duplicate submission and restores the editor input on failure. The TUI chooses `agent.steer()` or `agent.followup()` from the status after that asynchronous preparation, so idle follow-ups still dispatch `agent/prompt-submit` while in-turn steering joins at a checkpoint without that hook.

-While the agent is running, ordinary editor submissions call `agent.steer()`; otherwise they call `agent.send()`. A slash at the start of the submitted line enters `ctx.commands` instead: known commands execute directly, unknown commands produce a warning, and neither path automatically reaches the model. A command producer may explicitly schedule agent work; [`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-surfaces) uses that contract for `/plan [message]`. The TUI registers `/help`, `/model`, `/clear`, `/reasoning`, `/tools`, `/redraw`, `/reload`, `/resume`, `/status`, and `/exit` as agent-scoped definitions; every other effective command joins autocomplete and `/help` dynamically, as do `/skill:` completions. A status line above the editor reports the turn phase the TUI derives from session events — waiting for the first token, thinking, responding, or executing tools — with the elapsed time in that phase and the running step total, refreshed each second, and ends with the `Enter sends steering, Esc cancels` hint; while steering messages wait to reach the model it inserts a `N queued ·` badge before the hint that clears as each drains. Ctrl+C or Escape cancels a running turn. Tool cards collapse long bodies into a configurable head/tail preview; Ctrl+O toggles every card between its preview and full output. Ctrl+R toggles reasoning, Ctrl+L redraws, and Ctrl+D exits while idle.
+While the agent is running, ordinary editor submissions call `agent.steer()`; otherwise they call `agent.followup()`. A slash at the start of the submitted line enters `ctx.commands` instead: known commands execute directly, unknown commands produce a warning, and neither path automatically reaches the model. A command producer may explicitly schedule agent work; [`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-surfaces) uses that contract for `/plan [message]`. The TUI registers `/help`, `/model`, `/clear`, `/reasoning`, `/tools`, `/redraw`, `/reload`, `/resume`, `/status`, and `/exit` as agent-scoped definitions; every other effective command joins autocomplete and `/help` dynamically, as do `/skill:` completions. A status line above the editor reports the turn phase the TUI derives from session events — waiting for the first token, thinking, responding, or executing tools — with the elapsed time in that phase and the running step total, refreshed each second, and ends with the `Enter sends steering, Esc cancels` hint; while steering messages wait to reach the model it inserts a `N queued ·` badge before the hint that clears as each drains. Ctrl+C or Escape cancels a running turn. Tool cards collapse long bodies into a configurable head/tail preview; Ctrl+O toggles every card between its preview and full output. Ctrl+R toggles reasoning, Ctrl+L redraws, and Ctrl+D exits while idle.

 `/model` opens the advisory `ctx.llm` catalog as a keyboard selector: Up/Down moves, Enter selects, and Escape closes it. `/model <model>` still selects an unambiguous model id directly, while `/model <provider>/<model>` selects an exact target. The configured target or latest logged request header initializes the selector, and an unlisted current model remains visible because catalogs are advisory. Selection is local to this TUI session. Prompt assembly snapshots the target for one step, replaces `{{provider}}` and `{{model}}`, and applies the same pair through `agent/request`; a switch during assembly therefore starts with a later step. The request header durably records targets that reach the model, while an unused selection remains process-local.

@@ -80,7 +80,7 @@ The palette uses the standard 16-color ANSI foregrounds and SGR attributes, whic

 #### What the model sees

-Each non-empty ordinary editor submission becomes one text block, sent with `agent.send()` while the target agent is idle and `agent.steer()` while it is running. A session mention becomes readable `@label` text plus the durable untrusted context defined by [`dsh-session-reference`](../../context/session-reference/README.md); its full JSON is hidden behind a compact reference card. Slash commands and keybindings are TUI-only; command results remain terminal notices. A command producer may schedule a separate agent input, such as the optional message accepted by `/plan [message]`.
+Each non-empty ordinary editor submission becomes one text block, sent with `agent.followup()` while the target agent is idle and `agent.steer()` while it is running. A session mention becomes readable `@label` text plus the durable untrusted context defined by [`dsh-session-reference`](../../context/session-reference/README.md); its full JSON is hidden behind a compact reference card. Slash commands and keybindings are TUI-only; command results remain terminal notices. A command producer may schedule a separate agent input, such as the optional message accepted by `/plan [message]`.

 #### Token effect

@@ -128,7 +128,7 @@ Changing provider or model enters that target's cache domain; no cache reuse acr

 #### What the model sees

-A `/skill:<name> [instructions]` submission loads the named skill and delivers one text block: a `<skill name="…">` element wrapping the skill's instructions — preceded, when the provider exposes a resource base, by a line locating the skill's relative resources — followed by any trailing instructions the user typed. Delivery follows the same send-while-idle / steer-while-running rule as ordinary input. The command, not the model, chooses the skill; model-disabled skills are omitted from autocomplete but stay loadable by exact name.
+A `/skill:<name> [instructions]` submission loads the named skill and delivers one text block: a `<skill name="…">` element wrapping the skill's instructions — preceded, when the provider exposes a resource base, by a line locating the skill's relative resources — followed by any trailing instructions the user typed. Delivery follows the same followup-while-idle / steer-while-running rule as ordinary input. The command, not the model, chooses the skill; model-disabled skills are omitted from autocomplete but stay loadable by exact name.

 #### Token effect

--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
@@ -1884,14 +1884,15 @@ export function createTuiChat(
  let toolsExpanded = false
  let streaming: StreamingAssistantComponent | undefined
  let runningStatus: RunningStatus | undefined
-  // Steering messages queued during the running turn (`agent/queued`) that the
-  // loop has not yet drained, shown as a badge on the status line. Each entry is
-  // the queued message's serialized source: a drain (`steering/message`) removes
-  // one MATCHING entry, so loop-authored steering — continuation reasons enter
-  // the inbox without an `agent/queued` event — cannot consume a pending user
-  // message's slot. Cleared on leaving `running`, which also absorbs a
-  // cancellation that discards the queue without logging drains; the status
-  // line exists only while running, so idle carries no badge to keep current.
+  // Steering messages queued during the running turn (`agent/inbox/enqueue`
+  // with `info.steering`) that the loop has not yet drained, shown as a badge on
+  // the status line. Each entry is the queued message's serialized source: a
+  // drain (`steering/message`) removes one MATCHING entry, so a loop-authored
+  // continuation reason (which enqueues and drains under its own source) pushes
+  // and pops its own slot and cannot consume a pending user message's slot.
+  // Cleared on leaving `running`, which also absorbs a cancellation that
+  // discards the queue without logging drains; the status line exists only
+  // while running, so idle carries no badge to keep current.
  const pendingSteering: string[] = []
  let disposed = false
  let shuttingDown: Promise<void> | undefined
@@ -2238,6 +2239,29 @@ export function createTuiChat(
  const renderEvent = (event: SessionEvent, options: { addHistory: boolean; renderChunks: boolean }): void => {
    switch (event.type) {
      case 'user/message': {
+        // Injected context (plugin/goal source) renders as a dim context card,
+        // not a human bubble; only a direct human prompt is a user message. The
+        // boolean avoids narrowing `source`, so the label keeps its full union.
+        const source = event.data.source
+        if (source.kind !== 'user') {
+          const references = sessionReferenceCard(event.data.meta)
+          if (references !== undefined) {
+            chat.addChild(new Spacer(1))
+            chat.addChild(new Text(palette.dim(`Referenced sessions · ${references.map(displayText).join(', ')}`), 1, 0))
+            break
+          }
+          const text = displayText(contentText(event.data.content).trim())
+          if (text) {
+            // The tui type view lacks plugin-augmented source kinds (e.g. goal),
+            // so read the display label without narrowing on `kind`.
+            const labelled = source as { kind: string; plugin?: string }
+            const label = labelled.plugin ?? labelled.kind
+            chat.addChild(new Spacer(1))
+            chat.addChild(new Text(palette.dim(`Context · ${displayText(label)}`), 1, 0))
+            chat.addChild(new Text(palette.muted(text), 1, 0))
+          }
+          break
+        }
        const text = displayText(contentText(displayPromptContent(event.data)).trim())
        if (text) {
          chat.addChild(new Spacer(1))
@@ -2262,22 +2286,6 @@ export function createTuiChat(
        }
        break
      }
-      case 'context/message': {
-        const references = sessionReferenceCard(event.data.meta)
-        if (references !== undefined) {
-          chat.addChild(new Spacer(1))
-          chat.addChild(new Text(palette.dim(`Referenced sessions · ${references.map(displayText).join(', ')}`), 1, 0))
-          break
-        }
-        const text = displayText(contentText(event.data.content).trim())
-        if (text) {
-          const source = event.data.source.kind === 'plugin' ? event.data.source.plugin : event.data.source.kind
-          chat.addChild(new Spacer(1))
-          chat.addChild(new Text(palette.dim(`Context · ${displayText(source)}`), 1, 0))
-          chat.addChild(new Text(palette.muted(text), 1, 0))
-        }
-        break
-      }
      case 'prompt/blocked':
        appendNotice(`Prompt blocked: ${event.data.reason}`, 'warning')
        break
@@ -2363,7 +2371,6 @@ export function createTuiChat(
      const isSurface = event.type === 'user/message'
        || event.type === 'assistant/message'
        || event.type === 'tool/result'
-        || event.type === 'context/message'
        || event.type === 'steering/message'
      if (isSurface && !active.has(event.seq)) continue
      if (event.type === 'tool/call' && !activeCalls.has(event.data.callId)) continue
@@ -2805,7 +2812,7 @@ export function createTuiChat(
    } else if (agent.status === 'running') {
      agent.steer(content, { contexts })
    } else {
-      agent.send(content, { contexts })
+      agent.followup(content, { contexts })
    }
  }

@@ -3149,9 +3156,9 @@ export function createTuiChat(
    advanceTurnPhase(event)
    if (event.type === 'steering/message') {
      // A queued steering message reached the model as it drained; drop its
-      // entry from the badge. Matching by source keeps loop-authored steering
-      // (e.g. continuation reasons), which logs here without a matching
-      // `agent/queued` increment, from consuming a pending user slot.
+      // entry from the badge. Matching by source keeps a loop-authored
+      // continuation reason popping its own enqueued slot rather than a pending
+      // user message's slot.
      const drained = pendingSteering.indexOf(JSON.stringify(event.data.source))
      if (drained >= 0) {
        pendingSteering.splice(drained, 1)
@@ -3165,7 +3172,7 @@ export function createTuiChat(
    renderEvent(event, { addHistory: false, renderChunks: true })
    requestRender()
  })
-  const disposeQueued = ctx.on('agent/queued', (subject, _content, info) => {
+  const disposeQueued = ctx.on('agent/inbox/enqueue', (subject, info) => {
    if (subject !== agent || !info.steering) return
    pendingSteering.push(JSON.stringify(info.source))
    refreshStatus()
--- a/packages/ui/tui/tests/harness.ts
+++ b/packages/ui/tui/tests/harness.ts
@@ -1,6 +1,7 @@
 import { Context } from 'cordis'
 import type { Terminal } from '@earendil-works/pi-tui'
 import AgentRegistry, {
+  AgentMessageId,
  type Agent,
  type AgentCancelCause,
  type AgentOptions,
@@ -171,15 +172,23 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
    steered,
    steeredOptions,
    cancelled,
-    send(content, options) {
+    followup(content, options) {
      sent.push(content)
      sentOptions.push(options)
+      return AgentMessageId('stub')
+    },
+    queue(content, options) {
+      sent.push(content)
+      sentOptions.push(options)
+      return AgentMessageId('stub')
    },
    steer(content, options) {
      steered.push(content)
      steeredOptions.push(options)
+      return AgentMessageId('stub')
    },
-    inject() {},
+    inject: () => AgentMessageId('stub'),
+    send: () => AgentMessageId('stub'),
    cancel(cause = { kind: 'user' }) {
      cancelled.push(cause)
    },
--- a/packages/ui/tui/tests/session-reference.snapshot.ts
+++ b/packages/ui/tui/tests/session-reference.snapshot.ts
@@ -128,7 +128,7 @@ describe('TUI session-reference snapshot', () => {
      type: 'text',
      text: '\n\n## My request:\n',
    })
-    expect(target.session.events.some(event => event.type === 'context/message')).toBe(false)
+    expect(target.session.events.some(event => event.type === 'user/message' && event.data.source.kind !== 'user')).toBe(false)

    const snapshot = await terminal.snapshot({ includeScrollback: true })
    if (REFRESHING) {
--- a/packages/ui/tui/tests/tui.snapshot.ts
+++ b/packages/ui/tui/tests/tui.snapshot.ts
@@ -474,7 +474,7 @@ describe('TUI terminal-state snapshots', () => {
        session.append('todo/write', {
          todos: [{ content: `Unsafe todo ${CONTROL_PROBE}`, status: 'in_progress' }],
        })
-        session.append('context/message', {
+        session.append('user/message', {
          content: [{ type: 'text', text: `Unsafe context ${CONTROL_PROBE}` }],
          source: { kind: 'plugin', plugin: `unsafe-${CONTROL_PROBE}` },
        }, { surfaceOp: 'append' })
@@ -590,7 +590,7 @@ describe('TUI terminal-state snapshots', () => {
    await checkpoint('surface-before-compaction', harness.terminal, { includeScrollback: true })

    await renderAfter(harness, () => {
-      harness.session.append('context/message', {
+      harness.session.append('user/message', {
        content: [{ type: 'text', text: 'Compacted summary: the prior command completed and its details were retired from the active surface.' }],
        source: { kind: 'plugin', plugin: 'compact' },
      }, {
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -4,7 +4,7 @@ import { join, resolve } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { CombinedAutocompleteProvider, type Terminal } from '@earendil-works/pi-tui'
-import AgentRegistry, { agentEvents, assembleContextFor, type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents, assembleContextFor, AgentMessageId, type Agent } from '@deepseek-ai/dsh-agent'
 import { type LlmCallConfig } from '@deepseek-ai/dsh-llm'
 import { GOAL_CHANGE_VERSION, GoalId, renderGoalChange, type GoalSnapshotChangeMeta } from '@deepseek-ai/dsh-goal'
 import CommandService, { type CommandInvocation } from '@deepseek-ai/dsh-commands'
@@ -1073,7 +1073,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
    }
    const result = await setup({
      beforeMount(session) {
-        session.append('context/message', {
+        session.append('user/message', {
          content: renderGoalChange(change),
          source: { kind: 'goal', goalId: change.goal.id, revision: change.goal.revision, round: 0 },
          meta: change as unknown as JsonValue,
@@ -1172,8 +1172,11 @@ describe('pi-tui chat lifecycle and transcript', () => {
    result.session.append('user/message', { content: [{ type: 'text', text: '   ' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
    result.session.append('steering/message', { turn: 2, content: [{ type: 'text', text: 'steering note' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
    result.session.append('steering/message', { turn: 2, content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    result.session.append('context/message', { content: [{ type: 'text', text: 'user context' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    result.session.append('context/message', { content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    result.session.append('user/message', { content: [{ type: 'text', text: 'user context' }], source: { kind: 'plugin', plugin: 'ctx' } }, { surfaceOp: 'append' })
+    result.session.append('user/message', { content: [{ type: 'text', text: '' }], source: { kind: 'plugin', plugin: 'ctx' } }, { surfaceOp: 'append' })
+    // A non-plugin injected source (goal) has no `plugin` field, so its context
+    // card label falls back to the source kind.
+    result.session.append('user/message', { content: [{ type: 'text', text: 'goal context' }], source: { kind: 'goal', goalId: 'g1', revision: 1, round: 0 } as never }, { surfaceOp: 'append' })
    result.session.append('prompt/blocked', { content: [{ type: 'text', text: 'blocked' }], source: { kind: 'user' }, reason: 'test policy' })
    appendAssistant(result.session, [])
    result.session.append('step/end', { turn: 1, step: 1 })
@@ -1254,6 +1257,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
    expect(result.terminal.output).toContain('Enter sends steering, Esc cancels')
    expect(result.terminal.output).toContain('Steering')
    expect(result.terminal.output).toContain('user context')
+    expect(result.terminal.output).toContain('Context · goal') // goal-sourced injected context labels by kind
    expect(result.terminal.output).toContain('Prompt blocked')
    expect(result.terminal.output).toContain('Turn cancelled')
    expect(result.terminal.progress).toContain(true)
@@ -1356,16 +1360,16 @@ describe('pi-tui chat lifecycle and transcript', () => {
    expect(result.terminal.output).not.toContain('queued')

    const queueSteering = (text: string): void => {
-      result.ctx.emit('agent/queued', result.agent, [{ type: 'text', text }], { source: { kind: 'user' }, contexts: [], steering: true })
+      result.ctx.emit('agent/inbox/enqueue', result.agent, { id: AgentMessageId('stub'), content: [{ type: 'text', text }], source: { kind: 'user' }, contexts: [], steering: true, wakeup: true })
    }
    const drainSteering = (text: string): void => {
      result.session.append('steering/message', { turn: 1, content: [{ type: 'text', text }], source: { kind: 'user' } }, { surfaceOp: 'append' })
    }

    // A steering queue for a different agent never touches this status line.
-    const other = { ...result.agent, id: SessionId('other') } as Agent
+    const other = { ...result.agent, id: SessionId('other') } as unknown as Agent
    result.terminal.output = ''
-    result.ctx.emit('agent/queued', other, [{ type: 'text', text: 'elsewhere' }], { source: { kind: 'user' }, contexts: [], steering: true })
+    result.ctx.emit('agent/inbox/enqueue', other, { id: AgentMessageId('stub'), content: [{ type: 'text', text: 'elsewhere' }], source: { kind: 'user' }, contexts: [], steering: true, wakeup: true })
    await tick()
    expect(result.terminal.output).not.toContain('queued')

@@ -1378,7 +1382,7 @@ describe('pi-tui chat lifecycle and transcript', () => {

    // A non-steering queue (an idle-style send) leaves the badge untouched.
    result.terminal.output = ''
-    result.ctx.emit('agent/queued', result.agent, [{ type: 'text', text: 'sent' }], { source: { kind: 'user' }, contexts: [], steering: false })
+    result.ctx.emit('agent/inbox/enqueue', result.agent, { id: AgentMessageId('stub'), content: [{ type: 'text', text: 'sent' }], source: { kind: 'user' }, contexts: [], steering: false, wakeup: true })
    drainSteering('first')
    await tick()
    expect(result.terminal.output).toContain('1 queued')
@@ -1398,8 +1402,9 @@ describe('pi-tui chat lifecycle and transcript', () => {
    await tick()
    expect(result.terminal.output).toContain('1 queued')

-    // A loop-authored steering event (plugin source, no matching agent/queued)
-    // cannot consume a pending user slot, even when it drains first.
+    // A steering/message whose source matches no pending badge entry (here a
+    // plugin source with no tracked enqueue) pops nothing, so it cannot consume
+    // a pending user slot even when it drains first.
    result.terminal.output = ''
    result.session.append('steering/message', {
      turn: 1,
@@ -1431,7 +1436,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
    const idle = await setup()
    // A steering queue arriving while idle has no status line to badge, so the
    // refresh is a no-op beyond requesting a render.
-    idle.ctx.emit('agent/queued', idle.agent, [{ type: 'text', text: 'early' }], { source: { kind: 'user' }, contexts: [], steering: true })
+    idle.ctx.emit('agent/inbox/enqueue', idle.agent, { id: AgentMessageId('stub'), content: [{ type: 'text', text: 'early' }], source: { kind: 'user' }, contexts: [], steering: true, wakeup: true })
    idle.session.append('tool/call', { turn: 1, step: 0, callId: 'pre' as never, name: 'bash', arguments: '{}' })
    await tick()
    expect(idle.terminal.output).not.toContain('Executing tools')
@@ -1878,7 +1883,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
    await mkdir(join(cwd, 'docs'), { recursive: true })
    await writeFile(join(cwd, 'src', 'source-file.ts'), 'export const source = true\n')
    await writeFile(join(cwd, 'docs', 'design notes.md'), '# Design\n')
-    await writeFile(join(cwd, 'unsafe\nfile.ts'), 'unsafe name\n')
+    await writeFile(join(cwd, 'unsafe\u007ffile.ts'), 'unsafe name\n')
    const result = await setup({
      cwd,
      tools: {
@@ -1915,10 +1920,11 @@ describe('pi-tui chat lifecycle and transcript', () => {
        expect(result.terminal.output).toContain('Folder · docs/')
      })
      result.terminal.send('\t')
-      await vi.waitFor(() => {
-        expect(result.terminal.output).toContain('File · design notes.md')
-      })
+      result.terminal.output = ''
      result.terminal.send('\t')
+      await vi.waitFor(() => {
+        expect(result.terminal.output).toContain('@"docs/design notes.md"')
+      })
      await tick()
      result.terminal.send('\r')
      await vi.waitFor(() => { expect(result.agent.sent).toHaveLength(2) })
@@ -2156,7 +2162,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
    expect(result.terminal.output).toContain('Referenced sessions · Steering source (steering-source)')
    expect(result.terminal.output).not.toContain('hidden non-reference prefix')

-    result.session.append('context/message', {
+    result.session.append('user/message', {
      content: [{ type: 'text', text: 'secret full snapshot payload' }],
      source: { kind: 'plugin', plugin: 'session-reference' },
      meta: {
@@ -2175,13 +2181,13 @@ describe('pi-tui chat lifecycle and transcript', () => {
      [{ kind: 'session-reference', references: [{}] }, 'invalid-fields'],
    ]
    for (const [meta, text] of invalidCards) {
-      result.session.append('context/message', {
+      result.session.append('user/message', {
        content: [{ type: 'text', text }],
        source: { kind: 'plugin', plugin: 'session-reference' },
        meta,
      }, { surfaceOp: 'append' })
    }
-    result.session.append('context/message', {
+    result.session.append('user/message', {
      content: [{ type: 'text', text: 'same-label snapshot' }],
      source: { kind: 'plugin', plugin: 'session-reference' },
      meta: { kind: 'session-reference', references: [{ sessionId: 'same', label: 'same' }] },
@@ -2615,7 +2621,7 @@ describe('pi-tui chat lifecycle and transcript', () => {

    const events = await setup()
    const unrelatedSession = events.ctx.sessions.create(SessionId('unrelated-session'))
-    const unrelatedAgent = { ...events.agent, id: unrelatedSession.id, session: unrelatedSession }
+    const unrelatedAgent = { ...events.agent, id: unrelatedSession.id, session: unrelatedSession } as unknown as Agent
    unrelatedSession.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    unrelatedSession.append('todo/write', { todos: [{ content: 'hidden', status: 'pending' }] })
    agentEvents(events.ctx, unrelatedAgent).emit('agent/status', 'running')
@@ -2978,7 +2984,7 @@ describe('tool cards and surface replay', () => {
      turn: 1, step: 1, callId: 'old-call' as never, content: [{ type: 'text', text: 'old output' }], isError: false,
    }, { surfaceOp: 'append' })
    const start = result.session.surface.nodes[0] as number
-    result.session.append('context/message', {
+    result.session.append('user/message', {
      content: [{ type: 'text', text: 'summary replacement' }],
      source: { kind: 'plugin', plugin: 'compact' },
    }, {
@@ -3299,7 +3305,7 @@ describe('terminal mounting', () => {
    const session = ctx.sessions.create(SessionId('main'))
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'idle', ctx,
-      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
    })
    const terminal = new FakeTerminal()
    mountTui(ctx, { color: false }, { terminal, exit: vi.fn() })
@@ -3323,7 +3329,7 @@ describe('terminal mounting', () => {
    const session = ctx.sessions.create(SessionId('main'))
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'idle', ctx,
-      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
    })
    const terminal = new FakeTerminal()
    // Mirror dsh-tui's own inject (minus loader, the absence under test).
@@ -3357,14 +3363,14 @@ describe('terminal mounting', () => {
    const otherSession = ctx.sessions.create(SessionId('other-session'))
    ctx.agents.register({
      id: otherSession.id, options: {}, session: otherSession, status: 'idle', ctx,
-      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
    })
    expect(terminal.started).toBe(0)

    const session = ctx.sessions.create(SessionId('late-session'))
    const agent = {
      id: session.id, options: {}, session, status: 'idle', ctx,
-      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
    } as Agent
    ctx.agents.register(agent)
    await tick()
@@ -3394,7 +3400,7 @@ describe('terminal mounting', () => {
    const session = ctx.sessions.create(SessionId('main-session'))
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'idle', ctx,
-      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
    })
    await tick()
    expect(terminal.started).toBe(0)
@@ -3436,7 +3442,7 @@ describe('terminal mounting', () => {
    session.append('step/start', { turn: 1, step: 1 })
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'running', ctx,
-      send() {}, steer() {}, inject() {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => AgentMessageId('stub'), queue: () => AgentMessageId('stub'), steer: () => AgentMessageId('stub'), inject: () => AgentMessageId('stub'), send: () => AgentMessageId('stub'), cancel() {}, whenIdle: () => Promise.resolve(),
    })
    const terminal = new FakeTerminal()
    terminal.start = () => { throw new Error('terminal startup failed') }