deepseek-harness/missions/tasks/20260719-1902-apiproxy-api-design/core-coverage.md

core 能力面 × 契约 v1.3 覆盖度盘点

2026-07-19 起盘（分批落盘中）。方法：逐包读 core 源码 types/service 面（file:line 为证），对照 design.md v1.3 标注四态：已覆盖 / 有意不做（引拍板）/ 接缝已留（说在哪）/ 漏判（需新裁决，汇总见文末清单）。 背景：rpc-compare 发现契约漏 subagent 谱系，根因是当初只按 UI 需求反查 core、未做系统盘点；本文件补这道工序。

1. session 域（packages/core/session）

1.1 SessionEventMap 全类型表（types.ts:180-252）

事件	core 事实	契约状态
turn/start / turn/end	types.ts:187/193，turn 边界 + TurnTrigger/TurnEndReason（merge-extensible，types.ts:79-124）	已覆盖——mux session/event + history 纯透传（design §3.3 透传纪律）
step/start / step/end	types.ts:195/197	已覆盖（同上透传）
user/message	types.ts:199	已覆盖（透传；client fold 消费）
prompt/blocked	types.ts:204，veto 的 durable 记录	已覆盖（透传）。UI 是否渲染是 client fold 决策，不是契约缺口
context/message	types.ts:212-217，含 meta（模型不可见 durable JSON）	已覆盖（透传）
assistant/chunk	types.ts:219，token 级	已覆盖——「token 流即事件流」（design §3.3）
assistant/message	types.ts:226，含 usage?: TokenUsage	已覆盖（透传）。usage/token 统计随之免费到达 client，无需独立统计接口（§7 LLM 层回引此行）
tool/call / tool/result	types.ts:232/242；result 带 meta?: unknown（tool 私有 presentation 载荷）	已覆盖（透传）；render intent（presentCall/presentResult）有意不做——design §3.3 tool presentation 拍板「先透传，additive 附件帧留座」
steering/message	types.ts:244	已覆盖（透传）
todo/write	types.ts:246，全量快照、last-write-wins、log-only	已覆盖（透传）；client fold 照 last-write-wins 折即可，无需独立 todo 接口（§6 回引此行）
request/header	types.ts:251，EpochHeader 快照（config/system/tools/messagePrefix）	已覆盖（透传）。UI 可从中读 provider/model 现值变化
merge-extensible 扩展键	types.ts:180 map 声明	已覆盖——design §3.3：client fold 对未知 type documented-default，schema 留「合法信封+未知类型」分支

1.2 Session/SessionStore 服务面（index.ts）

能力	core 事实	契约状态
session/created / session/disposed 事件	index.ts:47/57	已覆盖——HostFrame host/session-added/removed（design §3.3）
session/event 追加流	index.ts:69	已覆盖——mux 的源
session/flush 检查点	index.ts:79	有意不做（不对客暴露）——durability 是 host 内部事务，client 只见已落地事件
store.get/list	index.ts:818/826（live only）	已覆盖——sessions.list（live+冷合并的持久化清单，v1 mtime 三字段拍板）
SessionHeader.parentSession + seedLength	types.ts:47/52；fork 时写入 index.ts:854-855	漏判 →【L1】——谱系在 core 持久化面存在，契约 SessionSummary/HostFrame 均未携带
SessionHeader.cwd / createdAt	types.ts:43/45	漏判 →【L2】——create 收 cwd 入参但 list/describe 均不回吐；createdAt 被 v1「mtime 即 updatedAt」拍板部分覆盖但非同一语义
SessionStore.fork()	index.ts:843-857；SessionForkSource index.ts:546；错误码 SessionForkErrorCode index.ts:556-562（turn/end 边界约束 :890-895）	漏判 →【L3】——core 有完整 fork 原语（opencode 也有 POST /session/:id/fork 对照），契约无 session.fork 方法
repair（interruptedTurnClosers）	index.ts:25 导出；repair.ts；persistence 加载时闭合 crash 孤儿 turn（TurnEndReason interrupted，types.ts:120）	已覆盖（间接）——修复产物就是 turn/end interrupted 事件，随 history 透传到达；修复动作本身是 host 内部行为，无需接口
surface（foldSurface/SurfaceOp/replace）	index.ts:26-27 导出；types.ts:262-309（SurfaceOp append/replace，compaction 用）	已覆盖——design §5「优先复用 core foldSurface」；replace 语义随事件透传，client fold 天然处理 compaction
deriveMessages/requestHeader 折叠	index.ts:469/432	有意不做（server 不代折）——「历史=事件重放，client 单一 fold」拍板（README 拍板表）

2. agent 域（packages/core/agent）

能力	core 事实	契约状态
agent/created / agent/disposed	types.ts:147/156（注册/注销时 emit）	已覆盖——HostFrame added/removed 的 agent 侧对应（HostFrame 语义=「session 出现/消失」，v1 agent 与 session 同生命周期）
agent/status（idle⇄running→disposed）	types.ts:165；AgentStatus types.ts:47	已覆盖——HostFrame host/session-status running 布尔。三态压两态是拍板（冷 session 拍板：attach 不暴露，disposed 即 removed）
agent/queued（入箱通知）	types.ts:175	有意不做——prompt() 返回 accepted 即达意；入箱细节属 host 内部（CQRS：渲染靠 session 事件）
send/steer/cancel 原语	types.ts:103/110/127	已覆盖——prompt(mode: queue/steer)、cancel 1:1 映射（design §3.1）
inject（注入上下文不跑模型）	types.ts:119	漏判 →【L4】——core 第三条输入原语，契约只映射了 send/steer；UI 场景（如「贴文件给 agent 但不触发回复」）v1 是否需要待裁决
whenIdle()	types.ts:130	有意不做——client 由 host/session-status 事件驱动，不需要 promise 面
AgentRegistry.create/resume（CreateAgentOptions：sessionId/meta{cwd,parentSession,seedLength}/seed/agentOptions/setup）	index.ts:44-90、:352/:371	已覆盖（部分）——sessions.create 走此路（cwd 已在契约入参）；meta.parentSession/seed 是 fork/spawn 用的，与【L3】同源，client 侧 v1 不透出
AgentRegistry.get/list/roots/isOwnedBy	index.ts:530/550/560+/543	list/get 已覆盖（sessions.list + running）；roots()/isOwnedBy（运行时归属树）漏判 →【L1】共同体——UI 要画 subagent 树需要谱系，见 L1 处置提案
initiator scope（withInitiator/initiator()）	index.ts:288/:258；RFC 2026-07-15-agent-initiator-scope	有意不做——进程内 AsyncLocalStorage 机制，本质不可序列化，不属 wire 契约；UI 需要的「谁创建了谁」由持久谱系（L1）承担
扩展 seam 事件（pre-step/prompt-submit/request/session-prefix/step-result/post-step/request-error/turn-continuation/turn-stop、agent/error）	types.ts:204-311	有意不做（对客）——插件扩展 seam，是 host 进程内 waterfall/serial 钩子；durable 后果已进 session log 透传（如 prompt/blocked、turn/end error）。agent/error 的无 turn 位置失败 →【L5】边缘：live-only 诊断无 session 事件时 client 不可见，待裁决是否要 stream/error 级 host 通知

3. subagent 包组（packages/subagent/*：spawn/fork/inprocess/subprocess/acp + tool-subagent）

能力	core 事实	契约状态
子 agent 创建（spawn=白纸 / fork=继承 turn 前缀）	subagent/src/types.ts:52-101（StartRequest：parent 必填、读 parent.session.header 拿 cwd+stamp parentSession，:56-61）；SubagentRun.id=子 session id、parentSession 记录 parent（:148-154）	对 UI 的可观测面 = 普通 session：子 agent 就是 registry 里一个 live agent + store 里一个 session，mux/hostEvents 天然看得见。缺的只是谱系标注 →【L1】（host/session-added 无 parentSessionId，UI 无法区分「用户开的」和「agent spawn 的」）
运行时 run 面（result promise/dispose/sendMessage?/resume?）	types.ts:148-185	有意不做——run 生命周期属 parent agent 的工具调用（tool/call task → tool/result），已随事件透传；client 不直接操纵子 run
stopReason / structured output	types.ts:109-141	已覆盖（间接）——结果进 parent 的 tool/result 透传
ACP/subprocess 远程子 agent	subagent-acp、subagent-subprocess	同上——远程 run 无本地 session；parent 侧 tool 事件已覆盖其可观测面；v1 不做远程子会话浏览（不做清单精神，未明文 → 盘点顺手补进 §6 不做清单措辞即可，不算漏判）

4. ctx.tasks 后台任务（packages/tasks/tasks）

能力	core 事实	契约状态
tasks.list/get/wait（TaskSnapshot：kind/label/status/detail/output/startedAt/finishedAt）	index.ts:153/167/226/326	漏判 →【L6】——运行时全局后台任务注册表（bash 后台、subagent run 等挂在这），UI「后台任务列表」是常见诉求；但 v1 UI 范围未含此面板，处置建议偏「留接缝」
onTaskDone 完成通知	index.ts:283	同【L6】——若做任务面板需 HostFrame 或独立流；不做面板则无需
任务归属（owner: Agent、session-scoped 授权）	index.ts:44-48（TrackedTask.owner）、list(caller) 过滤	同【L6】附注：core 已有按 agent 过滤语义，接口若做可直接映射

5. 审批与问答（packages/ui/user-approval、user-interaction）

能力	core 事实	契约状态
approval/request waterfall（待决问题推给 answerer 链）	user-approval/src/index.ts:23-32；ApprovalOutcome :91（allowed-once/rejected/cancelled/unavailable，fail-closed）	有意不做（v1）——design §6 不做清单明文「审批/问答域」。结构性事实需记录：这是 client→server 反向要答案的面，纯 mux 单向流装不下，将来要么复用 unary（poll/answer 方法对）要么加双向帧——接缝形态建议在拍板时一并定
approval/asked / approval/decided session 审计事件	index.ts:35-60（log-only，merge into SessionEventMap）	已覆盖——merge-extensible 事件随 mux 透传（design §3.3 未知类型分支），UI 已可"看到"审批发生过；缺的只是"参与决定"（上行）
approval/policy（ask/never，session 内覆写）	index.ts:108 + SessionEventMap merge	已覆盖（事件透传）；改 policy 的命令面归审批域一并 v2
ctx.userInteraction.ask（AskUserQuestionRequest/Answer，单 provider 注册制）	user-interaction/src/index.ts:43-71（registerProvider 单占 :96-107）	有意不做（v1）——同上不做清单。附注：单 provider 语义 ⇒ Web client 接管问答时要经 host 侧代理 provider 中转（provider 在 host 进程注册、答案从 wire 上取），这决定将来接缝在 impl 不在契约新增语义

6. workflow / todo / skill / compact 可观测面速查

包	core 事实	契约状态
todo（packages/todo）	唯一持久面 = todo/write session 事件（types.ts:246）	已覆盖——透传 + client fold last-write-wins（§1.1 已列）
compact（packages/compact）	产物 = surface replace 事件 + context/message（SurfaceOp types.ts:292-294）	已覆盖——透传；client fold 处理 replace 即正确渲染压缩后视图（design §5 foldSurface 复用）
skill（packages/skill）	装载产物 = context/message（skill 内容注入）+ tool/call 事件	已覆盖（透传）；skill 目录浏览/管理面 v1 无 UI 诉求，有意不做（catalog 工具是模型面不是 client 面）
workflow（packages/workflow）	worker-thread 引擎；对 session 的可观测面 = 其 tool/call、tool/result + 子 agent session（同 §3）	已覆盖（间接）；workflow 进度独立流 v1 不做，与 L6 任务面板同性质
guard（packages/guard）	loop-hygiene 插件，干预结果落 session 事件（steering/turn-stop）	已覆盖（透传，无独立面）

7. LLM 层（packages/llm）

能力	core 事实	契约状态
usage/token 统计	assistant/message.usage?: TokenUsage（session types.ts:226，与消息同travel）；request/header 里 config	已覆盖——透传即达（§1.1 已列）；聚合统计（session 累计 token）是 client fold 的算术，不需要 server 接口
adapter 注册面（provider 现值）	LlmService 注册表；AgentOptions.provider/model（agent types.ts:21-26）	已覆盖——host.describe 的 provider/model 现值（20:02 拍板）；adapter 列表枚举（UI 下拉「可用 provider 有哪些」）漏判 →【L7】：describe 只给现值不给候选集，「模型切换」在不做清单但「枚举可选项」是它的读前提，处置建议留接缝
模型切换（运行中改 provider/model）	agent/request waterfall 可换 config	有意不做——design §6 不做清单明文

漏判清单（已裁决，2026-07-19 21:13：L1/L2/L5 合入 design.md v1.5；L3/L4/L6/L7 类型预留 design §8；审批/问答提案整体采纳并入 §3.4）

#	缺口	core 事实（file:line）	建议处置	一句话理由
L1	subagent/fork 谱系不可见（已知条目）：host/session-added 与 SessionSummary 均无 parent 信息，UI 无法画子 agent 树、无法区分用户开的还是 agent spawn 的	SessionHeader.parentSession/seedLength（session types.ts:47/52）；fork 时写入（session index.ts:854）；spawn 时 stamp（subagent types.ts:56-61 REQUIRED parent）	进 v1 契约。补法：① host/session-added 帧加可选 parentSessionId?: SessionId（从 session.header.parentSession 读，无谱系时缺省）；② SessionSummary 同补 parentSessionId?（冷 session 列表也要能画树；jsonl 后端从持久化 header 读）。运行时归属（registry owner/roots，agent index.ts:543/560）不透出——durable 谱系已够 UI 用，运行时树是进程内概念	字段 core 已持久化、读取零成本；缺它 UI 树状视图无法做，且 additive 可选字段不破坏现契约
L2	session 元数据有入无出：create 收 cwd 但 list/history 均不回吐；createdAt 同	SessionHeader.cwd/createdAt（session types.ts:43/45）	进 v1 契约（顺手）：SessionSummary 加 cwd?: string。createdAt 不加——v1「mtime=updatedAt」拍板已覆盖排序诉求，再加是第二时间语义	多 session 不同 cwd 时列表页无法标注工作目录；一字段事，与 L1 同一次 SessionSummary 改动
L3	fork 无契约方法：core 有完整原语+类型化错误码，opencode 有同款端点	SessionStore.fork（session index.ts:843-857）；SessionForkErrorCode :556-562；turn/end 边界 :890-895	留接缝：v1 不加 session.fork（UI 无 fork 按钮诉求）；接缝=将来 RpcMethodMap 加 'session.fork' 一行 + SessionForkErrorCode 并入 RpcErrorCode 按域扩展，零结构变化	形态 B 下加方法是纯 additive；现在加则要陪审 UI 交互（fork 点选择、边界约束提示）不值 v1
L4	agent.inject 第三输入原语无映射：prompt 只有 queue/steer	Agent.inject（agent types.ts:119）；idle 时一次性 turn 语义 types.ts:84-89	留接缝：prompt 的 mode union 将来加 'inject' 即可（merge 进闭合 union + impl 分发）。v1 Web UI 无「注入不触发回复」交互	三原语中 inject 是插件/自动化面（文件变更通知等 host 内部已在用）；人机 UI 场景未出现，union 扩展零迁移
L5	无 turn 位置的 live 失败 client 不可见：agent/error 在 session log 无对应事件时（如 flush 失败、驱动崩溃）UI 只能看到 session 卡死	agent/error emit（agent types.ts:311，"even when the error has no in-turn position"）	进 v1 契约（轻量）：HostFrame 加 { type: 'host/agent-error'; sessionId; message: string }——只做诊断展示不做恢复语义	不加则「agent 停了但 UI 永远转圈」无解释渠道；一帧类型，Frame union additive
L6	后台任务注册表无接口：bash 后台/长任务在 ctx.tasks，UI 任务面板无数据源	tasks.list/get/wait/onTaskDone（tasks index.ts:153/167/226/283）；TaskSnapshot :326	留接缝：任务面板不在 v1 UI 范围；接缝=将来新 tasks 域（一域一文件 + RpcMethodMap 数行 + 完成通知并入 hostEvents 或独立流）。设计已天然支持新域（design §1「新域=新文件对+根接口一字段」）	v1 UI 无此面板；域级 additive 是本契约的标准扩展路径，无需预留字段
L7	provider 候选集不可枚举：describe 给现值，UI「切换模型」下拉无数据源	LlmService adapter 注册表；AgentOptions.provider/model（agent types.ts:21-26）	留接缝：模型切换整域在不做清单，枚举是其读前提，一起进将来的 provider 域；不单独提前	只读枚举脱离切换动作无用户价值；避免半个域
—	审批/问答：形态已拍板（2026-07-19 21:0x，mux 下行帧 + HTTP unary 上行），协议提案见下节，随本清单一并裁决	见下节逐条 file:line	本轮定契约形状，实现可排后	—

审批/问答域协议提案（已采纳并入 design.md §3.4；21:19 修订：QuestionAskId 取消、问题标识复用 RpcId——下文为原提案存档，以 design.md 为准）

已定：请求下行 = mux 控制帧（稳定 id + session 锚点）；回答上行 = 普通 unary（respond 带 id 回传）。不做双向帧/双工通道——SSE 本就是 server→client，回送有 HTTP。

A. 方法与帧

// RpcMethodMap 增两行（key 按域单数 convention）
'approval.respond': ApprovalApi['respond']
'question.respond': QuestionApi['respond']

export interface ApprovalApi {
  /** 回答一个待决审批。outcome 只收 client 可给的子集（cancelled/unavailable 是 host 侧结局）。 */
  respond(input: { sessionId: SessionId; id: ApprovalRequestId; outcome: 'allowed-once' | 'rejected' }):
    Promise<RpcResponse<{ accepted: true }>>
}
export interface QuestionApi {
  /** 整批回答一次 ask（core 事实：一次 ask 多题一个 answer，user-interaction index.ts:63-67）。 */
  respond(input: { sessionId: SessionId; id: QuestionAskId; answer: AskUserQuestionAnswer }):
    Promise<RpcResponse<{ accepted: true }>>
}

// MuxFrame 增四帧（Frame 族，session 锚点）
| { type: 'approval/requested'; sessionId: SessionId; id: ApprovalRequestId; toolName: string; callId?: CallId; reason?: string }
| { type: 'approval/resolved';  sessionId: SessionId; id: ApprovalRequestId; outcome: ApprovalOutcome }
| { type: 'question/requested'; sessionId: SessionId; id: QuestionAskId; questions: AskUserQuestionItem[] }
| { type: 'question/resolved';  sessionId: SessionId; id: QuestionAskId; outcome: 'answered' | 'cancelled' }

• requested 载荷 = core 类型透传：审批帧字段即 ApprovalRequest 去 agent（换 sessionId 锚）去 signal（user-approval index.ts:190-212）；问题帧直接透传 AskUserQuestionItem[]（user-interaction index.ts:29-41，model 自带题内 id）。
• resolved 帧是收敛面：多 client 同看一 session 时，别人答掉/超时取消/policy 决掉，观察方靠 resolved 撤卡片；自己答成功也等 resolved 帧统一收敛（respond 的 accepted 只表示受理）。

B. id 纪律（按现行纪律推导）

• 审批：复用 core ApprovalRequestId（已 brand，user-approval index.ts:76）——SessionId 同款先例：type-only import、id 全部源自 server（requested 帧），client 只回传。
• 问答：host 造 QuestionAskId（api 层新 brand：Branded<'question-ask-id'>）——core 事实：user-interaction 无 request 级 id（AskUserQuestionRequest 只有题内 model 自给的 string id，index.ts:29-33），host 代理 provider 受理 ask() 时 mint UUID。与 cursor 占位不同（那是未实现故不 brand），此 id 实装即进签名，按「opaque 跨界 id 必 brand」仓规上 brand。

C. 竞争语义

• 先到先赢，host 内存 pending 表是唯一裁判：一个 id 只被 settle 一次。竞争方：client respond vs signal abort（tool 取消/step 中止 → cancelled，user-approval index.ts:206-211）vs 另一 client respond。policy 'never' 在 answerer 链之前解决（index.ts:100-108），requested 帧根本不发——天然对齐。core 无审批超时（signal 是唯一撤回通道），不发明。
• 迟到/重复回答：RpcErrorDetailsMap 增两码——'approval-not-pending': { id: ApprovalRequestId }、'question-not-pending': { id: QuestionAskId }（分域两码不合一：details 类型不同，且按域扩展是既定纪律）。

D. 刷新恢复（推荐：subscribed 基线重放）

推荐：client 重开 mux 后，host 在每个 session 的 session/subscribed 帧之后立即重放该 session 仍 pending 的 */requested 帧（来源=host 内存 pending 表）。理由：单一事实源（全走 mux），与 lastSeq 补缝流程同构，client 无需第二条 bootstrap 路径做 join。不推荐 host.describe 带 pending 列表：跨 session 聚合 + 与流竞态，两处真相。 不能从 history 推 pending（审批虽有 approval/asked/decided 审计事件，但 crash 后 asked-without-decided 是永久悬案——pending 真相只在 host 内存，重放帧无此歧义）。

E. core 事实对齐（盘点批3 + 本批补核）

core 事实	file:line	提案对齐
approval 走 policy → answerer waterfall 链，fail-closed unavailable	user-approval index.ts:23-32、:100-108	host 侧注册一个「wire answerer」进链：收 approval/request → 发 requested 帧 → 等 respond/abort → 返回 outcome。链上仍可有其他 answerer（组合语义不变）
approval/asked/decided 已是 session 审计事件（log-only）	index.ts:35-60	保持透传不动；帧是 live 控制面、事件是 durable 审计，职责分离不算重复造 DTO
ApprovalOutcome 四值闭合 union	index.ts:91	resolved 帧透传全集；respond 入参窄化为 client 可给二值
userInteraction 单 provider 注册制	user-interaction index.ts:96-107	host 代理 provider 是唯一注册者（盘点 §5 已注），多 web client 竞争在 wire 层由 pending 表裁决，不违单 provider
ask() 不落 session 日志	user-interaction 全文无 SessionEventMap merge（本批 grep 核实）	问答无审计事件可依赖 → requested/resolved 帧是问答唯一可观测面，D 的内存重放是唯一恢复路径（自洽）
一次 ask 多题、整批回答	index.ts:43-67	respond 收整个 AskUserQuestionAnswer，不拆单题方法

汇总（裁决后）：L1/L2/L5 已合入 v1.5（SessionSummary.parentSessionId?/cwd?、session-added 帧 parentSessionId?、host/agent-error 帧）；L3/L4/L6/L7 类型已预留（design §8 完整签名，不进 map——fail loud 优于 not-implemented 兜底）；审批/问答提案（下节）整体采纳并入 design §3.4。本文件转为盘点存档，后续契约变更以 design.md 为准。