dsh-acp-enhanced 0.1.0

package/lib/index.js

@@ -0,0 +1,1429 @@
+/**
+ * Enhanced Agent Client Protocol server for DeepSeek Harness.
+ *
+ * A drop-in improvement over the official `@deepseek-ai/dsh-acp` automation
+ * bridge. It keeps the same session model (fresh agents per `session/new`,
+ * prompt/cancel lifecycle, one-shot permission requests) and adds the surfaces
+ * the Web GUI has but the official wire lacks:
+ *
+ * - **Block-level streaming**: `text` blocks are emitted as soon as each block
+ *   commits (`block-end`), instead of waiting for the whole `assistant/message`.
+ *   A retried/cancelled block is dropped before it commits, so the wire never
+ *   carries torn text.
+ * - **Usage telemetry**: every provider `usage` sample is broadcast as a
+ *   standard `usage_update` (used = context pressure, size = model context
+ *   window), with the full breakdown in `_meta`: input/output/cache/reasoning
+ *   tokens, cache hit rate, tokens-per-second, step elapsed, turn count, and
+ *   tool-call stats.
+ * - **Tool visibility**: `tool_call` / `tool_call_update` notifications carry
+ *   the tool name and per-call elapsed time.
+ * - **Session configuration**: `session/set_config_option` switches model,
+ *   reasoning effort, and permission preset; the option set is advertised on
+ *   `session/new` and re-broadcast as `config_option_update` after changes.
+ * - **Session modes**: permission presets are exposed as ACP modes
+ *   (`session/set_mode`), so the client's mode UI drives the sandbox/approval
+ *   preset of the session.
+ *
+ * Stdout is reserved for ACP JSON-RPC; diagnostics go to stderr only.
+ *
+ * @module dsh-acp-enhanced
+ */
+
+import { randomUUID } from 'node:crypto'
+import { rm } from 'node:fs/promises'
+import { isAbsolute, dirname } from 'node:path'
+import { Readable, Writable } from 'node:stream'
+import Schema from '@deepseek-ai/schemastery'
+import { AgentSideConnection, ndJsonStream, PROTOCOL_VERSION, RequestError } from '@agentclientprotocol/sdk'
+import { createUserMessage, errorChain, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+import { installModelSelection } from '@deepseek-ai/dsh-agent'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { acpPromptToText, promptHasUnsupportedContent, turnEndToStopReason, usageTelemetry } from './codec.js'
+
+export const name = 'acp-enhanced'
+/** The bridge creates and owns agents; every other concern is carried by the composition. */
+export const inject = ['agents', 'llm', 'approval', 'tools']
+
+export const Config = Schema.object({
+  /** Initial provider route for every created agent. */
+  provider: Schema.string(),
+  /** Initial model for every created agent. */
+  model: Schema.string(),
+  /** When false (default), the model dropdown advertises only the configured
+   *  provider's models. On a single-provider machine (chat routed through a
+   *  company gateway, or through a single official key) this hides "phantom"
+   *  providers — mountable-but-unroutable adapters whose models look switchable
+   *  but fail to dispatch with a MISSING_CREDENTIAL error. Set true to list
+   *  every served provider's models regardless. */
+  includeAllProviders: Schema.boolean().default(false),
+})
+
+/** Preserve invalid-parameter detail in the SDK wire error message. */
+function invalidParams(detail) {
+  return RequestError.invalidParams(undefined, detail)
+}
+
+/** Preserve failed-turn detail; plain handler errors become a generic wire internal error. */
+function internalError(detail) {
+  return RequestError.internalError(undefined, detail)
+}
+
+/**
+ * Map a dsh tool name to the ACP ToolKind used for icons and card UX.
+ *
+ * Zed treats kind == 'execute' as a TERMINAL tool and kind == 'edit' as a
+ * diff tool, and for both it HIDES rawInput (the "Raw Input:" section). Only
+ * genuinely terminal tools (zed_terminal) should be 'execute'; local executors
+ * like bash/run_code must stay 'other' so the editor shows the exact arguments
+ * (the command) plus the output. Write/edit tools likewise stay 'other' unless
+ * the bridge also emits diff content — otherwise the card would show nothing.
+ */
+function toolKindFor(name) {
+  if (name === 'zed_terminal') return 'execute'
+  if (/^fs_.*read|read_text|cat|show/.test(name)) return 'read'
+  if (/search|find|grep/.test(name)) return 'search'
+  if (/fetch|http/.test(name)) return 'fetch'
+  if (/think/.test(name)) return 'think'
+  return 'other'
+}
+
+/** Parse a tool's raw arguments JSON into a JSON value for ACP rawInput. */
+function parseToolArguments(raw) {
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed !== null && typeof parsed === 'object' ? parsed : String(raw ?? '')
+  } catch {
+    return String(raw ?? '')
+  }
+}
+
+/** Extract a bounded text preview of a dsh tool result for ACP rawOutput. */
+function resultPreview(event) {
+  if (event.data.error !== undefined) {
+    return `[tool error: ${event.data.error.code ?? event.data.error.name ?? 'unknown'}]`
+  }
+  const parts = []
+  for (const block of event.data.message?.content ?? []) {
+    for (const inner of block?.content ?? []) {
+      if (inner?.type === 'text' && typeof inner.text === 'string') parts.push(inner.text)
+    }
+  }
+  const text = parts.join('\n')
+  return text.length > 0 ? text.slice(0, 12000) : undefined
+}
+
+/** Mount the enhanced ACP server. */
+export function apply(ctx, config) {
+  // ACP handlers execute outside this plugin's injection scope, so capture the
+  // injected services during apply rather than reading them lazily in a callback.
+  const agents = ctx.agents
+  const llm = ctx.llm
+  const approval = ctx.approval
+  const tools = ctx.tools
+  const logger = ctx.logger
+  /** The user-questions service (mounted by dsh-base); absent in minimal deployments. */
+  const userQuestions = ctx.get('userQuestions')
+
+  /** sessionId → protocol state for one bridge-owned agent. */
+  const sessions = new Map()
+  let closed = false
+  let conn
+  /** Capabilities the connected client advertised on `initialize`. */
+  let clientCaps = {}
+  /** Disposers for the client-forwarding tools currently registered. */
+  let clientToolDisposers = []
+
+  /** Resolve the permission-presets service, tolerating a lazy mount. */
+  const permissionPresets = () => ctx.get('permissionPresets')
+
+  /** Return the bridge-owned record for an agent, rejecting same-id impostors. */
+  const ownedRecord = (agent) => {
+    const record = sessions.get(agent.session.id)
+    return record?.agent === agent ? record : undefined
+  }
+
+  const assertOpen = () => {
+    if (closed) throw internalError('the ACP bridge has been disposed')
+  }
+
+  const requireSession = (sessionId) => {
+    const record = sessions.get(sessionId)
+    if (record === undefined) throw invalidParams(`unknown session: ${sessionId}`)
+    return record
+  }
+
+  /** Send a protocol update without letting a disconnected client fail an agent turn. */
+  const notify = (notification) => {
+    void conn.sessionUpdate(notification).catch((error) => {
+      logger.warn(`acp-enhanced: session/update failed: ${String(error)}`)
+    })
+  }
+
+  const settlePrompt = (record, reason) => {
+    const inflight = record.inflight
+    if (inflight === undefined) return
+    record.inflight = undefined
+    inflight.resolve(reason)
+  }
+
+  const rejectFromError = (inflight, reason) => {
+    inflight.reject(internalError(`turn failed: ${reason.error.message}`))
+  }
+
+  // ── session/event → ACP notifications ─────────────────────────────────────
+
+  ctx.on('session/event', (session, event) => {
+    const record = sessions.get(session.header.id)
+    if (record === undefined || record.agent.session !== session) return
+    try {
+      if (process.env.ACP_DEBUG) {
+        const extra = event.type === 'turn/end' ? ` reason=${JSON.stringify(event.data.reason)}` : event.type === 'assistant/chunk' ? ` chunkType=${event.data.chunk.type}` : event.type === 'agent/inbox/spliced' ? ` hasPending=${record.agent.inbox?.hasPending}` : event.type === 'tool/call' ? ` name=${event.data.name}` : ''
+        process.stderr.write(`[acp-debug] ${event.type} turn=${event.data?.turn} step=${event.data?.step}${extra}\n`)
+      }
+      switch (event.type) {
+        case 'assistant/chunk':
+          handleChunk(record, event)
+          break
+        case 'assistant/message':
+          // Final accounting when the adapter reported usage on the message
+          // rather than as a stream chunk.
+          if (event.data.usage !== undefined) emitUsage(record, event.data.usage, event)
+          break
+        case 'turn/start': {
+          record.turnCount += 1
+          record.turnStartedAt = Date.now()
+          break
+        }
+        case 'turn/end': {
+          const elapsed = record.turnStartedAt === undefined ? 0 : Date.now() - record.turnStartedAt
+          record.turnStartedAt = undefined
+          record.lastActivityAt = Date.now()
+          publishSessionInfo(record, { updatedAt: new Date(record.lastActivityAt).toISOString() })
+          // Surface turn-level stats even when no usage sample landed this turn.
+          if (record.lastUsage !== undefined) {
+            notify({
+              sessionId: session.header.id,
+              update: {
+                sessionUpdate: 'usage_update',
+                used: record.lastUsage.used,
+                size: record.lastUsage.size,
+                _meta: {
+                  ...record.lastUsage.meta,
+                  turnCount: record.turnCount,
+                  turnMs: elapsed,
+                  tools: record.toolStats.count > 0 ? {
+                    count: record.toolStats.count,
+                    totalMs: record.toolStats.totalMs,
+                  } : undefined,
+                },
+              },
+            })
+          }
+          break
+        }
+        case 'step/start':
+          record.stepStartedAt = Date.now()
+          // One ACP message per model step: all block chunks of this step share
+          // the same messageId so the client can group them.
+          record.messageId = randomUUID()
+          break
+        case 'tool/call': {
+          record.toolStats.lastCallAt = Date.now()
+          record.toolStats.lastName = event.data.name
+          notify({
+            sessionId: session.header.id,
+            update: {
+              sessionUpdate: 'tool_call',
+              toolCallId: event.data.callId,
+              title: event.data.name,
+              kind: toolKindFor(event.data.name),
+              rawInput: parseToolArguments(event.data.arguments),
+              _meta: {
+                turn: event.data.turn,
+                step: event.data.step,
+                name: event.data.name,
+                argumentsPreview: event.data.arguments.slice(0, 200),
+              },
+            },
+          })
+          break
+        }
+        case 'tool/result': {
+          const elapsed = record.toolStats.lastCallAt === undefined
+            ? 0
+            : Date.now() - record.toolStats.lastCallAt
+          record.toolStats.count += 1
+          record.toolStats.totalMs += elapsed
+          record.toolStats.lastCallAt = undefined
+          // The tool call id lives on the ToolResultBlock, not on the event root.
+          const callId = event.data.message?.content?.[0]?.toolCallId ?? event.data.callId
+          const preview = resultPreview(event)
+          notify({
+            sessionId: session.header.id,
+            update: {
+              sessionUpdate: 'tool_call_update',
+              toolCallId: callId,
+              status: event.data.error === undefined ? 'completed' : 'error',
+              ...preview === undefined ? {} : { rawOutput: preview },
+              _meta: {
+                turn: event.data.turn,
+                step: event.data.step,
+                elapsedMs: elapsed,
+                count: record.toolStats.count,
+                totalMs: record.toolStats.totalMs,
+              },
+            },
+          })
+          break
+        }
+        case 'request/context':
+          if (event.data.contextWindow !== undefined) record.contextWindow = event.data.contextWindow
+          break
+        case 'session/title': {
+          const title = event.data.title
+          if (typeof title === 'string' && title.length > 0) {
+            record.title = title
+            publishSessionInfo(record, {
+              title,
+              updatedAt: new Date().toISOString(),
+            })
+          }
+          break
+        }
+        case 'plan/mode': {
+          // Map DSH plan mode flips onto the ACP Plan panel. DSH plan mode has
+          // no structured task list, so a single state entry marks "planning in
+          // progress" while active; leaving plan mode clears the panel. The
+          // wire shape is flat: `{ sessionUpdate: 'plan', entries: [...] }`.
+          const active = event.data.active === true
+          notify({
+            sessionId: session.header.id,
+            update: {
+              sessionUpdate: 'plan',
+              entries: active
+                ? [{
+                  content: 'Plan mode: the agent will propose a plan and await your review before making changes.',
+                  priority: 'high',
+                  status: 'in_progress',
+                }]
+                : [],
+            },
+          })
+          break
+        }
+      }
+    } finally {
+      const inflight = record.inflight
+      if (inflight !== undefined && event.type === 'turn/end'
+        && (inflight.turn === undefined || inflight.turn === event.data.turn)) {
+        // agent/inbox/claimed can arrive on a scope this plugin does not see;
+        // with at most one in-flight prompt per session, the newest turn/end
+        // is authoritative for the pending prompt.
+        if (event.data.reason.kind === 'error') {
+          record.inflight = undefined
+          rejectFromError(inflight, event.data.reason)
+        } else {
+          inflight.endReason = event.data.reason
+        }
+      }
+    }
+  })
+
+  /**
+   * Block-level streaming: accumulate text deltas per block index and forward
+   * committed blocks immediately. A retry restarts the same index, so torn
+   * partial text never reaches the wire; the uncommitted tail of a cancelled
+   * attempt is simply dropped.
+   */
+  function handleChunk(record, event) {
+    const chunk = event.data.chunk
+    switch (chunk.type) {
+      case 'block-start':
+        if (chunk.blockType === 'text') record.buffer[chunk.index] = ''
+        break
+      case 'text-delta':
+        if (record.buffer[chunk.index] !== undefined) record.buffer[chunk.index] += chunk.text
+        break
+      case 'block-end': {
+        const text = record.buffer[chunk.index]
+        delete record.buffer[chunk.index]
+        if (chunk.block.type === 'text' && text !== undefined && text.length > 0) {
+          notify({
+            sessionId: record.agent.session.id,
+            update: {
+              sessionUpdate: 'agent_message_chunk',
+              messageId: record.messageId,
+              content: { type: 'text', text },
+            },
+          })
+        }
+        break
+      }
+      case 'usage':
+        emitUsage(record, chunk.usage, event)
+        break
+    }
+  }
+
+  /** Broadcast one usage sample as a standard usage_update with rich _meta. */
+  function emitUsage(record, usage, event) {
+    const now = Date.now()
+    const elapsedMs = record.stepStartedAt === undefined ? 0 : now - record.stepStartedAt
+    const telemetry = usageTelemetry(usage, elapsedMs)
+    const used = telemetry.contextTokens
+    const size = record.contextWindow ?? used
+    const update = {
+      sessionUpdate: 'usage_update',
+      used,
+      size,
+      _meta: {
+        ...telemetry,
+        turn: event?.data?.turn,
+        step: event?.data?.step,
+        turnCount: record.turnCount,
+        tools: record.toolStats.count > 0 ? {
+          count: record.toolStats.count,
+          totalMs: record.toolStats.totalMs,
+        } : undefined,
+      },
+    }
+    record.lastUsage = { used, size, meta: update._meta }
+    notify({ sessionId: record.agent.session.id, update })
+  }
+
+  // ── approval → session/request_permission ─────────────────────────────────
+
+  ctx.on('approval/request', (request, next) => {
+    const record = ownedRecord(request.agent)
+    if (record === undefined || request.callId === undefined) return next()
+    return conn.requestPermission({
+      sessionId: record.agent.session.id,
+      toolCall: { toolCallId: request.callId },
+      options: [
+        { optionId: 'allow-once', name: 'Allow once', kind: 'allow_once' },
+        { optionId: 'reject-once', name: 'Reject', kind: 'reject_once' },
+      ],
+    }).then(({ outcome }) => {
+      if (outcome.outcome === 'cancelled') return 'cancelled'
+      return outcome.optionId === 'allow-once' ? 'allowed-once' : 'rejected'
+    })
+  })
+
+  // ── configuration options (model / reasoning effort / permission preset) ──
+
+  /**
+   * A provider route can register asynchronously right after boot, so a
+   * freshly spawned bridge may enumerate before the profile's provider (e.g.
+   * one that registers after a gateway/adapter section is applied) appears in
+   * `llm.listProviders()`. Without a settle, the very first `session/new`
+   * builds a model select that omits the session's own provider, so its models
+   * cannot be chosen. Wait until the expected provider is registered (or a
+   * short ceiling elapses) before building the catalog; also rebroadcast
+   * config options whenever the adapter set changes, so an editor that opened
+   * a session mid-boot catches up.
+   */
+  function waitForProvider(provider) {
+    if (provider === undefined) return Promise.resolve()
+    if (llm.listProviders().some((entry) => entry.id === provider)) return Promise.resolve()
+    return new Promise((resolve) => {
+      let settled = false
+      const finish = () => {
+        if (settled) return
+        settled = true
+        dispose()
+        clearTimeout(timer)
+        resolve()
+      }
+      const check = () => {
+        if (llm.listProviders().some((entry) => entry.id === provider)) finish()
+      }
+      const timer = setTimeout(finish, 4000)
+      const dispose = ctx.on('llm/adapters-updated', check)
+    })
+  }
+
+  /** Rebuild every open session's config options when the provider set changes. */
+  ctx.on('llm/adapters-updated', () => {
+    for (const record of sessions.values()) {
+      broadcastConfig(record).catch((error) => {
+        logger.warn(`acp-enhanced: config rebroadcast after adapter update failed: ${String(error)}`)
+      })
+    }
+  })
+
+  /** Model directory for the select option: provider/model entries with reasoning info. */
+  async function modelCatalog() {
+    const groups = []
+    await waitForProvider(config.provider)
+    let providers = llm.listProviders()
+    if (!config.includeAllProviders) {
+      const configured = providers.filter((entry) => entry.id === config.provider)
+      // Only advertise the configured provider's models. This machine's default
+      // route is the one that can actually dispatch; dropping the rest keeps the
+      // "phantom" cross-provider group (e.g. an official adapter mounted but
+      // without a key when chat routes through a company gateway) from appearing
+      // selectable — picking one silently broke every later prompt. Fall back to
+      // the full set only if the configured provider isn't served yet, so the
+      // dropdown is never empty during adapter boot.
+      if (configured.length > 0) providers = configured
+    }
+    for (const provider of providers) {
+      try {
+        const models = await llm.listModels(provider.id)
+        const entries = await Promise.all(models.map(async (model) => {
+          let resolved
+          try {
+            resolved = await llm.resolveModelInfo(provider.id, model.id)
+          } catch {
+            resolved = undefined
+          }
+          return {
+            id: model.id,
+            name: model.name,
+            ...model.description === undefined ? {} : { description: model.description },
+            ...resolved?.reasoning === undefined ? {} : {
+              reasoning: {
+                efforts: resolved.reasoning.efforts.map((effort) => ({
+                  id: effort.id,
+                  name: effort.name,
+                  ...effort.description === undefined ? {} : { description: effort.description },
+                })),
+                ...resolved.reasoning.defaultEffort === undefined ? {} : { defaultEffort: resolved.reasoning.defaultEffort },
+              },
+            },
+          }
+        }))
+        if (entries.length > 0) groups.push({ id: provider.id, name: provider.name, models: entries })
+      } catch {
+        // A provider that fails to enumerate contributes no models.
+      }
+    }
+    return groups
+  }
+
+  /** Build the full config-option set for one session. */
+  async function buildConfigOptions(record) {
+    const selected = record.selection.current
+    const options = []
+    const groups = await modelCatalog()
+    // ACP grouped-select shape: each group is `{ group, name, options }`
+    // (`group` = unique id, `name` = display label). Emitting `groupName`
+    // instead made Zed skip the whole group on deserialization, so the model
+    // dropdown came back empty and models could not be selected.
+    const selectGrouped = groups.map((group) => ({
+      group: group.id,
+      name: group.name,
+      options: group.models.map((model) => ({
+        value: `${group.id}/${model.id}`,
+        name: model.name,
+        ...model.description === undefined ? {} : { description: model.description },
+      })),
+    }))
+    options.push({
+      id: 'model',
+      type: 'select',
+      name: 'Model',
+      description: 'Provider/model route for this session (provider/model values).',
+      category: 'model',
+      currentValue: `${selected.provider}/${selected.model}`,
+      options: selectGrouped,
+    })
+    const modelInfo = await llm.resolveModelInfo(selected.provider, selected.model).catch(() => undefined)
+    const efforts = modelInfo?.reasoning?.efforts ?? []
+    // Only advertise the reasoning-effort option when the routed model exposes
+    // selectable efforts. A model route without reasoning metadata (e.g. a
+    // gateway that reports none) would otherwise render an empty, dead dropdown
+    // chip next to the send button.
+    if (efforts.length > 0) {
+      options.push({
+        id: 'reasoning_effort',
+        type: 'select',
+        name: 'Reasoning effort',
+        description: 'Reasoning level applied to model requests for this session.',
+        category: 'thought_level',
+        currentValue: selected.reasoningEffort ?? modelInfo?.reasoning?.defaultEffort ?? '',
+        options: efforts.map((effort) => ({
+          value: effort.id,
+          name: effort.name,
+          ...effort.description === undefined ? {} : { description: effort.description },
+        })),
+      })
+    }
+    const permission = permissionPresets()
+    if (permission !== undefined) {
+      options.push({
+        id: 'permission_preset',
+        type: 'select',
+        name: 'Permission preset',
+        description: 'Sandbox mode and approval policy bundle for this session.',
+        category: 'mode',
+        currentValue: permission.current(record.agent.session.events),
+        options: permission.names.map((presetName) => {
+          const spec = permission.presets[presetName]
+          return {
+            value: presetName,
+            name: spec?.name ?? presetName,
+            ...spec?.description === undefined ? {} : { description: spec.description },
+          }
+        }),
+      })
+    }
+    const planMode = ctx.get('planMode')
+    if (planMode !== undefined) {
+      options.push({
+        id: 'plan_mode',
+        type: 'boolean',
+        name: 'Plan mode',
+        description: 'Ask the agent to plan before acting and present the plan for review.',
+        category: 'plan',
+        currentValue: planMode.get(record.agent).active,
+      })
+    }
+    return options
+  }
+
+  /** Resolve and apply a new model/effort selection to the session. */
+  async function applySelection(record, next) {
+    const resolved = await llm.resolveCallConfig(next)
+    const selected = {
+      provider: resolved.provider,
+      model: resolved.model,
+      ...resolved.reasoningEffort === undefined ? {} : { reasoningEffort: resolved.reasoningEffort },
+    }
+    record.selection.current = selected
+    // Persist as the default only when the chosen route is one this bridge is
+    // wired to serve. On a single-provider machine the default route is the
+    // routable one, so switching within it always persists; a stray cross-provider
+    // pick (a manually addressed adapter that isn't configured here) is applied
+    // to this session but never recorded as the default, so it can't poison the
+    // default for every later session with a non-routable route.
+    const persistDefault = config.includeAllProviders || selected.provider === config.provider
+    if (persistDefault) {
+      try {
+        await ctx.get('agentDefaultModel')?.saveSelection?.(selected)
+      } catch (error) {
+        logger.warn(`acp-enhanced: the model switch applies to this session but was not saved as the default: ${String(error)}`)
+      }
+    }
+  }
+
+  async function broadcastConfig(record) {
+    const configOptions = await buildConfigOptions(record)
+    notify({
+      sessionId: record.agent.session.id,
+      update: { sessionUpdate: 'config_option_update', configOptions },
+    })
+    return configOptions
+  }
+
+  /** Apply one permission preset, mirroring the /permission command. */
+  function applyPermissionPreset(record, presetName, permission) {
+    if (!permission.names.includes(presetName)) {
+      throw invalidParams(`unknown permission preset "${presetName}" (available: ${permission.names.join(', ')})`)
+    }
+    permission.apply(record.agent.session, presetName, (policy) => {
+      approval.setPolicy(record.agent, policy)
+    })
+  }
+
+  // ── client-forwarding tools (Zed fs / terminal) ──────────────────────────
+
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+  /** The bridge-owned session record behind a tool call, or throw. */
+  function sessionIdOf(exec) {
+    const record = ownedRecord(exec.agent)
+    if (record === undefined) {
+      throw new Error('this tool is only usable inside a bridge-owned session')
+    }
+    return record.agent.session.id
+  }
+
+  /**
+   * Register (or refresh) the tools that forward to the connected client's own
+   * capabilities — Zed's filesystem API and terminal. They only exist while the
+   * client advertised the matching capability, so a raw test client or a plain
+   * automation client never sees them. When the model edits project files
+   * through `zed_write_text_file`, Zed applies the change to its own buffer and
+   * surfaces it in the agent panel's "edited files" section with diff +
+   * accept/reject; `zed_terminal` runs the command in a real Zed terminal.
+   */
+  function syncClientTools() {
+    for (const dispose of clientToolDisposers) dispose()
+    clientToolDisposers = []
+    const fsCaps = clientCaps.fs ?? {}
+    if (fsCaps.readTextFile === true) {
+      clientToolDisposers.push(tools.register(defineTool({
+        name: 'zed_read_text_file',
+        description: 'Read a file through the connected editor (Zed) instead of the local fs tool. Use for files inside the editor workspace; the editor resolves the path against its project and records the read in its agent activity log.',
+        parameters: {
+          path: { type: 'string', required: true, description: 'Absolute path to the file to read.' },
+          line: { type: 'integer', description: '1-based line to start reading from.' },
+          limit: { type: 'integer', description: 'Maximum number of lines to read.' },
+        },
+        output: {
+          schema: {
+            type: 'object', additionalProperties: false,
+            properties: { content: { type: 'string', required: true } },
+          },
+          render: (_args, value) => [{ type: 'text', text: value.content }],
+        },
+        async execute(args, exec) {
+          const sessionId = sessionIdOf(exec)
+          const response = await conn.readTextFile({
+            sessionId,
+            path: args.path,
+            ...args.line === undefined ? {} : { line: args.line },
+            ...args.limit === undefined ? {} : { limit: args.limit },
+          })
+          return { content: response.content }
+        },
+      })))
+    }
+    if (fsCaps.writeTextFile === true) {
+      clientToolDisposers.push(tools.register(defineTool({
+        name: 'zed_write_text_file',
+        description: 'Write a file through the connected editor (Zed) instead of the local fs write tool. Use for project files in the editor workspace: the editor applies the change to its own buffer and shows it in the agent panel\'s edited-files section with a diff you can accept or reject. The content replaces the whole file.',
+        parameters: {
+          path: { type: 'string', required: true, description: 'Absolute path to the file to write.' },
+          content: { type: 'string', required: true, description: 'The full text content to write to the file.' },
+        },
+        output: {
+          schema: {
+            type: 'object', additionalProperties: false,
+            properties: { path: { type: 'string', required: true }, bytes: { type: 'integer' } },
+          },
+          render: (_args, value) => [{ type: 'text', text: `wrote ${value.bytes ?? 0} bytes to ${value.path} (in the editor)` }],
+        },
+        async execute(args, exec) {
+          const sessionId = sessionIdOf(exec)
+          await conn.writeTextFile({ sessionId, path: args.path, content: args.content })
+          return { path: args.path, bytes: Buffer.byteLength(args.content, 'utf8') }
+        },
+      })))
+    }
+    if (clientCaps.terminal === true) {
+      clientToolDisposers.push(tools.register(defineTool({
+        name: 'zed_terminal',
+        description: 'Run a command in a terminal inside the connected editor (Zed) instead of the local bash tool. The command runs in a real editor terminal visible in the panel; output is captured until the process exits (up to 120s). Use when running commands in the editor workspace where you want the terminal visible.',
+        parameters: {
+          command: { type: 'string', required: true, description: 'The command to execute.' },
+          args: { type: 'array', items: { type: 'string' }, description: 'Optional command arguments.' },
+          cwd: { type: 'string', description: 'Working directory for the command (absolute path).' },
+        },
+        output: {
+          schema: {
+            type: 'object', additionalProperties: false,
+            properties: {
+              output: { type: 'string', required: true },
+              exitCode: { required: true, oneOf: [{ type: 'integer' }, { type: 'null' }] },
+              signal: { required: true, oneOf: [{ type: 'string' }, { type: 'null' }] },
+              timedOut: { type: 'boolean', required: true },
+            },
+          },
+          render: (_args, value) => [{
+            type: 'text',
+            text: value.timedOut
+              ? `timed out after 120s; last output:\n${value.output}`
+              : `exit code: ${value.exitCode ?? 'signal' + (value.signal ?? '')}\n${value.output}`,
+          }],
+        },
+        async execute(args, exec) {
+          const sessionId = sessionIdOf(exec)
+          const handle = await conn.createTerminal({
+            sessionId,
+            command: args.command,
+            ...args.args === undefined || args.args.length === 0 ? {} : { args: args.args },
+            ...args.cwd === undefined ? {} : { cwd: args.cwd },
+          })
+          try {
+            let output = ''
+            let exitStatus
+            const deadline = Date.now() + 120_000
+            while (Date.now() < deadline) {
+              await sleep(300)
+              const chunk = await handle.currentOutput()
+              if (chunk.output) output = chunk.output // cumulative
+              if (chunk.exitStatus !== undefined && chunk.exitStatus !== null) {
+                exitStatus = chunk.exitStatus
+                break
+              }
+            }
+            if (exitStatus === undefined) {
+              await handle.kill().catch(() => {})
+              const final = await handle.currentOutput().catch(() => undefined)
+              if (final?.output) output = final.output
+              return { output, exitCode: null, signal: null, timedOut: true }
+            }
+            return {
+              output,
+              exitCode: exitStatus.exitCode ?? null,
+              signal: exitStatus.signal ?? null,
+              timedOut: false,
+            }
+          } finally {
+            await handle.release().catch(() => {})
+          }
+        },
+      })))
+    }
+    if (clientCaps.elicitation?.form !== undefined && clientCaps.elicitation?.form !== null && userQuestions !== undefined) {
+      // Model-facing question tool (mirrors @deepseek-ai/dsh-tool-ask-user),
+      // rendered in the editor as a form elicitation instead of a web dialog.
+      clientToolDisposers.push(tools.register(defineTool({
+        name: 'ask_user_question',
+        description: 'Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable id that will be echoed in the answer. The questions render as a form inside the editor.',
+        parameters: { questions: {
+          type: 'array',
+          required: true,
+          description: 'Questions to ask the user before continuing.',
+          items: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              id: { type: 'string', required: true, description: 'Stable id for this question; echoed in the answer.' },
+              question: { type: 'string', required: true, description: 'The specific question to ask the user.' },
+              header: { type: 'string', description: 'Optional short heading for the question, such as "Confirm" or "Choose Mode".' },
+              options: {
+                type: 'array',
+                description: 'Optional choices to show the user. If you recommend one, put it first and append "(Recommended)" to that label.',
+                items: {
+                  type: 'object', additionalProperties: true,
+                  properties: {
+                    label: { type: 'string', required: true, description: 'Short user-facing option label.' },
+                    description: { type: 'string', description: 'One sentence explaining the tradeoff or impact.' },
+                  },
+                },
+              },
+              multi_select: { type: 'boolean', description: 'Whether the user may select more than one option. Defaults to false.' },
+            },
+          },
+        } },
+        output: {
+          schema: {
+            type: 'object', additionalProperties: false,
+            properties: { answers: {
+              type: 'array', required: true,
+              items: {
+                type: 'object', additionalProperties: false,
+                properties: {
+                  id: { type: 'string', required: true },
+                  selected: { type: 'array', required: true, items: { type: 'string' } },
+                  custom: { type: 'string' },
+                },
+              },
+            } },
+          },
+          render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+        },
+        async execute(args, exec) {
+          const answers = await userQuestions.ask({
+            questions: args.questions.map((question) => ({
+              id: question.id,
+              question: question.question,
+              ...question.header === undefined ? {} : { header: question.header },
+              ...question.options === undefined ? {} : { options: question.options },
+              ...question.multi_select === undefined ? {} : { multiSelect: question.multi_select },
+            })),
+            ...exec.agent === undefined ? {} : { agent: exec.agent },
+            signal: exec.signal,
+          })
+          return {
+            answers: answers.answers.map((answer) => ({
+              id: answer.id,
+              selected: [...answer.selected],
+              ...answer.custom === undefined ? {} : { custom: answer.custom },
+            })),
+          }
+        },
+      })))
+      // The UI provider that renders those questions as an editor form.
+      clientToolDisposers.push(userQuestions.registerProvider({
+        ask: async (request) => {
+          const record = ownedRecord(request.agent)
+          if (record === undefined) {
+            throw new Error('ask_user_question is only usable inside a bridge-owned session')
+          }
+          const properties = {}
+          const required = []
+          for (const question of request.questions) {
+            required.push(question.id)
+            const labels = (question.options ?? []).map((option) => option.label)
+            if (question.multiSelect === true) {
+              properties[question.id] = {
+                type: 'array',
+                ...labels.length > 0 ? { items: { type: 'string', enum: labels } } : { items: { type: 'string' } },
+                description: question.question,
+              }
+            } else if (labels.length > 0) {
+              properties[question.id] = { type: 'string', enum: labels, description: question.question }
+            } else {
+              properties[question.id] = { type: 'string', description: question.question }
+            }
+          }
+          const response = await conn.unstable_createElicitation({
+            sessionId: record.agent.session.id,
+            mode: 'form',
+            message: request.questions.map((question) => question.question).join('\n'),
+            requestedSchema: { type: 'object', properties, required },
+          })
+          if (response.action !== 'accept') {
+            throw new Error(`the user ${response.action === 'decline' ? 'declined' : 'cancelled'} the question`)
+          }
+          const content = response.content ?? {}
+          return {
+            answers: request.questions.map((question) => {
+              const value = content[question.id]
+              const selected = Array.isArray(value)
+                ? value.filter((entry) => typeof entry === 'string')
+                : typeof value === 'string' ? [value] : []
+              return { id: question.id, selected }
+            }),
+          }
+        },
+      }))
+    }
+  }
+
+  // ── session records + history replay ─────────────────────────────────────
+
+  /** Build the bridge-owned protocol record for a fresh or resumed agent. */
+  function makeRecord(handle) {
+    // Session-local model selection, exactly as the Web api-proxy installs it:
+    // reads fall back to the logged request header, then the default.
+    let picked
+    const selection = {
+      get current() {
+        if (picked !== undefined) return picked
+        const logged = handle.agent.session.requestHeader()?.config
+        if (logged === undefined) return ctx.get('agentDefaultModel')?.currentSelection?.() ?? {}
+        return {
+          provider: logged.provider,
+          model: logged.model,
+          ...logged.reasoningEffort === undefined ? {} : { reasoningEffort: logged.reasoningEffort },
+        }
+      },
+      set current(next) {
+        picked = next
+      },
+      assembled: undefined,
+    }
+    installModelSelection(handle.agent.ctx, selection)
+    return {
+      agent: handle.agent,
+      dispose: () => handle.dispose(),
+      inflight: undefined,
+      messageId: undefined,
+      stepStartedAt: undefined,
+      turnStartedAt: undefined,
+      turnCount: 0,
+      title: undefined,
+      lastActivityAt: undefined,
+      toolStats: { count: 0, totalMs: 0, lastCallAt: undefined, lastName: undefined },
+      buffer: {},
+      contextWindow: undefined,
+      lastUsage: undefined,
+      selection,
+    }
+  }
+
+  /**
+   * Best-effort last known title of a persisted (non-live) session, read from
+   * its stored log's `session/title` events. Bounded: oversized logs are
+   * skipped rather than fully loaded.
+   */
+  async function readStoredTitle(persistence, id) {
+    try {
+      if (persistence?.supportsRawArtifacts !== true) return undefined
+      const raw = await persistence.readRaw(id)
+      if (raw === undefined || raw.content.length > 8 * 1024 * 1024) return undefined
+      let last
+      for (const line of raw.content.split('\n')) {
+        if (line.trim().length === 0) continue
+        try {
+          const record = JSON.parse(line)
+          if (record?.type === 'session/title' && typeof record?.data?.title === 'string') {
+            last = record.data.title
+          }
+        } catch {
+          // Malformed line — skip; titles live on well-formed rows.
+        }
+      }
+      return last
+    } catch {
+      return undefined
+    }
+  }
+
+  /** Publish a session-metadata change (title / last activity) to the client. */
+  function publishSessionInfo(record, info) {
+    notify({
+      sessionId: record.agent.session.id,
+      update: { sessionUpdate: 'session_info_update', ...info },
+    })
+  }
+
+  /** Extract plain text from a dsh message's content blocks (baseline ACP is text-only). */
+  function textFromBlocks(content) {
+    const parts = []
+    for (const block of content ?? []) {
+      if (block?.type === 'text' && typeof block.text === 'string') parts.push(block.text)
+    }
+    return parts.join('\n')
+  }
+
+  /**
+   * Replay a resumed session's conversation to the client as ACP session
+   * notifications. Zed inserts the thread before the load RPC completes, so
+   * these find it. Only the baseline-visible surface is replayed: user and
+   * assistant text chunks plus tool calls/results; everything else (turns,
+   * steps, usage, plan flips, …) is omitted.
+   */
+  async function replayHistory(record) {
+    const events = record.agent.session.events
+    for (const event of events) {
+      try {
+        switch (event.type) {
+          case 'user/message': {
+            // Only direct human prompts (source.kind === 'user') belong in the
+            // editor thread; synthetic injections (system reminders, skill
+            // content, cron notices, …) would clutter it.
+            if (event.data.source?.kind !== 'user') break
+            const text = textFromBlocks(event.data.content)
+            if (text.trim().length === 0) break
+            await notifyNow(record, {
+              sessionUpdate: 'user_message_chunk',
+              messageId: randomUUID(),
+              content: { type: 'text', text },
+            })
+            break
+          }
+          case 'assistant/message': {
+            const text = textFromBlocks(event.data.message.content)
+            if (text.trim().length === 0) break
+            await notifyNow(record, {
+              sessionUpdate: 'agent_message_chunk',
+              messageId: randomUUID(),
+              content: { type: 'text', text },
+            })
+            break
+          }
+          case 'tool/call':
+            await notifyNow(record, {
+              sessionUpdate: 'tool_call',
+              toolCallId: event.data.callId,
+              title: event.data.name,
+              kind: toolKindFor(event.data.name),
+              rawInput: parseToolArguments(event.data.arguments),
+              _meta: {
+                turn: event.data.turn,
+                step: event.data.step,
+                name: event.data.name,
+                argumentsPreview: String(event.data.arguments ?? '').slice(0, 200),
+              },
+            })
+            break
+          case 'tool/result': {
+            const preview = resultPreview(event)
+            const callId = event.data.message?.content?.[0]?.toolCallId ?? event.data.callId
+            await notifyNow(record, {
+              sessionUpdate: 'tool_call_update',
+              toolCallId: callId,
+              status: event.data.error === undefined ? 'completed' : 'error',
+              ...preview === undefined ? {} : { rawOutput: preview },
+              _meta: {
+                turn: event.data.turn,
+                step: event.data.step,
+                name: event.data.name,
+              },
+            })
+            break
+          }
+        }
+      } catch (error) {
+        logger.warn(`acp-enhanced: history replay skipped an event: ${String(error)}`)
+      }
+    }
+  }
+
+  /** Awaiting variant of notify() used by history replay (ordered delivery). */
+  async function notifyNow(record, update) {
+    await conn.sessionUpdate({
+      sessionId: record.agent.session.id,
+      update,
+    }).catch((error) => {
+      logger.warn(`acp-enhanced: session/update failed during history replay: ${String(error)}`)
+    })
+  }
+
+  // ── the Agent face ────────────────────────────────────────────────────────
+
+  const makeAgent = (connection) => {
+    conn = connection
+    return {
+      initialize(params) {
+        clientCaps = params?.clientCapabilities ?? {}
+        syncClientTools()
+        return Promise.resolve({
+          protocolVersion: PROTOCOL_VERSION,
+          agentInfo: { name: 'deepseek-harness-acp-enhanced', version: '0.1.0' },
+          agentCapabilities: {
+            loadSession: true,
+            sessionCapabilities: { list: {}, delete: {} },
+            promptCapabilities: { image: false, audio: false, embeddedContext: false },
+          },
+          authMethods: [],
+        })
+      },
+
+      authenticate() {
+        return Promise.resolve()
+      },
+
+      async newSession(params) {
+        assertOpen()
+        validateSessionParams(params)
+        const sessionId = SessionId(randomUUID())
+        const handle = await agents.create({
+          sessionId,
+          meta: { cwd: params.cwd },
+          agentOptions: {
+            ...config.provider === undefined ? {} : { provider: config.provider },
+            ...config.model === undefined ? {} : { model: config.model },
+          },
+        })
+        if (closed) {
+          await handle.dispose()
+          throw internalError('connection closed during session/new')
+        }
+        const record = makeRecord(handle)
+        sessions.set(sessionId, record)
+        const permission = permissionPresets()
+        return {
+          sessionId,
+          ...permission === undefined ? {} : {
+            modes: {
+              currentModeId: permission.current(handle.agent.session.events),
+              availableModes: permission.names.map((presetName) => {
+                const spec = permission.presets[presetName]
+                return {
+                  id: presetName,
+                  name: spec?.name ?? presetName,
+                  ...spec?.description === undefined ? {} : { description: spec.description },
+                }
+              }),
+            },
+          },
+          configOptions: await buildConfigOptions(record),
+        }
+      },
+
+      async loadSession(params) {
+        assertOpen()
+        if (!isAbsolute(params.cwd)) throw invalidParams(`cwd must be an absolute path: ${params.cwd}`)
+        if (params.additionalDirectories !== undefined && params.additionalDirectories.length > 0) {
+          throw invalidParams('additionalDirectories is not supported')
+        }
+        if (params.mcpServers.length > 0) throw invalidParams('mcpServers is not supported')
+        const sessionId = SessionId(params.sessionId)
+        const live = sessions.get(sessionId)
+        if (live !== undefined) {
+          // Already live on this connection: return its state without replay.
+          const permission = permissionPresets()
+          return {
+            ...permission === undefined ? {} : {
+              modes: {
+                currentModeId: permission.current(live.agent.session.events),
+                availableModes: permission.names.map((presetName) => {
+                  const spec = permission.presets[presetName]
+                  return { id: presetName, name: spec?.name ?? presetName }
+                }),
+              },
+            },
+            configOptions: await buildConfigOptions(live),
+          }
+        }
+        const handle = await agents.resume({
+          resumeSessionId: sessionId,
+          agentOptions: {
+            ...config.provider === undefined ? {} : { provider: config.provider },
+            ...config.model === undefined ? {} : { model: config.model },
+          },
+        })
+        if (closed) {
+          await handle.dispose()
+          throw internalError('connection closed during session/load')
+        }
+        const record = makeRecord(handle)
+        sessions.set(sessionId, record)
+        // Zed inserts the thread before the load RPC completes; replay the
+        // conversation history as notifications so the thread renders.
+        await replayHistory(record)
+        const permission = permissionPresets()
+        return {
+          ...permission === undefined ? {} : {
+            modes: {
+              currentModeId: permission.current(record.agent.session.events),
+              availableModes: permission.names.map((presetName) => {
+                const spec = permission.presets[presetName]
+                return {
+                  id: presetName,
+                  name: spec?.name ?? presetName,
+                  ...spec?.description === undefined ? {} : { description: spec.description },
+                }
+              }),
+            },
+          },
+          configOptions: await buildConfigOptions(record),
+        }
+      },
+
+      async prompt(params) {
+        assertOpen()
+        const record = requireSession(SessionId(params.sessionId))
+        if (record.inflight !== undefined) {
+          throw invalidParams('a prompt is already in flight for this session')
+        }
+        if (promptHasUnsupportedContent(params.prompt)) {
+          throw invalidParams('only text and resource_link prompt content is supported')
+        }
+        const text = acpPromptToText(params.prompt)
+        if (text.trim().length === 0) throw invalidParams('empty prompt')
+        if (ctx.agents.get(record.agent.id) !== record.agent) {
+          throw internalError('prompt was not queued: the agent was disposed outside the bridge')
+        }
+        const message = createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
+        if (process.env.ACP_DEBUG) process.stderr.write(`[acp-debug] followup queued, agent phase=${record.agent.phase?.kind} inboxPending=${record.agent.inbox?.hasPending}\n`)
+        const stopReason = await new Promise((resolve, reject) => {
+          const inflight = {
+            resolve,
+            reject,
+            messageId: message.id,
+            turn: undefined,
+            endReason: undefined,
+          }
+          record.inflight = inflight
+          try {
+            record.agent.followup(message)
+          } catch (error) {
+            record.inflight = undefined
+            const detail = error instanceof Error ? error.message : String(error)
+            throw internalError(`prompt was not queued: ${detail}`)
+          }
+          void record.agent.whenIdle().then(() => {
+            if (record.inflight !== inflight) return
+            record.inflight = undefined
+            const end = inflight.endReason
+            if (end === undefined) {
+              inflight.resolve('cancelled')
+            } else {
+              inflight.resolve(end.kind === 'max-tokens' ? 'end_turn' : turnEndToStopReason(end))
+            }
+          })
+        })
+        return { stopReason }
+      },
+
+      cancel(params) {
+        const record = sessions.get(SessionId(params.sessionId))
+        if (record === undefined) return Promise.resolve()
+        record.agent.cancel({ kind: 'user' })
+        settlePrompt(record, 'cancelled')
+        return Promise.resolve()
+      },
+
+      async setSessionConfigOption(params) {
+        assertOpen()
+        const record = requireSession(SessionId(params.sessionId))
+        // ACP serializes SessionConfigOptionValue FLATTENED into the request
+        // (schema 1.4.0 / JS SDK 0.25.1, what Zed sends): selects arrive as
+        // `value: '<id>'`, booleans as `type: 'boolean', value: true` at the
+        // top level. The SDK already validates this shape, so `params.value`
+        // is a plain string/boolean here. The unwrap below is only a safety
+        // net for hand-rolled streams that send the older nested form.
+        let value = params.value
+        if (typeof value === 'object' && value !== null && !Array.isArray(value) && 'value' in value) {
+          value = value.value
+        }
+        switch (params.configId) {
+          case 'model': {
+            if (typeof value !== 'string') throw invalidParams('model value must be a "provider/model" string')
+            const slash = value.indexOf('/')
+            if (slash <= 0 || slash === value.length - 1) {
+              throw invalidParams('model value must be a "provider/model" string')
+            }
+            const current = record.selection.current
+            await applySelection(record, {
+              provider: value.slice(0, slash),
+              model: value.slice(slash + 1),
+              ...current.reasoningEffort === undefined ? {} : { reasoningEffort: current.reasoningEffort },
+            })
+            break
+          }
+          case 'reasoning_effort': {
+            if (typeof value !== 'string' || value.length === 0) {
+              throw invalidParams('reasoning_effort value must be a non-empty effort id')
+            }
+            const current = record.selection.current
+            await applySelection(record, {
+              provider: current.provider,
+              model: current.model,
+              reasoningEffort: ReasoningEffortId(value),
+            })
+            break
+          }
+          case 'permission_preset': {
+            if (typeof value !== 'string') throw invalidParams('permission_preset value must be a preset name')
+            const permission = permissionPresets()
+            if (permission === undefined) throw internalError('permission presets are not mounted')
+            applyPermissionPreset(record, value, permission)
+            break
+          }
+          case 'plan_mode': {
+            if (typeof value !== 'boolean') throw invalidParams('plan_mode value must be a boolean')
+            const planMode = ctx.get('planMode')
+            if (planMode === undefined) throw internalError('plan mode is not mounted')
+            planMode.set(record.agent, value)
+            break
+          }
+          default:
+            throw invalidParams(`unknown config option "${params.configId}" (available: model, reasoning_effort, permission_preset, plan_mode)`)
+        }
+        const configOptions = await broadcastConfig(record)
+        return { configOptions }
+      },
+
+      async setSessionMode(params) {
+        assertOpen()
+        const record = requireSession(SessionId(params.sessionId))
+        const permission = permissionPresets()
+        if (permission === undefined) throw internalError('session modes are unavailable: permission presets are not mounted')
+        applyPermissionPreset(record, params.modeId, permission)
+        notify({
+          sessionId: record.agent.session.id,
+          update: { sessionUpdate: 'current_mode_update', currentModeId: params.modeId },
+        })
+        await broadcastConfig(record)
+        return {}
+      },
+
+      async listSessions(params) {
+        assertOpen()
+        if (params.cwd !== undefined && params.cwd !== null && !isAbsolute(params.cwd)) {
+          throw invalidParams(`cwd must be an absolute path: ${params.cwd}`)
+        }
+        const cwd = params.cwd ?? undefined
+        const persistence = ctx.get('sessionPersistence')
+        const headers = persistence === undefined ? [] : await persistence.list()
+        const out = []
+        for (const header of headers) {
+          if (cwd !== undefined && header.cwd !== undefined && header.cwd !== cwd) continue
+          const live = sessions.get(header.id)
+          const title = live?.title ?? await readStoredTitle(persistence, header.id)
+          const updatedAtMs = live?.lastActivityAt ?? header.createdAt
+          out.push({
+            sessionId: header.id,
+            cwd: header.cwd ?? cwd ?? process.cwd(),
+            ...title === undefined ? {} : { title },
+            updatedAt: new Date(updatedAtMs).toISOString(),
+          })
+        }
+        out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+        return { sessions: out }
+      },
+
+      async deleteSession(params) {
+        assertOpen()
+        const sessionId = SessionId(params.sessionId)
+        const live = sessions.get(sessionId)
+        if (live !== undefined) {
+          sessions.delete(sessionId)
+          try {
+            await live.dispose()
+          } catch (error) {
+            logger.warn(`acp-enhanced: failed to dispose live session ${sessionId}: ${String(error)}`)
+          }
+        }
+        const persistence = ctx.get('sessionPersistence')
+        if (persistence !== undefined) {
+          try {
+            const headers = await persistence.list()
+            const header = headers.find((entry) => entry.id === sessionId)
+            if (header !== undefined) {
+              const location = persistence.locate(header)
+              // The JSONL backend owns one directory per session; remove the
+              // whole directory (log + any session-local artifacts). No official
+              // delete API exists on the persistence surface, so this removes the
+              // backend artifact directly.
+              if (location?.path !== undefined) {
+                await rm(dirname(location.path), { recursive: true, force: true })
+              }
+            }
+          } catch (error) {
+            logger.warn(`acp-enhanced: failed to remove persisted session ${sessionId}: ${String(error)}`)
+          }
+        }
+        return {}
+      },
+    }
+  }
+
+  const stream = config.stream ?? ndJsonStream(
+    Writable.toWeb(process.stdout),
+    Readable.toWeb(process.stdin),
+  )
+  conn = new AgentSideConnection(makeAgent, stream)
+
+  let quiescing
+  const quiesce = () => {
+    if (quiescing !== undefined) return quiescing
+    closed = true
+    const records = [...sessions.values()]
+    sessions.clear()
+    for (const record of records) {
+      record.agent.cancel({ kind: 'user' })
+      settlePrompt(record, 'cancelled')
+    }
+    quiescing = (async () => {
+      const subagents = ctx.get('subagents')
+      if (subagents?.drainContinuableDescendants !== undefined) {
+        try {
+          await subagents.drainContinuableDescendants(records.map((record) => record.agent))
+        } catch (error) {
+          logger.warn(`acp-enhanced: continuable subagent teardown failed: ${String(error)}`)
+        }
+      }
+      const disposals = await Promise.allSettled(records.map((record) => record.dispose()))
+      const failures = []
+      for (const result of disposals) {
+        if (result.status === 'rejected') failures.push(result.reason)
+      }
+      if (failures.length > 0) {
+        const detail = failures.map((failure) => errorChain(failure)).join('; ')
+        throw new AggregateError(failures, `ACP agent teardown failed for ${failures.length} session(s): ${detail}`)
+      }
+    })()
+    return quiescing
+  }
+
+  void conn.closed
+    .catch((error) => {
+      logger.warn(`acp-enhanced: connection closed with an error: ${String(error)}`)
+    })
+    .then(quiesce)
+    .catch((error) => {
+      logger.warn(`acp-enhanced: connection-close teardown failed: ${String(error)}`)
+    })
+
+  ctx.effect(() => quiesce, 'acp-enhanced.connection')
+}
+
+/** Reject session features outside the automation contract. */
+function validateSessionParams(params) {
+  if (!isAbsolute(params.cwd)) throw invalidParams(`cwd must be an absolute path: ${params.cwd}`)
+  if (params.additionalDirectories !== undefined && params.additionalDirectories.length > 0) {
+    throw invalidParams('additionalDirectories is not supported')
+  }
+  if (params.mcpServers.length > 0) throw invalidParams('mcpServers is not supported')
+}