refactor(agent-loop): simplify observable state machine

scripts/gen-cordis-catalog.ts

@@ -48,7 +48,6 @@ export const LINK_MAP: Record<string, string> = {
   MessageSource: 'core.md',
   PromptDecision: 'core.md',
   RequestError: 'core.md',
-  RequestErrorDecision: 'core.md',
   PreparedReferencedMessage: 'session-reference.md',
   SessionReferenceCandidate: 'session-reference.md',
   SessionReferenceInput: 'session-reference.md',

scripts/gen-doc-graphs.ts

@@ -646,22 +646,31 @@ class EventRelationCollector {
   /** Walk one package source file and classify event API calls by receiver type. */
   private visitSource(source: PackageSource): void {
     const visit = (node: ts.Node): void => {
-      if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
-        const receiverKind = this.receiverKind(node.expression.expression)
-        const method = node.expression.name.text
-        if (receiverKind === 'events-service' && method === 'dispatch') {
-          const argumentList = node.arguments[1]
-          if (argumentList) {
-            for (const event of this.eventNamesFromArgumentList(argumentList, new Set())) {
-              this.addDispatcher(event, source.pkg, 'events.dispatch')
+      if (ts.isCallExpression(node)) {
+        if (this.isAgentEventEmitter(node.expression)) {
+          const event = node.arguments[2]
+          if (event) {
+            for (const name of this.finiteStringValues(event) ?? []) {
+              this.addDispatcher(name, source.pkg, 'emitAgentEvent')
             }
           }
-        } else if (receiverKind === 'context' || receiverKind === 'agent-dispatch') {
-          const eventNames = this.eventNamesFromCall(node, receiverKind)
-          if (method === 'on' || method === 'once') {
-            for (const event of eventNames) this.ensure(event).listeners.add(source.pkg)
-          } else if (method === 'emit' || method === 'parallel' || method === 'serial' || method === 'waterfall') {
-            for (const event of eventNames) this.addDispatcher(event, source.pkg, method)
+        } else if (ts.isPropertyAccessExpression(node.expression)) {
+          const receiverKind = this.receiverKind(node.expression.expression)
+          const method = node.expression.name.text
+          if (receiverKind === 'events-service' && method === 'dispatch') {
+            const argumentList = node.arguments[1]
+            if (argumentList) {
+              for (const event of this.eventNamesFromArgumentList(argumentList, new Set())) {
+                this.addDispatcher(event, source.pkg, 'events.dispatch')
+              }
+            }
+          } else if (receiverKind === 'context' || receiverKind === 'agent-dispatch') {
+            const eventNames = this.eventNamesFromCall(node, receiverKind)
+            if (method === 'on' || method === 'once') {
+              for (const event of eventNames) this.ensure(event).listeners.add(source.pkg)
+            } else if (method === 'emit' || method === 'parallel' || method === 'serial' || method === 'waterfall') {
+              for (const event of eventNames) this.addDispatcher(event, source.pkg, method)
+            }
           }
         }
       }
@@ -670,6 +679,22 @@ class EventRelationCollector {
     visit(source.sourceFile)
   }
 
+  /** Match the exported contained-notification helper by declaration identity. */
+  private isAgentEventEmitter(expression: ts.Expression): boolean {
+    if (!ts.isIdentifier(expression)) return false
+    const local = this.project.checker.getSymbolAtLocation(expression)
+    if (!local) return false
+    const symbol = local.flags & ts.SymbolFlags.Alias
+      ? this.project.checker.getAliasedSymbol(local)
+      : local
+    const declarations = symbol.declarations ?? []
+    return declarations.some((declaration) => {
+      return ts.isFunctionDeclaration(declaration)
+        && declaration.name?.text === 'emitAgentEvent'
+        && this.project.relativePath(declaration.getSourceFile()) === 'packages/core/agent/src/dispatch.ts'
+    })
+  }
+
   /** Classify a receiver using assignability to the repository's actual event API types. */
   private receiverKind(receiver: ts.Expression): EventReceiverKind | undefined {
     const type = this.project.checker.getTypeAtLocation(receiver)
@@ -916,7 +941,6 @@ function renderLifecycle(): string {
     '  participant LLM as ctx.llm',
     '  participant Tools as ctx.tools',
     '  participant Session',
-    '  participant Persistence',
     '  participant SDK as UI or SDK listener',
     '  User->>Agent: followup(content)',
     `  Agent-->>SDK: ${mermaidCode('agent/inbox/enqueue')}`,
@@ -927,7 +951,7 @@ function renderLifecycle(): string {
     '  Hooks-->>Driver: authoritative allow, block, or add context',
     `  Driver->>Session: ${mermaidCode('user/message')} or rejected ${mermaidCode('turn/end')}`,
     `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
-    `  Driver-->>Driver: ${mermaidCode('agent/pre-step')} serial checkpoint`,
+    `  Driver-->>Driver: ${mermaidCode('agent/step')} serial checkpoint`,
     `  Driver->>Session: ${mermaidCode('step/start')}`,
     `  Driver->>LLM: ${mermaidCode('agent/request')} waterfall, then ${mermaidCode('llm/stream')} waterfall`,
     '  LLM-->>Driver: StreamChunk*',
@@ -936,9 +960,8 @@ function renderLifecycle(): string {
     '  alt final adapter or terminal in-band request failure',
     `    Driver->>Session: ${mermaidCode('step/end')}`,
     `    Driver->>Hooks: ${mermaidCode('agent/request-error')} waterfall`,
-    '    Hooks-->>Driver: retry in a new step or preserve the original error',
+    '    Hooks-->>Driver: call agent.retry() or preserve the original error',
     '  else model request succeeded',
-    `  Driver->>Hooks: ${mermaidCode('agent/step-result')} waterfall`,
     `  Driver->>Session: ${mermaidCode('assistant/message')}`,
     '  Driver->>Tools: classify pending call by executionMode',
     '  loop barriers and bounded rolling pool, reclassify before start',
@@ -953,19 +976,16 @@ function renderLifecycle(): string {
     '    end',
     '  end',
     '  Driver->>Session: post-tool context and steering (no prompt-submit)',
-    `  Driver->>Hooks: ${mermaidCode('agent/post-step')} serial checkpoint`,
     `  Driver->>Session: ${mermaidCode('step/end')}`,
-    `  Driver->>Hooks: ${mermaidCode('agent/turn-continuation')} waterfall`,
-    `  Driver->>Hooks: ${mermaidCode('agent/turn-stop')} serial terminal checkpoint`,
+    `  Driver->>Hooks: ${mermaidCode('agent/stopping')} serial terminal checkpoint`,
     '  end',
     `  Driver->>Session: ${mermaidCode('turn/end')}`,
-    `  Driver->>Persistence: ${mermaidCode('session/flush')} parallel checkpoint`,
     `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
     '```',
     '',
     'The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.',
     '',
-    '`dsh-compact-basic` uses `agent/post-step` for pressure after those durable facts and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and a fresh retry step, and returns retry only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
+    '`dsh-compact-basic` uses `agent/step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
     '',
     'The returned `agent/prompt-submit` allow is authoritative; listeners wrapping `next()` preserve downstream content and additional contexts unless replacement is intentional. Steering bypasses that waterfall and joins at its durable checkpoint.',
     '',

scripts/type-equiv.manifest.json

@@ -6,119 +6,229 @@
       "symbol": "Branded",
       "source": "packages/util/brand/src/index.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "Branded",
+      "source": "packages/util/brand/src/index.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "ContentBlockMap",
       "source": "packages/llm/llm/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "ContentBlockMap",
+      "source": "packages/llm/llm/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "AssistantProvenance",
       "source": "packages/llm/llm/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "AssistantProvenance",
+      "source": "packages/llm/llm/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "Message",
       "source": "packages/llm/llm/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "Message",
+      "source": "packages/llm/llm/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "MessageSourceMap",
       "source": "packages/llm/llm/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "MessageSourceMap",
+      "source": "packages/llm/llm/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "FinishReasonMap",
       "source": "packages/llm/llm/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "FinishReasonMap",
+      "source": "packages/llm/llm/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "LlmProviderInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "LlmProviderInfo",
+      "source": "packages/llm/llm/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "LlmModelInfo",
       "source": "packages/llm/llm/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "LlmModelInfo",
+      "source": "packages/llm/llm/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "LlmModelContext",
       "source": "packages/llm/llm/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "LlmModelContext",
+      "source": "packages/llm/llm/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "GenerateOptions",
       "source": "packages/llm/llm/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "GenerateOptions",
+      "source": "packages/llm/llm/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "ToolSchema",
       "source": "packages/llm/llm/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "ToolSchema",
+      "source": "packages/llm/llm/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "LlmCallConfig",
       "source": "packages/llm/llm/src/call-config.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "LlmCallConfig",
+      "source": "packages/llm/llm/src/call-config.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "SessionEvent",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "SessionEvent",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "SendTarget",
       "source": "packages/core/agent/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "SendTarget",
+      "source": "packages/core/agent/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "SendOptions",
       "source": "packages/core/agent/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "SendOptions",
+      "source": "packages/core/agent/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "AliasSendOptions",
       "source": "packages/core/agent/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "AliasSendOptions",
+      "source": "packages/core/agent/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "AgentMessageId",
       "source": "packages/core/agent/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "AgentMessageId",
+      "source": "packages/core/agent/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "AgentMessage",
       "source": "packages/core/agent/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "AgentMessage",
+      "source": "packages/core/agent/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "CancelOptions",
       "source": "packages/core/agent/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "CancelOptions",
+      "source": "packages/core/agent/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "AgentCancelCause",
       "source": "packages/core/agent/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "AgentCancelCause",
+      "source": "packages/core/agent/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "Agent",
       "source": "packages/core/agent/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "Agent",
+      "source": "packages/core/agent/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "AdditionalContext",
       "source": "packages/core/agent/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "AdditionalContext",
+      "source": "packages/core/agent/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/core.md",
       "symbol": "PromptDecision",
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
-      "symbol": "ContinuationDecision",
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "PromptDecision",
       "source": "packages/core/agent/src/types.ts"
     },
     {
@@ -127,17 +237,17 @@
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
-      "symbol": "RequestErrorDecision",
+      "doc": "docs/core-data-structures/core.zh.md",
+      "symbol": "RequestError",
       "source": "packages/core/agent/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/core.md",
-      "symbol": "ContinuationStop",
+      "symbol": "SessionStartSource",
       "source": "packages/core/agent/src/types.ts"
     },
     {
-      "doc": "docs/core-data-structures/core.md",
+      "doc": "docs/core-data-structures/core.zh.md",
       "symbol": "SessionStartSource",
       "source": "packages/core/agent/src/types.ts"
     },
@@ -313,77 +423,153 @@
       "symbol": "UserMessageData",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "UserMessageData",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "SessionEventMap",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SessionEventMap",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "OutOfBandSessionEventMap",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "OutOfBandSessionEventMap",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "EpochHeader",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "EpochHeader",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "TodoItem",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "TodoItem",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "SessionEvent",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SessionEvent",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "TurnTriggerMap",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "TurnTriggerMap",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "TurnEndReasonMap",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "TurnEndReasonMap",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "SurfaceEventType",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SurfaceEventType",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "SurfaceOp",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SurfaceOp",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "SurfaceIntent",
       "source": "packages/core/session/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SurfaceIntent",
+      "source": "packages/core/session/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "SessionSurface",
       "source": "packages/core/session/src/surface.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SessionSurface",
+      "source": "packages/core/session/src/surface.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "SurfaceFoldReplacement",
       "source": "packages/core/session/src/surface.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SurfaceFoldReplacement",
+      "source": "packages/core/session/src/surface.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "SurfaceFoldResult",
       "source": "packages/core/session/src/surface.ts"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "SurfaceFoldResult",
+      "source": "packages/core/session/src/surface.ts"
+    },
     {
       "doc": "docs/core-data-structures/session.md",
       "symbol": "Session",
       "source": "packages/core/session/src/index.ts",
       "projection": "public-api"
     },
+    {
+      "doc": "docs/core-data-structures/session.zh.md",
+      "symbol": "Session",
+      "source": "packages/core/session/src/index.ts",
+      "projection": "public-api"
+    },
     {
       "doc": "docs/core-data-structures/persistence.md",
       "symbol": "SessionHeader",