For AI agents: the complete documentation index is available at /runlab/llms.txt, the full documentation bundle is available at /runlab/llms-full.txt, and this page is available as Markdown at /runlab/design/generated/run-engine.md.

Run Engine

RunEngine 是 Run Protocol 的执行边界。它接收 RunInput,管理一次完整的程序执行,并返回 Result<RunOutput, EngineError>。

RunEngine::run(input: RunInput) -> Result<RunOutput, EngineError>

本页规定 run 内部必须完成的顺序和可观察语义。实现可以选择自己的代码结构和进程模型,但必须提供相同的协议行为。

内部验证不是协议阶段

run 必须在启动任何 Program 前完成两类检查:

  1. 输入验证:确认输入结构、OCI 对象、跨字段约束和固定限制符合协议。
  2. 能力验证:确认当前引擎能够忠实实施输入中的每项条件。

失败时返回 EngineError,并指出字段或能力原因。产品可以在调用前提供建议性的输入检查,但真正执行仍必须在 run 内验证,因为内容、宿主资源和引擎能力可能已经变化。

执行顺序

一次调用按以下顺序进行:

验证输入与能力
      ↓
准备每个 Program 的环境和标准流
      ↓
创建并启动受控依赖程序
      ↓
创建并启动 primary
      ↓
等待 primary 结束或出现终结条件
      ↓
停止仍在运行的 Program
      ↓
排空标准流并取得进程结果
      ↓
按 RunControls 决定是否捕获每个 Program 的最终环境
      ↓
清理临时资源
      ↓
返回 RunOutput

准备包括验证并物化 OCI Image、创建 OCI bundle、建立标准流和执行所需资源。引擎必须为每个 Program 使用独立的可写 rootfs。

执行区间与超时

执行区间从第一个 Program 即将执行 OCI start 时开始,到调用进入终结阶段时停止。计时必须使用单调时钟。

execution_timeout_ms 省略时没有执行期限。显式期限到达后,引擎停止启动新的 Program,并立即进入终结阶段。准备和结果捕获不计入执行区间,但仍然必须有界,不能让一次调用因内部操作而永久无法返回。

进入终结

下列任一条件使执行进入终结阶段:

  • primary 退出。
  • primary 无法创建或启动。
  • 执行期限到达。
  • 调用方取消当前 run 调用。
  • 引擎发生导致已启动 Program 必须停止的操作错误。

取消针对正在进行的 run 调用。具体使用同步调用、取消令牌、进程信号还是其他控制句柄,属于引擎接口设计。实现方式不能改变输出中事实的含义。

受控依赖程序在 primary 运行期间自行退出,不会单独触发终结,也不会被重启。具体语义参见受控依赖程序的执行语义。

有界停止

进入终结后,引擎必须停止继续传递尚未写完的 stdin,关闭输入写端,并对所有仍在运行的 Program 执行有界停止:

  1. 发送 SIGTERM。
  2. 继续排空 stdout 和 stderr,并等待进程结束。
  3. 从首次尝试发送 SIGTERM 起,全体 Program 共享 10 秒宽限期。
  4. 宽限期结束后,对仍在运行的 Program 发送 SIGKILL。
  5. 在实现声明的有限确认期限内等待,并取得能够证明的进程结果。

对于已经自然退出或确认没有启动的 Program,引擎不得伪造停止动作。信号发送失败、等待失败和确认期限届满都必须作为事实返回。确认期限届满后,进程结果标记为未知。请求捕获最终环境时,如果无法证明所有写入进程已经停止,最终环境必须标记为不可取得;未请求时仍返回 not_requested。

内部操作期限

10 秒停止宽限期是所有实现共同的协议常量。除此之外,每个 RunEngine 还必须公开以下操作使用的有限期限:准备、Runtime create 与 start、发送 SIGTERM 与 SIGKILL、等待进程、强制终止后确认、标准流排空、运行时文件系统移除、最终环境捕获和清理。这些期限是实现能力,不是 RunInput 字段。同一实现不得针对单次调用静默改变这些期限。

内部期限届满时,引擎根据执行操作是否已经开始,以及能否形成可信输出,按以下规则处理:

  • 执行操作尚未开始时,返回 EngineError。
  • 执行操作已经开始且仍能形成可信输出时,在 RunOutput 中记录超时、未知或不可取得事实,并继续完成其他有界收集。
  • 无法形成结构完整、来源可信的输出时,返回 EngineError。

因此,没有 execution_timeout_ms 只表示 Program 执行区间没有期限,不表示 RunEngine 的准备、停止、捕获或清理操作可以永久阻塞。

结果收集

所有 Program 都已结束、确认没有启动,或者强制终止后的确认期限已经届满时,引擎进入有界结果收集:

  • 完成标准流排空并记录 EOF、截断或读取错误。
  • 记录每个 Program 实际接收的 stdin 字节数,以及输入写端是否成功关闭。
  • 只在能够证明不会再有进程使用相应文件系统时,移除 bind mount、proc、tmpfs 等运行时文件系统。
  • capture_final_environment 为真时,从稳定的受控 rootfs 构造每个 Program 的最终 OCI Image,或记录无法取得的原因;为假时不执行捕获并记录 not_requested。
  • 清理本次调用创建的 bundle、Runtime 对象、进程、网络和其他临时资源。

捕获或清理失败不能抹去已经取得的进程和标准流事实。只要仍能形成符合协议的输出,引擎就返回 Ok(RunOutput),并在相应位置记录错误或不可用结果。

何时返回 EngineError

启动任何 Program 前发现输入无效或能力不足,直接返回 EngineError,此时没有 RunOutput。

执行已经开始后,引擎应优先返回包含失败事实的 RunOutput。只有引擎无法构造结构完整、来源可信的输出时,才返回 EngineError。如果引擎进程意外终止或宿主机停止运行,调用可能没有机会返回任何值。Result 只表示实际返回的协议结果。