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

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

packages/ui/acp/README.md

@@ -28,7 +28,7 @@ It is a **client-driver / UI plugin**, the structured analogue of the readline `
 | `session/load` | `ctx.agents.resume(...)` | replays the persisted event log to the client as `session/update` — the USER side (`user/message` → `user_message_chunk`), assistant text/reasoning (`assistant/chunk`), and tool calls/results (`tool/call` + `tool/result`). Re-loading an already-live id is rejected; the id's load slot is reserved (`loadingIds`) BEFORE the async resume so a pipelined load of the SAME id can't leak a second agent (distinct ids load concurrently). The resumed session keeps its PERSISTED header `cwd`, so its bash tools run in the original workspace; the requested `cwd` must be absolute and match the persisted `cwd`. After the async resume a `closed` re-check refuses to install a record if the bridge tore down mid-load |
 | `session/prompt` | `agent.send()` | supports ACP `text` and `resource_link` blocks; rejects image/audio/embedded resource and empty prompts; one in-flight prompt PER session (independent); settles on the OWNING turn's end (a turn that ends in `error` rejects the RPC) |
 | `session/cancel` | `agent.cancel()` | the queue-aware cancel: aborts a running step, clears queued + steering work, and drops a turn about to start, then settles the prompt `cancelled` — for ONLY that session (a cancel never touches another session's stream or prompt) |
-| `session/update` | `session/event` | `agent_message_chunk` (text-delta), `agent_thought_chunk` (reasoning-delta), `user_message_chunk` (load replay), `tool_call`/`tool_call_update` (title/kind/rawInput/content owned by the TOOL via `presentCall`/`presentResult` — see Tool-call presentation) |
+| `session/update` | `session/event` | `agent_message_chunk` (text-delta), `agent_thought_chunk` (reasoning-delta), `user_message_chunk` (load replay), `tool_call`/`tool_call_update` (title/kind/rawInput/content/locations owned by the TOOL via `presentCall`/`presentResult` — see Tool-call presentation) |
 | `elicitation/create` | `ctx.userInteraction` provider | `ask_user_question` pauses the tool call and asks the ACP client for a session-scoped form; choices use a `choice` single-select field, free-form answers use `answer`/`custom_answer`, and cancel/decline returns a structured `UserInteractionError` |
 
 ## Multi-session
@@ -43,7 +43,7 @@ Each session runs in its own workspace, recorded as the session's `SessionHeader
 
 ## Tool-call presentation
 
-How a tool call renders in the editor is owned by the TOOL, not the bridge — the bridge never special-cases tool names. Each tool may declare `presentCall(args)` (pending state: a human-readable `title`, a `kind` for the icon, the salient `rawInput` to show in a detail view, and optional `content` blocks shown alongside) and `presentResult(args, result)` (completed state: an optional replacement `title` and reformatted `content`) on its `dsh-tools` definition. The bridge looks the definition up by name in `ctx.tools` and maps the neutral `ToolCallPresentation`/`ToolResultPresentation` to the ACP `tool_call`/`tool_call_update` wire shapes. A tool that declares neither gets a generic fallback (title = tool name, raw parsed args as `rawInput`, kind inferred from the name). For example `dsh-tool-bash` sets the title to the exact `command` ("ls -la src"), `kind: 'execute'`, the `command` as `rawInput`, the model `description` as a `content` text block, and wraps the completed output in a fenced ` ```console ` block. (The command is the title because an editor hides `rawInput` for execute-kind cards — Zed renders it only for non-terminal tools — and the reference adapters likewise use the command as an execute tool's title.)
+How a tool call renders in the editor is owned by the TOOL, not the bridge — the bridge never special-cases tool names. Each tool may declare `presentCall(args)` (pending state: a human-readable `title`, a `kind` for the icon, the salient `rawInput` to show in a detail view, optional `content` blocks shown alongside, and optional `locations` — `{ path, line? }[]` files the call reads/modifies, forwarded as `tool_call.locations` so an editor can follow along) and `presentResult(args, result)` (completed state: an optional replacement `title` and reformatted `content`) on its `dsh-tools` definition. The bridge looks the definition up by name in `ctx.tools` and maps the neutral `ToolCallPresentation`/`ToolResultPresentation` to the ACP `tool_call`/`tool_call_update` wire shapes. A tool that declares neither gets a generic fallback (title = tool name, raw parsed args as `rawInput`, kind inferred from the name). For example `dsh-tool-bash` sets the title to the exact `command` ("ls -la src"), `kind: 'execute'`, the `command` as `rawInput`, the model `description` as a `content` text block, and wraps the completed output in a fenced ` ```console ` block; the `dsh-tool-fs` `read`/`write`/`edit` tools set a `Read/Write/Edit <path>` title, a `read`/`edit` kind, and a `locations` entry for the file. (The command is the title because an editor hides `rawInput` for execute-kind cards — Zed renders it only for non-terminal tools — and the reference adapters likewise use the command as an execute tool's title.)
 
 The `tool/result` session event carries only `{ callId, content, isError }` — not the tool name or args — so to call a tool's `presentResult` the bridge keeps a small per-session map from `callId` to the in-flight call's `(name, args)`, populated on `tool/call` and removed as each result is presented (it holds only currently-in-flight calls, never finished ones). This is bridge-local state — NOT a change to the event schema or a core service. The map lives on the `SessionRecord`, so two concurrent sessions never cross their in-flight tool state; a `session/load` replay uses a throwaway presenter that pairs each `tool/call` with its `tool/result` as the log replays in order, so replayed tool cards render identically to live ones.
 

packages/ui/acp/acp-feature-support.md

@@ -101,7 +101,7 @@ Tool-call presentation is **owned by each tool** (`presentCall` / `presentResult
 | `content` blocks | S | ✅ | ✅ | ✅ | Text content; the description renders above the card. |
 | `diff` content | S | ❌ | ✅ | ✅ | No structured diff rendering for edits (would need a diffing edit tool + presenter). |
 | `terminal` content | S | ✅ | ✅ | ✅ | Via the Zed `_meta` terminal convention (see below), not the spec `terminal/*` sub-protocol. |
-| `locations` (follow-along) | S | ❌ | ✅ | ✅ | No file-location hints emitted. |
+| `locations` (follow-along) | S | ✅ | ✅ | ✅ | The `read`/`write`/`edit` tools emit `{ path, line? }` file-location hints via `presentCall`. |
 | `rawInput` | S | ✅ | ⚠️ | ✅ | Parsed tool args surfaced as `rawInput`. |
 | `rawOutput` | S | ❌ | ⚠️ | ✅ | Not emitted. |
 
@@ -147,7 +147,7 @@ Ranked by how commonly the reference adapters ship them and how much UX they unl
 5. **Slash commands** (`available_commands_update`).
 6. **MCP passthrough** (`mcpServers` on `session/new` + `mcpCapabilities`).
 7. **Richer prompt content** — image / embedded `resource` blocks (needs a multimodal model path).
-8. **Diff + location tool rendering** — `diff` content and `locations` for edit tools.
+8. **Diff tool rendering** — structured `diff` content for edit tools (the `locations` follow-along hint already ships on `read`/`write`/`edit`).
 9. **Usage reporting** (`usage_update`) — the harness already records token usage internally (on `assistant/message`).
 10. **Editor filesystem delegation** (`fs/read_text_file` / `fs/write_text_file`) — lets the agent see unsaved buffers; lower priority since the harness has direct disk access.
 

packages/ui/acp/package.json

@@ -39,12 +39,15 @@
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-bash-local": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
+    "@deepseek-ai/dsh-fs-policy": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs": "workspace:^",
     "@deepseek-ai/dsh-tool-todo": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-tool-ask-user": "workspace:^",

packages/ui/acp/src/index.ts

@@ -990,6 +990,7 @@ export function streamSessionEventUpdate(
           kind: present.kind,
           status: 'in_progress',
           ...present.rawInput !== undefined ? { rawInput: present.rawInput } : {},
+          ...present.locations !== undefined ? { locations: present.locations } : {},
           ...callContent.length > 0 ? { content: callContent } : {},
           ...asTerminal
             ? { _meta: { terminal_info: { terminal_id: event.data.callId, cwd: terminalCwd(present.terminal, terminal.cwd) } } }
@@ -1080,6 +1081,8 @@ interface ResolvedCallPresentation {
   rawInput?: unknown
   /** UI content shown on the pending call (e.g. a bash description text block above the card). */
   content?: ContentBlock[]
+  /** Files this call reads/modifies (mapped to ACP `tool_call.locations`), for editor follow-along. */
+  locations?: { path: string; line?: number }[]
   /** Tool's request to render as a terminal (the pending side carries the cwd). */
   terminal?: ToolTerminal
 }
@@ -1159,6 +1162,7 @@ export class ToolPresenter {
       kind: present.kind ?? 'other',
       rawInput: present.rawInput,
       ...present.content !== undefined ? { content: present.content } : {},
+      ...present.locations !== undefined ? { locations: present.locations } : {},
       ...present.terminal !== undefined ? { terminal: present.terminal } : {},
     }
   }

packages/ui/acp/tests/harness.ts

@@ -19,7 +19,10 @@ import AgentRegistry from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
+import * as FsPolicy from '@deepseek-ai/dsh-fs-policy'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
+import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
 import {
   ClientSideConnection,
@@ -175,6 +178,15 @@ export async function makeBridgeHarness(options: {
    * tool + the bridge's own todo/write→plan mapping, not a stand-in.
    */
   withTodo?: boolean
+  /**
+   * Plug the REAL filesystem stack (`dsh-fs-local` + `dsh-fs-policy` +
+   * `dsh-tool-fs`) so a test can drive `read`/`write`/`edit` through the bridge
+   * and assert their tool-owned presentation (title/kind/`locations`) on the
+   * wire — the shipping tools, not a stand-in. `fsCwd` sets the local backend's
+   * base directory (default: `storageDir`).
+   */
+  withFs?: boolean
+  fsCwd?: string
 } = { storageDir: '' }): Promise<BridgeHarness> {
   const adapter = new MockAdapter(options.script ?? [])
 
@@ -197,6 +209,11 @@ export async function makeBridgeHarness(options: {
   if (options.withTodo) {
     await ctx.plugin(ToolTodo)
   }
+  if (options.withFs) {
+    await ctx.plugin(LocalFileSystem, { cwd: options.fsCwd ?? options.storageDir })
+    await ctx.plugin(FsPolicy)
+    await ctx.plugin(ToolFs)
+  }
   ctx.llm.registerAdapter(['mock'], adapter)
 
   // Two identity byte pipes cross-wired into the two ndJsonStreams: bytes the

packages/ui/acp/tests/stream-update.spec.ts

@@ -1,8 +1,13 @@
 import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
 import type { SessionNotification } from '@agentclientprotocol/sdk'
-import type { ToolDefinition, ToolRegistry } from '@deepseek-ai/dsh-tools'
+import type { ToolDefinition, ToolRegistry as ToolRegistryType } from '@deepseek-ai/dsh-tools'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import FsLocal from '@deepseek-ai/dsh-fs-local'
+import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import { streamSessionEventUpdate, agentOptions, todosToPlan, ToolPresenter } from '../src/index.ts'
 
 /** Collect the updates a single event produces (no presenter → generic fallback). */
@@ -20,7 +25,7 @@ function liveUpdatesFor(event: SessionEvent): SessionNotification['update'][] {
 }
 
 /** A tiny tool registry stub exposing just `get` for {@link ToolPresenter}. */
-function registryOf(...tools: ToolDefinition[]): Pick<ToolRegistry, 'get'> {
+function registryOf(...tools: ToolDefinition[]): Pick<ToolRegistryType, 'get'> {
   const map = new Map(tools.map(t => [t.name, t]))
   return { get: name => map.get(name) }
 }
@@ -330,6 +335,38 @@ describe('ToolPresenter (tool-owned presentation via the tool registry)', () =>
     expect(updates[0]).toMatchObject({ sessionUpdate: 'tool_call', title: 'boom' })
     expect(updates[1]).toMatchObject({ sessionUpdate: 'tool_call_update', content: [{ type: 'content', content: { type: 'text', text: 'raw' } }] })
   })
+
+  it('forwards a tool-owned `locations` onto the wire tool_call (REAL fs read/edit tools)', async () => {
+    // Use the SHIPPING fs tools (not a stand-in), booted through their real
+    // plugins, so the wire tool_call carries the actual presentCall output —
+    // including `locations` for editor follow-along. (AGENTS.md "prefer the real
+    // implementation over a mock".)
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(FsLocal)
+    await ctx.plugin(ToolFs)
+    const presenter = new ToolPresenter(ctx.tools)
+
+    const [readCall] = updatesWith(presenter, evt('tool/call', {
+      turn: 1, step: 1, callId: CallId('r1'), name: 'read',
+      arguments: JSON.stringify({ file_path: 'src/a.ts', offset: 12 }),
+    }))
+    expect(readCall).toMatchObject({
+      sessionUpdate: 'tool_call', toolCallId: 'r1', title: 'Read src/a.ts', kind: 'read',
+      rawInput: 'offset 12', locations: [{ path: 'src/a.ts', line: 12 }],
+    })
+
+    const [editCall] = updatesWith(presenter, evt('tool/call', {
+      turn: 1, step: 1, callId: CallId('e1'), name: 'edit',
+      arguments: JSON.stringify({ file_path: 'src/b.ts', old_string: 'x', new_string: 'y' }),
+    }))
+    expect(editCall).toMatchObject({
+      sessionUpdate: 'tool_call', toolCallId: 'e1', title: 'Edit src/b.ts', kind: 'edit',
+      locations: [{ path: 'src/b.ts' }],
+    })
+    await ctx.fiber.dispose()
+  })
 })
 
 describe('terminal-card mapping (capability-gated)', () => {