export const name = 'acp' // 插件名：cordis 组合图里的唯一标识/** The bridge creates and owns agents; every other concern is carried by the agent composition. */ // 注释：桥接层只负责"创建并拥有 agent"，其余全部交给 agent 自身的组合export const inject = ['agents'] // 唯一的注入点——只需要 agent 工厂，其他服务一律不碰/** Preserve invalid-parameter detail in the SDK wire error message. */ // 注释：保留参数错误的细节到 wire 错误消息里function invalidParams(detail: string): RequestError { // 构造 JSON-RPC -32602（invalid params）错误，detail 会透传给客户端  return RequestError.invalidParams(undefined, detail) // 用 SDK 的工厂方法而不是手拼对象——保证错误码与形状符合协议} // 函数结束：参数类问题统一走这里，客户端能拿到可读原因/** Preserve failed-turn detail; plain handler errors become a generic wire internal error. */ // 注释：保留失败 turn 的细节；普通 handler 异常会变成泛化的内部错误function internalError(detail: string): RequestError { // 构造 JSON-RPC -32603（internal error）错误，detail 同样透传  return RequestError.internalError(undefined, detail) // 与 invalidParams 对称：服务端自身故障走这个码} // 函数结束：两个助手把"谁的错"编码进 wire 状态码/** Plugin config: the provider/model selection used for each ACP-created agent. */ // 注释：插件配置——每个 ACP 创建的 agent 用哪个 provider/modelexport interface AcpConfig { // 配置接口：两个字段都可选，方便由别的监听器提供目标  /** Provider route for created agents. */ // provider 路由（如 deepseek-chat）  provider?: string // 可选：不配就沿用 agent 组合的默认路由  /** Model name for created agents. */ // 模型名  model?: string // 可选：不配就沿用默认模型} // 接口结束：demo 应用会同时要求两者必填（见 acp-demo README）export const Config: Schema<AcpConfig> = Schema.object({ // 用 schemastery 声明配置 schema，Loader 据此校验 cordis.yml  provider: Schema.string(), // provider 字段：字符串  model: Schema.string(), // model 字段：字符串) // schema 结束

/** Per-session protocol state. */ // 注释：每个会话的协议状态——桥接层为它创建的 agent 记的账interface SessionRecord { // 一条记录 = 一个 ACP session 的全部私有状态  agent: Agent // 本会话拥有的那个 harness agent（对象引用，后面要做同一性校验）  /** Exact owned-agent disposer; resolves after registry, loop, and session teardown. */ // 注释：精确的拥有者拆除器；registry/loop/session 全部拆完才 resolve  dispose: () => Promise<void> // 闭包住 agents.create() 返回的 handle.dispose——只有桥接层能拆它  /** In-flight prompt and its captured turn number for exact settlement. */ // 注释：在途 prompt + 捕获到的轮次号，用于精确结算  inflight: { // 单槽位设计：同一会话同时只允许一个 prompt（prompt() 里会检查）    resolve: (reason: StopReason) => void // 正常结算入口：带 ACP stop reason    reject: (error: Error) => void // 异常结算入口：turn 失败时立即拒绝    messageId: string // 入队消息的 id——用来和 agent/inbox/claimed 事件做关联    turn: number | undefined // 该消息实际触发的轮次号；undefined = 还没被认领    /** The correlated turn's ending, set at turn/end and settled at whole-agent idle. */ // 注释：关联轮次的结束原因，turn/end 时记下、整个 agent idle 时才结算    endReason: TurnEndReason | undefined // 先记后结——因为 idle 前还可能有 steering/注入的后续轮次} | undefined // undefined = 当前没有在途 prompt（会话空闲）

export function apply(ctx: Context, config: AcpConfig): void { // 插件入口：挂载自动化 ACP 服务器  // ACP handlers execute outside this plugin's injection scope, so capture the  // injected service during apply rather than reading it lazily in a callback.  const agents = ctx.agents // 在 apply 阶段就把注入的 agent 工厂抓进闭包——handler 执行时已不在注入作用域内，懒读会拿不到  const logger = ctx.logger // 日志器同样提前捕获  const sessions = new Map<SessionId, SessionRecord>() // 会话表：ACP sessionId → 本桥接层拥有的记录  let closed = false // 拆除开关：一旦置位，newSession/prompt 全部拒绝（assertOpen）  let conn: AgentSideConnection // ACP SDK 连接句柄；makeAgent 里赋值，notify/权限请求要用它回写客户端  /** Return the bridge-owned record for an agent, rejecting same-id impostors. */ // 注释：按 agent 反查记录，同时拒绝"同 id 冒名者"  const ownedRecord = (agent: Agent): SessionRecord | undefined => { // 事件里带的是 agent 对象——必须确认它真是本桥接层创建的那个    const record = sessions.get(agent.session.id) // 先按 session id 查表    return record?.agent === agent ? record : undefined // 再比对对象同一性：id 相同但对象不同（比如别的入口创建的）→ 视为不存在} // 函数结束：这是"桥接层只响应自己拥有的会话"的守门员  const assertOpen = (): void => { // 拆除检查：closed 之后一切新工作都拒绝    if (closed) throw internalError('the ACP bridge has been disposed') // 抛 wire 内部错误，客户端能明确知道桥已死} // 函数结束  const requireSession = (sessionId: SessionId): SessionRecord => { // prompt/cancel 的会话查找：找不到就是参数错    const record = sessions.get(sessionId) // 查表    if (record === undefined) throw invalidParams(`unknown session: ${sessionId}`) // 未知 id → -32602，把 id 带回去方便客户端排查    return record // 命中则返回记录} // 函数结束

// Emit only committed assistant text. Raw chunks, reasoning, tools, plans,// titles, and retry markers are presentation or trace data and stay off the// automation wire.ctx.on('session/event', (session, event: SessionEvent) => { // 监听会话日志事件流——这是 harness 的权威事件源（第7讲分析过）  const record = sessions.get(session.header.id) // 按事件里的 session id 查本桥接层的记录  if (record === undefined || record.agent.session !== session) return // 不是自己拥有的会话 → 直接忽略，绝不转发别人的流量  try { // 进入"文本转发"分支；finally 里还要做结算检查    if (event.type === 'assistant/message') { // 只关心已提交的 assistant 消息（committed），delta-chunk 等中间态不处理      for (const block of event.data.message.content) { // 遍历消息内容块：text / image / tool_use…        if (block.type === 'text' && block.text.length > 0) { // 非空文本块 → 原样上 wire          notify({ // 发一条 session/update 通知（notify 内部吞掉传输错误，见下）            sessionId: record.agent.session.id, // 带上 ACP 会话 id            update: { // 更新载荷              sessionUpdate: 'agent_message_chunk', // ACP 词汇：assistant 消息的一个片段              content: { type: 'text', text: block.text }, // 文本内容原样转发——不做任何改写            }, // 载荷结束          }) // notify 调用结束} else if (block.type === 'image') { // 图片块：ACP 基线不支持内联图，降级成占位文本          notify({ // 同样走 agent_message_chunk            sessionId: record.agent.session.id, // 会话 id            update: { // 载荷              sessionUpdate: 'agent_message_chunk', // 片段类型不变              content: { type: 'text', text: `[image attachment ${block.attachment.attachmentId}]` }, // 渲染成 [image attachment <id>]——客户端至少知道"这里有过一张图"            }, // 载荷结束          }) // notify 调用结束} // else-if 分支结束：其他块类型（tool_use/thinking…）一律不上 wire} // for 循环结束} // if (assistant/message) 结束} finally { // 无论转发成功与否，都要做结算检查——错误不能吞掉 turn/end 信号      const inflight = record.inflight // 取当前在途槽位（可能没有）      if (inflight !== undefined && event.type === 'turn/end' && inflight.turn === event.data.turn) { // 三条件：有在途 prompt + 这是 turn/end + 轮次号正是我们关联的那个        if (event.data.reason.kind === 'error') { // 模型/工具失败 → 立即拒绝，不等 idle          record.inflight = undefined // 先清槽位——防止 whenIdle 分支再结算一次（双结算防护）          rejectFromError(inflight, event.data.reason) // 用错误详情 reject prompt promise} else { // 非 error 结束 → 只记录，不结算          inflight.endReason = event.data.reason // 记下原因；真正的结算等整个 agent idle（第六节）} // if/else 结束} // turn/end 检查结束} // finally 结束}) // ctx.on 注册结束

async prompt(params: PromptRequest): Promise<PromptResponse> { // ACP 核心方法：提交一条 prompt，等整个 agent idle 后返回 stopReason        assertOpen() // 闸0：桥接层已拆除 → 直接内部错误（第五节讲过）        const record = requireSession(SessionId(params.sessionId)) // 闸1：会话必须存在且归本桥接层所有，否则 -32602        if (record.inflight !== undefined) { // 闸2：单槽位——同一会话已有在途 prompt          throw invalidParams('a prompt is already in flight for this session') // 拒绝并发委托：stopReason 归属必须唯一可解释} // 闸2结束        if (promptHasUnsupportedContent(params.prompt)) { // 闸3：内容类型检查（codec.ts，第八节细讲）          throw invalidParams('only text and resource_link prompt content is supported') // 超出基线（image/audio/embedded）→ 拒绝而不是静默丢弃} // 闸3结束        const text = acpPromptToText(params.prompt) // 把 ACP 内容块拍平成纯文本：text 原样拼接，resource_link 渲染成方括号引用        if (text.trim().length === 0) throw invalidParams('empty prompt') // 闸4：空 prompt 拒绝——避免给 agent 喂一条无意义消息        // Not driving a retired agent is this bridge's contract: an        // agent-loop-only reload disposes the loop's agents while the bridge        // record survives, so validate the record against the live registry        // before sending — a disposed machine would accept the item silently.        if (ctx.agents.get(record.agent.id) !== record.agent) { // 闸5（最隐蔽）：拿记录里的 agent 去活注册表里对——对象必须还是同一个          throw internalError('prompt was not queued: the agent was disposed outside the bridge') // 若 agent-loop 重载已把旧 agent 拆掉而桥接层记录还在，disposed 的机器会"静默收下"消息——这里 fail loud} // 闸5结束：五道闸全过才允许入队        const message = createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } }) // 拍平后的文本变成一条标准用户消息（第12讲分析过的 LLM 消息结构）        const stopReason = await new Promise<StopReason>((resolve, reject) => { // prompt 的"结算 promise"：谁 resolve/reject，stopReason 就是什么          // Arm the slot before followup() so a listener-driven synchronous          // turn cannot slip past correlation;          const inflight: NonNullable<SessionRecord['inflight']> = { // 构造在途槽位：resolve/reject 直接闭包住外层 promise            resolve, reject, messageId: message.id, turn: undefined, endReason: undefined, // messageId 用于 claimed 关联；turn/endReason 先留空} // 槽位对象结束          record.inflight = inflight // 关键顺序：先占槽再 followup()——同步触发的轮次不可能绕过关联检查          try { // 入队尝试            record.agent.followup(message) // 把用户消息塞进 agent 收件箱（第9讲分析过的 agent loop 入口）} catch (error: unknown) { // followup() 同步抛错（如非法输入）→ 必须释放槽位，否则会话永远"在途"            record.inflight = undefined // 清槽            const detail = error instanceof Error ? error.message : String(error) // 提取可读错误详情            throw internalError(`prompt was not queued: ${detail}`) // 抛给外层 → prompt() reject，客户端拿到原因} // catch 结束

          // Settlement waits for whole-agent idle: a correlated turn/end arms          // `endReason`, while a turnless slot (admission discarded the          // prompt) stays cancelled. Other producers may run further turns          // before quiescence; the prompt settles only when the agent stops.          void record.agent.whenIdle().then(() => { // 等整个 agent 进入空闲（不是单轮结束！）——idle 前还可能有 steering/注入的后续轮次参与本次委托            if (record.inflight !== inflight) return // 槽位已被别人结算过（error 路径/cancel/quiesce）→ 幂等防护，绝不二次 resolve            record.inflight = undefined // 清槽：会话回到空闲态            const end = inflight.endReason // 取关联轮次记下的结束原因（可能没有）            if (end === undefined) { // 没有任何关联轮次 → 准入阶段就把 prompt 丢了（admission discarded）              inflight.resolve('cancelled') // 结算为 cancelled：客户端知道"没跑"} else { // 有关联轮次的结束原因              // Token-limit and other non-terminal endings are not prompt-level              // stop reasons (see README); only normal quiescence reports end_turn.              inflight.resolve(end.kind === 'max-tokens' ? 'end_turn' : turnEndToStopReason(end)) // max-tokens 特判成 end_turn（token 上限不是"提示词级停止原因"）；其余走 codec 映射} // if/else 结束          }) // whenIdle 链结束——注意是 void：结算完全由事件驱动，prompt() 只 await 外层 promise        }) // new Promise 构造器结束        return { stopReason } // ACP 要求每个 prompt 响应都带 stopReason（end_turn/cancelled/max_tokens/refusal…）} // prompt() 方法结束

// Permission requests are a machine policy channel for ACP clients such as// dsh-subagent-acp. The bridge offers one-shot choices only and never infers a// durable grant from an unknown client response.ctx.on('approval/request', (request, next) => { // 挂进审批瀑布：本桥接层是其中一级决策者（next() = 交给下一级）    const record = ownedRecord(request.agent) // 守门员再出场：只处理自己拥有的 agent 的审批请求    if (record === undefined || request.callId === undefined) return next() // 不是我的会话、或没有工具调用 id → 放行给瀑布下一级，不越权决策    return conn.requestPermission({ // 反向 RPC：向 ACP 客户端发起 session/request_permission（这是少数"服务端→客户端"的请求）      sessionId: record.agent.session.id, // 告诉客户端是哪个会话在要权限      toolCall: { toolCallId: request.callId }, // 带上工具调用 id——客户端可以据此做策略匹配      options: [ // 只给两个一次性选项：刻意不提供 allow_always（持久授权）        { optionId: 'allow-once', name: 'Allow once', kind: 'allow_once' }, // 允许这一次        { optionId: 'reject-once', name: 'Reject', kind: 'reject_once' }, // 拒绝这一次      ], // options 结束    }).then(({ outcome }) => { // 客户端回答后，把 ACP 词汇翻译回 harness 审批词汇      if (outcome.outcome === 'cancelled') return 'cancelled' // 客户端没选（超时/断开）→ cancelled：工具按取消处理      return outcome.optionId === 'allow-once' ? 'allowed-once' : 'rejected' // allow-once → allowed-once；其余一律 rejected——fail closed    }) // then 链结束：返回值交还给审批瀑布继续流转} // ctx.on 注册结束

requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse> { // 客户端侧的权限回答器：由 spawn 配置里的 permission 策略驱动      // Auto-answer by the configured policy. `allow` selects the first option      // whose kind is `allow_once` or `allow_always`; if the child offered none (or we      // reject), answer `cancelled` so the child does not proceed.      if (spec.permission === 'allow') { // 策略为 allow → 在子进程给的选项里找第一个"允许类"        const allow = params.options.find(o => o.kind === 'allow_once' || o.kind === 'allow_always') // 按 kind 匹配（不是 optionId）——对服务端措辞变化免疫        if (allow !== undefined) { // 找到了 → 选它          return Promise.resolve({ outcome: { outcome: 'selected', optionId: allow.optionId } }) // 回传 selected + optionId，子进程侧翻译成 allowed-once} // 没找到允许类选项 → 落到下面的 cancelled} // if (allow) 结束：策略为 reject 时直接跳过整个分支      return Promise.resolve({ outcome: { outcome: 'cancelled' } }) // 兜底一律 cancelled——子进程不会"默认放行"} // requestPermission 结束

export function turnEndToStopReason(reason: TurnEndReason): StopReason { // 把 harness 轮次结束原因映射到 ACP 终态词汇  switch (reason.kind) { // 按 kind 分支——TurnEndReason 是封闭联合，每个成员都要有去处    case 'completed': // 正常完成      return 'end_turn' // → ACP 的"轮次结束"    case 'max-tokens': // token 上限      return 'max_tokens' // → ACP 同名概念（注意：prompt() 里会特判成 end_turn，见第五节）    // `cancelled` is reserved for explicit client cancellation (`session/cancel`)    // and disposal, both settled out of band; a turn aborted by a hook or    // another owner is ordinary quiescence and reports `end_turn`. // 注释：cancelled 是保留字，只给显式取消/拆除（带外结算）；hook 中止算普通停稳    case 'aborted': // 被 hook 或其他拥有者中止      return 'end_turn' // → 对客户端就是"agent 停了"，不占用 cancelled 语义    case 'interrupted': // 被打断（如用户中断）      return 'cancelled' // → 这是 harness 侧最接近"取消"的终态    case 'blocked': // 被策略拦截    case 'error': // 出错（prompt() 里 error 走 reject 路径，这里是兜底映射）      return 'end_turn' // → 保守映射：不向客户端谎报成功细节    /* v8 ignore next 2 -- TurnEndReason is closed and every member is handled above */ // 覆盖率豁免：封闭联合已全部处理    default: // 防御性兜底（理论上不可达）      return 'end_turn' // → 未知终态按"停稳"上报，绝不抛异常打断结算链} // switch 结束

export function acpPromptToText(prompt: readonly AcpContentBlock[]): string { // 把 ACP prompt 的基线内容块拍平成纯文本  return prompt.flatMap((block): string[] => { // flatMap：每个块展开成 0..n 段文本，最后拼接——保持 wire 顺序    switch (block.type) { // 按块类型分支      case 'text': // 文本块        return [block.text] // → 原样保留（单元素数组）      case 'resource_link': // 资源链接：ACP 基线要求所有 agent 必须接受它        return [`\n[resource_link name=${JSON.stringify(block.name)} uri=${JSON.stringify(block.uri)}]\n`] // → 渲染成显式方括号引用——客户端可以"指文件"，桥接层不会悄悄丢掉这个上下文（模型可用自己的工具打开它）      default: // 其他类型（image/audio/embedded resource…）        return [] // → 展开为空：但注意 prompt() 里会先被 promptHasUnsupportedContent 拒绝，这里只是双保险} // switch 结束  }).join('') // 所有片段按序拼接成最终文本} // acpPromptToText 结束export function promptHasUnsupportedContent(prompt: readonly AcpContentBlock[]): boolean { // 检查 prompt 是否携带超出 ACP 基线的内容  return prompt.some(block => block.type !== 'text' && block.type !== 'resource_link') // 只要有一个块不是 text/resource_link → true：image/audio/embedded 是可选能力，本桥接层没公布（initialize 里 image:false），所以拒绝而不是静默丢弃} // promptHasUnsupportedContent 结束

  let quiescing: Promise<void> | undefined // 记忆化槽：并发触发（断开 + context dispose）只跑一次拆除  const quiesce = (): Promise<void> => { // 拆除入口：返回同一个 promise，调用方都能 await 到最终结果    if (quiescing !== undefined) return quiescing // 已在拆 → 直接复用（幂等）    closed = true // 第一步：先关门——newSession/prompt 立刻开始拒绝（assertOpen/requireSession 都会炸）    const records = [...sessions.values()] // 快照当前所有会话记录    sessions.clear() // 清空表：后续事件路由查不到记录 → 自动静默，不再转发任何 wire 流量    // Stop the bridge's own work before any await: a descendant drain can block    // on persistence or scoped cleanup, and the top-level agents must not keep    // running model and tool calls for its whole duration.    for (const record of records) { // 第二步：在任何 await 之前，同步停掉所有顶层 agent      record.agent.cancel({ kind: 'user' }) // cancel 每个 agent——拆除期间不允许再跑模型调用和工具（drain 可能阻塞在持久化上）      settlePrompt(record, 'cancelled') // 结算所有在途 prompt 为 cancelled：客户端立刻拿到结果，不用等拆除完成} // for 结束：此刻桥接层已"静默"    quiescing = (async () => { // 第三步：异步拆除主体（记忆化）      // Continuable subagents outlive the turn that started them, and their      // Activations own descendant teardown. Drain only these sessions' forests      // child-first BEFORE disposing the top-level agents,      const subagents = ctx.get('subagents') as ContinuableDrain | undefined // 结构化读取子代理服务的唯一拆除方法（第51-57行定义的接口）——本包因此不依赖 subagent 包；服务不存在 = 没有可继续后代      if (subagents !== undefined) { // 有 → drain 这些会话森林里的可继续后代        try { // drain 可能失败（持久化阻塞等），不能炸掉整个拆除          await subagents.drainContinuableDescendants(records.map(record => record.agent)) // 关键顺序：child-first 拆完所有后代，再动顶层 agent——否则会有后代还握着"主人已释放的运行时"} catch (error: unknown) { // drain 失败 → 降级为警告          logger.warn(`acp: continuable subagent teardown failed: ${String(error)}`) // 记录后继续：顶层拆除仍要执行，不能因为后代清理失败就泄漏顶层 agent} // try/catch 结束} // if (subagents) 结束      const disposals = await Promise.allSettled(records.map(record => record.dispose())) // 第四步：并行释放所有顶层 agent handle（registry/loop/session 全拆）      const failures: unknown[] = [] // 收集失败项      for (const result of disposals) { // 遍历 allSettled 结果        if (result.status === 'rejected') failures.push(result.reason as unknown) // rejected → 记入失败列表（fulfilled 的跳过）} // for 结束      if (failures.length > 0) { // 有拆除失败 → 必须上报，不能静默吞掉        const detail = failures.map(failure => errorChain(failure)).join('; ') // 把每个失败的完整错误链（含嵌套 cause）拼进 message——因为生产消费者用 String() 渲染 AggregateError 时只显示 message        throw new AggregateError( // 聚合抛出：调用方（context dispose 链）能看到"几个会话拆失败 + 各自原因"          failures, // 原始错误对象列表          `ACP agent teardown failed for ${failures.length} session(s): ${detail}`, // message 里内嵌全部诊断) // AggregateError 构造结束} // if (failures) 结束：全成功则静默返回    })() // async IIFE 结束，赋给 quiescing    return quiescing // 返回拆除 promise} // quiesce 函数结束

export function acpStopReason(reason: StopReason): SubagentStopReason { // 客户端侧反向映射：ACP 终态 → harness 子代理停止原因  switch (reason) { // ACP StopReason 是封闭 wire 联合，逐成员处理    case 'end_turn': // 正常结束      return 'completed' // → 子代理任务完成    case 'max_tokens': // token 上限      return 'max-tokens' // → harness 同名概念    case 'refusal': // 模型拒绝      return 'refusal' // → harness 同名概念    case 'cancelled': // 被取消（服务端第五节的带外结算路径）      return 'aborted' // → harness 的"中止"    // `max_turn_requests` (the child hit its turn-request budget) has no direct    // harness equivalent and means the task did NOT finish cleanly — surface it    // as a generic failure so the consumer maps it to an isError result rather    // than reporting a partial answer as success.    case 'max_turn_requests': // 子进程用完了轮次预算——任务没干净完成，但 harness 没有对应终态      return 'error' // → 故意映射成 error：消费者会把它当 isError 结果，而不是把"半成品答案"报成功（fail loud）} // case 结束    // ACP StopReason is a closed wire union, but a future SDK could add a    // variant; treat an unknown terminal reason as a failure (never silently 'completed').    default: // 未来 SDK 新增的未知终态      return 'error' // → 一律按失败处理——绝不静默报 completed（协议演化的安全网）} // switch 结束

prompt 路径（session/prompt → stopReason）

▼

▼

▼

▼

🔹 拆除路径：conn.closed / ctx.effect → quiesce()：关门 → cancel+settlePrompt('cancelled') → drainContinuableDescendants（child-first）→ Promise.allSettled(dispose) → AggregateError 上报