@coralai/sps-cli 0.63.6 → 0.65.1

package/docs/openai-daemon-agent.md

@@ -0,0 +1,144 @@
+# OpenAI daemon Agent 运维与使用指南
+
+SPS 0.64 提供显式 opt-in 的 `openai × daemon` 路径。SPS daemon 负责会话与监管，每次 dispatch 启动一个短生命周期 `sps openai-agent` 进程；worker 使用 `@openai/agents` 0.13.5 的完整 agent loop。上层 chat、pipeline、dashboard 继续消费同一套文本、工具、交互、usage、错误与 terminal 契约。
+
+这条路径实现的是 substrate、产品契约和轻 agent 能力对等，不声称复制 Claude Code 的全部编码策略、hook/settings 文件格式、agent teams 或后台任务行为。
+
+## 启用与回滚
+
+全局 worker 配置位于 `~/.coral/agents/defaults.json`：
+
+```json
+{
+  "worker": {
+    "agent": "openai",
+    "mode": "daemon",
+    "providerId": "official",
+    "model": "gpt-5",
+    "transport": "responses"
+  },
+  "reviewer": {
+    "providerId": "codex",
+    "model": "gpt-5.4"
+  }
+}
+```
+
+旧配置按 read-old/write-new 规则迁移：旧 OpenAI 配置缺少 `mode` 时仍使用 `sdk`；Claude 缺少 `mode` 时仍使用 `daemon`。因此升级不会自动把已有 OpenAI worker 切到新路径。
+
+回滚不需要删除会话数据，只需把 OpenAI 的 `mode` 改回 `sdk`。不要在仍有活动 run 时手工删除 `~/.coral/sessions/openai`。
+
+## Provider 与凭据
+
+- `providerId: "official"`：使用 OpenAI API，凭据来自 `OPENAI_API_KEY` 或 SPS 对应环境配置。
+- 第三方 OpenAI-compatible provider：配置在 `~/.coral/game-platform/agent-providers.json`，worker 只接收当前 provider 的 `SPS_PROVIDER_API_KEY`。
+- `transport` 支持 `responses`、`chat_completions` 和 `codex`；worker 会先协商 capability，不支持的 Responses 特性会降级并产生结构化 warning。
+
+凭据只通过 supervisor allowlist 后的子进程环境进入当前 dispatch。start command、stdout 协议、checkpoint、RunState、workspace state、tool ledger、metrics 与 trace metadata 均不保存 key。MCP header、raw provider event、异常原始 payload 和 approval reason 也不进入默认 trace。
+
+## Agent loop 与能力
+
+worker 使用流式 SDK Runner，支持：
+
+- 多轮模型/工具 loop、结构化输出和 handoff。
+- filesystem、shell、apply patch、图片查看和长命令 stdin。
+- `.agents/skills` 懒加载与 context compaction。
+- SPS managed MCP；MCP 工具统一使用 qualified identity。
+- tool input/output guardrail、approval interruption、`present_choices` 和 `present_form`。
+- run-wide settled usage；input、output、reasoning 和 cached input 字段使用同一 provider-neutral 事件。
+
+stdout 只包含 Agent Process Protocol V1 NDJSON。诊断写 stderr，不参与事件解析。
+
+## Sandbox
+
+开发环境默认：
+
+```text
+profile=workspace, provider=unix_local
+```
+
+UnixLocal 只用于受信任的本地开发。它不是主机安全边界。
+
+`NODE_ENV=production` 时默认：
+
+```text
+profile=production, provider=docker
+```
+
+生产 profile 会 fail closed：不能显式降级为 UnixLocal。Docker session 返回给 agent 前必须成功设置 2 CPU、2048 MiB 内存、256 PID 上限并断开 bridge 网络；任一 hardening 命令失败会删除容器并终止 run。workspace 以隔离副本进入容器，创建和修改在 SDK 序列化阶段同步回已授权项目目录。hosted sandbox 尚未接入本版本。
+
+可用 `SPS_OPENAI_SANDBOX_IMAGE` 指定经过内部审核的镜像。默认镜像是 `node:22-bookworm-slim`。项目内解析到授权根外的 symlink 会在 agent/tool 启动前被拒绝；manifest 也拒绝 `..` 路径逃逸。生产 run 的 wall time 上限为 30 分钟，单工具默认 60 秒。
+
+## 持久状态
+
+每个逻辑会话目录：
+
+```text
+~/.coral/sessions/openai/<sessionId>/
+├── session.json
+├── history.json
+├── checkpoint.json
+├── interactions.json
+├── tool-ledger.json
+├── workspace.json
+└── runs/<runId>/
+    ├── events.jsonl
+    ├── terminal.json
+    └── metrics.json
+```
+
+职责保持分离：history 是 conversation owner；checkpoint 是在途 SDK RunState；interaction 是人类等待；ledger 是副作用证据；events/terminal 是输出重放；workspace 是 sandbox 状态；metrics 只含 ID、时间和状态。
+
+## 等待、恢复与 operator reconciliation
+
+`run.waiting_for_input` 是 worker 进程的 terminal，但不是 logical run 的结束。worker 退出后 interaction 仍可等待数小时；Dashboard 提交答案时带 revision，重复相同提交幂等，冲突 revision 被拒绝。新 worker 从 checkpoint 恢复同一 `runId`、`turnId` 和递增 sequence。
+
+异常退出时：
+
+1. 已有 hard terminal：只重放，不重跑。
+2. 无 terminal 且 checkpoint `safeToResume=true`：恢复同一 logical run。
+3. ledger 中 read-only/幂等调用结果未知：允许按策略重试。
+4. 非幂等调用停在 `started`：进入 `operator_reconciliation`，不自动重试。
+
+运维人员在表单选择：
+
+- `effect_completed`：外部系统已完成，填写规范化 result，后续从 ledger 重放。
+- `safe_to_retry`：确认外部系统没有产生效果，允许重新执行。
+
+不确定时不要选 `safe_to_retry`。
+
+## Observability
+
+SDK trace 关联 `sessionId`、`runId`、`turnId`、agent bundle、provider、model 和 sandbox provider；`traceIncludeSensitiveData=false`。设置 `SPS_OPENAI_AGENT_TRACE=1` 才启用。退出前最多等待 2 秒 flush；export 失败产生 warning/metric，不覆盖真实 run terminal。
+
+daemon/session inspect 暴露 spawn latency、time-to-first-event、lastOutputAt、run/cancel duration、exit code/signal、replay gap 和 resume outcome。run metrics 还保存 checkpoint age、MCP close、sandbox cleanup 与 trace flush 结果。pipeline 只按 terminal 或 lost 推进；`lost` 是失败，git diff 或“完成”文案不能把它改成成功。
+
+## Retention 与删除
+
+Dashboard 删除 OpenAI daemon chat 时，先通过 daemon 停止活动 worker，再删除整个 worker-owned session tree，最后删除 chat history。若 daemon 不可用或 cleanup 失败，chat history 保留并返回错误，方便重试和巡检；不会只删 history 而留下 secret、checkpoint 或孤儿 sandbox。
+
+不要直接 `rm -rf` 会话根。自动删除会校验 session identity、路径边界并且可重复调用。
+
+## 灰度与验收
+
+推荐顺序：
+
+1. fake provider CI。
+2. 带真实账号的内部 OpenAI live smoke。
+3. 单项目显式 `openai × daemon`。
+4. 多 provider/key 并发与 secret canary。
+5. worker/daemon kill、terminal/store failure 和副作用故障注入。
+6. 生产 Docker canary。
+
+只有 terminal 丢失率、重复副作用、resume 成功率、冷启动、取消延迟和资源指标达到团队阈值后，才单独决策是否改变 OpenAI 默认模式。0.64 不改变默认。
+
+## 故障速查
+
+| 现象 | 处理 |
+|---|---|
+| `workspace_unavailable` | 检查 Docker、镜像、symlink 或 workspace 状态；不要降级生产 profile。 |
+| `provider_state_unavailable` | 检查 checkpoint/agent bundle/provider conversation owner，必要时回滚 SDK mode。 |
+| `operator_reconciliation` | 核对外部系统事实后提交 reconciliation，禁止盲目重试。 |
+| `trace_flush_failed` | run terminal 仍有效；检查 exporter，metrics 会记录 warning。 |
+| `lost` | 检查 exit code、stderr 和最近 checkpoint；不能按 git 产物判成功。 |
+| 删除返回失败 | 启动/修复 daemon 后重试删除，确认 session tree 已清理。 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coralai/sps-cli",
-  "version": "0.63.6",
+  "version": "0.65.1",
   "description": "SPS CLI — AI-driven development pipeline orchestrator",
   "type": "module",
   "main": "dist/main.js",
@@ -36,7 +36,9 @@
     "skills/writer",
     "skills/registry.yaml",
     "README.md",
-    "README-CN.md"
+    "README-CN.md",
+    "CHANGELOG.md",
+    "docs/openai-daemon-agent.md"
   ],
   "keywords": [
     "cli",
@@ -51,25 +53,29 @@
     "@biomejs/biome": "^2.4.10",
     "@playwright/test": "^1.59.1",
     "@types/node": "^25.5.0",
-    "@vitest/coverage-v8": "^4.1.2",
+    "@vitest/coverage-v8": "^4.1.10",
     "knip": "^6.3.0",
-    "tsx": "^4.21.0",
+    "tsx": "^4.23.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.10"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.196",
     "@colbymchenry/codegraph": "^1.2.0",
-    "@coralai/agent-runtime": "^0.2.0",
-    "@hono/node-server": "^2.0.0",
-    "@openai/agents": "^0.11.6",
+    "@hono/node-server": "^2.0.11",
+    "@openai/agents": "0.13.5",
     "chokidar": "^5.0.0",
-    "hono": "^4.12.14",
+    "hono": "^4.12.32",
     "open": "^11.0.0",
     "openai": "^6.45.0",
     "yaml": "^2.8.3",
     "zod": "^4.4.3"
   },
+  "overrides": {
+    "@hono/node-server": "$@hono/node-server",
+    "fast-uri": "3.1.4",
+    "hono": "$hono"
+  },
   "exports": {
     ".": "./dist/main.js",
     "./server": {

package/project-template/.claude/hooks/openai/on-start.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# SPS openai worker hook · on-start
+# 运行时机:openai worker 每轮开始前(经 sps 调用,bash 执行,不需可执行位)。
+# 可用环境:SPS_HOOK_EVENT / SPS_CWD / SPS_SESSION_ID / SPS_RUN_ID。
+# 底座预留,当前留空 = no-op。日后在此加逻辑(务必快速返回;超 10s 会被杀,失败不阻断 worker)。
+exit 0

package/project-template/.claude/hooks/openai/on-stop.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# SPS openai worker hook · on-stop
+# 运行时机:openai worker 每轮结束后(成功/失败都跑;经 sps 调用,bash 执行)。
+# 可用环境:SPS_HOOK_EVENT / SPS_CWD / SPS_SESSION_ID / SPS_RUN_ID。
+# 底座预留,当前留空 = no-op。注:卡片完成后的建图谱/记忆落库由 sps 编排层做,不在此脚本。
+exit 0