提供方能力系统

V2 不得假设每个提供方（provider）都能做到 Codex 能做的事。提供方行为应当通过能力和策略来表达，而不要在编排各处散落按提供方名称分支的条件。

能力形态

type ProviderCapabilities = {
  sessions: SessionCapabilities;
  threads: ThreadCapabilities;
  turns: TurnCapabilities;
  streaming: StreamingCapabilities;
  tools: ToolCapabilities;
  approvals: ApprovalCapabilities;
  planning: PlanningCapabilities;
  subagents: SubagentCapabilities;
  context: ContextCapabilities;
  checkpointing: CheckpointCapabilities;
  identity: IdentityCapabilities;
};

能力应当带有版本，并由每个适配器（adapter）在提供方会话（session）开始时发出。

提供方会话能力

type SessionCapabilities = {
  supportsMultipleProviderThreadsPerSession: boolean;
  supportsModelSwitchInSession: boolean;
  supportsProviderSwitchingViaHandoff: boolean;
  supportsRuntimeModeSwitchInSession: boolean;
  pendingRequestsSurviveRestart: boolean;
};

策略示例：

• 如果不支持切换模型，就启动一个新的提供方会话（session）。
• 如果待处理请求无法在重启后保留，就把旧请求标记为 not_resumable。

恢复提供方对话线程（provider thread）并不是一项能力。它是适配器（adapter）必须具备的原语。适配器必须能够从已存储的提供方游标、提供方会话或对话线程（thread）句柄开始，或者返回运行时恢复失败。

对话线程能力

type ThreadCapabilities = {
  canCreateEmptyThread: boolean;
  canReadThreadSnapshot: boolean;
  canRollbackThread: boolean;
  canForkThread: boolean;
  canForkFromTurn: boolean;
  canForkFromSubagentThread: boolean;
  exposesNativeThreadId: boolean;
};

Codex 可以暴露强对话线程（thread）ID 和回滚快照。Claude 可以通过自己的模型或提供方会话（session）原语支持原生分叉。其他提供方可能只支持由应用合成的分叉。

回合能力

type TurnCapabilities = {
  exposesNativeTurnId: boolean;
  emitsTurnStarted: boolean;
  emitsTurnCompleted: boolean;
  supportsInterrupt: boolean;
  supportsActiveSteering: boolean;
  supportsSteeringByInterruptRestart: boolean;
  supportsQueuedMessages: boolean;
  terminalStatusQuality: "strong" | "weak" | "none";
};

如果 terminalStatusQuality 较弱，V2 应当用适配器策略推断终态，并相应地标出关联强度。

supportsActiveSteering 表示提供方可以直接修改进行中的回合（turn）。supportsSteeringByInterruptRestart 表示 V2 可以通过打断活跃回合并启动一次替换尝试，来实现应用级转向。如果提供方支持打断，也支持正常的后续回合，那么大多数提供方都应当支持后者。

流式能力

type StreamingCapabilities = {
  streamsAssistantText: boolean;
  streamsReasoning: boolean;
  streamsToolOutput: boolean;
  streamsPlanText: boolean;
  emitsMessageCompleted: boolean;
};

如果没有发出消息完成，规范化器就在根运行进入终态时关闭助手消息。

工具能力

type ToolCapabilities = {
  exposesToolItemIds: boolean;
  emitsToolStarted: boolean;
  emitsToolCompleted: boolean;
  emitsToolOutput: boolean;
  supportsMcpTools: boolean;
  supportsDynamicToolCallbacks: boolean;
};

较弱的提供方可能只产生文本形式的工具摘要。适配器（adapter）仍然可以按作用域内的序号，创建有序的 turnItems 和执行节点。

批准能力

type ApprovalCapabilities = {
  supportsCommandApproval: boolean;
  supportsFileReadApproval: boolean;
  supportsFileChangeApproval: boolean;
  supportsApplyPatchApproval: boolean;
  approvalsHaveNativeRequestIds: boolean;
  approvalCallbacksAreLiveOnly: boolean;
  approvalsCanOriginateFromSubagents: boolean;
};

只要可以回应，界面就应当显示来自任一执行节点的待处理批准，包括子智能体的批准。

计划能力

type PlanningCapabilities = {
  emitsPlanUpdated: boolean;
  emitsTodoList: boolean;
  emitsProposedPlan: boolean;
  supportsStructuredQuestions: boolean;
  planDeltasHaveItemIds: boolean;
};

映射策略：

• emitsTodoList：更新实时运行进度。
• emitsProposedPlan：创建可接受、可实施的计划产物。
• supportsStructuredQuestions：创建可回应的用户输入请求。

如果提供方只发出普通的助手文本，应用就不应当假装它拥有结构化计划。

子智能体能力

type SubagentCapabilities = {
  supportsSubagents: boolean;
  exposesSubagentThreadIds: boolean;
  emitsSubagentLifecycle: boolean;
  canWaitForSubagents: boolean;
  canCloseSubagents: boolean;
  canForkSubagentThread: boolean;
};

当 exposesSubagentThreadIds 为真时，子智能体的提供方对话线程（provider thread）会成为可寻址的 ProviderThread 记录。当它为假时，只要提供方暴露了足够的生命周期信息，子智能体仍然可以显示为嵌套的执行节点。

上下文交接能力

上下文交接控制提供方（provider）切换，以及提供方对话线程（provider thread）的重建。

type ContextCapabilities = {
  acceptsSystemContext: boolean;
  acceptsDeveloperContext: boolean;
  acceptsSyntheticUserContext: boolean;
  canGenerateSummaries: boolean;
  canConsumeHandoffSummaries: boolean;
  supportsDeltaHandoff: boolean;
  supportsFullThreadHandoff: boolean;
  maxRecommendedHandoffChars: number | null;
};

策略示例：

• 如果 supportsDeltaHandoff 可用，就回到先前的提供方对话线程，摘要只包含发生在该提供方之外的运行。
• 如果增量交接不受支持或质量不足，就用完整的对话线程摘要创建一条新的提供方对话线程。
• 如果提供方不能接受显式上下文，切换提供方时就应当要求合成的用户上下文，或者标记为不受支持。
• 如果没有提供方能够生成摘要，就使用应用已配置的摘要提供方，或本地摘要器能力。

检查点能力

建立检查点（checkpoint）主要由应用负责，但提供方对话的回滚取决于提供方。

type CheckpointCapabilities = {
  appCanCheckpointFilesystem: boolean;
  supportsNestedCheckpointScopes: boolean;
  providerCanRollbackConversation: boolean;
  providerRollbackReturnsSnapshot: boolean;
  providerCanReadConversationSnapshot: boolean;
};

如果不支持提供方回滚，文件系统回滚仍然可以进行，但提供方的对话状态必须重新开始，或标记为已偏离。嵌套的检查点范围归应用所有；提供方只影响它们嵌套的提供方对话能否回滚到与已恢复的文件系统状态一致。

身份能力

type IdentityCapabilities = {
  nativeThreadIds: "strong" | "weak" | "none";
  nativeTurnIds: "strong" | "weak" | "none";
  nativeItemIds: "strong" | "weak" | "none";
  nativeRequestIds: "strong" | "weak" | "none";
};

这决定规范化器如何关联事件（event）：

• strong：把原生 ID 用作带作用域的提供方引用。
• weak：使用原生 ID，再加上序号或指纹。
• none：按作用域内的序号分配。

降级策略

每项功能都应当声明，缺少相应能力时会怎样。

示例：

interrupt unsupported
  -> stop session if allowed, otherwise mark unsupported

active steering unsupported
  -> interrupt active turn and restart the run as a steering replacement attempt

fork unsupported
  -> synthetic fork from app projection if policy allows

rollback unsupported
  -> restore filesystem checkpoint, restart provider context, mark provider state divergent

nested checkpoint unsupported
  -> capture only root-run checkpoint and record child filesystem activity as uncheckpointed

provider switch return unsupported
  -> create fresh provider thread with full app-thread summary

structured approvals unsupported
  -> provider runs under configured sandbox policy; no approval UI

plan_updated unsupported
  -> no live todo UI; rely on assistant messages

界面不应当把不受支持的行为藏在提供方专属的错误后面。它应当收到带类型的能力结果。

适配器契约

每个提供方适配器（adapter）都应当暴露：

type ProviderAdapter = {
  getCapabilities(): ProviderCapabilities;
  startSession(input): ProviderSession;
  ensureProviderThread(input): ProviderThread;
  sendRun(input): ProviderTurnStartResult;
  steerRun?(input): void;
  interrupt(input): void;
  respondToRequest(input): void;
  readThreadSnapshot?(input): ProviderThreadSnapshot;
  rollbackThread?(input): ProviderThreadSnapshot | void;
  forkThread?(input): ProviderThread;
  streamEvents(): Stream<ProviderAdapterEvent>;
};

可选方法由能力把守。编排层在未检查能力、也未经过策略包装的情况下，不应当调用可选方法。

原始提供方帧应由提供方的传输层或运行时记录为有界诊断。适配器流应当暴露规范化的提供方事件（event），以便 V2 规范化器把它们变成应用的编排事件。

由能力驱动的界面

界面应当收到已经按能力取舍过的操作：

• 按分叉来源显示或隐藏分叉操作。
• 把打断显示为可用、破坏性后备或不可用。
• 把批准显示为可回应或已过期。
• 只有存在结构化计划产物时，才显示计划或待办面板。
• 只有存在应用检查点（checkpoint）时才显示回滚，并标注提供方（provider）回滚是否受支持。

这样，产品在 Codex、Claude、Cursor、OpenCode 以及未来的提供方之间都会保持可预期。