Merge remote-tracking branch 'origin/master' into codex/ask-user-question

# Conflicts:
#	packages/README.md
#	packages/ui/acp/README.md
#	pnpm-lock.yaml

packages/core/tools/README.md

@@ -8,7 +8,7 @@ Tool registry and execution waterfall. Tool plugins register their schemas and e
 
 - `ctx.tools.register(definition: ToolDefinition): () => void` Register a tool. Disposed with the calling fiber.
 - `ctx.tools.get(name: string): ToolDefinition | undefined`
-- `ctx.tools.schemas(): ToolSchema[]` Schemas of all registered tools (without the `execute` functions).
+- `ctx.tools.schemas(): ToolSchema[]` Schemas of all registered tools (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog/tools.md](../../../docs/tool-catalog/tools.md), generated by booting each tool plugin and harvesting this method (see [the tool-schema-catalog RFC](../../../docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md)).
 - `ctx.tools.execute(exec: ToolExecution): Promise<ToolExecutionResult>` Execute one tool call through the `tools/execute` waterfall.
 
 ### Injected services
@@ -72,7 +72,7 @@ See `defineTool`, `validateArgs`, `ToolArgsError`, `SchemaSpec`, `InferArgs`, an
 
 A tool owns how ITS calls render in a UI (an editor's tool-call card, a CLI log line) — a UI plugin must NOT special-case tool names. A `ToolDefinition` may declare two optional, pure, display-only methods:
 
-- `presentCall(args): ToolCallPresentation | undefined` — the PENDING state: a human-readable `title` (always-visible label), an optional `kind` (`read`/`edit`/`execute`/… for icon/treatment, default `other`), an optional `rawInput` (the salient input to show in a detail view — e.g. a shell command as a string, NOT the whole args object), an optional `content` (UI content shown alongside the title/card — e.g. a bash `description` as a text block above the terminal card), and an optional `terminal` (a neutral `{ cwd? }` asking a capable UI to render this call as a TERMINAL, e.g. for `bash`).
+- `presentCall(args): ToolCallPresentation | undefined` — the PENDING state: a human-readable `title` (always-visible label), an optional `kind` (`read`/`edit`/`execute`/… for icon/treatment, default `other`), an optional `rawInput` (the salient input to show in a detail view — e.g. a shell command as a string, NOT the whole args object), an optional `content` (UI content shown alongside the title/card — e.g. a bash `description` as a text block above the terminal card), an optional `locations` (`{ path, line? }[]` — the files this call reads/modifies, so a capable UI can follow along / jump to them; the ACP bridge forwards them as `tool_call.locations`), and an optional `terminal` (a neutral `{ cwd? }` asking a capable UI to render this call as a TERMINAL, e.g. for `bash`).
 - `presentResult(args, result): ToolResultPresentation | undefined` — the COMPLETED state, given the same `args` and the `{ content, isError }` result: an optional replacement `title`, reformatted `content` (e.g. wrap command output in a fenced ` ```console ` block — a UI-only affordance that must NOT appear in the model-facing `execute` result), and an optional `terminal` (the `{ output?, exitCode?, signal? }` for a terminal-rendered call). The `ToolTerminal` shape is provider-neutral; a UI bridge (the ACP bridge) maps it to a terminal card (with an exit-status pill) and a UI that can't ignores it and uses `content`.
 
 Returning `undefined` (or omitting a method) tells a UI to fall back to a generic presentation (title = tool name, raw args as input, raw result content). Both methods must be **pure and side-effect-free**: a UI may call them during live streaming AND during a session-log replay, so they depend only on their arguments. With `defineTool`, `args` is the typed `InferArgs<S>` shape; the helper soft-validates before calling (a malformed/older logged arg shape yields `undefined` rather than throwing, since display must never crash a replay). The shapes are provider-neutral — the ACP bridge (`dsh-acp`) maps them to ACP `tool_call`/`tool_call_update` wire fields, and `dsh-tool-bash` is the reference implementation.

packages/core/tools/src/index.ts

@@ -109,6 +109,16 @@ export interface ToolCallPresentation {
    * {@link terminal} block (if any) as a terminal card.
    */
   content?: ContentBlock[]
+  /**
+   * Files this call reads or modifies, so a capable UI can "follow along" —
+   * highlight or jump to the file (and line) as the tool runs. Provider-neutral
+   * `{ path, line? }` pairs; a UI bridge maps them to its own affordance (the ACP
+   * bridge forwards them as `tool_call.locations`). `path` is what the tool
+   * operated on (the model-facing path); `line` is an optional 1-based line to
+   * focus (e.g. a read's offset). Omit for a call that touches no file (e.g.
+   * `bash`).
+   */
+  locations?: { path: string; line?: number }[]
   /**
    * Ask a capable UI to render this call as a TERMINAL (a command running in a
    * working directory), not a generic tool card — set by a tool whose call IS a

packages/core/tools/tests/gen-tool-catalog.spec.ts

@@ -0,0 +1,117 @@
+/**
+ * Guarantee tests for the tool-schema catalog generator
+ * (`scripts/gen-tool-catalog.ts`).
+ *
+ * The generated catalog is frozen by a regenerate-and-diff freshness gate, so
+ * the freshness half is exercised by `pnpm run verify-tool-catalog` in CI. What
+ * a freshness diff CANNOT prove is (a) that BOOTING the tool plugins yields the
+ * shipped schema — the whole reason this generator boots instead of parsing
+ * source (a runtime-spread enum resolves to its literal members) — and (b) that
+ * the completeness guard REJECTS a tool package missing from the boot manifest,
+ * the property that replaces the AST pass's "nothing silently omitted". These
+ * tests drive the exported `collectToolCatalog` / `assertManifestComplete` /
+ * `render` directly, mirroring the negative-path style of the cordis-catalog
+ * generator tests.
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  assertManifestComplete,
+  collectToolCatalog,
+  render,
+  type ToolCatalog,
+} from '../../../../scripts/gen-tool-catalog.ts'
+
+/** JSON Schema shape enough to reach the values AST extraction can't. */
+interface JsonSchema {
+  type: string
+  properties?: Record<string, JsonSchema>
+  items?: JsonSchema
+  enum?: string[]
+  required?: string[]
+}
+
+describe('gen-tool-catalog collectToolCatalog', () => {
+  it('boots every shipped tool package and harvests its model-facing schemas', async () => {
+    const catalog = await collectToolCatalog()
+    const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort()
+    expect(names).toEqual(['ask_user_question', 'bash', 'bash_kill', 'bash_output', 'edit', 'read', 'subagent', 'todo_write', 'write'])
+    // Every tool carries a JSON-Schema `parameters` object (what the model sees).
+    for (const entry of catalog) {
+      for (const schema of entry.schemas) {
+        expect((schema.parameters as unknown as JsonSchema).type).toBe('object')
+      }
+    }
+  })
+
+  it('resolves a runtime-spread enum to its literal members (the payoff over AST)', async () => {
+    const catalog = await collectToolCatalog()
+    const todo = catalog
+      .flatMap(entry => entry.schemas)
+      .find(s => s.name === 'todo_write')
+    // `todo-todo` writes `enum: [...STATUSES]` — a source AST would see the
+    // spread, not the values. Booting yields the shipped enum literals.
+    const status = (((todo?.parameters as unknown as JsonSchema).properties?.todos)?.items)?.properties?.status
+    expect(status?.enum).toEqual(['pending', 'in_progress', 'completed'])
+  })
+
+  it('attributes each package with a source pointer that names its index', async () => {
+    const catalog = await collectToolCatalog()
+    const bash = catalog.find(entry => entry.pkg === '@deepseek-ai/dsh-tool-bash')
+    expect(bash?.source).toBe('packages/bash/tool-bash/src/index.ts')
+  })
+
+  it('records the shipped `subagent_fork` alias in a note (config-driven tool name)', async () => {
+    // `tool-subagent`'s registered name is the load-time `toolName` config, so
+    // the shipped agents surface this one package as both `subagent` and
+    // `subagent_fork`. Booting yields only the default name; the note is how a
+    // reader learns the fork alias the model also sees. Without it the catalog
+    // would silently under-report the shipped tool surface.
+    const catalog = await collectToolCatalog()
+    const subagent = catalog.find(entry => entry.pkg === '@deepseek-ai/dsh-tool-subagent')
+    expect(subagent?.schemas.map(s => s.name)).toEqual(['subagent'])
+    expect(subagent?.note).toMatch(/subagent_fork/)
+  })
+})
+
+describe('gen-tool-catalog assertManifestComplete', () => {
+  it('passes when the manifest lists every on-disk tool package (the default)', () => {
+    expect(() => { assertManifestComplete() }).not.toThrow()
+  })
+
+  it('throws, naming the omitted package, when a tool package is missing from the manifest', () => {
+    // An empty manifest scanned against the real tree: every `tool-*` package
+    // is unlisted, so the guard must fire and name them.
+    expect(() => { assertManifestComplete([]) }).toThrow(/not in the boot manifest/)
+    expect(() => { assertManifestComplete([]) }).toThrow(/tool-bash/)
+  })
+})
+
+describe('gen-tool-catalog render', () => {
+  it('emits a package heading, a tool heading, and a json schema fence', () => {
+    const catalog: ToolCatalog = [
+      {
+        pkg: '@deepseek-ai/dsh-tool-demo',
+        source: 'packages/demo/tool-demo/src/index.ts',
+        schemas: [{ name: 'demo', description: 'A demo tool.', parameters: { type: 'object', properties: {} } }],
+      },
+    ]
+    const md = render(catalog)
+    expect(md).toContain('## `@deepseek-ai/dsh-tool-demo`')
+    expect(md).toContain('### `demo`')
+    expect(md).toContain('A demo tool.')
+    expect(md).toContain('```json')
+    expect(md).toContain('Source: [`packages/demo/tool-demo/src/index.ts`]')
+  })
+
+  it('renders the strict flag when a schema sets it', () => {
+    const catalog: ToolCatalog = [
+      {
+        pkg: '@deepseek-ai/dsh-tool-demo',
+        source: 'packages/demo/tool-demo/src/index.ts',
+        schemas: [{ name: 'demo', description: '', parameters: { type: 'object', properties: {} }, strict: true }],
+      },
+    ]
+    expect(render(catalog)).toContain('Strict: `true`')
+  })
+})