diff --git a/.task/archive/feature-agent-stack-audit-remediation-b1.md b/.task/archive/feature-agent-stack-audit-remediation-b1.md new file mode 100644 index 00000000..6799d70c --- /dev/null +++ b/.task/archive/feature-agent-stack-audit-remediation-b1.md @@ -0,0 +1,184 @@ +# feature/agent-stack-audit-remediation-b1 任务卡 + +任务主记录：PR #685 https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/685；状态：已完成（合入前闭合）；owner：weichen + +## 基线与授权 + +- 权威仓：ssh://git@192.168.3.2:2222/weichen/Agent-System-Dev.git；目标分支：main；R0（initial_base_sha）= d9e9c0560a2767539f4415b579adbeff86a22ba6 +- 工作区：/home/weichen/projects/Agent-System-Dev-wt-feature-agent-stack-audit-remediation-b1（worktree）；分支：feature/agent-stack-audit-remediation-b1 +- 分支类型：standalone；root_target：main；immediate_target：main；accepting_requirements：false +- 需求分流：verdict=NEW；selected_initiative=无；requirement_sha256=14019d085070900db07365351975abf0915c3b1fc34ef0d05c85fe975c9ac834；triage_receipt=/tmp/triage-remediation-b1-1792595736.json；receipt_sha256=0de1f5ad5737d0839f79d7098faced9f6f9366ca1a17486083b8439749dea27e + +- 授权与交付终点：用户已批准按方案实施第一批（U1-U7、U10）。范围内连续推进：agent-per-unit 逐单元实施、host 权威验证、组件分支提交、Backend 嵌套 gitlink 与 Dev 组合指针更新、组合验证、独立 Review、PR/CI/合入。终点为第一批全部单元收口。未授权：部署、真实数据迁移、发布、第二批 U8/U9/U11、功能增量 A1-A4、A2A 互通。 +- 交付模式：goal-first（目标、范围和交付终点一次确认；范围内连续推进） +- 实施执行：agent-per-unit（配置：AGENT-EXECUTION.md） +- 合入执行：agent（已授权交付范围内，Review 通过、冲突解决且当前 HEAD 的 CI 通过后合入） +- 人工决策点：仅限目标/范围/验收变更、重大取舍、高后果操作或无法自动判定的业务验收 +- 当前阶段：组合验证与交付；当前增量：第一批 U1-U7、U10 全部实施完成 +- host 记录：为使 U7 可按 agent-per-unit 执行，deps/agent-command 缺少组件级 AGENT-EXECUTION.md（其余四个目标仓均有且 validate: ok），host 按 agent-intent 同版模板补齐并以执行配置身份提交到该组件任务分支；理由与差异记录于本卡。 +- 流程依据：仓库根目录 policy/delivery.md（归档后仍按仓库根目录定位） + +## 目标与非目标 + +**目标**：按已批准方案（docs/superpowers/plans/2026-10-21-agent-stack-audit-remediation-plan.md，基线 d9e9c0560a）修复第一批 F01-F10、F13：执行隔离（U1/U2）、失败结果真实语义与恢复安全（U3）、权限缓存版本化（U4）、意图快照与生成校验（U5）、Backend 意图受理（U6）、命令隔离与回执（U7）、Backend 用户/项目配置路由（U10）。每单元以原触发条件回归阻断为验收，正常路径不退化。 + +**非目标**：U8/U9/U11（第二批）；A1-A4 功能增量；A2A 互通（F16）；全库接口替换、幂等平台、分布式执行；部署/迁移/发布；不把工作区路径检查宣称为 OS 沙箱。 + +## Agent 实施收据 + +路由与 fail-stop 规则见根目录 AGENT-EXECUTION.md 与 policy/delivery.md；每次尝试一行，原始日志留在源码外收据路径。 + +单元包由 host 写于 /tmp/agent-stack-b1/.json（network=false、external_cost=false 均为声明）；波次：A=U1(native)+U3(squad)+U5(intent) 并行；B=U2(native)+U4(squad)+U10(backend)；C=U7a(command)+U6(backend，依赖 U5 嵌套指针)；D=U7b(backend cmdbus，依赖 U7a)。同仓单元串行 apply。 + +| 单元 ID | 预期范围 | 配置摘要 | 角色 | 候选顺序 | attempt | CLI/模型 | 终态 | transport | fallback | 源码外收据路径 | +|---|---|---|---|---|---|---|---|---|---|---| +| agent-stack-b1-u1-native-workspace | native: adapters/native/backend.go+test, runtime/tools/{exec,jail,atomic}.go+test | digest 见 /tmp/agent-stack-b1/u1-run.json | implementation | [cursor, antigravity, pi-glm, pi, codex] | 1 | cursor-agent-stable | success | refs/agent-exec/e10eca84…/18a9b3caba61 → native 81e5bf3（transport 273213a 重写为规范提交） | 否 | /tmp/agent-stack-b1/u1-run.json | +| agent-stack-b1-u5-intent-snapshot-generated | intent: intent/（fold/registry/catalog/recognizer/slots/generator+tests） | digest 见 /tmp/agent-stack-b1/u5-run.json | implementation | 同上 | 1 | cursor-agent-stable | success | refs/agent-exec/357b5d70…/90a2c1b0488f → intent 765a7e7 | 否 | /tmp/agent-stack-b1/u5-run.json | +| agent-stack-b1-u7a-command-isolation | command: registry.go/result.go/conformance/+tests | digest 见 /tmp/agent-stack-b1/u7a-run.json | implementation | 同上 | 1 | cursor-agent-stable | success | refs/agent-exec/243aef44…/2e0a169b7174 → command fe7987d | 否 | /tmp/agent-stack-b1/u7a-run.json | +| u2-native-session-contract | native: contract.go/backend.go/session/tree.go/tools+regression tests | digest 见 /tmp/agent-stack-b1/u2-run.json | implementation | 同上 | 1 | cursor-agent-stable | success | transport f7a3ff39 重写为规范提交（基于 81e5bf3） | 否 | /tmp/agent-stack-b1/u2-run.json | +| u4-squad-resolver-config | squad: squad/backend.go+config_identity.go, adapters/native/register.go+tests | digest 见 /tmp/agent-stack-b1/u4-run.json | implementation | 同上 | 1 | cursor-agent-stable | success | squad 3a98d873 → aa15a5d 规范提交 | 否 | /tmp/agent-stack-b1/u4-run.json | +| u10-backend-scoped-config（首次） | backend: internal/app|runtime|squadadapter | digest 见 /tmp/agent-stack-b1/u10-run.json | implementation | [pi, codex]（cursor/agy 临时禁用） | 1 | pi MiniMax-M3 | failed-unknown（fail-stop：退出码 0 但无有效终态记录） | 无 transport，不采用 | 否 | /tmp/agent-stack-b1/u10-run.json；现场保留 /tmp/agent-exec-1000/b627ce2c41c90bea0d9f78270819d419 待对账 | +| u10-backend-scoped-config（重派） | 同上；包修正：allowed_paths 补嵌套 deps gitlink，禁止 -modfile 变通 | digest 见 /tmp/agent-stack-b1/u10b-run.json | implementation | [pi, codex] | 1 | pi MiniMax-M3 | success | transport 4c08cd8 → backend 80faf3e 规范提交 | 否 | /tmp/agent-stack-b1/u10b-run.json | +| u3a-native-result-fidelity | native: exec/、adapters/native/、runtime/loop.go | digest 见 /tmp/agent-stack-b1/u3a-run.json | implementation | 同上 | 1 | cursor-agent-stable | success | transport bf3e151 → native 5c0d2d8 规范提交 | 否 | /tmp/agent-stack-b1/u3a-run.json | +| （随 U10 重派）嵌套 agent-intent 指针 765a7e7 | backend deps/agent-intent bump | host 提交 406cffd | host | — | — | host | done | 406cffd | host 直接提交（gitlink 集成） | — | — | +| u6-backend-intent-admission | backend: intentgate/route/server/workflow | digest 见 /tmp/agent-stack-b1/u6-run.json | implementation | [pi, codex] | 1 | pi MiniMax-M3 | success | transport 0dff5ee → backend 0e55875 规范提交 | 否 | /tmp/agent-stack-b1/u6-run.json | +| （随 U6）嵌套 agent-command 指针 fe7987d | backend deps/agent-command bump | host 提交 e8d0c9b | host | — | — | host | done | e8d0c9b | host 直接提交（gitlink 集成） | — | — | +| u3b-squad-result-recovery（首次） | squad: squad/、adapters/native/ | digest 见 /tmp/agent-stack-b1/u3b-run.json | implementation | 同上 | 1 | cursor-agent-stable | failed-unknown（fail-stop；cursor TLS 会话前故障，553B 日志、零改动，现场 /tmp/agent-exec-1000/287d14d44c37c0336519417b92c5cc5a 保留） | 无 | 否 | /tmp/agent-stack-b1/u3b-run.json；对账：日志证明未建立会话、workspace 零改动，环境瞬断，重派 | +| u3b-squad-result-recovery（重派） | 同上 | digest 见 /tmp/agent-stack-b1/u3b2-run.json | implementation | [cursor（后禁用）， antigravity（后禁用）， pi, codex] | 2 | cursor-agent-stable | failed-unknown（"Cannot use this model: auto"，48B 日志、零改动；与已记录配额耗尽一致）→ 禁用 cursor（squad 4e65577） | 无 | 否 | /tmp/agent-stack-b1/u3b2-run.json；现场 /tmp/agent-exec-1000/b7ed6a71… | +| u3b（第 3 次） | 同上 | digest 见 /tmp/agent-stack-b1/u3b3-run.json | implementation | [antigravity, pi, codex] | 1 | agy gemini | failed-unknown（400 FAILED_PRECONDITION 地区限制，0 token、零改动）→ 禁用 agy（squad 后续提交） | 无 | 否 | /tmp/agent-stack-b1/u3b3-run.json；现场 /tmp/agent-exec-1000/8fd18fc9… | +| u7b-backend-receipts | backend: internal/cmdbus、internal/server | digest 见 /tmp/agent-stack-b1/u7b-run.json | implementation | [pi, codex] | 1 | pi MiniMax-M3 | success | transport 3a2b548 → backend 4030449 规范提交 | 否 | /tmp/agent-stack-b1/u7b-run.json | +| u3b（第 4 次） | 同上 | digest 见 /tmp/agent-stack-b1/u3b4-run.json | implementation | [pi, codex] | 1 | pi MiniMax-M3 | success | transport 5a00e3c → squad 23f161b 规范提交 | 否 | /tmp/agent-stack-b1/u3b4-run.json | +| u6-repair-boundary | backend: server 测试改经 intentgate | digest 见 /tmp/agent-stack-b1/u6r-run.json | repair | [pi, codex] | 1 | pi MiniMax-M3 | success | backend 49c1259 | 否 | /tmp/agent-stack-b1/u6r-run.json | +| u3b-repair-sqlite-test（首次） | squad: adapters/sqlite 测试 | digest 见 /tmp/agent-stack-b1/u3br-run.json | repair | 同上 | 1 | pi MiniMax-M3 | blocked（实现完成但验证环境缺嵌套 deps，包修正后重派；现场保留 b0f0f936…） | 无 | 否 | /tmp/agent-stack-b1/u3br-run.json | +| u3b-repair-sqlite-test（重派） | 同上；包补嵌套 deps | digest 见 /tmp/agent-stack-b1/u3br2-run.json | repair | [pi, codex] | 1 | pi MiniMax-M3 | success | squad 0f1daa8 | 否 | /tmp/agent-stack-b1/u3br2-run.json | +| gitlink-integration 1-4 | Dev 顶层/嵌套指针级联对齐 | host 集成 | implementation | [cursor,…] | 各 1 | cursor / antigravity? / pi | success×4 | 76766356/d31c7b55/3ae7605f/647fa51c | 否 | /tmp/agent-stack-b1/gitlink{,2,3,4}-run.json | + +## 关联方向与规划 + +- 适用状态：待核对（无适用规划时说明原因） +- 主记录路径/版本：待核对（路径按仓库根目录定位，归档后不变；只引用唯一正文） +- 对应里程碑：待核对 + +## 需求分析 + +| ID | 描述 | 项目符合度及依据 | 优先级 | 验收条件 | 依赖 | 结论 | +|---|---|---|---|---|---|---| +| R1-R7 | 方案 Requirements 节（执行与权限/输入恢复可核对性） | 与方案一致，逐条映射到 U1-U7、U10 | P1 | 方案各单元验收行 | U2←U1，U6←U5，U7b←U7a | 已确认 | + +## 方案与计划 + +- 方案引用：docs/superpowers/plans/2026-10-21-agent-stack-audit-remediation-plan.md（本分支 d3161347，审计基线 d9e9c0560a） +- 实施计划引用：本卡「Agent 实施收据」节前导说明（波次与依赖） +- 测试计划引用：方案 Verification Contract；各单元先用 F-ID 触发条件做最小回归，最终候选执行组合验证 + +## 阶段记录 + +| 阶段 | 对象版本 | 状态 | 决策/执行者 | 时间 | 依据 | +|---|---|---|---|---|---| +| 需求拆解 | 本卡 | 已完成 | host | 2026-10-21 | 用户批准第一批 | +| 需求评估 | 分流收据 | 已完成 | host | 2026-10-21 | verdict=NEW | +| 需求表确认 | 本卡 R1-R7 | 已完成 | host | 2026-10-21 | 方案 Requirements | +| 方案设计 | 方案文档 d3161347 | 已完成 | 前序会话 | 2026-10-21 | F01-F16 | +| 实施计划 | 本卡波次表 | 已完成 | host | 2026-10-21 | U1-U7/U10 依赖 | +| 实施与自检 | 全部 10 单元 + 2 修复完成；组合 make test PASS（verify-combo-make-test4.json exit=0） | 已完成 | agent-per-unit + host 验证 | 2026-10-21 | verify-*.json 全部 exit=0 | +| 正式测试与验收 | Dev 76766356→647fa51c 组合 | PASS | host | 2026-10-21 | make test（worktree/governance/boundaries/pins/libs/core/backend/frontend/ui/agentcmd） | +| 代码 Review | 待定 | 待执行 | — | — | — | +| 合入 | 待定 | 待执行 | — | — | — | +| 合入核验与收口 | 待定 | 待执行 | — | — | — | + +## 探索试验与迭代 + +| 增量/试验 | 假设 | 范围 | 判断和停止条件 | 授权/决策依据 | 结果 | 变更影响 | 需重审补测 | +|---|---|---|---|---|---|---|---| +| 待定义 | — | — | — | 待核对 | NOT_RUN | 待评估 | 待评估 | + +## 同步记录 + +| 节点 | sync_base_sha | tested_head_sha | checked_at | +|---|---|---|---| +| 启动 | d9e9c0560a2767539f4415b579adbeff86a22ba6 | d9e9c0560a2767539f4415b579adbeff86a22ba6 | 2026-10-21T15:17:41Z | + +## 证据（Evidence） + + +| 时间(UTC) | 命令 | 被测HEAD | exit | 来源 | sha256(16) | +|---|---|---|---|---|---| + +## 交付调度 + +- 调度状态：未入队；调度记录：无 +- entry_id：无；attempt_id：无；窗口执行者：无 +- 固定候选：无（base/head、组件与相关配置引用实际尝试） +- 调度依据：policy/delivery.md#合入调度 +- 固定后证据：源码外 RECEIPT；实际结果后按授权原样导入和闭合 + +## 结果与验证 + +- 结果： +- 验证：<结论摘要 PASS/FAIL/SKIP/NOT_RUN 逐项；逐条证据由 make evidence 写入上方证据表> +- 影响与剩余项： + +## 规划进展与下一步 + +- 本次推进/剩余：待核对（依据实际成果更新适用方案/规划） +- 首选下一任务：待核对（无适用规划、已完成或受阻时如实说明，不虚构任务） +- 推荐依据：待填写 +- 前置条件/待确认：待核对 +- 预期产物/验收条件：待定义 +- 重复任务核对：待核对（已有/在途任务、PR 与规划记录） +- 启动授权：未授权（建议不自动启动新任务，仍须明确授权） + +## 合入与清理 + +- Review 记录：独立 CLI 评审单元 agent-stack-b1-independent-review（pi-glm attempt1 success，收据 /tmp/agent-stack-b1/review4-run.json）；结论 APPROVE（0 blocker / 0 major / 5 minor 非阻塞跟进项）；报告 .task/reviews/2026-10-21-agent-stack-b1-independent-review.md；被审对象 d55e57dd vs main b25846d2 +- 冲突记录：NOT_RUN（最新目标同步、冲突处置、组合兼容核验及复审/补测） +- CI 记录：NOT_RUN（当前 HEAD 完整 SHA、全部必需检查、运行链接、执行身份及 GATE 结果） +- CI 记录：f23d1df7 首 轮三 job Checkout 失败——五个组件 pin 仅存本地；已推送组件分支 fix/agent-stack-audit-b1 至各自 origin（native ac91b84 / squad 0f1daa8 / intent 765a7e7 / command fe7987d / backend b614180），本提交重触发 CI +- 合入记录：NOT_RUN（交付授权范围、PR、被核验 HEAD、合入 SHA、目标分支及内容核验） +- 清理记录：NOT_RUN（授权依据、写者退出确认、worktree/分支/任务卡处置） + + +```json +{ + "summary_schema": 1, + "source": "SELF", + "timestamp": "2026-10-21T15:16:36.646637+00:00", + "command": "make precheck", + "exit_code": 0, + "cwd": "/home/weichen/projects/Agent-System-Dev", + "before_head": "d9e9c0560a2767539f4415b579adbeff86a22ba6", + "after_head": "d9e9c0560a2767539f4415b579adbeff86a22ba6", + "branch": "main", + "target_branch": "main", + "target_head": "d9e9c0560a2767539f4415b579adbeff86a22ba6", + "root_target": "main", + "immediate_target": "main", + "before_tracked_diff_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "after_tracked_diff_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "output_tail": [ + "make[1]: Entering directory '/home/weichen/projects/Agent-System-Dev'", + "[repo] branch=main head=d9e9c0560a", + "[remote] origin/main=d9e9c0560a ahead=0 behind=0", + "[tree] clean submodules_drift=0 uninit=0", + "[worktrees] linked=5", + "[recycle] merged un-recycled branches: fix/ci-rdm-pin-materialization", + "[initiatives] local cards (not authoritative): none", + "[hooks] core.hooksPath=scripts/hooks（pre-commit/post-merge 实际接线）", + "[facts] policy/facts.md 6 条事实均在有效期内", + "[required-reading] core/baseline.md, workflows/delivery.md §1, policy/delivery.md", + "[R0] d9e9c0560a（完整：d9e9c0560a2767539f4415b579adbeff86a22ba6）", + "[worktree] before-sync: recursive component checks passed", + "[verdict] READY — 保留本次 precheck receipt 后建任务工作区：PRECHECK_RECEIPT=/tmp/task-precheck.json make task-start NAME=feature/your-branch", + "make[1]: Leaving directory '/home/weichen/projects/Agent-System-Dev'" + ], + "output_sha256": "774b7616a7c39f1933001f482966329eebfb9b7ba3983a29959d38392265dac6", + "receipt_sha256": "282b6b21a2d7d06db1ac80d250f73d0ddfe9dedc917ac12c83a2af0e5e692e9b", + "receipt_path": "/home/weichen/.cache/agent-system-dev/evidence/282b6b21a2d7d06db1ac80d250f73d0ddfe9dedc917ac12c83a2af0e5e692e9b.json" +} +``` + +## 闭合记录（合入前折叠） + +- 本卡在 PR #685（https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/685）合入前闭合并归档，随该 PR 一同合入。 +- 该 PR 的合并提交即本任务的落地记录。 +- 合入后无需回填，也无需单独的闭合 PR。 diff --git a/.task/reviews/2026-10-21-agent-stack-b1-independent-review.md b/.task/reviews/2026-10-21-agent-stack-b1-independent-review.md new file mode 100644 index 00000000..3e17de16 --- /dev/null +++ b/.task/reviews/2026-10-21-agent-stack-b1-independent-review.md @@ -0,0 +1,90 @@ +# Independent Code Review — feature/agent-stack-audit-remediation-b1 + +- Reviewer: independent CLI review session (agent-stack-b1-independent-review unit) +- Date: 2026-10-21 +- Review object: Dev worktree branch `feature/agent-stack-audit-remediation-b1` @ `d55e57dd` (merged tip) versus main @ `b25846d2`; five pinned components diffed old-pin → new-pin: + - deps/agent-native `2fc66be6` → `ac91b843` + - deps/agent-squad `c7121bda` → `0f1daa8b` + - deps/agent-intent `651a2e1e` → `765a7e71` + - deps/agent-command `4f583ca3` → `fe7987dc` + - modules/backend `528e3a4c` → `b6141800` +- Plan: docs/superpowers/plans/2026-10-21-agent-stack-audit-remediation-plan.md (audit baseline d9e9c0560a) +- Claimed scope: batch 1 = U1, U2, U3a/U3b, U4, U5, U6, U7a/U7b, U10. +- Method: read-only review of `git diff` per component plus Dev-level files; focused package tests where this worktree permits (see Verification runs). This review made no changes other than this report file. + +## Findings + +### Blockers + +None. + +### Major + +None. + +### Minor + +- **M1 — SessionScope identity string can collide (native).** `adapters/native/contract_bind.go:60-66` builds the scope identity as `tenant+"/"+project+"/"+session`. Distinct scopes containing `/` can collide (tenant `a/b` + project `c` vs tenant `a` + project `b/c`), which would bind two identities to the same hashed transcript file (contract_bind.go:72-77) and pass the exact-match check in `bindSessionScope` (adapters/native/backend.go:645-669). Today product identifiers do not contain `/`, so no legal path regresses; recommend length-prefixed or JSON-encoded identity in a follow-up. +- **M2 — Reflection/JSON "probe" of statically present fields (squad).** `adapters/native/register.go:217-247` marshals the native result through JSON to discover `SideEffects/Canceled/Aborted`. The squad module is pinned to native `ac91b843`, where these fields exist at compile time; direct field copy is identical, simpler, and the "deps 尚未跟进" rationale in the comment cannot occur in a statically linked Go build. Behaviorally equivalent today; flagged as avoidable indirection that can silently mask future field renames (JSON key drift would quietly fall back to "possible"). +- **M3 — `trustedUnknownOpID` does not survive JSON roundtrip (command).** `result.go:44-49` (unexported flag) + `result.go:76-95` (Validate): an Unknown receipt carrying a trusted OperationID fails `Validate()` after a marshal/unmarshal cycle. Verified by grep that no in-repo path re-validates a deserialized receipt (backend persists audit *envelopes*, not receipts; `internal/cmdbus` has no ExecReceipt unmarshal), so nothing breaks today — but the library contract is sharper than its docs admit. Suggest documenting the roundtrip limitation or providing a rehydration constructor. +- **M4 — Stale recovery header comment (squad).** `squad/engine.go:1053-1069` still states "auto 允许一次重试", but `HitlAuto` now falls into the `default:` reconciliation branch (engine.go:1137-1178) and no longer auto-retries running steps without a trusted record. The code is the intended F05 tightening; only the comment contradicts it. +- **M5 — Writable preflight does not cover `delegate_task` (native).** U2 preflight (adapters/native/backend.go:213-227) rejects non-empty Writable with exec/MCP/host tools, but the workspace registry still registers `subagent.Register` (backend.go:278) and code orchestration (`run_tool_script`). `run_tool_script` only invokes registry tools (which enforce the allowlist, runtime/tools/registry.go:369-388) and bans the interpreter, so the residual exposure is a spawned sub-agent not inheriting the parent's write-set. The plan scoped this batch's preflight to "进程/MCP/宿主工具"; a follow-up decision on subagent scoping is warranted, not a blocker here. +- **M6 — Canceled mapping keyed on ctx, not on the result (native).** `adapters/native/contract.go:100-105` maps to `OutcomeCanceled` only via `errors.Is(ctx.Err(), context.Canceled)`. A `runRes.Canceled`/`StopAborted` run that is *not* caused by ctx cancellation falls to the failed branch (with `Retryable=false` because backend.go:385-396 already clears it, so no unsafe retry — only the outcome label is less precise). Edge case; native abort paths set ctx. + +### Notes + +- **N1 — Squad `AGENT-EXECUTION.md` disables cursor/antigravity adapters** (component diff, +10/-2). Operational agent-execution config, not product code; documented on the task card with fail-stop rationale. It will ride the component branch into the component repo — restore `enabled: true` as the file itself instructs. +- **N2 — Command `AGENT-EXECUTION.md` added (+67).** Host-documented deviation (component lacked one; template parity with agent-intent), recorded on the task card. +- **N3 — Executor failures without `SideEffects=none` lose auto-retry.** `squad/workflow.go:455-459` + `squad/port.go:99-117` intentionally default missing qualifier to "possible" (no bounded retry). This is the specified KTD4/U3 behavior change ("缺少副作用证明的失败默认禁止自动重放"), covered by `TestSideEffectsPossibleNotRetried` / `TestSideEffectsNoneRetriedWithinBounds`; third-party executors must now declare `none` to keep transient retry. Listed so the API change is visible to integrators. +- **N4 — Generated-command ActionRef now resolves against the full snapshot**, not only the top-k catalog (`intent/recognizer.go:384-437` `resolveActionRef`, replacing `generatedSpecOf`). Deliberate widening that fixes F08's "合法异名目标被拒"; slot keys/values and dispatch still gated by `validateProvidedSlots` (intent/slots.go:174-214) and backend admission (internal/server/intent_admission.go:41-63). +- **N5 — Pin coherence verified.** Nested gitlinks agree at every level: intent `765a7e71` (native→deps, squad→deps, backend→deps), native `ac91b843` (squad→deps, backend→deps), command `fe7987dc` (backend→deps), squad `0f1daa8b` (backend→deps). +- **N6 — Audit-failure unknown receipts keep the trusted ID** via `unknownReceipt`/`NewUnknownAfterExecution` (internal/cmdbus/cmdbus.go:690-712, deps/agent-command/result.go:64-71); rejected never carries an ID (cmdbus.go:706-712). Confirms U7b's F10 requirement end-to-end with `TestCommittedWithAuditFailureKeepsOperationID`. + +## Unit-by-unit review (spec lens, with trigger-condition evidence) + +| Unit / Finding | Trigger in plan | Blocking change in diff (file:line) | Verdict | +|---|---|---|---| +| U1 / F01 | reasoning Targets with `../`, absolute, or escaping symlink wrote files before delivery validation | Authorization pass before any write: `pathInWriteSet` + `tools.Resolve` per target, then a second write loop (adapters/native/backend.go:336-378); zero-write asserted by `TestBackendReasoningProfileRejectsPathEscape` (traversal/absolute/symlink, safe.md also absent) | blocked | +| U1 / F03 | ExecConfig env nil → host env inherited | `normalizeExecEnv` nil→empty whitelist at registration and per-process (runtime/tools/exec.go:42-51, 165); tests nil/explicit-empty/whitelist | blocked | +| U1 / F15a | CombinedOutput unbounded before 64KiB trim | Continuous drain into fixed head+tail ring (`headTailBuffer`, exec.go:192-276; `runProcess` 157-175); bounded-memory + cancel-drain tests | blocked | +| U2 / F02 | Same WorkDir reused across SessionScopes; Writable set on workspace | Scope-keyed transcript `transcriptPathForScope` (contract_bind.go:72-77); fail-closed identity binding incl. refusal to adopt identity-less stores (backend.go:645-669); Writable enforced on write/edit/multi_edit (runtime/tools/registry.go:356-388, builtin.go:106-109/155-158/339-342) with exec/MCP/host preflight rejection (backend.go:213-227); empty scope keeps legacy path (compat verified) | blocked | +| U2 / F04 | Torn JSONL tail then append → mid-file corruption | `repairTailLocked` final-line-only repair, valid fragment gets newline, invalid truncated, mid-file untouched (runtime/session/tree.go:156-234); torn/missing-newline/mid-file/append-then-load tests | blocked | +| U2 / F15b | CapText declared but Text empty | Contract captures final assistant text and surfaces it; pure-text success no longer forces implicit file delivery (`withAllowEmptyTargets`, contract.go:62-66, 88-96); `TestContractPureTextSuccessCarriesText` | blocked | +| U3a | canceled treated as retryable; side-effect honesty | Result gains Canceled/Unknown/SideEffects with `EffectiveSideEffects` (exec/backend.go:79-105); loop propagates ToolCalls and Canceled, clears Retryable on cancel (runtime/loop.go:202-213, 343-361); adapter maps definite-preflight → none, tool dispatch → possible, run-started transport failure → Unknown+possible (backend.go:334-341, 381-409, sideEffectsForTools 593-599) | blocked | +| U3b / F05 | success=patches-only; failed-with-patches promoted; file-presence completion on recovery; new ExecutionID per retry | `(nil,nil)`/nil-result stable failure (workflow.go:429-439); promotion path removed — patches materialize only after explicit Success, or as diagnostics without flipping status (workflow.go:444-461); canceled/aborted never retried (workflow.go:440-452, port.go:121-123); recovery trusts only `step_terminals.json` records, otherwise `needs_reconciliation` (engine.go:1070-1180, models.go:299-314); `RunWaitingReconciliation` resume inspects without advancing (engine.go:1199-1206); ExecutionID reused across attempts and recovery (workflow.go:402-409, engine.go:1130-1133; `TestRetryReusesExecutionIDAndDeadline`) | blocked | +| U4 / F06 | config update reuses stale executor cache | Cache key adds `ConfigIdentity(role)` + factory generation (squad/backend.go:171-175, config_identity.go:14-33 incl. BashPermission); Register/RegisterInstance invalidate per-backend cache (backend.go:62-75); concurrency gates persist across generations and update max on resolve (backend.go:182-285); allow→deny / factory swap / gate-cap tests | blocked | +| U5 / F07(intent) | caller mutates registry input or returned nested objects | Deep clone at Register/compile/Snapshot/Options/Catalog boundaries (intent/fold.go:57-129, registry.go:488, 520-528, 554, 588-592, catalog.go:36-60,142); isolation asserted in u5 tests | blocked | +| U5 / F08 | generated fallback bypasses slot validation / loses risk metadata; valid alias rejected | Generated Top built from authoritative compiledSpec with full slot validation, missing/invalid projection, risk/confirm/action metadata (recognizer.go:384-437, slots.go:174-214); classifier scores NaN/Inf/out-of-range rejected and quantized before threshold (recognizer.go:176-201, 322-330); non-finite/low-confidence keep ambiguous | blocked | +| U6 / F09 | InvalidSlots dropped; router only sees Start; text-only params | Gate projects Missing *and* Invalid with reasons + risk/confirm/action (intentgate/gate.go:42-52, 198-232); router blocks dispatch unless `Complete()` and structured Clarification (route/route.go:60-72, 173-180); unsupported cancel/set_slot honestly fall back to turn without dispatching same-sentence Start (route/route.go:83-90, 121-131); params mapped per declared schema with type casts and required-param admission (server/intent_admission.go:41-113); high-risk still confirmed by cmdbus (`TestHighRiskCommandStillRequiresConfirmation`) | blocked | +| U7a / F07(command) | ParamsSchema/ExposeAsTool shared references | Deep copy in/out of Register/Resolve/List (registry.go:37-47, 62-66, 117, 124-130); mutation conformance test | blocked | +| U7b / F10 | any handler error → "no side effects rejected"; audit failure drops op ID | `ErrNotExecuted`/`NotExecuted()` marker; unmarked handler errors → Unknown with trusted op ID (cmdbus.go:75-118, 536-553); audit-failure path preserves ID for committed/accepted/unknown and never for rejected (cmdbus.go:687-712); confirm-card unknown lands warn terminal with reconciliation note (cmdbus.go:615-640); owner/project-scoped bounded operation query + endpoint (cmdbus.go:263-296, server/operation_query.go) | blocked | +| U10 / F13 | squad resolves model/base/key from default account/project | Factory resolves entire route from the run's effective snapshot + profile via the same `ResolveChatModel`/`OpenRouteClient` rules as direct path (app/squad_native.go:57-84, runtime/run_config.go:17-62, squad_runner.go:83-86, llm.go:255/604); fallback to default only when host lacks the Settings port; owner-crossing secret tests (`TestSquadNativeOptionsNeverBorrowsAnotherOwnerSecret`), route-contract EOF parity test | blocked | + +## Regression lens + +- **Empty SessionScope:** legacy fixed transcript path, no identity checks, `Targets` defaulting preserved (backend.go:144-146, contract_bind.go:72-74). Verified by `TestLegacyTranscriptStillLoads` and empty-scope branches in regression tests. +- **Zero-value results:** `ExecResult{}` zero value = Success false, SideEffects empty → read as "possible" (port.go:110-117) → stable failure, no panic (`TestNilNilResultIsStableFailure`, `TestSideEffectsZeroMeansLegacy`). +- **Default configs:** U10 keeps default-account fallback only for hosts without the run Settings port (squad_native.go:60-66); `routeContractFor` logic untouched, only re-exported (`llm.go:604`). +- **Retry semantics change is intentional and covered** (Note N3): transport failures from executors that do not declare `SideEffects=none` now fail fast instead of text-heuristic retry — exactly the F05/KTD4 remedy. +- **Route fallback for legal matched intents:** `unconsumedCommandKinds` only fires when cancel/set_slot/chitchat/handoff commands are present; the rule funnel emits those only on expectation-hit/ambiguous branches, and matched+complete emits Start alone (intent/command.go:88-113), so normal command dispatch is unaffected (`TestValidSlotsReachHandlerMappedPerSchema`). + +## Scope lens + +All component diffs map to declared units: native (U1/U2/U3a), squad (U3b/U4), intent (U5, generator.go comment-only), command (U7a), backend (U6/U7b/U10 + mechanical `OpenRouteClient` rename and nested gitlinks). Dev-level changes are the task card, the plan document, and the five gitlinks. Out-of-unit but documented: squad `AGENT-EXECUTION.md` adapter disablement and command `AGENT-EXECUTION.md` addition (Notes N1/N2 — execution-infra config, explicitly recorded on the task card; no product code outside units). No undeclared product behavior changes found. + +## Test lens + +New tests assert the original trigger conditions, not just happy paths: F01 asserts zero writes for all three escape classes; F02 asserts no shared transcript, resume-with-matching-scope, and refusal to adopt identity-less stores; F04 covers torn tail, missing newline, mid-file error, repair-then-append; F05 covers patches-only success, failed-with-full-patches stays failed, canceled/aborted not retried, side-effect-gated retry bounds, all four recovery quadrants (record/files × present/missing), ExecutionID+deadline reuse; F06 covers tighten/loosen/factory-swap/tool-change/cache-reuse/parallel-first/in-flight-cap; F07 mutation attempts on both registries; F08/F09 missing vs invalid vs unknown-key vs required-param blocks with reasons; F10 unknown-with-ID, not-executed-stays-rejected, audit-failure-keeps-ID, repeated-confirm-once, cross-owner query scope; F13 owner-secret isolation, project layer, direct-route parity, default fallback. + +## Verification runs (this review worktree) + +Focused tests with `GOWORK=off`, per-directory, foreground: +- deps/agent-command: `go test ./...` — ok (2 packages, includes new registry/result/conformance tests). +- deps/agent-native: `go test ./runtime/session/ ./runtime/tools/` — ok (torn-JSONL, env whitelist, bounded buffer, writable allowlist suites). `adapters/native` — NOT_RUN here: nested deps (error-code-system etc.) are uninitialized in this review worktree and cannot be materialized offline; covered by the recorded green combination run. +- deps/agent-intent, deps/agent-squad, modules/backend: NOT_RUN here for the same missing-nested-deps reason (backend imports all components). Covered by the host-recorded combination `make test` PASS on the batch candidate (verify-combo-make-test4.json, exit=0), which this review did not re-run per packet instruction. + +## Verdict + +REVIEW VERDICT: APPROVE + +Blocking reasons: none. The diff implements the declared batch-1 units with trigger-condition regression coverage; the six minor findings (M1-M6) are quality follow-ups that do not block merge: none of them breaks a legal existing path, all have safe defaults (fail-closed), and the intentional behavior changes (retry tightening, cancel/no-retry semantics) are the specified F05 remedies with test coverage. Recommend filing M1-M5 as follow-up increments and restoring the temporarily disabled agent-execution adapters (N1) per the file's own instruction. diff --git a/deps/agent-command b/deps/agent-command index 4f583ca3..fe7987dc 160000 --- a/deps/agent-command +++ b/deps/agent-command @@ -1 +1 @@ -Subproject commit 4f583ca3eeeb07a56a714c5086de84dcd6ad2980 +Subproject commit fe7987dc03e96d59705a547e2099cdea13affcd2 diff --git a/deps/agent-intent b/deps/agent-intent index 651a2e1e..765a7e71 160000 --- a/deps/agent-intent +++ b/deps/agent-intent @@ -1 +1 @@ -Subproject commit 651a2e1e03c4326888ef9f742ce592140ae30ab8 +Subproject commit 765a7e717737dcbe0d684ece3b7e2b38923c53d5 diff --git a/deps/agent-native b/deps/agent-native index 2fc66be6..ac91b843 160000 --- a/deps/agent-native +++ b/deps/agent-native @@ -1 +1 @@ -Subproject commit 2fc66be65201232ea38ba64d457efad5565d869d +Subproject commit ac91b8436ea9f5c80861bb4b1b1534ede0b9918f diff --git a/deps/agent-squad b/deps/agent-squad index c7121bda..0f1daa8b 160000 --- a/deps/agent-squad +++ b/deps/agent-squad @@ -1 +1 @@ -Subproject commit c7121bda2a681dc46078350f7929e56e142db57f +Subproject commit 0f1daa8b89b158cc4a0fe85d33050f48cedf129a diff --git a/docs/superpowers/plans/2026-10-21-agent-stack-audit-remediation-plan.md b/docs/superpowers/plans/2026-10-21-agent-stack-audit-remediation-plan.md new file mode 100644 index 00000000..395aae1f --- /dev/null +++ b/docs/superpowers/plans/2026-10-21-agent-stack-audit-remediation-plan.md @@ -0,0 +1,311 @@ +--- +title: Agent Stack Audit and Remediation - Plan +type: fix +date: 2026-10-21 +artifact_contract: ce-unified-plan/v1 +product_contract_source: ce-plan-bootstrap +execution: code +--- + +# Agent Stack Audit and Remediation - Plan + +## Goal Capsule + +对 Agent-Native、Agent-Squad、Agent-Intent、Agent-Command 及其 Backend 接入做源码审查和外部协议核对，先修复现有能力的契约缺陷，再补充影响实际使用的功能。 +本次交付是待用户审阅的方案；业务实现、迁移、部署和发布尚未授权或执行。 +建议保留现有四库分层，分批兑现可验证结果，不重写 Agent 平台、不迁移到新的编排框架。 + +- 第一批：执行边界、失败结果、权限缓存、意图校验、命令回执、用户/项目配置。 +- 第二批：持久化适配、队列限额、过程事件。 +- 后续增量：多轮意图闭环、恢复诊断、目录召回、外部互通。 +- 停止条件：批准批次的回归和适用组合验证通过，完成对应 Review、PR/CI 与收口；未批准增量不顺带实施。 + +## Product Contract + +### Scope and Evidence + +审查日期为 2026-10-21。以下 SHA 是本次实际检出；Dev 启动检查确认与当次远端 main 一致、组件无漂移，不能据此声称各组件远端没有更新。 + +| 对象 | 路径 | 审查 SHA | +|---|---|---| +| Dev | 仓库根 | `d9e9c0560a2767539f4415b579adbeff86a22ba6` | +| Native | `deps/agent-native` | `2fc66be65201232ea38ba64d457efad5565d869d` | +| Squad | `deps/agent-squad` | `c7121bda2a681dc46078350f7929e56e142db57f` | +| Intent | `deps/agent-intent` | `651a2e1e03c4326888ef9f742ce592140ae30ab8` | +| Command | `deps/agent-command` | `4f583ca3eeeb07a56a714c5086de84dcd6ad2980` | +| Backend | `modules/backend` | `f084d10aa5ea2e4ad2ab4e6eb1268d3e83c6e991` | + +发现以当前源代码及现有测试的检查为依据，均给出触发条件；不是线上事故结论，也不是穷尽性安全认证。 +研究子任务报告了 Native、Squad 的本地测试和仓外探针；主线程已核对关键源代码，但未重放这些执行，也未将其导入正式 evidence，故本方案不以这些报告作为通过凭证。 +修复回归、组合测试、GATE、独立 REPLAY、生产验收均为 `NOT_RUN`。 +旧 N1/N2/N3、Q1/Q2/Q3 和 I1/I2 提案只用于理解历史意图，不把旧“已完成”或“待实现”表述当作当前事实。 + +### Existing Responsibilities + +| 模块 | 当前已有能力 | 应保持的边界 | +|---|---|---| +| Agent-Intent | 规则/守卫/预期、槽位验证、语义裁决、生成兜底、目录与诊断 | 识别和提出动作；不授予执行权限 | +| Agent-Command | 命令资产/注册表、危险分级、执行四态、审计信封 | 保持无 I/O；实际授权、执行、幂等持久化由宿主负责 | +| Agent-Native | 模型流、Agent 循环、工具/MCP、预算/取消、会话、checkpoint、外部适配 | 执行一次受约束任务；路径授权不冒充 OS 沙箱 | +| Agent-Squad | 规划、图调度、leader、HITL、黑板/邮箱/移交/任务板、存储与队列适配 | 协作与步骤推进；依赖注入执行器，不复制单 Agent 内核 | + +这些库并非一条固定串行流水线：普通对话可以直接执行 Native，系统命令由宿主消费 Intent 并经 Command 受理，多步任务才进入 Squad。 +真正的问题集中在边界传递和失败路径，而不是缺少更多拓扑或工具数量。 + +### Findings + +严重级别按触发后的影响排序，生产暴露面另列。P1 不表示已观察到线上损害。 +下列行号是本次基线定位，实施时还须按符号及新基线复核。 + +| ID | 优先级与触发条件 | 源码证据 | 后果与影响边界 | +|---|---|---|---| +| F01 | P1：reasoning 请求的 Targets 含 `../` 或指向根外的符号链接 | Native `adapters/native/backend.go:324-333` 先直接写文件，后续才做交付校验 | 可先写出工作区再返回失败；应在任何副作用前拒绝非法目标。上层自行校验可降低暴露，不能代替库契约 | +| F02 | P1：同一 WorkDir 被不同 ContractRequest.SessionScope 复用；或设置 Workspace.Writable | Native `adapters/native/contract.go:42-51` 未映射这些约束；`backend.go:260-273` 使用固定 transcript，仅记录字符串 scope | 跨 scope 上下文串读及写集约束失效。当前 Backend 未发现 Contract() 消费，不据此断言产品跨租户泄露 | +| F03 | P1：ExecConfig 已启用解释器但 Env 为 nil | Native `runtime/tools/exec.go:25-26,139` | nil 被交给 os/exec，继承宿主环境，与完整白名单合同不符。Backend 当前解释器装配显式给出 env，该具体入口已有缓解 | +| F04 | P1：崩溃留下半截 JSONL 尾行，随后续写 | Native `runtime/session/tree.go:155-181,194-207` | Load 只在内存忽略尾行，Append 紧接损坏字节；下一次读取变为中段 JSON 错误。完整 JSON 无换行也需处理 | +| F05 | P1：Executor 成功仅含 patches、失败带 patches，或 running 步骤崩溃后自动恢复 | Squad `squad/workflow.go:403-418,455-464`、`squad/engine.go:1055-1109` | 正常路径成功未物化而失败、失败可被提升为成功；恢复路径文件齐全即判 completed，缺文件则直接重跑，未核对可信终态和外部副作用。Native 自行落盘只能掩盖其中的成功物化问题 | +| F06 | P1：同名 role/model/backend 的权限或并发配置更新 | Squad `squad/backend.go:38-48,86-123`；`adapters/native/register.go:104-106` | 缓存键忽略 BashPermission/其他配置，Register 也不清缓存；allow→deny 后可能继续复用旧执行器。产品每次新建 resolver 可缓解，长期服务/公共库使用仍受影响 | +| F07 | P1：调用方修改注册输入或公开返回的嵌套对象 | Intent `intent/fold.go:37-57`、`registry.go:289,494,531,557`；Command `registry.go:60,98,107` | Intent.Action/Examples 与部分目录数据、Command.ParamsSchema/ExposeAsTool 共享引用；可在 revision/锁之外改变已验证定义。这是同进程 API 合同缺陷，不等于任意远端用户已能修改 | +| F08 | P1：启用意图生成兜底，并返回缺槽/非法槽值或异名 Action | Intent `intent/recognizer.go:333-414`、`catalog.go` | 生成路径未共用完整槽位校验，Top 丢风险/确认/动作元数据，handler 槽位查表键不一致；显式 Action 的合法异名目标又会被拒。Backend 开关 `runtime.intentGenerator` 默认 false | +| F09 | P1：规则识别到非法槽位，宿主收到 Start + Clarify | Backend `internal/intentgate/gate.go:167-178`、`internal/route/route.go:66-72`、`internal/server/server.go:1206-1230` | InvalidSlots 被丢弃，Router 只取 Start。命令入口还只传 text，未传已识别槽位；可能误路由或被后续 schema 拒绝。不能据此断言任何高危命令都能绕过 cmdbus 确认 | +| F10 | P1：handler 已有副作用后报错，或成功后审计存储失败 | Command `result.go:41-43`；Backend `internal/cmdbus/cmdbus.go:433-438,539-559` | 任意 handler error 被归为“无副作用 rejected”；审计失败改 unknown 却丢已生成 op ID，且库禁止 unknown 携带 ID，影响对账及安全重试 | +| F11 | P1/P2：使用 SQLiteStore 保存协作状态，或在 async/on_exit 模式退出时 checkpoint 失败 | Squad `adapters/sqlite/runstore.go:77-119`；`squad/workflow.go:41-53` | Mailbox/Handoffs/Board 未持久化；相同 JSON 文本作 map key 会覆盖解码目标；flush 错误被吞。Checkpoint 失败不等于已完成外部动作回滚，应单独报告持久化失败 | +| F12 | P2：同一 runtime 下多个 agent 同时或连续领取任务 | Squad `adapters/sqlite/queue.go:226-239` | 只数 agent 的在途任务，取两种 cap 的最小值不能限制 runtime 总并发；当前产品是否启用该独立队列须在实施时核验 | +| F13 | P1：当前用户/项目有独立模型路由配置，进入 Squad | Backend `internal/app/app.go:340-364`、`internal/runtime/squad_runner.go:83-95`、`internal/runtime/llm.go:604-608` | 小队从默认账户/空项目读取 base/key 等，入口只覆盖 model，可能把用户模型名与默认端点/凭据混用；ReasoningSplit、RouteContract 也与 direct 路径不一致 | +| F14 | P2：小队同名工具多次调用，或工具返回错误 | Native `runtime/loop.go:43-45,777-836`、`adapters/native/backend.go:405-418`；Squad `squad/port.go:66`；Backend `internal/runtime/squad_runner.go:49-54` | CallID 在旧过程契约中丢失，宿主用工具名代替；结束事件实际文本在 Text，宿主读 Detail 并恒写 ok。结果归属、摘要与成功状态失真 | +| F15 | P2：执行工具输出大量数据；或 Contract 调用要求纯文本 | Native `runtime/tools/exec.go:149,175`、`adapters/native/contract.go:25,67-77` | CombinedOutput 先全量缓冲再裁剪，64KiB 只是展示上限；声明 CapText 却不填 Text。分别并入 U1、U2 的合同修复 | +| F16 | P2：使用 A2A adapter 接入符合 1.0 的外部服务 | Squad `adapters/a2a/card.go:24-46`、`executor.go:19-25,135,171`、`conformance_test.go` | 声称 1.0，却仍用旧 `message/send`、`tasks/get`、小写状态与旧 Card；测试假服务复制了同一套自定义结构。当前 Backend 无该依赖，不阻塞本地核心修复，但不得声称 1.0 互通已验证 | + +### Requirements + +**执行与权限** + +- R1. 不合法路径/写集/会话身份必须在模型或工具副作用发生前拒绝；支持空约束的既有兼容语义。 +- R2. 后续运行采用新的权限配置；不能因旧缓存或错误配置作用域扩大能力或混用用户凭据。 +- R3. 失败、取消、不确定、已完成保持真实语义；文件存在不是成功证据，未知不能无条件重试。 + +**输入、恢复与可核对性** + +- R4. 规则与生成路径共用权威动作定义和槽位验证；缺失/非法/歧义必须保留到宿主。 +- R5. 状态快照和注册表对外隔离可变数据，读者不能绕过更新协议改变定义。 +- R6. 恢复后保留协作状态，保存失败可见；runtime/agent 并发上限独立生效。 +- R7. 回执保留可信关联标识；事件保留工具调用身份、真实错误和实际输出；用户可分辨完成、等待与待核对。 + +**功能增量** + +- R8. 在已批准修复收口后，单独选择下一批功能；不把提案中的全部建议自动视为实施范围。 + +--- + +## Planning Contract + +### Technical Decisions + +- KTD1. 保留四库边界和现有 Go 模块；通过当前接口增量修复。现有功能覆盖足够广，整体重写会扩大兼容性与验证成本。 +- KTD2. 识别输出只作为动作建议。执行时按当前 actor/project 授权、命令 schema、确认凭证再判断；目录可见不代表允许执行。MCP 对工具 annotations 的不可信要求也支持这一边界，见 S1。 +- KTD3. 以宿主当前运行的有效配置构造 model/base/key/协议及完成性规则，作为同一配置快照传入；不随意开通新的 provider 协议。工具权限可在执行前进一步收紧，不能由旧构造缓存恢复。 +- KTD4. 先验证执行结果，再物化候选文件，再做交付检查；失败候选可以作为诊断保留，但不得发布为成功。结果 Unknown 与可重试性分别判断，不把 HTTP/网络错误等同于“尚未执行”。 +- KTD5. Native 会话和 Squad 协作状态分别在原有存储上修复。检查点、工具副作用和产品聊天历史是不同记录；不新增统一分布式执行平台，不承诺跨外部系统 exactly-once。恢复设计参考 S2 的线程状态/跨线程存储区分。 +- KTD6. Command 保持无 I/O。扩展可表达副作用不确定性的 handler 结果，并复用宿主已有 operation/outbox 存储；unknown 可携带已可信生成的 ID。可查询操作记录与权限检查必须真实存在，不能只改枚举注释。 +- KTD7. 两个四态合同不强行合并：Command 描述动作受理/生效，Native 描述 Agent 执行终态；Squad 通过适配保留差异。命令 accepted 不是 Agent succeeded，创建确认卡也不是业务动作完成。 +- KTD8. A2A 先明确支持版本并以官方独立 fixture 验证；需要兼容旧协议时显式分版本，不把旧协议重新标成 1.0。是否投入完整互通是后续增量决策，见 S3。 + +### Component Flow + +```mermaid +flowchart TB + U[用户输入] --> H[Backend 身份与项目上下文] + H --> I[Intent 识别与槽位验证] + I --> C[Command 宿主授权与确认] + I --> W[工作流或 Squad 编排] + I --> N[Native 单 Agent 执行] + W --> N + N --> T[经授权工具与外部能力] + C --> O[操作记录与回执] + T --> E[真实结果与过程事件] + W --> S[协作状态与 checkpoint] + E --> H + O --> H + S --> H +``` + +这张图表达边界关系，不要求所有输入都逐一经过四个库。 + +### Outcome Flow + +```mermaid +flowchart TB + R[请求] --> V{授权与参数有效} + V -->|否| X[Rejected: 未开始动作] + V -->|是| P{需要确认或异步处理} + P -->|是| A[Accepted: 保留可查询 ID] + P -->|否| E[执行动作] + A -->|授权确认或继续| E + E --> F{结果及记录是否确定} + F -->|已完成并可核对| C[Committed 或执行 Succeeded] + F -->|明确失败| D[Failed 或有依据的 Rejected] + F -->|无法确认| Q[Unknown: 保留 ID 与待核对原因] + Q --> Z[查询与对账: 禁止盲目重放] +``` + +取消请求同样需要确认执行侧状态；不能只因为本地 context 结束就声称远端动作已停止。 + +### Delivery Order + +第一批建议 U1-U7、U10：其中 U1-U4 先修 Native/Squad 执行与恢复基础，U5-U7 处理输入/命令合同；U10 的当前用户/项目配置问题与它们并行处理，不排在可选存储适配之后。 +第二批 U8、U9、U11：恢复适配、队列和事件一致性。 +每个批次在组件兼容提交落地后更新 Backend 嵌套 gitlink 和 Dev 组合指针，完成一次适用组合验证。 +同批只读研究可以并行；每个仓库写入单元按 `AGENT-EXECUTION.md` 新 session、受控 transport/admit 进入候选，由 host 验证与交付。 + +实施前重新确认当前代码、在途任务与远端分流；本文不会覆盖后续已修复问题，也不会复用过期 CI 结论。 +迁移脚本可以在隔离测试库验证，真实数据迁移、部署和发布另走授权边界。 + +--- + +## Implementation Units + +### U1. Native Workspace and Process Boundaries + +目标：修复 F01/F03 及 F15 的输出缓冲问题，落实 R1。 +文件：`deps/agent-native/adapters/native/backend.go`、`runtime/tools/exec.go`、现有 `runtime/tools/jail.go`/`atomic.go`；测试放 `adapters/native/backend_test.go`、`runtime/tools/exec_tools_test.go`。 +方案：复用已有工作区路径解析，目标在执行前预检，实际访问仍校验根内与 symlink；Env nil 归一为空白名单；子进程持续 drain 到有界头尾缓冲，不在结束后才限制内存。 +验收：合法目标正常产出；`../`、绝对路径和 symlink 逃逸在零外部写入前拒绝；nil/空/显式 env 分别验证；大输出与取消后子进程退出且缓冲有界。 +不把工作区路径检查描述为完整 OS 沙箱；并发敌对文件系统场景优先复用可提供根约束的文件 API。 + +### U2. Native Session and Contract Fidelity + +目标：修复 F02/F04 及 F15 的 CapText，落实 R1/R3/R6；依赖 U1 的文件访问边界。 +文件：`deps/agent-native/adapters/native/contract.go`、`backend.go`、`runtime/session/tree.go`、`exec/contract_spec.go`；测试放 `runtime/session/tree_test.go`、`adapters/native/contract_regression_test.go`（新增）及 `conformance/`。 +方案：将非空 SessionScope 绑定存储身份并在恢复前检查，Writable 限制贯穿可约束的文件工具；对于进程/MCP/宿主工具等无法兑现该写集的配置，本批在 preflight 明确拒绝非空 Writable，不假定根路径检查能限制任意进程。独占追加时修复半截尾记录/补齐合法无换行记录；中段损坏仍报错。保留真实文本输出，纯文本任务不强制隐式文件交付。 +验收：同 root 不同 tenant/project/session 不串上下文；已有匹配 scope 可继续；身份不明的旧文件不得自动归给新身份；只允许写指定路径；半截尾行恢复后可再读再写；纯文本成功的 Text 非空。 +兼容：空 scope 保持既有一次性/旧门面语义，不进行全库存量会话迁移；历史缺身份记录只在明确兼容路径读取。 + +### U3. Squad Execution Results + +目标：修复 F05，落实 R3；无先行依赖。 +文件：`deps/agent-squad/squad/workflow.go`、`leader.go`、`engine.go` 的 recoverInterrupted、`port.go`、步骤状态持久化及 `step_retry.go`、`adapters/native/register.go`；必要的 `deps/agent-native/exec/backend.go` 与适配器映射；测试 `squad/step_retry_test.go`、`squad/recovery_test.go`、`squad/attempt_test.go`、`squad/executor_result_contract_test.go`（新增）。 +方案：按 KTD4 统一普通步、IntentRunner 和 leader 委派的结果处理；显式处理 `(nil,nil)` 与物化错误。已有文件只能帮助诊断，不能覆盖执行器终态。 +当前旧 ExecResult/exec.Result 只有 Success/Retryable，不能承接 Unknown/SideEffects。本单元先以兼容新增的可选字段或等价的类型化错误保留这些信息，再让 retry 层消费；缺少副作用证明的失败默认禁止自动重放，不能继续只按错误文本推断可重试。已有明确未派发或纯读取失败仍可有界重试；无需在本批整体替换所有 Executor 接口。 +恢复入口同样消费持久化的终态与副作用证据。running 崩溃后，只有可信完成记录才能恢复为 completed，只有明确未执行或安全重放证据才能转 pending；其他情况保留待核对原因，禁止自动推进，沿现有中断恢复/HITL 入口处理。无交互模式明确返回需核对状态，不无限等待，也不伪称动作已失败。 +验收：成功 patches-only 正常完成；失败带完整 patches 仍失败；空结果稳定失败而不 panic；部分/非法 patches 不成功；取消/Unknown 不自动变成可重试失败。外部动作完成、终态未保存时崩溃，分别测试目标文件齐全/缺失，两种情况均不伪成功或自动重复动作。检查重复尝试仍复用 ExecutionID 和截止时间。 + +### U4. Squad Resolver Configuration + +目标：修复 F06，落实 R2；无先行依赖。 +文件：`deps/agent-squad/squad/backend.go`、`adapters/native/register.go`；测试 `squad/backend_test.go`、`adapters/native/register_test.go`。 +方案：后端工厂和角色执行配置有明确版本/摘要，更新时使相关缓存失效；限流身份与执行器配置身份分开，不能换版本便绕过同一角色并发上限。 +验收：allow→deny 收紧、deny→allow 显式放开、工厂替换、工具配置变化和限额变化正确；并行首次 Resolve 不重复构造；在途旧执行不会因新版本开启而突破总限额。 +在途任务已开始动作不承诺回滚；需要即时撤权的宿主继续在每次工具执行前检查。 + +### U5. Intent Snapshot and Generated Actions + +目标：修复 F07 的 Intent 部分与 F08，落实 R4/R5；无先行依赖。 +文件：`deps/agent-intent/intent/fold.go`、`registry.go`、`catalog.go`、`recognizer.go`、`slots.go`；测试 `intent/registry_test.go`、`intent/slots_catalog_test.go`、`intent/i2_test.go`。 +方案：补齐现有 clone 的输入/输出边界；目录保留权威 ActionRef；生成命令先解析回唯一 spec，再复用槽位校验和风险元数据；不得用 handler 字符串索引 spec-ID 槽位表。分类器输入同样隔离，拒绝非有限/越界分数并重检阈值。 +验收：修改原始 spec、SpecByID/Catalog/Options 不影响生效快照；规则与生成同动作同槽位得到等价结果；必填缺失、非法枚举/格式、未知槽位及 handler 重名均稳定处理；Action 指向不同命令 ID 仍可正确路由；低置信度不转 matched。 +拆成独立实施时沿“快照隔离”和“生成校验”两个有界 worker 包执行，不合成通用 schema 平台。 + +### U6. Backend Intent Admission + +目标：修复 F09，落实 R4；依赖 U5 的权威结果结构。 +文件：`modules/backend/internal/intentgate/gate.go`、`internal/route/route.go`、`internal/server/server.go`、必要的 `internal/workflow/` 消费点；测试 `internal/intentgate/gate_test.go`、`internal/route/route_test.go`、`internal/server/intent_admission_test.go`（新增）。 +方案：传递 missing/invalid 及澄清信息；区分“可开始澄清的流程草稿”和“可执行副作用的完整动作”。命令槽位按已声明 schema 映射，不能无类型地复制所有字符串；已有 text handler 保持兼容。高危动作仍由 cmdbus 确认。 +验收：缺槽和非法槽都不会直接执行业务动作；允许澄清的流程可挂起；校验通过后的槽位正确进入 handler；显式取消/纠正尚未实现时诚实回退，不能声明已支持。 + +### U7. Command Isolation and Receipts + +目标：修复 F07 的 Command 部分及 F10，落实 R3/R5/R7；与 U6 可独立。 +文件：`deps/agent-command/registry.go`、`result.go`、`conformance/`；`modules/backend/internal/cmdbus/cmdbus.go` 及已有 operation/outbox 的最小存储接口；测试 `deps/agent-command/registry_test.go`、`result_test.go`（不存在时新增）、`modules/backend/internal/cmdbus/cmdbus_test.go`、`account_write_fence_test.go`。 +方案：复制 ParamsSchema 与 ExposeAsTool；unknown 允许保留可信 OperationID；handler 区分明确未执行与执行后未知。优先按现有持久化记录提供经 owner/project 授权的查询；若所选命令没有操作记录，则把最小持久化与查询作为该命令适配的组成部分，不能宣布“有 ID 就可查询”。 +验收：外部修改返回 spec 不改注册表；成功后 audit 失败返回 unknown 且保留 ID；明确校验拒绝为 rejected；副作用后报错不伪称未执行；未知操作只核对、不自动重放；重复确认/跨用户查询不会重复执行或泄露结果。 +跨仓先落兼容库变更，再更新 Backend。完整通用幂等平台不在本批；新幂等键只在选定命令已有明确重复执行风险时设计。 + +### U8. Squad Durable State + +目标：修复 F11，落实 R6/R7；结果解释依赖 U3。 +文件：`deps/agent-squad/adapters/sqlite/runstore.go`、迁移入口、`squad/workflow.go` 与现有 checkpoint writer；测试 `adapters/sqlite/runstore_test.go`、`squad/checkpoint_test.go`。 +方案：SQLite 完整保存 Mailbox/Handoffs/Board；用明确字段到目标的序列解码，不用内容作 map key。终态保存、manifest 和 checkpoint flush 均检查错误，并在 EvRunCompleted/成功返回之前收敛；不能只在 defer 改 error 而此前已经发出完成事件。保存错误与业务终态分别可见，不能因此重复执行已完成业务动作。 +验收：FileStore/SQLite 同一合同 round-trip；恢复后继续收信/移交/认领；相同 clarifications/steering 都保存；sync/async/on_exit 的失败注入均可见；终态保存/manifest 失败不发伪成功事件；旧 schema 升级保留原数据。真实库迁移另行授权。 + +### U9. Squad Queue Capacity + +目标：修复 F12，落实 R6；可独立。 +文件：`deps/agent-squad/adapters/sqlite/queue.go`；测试 `adapters/sqlite/queue_test.go`。 +方案：一次原子 Claim 同时验证 agent 在途数和 runtime 总在途数，读取/计数错误拒绝认领；保留原租约和重领规则。 +验收：runtime cap=1 下两个不同 agent 只能领取一个；同 agent 跨 runtime 仍受 agent cap；并发 Claim 不超限；释放后可继续领取。未接产品的队列模块不因此新接入产品。 + +### U10. Backend Scoped Runtime Configuration + +目标：修复 F13，落实 R2；无需等全部库修复。 +文件：`modules/backend/internal/app/app.go`、`internal/runtime/model.go`、`llm.go`、`internal/squadadapter/entry.go`；测试 `internal/app/squad_config_test.go`（新增）、`internal/runtime/model_test.go`、`route_contract_eof_test.go`。 +方案：从当前 rc.Settings、run owner、profile 解析完整路由，direct/squad 复用现有配置规则；必要时增加窄的工厂函数。保持项目来源观察/授权限制，不能为接线一致性重新开启被明确禁用的直连工具。 +验收：两个用户不同配置与密钥来源不串用；项目覆盖生效；profile model 覆盖使用对应路由规则；MiniMax reasoning 分离和受限 EOF contract 一致；默认配置仍兼容；测试仅用合成密钥和本地 fake server。 + +### U11. Tool Event Fidelity + +目标：修复 F14，落实 R7；跨 Native→Squad→Backend。 +文件：`deps/agent-native/runtime/loop.go`、`exec/backend.go`、`adapters/native/backend.go`；`deps/agent-squad/squad/port.go`、`adapters/native/register.go`；`modules/backend/internal/runtime/squad_runner.go`；测试各层现有 host-tools/adapter/runner 测试。 +方案：向后兼容新增调用 ID 和真实错误/状态信息，按原语义传递 Text/Detail；宿主事件与最终 message parts 一致。并行回调使用受控串行聚合或局部锁，必要时修复共享 artifactList 的并发访问。 +验收：同名工具两次调用各自配对；失败/拒绝/取消不显示 ok；摘要来自实际结果；并行事件/工件无丢失、无 race；旧适配器字段缺省不得被推断为已确认成功。 +仅修事件合同，本单元不修改界面布局；若后续需要 UI 展示，先按 DESIGN.md 单列范围。 + +--- + +## Functional Follow-Ups + +以下是功能建议，不计入前述修复的默认实施范围。推荐顺序为 A1、A2、A3，A4 按真实外部对接需求启动。 + +| ID | 建议 | 用户收益 | 最小交付与验收 | +|---|---|---|---| +| A1 | 多轮意图闭环 | “把日期改到周五”“取消刚才的任务”能作用于明确对象 | 消费已有 set_slot/change_slot/cancel/expectation；绑定 owner/project/conversation/action/revision；歧义先澄清，过期回答不影响新任务；先覆盖一类真实业务动作 | +| A2 | 执行与恢复诊断 | 看清卡在哪里、能否恢复、是否还要等人 | 在现有 run/operation 查询上提供当前责任角色、等待原因、最后稳定 checkpoint、已知副作用、下一步；先做授权读 API，不先造大型控制台 | +| A3 | 能力目录召回与离线评测 | 不因目录固定 top-8 而遗漏低优先级能力，减少误启动 | 先建立脱敏评测集：否定/引用指令、多意图、错误槽位、过期确认、生成规则一致性；比较准确匹配、误执行、澄清率与成本，再决定是否需要检索或模型调整 | +| A4 | 明确版本的 A2A 互通 | 外部 Agent 任务可查询、可取消并诚实报告状态 | 修 F16；采用官方 fixture/独立服务验证 Card、方法、状态与身份；持久化远端 task ID，处理 auth-required、未知态、超时和取消回执；不自动重发 message/send | + +现有 Makefile 已显式覆盖若干 Squad 嵌套 go.mod，但未列 A2A 子模块。 +A4 启动时须纳入自己的验证入口，不能假设根 `go test ./...` 自动覆盖独立模块。 +不建议本轮新增更多拓扑、动态角色市场、全自动自我改进或向量平台；先用评测证明新能力确有收益。 + +--- + +## Verification Contract + +实施先用各 F-ID 的具体触发条件形成最小回归，禁止只补“函数能调用”的测试。 +不调用真实付费模型，不使用生产数据库，不将已设置的真实凭据输出到日志。 + +| 验证层 | 范围 | 通过判据 | +|---|---|---| +| 直接回归 | U1-U11 各自文件/包 | 原触发条件被阻断，正常使用不退化 | +| 合同验收 | 现有 conformance 与 adapter 边界 | Native 文本/文件/隔离合同，Squad 成功/失败/未知处理，Intent 规则/生成一致，Command 四态可对账 | +| 定向并发 | 注册表/缓存/队列/事件聚合 | 相关 `-race` 与原子认领用例通过，不机械扩大到所有包 | +| 故障恢复 | 截断 JSONL、存储错误、执行后响应丢失 | 恢复不丢协作状态，不伪称完成，不重复外部副作用 | +| 宿主集成 | 两个用户、项目覆盖、缺槽、确认、direct/squad | 权限与配置作用域一致，确认后只执行一次，结果与事件一致 | +| 组合 | 固定组件及 Backend 嵌套 gitlink | 每批最终候选执行项目规定的 `make test` 和必要构建，按当前门禁保存 SELF；当前 HEAD 必需 CI 为 GATE | + +库级测试成功不证明产品装配成功；fake 协议服务成功不证明外部协议兼容；启动 READY 不证明业务功能通过。 +对于缺少真实后端的可选路径，清楚标注 NOT_RUN，不阻断已批准且不依赖它的本地修复交付。 + +## Definition of Done + +- 已批准批次的 F-ID 均有对应修复、反例与正常路径验证；被新基线消除的项记录来源，不重复实现。 +- 变化的公共合同向后兼容或有明确迁移路径；错误语义和状态持久化可解释。 +- 组件 SHA、Backend 嵌套引用与 Dev 组合一致；当前候选通过适用验证、独立 Review 和必需 CI 后按项目规范合入。 +- 无未授权部署/真实数据迁移/发布；可选功能保持独立，用户业务验收不被工程自检替代。 + +## Appendix + +### Primary Research + +- S1. MCP Tools specification，核对版本 `2025-11-25`，研究日 2026-10-21：工具定义、结构化输入/输出与 annotations 信任边界。`https://modelcontextprotocol.io/specification/2025-11-25/server/tools`。影响 KTD2；未要求升级协议或引入 SDK。 +- S2. LangGraph Persistence 官方文档，研究日 2026-10-21：checkpointer 的线程状态与 store 的跨线程数据各有作用域。`https://docs.langchain.com/oss/python/langgraph/persistence`。影响 KTD5；仅借鉴状态边界，不引入 LangGraph。 +- S3. A2A `v1.0.1` 官方 specification 与 v1 变更说明，研究日 2026-10-21：协议方法、Agent Card 的 supportedInterfaces 和任务状态表示。`https://a2a-protocol.org/v1.0.1/specification/`、`https://a2a-protocol.org/v1.0.1/whats-new-v1/`。影响 F16/KTD8/A4；不混用开发中 PR 版本。 + +外部研究用于校验契约和改进方案，不能单凭行业实践宣判本项目缺陷。 +进一步获取 Go os/exec 与 LangGraph interrupts 网页时检索工具连接失败；本方案未把未获取内容列为外部证据。 + +### Remaining Decisions + +建议批准第一批 U1-U7、U10 后连续实施到各自可验收的集成结果，再进入第二批 U8、U9、U11。 +也可一次批准两批，但不因此纳入 A1-A4。 +需要用户确定的是实施批次与后续功能优先级；具体函数、补充字段和回归组织由实施者在上述合同内确定，不再逐文件请求许可。 +当前没有证据支持宣称线上已被利用；部署状态、真实模型行为和外部 A2A 互通仍待相应阶段验证。 diff --git a/modules/backend b/modules/backend index 528e3a4c..b6141800 160000 --- a/modules/backend +++ b/modules/backend @@ -1 +1 @@ -Subproject commit 528e3a4c1ff9b59c4df998f4fffb39f0b52dbbcd +Subproject commit b6141800cc8b4239ea03d4f1e7edc5486fc31116