Runtime SDK

定位

本文件定义 runtime 侧 SDK 的规范性逻辑契约，用于支撑同一份运行代码在 worker、faas、sandbox、wasm 等不同 RunEnv 中运行。

v1 把 Runtime SDK 分成两层：

• Core SDK
  • 平台中立能力的规范性能力面
• Platform SDK
  • 绑定具体宿主环境的专属能力面

具体的 register(...)、use(...)、plugin、polyfill registry 和语言 helper 形状不属于 core 规范强约束，统一放到 Runtime SDK Implementation Recommendations。

Core SDK 标准能力

Core capability	逻辑契约
input.receive	接收平台投递的输入事件
output.publish	发布标准输出事件
tool.call	调用受平台治理的 tool 边界
interaction.request	创建或推进统一交互对象
tracing	接入统一 tracer / trace export 语义
config.read	读取 run / session 作用域配置
secrets.read	按需读取受控 secret
kv.read	读取会话级 KV
kv.write	写入会话级 KV
checkpoint.save	触发 checkpoint 保存
checkpoint.load	触发 checkpoint 加载

Core SDK 只承诺 capability 语义，不规定具体函数名或语言签名。

Platform SDK

Platform SDK 用于暴露与宿主环境强绑定的 API。v1 标准 capability 名如下：

• fs.read
• fs.write
• fs.list
• workspace.snapshot
• workspace.restore
• terminal.exec
• browser.open

这些能力 MUST 通过独立 Platform SDK 入口提供，而不是静默注入到 Core SDK 中。

Support Level

• surface=core
  • supportLevel 允许为 native | polyfilled | unsupported
• surface=platform
  • supportLevel 只允许为 native | unsupported

实现 MUST NOT 通过静默弱化语义把不满足契约的能力伪装成已支持。

Capability Negotiation

runtime attach 时，runtime MUST 上报：

• sdkCapabilities[]

平台回复时 MUST 返回裁剪后的：

• effectiveSdkCapabilities[]

编排器 MUST 在 attempt 上冻结：

• sdkCapabilitySnapshot[]

用于审计、诊断与恢复。

同一 attempt 内的 reconnect MUST 视为连接恢复，而不是新的能力协商窗口。除非编排器显式创建新的 attempt，否则 reconnect MUST NOT 让既有 sdkCapabilitySnapshot 漂移。

与 Revision / RunEnv 的关系

• AgentRevision.executionProfile.executionClass.runEnv、ToolRevision.executionProfile.executionClass.runEnv 或 McpServerRevision.executionProfile.executionClass.runEnv 是发布时选定的运行环境
• 同一 run 的 retry MUST NOT 借机自动切换 runEnv
• attach 协商得到的 sdkCapabilitySnapshot 只描述“该 attempt 在当前 runEnv 下的有效能力”，不改变 revision 的 northbound protocol profile
• 如果 reconnect 后 runtime 只能提供与既有 snapshot 不兼容的能力集，实现 MUST 让该连接恢复失败，并由 orchestrator 决定是否创建新 attempt

错误语义

• 如某项 core capability 不可满足，实现 MUST 返回稳定的 unsupported 错误，而不是延迟到业务逻辑内部静默失败
• 恢复失败 MUST 明确区分“连接丢失”和“能力集不兼容”

与其他规范的关系

• Runtime Connection Protocol
  • 定义 attach / heartbeat / KV / config / secrets 等传输协议
• Runtime Tracing
  • 定义 tracer 的逻辑 API
• Runtime SDK Implementation Recommendations
  • 定义推荐的 polyfill registry、plugin 装配和语言绑定形状