Merge remote-tracking branch 'origin/master' into session-query-tool

# Conflicts:
#	docs/architecture.i18n.yaml

scripts/gen-cordis-api.ts

@@ -30,8 +30,45 @@ function quote(value: string): string {
 }
 
 /**
- * Collect exported interface and type shapes; omit names declared in multiple
- * packages rather than risk serving the wrong package's shape.
+ * Reduce an exported class to its type shape: drop method/constructor bodies
+ * and property initializers so the catalog serves member signatures, not
+ * implementation.
+ */
+function classShape(node: ts.ClassDeclaration): ts.ClassDeclaration {
+  const isNonPublic = (member: ts.ClassElement): boolean =>
+    (ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined)?.some(m =>
+      m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword) ?? false
+  const members = node.members.flatMap((member): ts.ClassElement[] => {
+    if (isNonPublic(member) || (ts.isPropertyDeclaration(member) && ts.isPrivateIdentifier(member.name))) return []
+    if (ts.isMethodDeclaration(member)) {
+      return [ts.factory.updateMethodDeclaration(
+        member, member.modifiers, member.asteriskToken, member.name, member.questionToken,
+        member.typeParameters, member.parameters, member.type, undefined)]
+    }
+    if (ts.isConstructorDeclaration(member)) {
+      return [ts.factory.updateConstructorDeclaration(member, member.modifiers, member.parameters, undefined)]
+    }
+    if (ts.isGetAccessorDeclaration(member)) {
+      return [ts.factory.updateGetAccessorDeclaration(
+        member, member.modifiers, member.name, member.parameters, member.type, undefined)]
+    }
+    if (ts.isSetAccessorDeclaration(member)) {
+      return [ts.factory.updateSetAccessorDeclaration(
+        member, member.modifiers, member.name, member.parameters, undefined)]
+    }
+    if (ts.isPropertyDeclaration(member)) {
+      return [ts.factory.updatePropertyDeclaration(
+        member, member.modifiers, member.name, member.questionToken ?? member.exclamationToken, member.type, undefined)]
+    }
+    return [member]
+  })
+  return ts.factory.updateClassDeclaration(
+    node, node.modifiers, node.name, node.typeParameters, node.heritageClauses, members)
+}
+
+/**
+ * Collect exported interface, type-alias, and body-stripped class shapes; omit
+ * names declared in multiple packages rather than serve the wrong shape.
  */
 function collectTypeDecls(scanRoot: string = root): Map<string, string> {
   const printer = ts.createPrinter({ removeComments: true })
@@ -41,14 +78,16 @@ function collectTypeDecls(scanRoot: string = root): Map<string, string> {
     const abs = resolve(scanRoot, rel)
     const sf = ts.createSourceFile(abs, readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true)
     for (const stmt of sf.statements) {
-      if (!ts.isInterfaceDeclaration(stmt) && !ts.isTypeAliasDeclaration(stmt)) continue
+      const named = ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt) || ts.isClassDeclaration(stmt)
+      if (!named || stmt.name === undefined) continue
       if (!(stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)) continue
       const name = stmt.name.text
       if (decls.has(name)) {
         ambiguous.add(name)
         continue
       }
-      const printed = printer.printNode(ts.EmitHint.Unspecified, stmt, sf).replace(/\r/g, '')
+      const emit = ts.isClassDeclaration(stmt) ? classShape(stmt) : stmt
+      const printed = printer.printNode(ts.EmitHint.Unspecified, emit, sf).replace(/\r/g, '')
       decls.set(name, printed.length > MAX_DECL_CHARS
         ? `${printed.slice(0, MAX_DECL_CHARS)} /* …truncated — full shape in source */`
         : printed)

scripts/gen-cordis-catalog.ts

@@ -35,6 +35,8 @@ export const LINK_MAP: Record<string, string> = {
   ContinuationDecision: 'core.md',
   ContinuationStop: 'core.md',
   GenerateOptions: 'core.md',
+  AgentMessage: 'core.md',
+  AgentMessageId: 'core.md',
   HookContext: 'core.md',
   LlmCallConfig: 'core.md',
   LlmModelContext: 'core.md',

scripts/gen-doc-graphs.ts

@@ -918,8 +918,8 @@ function renderLifecycle(): string {
     '  participant Session',
     '  participant Persistence',
     '  participant SDK as UI or SDK listener',
-    '  User->>Agent: send(content)',
-    `  Agent-->>SDK: ${mermaidCode('agent/queued')}`,
+    '  User->>Agent: followup(content)',
+    `  Agent-->>SDK: ${mermaidCode('agent/inbox/enqueue')}`,
     '  Agent->>Driver: queued work wakes driver',
     `  Driver-->>SDK: ${mermaidCode('agent/status')} running`,
     `  Driver->>Session: ${mermaidCode('turn/start')}`,
@@ -998,7 +998,7 @@ function renderToolPipeline(): string {
     '  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]',
     '  finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]',
     `  final["${mermaidCode('tools/result')} synchronous notification<br/>frozen authoritative outcome"]`,
-    '  context["Active-batch additionalContexts FIFO<br/>context/message after recorded tool results"]',
+    '  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]',
     `  toolResult["Session event: ${mermaidCode('tool/result')}<br/>single model-facing outcome"]`,
     '  allResults["Tool batch settled<br/>recorded tool/result events complete"]',
     '  presentResult["UI completed card<br/>presentResult(args, result)"]',

scripts/gen-tool-catalog.ts

@@ -266,7 +266,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     dir: 'tool-goal',
     source: 'packages/goal/tool-goal/src/index.ts',
     requires: ['ctx.tools', 'ctx.agents', 'ctx.goals', 'ctx.systemPrompt', 'a calling Agent in an authorized open turn'],
-    writes: ['tool/call', 'context/message goal snapshot for mutations', 'tool/result'],
+    writes: ['tool/call', 'user/message goal snapshot for mutations', 'tool/result'],
     async mount(ctx) {
       await ctx.plugin(AgentRegistry)
       await ctx.plugin(GoalService)
@@ -353,7 +353,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     dir: 'tool-tasks',
     source: 'packages/tasks/tool-tasks/src/index.ts',
     requires: ['ctx.tools', 'ctx.tasks', 'ctx.systemPrompt'],
-    writes: ['tool/call', 'tool/result', 'context/message via agent.inject() for background completion notices'],
+    writes: ['tool/call', 'tool/result', 'user/message via agent.inject() for background completion notices'],
     async mount(ctx) {
       await ctx.plugin(TaskService)
       await ctx.plugin(ToolTasks)

scripts/type-equiv.manifest.json

@@ -73,12 +73,32 @@
     },
     {
       "doc": "docs/core-data-structures/core.md",
-      "symbol": "AgentCancelCause",
+      "symbol": "InjectOptions",
       "source": "packages/core/agent/src/types.ts"
     },
     {
       "doc": "docs/core-data-structures/core.md",
-      "symbol": "InjectOptions",
+      "symbol": "ResolvedAgentInput",
+      "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.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.md",
+      "symbol": "AgentCancelCause",
       "source": "packages/core/agent/src/types.ts"
     },
     {