docs: tighten prose audit after master retarget

packages/ui/acp/src/codec.ts

@@ -36,13 +36,8 @@ export function turnEndToStopReason(reason: TurnEndReason): StopReason {
 }
 
 /**
- * Translate a harness {@link ContentBlock} from a prompt into ACP content for
- * replay, or `undefined` for block kinds the bridge does not surface to the
- * client as message content. Today only `text` maps; `resource_link` is an
- * ACP prompt-only input rendered into text by {@link acpPromptToText};
- * `reasoning` is surfaced via `agent_thought_chunk`
- * streaming rather than as a message block, and `tool-call`/`tool-result`
- * are handled by the tool-call update path.
+ * Map replayable text to ACP message content. Other block kinds use their
+ * prompt, thought-stream, or tool-update paths.
  * @param block - the harness content block to translate.
  * @returns the ACP block, or `undefined` for a kind with no message-content mapping.
  */

packages/ui/acp/src/index.ts

@@ -1,37 +1,7 @@
 /**
- * The Agent Client Protocol (ACP) bridge: a client-driver / UI plugin that
- * exposes the harness agent as an ACP server over JSON-RPC stdio, so editors
- * (Zed and other ACP clients) can drive it. The structured analogue of the
- * readline `stdio-chat` plugin.
- *
- * This is NOT a loop change and NOT an ADR-0009 capability seam: it consumes
- * the existing `agent/*` event taxonomy, the `dsh-agent` create/resume factory,
- * and `dsh-session-persistence` (for `session/load`). It maps:
- *
- * - `initialize`     → protocol-version negotiation, text-only capabilities
- * - `session/new`    → `ctx.agents.create({ sessionId, meta:{cwd} })`
- * - `session/load`   → `ctx.agents.resume(...)` then replay the event log
- * - `session/prompt` → `agent.send()`, settle 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) + settle the in-flight prompt
- *
- * Multi-session (RFC 011): N concurrent sessions per connection, each mapped to
- * its own `ReactLoopAgent`. Sessions are keyed by id in `sessions` (forward) with an
- * `agent→sessionId` reverse map for O(1) demux of `agent/*` events; every
- * `session/event` and `agent/*` event is routed strictly to its owning session
- * record, so two sessions streaming at once never interleave their
- * `session/update` notifications. Permission prompts ride the same ownership
- * map: the bridge answers `approval/request` for its own agents over
- * `session/request_permission` (see the approval answerer below) — whether a
- * call ASKS is policy (a hook or plugin returning `ask`), not the bridge's.
- *
- * stdout is the protocol: this plugin must run in an example that loads NO
- * stdout logger (the console logger writes to stdout and would corrupt the
- * JSON-RPC frames). The guarantee is config-only — see the package README and
- * RFC 010 § Risks.
- *
+ * Multi-session ACP server bridge over JSON-RPC stdio. Creates or resumes
+ * agents, routes their events, settles prompts by turn, and answers approvals.
+ * Stdout is reserved for protocol frames.
  * @module @deepseek-ai/dsh-acp
  */
 
@@ -102,30 +72,15 @@ import {
 } from './codec.ts'
 
 export const name = 'acp'
-// The bridge programs against the interface packages only (architecture rule:
-// plugins never depend on dsh-agent-loop). `sessionPersistence` is required
-// because `initialize` advertises `loadSession: true`. `tools` lets a tool own
-// how its calls render (`presentCall`/`presentResult`); the bridge looks up the
-// definition by name and falls back to a generic presentation when absent.
+// Interface services required by advertised ACP capabilities.
 export const inject = ['agents', 'sessions', 'sessionPersistence', 'tools', 'userInteraction']
 
-/**
- * Build an ACP "invalid params" error whose human detail rides in the message.
- * `RequestError.invalidParams(data, additionalMessage)` keeps the standard
- * "Invalid params" message and appends `additionalMessage`, so we pass the
- * detail as `additionalMessage` (and no structured `data`).
- */
+/** Build an ACP invalid-params error with visible human detail. */
 function invalidParams(detail: string): RequestError {
   return RequestError.invalidParams(undefined, detail)
 }
 
-/**
- * Build an ACP "internal error" whose human detail rides in the message. Used
- * to reject a `session/prompt` whose turn ended in failure: a plain `Error`
- * thrown from a method handler is flattened to a generic "Internal error" on
- * the wire, so we wrap the detail in the SDK's `RequestError.internalError`
- * (which appends `additionalMessage`) to surface *why* the turn failed.
- */
+/** Build an ACP internal error with visible human detail. */
 function internalError(detail: string): RequestError {
   return RequestError.internalError(undefined, detail)
 }
@@ -248,13 +203,7 @@ function stringArrayContent(
 export interface AcpConfig {
   /** Model name for created agents (must have a registered adapter). */
   model?: string
-  /**
-   * Transport stream override. Production omits this (the plugin wires
-   * `process.stdin`/`process.stdout` via `ndJsonStream`). Tests inject an
-   * in-memory `Stream` (e.g. an `ndJsonStream` over a `Duplex` pair) to drive
-   * the bridge without a subprocess. Not part of the schemastery `Config` —
-   * it is a runtime-only seam, never set from a `cordis.yml`.
-   */
+  /** Runtime-only transport override for tests; production uses stdio. */
   stream?: Stream
 }
 
@@ -262,70 +211,23 @@ export const Config: Schema<AcpConfig> = Schema.object({
   model: Schema.string(),
 })
 
-/**
- * Per-session bridge state. One per live ACP session; held in the `sessions`
- * map keyed by id (RFC 011 multi-session).
- */
+/** Per-session bridge state keyed by ACP session id. */
 interface SessionRecord {
   sessionId: SessionId
   agent: Agent
-  /**
-   * The owned-agent disposer (from the {@link AgentHandle} the factory returned).
-   * Teardown calls it to unregister this ONE agent, stop its loop, await
-   * quiescence, and remove its session — instead of leaving it for the bridge
-   * fiber to reclaim.
-   */
+  /** Owned-agent disposer that reaches per-session quiescence. */
   dispose: () => Promise<void>
-  /**
-   * Resolves tool-owned presentation for THIS session's tool calls and remembers
-   * each in-flight call's `(name, args)` so the matching `tool/result` can find
-   * its tool. Per-session so two concurrent sessions never cross their in-flight
-   * tool state.
-   */
+  /** Per-session tool presenter and in-flight call correlation. */
   presenter: ToolPresenter
-  /**
-   * Whether THIS session renders shell tools as terminal cards — snapshotted
-   * from the client's `_meta.terminal_output` capability at session creation
-   * (`session/new`/`session/load`), NOT re-read live. A capability snapshot per
-   * session means the `tool_call` (which registers the terminal) and the matching
-   * `tool_call_update` (which streams its output) ALWAYS agree, even if a later
-   * `initialize` mutates the connection-level capability between them — otherwise
-   * a re-`initialize` mid-call could orphan a `terminal_output` (call non-terminal,
-   * result terminal) or clobber the card (call terminal, result non-terminal).
-   */
+  /** Session-creation snapshot of terminal-card support for call/result consistency. */
   terminalEnabled: boolean
-  /**
-   * The in-flight `session/prompt`, or `undefined` when none is pending. A
-   * prompt resolves with a {@link StopReason} or rejects with an Error (a
-   * turn that ended in failure). Settled exactly once by its matching
-   * `turn/end`, direct cancellation, or teardown.
-   *
-   * `turn` is the loop turn number this prompt owns, captured from the log's
-   * `turn/start` after `send()`. Until then it is `undefined` (the turn has not
-   * begun). Only a `turn/end` whose turn number equals `turn` settles the prompt
-   * — so a *previous* prompt's late `turn/end` (e.g. an aborted turn whose end
-   * arrives after the next prompt is already installed) can never settle the
-   * wrong prompt. A direct cancel/dispose settle clears the whole in-flight slot,
-   * so a later stale `turn/end` finds no pending prompt.
-   *
-   */
+  /** In-flight prompt and its captured turn number for exact settlement. */
   inflight: {
     resolve: (reason: StopReason) => void
     reject: (error: Error) => void
     turn: number | undefined
   } | undefined
-  /**
-   * Config switches accepted while the session was IDLE, not yet anchored in
-   * its log. The turn-enclosure contract makes a bare between-turns append
-   * invalid (the JSONL backend treats a post-`turn/end` tail as crash
-   * garbage, and dev invariants throw), so an idle switch waits here and is
-   * anchored at the next turn's prompt-submit — before anything in that
-   * turn assembles a prompt or runs a call, and last write
-   * per knob wins (an idle flip-flop anchors as one event). Until anchored,
-   * the switch lives only in bridge memory: the set/new/load responses
-   * overlay it truthfully, and a restart before the next turn reverts it —
-   * which `session/load` then reports honestly from the log's fold.
-   */
+  /** Idle config changes awaiting a turn-enclosed log anchor; last write wins. */
   pendingSwitches: { sandboxMode?: SandboxMode; approvalPolicy?: ApprovalPolicy }
 }
 
@@ -336,41 +238,23 @@ interface SessionRecord {
  * correlation in a `finally` so presentation failure cannot starve settlement.
  */
 export function apply(ctx: Context, config: AcpConfig): void {
-  // Capture the injected services NOW, during apply(), while we are inside this
-  // plugin's fiber (where `inject` grants access). The ACP method handlers run
-  // LATER, from the AgentSideConnection's JSON-RPC read loop — a context that is
-  // NOT this fiber's injection scope — so reading `ctx.agents` / `ctx.logger` /
-  // `ctx.sessionPersistence` lazily inside a handler throws "cannot get property
-  // … without inject". Resolving the references here and closing over them keeps
-  // the handlers working regardless of which fiber later invokes them.
+  // Capture injected services while executing inside this plugin's fiber.
   const agents = ctx.agents
   const sessionPersistence = ctx.sessionPersistence
   const logger = ctx.logger
   const tools = ctx.tools
   const userInteraction = ctx.userInteraction
-  // A new ToolPresenter per session (and a throwaway per load replay), each given
-  // this warn sink so a throwing tool presenter is logged, not propagated.
+  // Presenter failures are logged and contained per session or replay.
   const makePresenter = (agent?: Agent): ToolPresenter => new ToolPresenter(tools, (message) => { logger.warn(message) }, agent)
 
-  // Live sessions keyed by id (RFC 011 multi-session), plus an agent→sessionId
-  // reverse map so `agent/*` events (which carry only the Agent) demux in O(1).
-  // The two stay in lockstep: a record is added to `sessions` and the agent to
-  // `bySession` together, and removed together.
+  // Keep forward and reverse session indexes in lockstep.
   const sessions = new Map<SessionId, SessionRecord>()
   const bySession = new WeakMap<Agent, SessionId>()
-  // Session ids whose `session/load` is mid-`resume()` (the slot is reserved
-  // before the async resume so a pipelined load/new for the SAME id can't create
-  // two agents). Distinct ids load concurrently; a given id loads once at a time.
+  // Reserve ids across asynchronous resume; distinct ids still load concurrently.
   const loadingIds = new Set<SessionId>()
-  // Set once the bridge has torn down (disposal or client disconnect). An async
-  // `session/load` mid-`resume()` when teardown ran must observe this after its
-  // await and NOT install a record (which would resurrect a live agent/listeners
-  // after the bridge closed). Checked after every load await.
+  // Post-await checks prevent a closing bridge from publishing resumed sessions.
   let closed = false
-  // Whether the client advertised the Zed `_meta.terminal_output` capability in
-  // `initialize`. When true, a tool's terminal presentation is rendered as a
-  // terminal card (content + `_meta.terminal_*`); when false, the bridge uses
-  // the tool's text fallback. Set once in `initialize`, read on every tool event.
+  // Connection-level capability copied into each new session record.
   let terminalOutputCap = false
 
   // Assigned at the bottom, before any agent event can fire (a session only
@@ -1140,12 +1024,7 @@ export function streamSessionEventUpdate(
 }
 
 /**
- * Map a harness todo list to an ACP `plan` body. ACP's `PlanEntry` requires
- * `content` + `priority` + `status`, but a {@link TodoItem} carries no priority,
- * so synthesize a constant `'medium'` on every entry; `status` maps 1:1 (the
- * harness status triple IS `PlanEntryStatus`). The ACP client REPLACES its whole
- * plan on each `plan` update, matching the harness's whole-list-replace
- * semantics, so no per-entry diffing is needed.
+ * Map a whole harness todo list to an ACP plan, assigning medium priority.
  * @param todos - the harness todo list (the whole list, not a diff).
  * @returns the ACP plan body, one entry per todo.
  */
@@ -1153,14 +1032,7 @@ export function todosToPlan(todos: TodoItem[]): Plan {
   return { entries: todos.map((todo): PlanEntry => ({ content: todo.content, priority: 'medium', status: todo.status })) }
 }
 
-/**
- * Per-connection terminal-rendering context threaded into
- * {@link streamSessionEventUpdate}: whether the client advertised the
- * `_meta.terminal_output` capability, and the session's workspace cwd (the
- * default terminal-card header when a tool doesn't supply its own). Kept out of
- * the pure translator's required params so the no-capability / no-presenter
- * tests stay terse.
- */
+/** Terminal-card capability and workspace context for event rendering. */
 export interface TerminalRendering {
   enabled: boolean
   /** The session workspace cwd (terminal-card header default); `undefined` when the session has none. */
@@ -1171,59 +1043,30 @@ export interface TerminalRendering {
 const noTerminalRendering: TerminalRendering = { enabled: false, cwd: undefined }
 
 /**
- * Resolves tool-owned presentation for a session's tool-call events. A tool
- * declares `presentCall`/`presentResult` (see `dsh-tools`) returning a
- * `card`-tagged {@link ToolCallView}/{@link ToolResultView}; this looks them up
- * by name in the registry and applies a generic fallback when a tool defines
- * neither. The returned view is what {@link streamSessionEventUpdate} switches on.
- *
- * The `tool/result` session event does NOT carry the tool name or args — so to
- * call a tool's `presentResult` (which needs both), the presenter remembers each
- * `tool/call`'s `{ name, args, card }` keyed by callId and looks it up on the
- * matching result. The map is bridge-LOCAL (not a change to the event schema or a
- * core service): one presenter per live session
- * (and a throwaway per `session/load` replay), and each entry is removed when its
- * result arrives. In the normal loop a `tool/call` is always followed by a
- * `tool/result` (the registry turns even a thrown tool into an isError result),
- * so the map holds only currently-in-flight calls. The one exception is a step
- * torn down mid-tool (an abort between `tool/call` and `tool/result`), which can
- * leave a single stale entry per such call; this is bounded by the session
- * lifetime (the whole presenter is dropped on teardown) and never affects
- * correctness — a later result for a different callId is unaffected, and the
- * stale entry's only cost is one map slot until the session ends.
+ * Resolve tool-owned call/result views with generic fallbacks. Per-session
+ * call-id state supplies the tool name and arguments omitted from result events.
  */
 export class ToolPresenter {
   private readonly pending = new Map<CallId, { name: string; args: unknown; card: ToolCallView['card'] }>()
 
   /**
    * @param tools the registry to resolve tool definitions by name.
-   * @param onError invoked when a tool's `presentCall`/`presentResult` THROWS;
-   *   the presenter swallows the error and falls back to the generic
-   *   presentation so a buggy display callback can never fail a live turn or a
-   *   `session/load` replay (docs/defensive-patterns.md "contain callback exceptions at the
-   *   boundary"). Defaults to a no-op for callers that don't supply a logger.
+   * @param onError receives contained presenter failures before generic fallback.
    */
   constructor(
     private readonly tools: Pick<ToolRegistry, 'get'>,
     private readonly onError: (message: string) => void = () => {},
-    /**
-     * The agent whose view resolves tool presentations: a scoped/shadowed
-     * tool presents with ITS OWN presentCall/presentResult — the same
-     * definition that executed — not a same-named global's. Absent (a replay
-     * with no live agent) the global view presents.
-     */
+    /** Agent scope for tool lookup; absent during replay without a live agent. */
     private readonly agent?: Agent,
   ) {}
 
   /**
-   * Pending-state render intent for a `tool/call`; remembers `(name, args, card)`
-   * for the matching result.
+   * Resolve a pending call and remember its state for the matching result.
    * @param callId - the call id the matching `tool/result` will look up.
    * @param name - the tool name, resolved against the registry for `presentCall`.
    * @param argsJson - the raw arguments JSON from the event; parsed for the view
    * (a non-JSON string is surfaced raw).
-   * @returns the tool-owned view, or the generic fallback (title = tool name,
-   * kind `other`, parsed args as raw input) when the tool defines none or threw.
+   * @returns the tool-owned view, or a generic parsed-input fallback.
    */
   call(callId: CallId, name: string, argsJson: string): ToolCallView {
     const args = parseToolArguments(argsJson)
@@ -1245,16 +1088,12 @@ export class ToolPresenter {
   }
 
   /**
-   * Completed-state render intent for a `tool/result`; consumes the remembered
-   * `(name, args, card)`.
-   * @param callId - the id of the matching `tool/call`; an unknown or late id
-   * falls back to the raw content.
+   * Resolve a completed result and consume its remembered call state.
+   * @param callId - matching call id; unknown or late ids use raw content.
    * @param content - the result's content blocks (the fallback and fill-in body).
    * @param isError - whether the result is an error, forwarded to `presentResult`.
    * @param meta - the result's machine-readable meta, forwarded when present.
-   * @returns the tool-owned view — an orphaned `terminal` result (no terminal
-   * call side) and a content-less `generic` are normalized — or the raw-content
-   * generic card when the tool defines no `presentResult` or threw.
+   * @returns the normalized tool-owned view, or a raw-content generic fallback.
    */
   result(callId: CallId, content: ContentBlock[], isError: boolean, meta?: unknown): ToolResultView {
     const call = this.pending.get(callId)
@@ -1324,25 +1163,11 @@ type AcpToolCallContent =
   | { type: 'diff'; path: string; oldText: string | null; newText: string }
   | { type: 'terminal'; terminalId: string }
 
-/**
- * Relativize a file card's TITLE path against the session workspace cwd, so a
- * card reads `Read src/foo.ts` rather than `/abs/proj/src/foo.ts` — matching the
- * reference ACP adapter's `toDisplayPath`. Only the TITLE is relativized; the
- * card's `locations`/`diff` paths stay RAW (the editor opens the real path). The
- * pure tool presenter can't see the session cwd, so this happens here where the
- * bridge knows it. The rewrite is an exact substring replace of the known raw
- * path (a card carries the same path in `locations[0]`/`diffs[0]`), never a
- * heuristic. A path outside the workspace, or an absent/relative session cwd, is
- * left unchanged.
- */
+/** Relativize an in-workspace file path in a card title; keep target paths raw. */
 function displayTitle(title: string, rawPath: string | undefined, sessionCwd: string | undefined): string {
   if (rawPath === undefined || sessionCwd === undefined || !isAbsolute(rawPath) || !isAbsolute(sessionCwd)) return title
   const rel = relativePath(sessionCwd, rawPath)
-  // Only relativize a target that stays INSIDE the workspace. `relative` prefixes
-  // a `..` SEGMENT for a target above the cwd — test for the segment (`..` alone
-  // or `..<sep>…`), NOT a bare `..` char prefix, so a sibling like `..cache/x`
-  // (a real in-workspace name) still relativizes. Never relativize to the empty
-  // string (rawPath === cwd — a non-file target).
+  // Reject an empty relative path or a leading parent-directory segment.
   if (rel.length === 0 || rel === '..' || rel.startsWith(`..${pathSep}`)) return title
   return title.split(rawPath).join(rel)
 }