Runner 模块详细设计

August 29, 2026 · View on GitHub

1. 状态与权威

字段	值
状态	`ITERATION_2_DOCUMENT_CALIBRATION_CANDIDATE`；实现已交付，但不代表更广泛 conformance
稳定身份	Runner；Execution module M02
System owner	Project Execution System
结构权威	GitHub issue #47 与子 issue #62–#66
实现证据	pinned Iteration 2 submodule revision 下的 `execution-system/src/{interpreter,coordinator,host,invocation,custody,composition}`
Core 接口	`execute`、`inspect`、`cancel`；当前由 `ExecutionRuntimeAdapter` 类型描述
Companion	英文规范原文；本文是 non-normative 中文 companion
上层设计	Execution System
追踪资料	Runner 追踪与实现记录

历史边界： 下方 configured Provider key/runtime creation 描述已发布 1.x/Iteration 2 path。新的 2.0 Delivery 遵循 Role-to-Provider binding candidate：exact Role descriptor 冻结在 Manifest，installation composition 提供一个 owner-factory registry，只有该 Manifest 实际使用的 Provider 获得 realm，runtime/session/recovery 必须 exact-match，且不存在 credential、priority、fallback 或 rebinding。

本文把旧设计校准到 issue-authoritative Iteration 2 结构。Runner 是 Execution module M02，不是产品 System、subsystem、另一 M02 module 后面的实现，也不是第四个 Execution module。内部五个单元是 Interpreter、Lifecycle Coordinator、Workflow Host、Managed Agent Invocation 与 Custody submodule。ExecutionRuntimeAdapter 是当前 Core-to-Runner 类型名，不代表已经提升出的多态 Runner 抽象。只有未来确实需要多个 Runner 实现时，才可以把 M02 提升成该抽象，并且每个具体实现必须使用不同名称。追踪 companion只索引设计 ID 与证据，不形成另一 behavior owner。

2. 身份与目的

Runner 是执行 fully admitted Workflow activation 的 embedded Execution module。它的稳定身份不包含 LangGraph 或其他可替换实现依赖。LangGraph 是当前选定的 Workflow Host substrate；未来可以由兼容 Host Adapter 替换，而不改变 Execution-facing 接口或 in-flight Delivery。

Runner 只接收 deeply frozen RunnerActivationContext。execution.delivery 已完成 worktree admission、Package resolution、Manifest binding/persistence，并投影 exact Package、resource、Agent/model/Driver/provider、workspace 与 correlation binding。Runner 不拥有 Package Source/Store、worktree admission、current-slot state 或 Manifest persistence，也不读取 raw Package/schema document 或 selector。

Runner 严格实现 Execution owner 定义的三个 public operation：

execute(activation)
inspect(delivery)
cancel(delivery)

Resume、recovery、checkpoint、native session 和 retirement operation 都留在 private composition capability 中。

3. 创建平面

Execution 冻结 exact Runner configuration identity。private RunnerFactory 根据该 configuration 物化一个 Runner instance；它不在多个 Runner 实现之间进行选择。

Execution Runner configuration identity
  → RunnerFactory
      → Interpreter
      → Custody
      → configured Provider Adapter Factory registry instance
          → exact Provider Adapter Factory
          → concrete Provider runtime
      → exact configured Workflow Host Adapter Factory
          → concrete Workflow Host
      → Managed Agent Invocation
      → Lifecycle Coordinator
  → Runner（M02），通过 ExecutionRuntimeAdapter 暴露

RunnerFactoryConfig 是 closed immutable composition value。它包含创建实例所需的 exact storage root、所选 Workflow Host engine、Provider factory key/configuration。它不包含预构造的 provider-native service、任意 callback、ambient discovery、priority ordering 或 fallback rule。

Provider 创建使用 Runner composition 所有的 closed exact-key registry instance。Provider Factory SPI 和 concrete Provider factory 归 Managed Agent Invocation 所有。duplicate key、unknown key、invalid configuration 或 startup failure 必须在 Runner 发布前失败。

Workflow Host 创建使用唯一 exact configured factory。当前配置选择 engine: "langgraph"。不存在 Host registry、priority selection 或 fallback。未来 engine 通过扩展 closed configuration union 并提供兼容 factory 进入。

Factory selection 只发生在创建期。active Delivery 保持启动时的 exact Runner、Host、Provider 和 configuration identity；configuration reload 或 dependency availability 不得替换 in-flight implementation。

4. 调用平面与依赖方向

Agent Action 主路径是：

Execution Core → Runner（M02）/ Lifecycle Coordinator → Workflow Host → Managed Agent Invocation

完整 capability graph 是：

Lifecycle Coordinator → Interpreter
Lifecycle Coordinator → Workflow Host
Lifecycle Coordinator → Managed Invocation control
Lifecycle Coordinator → Custody lifecycle
Workflow Host → Managed Invocation action capability
Workflow Host → Custody capability

Workspace authority 只以 signed AuthorizedWorkspaceCapability value 的形式随 Host dispatch 到达 Managed Invocation。Managed Invocation 永远不获得 Custody service。返回值只完成原始调用，不形成 reverse dependency。

Interpreter 是一等 Runner submodule。其 compileRunnerActivation 实现消费 admitted activation、校验 exact closure/binding identity，并产生 minimal execution plan。它没有 durable state，也不执行 Delivery admission、Provider、Host 或 Custody effect。

5. Submodule ownership

Submodule	拥有	不拥有
Interpreter	admitted activation validation 与 Definition-to-executable-graph compilation	Delivery/worktree admission、durable state、graph progress
Lifecycle Coordinator	Adapter lifecycle、external bridge、cancel/recovery coordination、terminal settlement	graph decision、Provider session、Git mutation
Workflow Host	thread、graph path、dataflow、barrier、checkpoint、suspension、terminal proposal	Provider-native state、Delivery settlement、publication
Managed Agent Invocation	Provider invocation、native session、credential、Journal、structured completion	graph progression、Workflow Wait、Custody service
Custody	savepoint、Git-tree identity、scoped workspace authority、restore、result preservation、publication	worktree admission/lifecycle、file-editing API、graph path

每个 durable fact 只有一个 writer。caller-specific capability 防止调用者触达不归其所有的 operation。

6. 配置与扩展规则

constructed Runner 内的 Provider key 是 exact 且 closed；禁止 ambient plugin discovery、provider fallback 和 priority arbitration。
DSH Provider factory 拥有 DSH-native bootstrap，负责在 Provider Adapter boundary 后创建真实 AgentRegistry、SessionStore 和 native session factory。
Copilot/Codex 在各自 production obligation 完成前保持 typed fail-closed Provider shell；其存在不代表支持，也不得触发 fallback。
Workflow Host factory 拥有所选 substrate 和 private checkpoint storage 的创建；RunnerFactory 只拥有 exact selection 与 instance assembly。
result validation support 是 Runner 固定、fail-closed 的 internal capability，由 RunnerFactory 注入 Managed Invocation；它不是用户可配 policy，也不进入 shared activation Contract。
Observation 是 private one-way non-controlling port；disabled、rejected、throwing 或 tail loss 都不能改变 lifecycle truth 或阻塞已完成 Delivery。

7. Lifecycle invariant

correlation/binding mismatch 在 child effect 前失败。
unknown start/recovery disposition 保持 unknown；Runner 不伪造 non-start，也不 blind retry。
Action-scoped input 保持同一 episode/native session，与 Workflow Wait 不同。
Host result validation 与 Workspace validation 必须都通过，才能提交 result/data edge 和 next savepoint。
terminal 顺序是 proposal → preserve result → known publication → one retirement authorization → owner-scoped retirement → four known durable-owner facts → immutable settlement → optional Observation。Interpreter 没有 durable state，不是 retirement owner。
publication conflict 是 known，可进入 settlement；publication unknown 不可。
partial retirement retry 使用同一 authorization；已完成 owner 重放同一 fact，不重复 destructive cleanup。
public Adapter shape 始终严格为 execute、inspect、cancel。

8. 验证与 reopen 条件

必须包含以下 conformance 证明：

exact configuration selection，以及 duplicate/unknown factory-key negative；
使用真实 Provider/Host factory 构造，且不接收预构造 native service；
import DAG 与 caller-capability check；
admitted activation input，并从构造上拒绝 raw Package；
same-episode interaction、Workflow Wait、cancel 与 three-way recovery fixture；
真实 DSH local-transport acceptance path；
workspace/checkpoint/result/publication/retirement/settlement ordering；
Observation unavailable 时的隔离；
full、coverage、static-boundary、typecheck 与 build gate。

当 Runner 必须变成 remote service、多个 active instance 共享同一 Delivery、出现第二个 Runner implementation 或 Runner-selection 需求、Provider/Host 必须 runtime fallback、native state 必须穿过 Execution public seam，或 shared Contract 无法表达必要 cross-owner fact 时，重新打开本设计。