pikasTech-agentrun/docs/reference/spec-v01-agentrun-mgr.md

v0.1 agentrun-mgr 服务规格

agentrun-mgr 是 AgentRun v0.1 的长驻管理服务。它是公共 RESTful API、durable facts、tenant policy boundary、runner claim、event append 和 terminal status 的 authority；业务客户端、CLI 和 runner 都不能绕过它直接写 Postgres。

在系统中的职责划分

• 提供 Manager 公共 API：创建和查询 run、提交 command、分页读取 events、查询 backend capability。
• 提供手动调度 API：为已创建的 run/command 显式创建 Kubernetes runner Job，并快速返回 job identity、attempt 和轮询入口。
• 提供 Runner 私有 API：runner register、claim run、lease heartbeat、poll commands、append events、ack command、上报 status。
• 校验并持久化 tenantId、projectId、workspaceRef、providerId、backendProfile、executionPolicy 和 traceSink。
• 执行最小 tenant policy boundary：只做 schema、allowlist、idempotency、secret scope 和 executionPolicy 范围检查；不内建 UniDesk/HWLAB 的业务授权。
• 使用 Postgres 保存 runs、commands、events、runners、backends、leases 和 migration ledger。
• 输出结构化 health/readiness、failureKind、redacted SecretRef 和 trace correlation。

内部架构

agentrun-mgr 运行在 agentrun-v01 namespace，长驻 Deployment/Service 名称使用 agentrun-mgr。v0.1 自研服务实现优先使用 Bun + TypeScript；具体 HTTP 框架不是规格边界，但源码必须保持可被 Bun 运行、测试和打包。服务必须保持以下边界：

• HTTP JSON API 是稳定跨服务边界；不使用 SSE、WebSocket、long-polling 或长同步 turn 请求作为 v0.1 必备能力。
• Postgres adapter 是唯一 durable store adapter；file、sqlite、JSONL 或内存状态只能用于自测试。
• Migration 必须在 readiness 前完成或显式 fail fast，不能以空 schema 静默启动。
• Provider credential、Codex auth/config、Postgres DSN 明文不进数据库、event、trace、日志或 CLI 输出。
• Manager 可以保存 SecretRef 和 credential source reference，但不得读取 provider Secret 值后存库。

API 接口说明

公共 API 的 v0.1 范围：

GET  /health
GET  /health/live
GET  /health/readiness
POST /api/v1/runs
GET  /api/v1/runs/:runId
GET  /api/v1/runs/:runId/events?afterSeq=0&limit=100
POST /api/v1/runs/:runId/commands
GET  /api/v1/runs/:runId/commands/:commandId
POST /api/v1/runs/:runId/runner-jobs
GET  /api/v1/backends

面向 HWLAB v0.2 canary 的手动调度 API 目标见 spec-v01-hwlab-manual-dispatch.md。runner-jobs 只显式启动当前 run/command 的 runner Job，不扫描 pending queue，不等待完整模型 turn；自动 scheduler 仍是 deferred 能力。后续 durable cancel API 必须与同一 run/command 状态机衔接，不能让 HWLAB 直接删除 Kubernetes Job 作为正式取消语义。

Runner 私有 API 的 v0.1 范围：

POST  /api/v1/runners/register
POST  /api/v1/runs/:runId/claim
PATCH /api/v1/runs/:runId/lease
GET   /api/v1/runs/:runId/commands?afterSeq=0&limit=20
POST  /api/v1/runs/:runId/events
PATCH /api/v1/runs/:runId/status
POST  /api/v1/commands/:commandId/ack

所有 API 成功和失败响应都必须是 JSON。失败响应至少包含 failureKind、message 和 trace correlation；不得出现空 stdout/空 response 被误判为成功的情况。

Run 与 Command 合同

POST /api/v1/runs 必须持久化以下字段：

字段	v0.1 规则
tenantId	必填，只做 allowlist/schema 校验，默认候选为 unidesk、hwlab。
projectId	必填，例如 pikasTech/unidesk、pikasTech/HWLAB。
workspaceRef	必填，描述 source/worktree/workspace，不由 runner 猜测。
providerId	必填，例如 G14、D601；只表示目标 provider，不直接授予业务权限。
backendProfile	必填，v0.1 allowlist 为 codex 与 deepseek；两者共享 Codex stdio backend kind。
executionPolicy	必填或由 manager 显式补齐默认值，至少包含 sandbox、approval、timeout、network 和 secretScope。
traceSink	字段必须存在；可以为 null 或显式 sink。

POST /api/v1/runs/:runId/commands 必须支持 idempotency key。相同 key 且 payload hash 相同应返回既有 command；相同 key 但 payload hash 不同必须结构化失败。

Tenant Policy Boundary

v0.1 不实现独立 policy engine。Manager 只做基础边界收敛：

• 校验 tenant/project/provider/backendProfile 是否在 v0.1 允许集合内；当前 backendProfile 允许 codex 与 deepseek。
• 校验 workspaceRef 形态存在且与 tenant 请求一致；不替 tenant 判断某个 repo 操作是否业务授权。
• 校验 executionPolicy 不扩大 sandbox、network、approval、timeout 和 secretScope。
• 校验 secretScope 只引用 spec-v01-secret-distribution.md 中允许的 SecretRef，且存在与 backendProfile 同名的 provider credential；manager 只校验引用形态，不读取 Secret 值。
• 对 HWLAB live device mutation、UniDesk production deploy、GitHub issue/PR 写入等业务授权，Manager 只记录字段和审计事件，不把业务规则硬编码成通用门禁。

最小 Observability 合同

• events append-only，单 run 内 seq 单调递增。
• 每个 run 必须最终出现 terminal_status，或保持明确 non-terminal status 并可查询 lease/heartbeat。
• failureKind 至少能区分 schema-invalid、tenant-policy-denied、secret-unavailable、runner-lease-conflict、backend-failed、provider-auth-failed、provider-unavailable、infra-failed、cancelled。
• health/readiness 必须返回 Postgres reachable、schema migration ready、SecretRef redacted 状态和 build/source metadata。
• 日志、event、trace、health 和 diagnostics 不得输出 provider credential、Codex auth/config 内容、DSN password、token 或 URL credential。

测试规格

T1 Manager health/readiness

阅读 AGENTS.md、本文和 spec-v01-postgres.md，然后用 RESTful API 手动测试 agentrun-mgr 的 /health/live 和 /health/readiness。确认响应为 JSON，包含 serviceId、Postgres readiness、migration 状态、source commit、SecretRef redacted 状态；不得输出任何 Secret value。

T2 Run schema 与 tenant boundary

阅读本文和 spec-v01-services.md，然后调用 POST /api/v1/runs 创建包含 tenant/project/workspace/provider/backend/execution/trace 字段的 run。确认缺失字段、非法 tenant、非法 backend、backendProfile=deepseek 但缺少 matching provider credential、或扩大 secretScope 都返回结构化 failureKind，合法请求持久化后可用 GET /api/v1/runs/:runId 查询。

T3 Command idempotency

阅读本文，然后对同一个 run 使用相同 idempotency key 提交相同 command 两次，再提交 payload hash 不同的第三次。确认前两次返回同一个 command，第三次结构化失败，且所有响应为 JSON。

T4 Runner claim 与 event pagination

阅读本文和 spec-v01-agentrun-runner.md，然后让两个真实 runner 尝试 claim 同一个 run。确认只有一个 owner 成功，另一个返回 runner-lease-conflict 或等价 failureKind；随后分页读取 events，确认 seq 单调、不重复、不丢失。

T5 手动 runner Job 调度 API

阅读本文和 spec-v01-hwlab-manual-dispatch.md，然后用 RESTful API 创建 tenantId=hwlab 的 run、提交 command、调用 POST /api/v1/runs/:runId/runner-jobs。确认响应短返回 JSON，包含 runId、commandId、attemptId、jobName、namespace、log/pod identity 和后续 poll 入口；重复 idempotency key 不创建重复 job。

规格的实现情况

规格项	状态	说明
agentrun-mgr 服务规格	已定义	本文为 v0.1 manager 权威。
Manager REST API	已实现/已通过主闭环	已有 run、command、event、backends、runner register、claim、lease heartbeat、poll、ack、status、runner Job 创建和 health/readiness 的 HTTP JSON API；真实 runtime 已通过 RESTful API 主闭环。
手动 runner Job API	已实现主路径/待增强	POST /api/v1/runs/:runId/runner-jobs 已可创建 Kubernetes runner Job；HWLAB canary 还需固化 idempotency、响应 schema 和 cancel 衔接。
Tenant policy boundary	已实现最小边界	v0.1 已做 schema、tenant/backend allowlist、executionPolicy 和 secretScope 结构校验；业务授权仍由 UniDesk/HWLAB 自己判定。
deepseek backendProfile allowlist	已实现/已通过主闭环	Manager validation、backend capability 和 matching SecretRef 校验已支持 deepseek；真实 runtime 已经通过 CI/CD 发布并确认 Postgres migration 002_v01_backend_profiles 应用。
Postgres durable adapter	已实现/已通过主闭环	live runtime 通过 DATABASE_URL 使用 Postgres durable store；memory store 仅用于显式 self-test/dev。见 spec-v01-postgres.md。
Observability 最小合同	已实现主路径	events append-only、terminal status、failureKind、health/readiness store 状态、runner claim/lease/backend events 和 Secret/DSN redaction 已进入 manager；集中 trace 和部署级观测仍属后续工作。
durable cancel API	待实现	类型和 cancelled failureKind 已存在；面向 HWLAB /cancel 还需 public cancel API、runner 观察和 backend interrupt 闭环。