Merge remote-tracking branch 'origin/master' into feat/ripgrep-packaged-binary

scripts/doc-budgets.manifest.json

@@ -1,7 +1,7 @@
 {
   "AGENTS.md": 1775,
   "docs/AGENTS.md": 1150,
-  "docs/architecture.md": 1920,
+  "docs/architecture.md": 2160,
   "docs/cordis-primer.md": 600,
   "docs/defensive-patterns.md": 550,
   "docs/testing.md": 1100,

scripts/gen-cordis-catalog.ts

@@ -160,7 +160,18 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   SkillSummary: 'skills.md',
   SaveTextSpill: 'spill.md',
   SpillRef: 'spill.md',
+  ContinuableCreateRequest: 'subagent.md',
+  ContinuableCreateSpec: 'subagent.md',
+  ContinuableSetupContribution: 'subagent.md',
+  ContinuableStart: 'subagent.md',
+  ContinuableStartSpec: 'subagent.md',
+  CoordinatorMessageSource: 'subagent.md',
+  SubagentFollowupOptions: 'subagent.md',
+  SubagentListEntry: 'subagent.md',
   SubagentProvider: 'subagent.md',
+  SubagentReportDelivery: 'subagent.md',
+  SubagentReportMessageSource: 'subagent.md',
+  SubagentReportOptions: 'subagent.md',
   SubagentRun: 'subagent.md',
   SubagentService: 'subagent.md',
   SubagentStartRequest: 'subagent.md',
@@ -278,8 +289,8 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
   ResumeAgentOptions: 'agent resume contract is owned by packages/core/agent/README.md',
   SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
-  SubagentRunEndInfo: 'event-local snapshot is owned by packages/subagent/subagent/src/index.ts',
-  SubagentRunInfo: 'event-local snapshot is owned by packages/subagent/subagent/src/index.ts',
+  SubagentRunEndInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
+  SubagentRunInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
   TelemetryRecord: 'seam-local record contract is owned by packages/telemetry/session-telemetry/src/index.ts',
   WorkflowAgentEndInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',

scripts/gen-doc-graphs.ts

@@ -424,11 +424,11 @@ const SERVICE_ROLES: ServiceRole[] = [
   {
     key: 'subagents',
     pkg: 'subagent',
-    title: 'Subagent provider registry',
+    title: 'Subagent provider and continuation service',
     mode: 'seam',
     implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp'],
-    consumers: ['tool-subagent', 'tool-ralph'],
-    note: 'Providers implement transports; tool-subagent exposes configured delegation while tool-ralph requires one fresh structured-output route.',
+    consumers: ['tool-subagent', 'tool-subagent-control', 'tool-ralph'],
+    note: 'Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route.',
   },
   {
     key: 'tasks',

scripts/gen-tool-catalog.ts

@@ -11,7 +11,9 @@ import { basename, resolve } from 'node:path'
 import { Context } from 'cordis'
 import type { ToolSchema } from '@deepseek-ai/dsh-llm'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
-import SessionStore from '@deepseek-ai/dsh-session'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { createScope } from '@deepseek-ai/dsh-scope'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
 import GoalService from '@deepseek-ai/dsh-goal'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
@@ -26,6 +28,9 @@ import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa'
 import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import type { SubagentProvider } from '@deepseek-ai/dsh-subagent'
+import * as ToolSubagentControl from '@deepseek-ai/dsh-tool-subagent-control'
+import * as ToolSubagentListAgents from '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+import * as ToolSubagentReport from '@deepseek-ai/dsh-tool-subagent-report'
 import SkillService from '@deepseek-ai/dsh-skill'
 import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
 import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
@@ -66,10 +71,32 @@ function registerCatalogSubagentProvider(ctx: Context, name: string): void {
     capabilities: { outputSchema: true, depthLimit: true, toolFilter: true, persona: true },
     inheritsParentContext: false,
     start: () => Promise.reject(new Error('tool-catalog provider cannot start a child')),
+    // Declared so consumers configured for continuable background mode mount.
+    prepareContinuable: () => Promise.reject(new Error('tool-catalog provider cannot prepare a child')),
   }
   ctx.subagents.registerProvider(provider)
 }
 
+/** Minted child-scope keys for packages whose tools are never global. */
+const catalogChildScopes = new WeakMap<Context, Agent>()
+
+/**
+ * Install one scope-local tool package into an agent-like child scope for
+ * schema harvest, without starting a model, Agent loop, or persistence backend.
+ * @param ctx - catalog context owning the scope.
+ * @param mountScoped - package installer for the scoped context.
+ */
+async function mountCatalogChildScope(
+  ctx: Context,
+  mountScoped: (childCtx: Context) => void,
+): Promise<void> {
+  const key = { id: SessionId('tool-catalog-child') } as Agent
+  await ctx.plugin(Object.assign((inner: Context) => {
+    mountScoped(createScope(inner, key).ctx)
+  }, { inject: ['tools', 'systemPrompt', 'subagents'] }))
+  catalogChildScopes.set(ctx, key)
+}
+
 /**
  * Tool package plus its hand-maintained boot recipe. The caller mounts the
  * prompt and registry; each recipe supplies only package-specific seams and
@@ -80,8 +107,12 @@ interface ToolPackage {
   pkg: string
   /** The `packages/<group>/<dir>` leaf name — matched by the completeness guard. */
   dir: string
-  /** Repo-relative source path linked from the catalog entry. */
-  source: string
+  /**
+   * Repo-relative implementation source linked per harvested tool. Packages
+   * whose tools share one plugin may use a string; split plugins map each tool
+   * name to its own source.
+   */
+  source: string | Readonly<Record<string, string>>
   /** Services or owning runtime surfaces the package requires at execution time. */
   requires: string[]
   /** Session events or other visible state the tools write or affect. */
@@ -91,6 +122,8 @@ interface ToolPackage {
   /** Plug the injected seams + the tool plugin onto a context that already
    * carries `systemPrompt` + `tools`. */
   mount: (ctx: Context) => Promise<void>
+  /** Agent-like scope key whose tool view is catalogued instead of the global view. */
+  scope?: (ctx: Context) => Agent
   /**
    * Config for the caller's `ToolRegistry` mount. The registry itself ships a
    * model-facing tool (`run_code`, registered under a non-native `mode`), so
@@ -339,6 +372,46 @@ const TOOL_PACKAGES: ToolPackage[] = [
     note:
       'The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `apps/cli/config/base.cordis.yml` and `examples/acp-agent/cordis.yml`.',
   },
+  {
+    pkg: '@deepseek-ai/dsh-tool-subagent-control',
+    dir: 'tool-subagent-control',
+    source: {
+      list_agents: 'packages/subagent/tool-subagent-control/src/list-agents.ts',
+      send_message: 'packages/subagent/tool-subagent-control/src/index.ts',
+    },
+    requires: ['ctx.tools', 'ctx.subagents', 'ctx.sessionQuery (list_agents only)'],
+    writes: ['tool/call', 'tool/result', 'child session events through ctx.subagents'],
+    async mount(ctx) {
+      await ctx.plugin(SubagentService)
+      await ctx.plugin(LocalTaskService)
+      await ctx.plugin(AgentRegistry)
+      await ctx.plugin(SessionStore)
+      await ctx.plugin(SessionQuerySqlite, { path: ':memory:' })
+      await ctx.plugin(ToolSubagentControl)
+      await ctx.plugin(ToolSubagentListAgents)
+    },
+    note:
+      'The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (which additionally requires session query).',
+  },
+  {
+    pkg: '@deepseek-ai/dsh-tool-subagent-report',
+    dir: 'tool-subagent-report',
+    source: 'packages/subagent/tool-subagent-report/src/index.ts',
+    requires: ['ctx.subagents', 'a live continuable in-process child Agent'],
+    writes: ['tool/call', 'tool/result', 'a user-role message in the direct parent session'],
+    async mount(ctx) {
+      await ctx.plugin(AgentRegistry)
+      await ctx.plugin(SubagentService)
+      await mountCatalogChildScope(ctx, (childCtx) => {
+        ToolSubagentReport.installReportTool(childCtx, ctx, 'quiet')
+      })
+    },
+    scope: ctx => catalogChildScopes.get(ctx) as Agent,
+    note:
+      'Registered per continuable in-process child rather than globally, so this schema is visible only '
+      + 'inside such a child and survives its global `toolFilter`. The parent-facing `send_message` tool '
+      + 'is installed independently.',
+  },
   {
     pkg: '@deepseek-ai/dsh-tool-tasks',
     dir: 'tool-tasks',
@@ -402,7 +475,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
 /** One package's contribution to the catalog: its schemas plus attribution. */
 interface CatalogPackage {
   pkg: string
-  source: string
+  sources: Readonly<Record<string, string>>
   requires: string[]
   writes: string[]
   shippedNames?: string[]
@@ -454,10 +527,13 @@ export async function collectToolCatalog(packages: ToolPackage[] = TOOL_PACKAGES
       await ctx.plugin(SystemPrompt)
       await ctx.plugin(ToolRegistry, entry.toolsConfig ?? {})
       await entry.mount(ctx)
-      const schemas = ctx.tools.schemas().sort((a, b) => a.name.localeCompare(b.name))
+      const schemas = ctx.tools.schemas(entry.scope?.(ctx)).sort((a, b) => a.name.localeCompare(b.name))
       catalog.push({
         pkg: entry.pkg,
-        source: entry.source,
+        sources: Object.fromEntries(schemas.map(schema => [
+          schema.name,
+          toolSource(entry, schema.name),
+        ])),
         requires: entry.requires,
         writes: entry.writes,
         schemas,
@@ -471,6 +547,18 @@ export async function collectToolCatalog(packages: ToolPackage[] = TOOL_PACKAGES
   return catalog
 }
 
+/** Resolve one harvested tool to the plugin source that registered it. */
+function toolSource(entry: ToolPackage, toolName: string): string {
+  if (typeof entry.source === 'string') return entry.source
+  const source = entry.source[toolName]
+  if (source === undefined) {
+    throw new Error(
+      `gen-tool-catalog: ${entry.pkg} has no source mapping for harvested tool ${toolName}`,
+    )
+  }
+  return source
+}
+
 /** Render one tool's entry: name, description, JSON-Schema parameters, source. */
 function renderTool(schema: ToolSchema, source: string): string[] {
   const out = [`### \`${schema.name}\``, '']
@@ -513,7 +601,11 @@ export function render(catalog: ToolCatalog): string {
   ]
   for (const entry of catalog) {
     lines.push(`## \`${entry.pkg}\``, '')
-    for (const schema of entry.schemas) lines.push(...renderTool(schema, entry.source))
+    for (const schema of entry.schemas) {
+      // Collection validated that every harvested schema has a source.
+      const source = entry.sources[schema.name] as string
+      lines.push(...renderTool(schema, source))
+    }
     if (entry.note) lines.push(entry.note, '')
   }
   return lines.join('\n')

scripts/type-equiv.manifest.json

@@ -1094,6 +1094,51 @@
       "symbol": "SubagentStartRequest",
       "source": "packages/subagent/subagent/src/types.ts"
     },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "ResolvedSubagentStartRequest",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "CoordinatorMessageSource",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentReportMessageSource",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentReportDelivery",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentReportOptions",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentFollowupOptions",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "ContinuableStart",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "ContinuableCreateRequest",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "ContinuableCreateSpec",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
     {
       "doc": "docs/core-data-structures/subagent.md",
       "symbol": "SubagentResult",