@coralai/agent-runtime

统一的 agent 运行 / 管理适配层:把 @anthropic-ai/claude-agent-sdk 与 @openai/agents 归一到一套生命周期、会话、版本管理之下。消费者(sps-cli / gameforge / 未来其它)只对契约编程,不直接耦合任何 SDK。

它取代旧的 @coralai/claude-code-agent(claude-only + ACP):新项目是统一 + 直连 SDK,无 ACP 中间层。

它是什么 / 不是什么

是(机制层):加载/版本管理两个 SDK、会话生命周期(spawn/保活/复用/取消/超时/强杀/resume)、监管与重连、服务进程(daemon)、会话级可观测、cwd/权限机制。

不是(策略层,留给消费者):pipeline / 编排、完成判定的判据、PM/卡/git、控制台 UI、多租户配额策略。

边界一句话:本项目 = 怎么跑/管 agent;消费者 = 跑什么、何时跑、算不算完成。

双形态

• 库:in-process 嵌入(createRuntime() → 适配器),给 gameforge 那样直接调库的场景。
• 服务:agentd 守护进程(Unix socket / 可选 HTTP),给跨进程监管 + 消费者重启重连的场景。

同一核心,两种用法。

文档(先读这些)

| 文档 | 内容 | |---|---| | docs/00-charter.md | 项目章程:scope / 边界 / 非目标 / 形态 / 与 claude-code-agent 退役关系 | | docs/01-contract.md | 契约(消费者提的需求):统一接口、生命周期状态机、事件、服务协议、版本命令、上下文 | | docs/02-sdk-claude-agent-sdk.md | 从 claude-agent-sdk(0.3.196)提炼的功能接口 | | docs/03-sdk-openai-agents.md | 从 openai-agents(0.12.0)提炼的功能接口 | | docs/04-unified-interface.md | 统一接口设计:两 SDK 能力如何归一(含能力映射矩阵) | | docs/05-roadmap-migration.md | 路线图 + parity-then-switch 迁移 + sps-cli 接入 | | docs/06-tasks.md | 任务清单(P0–P6 + 决策 D1–D6,每项带验收;当前进度) | | docs/07-review-p0-sps-cli.md | P0 契约评审(sps-cli 视角)签字 + R1–R4 | | docs/08-integration-and-rollout.md | P5/P6 集成与上线步骤 + 门控 | | docs/09-sdk-coverage.md | SDK 覆盖映射:对照官方文档逐项接入(三层完全可达 + 逃生舱) |

测试

npm test               # 7 套零凭据确定性 smoke(P0–P4 + 集成)
npm run smoke:claude:live          # 真订阅 live 平价(需本地 claude 凭据)
npm run smoke:claude:live:resume   # 真订阅 live durable resume

状态

实现已铺开并测试通过:P1 ClaudeBackend(含 LIVE 平价/resume)、P2 服务化(agentd + 重连/恢复)、P3 版本管理、P4 OpenAiBackend、集成面,全部确定性 smoke 绿;sps-cli 经 mode:'runtime' 已可正常对接(LIVE 实跑通)。两 SDK 已对照官方文档全部接入(见 docs/09)。版本 0.1.0。