openclaw-agent-runtime-contracts

openclaw-agent-runtime-contracts 是小智 Claw 体系里的共享 runtime contract 层，承载 planner、todo、session、runtime resource manifest、capability manifest helper、memory lifecycle contract、provider runtime boundary，以及少量需要跨消费者复用的 runtime core。

它不是工具编排层，也不是消费者私有平台接线层；它的职责是把多个消费者共享的 runtime state contract 和少量 canonical runtime core 稳定下来。

当前职责

1. Planner contract，包括 task plan、task step、plan status、context snippet。
2. Todo contract，包括 todo item、todo status、summary helper。
3. Session contract，包括 session identity、runtime session、pending prompt。
4. Runtime resource manifest contract，包括 assets、profiles、legacy compatibility entry 和纯 helper。
5. Capability manifest helper，包括 snapshot clone / diff / merge 以及 namespace、workspace id 派生语义。
6. Memory lifecycle contract，包括 memory block、observation envelope、write-access 与 canonical hook/source 枚举。
7. Provider runtime boundary contract，包括 auth/model/profile capability 边界接口与极小型 compat helper。
8. Provider runtime core，包括 provider capability、auth resolution、pi auth/model discovery 的 shared canonical 逻辑，具体 config/store/platform key 接线仍由消费者注入。
9. Checkpoint runtime core，包括 mutation checkpoint snapshot / restore 的 shared canonical 逻辑，workspace root 与持久化写入仍由消费者注入。
10. 极小型纯辅助函数与状态常量。

明确不负责

1. 会话存储实现。
2. Planner 执行器。
3. Todo manager。
4. Session manager。
5. Tool orchestration policy。
6. 消费者私有数据库、缓存、配置装配、订阅/平台密钥接线。
7. 鉴权、订阅、审计的消费者私有宿主逻辑。
8. Tool orchestration policy 与 Hub 侧运行时编排。

文档入口

项目内 canonical 文档：

1. docs/package-contract.md
2. docs/api-surface-map.md
3. CONTRIBUTING.md
4. docs/releasing.md

说明：

1. 该包的 contract 真源已经迁入本子项目 docs，不再以父仓 steup/docs 正文为准。
2. 父仓保留的同名文档只作为跨项目导航入口，不再承担正文真源职责。
3. 导出面、breaking-change 规则、开发边界都应以本目录文档为准。

导入规则

允许：

import type {
  RuntimeSessionContract,
  TaskPlan,
  TodoItem,
} from "openclaw-agent-runtime-contracts";
import {
  summarizeTodoList,
  TASK_PLAN_STATUS_VALUES,
  createCapabilityManifestDiffPayload,
  MEMORY_OBSERVATION_HOOK_VALUES,
} from "openclaw-agent-runtime-contracts";

import type {
  MemoryContextBlock,
  MemoryObservationEnvelope,
} from "openclaw-agent-runtime-contracts";

import {
  RUNTIME_ASSET_IDS,
  normalizeRuntimeResourceManifest,
} from "openclaw-agent-runtime-contracts/resource-manifest";

import type {
  ProviderRuntimeAdapterContract,
  ProviderRuntimeResolvedAuthContract,
} from "openclaw-agent-runtime-contracts/provider-runtime-contract";

import {
  createProviderRuntimeAuthCore,
  resolveProviderRuntimeEnvApiKey,
} from "openclaw-agent-runtime-contracts/provider-runtime-core";

import {
  createMutationCheckpointRuntimeManager,
} from "openclaw-agent-runtime-contracts/checkpoint-runtime";

禁止把以下路径当作稳定 contract：

import type { TaskPlan } from "openclaw-agent-runtime-contracts/src/planner.js";
import { summarizeTodoList } from "openclaw-agent-runtime-contracts/dist/index.js";

开发命令

1. 安装：npm install
2. 构建：npm run build
3. 类型检查：npm run check
4. 打包检查：npm run pack:check

本地开发说明

1. 消费方当前通过本仓本地依赖消费该包。
2. package contract 以 dist/index.js 与 dist/index.d.ts 为准，因此改动共享代码后要先在本包执行 build。
3. 推荐顺序：先在本包执行 npm run build 或 npm run check，再回到消费者工程刷新依赖并执行 build/typecheck。
4. openclaw 中存在少量 TypeScript path fallback 仅用于仓内开发便利，不属于本包对外 contract。

AI Coding 规则

项目级 AI coding 规则位于：

1. .github/copilot-instructions.md

核心要求：

1. 只在本包沉淀 planner、todo、session、memory lifecycle、provider runtime、checkpoint runtime 相关的共享 contract 与 canonical core；消费者私有 config/store/平台接线不得回流到本包。
2. 不修改 dist/ 产物，始终改 src/ 并重新构建。
3. 导出面变化必须同步更新 package contract、surface map 与 CHANGELOG。

仓库维护基线

1. CI 位于 .github/workflows/ci.yml，默认执行 npm ci、npm run check、npm run build、npm run pack:check。
2. Gitee tag release workflow 位于 .gitee/workflows/release.yml，使用 Gitee Go 原生 build@nodejs 与 release@gitee 插件自动构建并发布 release。
3. runtime-contracts 在 Gitee Go 应复用与 orchestration 已验证一致的 YAML 结构，仅替换流水线唯一标识与仓库内容。
4. Issue 模板位于 .github/ISSUE_TEMPLATE，用于 bug 与 contract 能力请求收口。
5. 发布说明位于 docs/releasing.md，用于约束版本、变更说明和消费者联动验证。