refactor(agent-loop): simplify message machine

2026-07-30 13:49:57 +08:00
parent d554ae3019
commit f2e20c1ef0
212 changed files with 1326 additions and 2382 deletions
--- a/packages/ui/tui/src/components/dialogs.ts
+++ b/packages/ui/tui/src/components/dialogs.ts
@@ -460,7 +460,6 @@ function resumeTurnLabel(snapshot: SessionLogSnapshot): string {
    case 'completed': return `turn ${event.data.turn}: completed`
    case 'aborted': return `turn ${event.data.turn}: cancelled`
    case 'error': return `turn ${event.data.turn}: error`
-    case 'disposed': return `turn ${event.data.turn}: disposed`
    case 'max-tokens': return `turn ${event.data.turn}: max tokens`
    case 'interrupted': return `turn ${event.data.turn}: interrupted`
    default: return `turn ${event.data.turn}: unknown result`
--- a/packages/ui/tui/src/index.ts
+++ b/packages/ui/tui/src/index.ts
@@ -5,20 +5,7 @@
 * @module @deepseek-ai/dsh-tui
 */

-import {
-  CombinedAutocompleteProvider,
-  Container,
-  Key,
-  Spacer,
-  Text,
-  TUI,
-  ProcessTerminal,
-  matchesKey,
-  visibleWidth,
-  type EditorTheme,
-  type SlashCommand,
-  type TerminalColorScheme,
-} from '@earendil-works/pi-tui'
+import { CombinedAutocompleteProvider, Container, Key, Spacer, Text, TUI, ProcessTerminal, matchesKey, visibleWidth, type EditorTheme, type SlashCommand, type TerminalColorScheme } from '@earendil-works/pi-tui'
 import { Service, type Context, type Fiber } from 'cordis'
 import {
  assembleContextFor,
@@ -343,6 +330,7 @@ export function createTuiChat(
  const pendingSteering = new Set<MessageId>()
  let disposed = false
  let shuttingDown: Promise<void> | undefined
+  let exitAfterIdle = false
  // Optional: skills mount conditionally, so read the global service store
  // rather than declaring an injection that would make the TUI require them.
  const skills = ctx.get('skills')
@@ -786,9 +774,15 @@ export function createTuiChat(
          case 'completed':
            break
          case 'error': {
-            const key = `${event.data.turn}:${reason.step}`
-            const message = 'failure' in reason ? reason.failure.message : reason.message
-            if (!liveErrors.delete(key)) appendNotice(message, 'error')
+            const prefix = `${event.data.turn}:`
+            let alreadyReported = false
+            for (const key of liveErrors) {
+              if (!key.startsWith(prefix)) continue
+              liveErrors.delete(key)
+              alreadyReported = true
+            }
+            const message = reason.error instanceof Error ? reason.error.message : String(reason.error)
+            if (!alreadyReported) appendNotice(message, 'error')
            break
          }
          case 'aborted':
@@ -797,9 +791,6 @@ export function createTuiChat(
          case 'max-tokens':
            appendNotice('The model reached its output-token limit.', 'warning')
            break
-          case 'disposed':
-            appendNotice('Turn stopped: the agent was disposed.', 'warning')
-            break
          case 'interrupted':
            appendNotice('The previous process ended during this turn.', 'warning')
            break
@@ -892,9 +883,9 @@ export function createTuiChat(

  const requestExit = (): void => {
    if (agent.status === 'running') {
+      exitAfterIdle = true
      agent.cancel({ kind: 'user' })
      appendNotice('Cancelling the active turn before exit…', 'warning')
-      void agent.whenIdle().then(() => shutdown(true))
      return
    }
    void shutdown(true)
@@ -1190,67 +1181,14 @@ export function createTuiChat(
      appendNotice(`Agent "${agent.id}" is disposed.`, 'error')
      return
    }
-    if (agent.acceptsNextStep) {
-      // Steering is never subject to prompt admission; an attached snapshot
-      // drains beside it at the same step boundary through the outbox.
-      if (attachedContext !== undefined) {
-        agent.inject(attachedContext)
-      }
-      const message = createUserMessage({ content, source: { kind: 'user' } })
-      agent.steer(message)
-      pendingSteering.add(message.id)
-      refreshStatus()
-      return
-    }
-    if (attachedContext === undefined) {
-      agent.followup(createUserMessage({ content, source: { kind: 'user' } }))
-      return
-    }
-    // Idle: the snapshot rides the prompt's admission transaction so a
-    // blocking hook discards both together.
-    let cleanedUp = false
-    const message: UserMessage = createUserMessage({ content, source: { kind: 'user' } })
-    const acceptedId = message.id
-    const discarded = new Set<MessageId>()
-    const cleanup = (): void => {
-      // Every completion path detaches both listeners. Keep this
-      // idempotent so later cleanup paths cannot double-release them.
-      /* v8 ignore next -- unreachable idempotence guard, see above */
-      if (cleanedUp) return
-      cleanedUp = true
-      detachSubmit()
-      detachDiscard()
-    }
-    // Prepended so this wrapper is outermost: it observes the exact accepted
-    // message identity whether a downstream hook allows or blocks, then detaches.
-    const detachSubmit = ctx.on('agent/prompt-submit', async (subject, submitted, _signal, next) => {
-      if (subject !== agent || submitted.id !== message.id) return next()
-      cleanup()
-      const decision = await next()
-      if (decision.kind !== 'allow') return decision
-      return { ...decision, additionalContexts: [...decision.additionalContexts ?? [], attachedContext] }
-    }, { prepend: true })
-    // Installed before followup(): an enqueue listener can synchronously
-    // cancel and discard before followup() returns its id.
-    const detachDiscard = ctx.on('agent/inbox/discard', (subject, messages) => {
-      if (subject !== agent) return
-      for (const message of messages) discarded.add(message.id)
-      if (discarded.has(acceptedId)) cleanup()
-    })
-    // followup() accepts any typed input and contains listener failures;
-    // this guards a future synchronous throw so the wrapper cannot leak.
-    /* v8 ignore start -- future-proofing guard, see above */
-    try {
-      agent.followup(message)
-      if (discarded.has(acceptedId)) cleanup()
-    } catch (error: unknown) {
-      cleanup()
-      throw error
-    }
-    /* v8 ignore stop */
+    if (attachedContext !== undefined) agent.inject(attachedContext)
+    const message = createUserMessage({ content, source: { kind: 'user' } })
+    agent.steer(message)
+    pendingSteering.add(message.id)
+    refreshStatus()
  }

-  /** Deliver a user turn to the agent: steer while running, send while idle, or report a disposed agent. */
+  /** Deliver user input to the nearest step, or report a disposed agent. */
  const deliver = (payload: string): void => {
    dispatchMessage([{ type: 'text', text: payload }])
  }
@@ -1448,14 +1386,11 @@ export function createTuiChat(
  const settlePendingSteering = (id: MessageId): void => {
    if (pendingSteering.delete(id)) refreshStatus()
  }
-  const disposeDequeued = ctx.on('agent/inbox/dequeue', (subject, message) => {
+  const disposeDequeued = ctx.on('agent/inbox/admitted', (subject, message) => {
    if (subject === agent) settlePendingSteering(message.id)
  })
-  const disposeDiscarded = ctx.on('agent/inbox/discard', (subject, messages) => {
-    if (subject !== agent) return
-    let changed = false
-    for (const message of messages) changed = pendingSteering.delete(message.id) || changed
-    if (changed) refreshStatus()
+  const disposeDiscarded = ctx.on('agent/inbox/canceled', (subject, message) => {
+    if (subject === agent && pendingSteering.delete(message.id)) refreshStatus()
  })
  const disposeStatus = ctx.on('agent/status', (subject, status) => {
    if (subject !== agent) return
@@ -1464,6 +1399,10 @@ export function createTuiChat(
    // the queue without logging drains, cannot strand a stale count).
    if (status !== 'running') pendingSteering.clear()
    setStatus(status)
+    if (status === 'idle' && exitAfterIdle) {
+      exitAfterIdle = false
+      void shutdown(true)
+    }
  })
  const disposeError = ctx.on('agent/error', (subject, turn, step, error) => {
    if (subject !== agent) return
--- a/packages/ui/tui/tests/harness.ts
+++ b/packages/ui/tui/tests/harness.ts
@@ -6,7 +6,6 @@ import AgentRegistry, {
  type AgentCancelCause,
  type AgentOptions,
  type AgentStatus,
-  type SendOptions,
 } from '@deepseek-ai/dsh-agent'
 import type {
  ContentBlock,
@@ -27,7 +26,6 @@ interface FakeAgent extends Agent {
  status: AgentStatus
  sent: ContentBlock[][]
  sentMessages: UserMessage[]
-  sentOptions: (SendOptions | undefined)[]
  steered: ContentBlock[][]
  steeredIds: MessageId[]
  steeredOptions: UserMessage[]
@@ -178,7 +176,6 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
  if (options.omitInitialLifecycle !== true) {
    session.append('turn/start', {
      turn: 1,
-      trigger: { kind: 'message', source: { kind: 'user' } },
    })
    session.append('step/start', { turn: 1, step: 1 })
  }
@@ -187,7 +184,6 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
  const sentMessages: UserMessage[] = []
  const steered: ContentBlock[][] = []
  const steeredIds: MessageId[] = []
-  const sentOptions: (SendOptions | undefined)[] = []
  const steeredOptions: UserMessage[] = []
  const injected: ContentBlock[][] = []
  const injectedOptions: UserMessage[] = []
@@ -203,23 +199,15 @@ export async function createTuiTestHarness<TerminalType extends Terminal, Exit e
    ctx,
    sent,
    sentMessages,
-    sentOptions,
    steered,
    steeredIds,
    steeredOptions,
    injected,
    injectedOptions,
    cancelled,
-    send(input, options) {
-      sent.push(input.content)
-      sentMessages.push(input)
-      sentOptions.push(options)
-      return input.id
-    },
    followup(input) {
      sent.push(input.content)
      sentMessages.push(input)
-      sentOptions.push(undefined)
      return input.id
    },
    steer(input) {
--- a/packages/ui/tui/tests/tui.snapshot.ts
+++ b/packages/ui/tui/tests/tui.snapshot.ts
@@ -322,7 +322,6 @@ describe('TUI terminal-state snapshots', () => {
        session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
        session.append('turn/start', {
          turn: 2,
-          trigger: { kind: 'message', source: { kind: 'user' } },
        })
        appendUser(session, 'Next question.')
      },
@@ -774,14 +773,14 @@ describe('TUI terminal-state snapshots', () => {
        turn: 1,
        reason: { kind: 'error', step: 1, message: 'provider stream failed after partial output' },
      })
-      harness.session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
+      harness.session.append('turn/start', { turn: 2 })
      harness.session.append('turn/end', {
        turn: 2,
        reason: { kind: 'interrupted' },
      })
-      harness.session.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } })
+      harness.session.append('turn/start', { turn: 3 })
      harness.session.append('turn/end', { turn: 3, reason: { kind: 'disposed' } })
-      harness.session.append('turn/start', { turn: 4, trigger: { kind: 'message', source: { kind: 'user' } } })
+      harness.session.append('turn/start', { turn: 4 })
      // A merge-extensible turn-end kind unknown to the TUI still surfaces its
      // name so the agent never stops without a visible reason.
      harness.session.append('turn/end', { turn: 4, reason: { kind: 'plugin-policy' } as never })
@@ -822,7 +821,7 @@ describe('TUI terminal-state snapshots', () => {
    const log = (meta: typeof earlier, title: string, day: string): { meta: typeof earlier; events: SessionEvent[] } => ({
      meta,
      events: [
-        { type: 'turn/start', seq: 0, time: Date.parse(`${day}T00:00:01Z`), data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+        { type: 'turn/start', seq: 0, time: Date.parse(`${day}T00:00:01Z`), data: { turn: 1 } },
        { type: 'user/message', seq: 1, time: Date.parse(`${day}T00:00:02Z`), data: createUserMessage({ content: [{ type: 'text', text: 'restore the selector' }], source: { kind: 'user' } }), surfaceOp: 'append' },
        { type: 'step/start', seq: 2, time: Date.parse(`${day}T00:00:03Z`), data: { turn: 1, step: 1 } },
        { type: 'request/header', seq: 3, time: Date.parse(`${day}T00:00:04Z`), data: { header: { config: { provider: 'deepseek', model: 'deepseek-v4-pro' } }, reason: 'initial' } },
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -239,7 +239,7 @@ describe('goodbye message and /resume', () => {
    time = 100,
    reason: TurnEndReason = { kind: 'completed' },
  ): SessionEvent[] => [
-    { type: 'turn/start', seq: 0, time, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+    { type: 'turn/start', seq: 0, time, data: { turn: 1 } },
    { type: 'user/message', seq: 1, time: time + 1, data: createUserMessage({
      content: [{ type: 'text', text: 'resume me' }], source: { kind: 'user' },
    }), surfaceOp: 'append' },
@@ -1333,9 +1333,9 @@ describe('pi-tui chat lifecycle and transcript', () => {
    appendAssistant(result.session, [])
    result.session.append('step/end', { turn: 1, step: 1 })
    result.session.append('turn/end', { turn: 1, reason: { kind: 'aborted' } })
-    result.session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
+    result.session.append('turn/start', { turn: 2 })
    result.session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
-    result.session.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } })
+    result.session.append('turn/start', { turn: 3 })
    result.session.append('step/start', { turn: 3, step: 1 })
    result.session.append('assistant/chunk', {
      turn: 3,
@@ -1872,7 +1872,7 @@ describe('pi-tui chat lifecycle and transcript', () => {
      expect(result.terminal.output).not.toContain('│')
      expect(result.terminal.output).not.toContain('Response 1s')

-      result.session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
+      result.session.append('turn/start', { turn: 2 })
      result.session.append('step/start', { turn: 2, step: 1 })
      clock += 1_000
      result.terminal.output = ''
@@ -3760,7 +3760,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 }
-    unrelatedSession.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    unrelatedSession.append('turn/start', { turn: 1 })
    unrelatedSession.append('todo/write', { todos: [{ content: 'hidden', status: 'pending' }] })
    agentEvents(events.ctx, unrelatedAgent).emit('agent/status', 'running')
    agentEvents(events.ctx, unrelatedAgent).emit('agent/error', 1, 1, new Error('hidden error'))
@@ -3768,22 +3768,22 @@ describe('pi-tui chat lifecycle and transcript', () => {
    agentEvents(events.ctx, events.agent).emit('agent/error', 1, 1, new Error('live failure'))
    events.session.append('step/end', { turn: 1, step: 1 })
    events.session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, message: 'live failure' } })
-    events.session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
+    events.session.append('turn/start', { turn: 2 })
    events.session.append('turn/end', { turn: 2, reason: { kind: 'error', step: 1, message: 'durable failure' } })
-    events.session.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } })
+    events.session.append('turn/start', { turn: 3 })
    events.session.append('turn/end', { turn: 3, reason: { kind: 'aborted' } })
-    events.session.append('turn/start', { turn: 4, trigger: { kind: 'message', source: { kind: 'user' } } })
+    events.session.append('turn/start', { turn: 4 })
    events.session.append('turn/end', { turn: 4, reason: { kind: 'max-tokens' } })
-    events.session.append('turn/start', { turn: 5, trigger: { kind: 'message', source: { kind: 'user' } } })
+    events.session.append('turn/start', { turn: 5 })
    events.session.append('turn/end', { turn: 5, reason: { kind: 'interrupted' } })
-    events.session.append('turn/start', { turn: 6, trigger: { kind: 'message', source: { kind: 'user' } } })
+    events.session.append('turn/start', { turn: 6 })
    events.session.append('turn/end', {
      turn: 6,
      reason: { kind: 'error', step: 1, failure: { message: 'structured provider failure', code: 'SERVER' } },
    })
-    events.session.append('turn/start', { turn: 8, trigger: { kind: 'message', source: { kind: 'user' } } })
+    events.session.append('turn/start', { turn: 8 })
    events.session.append('turn/end', { turn: 8, reason: { kind: 'disposed' } })
-    events.session.append('turn/start', { turn: 9, trigger: { kind: 'message', source: { kind: 'user' } } })
+    events.session.append('turn/start', { turn: 9 })
    // Merge-extensible reason kind unknown to the TUI still names the stop.
    events.session.append('turn/end', { turn: 9, reason: { kind: 'plugin-policy' } as never })
    agentEvents(events.ctx, events.agent).emit('agent/disposed')
@@ -4715,7 +4715,7 @@ describe('terminal mounting', () => {
    const session = ctx.sessions.create(SessionId('main'))
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
    })
    const terminal = new FakeTerminal()
    mountTui(ctx, { theme: { color: false } }, { terminal, exit: vi.fn() })
@@ -4740,7 +4740,7 @@ describe('terminal mounting', () => {
    const session = ctx.sessions.create(SessionId('main'))
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
    })
    const terminal = new FakeTerminal()
    // Mirror dsh-tui's own inject (minus loader, the absence under test).
@@ -4775,14 +4775,14 @@ describe('terminal mounting', () => {
    const otherSession = ctx.sessions.create(SessionId('other-session'))
    ctx.agents.register({
      id: otherSession.id, options: {}, session: otherSession, status: 'idle', acceptsNextStep: false, ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => {}, steer: () => {}, inject: () => {}, 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', acceptsNextStep: false, ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
    } as Agent
    ctx.agents.register(agent)
    await tick()
@@ -4813,7 +4813,7 @@ describe('terminal mounting', () => {
    const session = ctx.sessions.create(SessionId('main-session'))
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'idle', acceptsNextStep: false, ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
    })
    await tick()
    expect(terminal.started).toBe(0)
@@ -4853,11 +4853,11 @@ describe('terminal mounting', () => {
    await ctx.plugin(TuiPromptService)
    ctx.provide('tools', { get: () => undefined } as never)
    const session = ctx.sessions.create(SessionId('failed-start-session'))
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('turn/start', { turn: 1 })
    session.append('step/start', { turn: 1, step: 1 })
    ctx.agents.register({
      id: session.id, options: {}, session, status: 'running', acceptsNextStep: true, ctx,
-      followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
+      followup: () => {}, steer: () => {}, inject: () => {}, cancel() {}, whenIdle: () => Promise.resolve(),
    })
    const terminal = new FakeTerminal()
    terminal.start = () => { throw new Error('terminal startup failed') }