Compare commits

...
20 Commits
Author SHA1 Message Date
cflmyandCursor 41587f319e release: v2.1.5 agent reliability workbench
Bump CLI/wasm/ext to 2.1.5; document ResourceView, ToolSpec, CheckpointV2,
EffectLedger, EKC warm-load, and web short/read lane isolation.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 15:39:36 +08:00
cflmyandCursor 298fbd51ea feat(workbench): expose CSV preview text for TablePreview
ResourceView csv render now includes bounded text alongside sanitized
HTML so clients can build interactive tables without re-parsing HTML.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 14:45:05 +08:00
cflmyandCursor 265dfdbcc4 feat(workbench): emit JSON source text and code line locators
ResourceView now carries render.text for JsonPreview/CodePreview and
honors locator.line with capped line locators for navigation.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 14:23:00 +08:00
cflmyandCursor 42a43f5ffd feat(workbench): honor ResourceView locator.page as focus_locator
PDF blob views echo the requested page for client navigation without
claiming text extract or OCR.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 14:18:38 +08:00
cflmyandCursor 037a963547 feat(workbench): emit blob_ref for PDF and image ResourceView
Client visual preview consumes the blob; extract/OCR capabilities stay
false so QA-10 honesty holds without cutting the preview path.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 14:14:17 +08:00
cflmyandCursor a32638e935 fix(workbench): drop trailing blank lines from CSV ResourceView
Avoid an empty last table row when files end with a newline.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 14:03:40 +08:00
cflmyandCursor 43eebe5671 feat(workbench): add bounded JSON and CSV ResourceView renderers
Serve static application/json and text/csv previews with outline/table
limits and flip extract_formats availability for those media types.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 13:55:35 +08:00
cflmyandCursor e833dc05e2 feat(agent): attach effect ledger watermark on CheckpointV2 save
Persist effects_watermark with resume checkpoints and pass resume_id into
step tool calls so mutating tools share a stable logical_run scope.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 13:48:45 +08:00
cflmyandCursor 11bb7ef277 feat(agent): wire EffectLedger through mutating run_tool
Prepare/start/commit write and execute tools with idempotent dedupe, and refuse
blind retry while ledger state is unknown or interrupted mid-flight (MA-T03).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 13:44:45 +08:00
cflmyandCursor 6bd90bb2d0 feat(agent): ship output channels, ContextPackV2, and effect ledger
Open AgentOutputV1/ContextPackV2 capability bits and add EffectLedgerRecordV1
so CheckpointV2 write auto-resume only unlocks on a safe watermark.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 13:28:03 +08:00
cflmyandCursor 4683f2e067 feat(agent): ToolSpec registry with authorize-before-call
Add ToolSpecV1 register/search/describe/prepare so CALL and native paths share one schema gate; unauthorized and invalid-arg prepares fail with zero executions.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 13:18:55 +08:00
cflmyandCursor 5912164039 feat(agent): CheckpointV2 atomic resume and AgentErrorV1
Replace bare resume writes with temp/fsync/rename, mark legacy loads as manual_review, and expose bounded read-only retry decisions while keeping write auto-resume closed without a ledger.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 11:03:39 +08:00
cflmyandCursor 303c06f773 feat(workbench): freeze agent protocols and ship ResourceView v1
Lock M-A0 Error/Tool/Checkpoint/Output/Context fixtures with capability bits off, and land M-A3 static md/txt/code ResourceView (no-exec) behind resource.view.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 10:59:59 +08:00
cflmyandCursor a1086fd6c3 docs: plan cross-repo agent reliability delivery
Lock M-A*/Q-A* sequencing, F01–F20 mapping, and first-slice gates on top of the 2026-10-27 designs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 10:49:20 +08:00
cflmy 6ffe5ceb19 docs: expand executable knowledge design notes 2026-10-27 02:10:54 +00:00
cflmy 6b568aff3d docs: design reliable agent capabilities 2026-10-27 02:10:25 +00:00
cflmyandCursor 16f26d7d60 fix(knowledge): warm-load IR for preflight/find/reuse queries
Stop full recompile on every knowledge preflight by writing ekc/graph/ir.json
and loading it unless --refresh or missing projections, cutting chat预检 wall time.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 09:18:27 +08:00
cflmyandCursor b8265a92aa fix(web): stop short/read/control from filling execute slots
Isolating every short invoke on the 2-slot worker pool caused no_slot under
normal traffic; keep short paths on parent (execute already off-process) and
background-reap after observer disconnect so zombies release slots.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 08:56:56 +08:00
cflmyandCursor 9af929971c fix(web): disconnect≠cancel and isolate short/read/control lanes
Observer SSE close no longer cancels execute by default; short/read/control
bypass parent INVOKE_LOCK via isolated admission, with read_lane=1 and gold samples.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 08:44:07 +08:00
cflmyandCursor 2c4fa4bb05 fix(ppa): install only rustc/cargo/std and use disk TMPDIR
Repeated --without flags were ignored by install.sh (last wins), so
rust-docs still filled /tmp and hit quota; prefer --components= and
a home-cache work dir instead of tmpfs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-26 19:13:48 +08:00
65 changed files with 6465 additions and 158 deletions

No files matched your search

+3 -1
View File
@@ -126,9 +126,11 @@ jobs:
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights
- **v2.1.5**:Agent 可靠工作台——ResourceView / ToolSpec / CheckpointV2 / EffectLedger · EKC ir.json 暖机 · Web 短读槽隔离
- **v2.1.5**: Agent reliability workbench — ResourceView / ToolSpec / CheckpointV2 / EffectLedger, EKC ir.json warm-load, web short/read lane isolation
- **v2.1.5 ext**:扩展包同步 2.1.5 / Ext pack 2.1.5
- **v2.1.4**:默认隔离 HTTP execute(ADR 0009)——worker 池 / `--call-lib-path` · `/_runtime/*` · MR-01 双流金样例 · `runtime.isolated_execution=1`
- **v2.1.4**: Default isolated HTTP execute (ADR 0009) — worker pool / `--call-lib-path`, `/_runtime/*`, MR-01 dual-stream gold, `runtime.isolated_execution=1`
- **v2.1.4 ext**:扩展包同步 2.1.4 / Ext pack 2.1.4
- **v2.1.3**:知识工作台运行时——ModelSelection/RunContext/usage · view document 只读嵌入 · LLM selection/messages/cancel · agent selection e2e
- **v2.1.3**: Workbench runtime — ModelSelection/RunContext/usage, view document read-only embed, LLM selection/messages/cancel, agent selection e2e
- **v2.1.1**:可执行知识主链——BoundCall · NarrativeRef · 来源/适用期 · patch/extract · 整代 CURRENT + closure · 发票示例 113
+32
View File
@@ -8,6 +8,38 @@
### Changed
## v2.1.5 — 2026-10-27
### Highlights
**Agent 可靠工作台 + EKC 热路径**:ResourceView(JSON/CSV/PDF/image `blob_ref`、locator 页/行)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制面与 execute 槽隔离。CLI · wasm · ext **2.1.5**。
```bash
git checkout v2.1.5 && cargo build --release
marqdo ext add web # CDN / Releases → 2.1.5
```
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——工作台协议与 Agent 运行时合同,不新增 Markdown 标记。
### Added
- **ResourceView v1**:有界 JSON/CSV 渲染;PDF/image `blob_ref`;`locator.page` / 行定位;CSV `text` 供 TablePreview。
- **Agent 合同**:ToolSpec 注册与 authorize-before-call;CheckpointV2 原子 resume;AgentErrorV1;输出通道;ContextPackV2;EffectLedger(含 mutating `run_tool` 水印)。
- **Workbench fixtures/schemas**:`tests/workbench_contracts` 协议金样例。
- **EKC `ir.json` 快照**:`marqdo knowledge` 写入 `.marqdo/ekc/graph/ir.json`;查询命令暖机热加载,免全量重编译。
- **`--refresh`**:`knowledge preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify` 可强制重编译。
### Fixed
- **工程预检热路径**:`knowledge preflight`(及 find/reuse 等)默认不再每次 `ensure_compiled` 全量 compile,修复聊天「工程预检」墙钟过长。
- **Web 槽隔离**:`short`/`read`/`control` 不再填满 execute 槽;disconnect≠cancel。
- **CSV ResourceView**:去掉尾部空行伪影。
### Changed
- 查询类 knowledge CLI:**缺投影才 compile**;CI / 源变更请先 `marqdo knowledge` 或 `--refresh`。
- CLI / wasm / `ext/VERSION` **同步 2.1.5**。
## v2.1.4 — 2026-10-26
### Highlights
Generated
+2 -2
View File
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "2.1.4"
version = "2.1.5"
dependencies = [
"anyhow",
"assert_cmd",
@@ -611,7 +611,7 @@ dependencies = [
[[package]]
name = "marqdo-wasm"
version = "2.1.4"
version = "2.1.5"
dependencies = [
"marqdo",
"serde_json",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "2.1.4"
version = "2.1.5"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
+7 -5
View File
@@ -281,10 +281,12 @@ marqdo catalog public -o .marqdo
---
## 现状(v2.1.4)
## 现状(v2.1.5)
- **默认隔离 HTTP execute(v2.1.4 · ADR 0009)**:`execute` / `sse-live` / `stream:true` → Supervisor worker 池(`--call-lib-path`);父进程不再占 `INVOKE_LOCK`;`/_runtime/*`;`runtime.isolated_execution=1`;MR-01 金样例;扩展包同步 **2.1.4**
- **Agent 可靠工作台(v2.1.5)**:ResourceView(JSON/CSV/PDF/image)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制与 execute 槽隔离;扩展包同步 **2.1.5**
- **默认隔离 HTTP execute(v2.1.4 · ADR 0009)**:`execute` / `sse-live` / `stream:true` → Supervisor worker 池(`--call-lib-path`);父进程不再占 `INVOKE_LOCK`;`/_runtime/*`;`runtime.isolated_execution=1`;MR-01 金样例
- **知识工作台运行时(v2.1.3)**:ModelSelection / RunContext / usage null≠0 · `view document` 只读嵌入 · LLM selection/messages/cancel · agent.step selection e2e · live smoke(设计 Partial:原生适配器 unavailable)
- **可执行知识生产链(v2.1.2)**:证据/闭包失效 · `verify`/`adjudicate` · `reuse_execute` / `eng_bind_execute`+`publish_gate` · `document.extract` · View `KnowledgePresentation`+SSE `page_token` · 上传限流 · 门禁 45 项(100/1000 单元)
- **可执行知识主链(v2.1.1)**:BoundCall 双后端 · NarrativeRef · 来源/适用期 · `artifact.patch` / `extract_pure` · 整代 `CURRENT` + closure · 发票示例 `113`
- **链接语法(v2.1.0)**:`[描述](目标)` 描述不执行 · `()` 与 `**代码**` 同权(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 链接循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels --mark` · 诊断 `label.*` · view 描述正文 + 代码片 + 桩徽章 · **可执行知识 [link-syntax.md](doc/design/link-syntax.md)**(项目索引、LinkInfo、链接图与 lock)
@@ -323,7 +325,7 @@ marqdo catalog public -o .marqdo
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
### 如何使用最新 Marqdo(v2.1.4)
### 如何使用最新 Marqdo(v2.1.5)
**安装解释器(任选其一)**
@@ -338,7 +340,7 @@ marqdo catalog public -o .marqdo
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v2.1.4 # 或留在 main
git checkout v2.1.5 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -377,7 +379,7 @@ marqdo wasm build
# → dist/wasm/ … 见 examples/browser-hello/
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
# https://github.com/cflmy/marqdo/releases/tag/v2.1.4
# https://github.com/cflmy/marqdo/releases/tag/v2.1.5
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "2.1.4"
version = "2.1.5"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
+7
View File
@@ -1,3 +1,10 @@
marqdo (2.1.5-1ppa1) noble; urgency=medium
* Marqdo 2.1.5: agent reliability workbench — ResourceView / ToolSpec /
CheckpointV2 / EffectLedger; EKC ir.json warm-load; web short/read lanes.
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 07:39:08 +0000
marqdo (2.1.4-1ppa1) noble; urgency=medium
* Marqdo 2.1.4: default isolated HTTP execute (ADR 0009) — Supervisor
+3
View File
@@ -19,6 +19,9 @@
| 文档 | 摘要 |
|------|------|
| [roadmap/agent-reliability-crossrepo-2026-10-27.md](roadmap/agent-reliability-crossrepo-2026-10-27.md) | **Proposed:跨仓 Agent 可靠性开发计划**;M-A0–M-A6 ∥ Q-A0–Q-A7 排期、依赖图、F01–F20 映射、MA-T*/QA-* 验收与第一刀切片;协议真源仍见下方设计文档 |
| [design/agent-reliability-tools-resources-2026-10-27.md](design/agent-reliability-tools-resources-2026-10-27.md) | **Proposed:智能体能力补足**;基于 `16f26d7`,增量设计错误恢复、检查点/效应账本、结构化工具、输出通道、上下文与只读资源视图;含跨仓边界、阶段计划和故障验收 |
| [research/agent-capabilities-2026-10-27.md](research/agent-capabilities-2026-10-27.md) | **官方能力调研与源码复核**;OpenAI/Claude/Gemini/LangGraph/Deep Agents/MCP,求道当前问题 F01–F20;区分现有能力、设计推导与待实测项 |
| [design/isolated-web-runtime-development-2026-10-26.md](design/isolated-web-runtime-development-2026-10-26.md) | **隔离执行与响应式 Web 运行时**:进程池、控制/读取分离、取消、事件恢复、发布一致性;实现见 `src/runtime/` |
| [adr/0009-isolated-web-runtime.md](adr/0009-isolated-web-runtime.md) | **ADR 0009**:隔离 Web 运行时决策;金样例通过后替代 ADR 0008 的并行性结论 |
| [跨库缺陷复核(2026-10-26)](../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md) | **最新源码与测试证据**:实际 HTTP 路由、知识发布/阅读断点、旧缺陷处置及 1000 单元编译性能失败;需同级 qdagent checkout |
+11 -9
View File
@@ -3,9 +3,9 @@
| 项目 | 约定 |
|---|---|
| 状态 | **Accepted**;HTTP **execute** 路径正式替代 [ADR 0008](0008-web-invoke-serialization.md) 的并行性结论。`legacy_serial`(未声明且非流式)仍引用 0008 单飞 / 父进程 `CallLibPath`。 |
| 日期 | 2026-10-26 |
| 日期 | 2026-10-26(修订 2026-10-27:disconnect≠cancel;control/read/short 无父锁) |
| 设计 | [isolated-web-runtime-development-2026-10-26.md](../design/isolated-web-runtime-development-2026-10-26.md) |
| 金样例 | `tests/isolated_execute_mr01.rs`(MR-01 双 60s SSE + short reads;同文件 MR-02 槽满拒绝) |
| 金样例 | `tests/isolated_execute_mr01.rs`(MR-01 双 60s SSE + short reads;同文件 MR-02 槽满拒绝;disconnect-keeps-running;control-under-dual-execute) |
## 背景
@@ -14,18 +14,20 @@ ADR 0008 确认:Go HTTP 多线程,但所有 Endpoint 共享一把解释器
## 决策
1. **首选架构**:预热的一次性 Marqdo worker 进程池;每个租约独占一个进程与 HostContext。
2. **HTTP 默认**:`class=execute` 或 `return=sse-live` 或 body `stream:true` → `admit` → `dispatch`(`--call-lib-path` worker);禁止父进程 `CallLibPath` / `Setenv` / `legacySSEBridgeMu`。`short` / `read` / `control` 仍父进程短路径;未声明非流式 → `legacy_serial`。
3. **控制/读取分离**:取消与事件订阅不进入任务解释器锁;短业务与长执行有独立容量(execute 槽默认 2)。
4. **协议**:`InvokeRequestV2` / worker env + NDJSON `MARQDO_EVENT_FORWARD` + `--emit-result`(首期);`/_runtime/*` 控制面。
5. **能力探测**:`runtime.isolated_execution=1`(默认)、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`;`runtime.read_lane` 仍 0。
6. **发布**:`expected_generation` CAS + publish journal;逻辑文档 ID 与物理 generation 路径解耦。
2. **HTTP 默认**:`class=execute` 或 `return=sse-live` / body `stream:true` → `admit` → `dispatch`(`--call-lib-path` worker);**禁止**父进程 `CallLibPath` / `Setenv` / `legacySSEBridgeMu`。声明的 `short`/`read`/`control` 走父进程短路径(execute 已离进程,父锁通常空闲);未声明非流式 → `legacy_serial`。
3. **控制/读取分离**:`/_runtime/*`(cancel、events、task get)不进入解释器锁。短读勿挤占 execute worker 槽(池默认 2);产品 cancel 优先 `/_runtime`。
4. **订阅 ≠ 取消**:`sse-live` 观察者 `ctx.Done()` 默认**只结束订阅**,不 `runtime.cancel`;后台仍 reap worker 以释放槽。仅显式 header `X-Marqdo-Cancel-On-Disconnect: 1` 才 disconnect=cancel。同步 `waitIsolatedJSON` 可保留 disconnect 取消。重连:`GET /_runtime/tasks/{id}/events` + `Last-Event-ID` / `after_seq`。
5. **协议**:`InvokeRequestV2` / worker env + NDJSON `MARQDO_EVENT_FORWARD` + `--emit-result`(首期);`/_runtime/*` 控制面。
6. **能力探测**:`runtime.isolated_execution=1`、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`、`runtime.read_lane=1`(短读不与 execute 抢父锁)。
7. **发布**:`expected_generation` CAS + publish journal;逻辑文档 ID 与物理 generation 路径解耦。
## 后果
- Execute / live SSE 不再抢进程级 SSE 桥;双流可并行(MR-01)。
- 短读走父进程:在 dual execute 下通常仍 200(父锁空闲);勿把 short/read/control 塞进 2 槽 execute 池。
- Legacy 未声明非流式路径仍可走父进程锁(ADR 0008)。
- 产品(qdagent)cancel / Last-Event-ID 接线仍为后续;不阻碍本框架发版。
- 产品(qdagent)`turn_events` / Last-Event-ID / cancel CAS 接线由 qdagent 验收;框架侧 disconnect≠cancel 与 `/_runtime` 无锁控制面已落地。
## 验收(摘要)
MR-01 绿:双假上游 60s 流不混字、短读全 200、两 worker `--call-lib-path`、第三路槽满 429/503、`runtime.isolated_execution=1`。其余见设计文档 §12。
MR-01 绿:双假上游 60s 流不混字、短读全 200、两 worker `--call-lib-path`、第三路槽满 429/503、`runtime.isolated_execution=1`、`runtime.read_lane=1`。观察者断连后任务仍跑完并可经 `/_runtime` 重放。其余见设计文档 §12。
@@ -0,0 +1,348 @@
# Marqdo 智能体能力补足:恢复、工具、上下文与资源视图
| 项目 | 约定 |
|---|---|
| 状态 | **Proposed**;本次交付设计,不代表以下新接口已实现 |
| 日期 / 基线 | 2026-10-27(Asia/Shanghai);Marqdo `16f26d7` / 2.1.4;qdagent `68b757e` |
| 调研与现状 | [官方资料与源码证据 F01–F20](../research/agent-capabilities-2026-10-27.md) |
| 产品配套 | [qdagent 智能体能力与预览设计](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级 checkout) |
| 继承 | [ext/agent](ext-agent.md)、[隔离 Web 运行时](isolated-web-runtime-development-2026-10-26.md)、[工作台合同](qdagent-workbench-runtime-and-view-2026-10-25.md) |
## 1. 目标与架构边界
让同一套文档原生 Agent 在模型错误、工具失败、网络中断后有界恢复;让工具可发现、可验证、可审计;让结果同时服务模型上下文与用户阅读。保留 `.mq.md` 工作簿、EKC 与验证证据的权威地位,不把框架改成第二套产品聊天服务。
现有 `src/runtime/` 已实现隔离进程、任务/事件与控制通道,本设计在其上补 Agent 步骤语义。现有 `ext/ai/agent.mq.md` 已有 step/plan/run、CALL/READ、观察压缩,继续扩展。框架不持有求道“笔记”业务表、中文按钮、默认回答字数或具体供应商账户。
| 议题 | Marqdo 所有 | qdagent 所有 |
|---|---|---|
| 恢复 | 错误分类、预算、检查点、工具效应、运行/事件语义 | 恢复按钮、会话关联、凭证修复入口、产品政策 |
| 工具 | ToolSpec/Call/Result、schema、权限执行、并发、MCP 传输 | 业务工具、默认集合、连接配置、用户授权范围 |
| 回答 | 结果分通道、输出预算、角色消息、finish reason | 简洁/标准/详细策略、摘要与产物卡、ASK/BUILD 行为 |
| 资源 | ResourceRef、只读内容/派生预览、定位、转换插件接口 | 笔记/文件/产物 ID 映射、owner 权限、预览组件和布局 |
| 知识 | preflight/reuse/verify/compile、记忆原语 | 何时提议沉淀、用户画像与可见管理 |
| 调试 | span、结构化事件、用量与错误码 | 可读过程、运行详情、产品评测语料 |
```mermaid
flowchart LR
APP[qdagent 产品策略与授权] --> RUN[ext/ai/agent step / plan / run]
RUN --> CTX[ContextPack 与预算]
RUN --> LLM[LLM Adapter]
RUN --> DISPATCH[Tool Dispatcher]
DISPATCH --> LOCAL[受控 Marqdo 函数]
DISPATCH --> MCP[MCP Client]
DISPATCH --> RES[资源读取 / 转换]
RUN --> REC[Checkpoint / Effect Ledger]
REC --> RT[既有 runtime task store / event log]
RUN --> OUTPUT[answer / artifact / progress / diagnostic]
RES --> VIEW[DocumentView / ResourceView]
OUTPUT --> APP
VIEW --> APP
```
## 2. 现状与增量
| 已有能力 | 本轮不能误判为缺失 | 要补的具体语义 |
|---|---|---|
| runtime.task_control_v2/event_replay/read_lane | 不再新建一套队列与 SSE 框架 | Agent 步骤恢复与传输重放的边界 |
| resume_save/load | 不再新建平行 checkpoint 命名空间 | 原子提交、版本摘要、作用域、效应关联 |
| CALL、ARGS、READ、plan patch | 不废弃文档式编排 | 类型化 schema、校验错误、有限修复、稳定 call_id |
| MCP stdio client | 不从零重写连接器 | timeout/cancel、resource、远程 transport 的能力探测 |
| DocumentViewV1 / Locator | 不另写 `.mq.md` 解析器 | 普通资源类型、明确 renderer、历史与相对资源处理 |
| LLM messages/usage | 不把 provider 行为交给产品猜测 | 输出预算、原生工具适配探测、角色边界与分通道 |
新模块路径及协议名以下均是**建议落点**。首批开发先固化 schema 与 fixture,再开放 feature bit;不得只更新 capabilities 把未实现能力标真。
## 3. 错误和恢复合同
### 3.1 ErrorV1
现有字符串错误保留兼容适配,新工具与 Agent 结果返回:
```json
{
"schema": "AgentErrorV1",
"code": "tool.timeout",
"category": "transient",
"stage": "tool",
"message": "读取资源超时",
"retryable": true,
"retry_after_ms": 1200,
"effect_state": "none",
"recovery_action": "retry_step",
"call_id": "call_01",
"details_ref": "resource:diagnostic_01"
}
```
`retryable` 仅是候选信息,最终动作由可信策略结合效应、截止时间、预算、取消状态决定。远端工具声称 readOnly/idempotent 不构成授权依据。凭证和原始堆栈不进入公开 message。
| 错误类别 / 例子 | 框架动作 | 不允许的动作 |
|---|---|---|
| transient:429、部分 5xx、连接失败 | 只在安全步骤重试,遵守 Retry-After | 无限重试、复用同一流片段直接追加 |
| invalid_arguments:schema 不匹配 | 把字段级错误作为 observation,最多 1 次参数修复 | 启动工具后才校验;静默丢弃字段 |
| validation_failed:编译/文档校验 | 保留候选与诊断,局部修复后重新验证 | 将未验证草稿标为成功 |
| context_overflow | 压缩可重建上下文,保留任务/限制/未决效应 | 丢失最新用户指令、授权或版本 |
| auth / forbidden | 直接 needs_input/blocked,交应用处理 | 换身份、扩大范围或匿名绕过 |
| conflict / stale_revision | 重新读取版本并重新规划 | 覆盖用户修改、对写操作盲重试 |
| capability_unavailable | 返回可行替代操作清单 | 假称已搜索、已渲染或已执行 |
| policy_denied | 显式拒绝该动作 | 把限制当工具错误让模型规避 |
| budget_exhausted | 保存状态与已完成结果,返回 partial | 自动增预算或伪造 completed |
| unknown_effect / worker_crash | 对账、查询外部状态,不能判断则 needs_reconciliation | 重跑整个工作簿 |
| cancelled | 停止新调用、保留可读产物、传播取消 | 在后台悄悄修复或恢复 |
初始建议:传输最多 2 次重试(总 3 次尝试),指数退避基准 0.5/1 秒并加 jitter;有 Retry-After 时使用服务端建议并受总 deadline 限制。参数修复最多 1 次,内容修复最多 2 次。预算由应用传入,框架只提供默认上限与执行机制。所有重试、修复和摘要模型调用计入同一成本账本。
错误指纹 `hash(tool_id, normalized_arguments, error_code, relevant_revision)` 连续出现 2 次且没有新证据时中止该策略,允许一次有依据的替代路径;不能通过改写错误文本绕过循环检测。
### 3.2 四类“恢复”必须分开
1. **续订事件**:客户端从 cursor 重放和订阅同一个 task,不发起新推理。
2. **重试步骤**:相同逻辑 operation、同幂等键;新 invocation attempt,复用成功的前序结果。
3. **恢复工作流**:从兼容 checkpoint 建立新 runtime task / attempt,关联 `resumed_from`,不把旧终态改回 running。
4. **重新生成答案**:新的输出版本;已有成功工具结果可复用,用户明确重新执行才重新产生效应。
当前 TaskState 把 interrupted/needs_reconciliation 视为终态,沿用此约定。新增 `AgentRun` 逻辑关联只管理目标和 attempt 链;调度权仍在原 runtime。恢复请求带 `expected_revision`、checkpoint digest 与幂等键,相同请求返回同一新 attempt,冲突返回 409 对应的框架错误。
执行失败不必丢掉有用内容:`outcome.status = succeeded | partial | failed | needs_input | cancelled`,伴随 `answer_ref/artifacts/error/recovery_options`。HTTP 调用成功与 Agent 业务 succeeded 不再混为同一字段。
## 4. 检查点与工具效应
### 4.1 CheckpointV2
在 `plugins/agent/src/resume.rs` 扩展已有实现,统一根目录由宿主提供,客户端不能传任意绝对路径。保留 legacy load,但旧 checkpoint 无效应信息时默认 `manual_review`,不能自动重做写操作。
| 字段组 | 内容 |
|---|---|
| 身份 | schema、checkpoint_id、logical_run_id、task_id、attempt_id、step_id、parent_checkpoint_id |
| 作用域 | principal_ref、workspace_id、session_id、授权 scope digest |
| 输入 | task revision、workbook revision/hash、输入资源 revisions、knowledge generation |
| 运行配置 | ModelSnapshot public ref、tool registry digest、policy revision、runtime compatibility |
| 进度 | completed_steps、pending_operation、observation refs、context summary ref |
| 约束 | 剩余 token/tool/time/cost 预算、deadline、cancel epoch |
| 一致性 | effect ledger watermark、event seq、manifest digest、committed_at |
写入协议:写唯一临时文件→flush/fsync→原子 rename→提交 checkpoint 指针;持久化配置下目录 fsync 按平台支持实现。所有引用 blob 在指针提交前落盘。损坏记录报 `checkpoint.corrupt` 并尝试上一个完整版本,不能读取半个 JSON 当无历史。
恢复前校验身份/授权、源版本、工具 schema 与模型兼容性。权限撤销立即生效;checkpoint 不是永久授权。源文件改变返回 `checkpoint.input_changed`,重新计划受影响步骤,不能偷偷使用最新文件继续旧验证结果。
### 4.2 Effect ledger
```text
prepared → started → committed
↘ failed_no_effect
↘ unknown → reconciled_committed | reconciled_no_effect | needs_input
```
每个 operation 持久记录 `operation_id/idempotency_key/args_digest/resource_scope/expected_revision/effect_class/result_ref`。幂等键作用域是 principal + workspace + logical_run + step + operation,不用随机 attempt ID 替换稳定 operation key。对同 key 不同 payload 拒绝。
读工具可重试;确定幂等写由服务端去重;可补偿写仅在补偿明确安全时执行;未知写先查询 receipt/版本。对外部系统不能承诺通用 exactly-once。关键 crash 窗口是“远端已成功、本地尚未记账”,必须返回 unknown 并对账。
本地文件使用 expected revision + staging + atomic replace;变更提交后检查点失败也靠 operation receipt 恢复。`tool.completed` 必须在结果与 receipt 可读取后提交,再对外发事件。事件发送失败不回滚已发生的业务效应。
不要复制 runtime 事件存储:Agent ledger 与 artifact manifest 是步骤事实,现有 runtime event log 是传输/调度事实;以 ID 关联,采用可重建投影与 outbox。跨 DB/文件不能声称一个事务完成,使用 manifest 提交点和恢复扫描补齐索引。
## 5. 结构化工具与调度
### 5.1 ToolSpecV1
```json
{
"schema": "ToolSpecV1",
"id": "workspace.read",
"version": "1",
"description": "读取授权资源的指定行范围",
"input_schema": {
"type": "object",
"properties": {
"resource_id": {"type": "string"},
"revision": {"type": "string"},
"start_line": {"type": "integer", "minimum": 1},
"max_lines": {"type": "integer", "minimum": 1, "maximum": 500}
},
"required": ["resource_id"],
"additionalProperties": false
},
"output_schema_ref": "ResourceReadV1",
"effect": "read",
"scopes": ["workspace:read"],
"timeout_ms": 10000,
"max_result_bytes": 65536,
"idempotency": "safe",
"concurrency_group": "resource-read",
"availability": "ready"
}
```
定义由宿主/可信模块注册;用户认证、scope 与资源根由宿主注入,不接受模型提供 principal 或任意 root。`read`、`write`、`execute`、`external_write` 是策略分类,不是靠工具命名推断。
ToolCallV1:`call_id/tool_id/tool_version/arguments/operation_id/parent_span_id`。ToolResultV1:`ok/status/summary/structured_content/resources/citations/error/usage/truncated/next_cursor/effect_receipt_ref`。超限结果先写 artifact,再返回摘要和范围读取句柄;不把几十 MB 文本送进 prompt。
### 5.2 一条执行通道
```text
发现 → 加载 schema → schema 校验 → 授权与范围解析 → 预算/取消检查
→ 幂等查询 → 执行 → 结果 schema/大小校验 → receipt/结果提交 → 事件 → observation
```
provider 原生 function call 与文档 `CALL:name + ARGS:{...}` 都归一到该通道。保留旧白名单适配,已有 `.mq.md ##` 可根据形参推导初始 schema,再允许显式描述收紧。转换不允许调用未暴露的框架内部函数。禁止对模型参数使用 eval/任意代码反序列化。
`tools.search` 返回已授权且当前可用的工具摘要;`tools.describe` 按 ID 返回完整 schema。核心 5–8 个工具可常驻,其余按需加载;此数量是产品起始配置,不写死框架。每次真正调用仍重新检查授权;搜索索引可列 unavailable 原因供诊断,但不能让未授权工具名字泄露私有连接信息。
初始支持 JSON Schema 的明确子集并公开能力;不支持的 schema 拒绝注册,不静默放宽。原生工具能力、并行工具调用、图片输入、结构化输出分别探测;纯文本兼容 provider 继续走 CALL,但并发和可靠性承诺按测试能力开放。
### 5.3 并发、MCP 与程序化执行
独立只读调用可并发,默认最多 4 个;修改同一资源的调用串行且用 revision CAS。依赖链、审批与取消检查保持顺序。一个并发调用失败不丢弃其他已成功结果。
MCP 扩展现有 client:先完善 timeout/cancel、错误映射、工具分页与 schema、resource read/link,再按 capability 增加远程 Streamable HTTP 与连接认证。stdio 不应允许模型选择任意宿主可执行文件。连接元数据归应用,凭证通过 secret handle 注入 worker,工具输出和 trace 不记录密钥。
工具 annotations 只是提示,可信策略确定真实效应。外部结果全部为数据,不能提升为 standing/system。MCP resource URI 转成宿主授权 ResourceRef,不允许前端直接请求任意 file:// 或内部网地址。
程序化工具编排和子 Agent 为后续切片:在沙箱中仅暴露注册 dispatcher,逐次执行同样的授权、预算和效应日志;禁止通过一段脚本绕过逐工具控制。子任务继承更小权限和共享总预算,不默认开放写同一资源。
## 6. 输出通道与上下文
### 6.1 AgentOutputV1
```json
{
"schema": "AgentOutputV1",
"status": "succeeded",
"answer": {"format": "markdown", "text": "已整理为三点,完整笔记见右侧。"},
"artifacts": [{"resource_id": "res_note_01", "revision": "sha256:example"}],
"citations": [],
"validation": {"status": "passed", "report_ref": "resource:verify_01"},
"finish_reason": "completed",
"recovery_options": []
}
```
这是结果传输协议,不要求模型每次逐字生成这张 JSON。文档式编排仍可产出 `.mq.md`,框架把稳定产物、摘要与事件归一化。普通文本回答可没有 artifact 和 validation;未运行的内容标 `not_applicable/not_run`,不能填 passed。
channel 至少区分 `answer/artifact/progress/diagnostic`。只有 answer delta 可追加到聊天正文;工作簿 token 和工具日志进入其他通道。进度是可观察动作摘要,不要求或泄露模型内部思维链。
应用传 `ResponsePolicy`:detail level、目标长度、最大输出 tokens、是否允许 artifact、用户显式需求。框架负责 budget 和 finish_reason,中文字符数与最终文案由应用决定。达到 token 上限返回 `length_limited` 和完整/不完整标记,不能裁剪 JSON/代码后假装成功。
优先从已验证产物结构投影摘要。必要时增加一次受预算控制的摘要模型调用;摘要不得新增未经证据支持的结论。修复成功后 accepted candidate、结果正文、artifact revision 与 verification digest 必须全部一致。
### 6.2 ContextPackV2
按优先级组装:可信运行规则→最新用户目标/约束→用户选中资源范围→未决操作/成功步骤摘要→检索证据→近期对话→可回读历史。保持角色结构,不把用户/工具文本简单拼进系统指令。
每个 item 携带 `origin/trust/resource_ref/revision/token_estimate/priority`。预算初值建议保留模型窗口 20% 给输出与协议开销;上下文使用达到可用预算 70% 时触发整理,具体比例配置化。优先剔除可重读的完整工具输出,保留摘要、引用和失败恢复锚点。
Compaction 必须保留:目标、用户限制、当前计划、已完成步骤、待决写入、授权范围、输入版本、已接受产物与引用、余量。summary 绑定其 source event range 和 digest,不能当成新的已验证知识。工具输入过时须重读,不能依赖压缩摘要执行写入。
已有 EKC/agent memory 继续提供知识发现和复用。长期用户记忆的创建/修改/删除政策归 qdagent;网页中的指令不能自动变成长期偏好。
## 7. 统一资源与只读视图
### 7.1 ResourceRefV1 / ResourceViewV1
ResourceRef 统一携带 `resource_id/workspace_id/kind/media_type/revision/digest/title/size/origin/locator`;opaque ID 由宿主映射,不将浏览器 path 直接当文件权限。revision 是内容版本,generation 是知识发布代,两者不混用。
```json
{
"schema": "ResourceViewV1",
"resource": {
"resource_id": "res_01", "workspace_id": "ws_01", "kind": "file",
"revision": "sha256:example", "media_type": "text/markdown", "title": "设计说明"
},
"renderer": {"id": "markdown", "version": "1", "trust": "sanitized"},
"render": {"format": "sanitized_html", "fragment": "<p>正文</p>"},
"outline": [],
"locators": [],
"completeness": "complete",
"no_exec": true,
"diagnostics": [],
"next_cursor": null
}
```
继续把 `.mq.md` 交 `view.document`,ResourceView 只包装/扩展,不能另解释一套 Marqdo 语义。普通 `.md/.txt/代码/JSON/CSV` 走媒体类型处理,避免全仓语义编译。浏览器组件由 qdagent 实现,框架只提供可读内容、受控片段或短期授权 blob 引用。
`fragment`、`text`、`blob_ref` 是互斥载荷,按严格 format enum 解码。未知格式返回 unsupported,不能用 `format.includes('html')` 猜测 HTML。为空与加载失败必须有独立状态。
### 7.2 格式矩阵
| 格式 | 框架提供 | 前端消费 | 未具备能力时 |
|---|---|---|---|
| `.mq.md` | 静态 DocumentView、outline、节点/引用 | 正文、语义链接、源码切换 | 只读源码 + 明确诊断,不执行 |
| Markdown / 笔记正文 | 共享静态 Markdown→受控结构/HTML、相对资源引用 | 标题、列表、表格、代码、链接 | 纯文本 |
| 文本/代码 | 分页行片段、编码信息、行定位 | 行号与语法高亮 | 编码提示/下载 |
| JSON / CSV | 有界解析、路径/行列定位、分页 | 树/表/源码 | 原始文本,标格式错误 |
| 图片 | 授权 blob、尺寸/元信息 | 缩放/旋转/替代文本 | 下载,不暗示已做 OCR |
| PDF | blob、页元信息,可选提取插件 | PDF.js 页渲染与定位 | 文件卡;提取不可用不阻止支持的视觉预览 |
| DOCX/XLSX/PPTX | 受限转换插件,可选 PDF/HTML 派生物 | 按派生格式预览 | 未安装转换器,保留下载 |
| HTML/SVG | 默认源码;允许时经严格清洗或受限派生物 | 隔离预览 | 不以内联可执行页面显示 |
| 未知二进制/压缩包 | 元数据 | 下载卡 | 不自动解压/执行 |
提取、预览、执行各有独立 capability。办公转换、OCR 使用受限 worker,禁宏与网络、限制时间/内存/页数/解压膨胀比;结果绑定原件 digest、转换器版本和参数。首期不承诺保真编辑。
### 7.3 安全、定位、缓存
所有读取先校验宿主授予的 workspace/resource scope,canonicalize 并处理 symlink 逃逸;读取句柄与校验对象一致,防路径检查后替换。读取原件的身份权限不可被缓存绕过。
预览绝不调用 `run/verify` 或有执行副作用的 view 路径;正文中的 Marqdo 调用链接只展示语义与导航,执行需单独工具调用与授权。远程图片、相对链接、资源 URL 经受控解析;下载入口不允许任意内网 fetch。
HTML 清洗在框架产出侧和浏览器插入侧都有明确边界;用成熟 allowlist 实现而非正则。禁止 script/event handler、危险 URI、任意 style/form/嵌入对象。前端配 CSP;对需要交互的产物另建无权限 sandbox,不复用文档渲染器。
缓存 key:workspace + resource ID + revision + renderer version + render options + policy version;命中前重新授权。历史 revision 不存在就返回 `version_unavailable`,不能默默展示当前版。locator 支持 node/span/line/page/cell,失效时标 stale 并提供用户主动查看最新版的操作。
建议首期限制:文本片段 256 KiB、代码单次 500 行、CSV 单次 200 行;更大内容分页,完整文件保留。数值需压测校准,不作为现有系统性能声明。
## 8. 事件、可观测性与能力协商
复用 RuntimeEventV2 的 task/run/attempt/seq/event_id。拟增加事件类型:`agent.step.started/completed`、`tool.started/completed/failed`、`recovery.scheduled/exhausted`、`checkpoint.committed`、`artifact.updated`、`answer.delta/committed`、`context.compacted`。现有 `message.delta` 由兼容适配映射 answer channel,不能同时重复消费两套事件。
终态提交包含 accepted output manifest、last_seq、result digest;断流客户端能通过快照补齐最终答案。stream delta 是预览,最终 committed revision 是权威。统计每次尝试的 usage,摘要和修复调用分别标 purpose;未知计量保持 unknown。
拟新增 capability:`agent.error_v1`、`agent.checkpoint_v2`、`agent.tool_schema_v1`、`agent.output_channels_v1`、`agent.context_pack_v2`、`resource.view_v1`,以及各 media renderer 的独立版本/可用状态。保持现有 probe,新增字段向后兼容;未知 feature 当不可用。
trace 记录因果 ID、耗时、错误类别、参数摘要、资源版本和 effect receipt。正文与密钥按配置脱敏,不默认把用户全文件复制进日志。输出中不包含模型私有推理;可审计的是实际动作与结果。
## 9. 分阶段实现与文件落点
| 包 | 修改/新增建议 | 交付内容 | 依赖 / 退出条件 |
|---|---|---|---|
| M-A0 | `src/workbench/capabilities.rs`、`tests/workbench_contracts.rs`、新增合同 fixtures | 上述协议、旧适配、状态映射 | 先冻结跨仓字段,未知字段/版本可降级 |
| M-A1 | `ext/ai/agent.mq.md`、`plugins/agent/src/resume.rs`、新 recovery/effects 支撑模块 | 分类错误、有界修复、accepted candidate、原子检查点 | M-A0;故障注入不重复写、旧记录不冒险自动恢复 |
| M-A2 | `plugins/agent/src/lib.rs`、`mcp_client.rs`、新 tool registry/dispatcher | schema 工具、调用统一、分页与结果资源 | M-A0;未授权调用为 0,失败结果结构正确 |
| M-A3 | `src/workbench/document_view.rs`、新 resource_view、媒体适配模块 | ResourceRef/View、普通格式静态阅读、no-exec | M-A0;资源定位与安全语料通过 |
| M-A4 | `ext/ai/agent.mq.md`、`plugins/llm/src/lib.rs`、`src/workbench/run_context.rs` | 输出分通道、预算、ContextPackV2 | M-A1/2;原生和纯文本 provider fixture 都可用 |
| M-A5 | `src/runtime/` 的既有存储/事件适配、MCP 与转换插件 | 恢复对账、PDF/Office 插件、远程 MCP | M-A1/2/3;持久模式 crash/restart 通过 |
| M-A6 | plan/subtask/sandbox 扩展 | 程序化工具、有界委派与可选浏览器 | 后置;须证明任务收益和预算/效应可控 |
先交 M-A0 与 qdagent P0 的静态阅读/错误结果修复;不要让完整 checkpoint v2 阻塞笔记预览。M-A1 可先上只读重试,写恢复待 ledger 通过再开放。新特性默认关闭直到对应合同实测通过,旧路径继续可读。
## 10. 验收与评测
所有目标是 proposed gate,尚未实测。基础机制用确定性 fake provider/tool;真实 provider 做少量单独 smoke 并记录费用,不能把随机模型输出作为唯一门禁。
| 编号 | 故障/任务 | 必须观察到的结果 |
|---|---|---|
| MA-T01 | 第一次 429、第二次成功 | 尊重退避、计量 2 次、最终只有一个 accepted answer |
| MA-T02 | 连续 schema 参数错误 | 一次修复后停止;工具未在无效参数下执行 |
| MA-T03 | 工具写成功但 receipt 提交前杀 worker | unknown_effect→查询对账;写计数不增加 |
| MA-T04 | checkpoint 写一半杀进程 | 读取上个完整 checkpoint 或明确 corrupt,不产生伪成功 |
| MA-T05 | 终态事件丢失、cursor 重放 | 最终快照恢复完整消息,工具执行次数不增加 |
| MA-T06 | 恢复请求重复/并发 | 同一幂等键只产生一个恢复 attempt |
| MA-T07 | 用户取消与重试定时器竞争 | 取消生效后无新工具调用,旧任务不复活 |
| MA-T08 | 执行中资源/权限改变 | stale/conflict/forbidden,不覆盖新版本 |
| MA-T09 | 恶意文本伪造 CALL/system | 不跨越工具白名单和授权范围 |
| MA-T10 | `.mq.md` 预览含写文件/联网语句 | 哨兵文件/网络计数不变;只读渲染成功或安全降级 |
| MA-T11 | 资源格式、超长输出、路径逃逸 | 正确 renderer/分页;越界拒绝;无 HTML 注入 |
| MA-T12 | 修复原文 A 得到通过验证的 B | answer/artifact/verification 都绑定 B digest |
| MA-T13 | 上下文压缩后继续 | 最新约束、待决效应、资源版本与剩余预算不丢失 |
| MA-T14 | 旧 CALL、旧 DocumentView 消费端 | 基础行为可用,能力缺失有明确返回 |
先运行受影响的 Rust/Go/Marqdo 合同与既有隔离 runtime 金样例,再做跨仓 HTTP/browser gate。性能目标:已缓存 100 KiB 文本视图服务端 p95 < 300 ms、核心工具发现 p95 < 100 ms,基准机器/并发/冷暖缓存必须记录;第三方网络延迟单独列出。
## 11. 迁移、回滚与未决项
兼容迁移按“新增协议→双读→新写→验证→逐步移除旧适配”推进。`.mq.md` 源码与旧运行产物不批量重写;旧 resume JSON 可读取但不能自动升级成带副作用保证的检查点。v2 checkpoint/ledger 保留 schema 版本,新老版本不并发写同一运行。
回滚关闭新工具自动发现、输出通道或转换器时,已提交资源和最终答案仍可读;执行恢复中的任务先 drain/停止接纳,不能切回会盲重做写操作的旧路径。迁移前备份可变索引与 manifest,回滚不删除用户产物。
实现前验证项:现有 runtime 持久存储可提供的原子提交边界、各平台 fsync/rename 行为、LLM adapter 原生 tool call 流式兼容、转换插件部署体积。协议优先按本文保守语义实现,验证不能满足则 feature 保持不可用,不阻塞已经完成的只读预览切片。
+6 -5
View File
@@ -53,22 +53,23 @@ Marqdo 把仓库投影为 **可查询、可验证、可复用** 的工程知识
落盘(G01 分离后):
- **权威语义图**:`.marqdo/graph/edges.json` · `nodes.json`(`SemanticProject`,含 `authority` 字段)· `steps.json`
- **EKC 检索投影**(非执行依据):`.marqdo/ekc/graph/graph.json` · `edges.json` · `index.json`
- **EKC 检索投影**(非执行依据):`.marqdo/ekc/graph/graph.json` · `edges.json` · `index.json` · **`ir.json`**(完整 IR 快照,供查询热路径)
## 5. CLI
```bash
marqdo knowledge [PATH] -o .marqdo # compile(默认)
marqdo knowledge preflight "task"
marqdo knowledge [PATH] -o .marqdo # compile(默认;写投影 + ir.json)
marqdo knowledge preflight "task" # 暖机读 ir.json;缺图才 compile
marqdo knowledge preflight "task" --refresh # 强制全量重编译后再预检
marqdo knowledge record REUSE
marqdo knowledge learn --task ... --failure ...
marqdo find "authentication"
marqdo find "authentication" # 同上:缺图才 compile;--refresh 强制
marqdo reuse "implement oauth login"
marqdo impact path/to/file.mq.md
marqdo conflicts | stale | duplicate [--fail] | verify
```
统一 `--json`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
统一 `--json`。查询类命令(`preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`)默认 **读已编译投影**;CI 或源变更后应先 `marqdo knowledge` 或加 `--refresh`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
## 6. Reuse 协议
+124 -1
View File
@@ -450,4 +450,127 @@ AI 优先使用既有知识,而非反复解释和重新生成
如何让一个 AI 在面对新任务时,能够像编译器复用已有函数一样,直接复用知识库中已经编译的知识,而不必重新理解和生成它?
如果 Marqdo 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。
如果 Marqdo 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。
# Marqdo 可执行知识体系:设计规范与完整范例
我已经基于 Marqdo 当前仓库的语法规范、`[]()` 设计、知识分层、对象模型和 EKC,整理了两份详细文档。
这次设计保留了你的原始理念:
> 代码即文档,文档即知识库,知识即可执行。
核心目标不是让 AI 更容易生成 Marqdo 代码,而是让 AI 尽可能不必重新生成已经存在的知识,转而通过编译器确定性地发现、引用、验证和执行既有知识。
第一份:完整架构设计规范
涵盖语义制品、知识引用、编译器架构、解析优先级、效应安全、版本管理、EKC 集成、Agent 复用协议和实施验收。
阅读设计文档
第二份:多文件可执行知识范例
以虚构书店定价为例,从原始政策文档开始,逐步构造知识定义、对象、计算能力、业务入口、AI 问答、知识复用和错误验证。
阅读完整示例
两份文档打包
下载 ZIP
## 一、这份设计最重要的三个决定
# Marqdo 可执行知识体系:核心设计纲领
**核心理念:代码即文档,文档即知识库,知识即可执行。**
## 1. 知识是可编译的语义制品
文档经过 Marqdo 编译器处理后,不只产生可执行逻辑,还应产生具有稳定身份、类型、签名、契约、依赖关系、来源和验证状态的语义制品(Semantic Artifact)。
知识可以表现为事实、函数、能力、约束、数据集或类型。它们无需全部被强制编码为类。
## 2. `[]()` 是知识使用的统一入口
`[描述](目标)` 保留 Markdown 的可读性。
- `[]` 面向人类,描述意图、意义或用途。
- `()` 面向编译器,包含既有 Marqdo 表达式或者可解析的知识目标。
- 描述不改变执行结果,也不能作为可信性依据。
- 编译器负责将目标解析为确定的符号身份,并验证使用条件。
既支持隐藏不易阅读的代码,也支持引用已经编译的知识。
## 3. AI 复用知识,而不是重新解释知识
AI 面对新任务时,应该遵循:
**Discover → Resolve → Verify → Reuse → Execute → Trace**
当知识缺失或不适用时,才进入 ADAPT 或 CREATE 流程。
检索可以模糊,但最终绑定必须确定。验证必须区分程序可执行性、契约符合性和现实事实正确性。
## 4. 编译器是知识系统的基础
AST、Semantic IR、符号索引、链接关系和知识验证应当由同一套语义体系产生。
解释器、字节码 VM、View、EKC 和 Agent 消费统一的编译结果,而不是各自重新解析文档。
## 5. 最终验收标准
一个 AI 能够发现现有知识、确定其身份、检查适用条件、直接执行既有能力、引用结果和来源,并在知识发生变化时识别受影响的调用者。
只有这条链条成立,Marqdo 才真正实现知识的可执行复用。
## 二、示例将展示什么
我选择了一个具有明确规则和复用价值的业务案例,而不只是使用“李白出生年份”这样的静态事实。
用户购买两件单价 60 元的商品,金卡折扣为 90%,满 100 元免运费。
AI 要处理的业务请求
> 请计算这笔金卡订单的最终应付款,并解释依据。
传统路径
检索政策 → AI 阅读规则 → 重新推导计算 → 生成新代码或答案
Marqdo 目标路径
发现定价能力 → 绑定已编译函数 → 检查输入与政策 → 执行 → 引用结果
目标语法示意(v2.1+,不是 v2.0.0 实测)
```
**应付 = [订单最终应付款](定价.计算应付金额(60, 2, "金卡"))**
```
根据演示政策计算
# ¥108
这套例子进一步展示了参数和返回值、类与继承、表格、条件分支、循环、跨文档调用、自然语言遮蔽,以及知识来源改变时的影响分析。
## 三、与当前版本的兼容边界
我特别保留了一个重要区分:设计目标不等于当前已经实现的功能。
根据这次读取的仓库内容,v2.0.0 已支持本地表达式遮蔽、对象、方法、控制流、表格集合、导入以及现有 EKC 基础;但无实例类函数调用、跨文档知识自动解析、完整 LinkInfo 和语义制品绑定仍需要进一步开发。
因此示例文档明确标注了目标语法和现有兼容写法,没有将尚未验证的代码描述为已经跑通。
## 四、我的主要架构建议
我认为接下来的开发不应该从 `[]()` 的外观继续扩展,而应该先实现:
统一符号索引 → 稳定知识身份 → 引用绑定 → 契约验证 → EKC 复用。
还有一点值得特别强调:我不赞成为了建立知识系统,再单独实现一个与 Marqdo 解释器并列的“知识编译器”。那样会重新制造你希望消除的表示碎片。
更合适的架构是让现有 Marqdo 编译管线产出统一的语义中间表示,然后由运行时、View、EKC 和 Agent 各自消费。
这意味着 Marqdo 的知识体系不是一个外挂的 RAG 框架,而是语言本身的语义能力。
我认为这才是整个设计中最值得投入资源,也最有可能形成独立研究贡献的部分。
@@ -0,0 +1,102 @@
# 智能体能力调研与求道差距复核(2026-10-27)
| 项目 | 说明 |
|---|---|
| 状态 | Research / 设计输入;不是功能交付声明 |
| 调研日期 | 2026-10-27,Asia/Shanghai |
| 源码基线 | Marqdo `16f26d7d60ce9fbc62feb0e8e83f93951f7b53fe`;qdagent `68b757e02ebfb64833b5262b0c8a683512581e8b` |
| 框架设计 | [Agent 恢复、工具与资源协议](../design/agent-reliability-tools-resources-2026-10-27.md) |
| 产品设计 | [求道智能体能力与预览体验](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级仓库) |
## 1. 方法与结论边界
先以 `git pull --ff-only` 同步两仓,再追踪真实调用链与前端入口;对比公开官方文档,不以营销介绍、工具数量或旧设计中的 done 标签代替实现证据。本次是静态源码复核与官方资料研究,没有启动部署实例,没有调用付费模型,没有进行竞品账号实测。因此,下表“源码确认”仅代表代码路径可见,“设计判断”与“待实测”不能写成已复现或已交付。
主流能力的共同方向是:可恢复的执行、结构化工具与资源、按需上下文、可追溯结果、独立产物展示。不同产品和模型支持范围不同;这里不是市场占有率调查,也不声称所有智能体都具备全部能力。求道应保留文档原生、EKC、验证后沉淀的定位,吸收机制,不引入第二套 Agent Runtime。
## 2. 官方资料与可借鉴机制
以下页面均在调研日实际打开;MCP 特意引用固定 `2025-06-18` 版本,作为兼容基线,不宣称它是最新协议。厂商专有能力必须探测,不能因为端点兼容 `/v1` 就认为全部可用。
| 编号 | 官方来源 | 已核实内容 | 对求道的设计启示 |
|---|---|---|---|
| S01 | [OpenAI Agents:集成与可观测性](https://developers.openai.com/api/docs/guides/agents/integrations-observability) | MCP 接入与运行、模型、工具等 tracing | 统一 call/attempt/span 关联;产品只显示阶段摘要,详细事件可展开 |
| S02 | [OpenAI:Memory 与 Compaction](https://developers.openai.com/cookbook/examples/agents_sdk/building_reliable_agents_memory_compaction) | 区分当前任务上下文压缩、跨运行记忆、可审阅产物 | 历史不要无限拼接;完整产物不等于聊天全文 |
| S03 | [LangGraph Persistence](https://docs.langchain.com/oss/python/langgraph/persistence) | checkpointer 保存 thread 状态,store 支撑跨 thread 数据 | 恢复执行状态和用户长期知识是两种生命周期 |
| S04 | [LangGraph Interrupts](https://docs.langchain.com/oss/python/langgraph/interrupts) | 恢复时节点代码可能重新执行 | 检查点不能单独保证写操作只执行一次,必须记录效应与幂等键 |
| S05 | [Claude Tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) | 工具定义按需进入模型上下文 | 工具多不代表每轮注入全部定义;检索后再校验权限 |
| S06 | [Claude Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) | 在执行环境中编排工具、筛选结果 | 大批量只读处理可减少模型往返;后置于基础工具可靠性 |
| S07 | [Deep Agents overview](https://docs.langchain.com/oss/python/deepagents/overview) | 文件系统、上下文管理、子任务与可选规划能力 | 规划应按任务启用;简单问答不强制复杂工作流 |
| S08 | [Gemini Tools](https://ai.google.dev/gemini-api/docs/tools) | 检索、URL、文件搜索、代码执行等工具面 | 覆盖“找资料—读内容—计算—形成产物”,不能只有工程检索 |
| S09 | [Gemini File search](https://ai.google.dev/gemini-api/docs/file-search) | 文件检索与引用信息 | 命中要能定位原文,检索摘要不能代替源文件版本 |
| S10 | [MCP Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) | schema、结构化结果、资源链接;annotations 有信任边界 | 工具结果包含短摘要和资源引用;注解不是权限凭证 |
| S11 | [MCP Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources) | URI 资源、读取和应用决定的上下文注入 | “预览”“加入上下文”“执行”必须是独立动作 |
| S12 | [Claude Artifacts](https://support.claude.com/en/articles/17153992-what-are-artifacts-and-how-do-i-use-them) | 产物在会话旁独立打开,可继续查看与编辑 | 右栏应承载正文;不应只提供离开当前会话的入口 |
| S13 | [Mozilla PDF.js](https://mozilla.github.io/pdf.js/) | Web PDF 解析和渲染 | PDF 视觉预览和 OCR/知识提取分开交付 |
| S14 | [DOMPurify 官方仓库](https://github.com/cure53/DOMPurify) | DOM 清洗、标签/属性配置;插入前清洗 | 替换前端正则“清洗器”,配合同源资源代理和 CSP |
上述设计启示是本次推导,相关性能收益、成本下降比例不照搬厂商基准。工程路线不绑定某个最新模型或套餐。
## 3. 源码事实清单
下列 qdagent 路径相对该仓库;Marqdo 路径相对本仓库。基线 commit 已固定,后续实现需按符号再定位。
| 编号 | 当前实现证据 | 结论与限制 |
|---|---|---|
| F01 | qdagent `agent/qdagent.mq.md::契约提示`、`ask` | ASK 和 BUILD 都要求完整六段式 `.mq.md`,包含 main、验证和元数据;普通回答变长有明确结构性诱因。不能断言这是唯一原因 |
| F02 | 同文件 `ask` 的门禁修复分支 | `r2` 送入第二次门禁后,成功分支仍 `result = raw`;可能展示修复前内容,设计必须绑定同一 accepted candidate |
| F03 | 同文件 `ask` 返回表 | `gated_error` 路径仍可能保留 `status=ok` 且返回 `ok=True`;必须明确业务失败与输送成功的不同含义 |
| F04 | 同文件 `eng_tools` | 默认白名单是 `tool_find/reuse/bind/verify/summarize` 五个工程工具;不是整个框架只有五个工具,也不代表已覆盖网页、笔记、文件编辑 |
| F05 | `ext/ai/agent.mq.md` | 有 step/plan/run、READ、CALL、观察压缩、工作簿和恢复接口;应扩展这些原语,不另造循环 |
| F06 | `plugins/agent/src/resume.rs::resume_save` | JSON 直接 `fs::write`;现有恢复接口不等于具备原子检查点、工具效应对账及任意步骤自动续跑 |
| F07 | `src/runtime/`、`src/workbench/capabilities.rs` | 已有隔离执行、取消、事件回放与读通道;这一轮是 Agent 级恢复补足,不重新规划整个进程池 |
| F08 | qdagent `session-store.ts::resumeTurn` | 终态 completed/failed/interrupted 直接返回;已有事件续订,但终态消息补齐与中断后的执行恢复需分别处理 |
| F09 | qdagent `DesktopFrame.tsx::RightNotesPanel` | 实际只有“查看全部笔记”导航至 `/notes`,没有侧栏笔记正文 |
| F10 | 同文件 `RightFilesPanel`、`WorkspacePage.tsx::openFile` | 文件点击已调 `openTarget`;右栏取首个 workspace,根目录最多 40 个非目录项。不能笼统写“所有按钮都跳转” |
| F11 | `DesktopFrame.tsx` 的 reader/rightbar 条件 | `DocumentReader` 与右侧 tab 容器互斥,且使用两套开关/宽度状态;不是统一的资源浏览面板 |
| F12 | qdagent `NotesPage.tsx` detail | 剥离 frontmatter 后以 `whiteSpace: pre-wrap` 显示文本;没有 Markdown/Marqdo 正文结构渲染 |
| F13 | qdagent `DocumentReader.tsx` | 已有 DocumentView、引用版本传递、请求代数防迟到覆盖;`profile_item` target 未进入读取分支,格式不是通用资源分派 |
| F14 | 同文件 `sanitizeHtmlFragment` | 主要靠正则移除 script/事件/javascript URL;不能当作完整 HTML 白名单安全边界。未在本次做漏洞利用实验 |
| F15 | `src/workbench/document_view.rs` | 有只读文档视图,注释与实现明确避开执行路径;已解析语义应继续复用 |
| F16 | `src/workbench/capabilities.rs` | text/markdown 提取可用,pdf/docx/ocr 标 unavailable;提取能力与浏览器 PDF 预览能力须分别探测 |
| F17 | qdagent `lib/web_search.mq.md` | 既有网页搜索桥使用 legacy 脚本和固定 `last_web_search.json`;存在并发覆盖设计风险,不能直接作为新工具通道 |
| F18 | `plugins/agent/src/mcp_client.rs` | 已有 stdio connect/list/call/close;不能把本轮描述为“从零添加 MCP”,远程连接和资源能力需另验 |
| F19 | qdagent `compose_messages` / `ask` | 对话按角色标记拼成字符串注入 standing;会话语义、上下文预算和外部内容信任层级仍需强化 |
| F20 | qdagent `lib/workbench.mq.md::documents_read` | 临时文件名以秒和环境 RANDOM 构造,RANDOM 缺失又退到秒;设计仍需真正唯一临时文件。workspace 缺省 `.` 不应作为新授权资源接口规则 |
这些是本轮优先级依据。10-26 release notes 所列修复作为已有基础保留,但“Implemented(本仓)”不能替代浏览器、真实 HTTP、进程中断与模型输出的联合验收。
## 4. 能力覆盖与差距优先级
| 能力 | 当前基础 | 本轮目标 | 优先级 / 归属 |
|---|---|---|---|
| 自动纠错 | 一次文档门禁修复、plan patch | 分类错误、有限修复、正确结果替换、可恢复失败 | P0 / 两仓 |
| 执行恢复 | 任务隔离、取消、事件回放、JSON checkpoint | 传输续订与执行续跑分离;效应对账 | P0 / Marqdo 原语,qdagent UX |
| 回答长度 | 六段式文档、完整历史 | 直接回答、摘要+产物、显式详述三种表达 | P0 / qdagent 策略,Marqdo 输出通道 |
| 资源阅读 | DocumentView / Locator | 笔记、工作文件、引用、产物统一入口 | P0 / 两仓 |
| 侧栏预览 | 两套状态与导航入口 | 单一右栏,点击即预览,聊天不中断 | P0 / qdagent |
| 工具使用 | 五工具默认白名单、MCP/库原语 | schema 注册、按需发现、资源读取/搜索/写入/验证 | P1 / 两仓 |
| 联网研究 | legacy 搜索脚本 | search+fetch、来源时间、限量正文、可定位引用 | P1 / 两仓 |
| 上下文与记忆 | EFI pack、profile、history | 分层上下文、预算、可编辑记忆、资源 pin | P1 / 两仓 |
| 多格式 | 文档视图、文本提取 | text/md/mq/code/json/csv/image;PDF 后续 | P0→P1 / 两仓 |
| 长任务与计划 | plan 工作簿 | 里程碑、预算、暂停/继续、产物进度 | P1 / 两仓 |
| 多智能体与浏览器 | 不作为当前完成前提 | 有界委派、隔离执行、受控浏览器工具 | P2 / 框架主导 |
| 可观测评测 | usage、事件与既有测试 | 工具/恢复指标、实际任务语料、回归门禁 | P0 起持续 / 两仓 |
## 5. 采用与暂缓的决策
采用:有界失败恢复;工具结果摘要+资源引用;结构化参数;步骤效应账本;产物与聊天投影分离;资源预览与“加入上下文”分离;用户可检查的引用;按需工具发现。原有源码、知识、工作簿与验证证据仍是权威,衍生视图可重建。
暂缓:全自动跨站电脑操作、任意外部 MCP 自动信任、默认多智能体协作、所有 Office 格式保真编辑、每次问答都规划/运行代码。它们不能先于当前恢复、工具授权和预览闭环。
不采用:把长回答直接 substring 截断、把失败原文当最终成功、前端断流即重发任务、把所有文件当 HTML、用网页内容改写 system 指令、把预览等同于执行可执行文档。
## 6. 必须补做的动态验证
1. 在真实聊天中验证六段式输出与门禁失败/修复的最终消息和持久产物是否一致。
2. 丢弃最后一帧、断网、刷新、worker 崩溃分别注入,确认事件重放不重做工具副作用。
3. 使用真实 HTTP 入口验证右栏笔记、嵌套文件、历史引用、跨 workspace 资源;不只调用兄弟辅助函数。
4. 用恶意/畸形 HTML、路径与符号链接、过大文件验证预览隔离;no-exec 通过哨兵副作用测试。
5. 对无凭证模型、text-only provider、不可用转换器做明确降级;记录版本与环境,禁止以 mock 成功声称上线成功。
后续设计文档中的时间、轮数、字符数、成功率阈值均为拟定验收目标,需用该语料校准。
@@ -0,0 +1,194 @@
# 跨仓 Agent 可靠性开发计划(2026-10-27)
| 项目 | 约定 |
|---|---|
| 状态 | **Proposed / planning**;本文是排期与验收编排,**不是**已实现声明 |
| 日期 | 2026-10-27(Asia/Shanghai) |
| 基线 | Marqdo `6ffe5ce` / 2.1.4;qdagent `c4c976c`(设计文档基线曾为 `16f26d7` / `68b757e`;排期以当前 HEAD 为准) |
| 协议真源 | [智能体能力补足设计](../design/agent-reliability-tools-resources-2026-10-27.md) |
| 产品真源 | [qdagent 智能体能力与预览](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级 checkout) |
| 证据 | [官方调研与 F01–F20](../research/agent-capabilities-2026-10-27.md) |
| 产品侧镜像 | [qdagent 开发计划镜像](../../../qdagent/doc/roadmap/agent-capabilities-development-2026-10-27.md) |
本文只编排依赖、落点、门禁与发布次序。**不发明第二套 Agent Framework**;不修改 `doc/next/`;不把 capability bit 在合同实测前标真。协议字段以设计文档为准,路线图只引用不另造 schema。
## 1. 目标与架构边界
让同一套文档原生 Agent 在模型错误、工具失败、网络中断后有界恢复;工具可发现、可验证、可审计;结果同时服务模型上下文与用户阅读。保留 `.mq.md` 工作簿、EKC 与验证证据的权威地位。
| 议题 | Marqdo 所有 | qdagent 所有 |
|---|---|---|
| 恢复 | ErrorV1、预算、CheckpointV2、效应账本、运行/事件语义 | 恢复按钮、会话关联、凭证修复入口、产品政策 |
| 工具 | ToolSpec/Call/Result、schema、权限执行、并发、MCP 传输 | 业务工具、默认集合、连接配置、用户授权范围 |
| 回答 | AgentOutput 分通道、输出预算、ContextPackV2 | 简洁/标准/详细策略、摘要与产物卡、ASK/BUILD |
| 资源 | ResourceRef/View、只读预览、转换插件接口 | 笔记/文件/产物 ID 映射、owner 权限、预览布局 |
| 知识 | preflight/reuse/verify/compile、记忆原语 | 何时提议沉淀、用户画像与可见管理 |
| 调试 | span、结构化事件、用量与错误码 | 可读过程、运行详情、产品评测语料 |
## 2. 现状(不再重做)
| 已落地基础 | 说明 |
|---|---|
| Agent A0–A4、O1–O5 | 文档原生 step/plan/run、沙盒与优化波次;扩展 `ext/ai/agent`,不另造循环 |
| 隔离 Web 运行时(ADR 0009) | `src/runtime/` Verified;本轮补 Agent 步骤语义,不重建进程池 |
| Workbench 合同切片 | DocumentView / Locator / capabilities;Partial,随本轮补 F 矩阵 |
| 可执行知识 S0–S6 | 本地确定性子集已门禁;**不重开 S0–S6** |
本轮增量(设计已锁、代码待做):`AgentErrorV1`、`CheckpointV2` + effect ledger、`ToolSpecV1` 统一调度、`ResourceViewV1`、`AgentOutputV1` 通道、`ContextPackV2`。
**产品措辞约束**:本地门禁绿 ≠ 远程/多租户安全;≠「知识验证 + Agent 复用闭环」全产品完成。
## 3. 跨仓依赖与日历顺序
```mermaid
flowchart TD
MA0[M-A0 contracts] --> QA0[Q-A0 fixtures]
MA0 --> MA3[M-A3 ResourceView]
MA0 --> MA1[M-A1 Error and Checkpoint]
MA0 --> MA2[M-A2 ToolSpec]
QA0 --> QA1[Q-A1 answer outcome]
QA0 --> QA2[Q-A2 right panel]
MA3 --> QA2
QA1 --> QA3[Q-A3 recovery UX]
MA1 --> QA3
MA2 --> QA4[Q-A4 product tools]
MA1 --> MA4[M-A4 channels ContextPack]
MA2 --> MA4
MA4 --> QA4
MA3 --> QA5[Q-A5 formats]
MA5[M-A5 ledger PDF MCP] --> QA5
MA4 --> QA6[Q-A6 plan memory]
MA5 --> QA7[Q-A7 connectors]
MA6[M-A6 subagents] --> QA7
```
### 3.1 强制顺序原则
1. 先 **M-A0 ∥ Q-A0** 冻结跨仓字段与缺陷 fixtures。
2. 立刻 **Q-A1 + Q-A2 + M-A3(文本/md/mq)**——**不得**被完整 CheckpointV2 阻塞。
3. **M-A1** 可先上只读重试 + 原子 checkpoint;**Q-A3** 终态快照可先行,写恢复等 effect ledger。
4. 再 **M-A2 ∥ Q-A4** → **M-A4 / Q-A6** → **M-A5 / Q-A5** → **M-A6 / Q-A7**。
5. 四类恢复必须分开:事件续订 / 步骤重试 / 工作流 resume(新 attempt + `resumed_from`)/ 答案再生成。
## 4. 阶段包明细
### Wave 0 — 合同
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|---|---|---|---|
| **M-A0** | `src/workbench/capabilities.rs`、`tests/workbench_contracts.rs`、新增合同 fixtures | Error/Tool/Resource/Output/Context 协议、旧适配、状态映射;capability **默认 false** | 跨仓字段冻结;未知字段/版本可降级 |
| **Q-A0** | 缺陷样例、HTTP 路由清单、answer/resource fixtures;设计入口 | 固化 F01–F20 相关 fixtures;`mock`/`live` 证据区分 | 与 M-A0 字段一致;不把 mock 当 live |
### Wave 1 — 可见痛点
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|---|---|---|---|
| **Q-A1** | `agent/qdagent.mq.md`、`gateway/openai`、api 映射 | accepted candidate;`outcome` ≠ HTTP `ok`;摘要投影;ASK 不强制六节 | 修复后只展示 B;未通过不标成功(F01/F02/F03) |
| **M-A3(首批)** | `src/workbench/document_view.rs`、新 `resource_view`、媒体适配 | ResourceRef/View;md/txt/code/mq 静态阅读;no-exec | 资源定位与安全语料通过(F15) |
| **Q-A2** | `DesktopFrame`、panel store、`DocumentReader`、ResourcePanel/Preview | 统一右栏;笔记/文件点击不导航;同 renderer | 所有入口同预览(F09–F14) |
### Wave 2 — 恢复
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|---|---|---|---|
| **M-A1** | `ext/ai/agent.mq.md`、`plugins/agent/src/resume.rs`、recovery/effects 模块 | ErrorV1、有界修复、accepted candidate 绑定、CheckpointV2 原子写 | 故障注入不重复写;旧记录不冒险自动恢复(F06) |
| **Q-A3** | `execution/turns`、session store、`api.ts` | 终态快照补齐、恢复动作、错误卡 | 事件恢复 0 工具调用;写恢复须 ledger(F08) |
### Wave 3 — 工具与通道
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|---|---|---|---|
| **M-A2** | `plugins/agent/src/lib.rs`、`mcp_client.rs`、tool registry/dispatcher | ToolSpec/Call/Result;CALL+native 单通道;分页与结果资源 | 未授权调用为 0;失败结果结构正确(F04/F05/F18) |
| **M-A4** | `ext/ai/agent.mq.md`、`plugins/llm`、`src/workbench/run_context.rs` | AgentOutput 通道、预算、ContextPackV2 | 原生与纯文本 provider fixture 可用(F01/F19) |
| **Q-A4** | `agent/tools/`、工具目录、ContextAttachment | 业务工具;保留旧五工程工具别名 | 找→读→改→验证→预览真实闭环 |
| **Q-A6** | 计划折叠、预算 UI、profile 忘记、候选沉淀 | ResponsePolicy UX、记忆边界 | 压缩与恢复不丢用户约束 |
### Wave 4 — 持久与格式
| 包 | 修改/新增建议 | 交付内容 | 退出门槛 |
|---|---|---|---|
| **M-A5** | `src/runtime/` 存储/事件适配、MCP 与转换插件 | ledger↔runtime 对账、PDF/Office 插件、远程 MCP | crash/restart 通过;诚实探测(F16–F18) |
| **Q-A5** | JSON/CSV/图片/PDF UI、网页来源与页/行引用 | 格式扩展与转换进度 | 缺插件可读降级;PDF 不假称 OCR |
| **M-A6 / Q-A7** | plan/subtask/sandbox;MCP 配置与委派 | 程序化工具、有界委派、可选浏览器 | **后置**;须证明收益与预算/效应可控 |
## 5. F01–F20 → 包映射
| ID | 摘要 | Marqdo | qdagent | 主要验收 |
|---|---|---|---|---|
| F01 | ASK/BUILD 强制六节 | M-A4 输出通道 | Q-A1 ResponsePolicy | QA-01、MA-T12 |
| F02 | 修复后仍返回 raw | M-A1 accepted 绑定 | Q-A1 | QA-03、MA-T12 |
| F03 | `gated_error` 仍 `status=ok` | M-A0/M-A1 ErrorV1 | Q-A1 envelope | QA-04 |
| F04 | 默认仅五工程工具 | M-A2 registry | Q-A4 目录 | QA-17 |
| F05 | 已有 step/plan/run | **扩展** agent.mq.md | — | 不另造 loop |
| F06 | `resume_save` 裸 `fs::write` | M-A1 CheckpointV2 | Q-A3 UX | MA-T03/T04 |
| F07 | runtime 已有 | 复用,不重建 | 接线恢复 API | — |
| F08 | `resumeTurn` 终态直返 | 事件 vs 再执行分离 | Q-A3 快照补齐 | QA-13、MA-T05 |
| F09–F12 | 右栏/笔记预览缺陷 | M-A3 ResourceView | Q-A2 | QA-06–QA-09 |
| F13 | DocumentReader 非通用分派 | DocumentView 保留 mq;ResourceView 其它 | 预览分派 | QA-09 |
| F14 | 正则 HTML 清洗 | 生产侧 allowlist | DOMPurify + CSP | QA-11、MA-T11 |
| F15 | DocumentView no-exec | 保持;ResourceView 禁 run/verify | — | MA-T10 |
| F16 | pdf/docx/ocr unavailable | M-A5 插件 + 诚实探测 | Q-A5 | QA-10 |
| F17 | legacy web_search 临时文件 | 优先框架 net 工具 | 迁移工具 | QA-17、F20 |
| F18 | MCP stdio 已有 | M-A2/5 timeout/cancel/remote | 连接器配置 | MA-T07 |
| F19 | 历史字符串 standing | M-A4 ContextPackV2 | compose_messages | QA-19、MA-T13 |
| F20 | 弱临时名;workspace `.` | 安全临时文件 + ResourceRef | 资源解析 | QA-08、MA-T11 |
## 6. 验收与发布
### 6.1 Marqdo 门禁(MA-T01–T14)
以设计文档 §10 为准;基础机制用确定性 fake provider/tool;真实 provider 少量单独 smoke 并记费用。摘要:
| 编号 | 必须观察到 |
|---|---|
| MA-T01 | 429 后成功:退避、计量、单一 accepted answer |
| MA-T02 | schema 连续错:一次修复后停;无效参数不执行工具 |
| MA-T03 | 写成功但 receipt 前提杀:unknown_effect→对账;写计数不增 |
| MA-T04 | checkpoint 写一半杀进程:完整上一检查点或明确 corrupt |
| MA-T05 | 终态事件丢失:快照恢复完整消息;工具次数不增 |
| MA-T06 | 重复/并发恢复:同一幂等键一个 attempt |
| MA-T07 | 取消 vs 重试:取消后无新工具调用 |
| MA-T08 | 权限/版本变更:stale/conflict/forbidden |
| MA-T09 | 伪造 CALL/system:不越白名单 |
| MA-T10 | `.mq.md` 预览含写/联网:哨兵不变;只读或安全降级 |
| MA-T11 | 格式/超长/路径逃逸:正确 renderer;越界拒绝;无注入 |
| MA-T12 | 修复 A→B:answer/artifact/verification 均绑定 B digest |
| MA-T13 | 上下文压缩后:约束、待决效应、版本、预算不丢 |
| MA-T14 | 旧 CALL/DocumentView:基础可用;缺失能力明确返回 |
先跑受影响的 Rust/Go/Marqdo 合同与隔离 runtime 金样例,再做跨仓 HTTP/browser gate。性能目标(须记录机器/并发/冷暖缓存):已缓存 100 KiB 文本视图服务端 p95 &lt; 300 ms;核心工具发现 p95 &lt; 100 ms。
### 6.2 qdagent 门禁(QA-01–QA-20)
以产品设计 §13 为准;路径必须 `serve → api → 权威业务函数 →` 真实前端。零容忍:重复写效应、预览执行副作用、跨 workspace 越权。
实现时:`python3 scripts/check-contracts.py`、相关 workbench 测试、前端 `npm test` / `npm run build`,再跑 Playwright;无服务时 E2E 须明确 skip/失败原因。
### 6.3 Feature flags 与灰度
建议开关:`agent_output_v2`、`resource_panel_v2`、`agent_tools_v1`、`agent_recovery_v2`。启用取决于 runtime capability + 服务端政策,不由前端单独决定。
灰度:内部单 workspace → 多 workspace → 真 provider/断网 → 默认开启。关闭恢复时必须停止接纳新恢复请求并保留 attempt 状态,**禁止**切回会盲重做写操作的旧路径。
兼容迁移:新增协议 → 双读 → 新写 → 验证 → 逐步移除旧适配。旧 resume JSON 可读但不能自动升级成带副作用保证的检查点。
## 7. 伴生轨(登记,不阻塞主线)
| 轨 | 动作 |
|---|---|
| 可执行知识 S0–S6 | **不重开**;消费 BoundCall/EKC;话术保持「本地子集」 |
| 知识支撑 F0(M02/M03/M05) | **并行伴生**:provenance/closure invalidate、真 verify API、Skill 无冲突 |
| Workbench Partial | 随 M-A0/M-A3 补 F 矩阵与 adapters;不重写 M00–M05 |
| 语言 next-phase P3 / Wave B1 评测 | **延后** |
| Web Document/Endpoint | 遵守 ADR 0007;禁止 compose_/json bag 回退 |
## 8. 下一步开工(第一刀实现切片)
确认本路线图入库后,**另开实现回合**(本文件仅文档):
1. **M-A0 + Q-A0**:合同与 fixtures
2. **Q-A1**:raw→accepted、outcome 一致性
3. **Q-A3 子集**:终态快照补齐
4. **Q-A2 + M-A3 子集**:右栏真实预览(笔记 / md / mq / txt / code)
发布判据是 MA-T* / QA-* 与真实 HTTP/browser 证据,不是接口返回 200 或代码中出现某符号名。
+1 -1
View File
@@ -1 +1 @@
2.1.4
2.1.5
+485 -11
View File
@@ -181,16 +181,335 @@ Find a human-readable call line: `CALL:<name>` or `调用:<name>` / `调用:<n
## run_tool
+ `tools`
+ `name`
+ `arguments`=None
+ `ledger_dir`=.marqdo/agent-effects
+ `logical_run_id`=None
+ `step_id`=None
+ `call_id`=None
+ `operation_id`=None
Allowlist check, then invoke the runbook `##` via `lib/subtask` (`spawn fn=` → `wait`).
Allowlist and ToolSpec prepare (M-A2), then invoke the runbook section via lib/subtask.
Unauthorized or invalid-args calls return ToolResultV1 failure without spawning (0 executions).
Mutating effects (write / execute / external_write) go through EffectLedger (M-A5a).
State flow is prepared then started then spawn then committed, failed_no_effect, or unknown.
Read tools skip the ledger. Matching idempotency_key and args_digest that already committed skips re-exec.
**allowed = > agent_tool_allowed tools=`tools` name=`name`**
1. `allowed`
**id = > subtask.spawn fn=`name`**
*> subtask.wait id=`id`*
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
**msg = "Tool not allowed:"**
*msg + name*
**_ = 1**
1. not `arguments`
**arguments = > table.empty_map**
2. *
**_ = 1**
**prepared = None**
**needs = False**
**opid = None**
**digest = None**
**idem = None**
**effect = "read"**
**receipt = None**
**raw = None**
1. not `p`
**allowed = > agent_tool_allowed tools=`tools` name=`name`**
1. not `allowed`
**msg = "Tool not allowed:"**
*msg + name*
2. *
**id = > subtask.spawn fn=`name`**
*> subtask.wait id=`id`*
**prepared = > agent_tools_prepare_call tool_id=`name` tools=`tools` arguments=`arguments` call_id=`call_id` operation_id=`operation_id` logical_run_id=`logical_run_id` step_id=`step_id`**
**pok = > json.get value=`prepared` key="ok"**
1. not `pok`
*prepared*
2. *
**_ = 1**
**needs = > json.get value=`prepared` key="needs_ledger"**
**call = > json.get value=`prepared` key="call"**
**opid = > json.get value=`call` key="operation_id"**
**digest = > json.get value=`prepared` key="args_digest"**
**idem = > json.get value=`prepared` key="idempotency_key"**
**tspec = > json.get value=`prepared` key="spec"**
**effect = > json.get value=`tspec` key="effect"**
1. `needs`
**led = > agent_effects_prepare operation_id=`opid` idempotency_key=`idem` args_digest=`digest` effect_class=`effect` logical_run_id=`logical_run_id` step_id=`step_id` ledger_dir=`ledger_dir`**
**rec = > json.get value=`led` key="record"**
**st0 = > json.get value=`rec` key="state"**
1. `st0` == "committed"
**receipt = > json.get value=`rec` key="result_ref"**
1. not `receipt`
**receipt = "effect:" + `opid`**
*> agent_tools_wrap_result ok=True status="succeeded" summary="deduped committed effect; skipped re-exec" structured_content=`rec` effect_receipt_ref=`receipt`*
2. *
1. `st0` == "reconciled_committed"
**receipt = > json.get value=`rec` key="result_ref"**
1. not `receipt`
**receipt = "effect:" + `opid`**
*> agent_tools_wrap_result ok=True status="succeeded" summary="deduped reconciled effect; skipped re-exec" structured_content=`rec` effect_receipt_ref=`receipt`*
2. *
1. `st0` == "unknown"
**receipt = "effect:" + `opid`**
*> agent_tools_wrap_result ok=False status="unknown_effect" summary="prior effect unknown; reconcile before retry" structured_content=`rec` effect_receipt_ref=`receipt`*
2. *
1. `st0` == "started"
> agent_effects_transition operation_id=`opid` state="unknown" note="retry saw started without commit; mark unknown" ledger_dir=`ledger_dir`
**receipt = "effect:" + `opid`**
*> agent_tools_wrap_result ok=False status="unknown_effect" summary="interrupted after started; reconcile before retry" structured_content=`rec` effect_receipt_ref=`receipt`*
2. *
1. `st0` == "needs_input"
**receipt = "effect:" + `opid`**
*> agent_tools_wrap_result ok=False status="needs_input" summary="effect needs_input; will not re-exec" structured_content=`rec` effect_receipt_ref=`receipt`*
2. *
> agent_effects_transition operation_id=`opid` state="started" ledger_dir=`ledger_dir`
**_ = 1**
2. *
**_ = 1**
**id = > subtask.spawn fn=`name`**
**raw = > subtask.wait id=`id`**
1. `needs`
**raw_s = > json.stringify value=`raw`**
1. not `raw`
> agent_effects_transition operation_id=`opid` state="unknown" note="empty tool outcome; reconcile required" ledger_dir=`ledger_dir`
**receipt = "effect:" + `opid`**
*> agent_tools_wrap_result ok=False status="unknown_effect" summary="tool outcome empty after started; ledger=unknown" structured_content=`raw` effect_receipt_ref=`receipt`*
2. *
**is_err = > text.starts_with text=`raw_s` prefix="Tool not allowed"**
1. `is_err`
> agent_effects_transition operation_id=`opid` state="failed_no_effect" note="rejected before effect" ledger_dir=`ledger_dir`
**receipt = "effect:" + `opid`**
*> agent_tools_wrap_result ok=False status="failed" summary=`raw_s` effect_receipt_ref=`receipt`*
2. *
**receipt = "effect:" + `opid`**
> agent_effects_transition operation_id=`opid` state="committed" result_ref=`receipt` ledger_dir=`ledger_dir`
*> agent_tools_wrap_result ok=True status="succeeded" summary="tool executed; effect committed" structured_content=`raw` effect_receipt_ref=`receipt`*
2. *
*raw*
## tools_register
+ `spec`=None
+ `specs`=None
Register ToolSpecV1 document(s). Unsupported schema keywords are refused.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_tools_register spec=`spec` specs=`specs`*
## tools_clear
Clear the in-process ToolSpec registry (tests / reseeding).
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_tools_clear*
## tools_search
+ `query`=""
+ `tools`=None
Search authorized registered tools (summaries only).
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_tools_search query=`query` tools=`tools`*
## tools_describe
+ `id`
+ `tools`=None
Return full ToolSpecV1 for an authorized tool id.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_tools_describe id=`id` tools=`tools`*
## tools_register_eng_defaults
Seed the five engineering tool specs (`tool_find` … `tool_summarize`).
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_tools_register_eng_defaults*
## tools_prepare_call
+ `tool_id`
+ `arguments`=None
+ `tools`=None
+ `call_id`=None
+ `operation_id`=None
+ `logical_run_id`=None
+ `step_id`=None
+ `idempotency_key`=None
Validate schema + authorize; returns ToolCallV1 or ToolResultV1 error (no side effects).
Also returns `args_digest` / `idempotency_key` / `needs_ledger` for EffectLedger wiring.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_tools_prepare_call tool_id=`tool_id` arguments=`arguments` tools=`tools` call_id=`call_id` operation_id=`operation_id` logical_run_id=`logical_run_id` step_id=`step_id` idempotency_key=`idempotency_key`*
## output_build
+ `status`="succeeded"
+ `text`=""
+ `format`="markdown"
+ `answer`=None
+ `artifacts`=None
+ `citations`=None
+ `validation`=None
+ `finish_reason`=None
+ `recovery_options`=None
+ `channels`=None
+ `allow_passed_without_report`=False
Build an `AgentOutputV1` document (M-A4). `validation.status=passed` requires `report_ref`.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_output_build status=`status` text=`text` format=`format` answer=`answer` artifacts=`artifacts` citations=`citations` validation=`validation` finish_reason=`finish_reason` recovery_options=`recovery_options` channels=`channels` allow_passed_without_report=`allow_passed_without_report`*
## output_apply_policy
+ `status`="succeeded"
+ `text`=""
+ `format`="markdown"
+ `answer`=None
+ `artifacts`=None
+ `citations`=None
+ `validation`=None
+ `policy`=None
+ `schema`=None
+ `schema_version`=None
+ `finish_reason`=None
+ `recovery_options`=None
+ `channels`=None
Apply `ResponsePolicy` (detail / max_chars / max_output_tokens / artifact_allowed) to an AgentOutputV1 or raw text.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_output_apply_policy status=`status` text=`text` format=`format` answer=`answer` artifacts=`artifacts` citations=`citations` validation=`validation` policy=`policy` schema=`schema` schema_version=`schema_version` finish_reason=`finish_reason` recovery_options=`recovery_options` channels=`channels`*
## output_channel_event
+ `channel`
+ `delta`=""
+ `resource_id`=None
+ `meta`=None
Split a stream delta by channel. Only `answer` sets `append_to_chat=true`.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_output_channel_event channel=`channel` delta=`delta` resource_id=`resource_id` meta=`meta`*
## output_project_conclusion
+ `document`=""
+ `text`=""
Deterministic chat projection from `# 结论` / `# conclusion` (F01 transition). Falls back to the first body paragraph.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_output_project_conclusion document=`document` text=`text`*
## context_pack_build
+ `items`=None
+ `budget_tokens`=8000
+ `output_reserve_pct`=20
+ `compact_threshold_pct`=70
+ `goal`=None
+ `constraints`=None
Assemble `ContextPackV2` with origin/trust/priority. Web/tool items cannot be `trust=trusted`.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_context_pack_build items=`items` budget_tokens=`budget_tokens` output_reserve_pct=`output_reserve_pct` compact_threshold_pct=`compact_threshold_pct` goal=`goal` constraints=`constraints`*
## context_pack_compact
+ `items`=None
+ `budget_tokens`=8000
+ `output_reserve_pct`=20
+ `compact_threshold_pct`=70
+ `goal`=None
+ `constraints`=None
+ `schema`=None
+ `schema_version`=None
+ `available_tokens`=None
+ `used_tokens`=None
+ `source_event_range`=None
Compact over-threshold packs; retain goal/constraints/pending_write/plan/trusted anchors (F19).
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_context_pack_compact items=`items` budget_tokens=`budget_tokens` output_reserve_pct=`output_reserve_pct` compact_threshold_pct=`compact_threshold_pct` goal=`goal` constraints=`constraints` schema=`schema` schema_version=`schema_version` available_tokens=`available_tokens` used_tokens=`used_tokens` source_event_range=`source_event_range`*
## render_workbook_skeleton
+ `goal`
@@ -677,8 +996,12 @@ Close a stdio MCP client session.
+ `route`=None
+ `result`=None
+ `resume_dir`=.marqdo/agent-resume
+ `checkpoint_v2`=False
+ `attempt_id`=None
+ `effect_ledger_watermark`=None
Persist a plan/run checkpoint as `.marqdo/agent-resume/<id>.json`.
Persist a plan/run checkpoint as `.marqdo/agent-resume/<id>.json` (atomic write).
Pass `checkpoint_v2=True` for CheckpointV2 schema. `resume_dir` must be host-relative.
**p = > plugin.native_path name="agent"**
1. `p`
@@ -687,16 +1010,56 @@ Persist a plan/run checkpoint as `.marqdo/agent-resume/<id>.json`.
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_resume_save id=`id` goal=`goal` task=`task` status=`status` round=`round` workbook=`workbook` events=`events` route=`route` result=`result` resume_dir=`resume_dir`*
*> agent_resume_save id=`id` goal=`goal` task=`task` status=`status` round=`round` workbook=`workbook` events=`events` route=`route` result=`result` resume_dir=`resume_dir` checkpoint_v2=`checkpoint_v2` attempt_id=`attempt_id` effect_ledger_watermark=`effect_ledger_watermark`*
## resume_load
+ `id`
+ `resume_dir`=.marqdo/agent-resume
Load a resume checkpoint (or `{ok:false,found:false}`).
Legacy / missing effect ledger → `recovery_mode=manual_review`, `write_auto_resume=false`.
*> agent_resume_load id=`id` resume_dir=`resume_dir`*
## error_make
+ `code`
+ `message`=None
+ `category`=None
+ `stage`=agent
+ `retryable`=None
+ `effect_state`=none
+ `recovery_action`=None
+ `call_id`=None
Build an `AgentErrorV1` document (M-A1).
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_error_make code=`code` message=`message` category=`category` stage=`stage` retryable=`retryable` effect_state=`effect_state` recovery_action=`recovery_action` call_id=`call_id`*
## error_decide_retry
+ `error`
+ `attempts`=0
+ `effect_class`=read
+ `cancelled`=False
+ `fingerprint_repeats`=0
Bounded recovery decision. Write / unknown effect → `manual_review` (no auto redo).
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_error_decide_retry error=`error` attempts=`attempts` effect_class=`effect_class` cancelled=`cancelled` fingerprint_repeats=`fingerprint_repeats`*
## resume_clear
+ `id`
+ `resume_dir`=.marqdo/agent-resume
@@ -720,6 +1083,113 @@ Author entry: load checkpoint for continuation. Returns the checkpoint map (`fou
*> resume_load id=`id` resume_dir=`resume_dir`*
## effects_prepare
+ `operation_id`
+ `idempotency_key`
+ `args_digest`
+ `effect_class`="write"
+ `resource_scope`=None
+ `expected_revision`=None
+ `result_ref`=None
+ `logical_run_id`=None
+ `step_id`=None
+ `attempt_id`=None
+ `ledger_dir`=.marqdo/agent-effects
Create (or dedupe) an `EffectLedgerRecordV1` in `prepared`. Same idempotency_key + args_digest returns the existing record; same key with different digest is rejected.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_effects_prepare operation_id=`operation_id` idempotency_key=`idempotency_key` args_digest=`args_digest` effect_class=`effect_class` resource_scope=`resource_scope` expected_revision=`expected_revision` result_ref=`result_ref` logical_run_id=`logical_run_id` step_id=`step_id` attempt_id=`attempt_id` ledger_dir=`ledger_dir`*
## effects_transition
+ `operation_id`
+ `state`
+ `result_ref`=None
+ `note`=None
+ `reconcile_hint`=None
+ `ledger_dir`=.marqdo/agent-effects
Advance ledger state (`prepared→started→committed|failed_no_effect|unknown→reconciled_*`).
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_effects_transition operation_id=`operation_id` state=`state` result_ref=`result_ref` note=`note` reconcile_hint=`reconcile_hint` ledger_dir=`ledger_dir`*
## effects_get
+ `operation_id`
+ `ledger_dir`=.marqdo/agent-effects
Load one ledger record.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_effects_get operation_id=`operation_id` ledger_dir=`ledger_dir`*
## effects_list
+ `ledger_dir`=.marqdo/agent-effects
+ `logical_run_id`=None
+ `state`=None
List ledger records (optional filters).
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_effects_list ledger_dir=`ledger_dir` logical_run_id=`logical_run_id` state=`state`*
## effects_watermark
+ `ledger_dir`=.marqdo/agent-effects
+ `logical_run_id`=None
Digest committed/open effects for CheckpointV2. `write_auto_resume_safe` is false while unknown or pending writes remain.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_effects_watermark ledger_dir=`ledger_dir` logical_run_id=`logical_run_id`*
## effects_reconcile
+ `operation_id`
+ `outcome`
+ `result_ref`=None
+ `note`=None
+ `ledger_dir`=.marqdo/agent-effects
Reconcile an `unknown` record: `outcome` = committed | no_effect | needs_input.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_effects_reconcile operation_id=`operation_id` outcome=`outcome` result_ref=`result_ref` note=`note` ledger_dir=`ledger_dir`*
---
## extract_call_args
@@ -2414,8 +2884,10 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o
**_ = 1**
1. `resume_id`
**_ckpt = resume_save id=`resume_id` goal=`task` task=`task` status=`st` round=1 workbook=`wb_path` result=`res` route=`routed` resume_dir=`resume_dir`**
**_wm = > effects_watermark ledger_dir=".marqdo/agent-effects" logical_run_id=`resume_id`**
**_ckpt = resume_save id=`resume_id` goal=`task` task=`task` status=`st` round=1 workbook=`wb_path` result=`res` route=`routed` resume_dir=`resume_dir` checkpoint_v2=True attempt_id="attempt_1" effect_ledger_watermark=`_wm`**
**out = table.put in=`out` at="resume" value=`_ckpt`**
**out = table.put in=`out` at="effect_ledger_watermark" value=`_wm`**
2. *
**_ = 1**
@@ -2429,8 +2901,10 @@ Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) o
+ `max_reads`=2
+ `sandbox`=False
+ `sandbox_profile`=default
+ `resume_id`=None
One atomic turn: budgeted context → LLM → optional `READ:` deepen → optional tool via subtask. Returns a *map* (`status`, `task`, `decision`, and on success `result` plus optional `tool` / `tool_result`; on failure `error`). By default (`writeback=True`) persists that map under named slots `ok` / `error` at the call site; pass `writeback=False` to skip.
Optional `resume_id` scopes EffectLedger idempotency for mutating tools.
With `stream=True`, the model call uses SSE; `echo=True` prints delta text to stdout as it arrives. The returned map is unchanged (final `result` string). Context source/skill start at default budget; up to `max_reads` of `READ:source` / `READ:skill` deepen before CALL/answer.
`sandbox=True` (O1 opt-in): attach the sandbox profile row on the result map (trial via `## trial` / `run sandbox=`).
@@ -2521,7 +2995,7 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st
| ok | `task` | `decision` |
1. `tool_name`
**tool_out = > run_tool tools=`tools` name=`tool_name`**
**tool_out = > run_tool tools=`tools` name=`tool_name` logical_run_id=`resume_id`**
**tool_s = > json.stringify value=`tool_out`**
**deny = > split value=`tool_s` sep="Tool not allowed"**
**deny_n = > len value=`deny`**
+266
View File
@@ -0,0 +1,266 @@
//! ContextPackV2 assemble + compact (M-A4).
use serde_json::{json, Value};
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
args.get(key)
.and_then(|v| v.as_str())
.filter(|s| !s.is_empty())
}
fn item_tokens(item: &Value) -> u64 {
item.get("token_estimate")
.and_then(|v| v.as_u64())
.unwrap_or_else(|| {
item.get("text")
.and_then(|v| v.as_str())
.map(|s| (s.chars().count() as u64).div_ceil(2))
.unwrap_or(32)
})
}
fn normalize_item(raw: &Value, default_priority: i64) -> Result<Value, String> {
let origin = raw
.get("origin")
.and_then(|v| v.as_str())
.unwrap_or("unknown");
let trust = raw
.get("trust")
.and_then(|v| v.as_str())
.unwrap_or(match origin {
"system" | "policy" => "trusted",
"user" => "user",
"tool" => "tool",
"web" => "untrusted",
_ => "unknown",
});
// External / web content must never be trust=trusted.
if matches!(origin, "web" | "tool") && trust == "trusted" {
return Err("tool/web origin cannot have trust=trusted".into());
}
Ok(json!({
"origin": origin,
"trust": trust,
"resource_ref": raw.get("resource_ref").cloned().unwrap_or(Value::Null),
"revision": raw.get("revision").cloned().unwrap_or(Value::Null),
"token_estimate": item_tokens(raw),
"priority": raw.get("priority").and_then(|v| v.as_i64()).unwrap_or(default_priority),
"role": raw.get("role").cloned().unwrap_or(json!(origin)),
"text": raw.get("text").cloned().unwrap_or(Value::Null),
"kind": raw.get("kind").cloned().unwrap_or(json!("content")),
"retain": raw.get("retain").and_then(|v| v.as_bool()).unwrap_or(false),
}))
}
/// Build ContextPackV2 from items + optional budget.
pub fn context_pack_build(args: &Value) -> Result<Value, String> {
let raw_items = args
.get("items")
.and_then(|v| v.as_array())
.cloned()
.unwrap_or_default();
let mut items = Vec::new();
for (i, raw) in raw_items.iter().enumerate() {
items.push(normalize_item(raw, i as i64)?);
}
// Stable priority order: lower priority number first (more important).
items.sort_by(|a, b| {
let pa = a.get("priority").and_then(|v| v.as_i64()).unwrap_or(0);
let pb = b.get("priority").and_then(|v| v.as_i64()).unwrap_or(0);
pa.cmp(&pb)
});
let budget = args
.get("budget_tokens")
.and_then(|v| v.as_u64())
.unwrap_or(8_000);
let reserve_pct = args
.get("output_reserve_pct")
.and_then(|v| v.as_u64())
.unwrap_or(20)
.min(50);
let available = budget.saturating_mul(100 - reserve_pct) / 100;
let used: u64 = items.iter().map(item_tokens).sum();
Ok(json!({
"schema": "ContextPackV2",
"schema_version": 2,
"items": items,
"budget_tokens": budget,
"available_tokens": available,
"used_tokens": used,
"output_reserve_pct": reserve_pct,
"compact_threshold_pct": args.get("compact_threshold_pct").and_then(|v| v.as_u64()).unwrap_or(70),
"goal": args.get("goal").cloned().unwrap_or(Value::Null),
"constraints": args.get("constraints").cloned().unwrap_or_else(|| json!([])),
}))
}
/// Compact pack when over threshold; must retain anchors listed in design §6.2.
pub fn context_pack_compact(args: &Value) -> Result<Value, String> {
let mut pack = if args.get("schema").and_then(|v| v.as_str()) == Some("ContextPackV2") {
args.clone()
} else {
context_pack_build(args)?
};
let available = pack
.get("available_tokens")
.and_then(|v| v.as_u64())
.unwrap_or(6400);
let threshold_pct = pack
.get("compact_threshold_pct")
.and_then(|v| v.as_u64())
.unwrap_or(70);
let threshold = available.saturating_mul(threshold_pct) / 100;
let used = pack
.get("used_tokens")
.and_then(|v| v.as_u64())
.unwrap_or(0);
if used <= threshold {
if let Some(obj) = pack.as_object_mut() {
obj.insert("compacted".into(), json!(false));
obj.insert("reason".into(), json!("under_threshold"));
}
return Ok(pack);
}
let items = pack
.get("items")
.and_then(|v| v.as_array())
.cloned()
.unwrap_or_default();
// Retain: goal/constraints (pack fields), retain=true, high priority (<=2),
// pending writes, failures — drop bulky tool dumps first (kind=tool_output, low priority).
let mut kept = Vec::new();
let mut dropped = Vec::new();
for item in items {
let retain = item.get("retain").and_then(|v| v.as_bool()).unwrap_or(false);
let priority = item.get("priority").and_then(|v| v.as_i64()).unwrap_or(99);
let kind = item.get("kind").and_then(|v| v.as_str()).unwrap_or("");
let trust = item.get("trust").and_then(|v| v.as_str()).unwrap_or("");
let must = retain
|| priority <= 2
|| matches!(kind, "goal" | "constraint" | "pending_write" | "plan" | "failure")
|| trust == "trusted";
if must {
kept.push(item);
} else if kind == "tool_output" || priority >= 8 {
dropped.push(item);
} else {
kept.push(item);
}
}
// If still over budget, drop lowest-priority non-retain from kept.
let mut kept_tokens: u64 = kept.iter().map(item_tokens).sum();
if kept_tokens > threshold {
kept.sort_by(|a, b| {
let pa = a.get("priority").and_then(|v| v.as_i64()).unwrap_or(0);
let pb = b.get("priority").and_then(|v| v.as_i64()).unwrap_or(0);
pb.cmp(&pa) // high priority number first for dropping
});
let mut next = Vec::new();
for item in kept.into_iter().rev() {
// rebuild ascending later
let retain = item.get("retain").and_then(|v| v.as_bool()).unwrap_or(false);
let priority = item.get("priority").and_then(|v| v.as_i64()).unwrap_or(99);
let t = item_tokens(&item);
if (retain || priority <= 1) || kept_tokens <= threshold {
next.push(item);
} else if kept_tokens > threshold {
kept_tokens = kept_tokens.saturating_sub(t);
dropped.push(item);
} else {
next.push(item);
}
}
next.sort_by(|a, b| {
let pa = a.get("priority").and_then(|v| v.as_i64()).unwrap_or(0);
let pb = b.get("priority").and_then(|v| v.as_i64()).unwrap_or(0);
pa.cmp(&pb)
});
kept = next;
kept_tokens = kept.iter().map(item_tokens).sum();
}
let digest_src = format!(
"kept={} dropped={} used={}",
kept.len(),
dropped.len(),
kept_tokens
);
let digest = format!("sha256-lite:{}", simple_hash(&digest_src));
if let Some(obj) = pack.as_object_mut() {
obj.insert("items".into(), json!(kept));
obj.insert("used_tokens".into(), json!(kept_tokens));
obj.insert("compacted".into(), json!(true));
obj.insert(
"compaction".into(),
json!({
"dropped_count": dropped.len(),
"source_event_range": args.get("source_event_range").cloned().unwrap_or(Value::Null),
"digest": digest,
"retained": ["goal", "constraints", "pending_write", "plan", "trusted_policy"],
}),
);
// Goal / constraints fields stay untouched.
if obj.get("goal").map(|v| v.is_null()).unwrap_or(true) {
if let Some(g) = opt_text(args, "goal") {
obj.insert("goal".into(), json!(g));
}
}
}
Ok(pack)
}
fn simple_hash(s: &str) -> u64 {
let mut h: u64 = 0xcbf29ce484222325;
for b in s.as_bytes() {
h ^= u64::from(*b);
h = h.wrapping_mul(0x100000001b3);
}
h
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn build_sorts_and_rejects_trusted_web() {
let pack = context_pack_build(&json!({
"budget_tokens": 1000,
"items": [
{"origin": "user", "text": "goal", "priority": 0, "kind": "goal", "retain": true},
{"origin": "tool", "text": "big dump", "priority": 9, "kind": "tool_output", "token_estimate": 500}
]
}))
.unwrap();
assert_eq!(pack["schema"], "ContextPackV2");
assert_eq!(pack["items"][0]["priority"], 0);
let bad = context_pack_build(&json!({
"items": [{"origin": "web", "trust": "trusted", "text": "x"}]
}));
assert!(bad.is_err());
}
#[test]
fn compact_keeps_goal_drops_tool_output() {
let pack = context_pack_build(&json!({
"budget_tokens": 200,
"output_reserve_pct": 20,
"compact_threshold_pct": 50,
"goal": "finish task",
"items": [
{"origin": "user", "text": "do it", "priority": 0, "kind": "goal", "retain": true, "token_estimate": 20},
{"origin": "tool", "text": "x".repeat(400), "priority": 9, "kind": "tool_output", "token_estimate": 200}
]
}))
.unwrap();
let compacted = context_pack_compact(&pack).unwrap();
assert_eq!(compacted["compacted"], true);
let items = compacted["items"].as_array().unwrap();
assert!(items.iter().any(|i| i["kind"] == "goal"));
assert!(!items.iter().any(|i| i["kind"] == "tool_output"));
assert_eq!(compacted["goal"], "finish task");
}
}
+623
View File
@@ -0,0 +1,623 @@
//! EffectLedgerRecordV1 — operation receipts for write-safe resume (M-A5 subset).
//!
//! State machine (design §4.2):
//! prepared → started → committed
//! ↘ failed_no_effect
//! ↘ unknown → reconciled_committed | reconciled_no_effect | needs_input
use std::fs::{self, File, OpenOptions};
use std::io::Write;
use std::path::{Path, PathBuf};
use serde_json::{json, Value};
const DEFAULT_LEDGER_DIR: &str = ".marqdo/agent-effects";
const STATES: &[&str] = &[
"prepared",
"started",
"committed",
"failed_no_effect",
"unknown",
"reconciled_committed",
"reconciled_no_effect",
"needs_input",
];
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
args.get(key)
.and_then(|v| v.as_str())
.filter(|s| !s.is_empty())
}
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
opt_text(args, key).ok_or_else(|| format!("missing text `{key}`"))
}
fn now_rfc3339() -> String {
chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
}
fn resolve_path(rel: &str) -> PathBuf {
let p = PathBuf::from(rel);
if p.is_absolute() {
return p;
}
if p.exists() {
return p;
}
let base = (|| {
let q = crate::host_query_json("cwd")?;
q.as_str()
.map(PathBuf::from)
.ok_or_else(|| "cwd not text".to_string())
})()
.or_else(|_| std::env::current_dir().map_err(|e| e.to_string()))
.unwrap_or_else(|_| PathBuf::from("."));
base.join(p)
}
fn ledger_root(args: &Value) -> Result<PathBuf, String> {
let rel = opt_text(args, "ledger_dir").unwrap_or(DEFAULT_LEDGER_DIR);
let p = PathBuf::from(rel);
if p.is_absolute() {
return Err(
"ledger_dir must be host-relative; absolute client paths are rejected".into(),
);
}
if rel.contains("..") {
return Err("ledger_dir must not contain '..'".into());
}
Ok(resolve_path(rel))
}
fn safe_id(id: &str) -> String {
id.chars()
.map(|c| {
if c.is_ascii_alphanumeric() || c == '-' || c == '_' {
c
} else {
'_'
}
})
.collect()
}
fn record_path(root: &Path, operation_id: &str) -> PathBuf {
root.join(format!("{}.json", safe_id(operation_id)))
}
fn ensure_dir(root: &Path) -> Result<(), String> {
fs::create_dir_all(root).map_err(|e| format!("effects mkdir: {e}"))
}
fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> {
let parent = path
.parent()
.ok_or_else(|| "ledger path has no parent".to_string())?;
ensure_dir(parent)?;
let tmp_name = format!(
".{}.tmp-{}-{}",
path.file_name()
.and_then(|s| s.to_str())
.unwrap_or("op.json"),
std::process::id(),
now_rfc3339().replace(':', "")
);
let tmp = parent.join(tmp_name);
let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?;
{
let mut f = OpenOptions::new()
.create(true)
.write(true)
.truncate(true)
.open(&tmp)
.map_err(|e| format!("effects temp open: {e}"))?;
f.write_all(text.as_bytes())
.map_err(|e| format!("effects temp write: {e}"))?;
f.flush().map_err(|e| format!("effects temp flush: {e}"))?;
f.sync_all()
.map_err(|e| format!("effects temp fsync: {e}"))?;
}
if let Ok(dir) = File::open(parent) {
let _ = dir.sync_all();
}
fs::rename(&tmp, path).map_err(|e| {
let _ = fs::remove_file(&tmp);
format!("effects atomic rename: {e}")
})?;
Ok(())
}
fn load_record(path: &Path) -> Result<Option<Value>, String> {
if !path.is_file() {
return Ok(None);
}
let text = fs::read_to_string(path).map_err(|e| format!("effects read: {e}"))?;
let doc: Value = serde_json::from_str(&text).map_err(|e| format!("effects corrupt: {e}"))?;
Ok(Some(doc))
}
fn valid_transition(from: &str, to: &str) -> bool {
matches!(
(from, to),
("prepared", "started")
| ("started", "committed")
| ("started", "failed_no_effect")
| ("started", "unknown")
| ("unknown", "reconciled_committed")
| ("unknown", "reconciled_no_effect")
| ("unknown", "needs_input")
// Idempotent no-ops / crash retries of the same terminal.
| ("committed", "committed")
| ("failed_no_effect", "failed_no_effect")
| ("reconciled_committed", "reconciled_committed")
| ("reconciled_no_effect", "reconciled_no_effect")
| ("needs_input", "needs_input")
// Re-prepare of same op is handled separately via idempotency.
| ("prepared", "prepared")
)
}
fn effect_class_ok(c: &str) -> bool {
matches!(c, "read" | "write" | "execute" | "external_write" | "none")
}
/// Prepare (or return existing) an EffectLedgerRecordV1.
pub fn effects_prepare(args: &Value) -> Result<Value, String> {
let operation_id = arg_text(args, "operation_id")?;
let idempotency_key = arg_text(args, "idempotency_key")?;
let args_digest = arg_text(args, "args_digest")?;
let effect_class = opt_text(args, "effect_class").unwrap_or("write");
if !effect_class_ok(effect_class) {
return Err(format!("invalid effect_class={effect_class}"));
}
let root = ledger_root(args)?;
ensure_dir(&root)?;
let path = record_path(&root, operation_id);
if let Some(existing) = load_record(&path)? {
let same_key = existing
.get("idempotency_key")
.and_then(|v| v.as_str())
== Some(idempotency_key);
let same_digest = existing.get("args_digest").and_then(|v| v.as_str()) == Some(args_digest);
if same_key && same_digest {
return Ok(json!({
"ok": true,
"deduped": true,
"record": existing,
}));
}
if same_key && !same_digest {
return Err(
"idempotency_key collision: same key with different args_digest".into(),
);
}
// Different operation_id path can't collide; same path different key is corrupt reuse.
return Err("operation_id already exists with different idempotency_key".into());
}
// Also scan for same idempotency_key under other operation_ids in this ledger dir.
if let Ok(rd) = fs::read_dir(&root) {
for ent in rd.flatten() {
let p = ent.path();
if p.extension().and_then(|e| e.to_str()) != Some("json") {
continue;
}
if let Ok(Some(doc)) = load_record(&p) {
if doc.get("idempotency_key").and_then(|v| v.as_str()) == Some(idempotency_key) {
let dig = doc.get("args_digest").and_then(|v| v.as_str());
if dig == Some(args_digest) {
return Ok(json!({
"ok": true,
"deduped": true,
"record": doc,
}));
}
return Err(
"idempotency_key collision: same key with different args_digest".into(),
);
}
}
}
}
let doc = json!({
"schema": "EffectLedgerRecordV1",
"schema_version": 1,
"operation_id": operation_id,
"idempotency_key": idempotency_key,
"args_digest": args_digest,
"resource_scope": args.get("resource_scope").cloned().unwrap_or(Value::Null),
"expected_revision": args.get("expected_revision").cloned().unwrap_or(Value::Null),
"effect_class": effect_class,
"result_ref": args.get("result_ref").cloned().unwrap_or(Value::Null),
"state": "prepared",
"logical_run_id": args.get("logical_run_id").cloned().unwrap_or(Value::Null),
"step_id": args.get("step_id").cloned().unwrap_or(Value::Null),
"attempt_id": args.get("attempt_id").cloned().unwrap_or(Value::Null),
"prepared_at": now_rfc3339(),
"updated_at": now_rfc3339(),
});
atomic_write_json(&path, &doc)?;
Ok(json!({
"ok": true,
"deduped": false,
"record": doc,
"path": path.to_string_lossy(),
}))
}
/// Transition an existing record to a new state.
pub fn effects_transition(args: &Value) -> Result<Value, String> {
let operation_id = arg_text(args, "operation_id")?;
let to = arg_text(args, "state")?;
if !STATES.contains(&to) {
return Err(format!("invalid state={to}"));
}
let root = ledger_root(args)?;
let path = record_path(&root, operation_id);
let mut doc = load_record(&path)?
.ok_or_else(|| format!("operation_id not found: {operation_id}"))?;
let from = doc
.get("state")
.and_then(|v| v.as_str())
.unwrap_or("prepared")
.to_string();
if !valid_transition(&from, to) {
return Err(format!("illegal transition {from} → {to}"));
}
if let Some(obj) = doc.as_object_mut() {
obj.insert("state".into(), json!(to));
obj.insert("updated_at".into(), json!(now_rfc3339()));
if let Some(r) = args.get("result_ref") {
if !r.is_null() {
obj.insert("result_ref".into(), r.clone());
}
}
if let Some(n) = args.get("note") {
if !n.is_null() {
obj.insert("note".into(), n.clone());
}
}
if to == "unknown" || to.starts_with("reconciled") {
obj.insert(
"reconcile_hint".into(),
args.get("reconcile_hint")
.cloned()
.unwrap_or_else(|| json!("check receipt / resource revision")),
);
}
}
atomic_write_json(&path, &doc)?;
Ok(json!({
"ok": true,
"from": from,
"to": to,
"record": doc,
}))
}
pub fn effects_get(args: &Value) -> Result<Value, String> {
let operation_id = arg_text(args, "operation_id")?;
let root = ledger_root(args)?;
let path = record_path(&root, operation_id);
match load_record(&path)? {
Some(doc) => Ok(json!({
"ok": true,
"found": true,
"record": doc,
"path": path.to_string_lossy(),
})),
None => Ok(json!({
"ok": true,
"found": false,
"operation_id": operation_id,
"path": path.to_string_lossy(),
})),
}
}
pub fn effects_list(args: &Value) -> Result<Value, String> {
let root = ledger_root(args)?;
let mut records = Vec::new();
if root.is_dir() {
let mut paths: Vec<_> = fs::read_dir(&root)
.map_err(|e| e.to_string())?
.flatten()
.map(|e| e.path())
.filter(|p| p.extension().and_then(|e| e.to_str()) == Some("json"))
.collect();
paths.sort();
for p in paths {
if let Ok(Some(doc)) = load_record(&p) {
if let Some(run) = opt_text(args, "logical_run_id") {
if doc.get("logical_run_id").and_then(|v| v.as_str()) != Some(run) {
continue;
}
}
if let Some(st) = opt_text(args, "state") {
if doc.get("state").and_then(|v| v.as_str()) != Some(st) {
continue;
}
}
records.push(doc);
}
}
}
Ok(json!({
"ok": true,
"count": records.len(),
"records": records,
"ledger_dir": root.to_string_lossy(),
}))
}
/// Compute a watermark digest over committed / reconciled records for a run.
pub fn effects_watermark(args: &Value) -> Result<Value, String> {
let listed = effects_list(args)?;
let records = listed
.get("records")
.and_then(|v| v.as_array())
.cloned()
.unwrap_or_default();
let mut parts = Vec::new();
let mut open_unknown = 0u64;
let mut pending_writes = 0u64;
for r in &records {
let state = r.get("state").and_then(|v| v.as_str()).unwrap_or("");
let oid = r.get("operation_id").and_then(|v| v.as_str()).unwrap_or("");
let cls = r.get("effect_class").and_then(|v| v.as_str()).unwrap_or("");
parts.push(format!("{oid}:{state}"));
if state == "unknown" || state == "needs_input" {
open_unknown += 1;
}
if matches!(cls, "write" | "external_write" | "execute")
&& matches!(state, "prepared" | "started" | "unknown" | "needs_input")
{
pending_writes += 1;
}
}
parts.sort();
let joined = parts.join("|");
let digest = format!("sha256-lite:{:x}", fnv64(&joined));
let write_auto_resume_safe = open_unknown == 0 && pending_writes == 0;
Ok(json!({
"ok": true,
"schema": "EffectLedgerWatermarkV1",
"schema_version": 1,
"watermark": digest,
"record_count": records.len(),
"open_unknown": open_unknown,
"pending_writes": pending_writes,
"write_auto_resume_safe": write_auto_resume_safe,
"logical_run_id": args.get("logical_run_id").cloned().unwrap_or(Value::Null),
}))
}
/// Reconcile an `unknown` record after inspecting the external receipt / revision.
pub fn effects_reconcile(args: &Value) -> Result<Value, String> {
let outcome = arg_text(args, "outcome")?; // committed | no_effect | needs_input
let state = match outcome {
"committed" => "reconciled_committed",
"no_effect" => "reconciled_no_effect",
"needs_input" => "needs_input",
other => return Err(format!("invalid reconcile outcome={other}")),
};
let mut targs = args.clone();
if let Some(obj) = targs.as_object_mut() {
obj.insert("state".into(), json!(state));
}
effects_transition(&targs)
}
fn fnv64(s: &str) -> u64 {
let mut h: u64 = 0xcbf29ce484222325;
for b in s.as_bytes() {
h ^= u64::from(*b);
h = h.wrapping_mul(0x100000001b3);
}
h
}
#[cfg(test)]
mod tests {
use super::*;
fn scratch(tag: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!(
"mq-effects-{}-{}-{}",
tag,
std::process::id(),
now_rfc3339().replace(':', "")
));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
dir
}
#[test]
fn prepare_dedupe_and_collision() {
let dir = scratch("prep");
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
let a = effects_prepare(&json!({
"operation_id": "op1",
"idempotency_key": "idem1",
"args_digest": "sha256:a",
"effect_class": "write",
"ledger_dir": "led",
"logical_run_id": "run1",
}))
.unwrap();
assert_eq!(a["deduped"], false);
assert_eq!(a["record"]["state"], "prepared");
let again = effects_prepare(&json!({
"operation_id": "op1",
"idempotency_key": "idem1",
"args_digest": "sha256:a",
"ledger_dir": "led",
}))
.unwrap();
assert_eq!(again["deduped"], true);
let clash = effects_prepare(&json!({
"operation_id": "op2",
"idempotency_key": "idem1",
"args_digest": "sha256:b",
"ledger_dir": "led",
}));
assert!(clash.unwrap_err().contains("collision"));
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir);
}
#[test]
fn transition_and_watermark_gates_write_resume() {
let dir = scratch("wm");
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
effects_prepare(&json!({
"operation_id": "op_w",
"idempotency_key": "idem_w",
"args_digest": "sha256:w",
"effect_class": "write",
"ledger_dir": "led",
"logical_run_id": "run1",
}))
.unwrap();
effects_transition(&json!({
"operation_id": "op_w",
"state": "started",
"ledger_dir": "led",
}))
.unwrap();
// Crash window: unknown — write auto-resume must stay closed.
effects_transition(&json!({
"operation_id": "op_w",
"state": "unknown",
"ledger_dir": "led",
}))
.unwrap();
let wm1 = effects_watermark(&json!({
"ledger_dir": "led",
"logical_run_id": "run1",
}))
.unwrap();
assert_eq!(wm1["write_auto_resume_safe"], false);
assert_eq!(wm1["open_unknown"], 1);
effects_reconcile(&json!({
"operation_id": "op_w",
"outcome": "committed",
"ledger_dir": "led",
"result_ref": "receipt:1",
}))
.unwrap();
let wm2 = effects_watermark(&json!({
"ledger_dir": "led",
"logical_run_id": "run1",
}))
.unwrap();
assert_eq!(wm2["write_auto_resume_safe"], true);
assert_eq!(wm2["open_unknown"], 0);
assert!(wm2["watermark"].as_str().unwrap().starts_with("sha256-lite:"));
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir);
}
#[test]
fn ma_t03_unknown_then_reconcile_no_second_commit_path() {
// Write "succeeds" locally only after reconcile; retry while unknown must not
// look write_auto_resume_safe (MA-T03 watermark gate).
let dir = scratch("mat03");
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
effects_prepare(&json!({
"operation_id": "op_kill",
"idempotency_key": "run|s|write_probe|sha256-lite:1",
"args_digest": "sha256-lite:1",
"effect_class": "write",
"ledger_dir": "led",
"logical_run_id": "run_kill",
}))
.unwrap();
effects_transition(&json!({
"operation_id": "op_kill",
"state": "started",
"ledger_dir": "led",
}))
.unwrap();
// Crash before commit:
effects_transition(&json!({
"operation_id": "op_kill",
"state": "unknown",
"ledger_dir": "led",
}))
.unwrap();
let wm = effects_watermark(&json!({
"ledger_dir": "led",
"logical_run_id": "run_kill",
}))
.unwrap();
assert_eq!(wm["write_auto_resume_safe"], false);
// Idempotent re-prepare returns same unknown record (no new op).
let again = effects_prepare(&json!({
"operation_id": "op_kill",
"idempotency_key": "run|s|write_probe|sha256-lite:1",
"args_digest": "sha256-lite:1",
"effect_class": "write",
"ledger_dir": "led",
"logical_run_id": "run_kill",
}))
.unwrap();
assert_eq!(again["deduped"], true);
assert_eq!(again["record"]["state"], "unknown");
effects_reconcile(&json!({
"operation_id": "op_kill",
"outcome": "committed",
"ledger_dir": "led",
"result_ref": "effect:op_kill",
}))
.unwrap();
let wm2 = effects_watermark(&json!({
"ledger_dir": "led",
"logical_run_id": "run_kill",
}))
.unwrap();
assert_eq!(wm2["write_auto_resume_safe"], true);
assert_eq!(wm2["pending_writes"], 0);
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir);
}
#[test]
fn illegal_skip_started() {
let dir = scratch("bad");
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
effects_prepare(&json!({
"operation_id": "op_x",
"idempotency_key": "idem_x",
"args_digest": "sha256:x",
"ledger_dir": "led",
}))
.unwrap();
let err = effects_transition(&json!({
"operation_id": "op_x",
"state": "committed",
"ledger_dir": "led",
}))
.unwrap_err();
assert!(err.contains("illegal transition"));
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir);
}
}
+274
View File
@@ -0,0 +1,274 @@
//! AgentErrorV1 — classified errors and bounded recovery decisions (M-A1).
use serde_json::{json, Value};
/// Build an AgentErrorV1 document from caller fields (compat: missing → defaults).
pub fn make_error(args: &Value) -> Result<Value, String> {
let code = args
.get("code")
.and_then(|v| v.as_str())
.filter(|s| !s.is_empty())
.ok_or_else(|| "missing text `code`".to_string())?;
let category = args
.get("category")
.and_then(|v| v.as_str())
.unwrap_or_else(|| infer_category(code));
let stage = args
.get("stage")
.and_then(|v| v.as_str())
.unwrap_or("agent");
let message = args
.get("message")
.and_then(|v| v.as_str())
.unwrap_or(code);
let retryable = args
.get("retryable")
.and_then(|v| v.as_bool())
.unwrap_or_else(|| default_retryable(category));
let effect_state = args
.get("effect_state")
.and_then(|v| v.as_str())
.unwrap_or("none");
let recovery_action = args
.get("recovery_action")
.and_then(|v| v.as_str())
.unwrap_or_else(|| default_recovery(category, effect_state));
let mut out = json!({
"schema": "AgentErrorV1",
"schema_version": 1,
"code": code,
"category": category,
"stage": stage,
"message": message,
"retryable": retryable,
"effect_state": effect_state,
"recovery_action": recovery_action,
});
if let Some(obj) = out.as_object_mut() {
if let Some(v) = args.get("retry_after_ms") {
obj.insert("retry_after_ms".into(), v.clone());
} else {
obj.insert("retry_after_ms".into(), Value::Null);
}
for key in ["call_id", "details_ref", "fingerprint"] {
if let Some(v) = args.get(key) {
if !v.is_null() {
obj.insert(key.into(), v.clone());
}
}
}
}
Ok(out)
}
/// Decide whether a step may auto-retry (read-only / no-effect only in M-A1).
///
/// Returns `{ok, action, reason, attempts_used, max_attempts}`.
pub fn decide_retry(args: &Value) -> Result<Value, String> {
let error = args
.get("error")
.cloned()
.ok_or_else(|| "missing map `error`".to_string())?;
let attempts = args
.get("attempts")
.and_then(|v| v.as_u64())
.unwrap_or(0) as u32;
let max_transport = args
.get("max_transport_attempts")
.and_then(|v| v.as_u64())
.unwrap_or(3) as u32; // 1 initial + 2 retries
let max_arg_repair = args
.get("max_arg_repairs")
.and_then(|v| v.as_u64())
.unwrap_or(1) as u32;
let effect_class = args
.get("effect_class")
.and_then(|v| v.as_str())
.unwrap_or("read");
let cancelled = args
.get("cancelled")
.and_then(|v| v.as_bool())
.unwrap_or(false);
let fingerprint_repeats = args
.get("fingerprint_repeats")
.and_then(|v| v.as_u64())
.unwrap_or(0) as u32;
if cancelled {
return Ok(decision("stop", "cancelled", attempts, max_transport));
}
let category = error
.get("category")
.and_then(|v| v.as_str())
.unwrap_or("unknown");
let retryable = error
.get("retryable")
.and_then(|v| v.as_bool())
.unwrap_or(false);
let effect_state = error
.get("effect_state")
.and_then(|v| v.as_str())
.unwrap_or("none");
let recovery = error
.get("recovery_action")
.and_then(|v| v.as_str())
.unwrap_or("none");
// Write / unknown effect: never auto-retry in M-A1 (ledger required).
if effect_class != "read" || matches!(effect_state, "unknown" | "started" | "committed") {
return Ok(decision(
"manual_review",
"write_or_unknown_effect_requires_ledger",
attempts,
max_transport,
));
}
if fingerprint_repeats >= 2 {
return Ok(decision(
"stop",
"error_fingerprint_loop",
attempts,
max_transport,
));
}
match category {
"transient" if retryable && attempts + 1 < max_transport => Ok(decision(
"retry_step",
"transient_read_safe",
attempts,
max_transport,
)),
"invalid_arguments" if recovery == "repair_args" && attempts < max_arg_repair => Ok(
decision("repair_args", "one_arg_repair", attempts, max_arg_repair),
),
"auth" | "forbidden" | "policy_denied" => Ok(decision(
"needs_input",
category,
attempts,
max_transport,
)),
"budget_exhausted" => Ok(decision("partial", category, attempts, max_transport)),
"cancelled" => Ok(decision("stop", "cancelled", attempts, max_transport)),
"unknown_effect" | "worker_crash" => Ok(decision(
"manual_review",
category,
attempts,
max_transport,
)),
_ => Ok(decision("stop", "not_auto_retryable", attempts, max_transport)),
}
}
fn decision(action: &str, reason: &str, attempts: u32, max_attempts: u32) -> Value {
json!({
"ok": true,
"schema": "AgentRetryDecisionV1",
"schema_version": 1,
"action": action,
"reason": reason,
"attempts_used": attempts,
"max_attempts": max_attempts,
"auto": matches!(action, "retry_step" | "repair_args"),
})
}
fn infer_category(code: &str) -> &'static str {
let c = code.to_ascii_lowercase();
if c.contains("timeout") || c.contains("429") || c.contains("5xx") || c.contains("connect") {
"transient"
} else if c.contains("schema") || c.contains("argument") {
"invalid_arguments"
} else if c.contains("auth") {
"auth"
} else if c.contains("forbid") {
"forbidden"
} else if c.contains("policy") {
"policy_denied"
} else if c.contains("budget") {
"budget_exhausted"
} else if c.contains("cancel") {
"cancelled"
} else if c.contains("conflict") || c.contains("stale") {
"conflict"
} else if c.contains("effect") || c.contains("crash") {
"unknown_effect"
} else {
"unknown"
}
}
fn default_retryable(category: &str) -> bool {
matches!(category, "transient")
}
fn default_recovery(category: &str, effect_state: &str) -> &'static str {
if effect_state == "unknown" {
return "reconcile";
}
match category {
"transient" => "retry_step",
"invalid_arguments" => "repair_args",
"auth" | "forbidden" | "policy_denied" | "needs_input" => "needs_input",
"budget_exhausted" => "return_partial",
"cancelled" => "stop",
"unknown_effect" | "worker_crash" => "manual_review",
_ => "stop",
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn make_error_defaults() {
let err = make_error(&json!({"code": "tool.timeout", "message": "t"})).unwrap();
assert_eq!(err["schema"], "AgentErrorV1");
assert_eq!(err["category"], "transient");
assert_eq!(err["retryable"], true);
assert_eq!(err["recovery_action"], "retry_step");
}
#[test]
fn read_transient_retries_once() {
let err = make_error(&json!({"code": "tool.timeout"})).unwrap();
let d = decide_retry(&json!({
"error": err,
"attempts": 0,
"effect_class": "read"
}))
.unwrap();
assert_eq!(d["action"], "retry_step");
assert_eq!(d["auto"], true);
}
#[test]
fn write_never_auto_retries() {
let err = make_error(&json!({"code": "tool.timeout"})).unwrap();
let d = decide_retry(&json!({
"error": err,
"attempts": 0,
"effect_class": "write"
}))
.unwrap();
assert_eq!(d["action"], "manual_review");
assert_eq!(d["auto"], false);
}
#[test]
fn fingerprint_loop_stops() {
let err = make_error(&json!({"code": "tool.timeout"})).unwrap();
let d = decide_retry(&json!({
"error": err,
"attempts": 0,
"effect_class": "read",
"fingerprint_repeats": 2
}))
.unwrap();
assert_eq!(d["action"], "stop");
}
}
+150 -1
View File
@@ -1,14 +1,19 @@
//! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb + v2 memory + adaptive route.
mod context_pack;
mod corpus;
mod effects;
mod eng;
mod error;
mod kb;
mod mcp_client;
mod mcp_server;
mod memory;
mod output;
mod resume;
mod route;
mod sandbox;
mod tools;
use std::collections::HashMap;
use std::ffi::CString;
@@ -667,7 +672,7 @@ unsafe extern "C" fn agent_marqdo_skill(
}
}
fn tool_names(tools: &serde_json::Value) -> Vec<String> {
pub(crate) fn tool_names(tools: &serde_json::Value) -> Vec<String> {
let mut out = Vec::new();
let rows = match tools {
serde_json::Value::Array(a) => a.as_slice(),
@@ -829,6 +834,86 @@ kb_ffi!(agent_resume_save, resume::resume_save, "agent_resume_save");
kb_ffi!(agent_resume_load, resume::resume_load, "agent_resume_load");
kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear");
kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list");
kb_ffi!(agent_error_make, error::make_error, "agent_error_make");
kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry");
kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register");
kb_ffi!(agent_tools_clear, tools::tools_clear, "agent_tools_clear");
kb_ffi!(agent_tools_search, tools::tools_search, "agent_tools_search");
kb_ffi!(agent_tools_describe, tools::tools_describe, "agent_tools_describe");
kb_ffi!(agent_tools_prepare_call, tools::tools_prepare_call, "agent_tools_prepare_call");
kb_ffi!(agent_tools_wrap_result, tools::tools_wrap_result, "agent_tools_wrap_result");
kb_ffi!(
agent_tools_args_digest,
tools::tools_args_digest,
"agent_tools_args_digest"
);
kb_ffi!(
agent_tools_needs_ledger,
tools::tools_needs_ledger,
"agent_tools_needs_ledger"
);
kb_ffi!(
agent_tools_register_eng_defaults,
tools::tools_register_eng_defaults,
"agent_tools_register_eng_defaults"
);
kb_ffi!(
agent_tools_seed_allowlist,
tools::seed_from_allowlist_args,
"agent_tools_seed_allowlist"
);
kb_ffi!(agent_output_build, output::output_build, "agent_output_build");
kb_ffi!(
agent_output_apply_policy,
output::output_apply_policy,
"agent_output_apply_policy"
);
kb_ffi!(
agent_output_channel_event,
output::output_channel_event,
"agent_output_channel_event"
);
kb_ffi!(
agent_output_project_conclusion,
output::output_project_conclusion,
"agent_output_project_conclusion"
);
kb_ffi!(
agent_context_pack_build,
context_pack::context_pack_build,
"agent_context_pack_build"
);
kb_ffi!(
agent_context_pack_compact,
context_pack::context_pack_compact,
"agent_context_pack_compact"
);
kb_ffi!(
agent_effects_prepare,
effects::effects_prepare,
"agent_effects_prepare"
);
kb_ffi!(
agent_effects_transition,
effects::effects_transition,
"agent_effects_transition"
);
kb_ffi!(agent_effects_get, effects::effects_get, "agent_effects_get");
kb_ffi!(
agent_effects_list,
effects::effects_list,
"agent_effects_list"
);
kb_ffi!(
agent_effects_watermark,
effects::effects_watermark,
"agent_effects_watermark"
);
kb_ffi!(
agent_effects_reconcile,
effects::effects_reconcile,
"agent_effects_reconcile"
);
kb_ffi!(agent_eng_preflight, eng::eng_preflight, "agent_eng_preflight");
kb_ffi!(agent_eng_reuse, eng::eng_reuse, "agent_eng_reuse");
kb_ffi!(agent_eng_bind_execute, eng::eng_bind_execute, "agent_eng_bind_execute");
@@ -878,6 +963,70 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
("agent_resume_load", "id,resume_dir", agent_resume_load),
("agent_resume_clear", "id,resume_dir", agent_resume_clear),
("agent_resume_list", "resume_dir", agent_resume_list),
("agent_error_make", "code,message,category", agent_error_make),
("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry),
("agent_tools_register", "spec,specs", agent_tools_register),
("agent_tools_clear", "", agent_tools_clear),
("agent_tools_search", "query,tools", agent_tools_search),
("agent_tools_describe", "id,tools", agent_tools_describe),
("agent_tools_prepare_call", "tool_id,arguments,tools", agent_tools_prepare_call),
("agent_tools_wrap_result", "ok,status,summary", agent_tools_wrap_result),
("agent_tools_args_digest", "arguments", agent_tools_args_digest),
("agent_tools_needs_ledger", "effect", agent_tools_needs_ledger),
(
"agent_tools_register_eng_defaults",
"",
agent_tools_register_eng_defaults,
),
("agent_tools_seed_allowlist", "tools", agent_tools_seed_allowlist),
("agent_output_build", "status,text,validation", agent_output_build),
(
"agent_output_apply_policy",
"status,text,policy",
agent_output_apply_policy,
),
(
"agent_output_channel_event",
"channel,delta",
agent_output_channel_event,
),
(
"agent_output_project_conclusion",
"document",
agent_output_project_conclusion,
),
(
"agent_context_pack_build",
"items,budget_tokens",
agent_context_pack_build,
),
(
"agent_context_pack_compact",
"items,budget_tokens",
agent_context_pack_compact,
),
(
"agent_effects_prepare",
"operation_id,idempotency_key,args_digest",
agent_effects_prepare,
),
(
"agent_effects_transition",
"operation_id,state",
agent_effects_transition,
),
("agent_effects_get", "operation_id", agent_effects_get),
("agent_effects_list", "ledger_dir", agent_effects_list),
(
"agent_effects_watermark",
"ledger_dir",
agent_effects_watermark,
),
(
"agent_effects_reconcile",
"operation_id,outcome",
agent_effects_reconcile,
),
("agent_kb_add_alias", "kb_dir,slug,alias", agent_kb_add_alias),
("agent_kb_promote", "kb_dir,goal,workbook", agent_kb_promote),
("agent_kb_quarantine", "kb_dir,slug", agent_kb_quarantine),
+289
View File
@@ -0,0 +1,289 @@
//! AgentOutputV1 + ResponsePolicy (M-A4).
use serde_json::{json, Value};
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
args.get(key)
.and_then(|v| v.as_str())
.filter(|s| !s.is_empty())
}
/// Normalize / build an AgentOutputV1 document.
pub fn output_build(args: &Value) -> Result<Value, String> {
let status = opt_text(args, "status").unwrap_or("succeeded");
if !matches!(
status,
"succeeded" | "partial" | "failed" | "needs_input" | "cancelled"
) {
return Err(format!("invalid status={status}"));
}
let answer = args.get("answer").cloned().unwrap_or_else(|| {
json!({
"format": opt_text(args, "format").unwrap_or("markdown"),
"text": opt_text(args, "text").unwrap_or(""),
})
});
let validation = args.get("validation").cloned().unwrap_or_else(|| {
json!({
"status": "not_run",
"report_ref": Value::Null
})
});
let vstatus = validation
.get("status")
.and_then(|v| v.as_str())
.unwrap_or("not_run");
if !matches!(
vstatus,
"passed" | "failed" | "not_applicable" | "not_run"
) {
return Err(format!("invalid validation.status={vstatus}"));
}
// Never claim passed without an explicit report when status says passed.
if vstatus == "passed" && validation.get("report_ref").map(|v| v.is_null()).unwrap_or(true) {
if args.get("allow_passed_without_report").and_then(|v| v.as_bool()) != Some(true) {
return Err("validation.status=passed requires report_ref".into());
}
}
let finish = opt_text(args, "finish_reason").unwrap_or(match status {
"succeeded" => "completed",
"partial" => "length_limited",
"cancelled" => "cancelled",
"needs_input" => "needs_input",
_ => "error",
});
Ok(json!({
"schema": "AgentOutputV1",
"schema_version": 1,
"status": status,
"answer": answer,
"artifacts": args.get("artifacts").cloned().unwrap_or_else(|| json!([])),
"citations": args.get("citations").cloned().unwrap_or_else(|| json!([])),
"validation": validation,
"finish_reason": finish,
"recovery_options": args.get("recovery_options").cloned().unwrap_or_else(|| json!([])),
"channels": args.get("channels").cloned().unwrap_or_else(|| json!({
"answer": true,
"artifact": true,
"progress": true,
"diagnostic": true
})),
}))
}
/// Apply ResponsePolicy budgets to an answer text → possibly partial output.
pub fn output_apply_policy(args: &Value) -> Result<Value, String> {
let mut out = if args.get("schema").and_then(|v| v.as_str()) == Some("AgentOutputV1") {
args.clone()
} else {
output_build(args)?
};
let policy = args.get("policy").cloned().unwrap_or(json!({}));
let detail = policy
.get("detail")
.and_then(|v| v.as_str())
.unwrap_or("standard");
let max_chars = match policy.get("max_chars").and_then(|v| v.as_u64()) {
Some(n) if n > 0 => n as usize,
_ => match detail {
"concise" => 250,
"detailed" => 8_000,
_ => 700,
},
};
let max_tokens = policy
.get("max_output_tokens")
.and_then(|v| v.as_u64())
.unwrap_or(0) as usize;
let artifact_allowed = policy
.get("artifact_allowed")
.and_then(|v| v.as_bool())
.unwrap_or(true);
let text = out
.pointer("/answer/text")
.and_then(|v| v.as_str())
.unwrap_or("")
.to_string();
// Soft char budget (CJK-aware enough: count Unicode scalars).
let chars: Vec<char> = text.chars().collect();
let mut finish = out
.get("finish_reason")
.and_then(|v| v.as_str())
.unwrap_or("completed")
.to_string();
let mut status = out
.get("status")
.and_then(|v| v.as_str())
.unwrap_or("succeeded")
.to_string();
let mut answer_text = text.clone();
if chars.len() > max_chars {
answer_text = chars.into_iter().take(max_chars).collect();
// Prefer not to cut mid-code fence if possible — soft trim at last newline.
if let Some(pos) = answer_text.rfind('\n') {
if pos > max_chars / 2 {
answer_text.truncate(pos);
}
}
finish = "length_limited".into();
if status == "succeeded" {
status = "partial".into();
}
}
// Token budget is advisory here (chars/4 approx) when max_output_tokens set.
if max_tokens > 0 {
let approx = answer_text.chars().count().div_ceil(2); // rough CJK token estimate
if approx > max_tokens {
let keep = max_tokens.saturating_mul(2);
answer_text = answer_text.chars().take(keep).collect();
finish = "length_limited".into();
status = "partial".into();
}
}
if let Some(obj) = out.as_object_mut() {
obj.insert("status".into(), json!(status));
obj.insert("finish_reason".into(), json!(finish));
if let Some(ans) = obj.get_mut("answer").and_then(|v| v.as_object_mut()) {
ans.insert("text".into(), json!(answer_text));
}
if !artifact_allowed {
obj.insert("artifacts".into(), json!([]));
}
obj.insert(
"response_policy".into(),
json!({
"detail": detail,
"max_chars": max_chars,
"max_output_tokens": max_tokens,
"artifact_allowed": artifact_allowed,
}),
);
}
Ok(out)
}
/// Split a channel event. Only `answer` is meant for chat body append.
pub fn output_channel_event(args: &Value) -> Result<Value, String> {
let channel = opt_text(args, "channel").ok_or_else(|| "missing channel".to_string())?;
if !matches!(channel, "answer" | "artifact" | "progress" | "diagnostic") {
return Err(format!("invalid channel={channel}"));
}
let delta = opt_text(args, "delta").unwrap_or("");
Ok(json!({
"schema": "AgentChannelEventV1",
"schema_version": 1,
"channel": channel,
"delta": delta,
"append_to_chat": channel == "answer",
"resource_id": args.get("resource_id").cloned().unwrap_or(Value::Null),
"meta": args.get("meta").cloned().unwrap_or(json!({})),
}))
}
/// Project `# 结论` (or first non-empty paragraph) from a marqdo document for chat.
pub fn output_project_conclusion(args: &Value) -> Result<Value, String> {
let doc = opt_text(args, "document")
.or_else(|| opt_text(args, "text"))
.unwrap_or("");
let mut in_conclusion = false;
let mut buf = String::new();
for line in doc.lines() {
let t = line.trim();
if t == "# 结论" || t.eq_ignore_ascii_case("# conclusion") {
in_conclusion = true;
continue;
}
if in_conclusion {
if t.starts_with("# ") {
break;
}
if t.is_empty() {
if !buf.is_empty() {
buf.push('\n');
}
continue;
}
if !buf.is_empty() {
buf.push('\n');
}
buf.push_str(t);
}
}
if buf.trim().is_empty() {
// Fallback: first non-frontmatter paragraph.
let mut past_fm = !doc.starts_with("---");
let mut fm_done = past_fm;
for line in doc.lines() {
if !fm_done {
if line.trim() == "---" {
if past_fm {
fm_done = true;
} else {
past_fm = true;
}
}
continue;
}
let t = line.trim();
if t.is_empty() || t.starts_with('#') || t.starts_with('|') {
continue;
}
buf = t.to_string();
break;
}
}
Ok(json!({
"ok": true,
"text": buf.trim(),
"channel": "answer",
"source": "conclusion_projection",
}))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn build_and_policy_limits() {
let out = output_build(&json!({
"status": "succeeded",
"text": "短答",
"validation": {"status": "not_applicable", "report_ref": null}
}))
.unwrap();
assert_eq!(out["schema"], "AgentOutputV1");
assert_eq!(out["answer"]["text"], "短答");
let long: String = "字".repeat(400);
let limited = output_apply_policy(&json!({
"status": "succeeded",
"text": long,
"validation": {"status": "not_applicable"},
"policy": {"detail": "concise", "max_chars": 100}
}))
.unwrap();
assert_eq!(limited["status"], "partial");
assert_eq!(limited["finish_reason"], "length_limited");
assert!(limited["answer"]["text"].as_str().unwrap().chars().count() <= 100);
}
#[test]
fn channel_answer_only_appends_chat() {
let e = output_channel_event(&json!({"channel": "progress", "delta": "检索中"})).unwrap();
assert_eq!(e["append_to_chat"], false);
let a = output_channel_event(&json!({"channel": "answer", "delta": "hi"})).unwrap();
assert_eq!(a["append_to_chat"], true);
}
#[test]
fn project_conclusion() {
let doc = "---\ntitle: t\n---\n\n# 任务\n问\n\n# 结论\n答案是 42。\n\n# main\nprint\n";
let p = output_project_conclusion(&json!({"document": doc})).unwrap();
assert!(p["text"].as_str().unwrap().contains("42"));
}
}
+348 -16
View File
@@ -1,6 +1,8 @@
//! Agent plan/run resume checkpoints under `.marqdo/agent-resume/`.
//! M-A1: CheckpointV2 atomic write (temp→fsync→rename); legacy load → manual_review.
use std::fs;
use std::fs::{self, File, OpenOptions};
use std::io::Write;
use std::path::{Path, PathBuf};
use serde_json::{json, Value};
@@ -27,7 +29,9 @@ fn resolve_path(rel: &str) -> PathBuf {
}
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
args.get(key).and_then(|v| v.as_str()).filter(|s| !s.is_empty())
args.get(key)
.and_then(|v| v.as_str())
.filter(|s| !s.is_empty())
}
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
@@ -43,9 +47,19 @@ fn opt_i64(args: &Value, key: &str, default: i64) -> i64 {
}
}
fn resume_root(args: &Value) -> PathBuf {
/// Host-relative resume roots only — reject absolute client paths (M-A1).
fn resume_root(args: &Value) -> Result<PathBuf, String> {
let rel = opt_text(args, "resume_dir").unwrap_or(DEFAULT_RESUME_DIR);
resolve_path(rel)
let p = PathBuf::from(rel);
if p.is_absolute() {
return Err(
"resume_dir must be host-relative; absolute client paths are rejected".into(),
);
}
if rel.contains("..") {
return Err("resume_dir must not contain '..'".into());
}
Ok(resolve_path(rel))
}
fn checkpoint_path(root: &Path, id: &str) -> PathBuf {
@@ -70,11 +84,106 @@ fn ensure_dir(root: &Path) -> Result<(), String> {
fs::create_dir_all(root).map_err(|e| format!("resume mkdir: {e}"))
}
pub fn resume_save(args: &Value) -> Result<Value, String> {
let id = arg_text(args, "id")?;
let root = resume_root(args);
ensure_dir(&root)?;
let path = checkpoint_path(&root, id);
/// Atomic durable write: unique temp → write → flush/fsync → rename.
fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> {
let parent = path
.parent()
.ok_or_else(|| "checkpoint path has no parent".to_string())?;
ensure_dir(parent)?;
let tmp_name = format!(
".{}.tmp-{}-{}",
path.file_name()
.and_then(|s| s.to_str())
.unwrap_or("ckpt.json"),
std::process::id(),
now_rfc3339().replace(':', "")
);
let tmp = parent.join(tmp_name);
let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?;
{
let mut f = OpenOptions::new()
.create(true)
.write(true)
.truncate(true)
.open(&tmp)
.map_err(|e| format!("resume temp open: {e}"))?;
f.write_all(text.as_bytes())
.map_err(|e| format!("resume temp write: {e}"))?;
f.flush().map_err(|e| format!("resume temp flush: {e}"))?;
f.sync_all()
.map_err(|e| format!("resume temp fsync: {e}"))?;
}
// Best-effort directory fsync (platform may ignore).
if let Ok(dir) = File::open(parent) {
let _ = dir.sync_all();
}
fs::rename(&tmp, path).map_err(|e| {
let _ = fs::remove_file(&tmp);
format!("resume atomic rename: {e}")
})?;
Ok(())
}
fn wants_checkpoint_v2(args: &Value) -> bool {
matches!(
args.get("schema").and_then(|v| v.as_str()),
Some("CheckpointV2")
) || args.get("schema_version").and_then(|v| v.as_u64()) == Some(2)
|| args.get("checkpoint_v2").and_then(|v| v.as_bool()) == Some(true)
}
fn build_checkpoint_v2(args: &Value, id: &str) -> Value {
let committed = now_rfc3339();
let mut doc = json!({
"schema": "CheckpointV2",
"schema_version": 2,
"checkpoint_id": args.get("checkpoint_id").cloned().unwrap_or_else(|| json!(id)),
"logical_run_id": args.get("logical_run_id").cloned().unwrap_or_else(|| json!(id)),
"task_id": args.get("task_id").cloned().unwrap_or_else(|| json!(id)),
"attempt_id": args.get("attempt_id").cloned().unwrap_or_else(|| json!("attempt_1")),
"step_id": args.get("step_id").cloned().unwrap_or(Value::Null),
"parent_checkpoint_id": args.get("parent_checkpoint_id").cloned().unwrap_or(Value::Null),
"principal_ref": args.get("principal_ref").cloned().unwrap_or(Value::Null),
"workspace_id": args.get("workspace_id").cloned().unwrap_or(Value::Null),
"session_id": args.get("session_id").cloned().unwrap_or(Value::Null),
"completed_steps": args.get("completed_steps").cloned().unwrap_or_else(|| json!([])),
"pending_operation": args.get("pending_operation").cloned().unwrap_or(Value::Null),
"deadline": args.get("deadline").cloned().unwrap_or(Value::Null),
"committed_at": args.get("committed_at").cloned().unwrap_or_else(|| json!(committed)),
// Effect watermark — absent/null means no ledger yet (write auto-resume closed).
"effect_ledger_watermark": args.get("effect_ledger_watermark").cloned().unwrap_or(Value::Null),
"event_seq": args.get("event_seq").cloned().unwrap_or(Value::Null),
"manifest_digest": args.get("manifest_digest").cloned().unwrap_or(Value::Null),
});
if let Some(obj) = doc.as_object_mut() {
// Preserve legacy author fields for dual-read.
for key in [
"goal", "task", "status", "workbook", "events", "route", "result", "round", "meta",
"id",
] {
if let Some(v) = args.get(key) {
if !v.is_null() {
obj.insert(key.to_string(), v.clone());
}
}
}
if !obj.contains_key("id") {
obj.insert("id".into(), json!(id));
}
if !obj.contains_key("updated_at") {
obj.insert("updated_at".into(), json!(committed.clone()));
}
if !obj.contains_key("round") {
obj.insert("round".into(), json!(opt_i64(args, "round", 0)));
}
if !obj.contains_key("status") {
obj.insert("status".into(), json!("running"));
}
}
doc
}
fn build_legacy_doc(args: &Value, id: &str) -> Value {
let mut doc = json!({
"id": id,
"updated_at": now_rfc3339(),
@@ -96,19 +205,84 @@ pub fn resume_save(args: &Value) -> Result<Value, String> {
obj.insert("status".into(), json!("running"));
}
}
let text = serde_json::to_string_pretty(&doc).map_err(|e| e.to_string())?;
fs::write(&path, text).map_err(|e| format!("resume save: {e}"))?;
doc
}
pub fn resume_save(args: &Value) -> Result<Value, String> {
let id = arg_text(args, "id")?;
let root = resume_root(args)?;
ensure_dir(&root)?;
let path = checkpoint_path(&root, id);
let v2 = wants_checkpoint_v2(args);
let doc = if v2 {
build_checkpoint_v2(args, id)
} else {
build_legacy_doc(args, id)
};
atomic_write_json(&path, &doc)?;
Ok(json!({
"ok": true,
"id": id,
"path": path.to_string_lossy(),
"updated_at": doc.get("updated_at").cloned().unwrap_or(Value::Null),
"schema": doc.get("schema").cloned().unwrap_or(Value::Null),
"schema_version": doc.get("schema_version").cloned().unwrap_or(Value::Null),
"updated_at": doc.get("updated_at").or_else(|| doc.get("committed_at")).cloned().unwrap_or(Value::Null),
"atomic": true,
}))
}
fn watermark_allows_write_auto(wm: &Value) -> bool {
match wm {
Value::Null => false,
Value::String(s) => !s.is_empty(),
Value::Object(obj) => {
// Prefer explicit safety bit from effects_watermark; bare digest objects
// without the bit are treated as unsafe (open unknown / pending writes).
match obj.get("write_auto_resume_safe").and_then(|v| v.as_bool()) {
Some(b) => b,
None => obj
.get("watermark")
.and_then(|v| v.as_str())
.map(|s| !s.is_empty())
.unwrap_or(false)
&& obj.get("open_unknown").and_then(|v| v.as_u64()).unwrap_or(1) == 0
&& obj.get("pending_writes").and_then(|v| v.as_u64()).unwrap_or(1) == 0,
}
}
_ => false,
}
}
fn annotate_recovery(mut doc: Value) -> Value {
let is_v2 = doc.get("schema").and_then(|v| v.as_str()) == Some("CheckpointV2")
&& doc.get("schema_version").and_then(|v| v.as_u64()) == Some(2);
let wm = doc
.get("effect_ledger_watermark")
.cloned()
.unwrap_or(Value::Null);
let ledger_safe = watermark_allows_write_auto(&wm);
let (recovery_mode, write_auto_resume) = if is_v2 && ledger_safe {
("checkpoint_v2", true)
} else if is_v2 {
// V2 without a safe ledger watermark: read resume OK; write auto-resume closed.
("checkpoint_v2_read_only", false)
} else {
// Legacy: no effect info → manual_review; never auto redo writes.
("manual_review", false)
};
if let Some(obj) = doc.as_object_mut() {
obj.insert("recovery_mode".into(), json!(recovery_mode));
obj.insert("write_auto_resume".into(), json!(write_auto_resume));
if !is_v2 {
obj.insert("legacy_adaptation".into(), json!("manual_review"));
}
}
doc
}
pub fn resume_load(args: &Value) -> Result<Value, String> {
let id = arg_text(args, "id")?;
let root = resume_root(args);
let root = resume_root(args)?;
let path = checkpoint_path(&root, id);
if !path.is_file() {
return Ok(json!({
@@ -119,7 +293,31 @@ pub fn resume_load(args: &Value) -> Result<Value, String> {
}));
}
let text = fs::read_to_string(&path).map_err(|e| format!("resume load: {e}"))?;
let mut doc: Value = serde_json::from_str(&text).map_err(|e| format!("resume json: {e}"))?;
let parsed: Value = match serde_json::from_str(&text) {
Ok(v) => v,
Err(e) => {
return Ok(json!({
"ok": false,
"found": true,
"id": id,
"path": path.to_string_lossy(),
"error": {
"schema": "AgentErrorV1",
"schema_version": 1,
"code": "checkpoint.corrupt",
"category": "unknown_effect",
"stage": "checkpoint",
"message": format!("corrupt checkpoint json: {e}"),
"retryable": false,
"effect_state": "unknown",
"recovery_action": "manual_review",
},
"recovery_mode": "manual_review",
"write_auto_resume": false,
}));
}
};
let mut doc = annotate_recovery(parsed);
if let Some(obj) = doc.as_object_mut() {
obj.insert("ok".into(), json!(true));
obj.insert("found".into(), json!(true));
@@ -130,7 +328,7 @@ pub fn resume_load(args: &Value) -> Result<Value, String> {
pub fn resume_clear(args: &Value) -> Result<Value, String> {
let id = arg_text(args, "id")?;
let root = resume_root(args);
let root = resume_root(args)?;
let path = checkpoint_path(&root, id);
let existed = path.is_file();
if existed {
@@ -145,7 +343,7 @@ pub fn resume_clear(args: &Value) -> Result<Value, String> {
}
pub fn resume_list(args: &Value) -> Result<Value, String> {
let root = resume_root(args);
let root = resume_root(args)?;
if !root.is_dir() {
return Ok(json!({ "ok": true, "items": [], "resume_dir": root.to_string_lossy() }));
}
@@ -156,6 +354,14 @@ pub fn resume_list(args: &Value) -> Result<Value, String> {
if p.extension().and_then(|e| e.to_str()) != Some("json") {
continue;
}
// Skip leftover temp files from crashed writers.
if p.file_name()
.and_then(|s| s.to_str())
.map(|s| s.starts_with('.'))
.unwrap_or(false)
{
continue;
}
let id = p
.file_stem()
.and_then(|s| s.to_str())
@@ -179,3 +385,129 @@ pub fn resume_list(args: &Value) -> Result<Value, String> {
"resume_dir": root.to_string_lossy(),
}))
}
#[cfg(test)]
mod tests {
use super::*;
use std::time::{SystemTime, UNIX_EPOCH};
fn scratch(label: &str) -> PathBuf {
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_nanos();
let dir = std::env::temp_dir().join(format!("marqdo-resume-{label}-{nanos}"));
fs::create_dir_all(&dir).unwrap();
dir
}
#[test]
fn absolute_resume_dir_rejected() {
let err = resume_root(&json!({"resume_dir": "/tmp/evil"})).unwrap_err();
assert!(err.contains("host-relative"));
}
#[test]
fn atomic_v2_roundtrip_and_legacy_manual_review() {
let dir = scratch("v2");
// Use relative path via env cwd — chdir into scratch for this test.
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
let rel = "ckpts";
let saved = resume_save(&json!({
"id": "run1",
"schema": "CheckpointV2",
"schema_version": 2,
"goal": "ping",
"status": "running",
"round": 1,
"resume_dir": rel,
"attempt_id": "a1",
}))
.unwrap();
assert_eq!(saved["ok"], true);
assert_eq!(saved["atomic"], true);
assert_eq!(saved["schema"], "CheckpointV2");
let loaded = resume_load(&json!({"id": "run1", "resume_dir": rel})).unwrap();
assert_eq!(loaded["found"], true);
assert_eq!(loaded["schema"], "CheckpointV2");
assert_eq!(loaded["recovery_mode"], "checkpoint_v2_read_only");
assert_eq!(loaded["write_auto_resume"], false);
// Legacy document without schema.
let _ = resume_save(&json!({
"id": "legacy1",
"goal": "pong",
"status": "interrupted",
"round": 2,
"resume_dir": rel,
}))
.unwrap();
let legacy = resume_load(&json!({"id": "legacy1", "resume_dir": rel})).unwrap();
assert_eq!(legacy["recovery_mode"], "manual_review");
assert_eq!(legacy["write_auto_resume"], false);
assert_eq!(legacy["legacy_adaptation"], "manual_review");
// V2 + safe watermark → write_auto_resume opens.
let _ = resume_save(&json!({
"id": "run_safe",
"schema": "CheckpointV2",
"schema_version": 2,
"status": "running",
"round": 3,
"resume_dir": rel,
"attempt_id": "a2",
"effect_ledger_watermark": {
"schema": "EffectLedgerWatermarkV1",
"watermark": "sha256-lite:abc",
"write_auto_resume_safe": true,
"open_unknown": 0,
"pending_writes": 0
}
}))
.unwrap();
let safe = resume_load(&json!({"id": "run_safe", "resume_dir": rel})).unwrap();
assert_eq!(safe["recovery_mode"], "checkpoint_v2");
assert_eq!(safe["write_auto_resume"], true);
// Unsafe watermark (open unknown) keeps write auto-resume closed.
let _ = resume_save(&json!({
"id": "run_unsafe",
"schema": "CheckpointV2",
"schema_version": 2,
"status": "running",
"round": 4,
"resume_dir": rel,
"attempt_id": "a3",
"effect_ledger_watermark": {
"watermark": "sha256-lite:def",
"write_auto_resume_safe": false,
"open_unknown": 1
}
}))
.unwrap();
let unsafe_ck = resume_load(&json!({"id": "run_unsafe", "resume_dir": rel})).unwrap();
assert_eq!(unsafe_ck["recovery_mode"], "checkpoint_v2_read_only");
assert_eq!(unsafe_ck["write_auto_resume"], false);
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir);
}
#[test]
fn corrupt_checkpoint_reports_error() {
let dir = scratch("corrupt");
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
fs::create_dir_all("ckpts").unwrap();
fs::write("ckpts/bad.json", "{not-json").unwrap();
let loaded = resume_load(&json!({"id": "bad", "resume_dir": "ckpts"})).unwrap();
assert_eq!(loaded["found"], true);
assert_eq!(loaded["ok"], false);
assert_eq!(loaded["error"]["code"], "checkpoint.corrupt");
assert_eq!(loaded["recovery_mode"], "manual_review");
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir);
}
}
+794
View File
@@ -0,0 +1,794 @@
//! ToolSpecV1 registry + call validation (M-A2).
//! Discovery → schema validate → authorize. Execution of Marqdo `##` stays in subtask;
//! this module never evals model-supplied code.
use std::collections::HashMap;
use std::sync::{Mutex, OnceLock};
use serde_json::{json, Map, Value};
fn registry() -> &'static Mutex<HashMap<String, Value>> {
static REG: OnceLock<Mutex<HashMap<String, Value>>> = OnceLock::new();
REG.get_or_init(|| Mutex::new(HashMap::new()))
}
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
args.get(key)
.and_then(|v| v.as_str())
.filter(|s| !s.is_empty())
}
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
opt_text(args, key).ok_or_else(|| format!("missing text `{key}`"))
}
/// Supported JSON Schema subset for tool input (reject unsupported constructs).
fn validate_schema_subset(schema: &Value) -> Result<(), String> {
let obj = schema
.as_object()
.ok_or_else(|| "input_schema must be object".to_string())?;
let ty = obj
.get("type")
.and_then(|v| v.as_str())
.unwrap_or("object");
if ty != "object" {
return Err(format!("unsupported root type={ty}; only object"));
}
if let Some(props) = obj.get("properties") {
let props = props
.as_object()
.ok_or_else(|| "properties must be object".to_string())?;
for (name, prop) in props {
let p = prop
.as_object()
.ok_or_else(|| format!("property {name} must be object"))?;
let pty = p.get("type").and_then(|v| v.as_str()).unwrap_or("string");
match pty {
"string" | "integer" | "number" | "boolean" | "array" | "object" => {}
other => {
return Err(format!(
"unsupported property type {other} for {name}; refuse register"
))
}
}
// Reject constructs we do not implement.
for banned in ["$ref", "oneOf", "anyOf", "allOf", "not", "if", "then", "else"] {
if p.contains_key(banned) {
return Err(format!(
"unsupported schema keyword {banned} on {name}; refuse register"
));
}
}
}
}
for banned in ["$ref", "oneOf", "anyOf", "allOf", "not", "if", "then", "else"] {
if obj.contains_key(banned) {
return Err(format!(
"unsupported schema keyword {banned}; refuse register"
));
}
}
Ok(())
}
fn normalize_spec(mut spec: Value) -> Result<Value, String> {
let obj = spec
.as_object_mut()
.ok_or_else(|| "spec must be object".to_string())?;
obj.insert("schema".into(), json!("ToolSpecV1"));
obj.entry("schema_version".to_string())
.or_insert(json!(1));
let id = obj
.get("id")
.and_then(|v| v.as_str())
.filter(|s| !s.is_empty())
.ok_or_else(|| "ToolSpecV1 requires id".to_string())?
.to_string();
obj.entry("version".to_string()).or_insert(json!("1"));
obj.entry("description".to_string())
.or_insert(json!(""));
let input = obj
.get("input_schema")
.cloned()
.unwrap_or_else(|| json!({"type": "object", "properties": {}, "additionalProperties": false}));
validate_schema_subset(&input)?;
obj.insert("input_schema".into(), input);
obj.entry("effect".to_string()).or_insert(json!("read"));
let effect = obj.get("effect").and_then(|v| v.as_str()).unwrap_or("read");
if !matches!(effect, "read" | "write" | "execute" | "external_write") {
return Err(format!("invalid effect={effect}"));
}
obj.entry("scopes".to_string()).or_insert(json!([]));
obj.entry("timeout_ms".to_string()).or_insert(json!(10_000));
obj.entry("max_result_bytes".to_string())
.or_insert(json!(65_536));
obj.entry("idempotency".to_string())
.or_insert(json!("safe"));
obj.entry("availability".to_string())
.or_insert(json!("ready"));
let _ = id;
Ok(spec)
}
fn validate_args_against_schema(schema: &Value, arguments: &Value) -> Result<(), String> {
let args = arguments
.as_object()
.ok_or_else(|| "arguments must be object".to_string())?;
let sch = schema.as_object().ok_or_else(|| "input_schema invalid".to_string())?;
let props = sch
.get("properties")
.and_then(|v| v.as_object())
.cloned()
.unwrap_or_default();
let additional = sch
.get("additionalProperties")
.and_then(|v| v.as_bool())
.unwrap_or(true);
if !additional {
for key in args.keys() {
if !props.contains_key(key) {
return Err(format!("unknown argument `{key}`"));
}
}
}
if let Some(req) = sch.get("required").and_then(|v| v.as_array()) {
for r in req {
let name = r.as_str().unwrap_or("");
if name.is_empty() {
continue;
}
if !args.contains_key(name) || args.get(name).map(|v| v.is_null()).unwrap_or(true) {
return Err(format!("missing required argument `{name}`"));
}
}
}
for (key, val) in args {
if let Some(prop) = props.get(key) {
if let Some(pty) = prop.get("type").and_then(|v| v.as_str()) {
let ok = match pty {
"string" => val.is_string(),
"integer" => val.as_i64().is_some() || val.as_u64().is_some(),
"number" => val.as_f64().is_some(),
"boolean" => val.is_boolean(),
"array" => val.is_array(),
"object" => val.is_object(),
_ => true,
};
if !ok {
return Err(format!("argument `{key}` type mismatch (want {pty})"));
}
}
if let Some(min) = prop.get("minimum").and_then(|v| v.as_f64()) {
if let Some(n) = val.as_f64() {
if n < min {
return Err(format!("argument `{key}` below minimum {min}"));
}
}
}
if let Some(max) = prop.get("maximum").and_then(|v| v.as_f64()) {
if let Some(n) = val.as_f64() {
if n > max {
return Err(format!("argument `{key}` above maximum {max}"));
}
}
}
}
}
Ok(())
}
fn authorized(allowlist: Option<&Value>, tool_id: &str) -> bool {
match allowlist {
None => true, // registry-only call sites may omit; still need registered spec
Some(tools) => crate::tool_names(tools).iter().any(|n| n == tool_id),
}
}
/// Register one ToolSpecV1 (or list). Host/trusted only — model cannot invent principal/root.
pub fn tools_register(args: &Value) -> Result<Value, String> {
let specs = if let Some(arr) = args.get("specs").and_then(|v| v.as_array()) {
arr.clone()
} else if args.get("spec").is_some() || args.get("id").is_some() {
let raw = args.get("spec").cloned().unwrap_or_else(|| args.clone());
vec![raw]
} else {
return Err("tools.register requires spec or specs[]".into());
};
let mut registered = Vec::new();
let mut guard = registry()
.lock()
.map_err(|_| "tools registry lock poisoned".to_string())?;
for raw in specs {
let spec = normalize_spec(raw)?;
let id = spec
.get("id")
.and_then(|v| v.as_str())
.unwrap()
.to_string();
guard.insert(id.clone(), spec);
registered.push(id);
}
Ok(json!({
"ok": true,
"registered": registered,
"count": registered.len(),
}))
}
pub fn tools_clear(args: &Value) -> Result<Value, String> {
let _ = args;
let mut guard = registry()
.lock()
.map_err(|_| "tools registry lock poisoned".to_string())?;
let n = guard.len();
guard.clear();
Ok(json!({"ok": true, "cleared": n}))
}
pub fn tools_search(args: &Value) -> Result<Value, String> {
let query = opt_text(args, "query").unwrap_or("").to_ascii_lowercase();
let allow = args.get("tools");
let guard = registry()
.lock()
.map_err(|_| "tools registry lock poisoned".to_string())?;
let mut items = Vec::new();
for (id, spec) in guard.iter() {
let avail = spec
.get("availability")
.and_then(|v| v.as_str())
.unwrap_or("ready");
let auth = authorized(allow, id);
if !auth {
// Do not leak unauthorized private connector names in search hits.
continue;
}
if !query.is_empty() {
let desc = spec
.get("description")
.and_then(|v| v.as_str())
.unwrap_or("");
if !id.to_ascii_lowercase().contains(&query)
&& !desc.to_ascii_lowercase().contains(&query)
{
continue;
}
}
items.push(json!({
"id": id,
"version": spec.get("version").cloned().unwrap_or(json!("1")),
"description": spec.get("description").cloned().unwrap_or(json!("")),
"effect": spec.get("effect").cloned().unwrap_or(json!("read")),
"availability": avail,
"authorized": true,
}));
}
items.sort_by(|a, b| {
let ai = a.get("id").and_then(|v| v.as_str()).unwrap_or("");
let bi = b.get("id").and_then(|v| v.as_str()).unwrap_or("");
ai.cmp(bi)
});
Ok(json!({
"ok": true,
"schema": "ToolSearchResultV1",
"schema_version": 1,
"items": items,
"count": items.len(),
}))
}
pub fn tools_describe(args: &Value) -> Result<Value, String> {
let id = arg_text(args, "id")?;
let allow = args.get("tools");
if !authorized(allow, id) {
return Ok(json!({
"ok": false,
"found": false,
"authorized": false,
"error": {
"schema": "AgentErrorV1",
"schema_version": 1,
"code": "tool.forbidden",
"category": "forbidden",
"stage": "tool",
"message": format!("tool `{id}` not in allowlist"),
"retryable": false,
"effect_state": "none",
"recovery_action": "needs_input",
}
}));
}
let guard = registry()
.lock()
.map_err(|_| "tools registry lock poisoned".to_string())?;
match guard.get(id) {
Some(spec) => Ok(json!({
"ok": true,
"found": true,
"authorized": true,
"spec": spec,
})),
None => Ok(json!({
"ok": false,
"found": false,
"authorized": true,
"error": {
"schema": "AgentErrorV1",
"schema_version": 1,
"code": "tool.not_found",
"category": "capability_unavailable",
"stage": "tool",
"message": format!("tool `{id}` not registered"),
"retryable": false,
"effect_state": "none",
"recovery_action": "stop",
}
})),
}
}
/// Validate + authorize a ToolCallV1. Does not execute side effects.
pub fn tools_prepare_call(args: &Value) -> Result<Value, String> {
let tool_id = arg_text(args, "tool_id")
.or_else(|_| arg_text(args, "id"))
.or_else(|_| arg_text(args, "name"))?;
let allow = args.get("tools");
if !authorized(allow, tool_id) {
return Ok(tool_result_err(
"tool.forbidden",
"forbidden",
format!("unauthorized call to `{tool_id}`"),
false,
));
}
let guard = registry()
.lock()
.map_err(|_| "tools registry lock poisoned".to_string())?;
let spec = match guard.get(tool_id) {
Some(s) => s.clone(),
None => {
return Ok(tool_result_err(
"tool.not_found",
"capability_unavailable",
format!("tool `{tool_id}` not registered"),
false,
));
}
};
drop(guard);
let avail = spec
.get("availability")
.and_then(|v| v.as_str())
.unwrap_or("ready");
if avail != "ready" {
return Ok(tool_result_err(
"tool.unavailable",
"capability_unavailable",
format!("tool `{tool_id}` availability={avail}"),
false,
));
}
let arguments = match args.get("arguments") {
None | Some(Value::Null) => json!({}),
Some(v) => v.clone(),
};
let schema = spec
.get("input_schema")
.cloned()
.unwrap_or_else(|| json!({"type":"object"}));
if let Err(e) = validate_args_against_schema(&schema, &arguments) {
return Ok(tool_result_err(
"tool.invalid_arguments",
"invalid_arguments",
e,
true,
));
}
let call_id = opt_text(args, "call_id")
.map(|s| s.to_string())
.unwrap_or_else(|| format!("call_{}", std::process::id()));
let operation_id = opt_text(args, "operation_id")
.map(|s| s.to_string())
.unwrap_or_else(|| format!("op_{tool_id}_{call_id}"));
let version = spec
.get("version")
.and_then(|v| v.as_str())
.unwrap_or("1");
let effect = spec
.get("effect")
.and_then(|v| v.as_str())
.unwrap_or("read");
let digest = args_digest(&arguments);
let logical_run = opt_text(args, "logical_run_id").unwrap_or("-");
let step = opt_text(args, "step_id").unwrap_or("-");
let idempotency_key = opt_text(args, "idempotency_key")
.map(|s| s.to_string())
.unwrap_or_else(|| format!("{logical_run}|{step}|{tool_id}|{digest}"));
let needs_ledger = matches!(effect, "write" | "execute" | "external_write");
let call = json!({
"schema": "ToolCallV1",
"schema_version": 1,
"call_id": call_id,
"tool_id": tool_id,
"tool_version": version,
"arguments": arguments,
"operation_id": operation_id,
"parent_span_id": args.get("parent_span_id").cloned().unwrap_or(Value::Null),
});
Ok(json!({
"ok": true,
"status": "prepared",
"call": call,
"spec": {
"id": tool_id,
"effect": effect,
"timeout_ms": spec.get("timeout_ms").cloned().unwrap_or(json!(10000)),
"max_result_bytes": spec.get("max_result_bytes").cloned().unwrap_or(json!(65536)),
},
"args_digest": digest,
"idempotency_key": idempotency_key,
"needs_ledger": needs_ledger,
"summary": format!("prepared authorized call to `{tool_id}`"),
}))
}
/// Stable digest of tool arguments for effect ledger idempotency (M-A5a).
pub fn tools_args_digest(args: &Value) -> Result<Value, String> {
let arguments = args
.get("arguments")
.cloned()
.or_else(|| args.get("value").cloned())
.unwrap_or_else(|| json!({}));
Ok(json!({
"ok": true,
"args_digest": args_digest(&arguments),
}))
}
fn args_digest(arguments: &Value) -> String {
let text = serde_json::to_string(arguments).unwrap_or_else(|_| "{}".into());
format!("sha256-lite:{:x}", fnv1a64(&text))
}
fn fnv1a64(s: &str) -> u64 {
let mut h: u64 = 0xcbf29ce484222325;
for b in s.as_bytes() {
h ^= u64::from(*b);
h = h.wrapping_mul(0x100000001b3);
}
h
}
/// True when effect_class requires EffectLedger before/after execution.
pub fn tools_needs_ledger(args: &Value) -> Result<Value, String> {
let effect = opt_text(args, "effect")
.or_else(|| opt_text(args, "effect_class"))
.unwrap_or("read");
Ok(json!({
"ok": true,
"needs_ledger": matches!(effect, "write" | "execute" | "external_write"),
"effect": effect,
}))
}
/// Wrap a successful / failed tool execution into ToolResultV1.
pub fn tools_wrap_result(args: &Value) -> Result<Value, String> {
let ok = args.get("ok").and_then(|v| v.as_bool()).unwrap_or(false);
let status = opt_text(args, "status").unwrap_or(if ok { "succeeded" } else { "failed" });
let summary = opt_text(args, "summary").unwrap_or("");
let mut out = json!({
"schema": "ToolResultV1",
"schema_version": 1,
"ok": ok,
"status": status,
"summary": summary,
"structured_content": args.get("structured_content").cloned().unwrap_or(Value::Null),
"resources": args.get("resources").cloned().unwrap_or_else(|| json!([])),
"citations": args.get("citations").cloned().unwrap_or_else(|| json!([])),
"error": args.get("error").cloned().unwrap_or(Value::Null),
"usage": args.get("usage").cloned().unwrap_or(Value::Null),
"truncated": args.get("truncated").and_then(|v| v.as_bool()).unwrap_or(false),
"next_cursor": args.get("next_cursor").cloned().unwrap_or(Value::Null),
"effect_receipt_ref": args.get("effect_receipt_ref").cloned().unwrap_or(Value::Null),
});
// Truncate oversized summary into artifact hint (do not dump MB into prompt).
let max_bytes = args
.get("max_result_bytes")
.and_then(|v| v.as_u64())
.unwrap_or(65_536) as usize;
if summary.len() > max_bytes {
if let Some(obj) = out.as_object_mut() {
obj.insert("truncated".into(), json!(true));
obj.insert(
"summary".into(),
json!(format!(
"{}… [truncated; use resource handle]",
&summary[..max_bytes.min(summary.len())]
)),
);
}
}
Ok(out)
}
/// Seed the five engineering tools used by qdagent (aliases remain CALL:tool_*).
pub fn tools_register_eng_defaults(args: &Value) -> Result<Value, String> {
let _ = args;
let specs = eng_default_specs();
tools_register(&json!({"specs": specs}))
}
fn eng_default_specs() -> Vec<Value> {
vec![
json!({
"id": "tool_find",
"version": "1",
"description": "Engineering find via EKC (read-only)",
"input_schema": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
"additionalProperties": false
},
"effect": "read",
"scopes": ["knowledge:read"],
"availability": "ready"
}),
json!({
"id": "tool_reuse",
"version": "1",
"description": "Engineering reuse / preflight discovery (read-only)",
"input_schema": {
"type": "object",
"properties": {"task": {"type": "string"}},
"required": ["task"],
"additionalProperties": false
},
"effect": "read",
"scopes": ["knowledge:read"],
"availability": "ready"
}),
json!({
"id": "tool_bind",
"version": "1",
"description": "Bind and execute a verified knowledge artifact",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string"},
"policy": {"type": "string"},
"project": {"type": "string"}
},
"required": ["query"],
"additionalProperties": false
},
"effect": "execute",
"scopes": ["knowledge:execute"],
"availability": "ready"
}),
json!({
"id": "tool_verify",
"version": "1",
"description": "Run L3 knowledge verification checks",
"input_schema": {
"type": "object",
"properties": {},
"additionalProperties": false
},
"effect": "read",
"scopes": ["knowledge:verify"],
"availability": "ready"
}),
json!({
"id": "tool_summarize",
"version": "1",
"description": "Summarize a Context Pack / preflight map",
"input_schema": {
"type": "object",
"properties": {"preflight": {"type": "object"}},
"required": ["preflight"],
"additionalProperties": false
},
"effect": "read",
"scopes": ["knowledge:read"],
"availability": "ready"
}),
]
}
fn tool_result_err(code: &str, category: &str, message: String, retryable: bool) -> Value {
let recovery = if category == "invalid_arguments" {
"repair_args"
} else if category == "forbidden" {
"needs_input"
} else {
"stop"
};
json!({
"ok": false,
"status": "failed",
"summary": message,
"schema": "ToolResultV1",
"schema_version": 1,
"structured_content": null,
"resources": [],
"citations": [],
"error": {
"schema": "AgentErrorV1",
"schema_version": 1,
"code": code,
"category": category,
"stage": "tool",
"message": message,
"retryable": retryable,
"retry_after_ms": null,
"effect_state": "none",
"recovery_action": recovery,
},
"usage": null,
"truncated": false,
"next_cursor": null,
"effect_receipt_ref": null,
})
}
/// Seed stub specs from a CALL allowlist (args.tools).
pub fn seed_from_allowlist_args(args: &Value) -> Result<Value, String> {
let tools = args
.get("tools")
.ok_or_else(|| "tools.seed_allowlist requires tools".to_string())?;
seed_from_allowlist(tools)
}
fn seed_from_allowlist(tools: &Value) -> Result<Value, String> {
let names = crate::tool_names(tools);
let mut specs = Vec::new();
for name in names {
// Minimal stub if not already registered — CALL whitelist compatibility.
let already = {
let guard = registry()
.lock()
.map_err(|_| "tools registry lock poisoned".to_string())?;
guard.contains_key(&name)
};
if already {
continue;
}
let mut m = Map::new();
m.insert("id".into(), json!(name));
m.insert("version".into(), json!("1"));
m.insert(
"description".into(),
json!(format!("Allowlist-derived tool `{name}`")),
);
m.insert(
"input_schema".into(),
json!({"type":"object","properties":{},"additionalProperties":true}),
);
m.insert("effect".into(), json!("execute"));
m.insert("scopes".into(), json!(["call:allowlist"]));
m.insert("availability".into(), json!("ready"));
specs.push(Value::Object(m));
}
if specs.is_empty() {
return Ok(json!({"ok": true, "registered": [], "count": 0}));
}
tools_register(&json!({"specs": specs}))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn register_search_describe_and_forbid() {
let _ = tools_clear(&json!({}));
let reg = tools_register_eng_defaults(&json!({})).unwrap();
assert_eq!(reg["count"], 5);
let allow = json!(["tool_find", "tool_reuse"]);
let search = tools_search(&json!({"tools": allow, "query": "find"})).unwrap();
assert_eq!(search["count"], 1);
assert_eq!(search["items"][0]["id"], "tool_find");
// Unauthorized tool must not appear.
let search2 = tools_search(&json!({"tools": allow, "query": "bind"})).unwrap();
assert_eq!(search2["count"], 0);
let denied = tools_describe(&json!({"id": "tool_bind", "tools": allow})).unwrap();
assert_eq!(denied["authorized"], false);
assert_eq!(denied["ok"], false);
let ok = tools_describe(&json!({"id": "tool_find", "tools": allow})).unwrap();
assert_eq!(ok["found"], true);
assert_eq!(ok["spec"]["schema"], "ToolSpecV1");
}
#[test]
fn prepare_rejects_bad_args_and_unauthorized() {
let _ = tools_clear(&json!({}));
tools_register_eng_defaults(&json!({})).unwrap();
let allow = json!(["tool_find"]);
let bad = tools_prepare_call(&json!({
"tool_id": "tool_find",
"tools": allow,
"arguments": {}
}))
.unwrap();
assert_eq!(bad["ok"], false);
assert_eq!(bad["error"]["category"], "invalid_arguments");
let unauth = tools_prepare_call(&json!({
"tool_id": "tool_bind",
"tools": allow,
"arguments": {"query": "x"}
}))
.unwrap();
assert_eq!(unauth["ok"], false);
assert_eq!(unauth["error"]["category"], "forbidden");
let good = tools_prepare_call(&json!({
"tool_id": "tool_find",
"tools": allow,
"arguments": {"query": "foo"},
"call_id": "c1"
}))
.unwrap();
assert_eq!(good["ok"], true);
assert_eq!(good["call"]["schema"], "ToolCallV1");
assert_eq!(good["call"]["tool_id"], "tool_find");
assert_eq!(good["needs_ledger"], false);
assert!(good["args_digest"].as_str().unwrap().starts_with("sha256-lite:"));
let allow2 = json!(["tool_bind"]);
let bind = tools_prepare_call(&json!({
"tool_id": "tool_bind",
"tools": allow2,
"arguments": {"query": "x"},
"call_id": "c2",
"logical_run_id": "run1",
"step_id": "s1"
}))
.unwrap();
assert_eq!(bind["ok"], true);
assert_eq!(bind["needs_ledger"], true);
assert_eq!(bind["spec"]["effect"], "execute");
assert!(bind["idempotency_key"]
.as_str()
.unwrap()
.starts_with("run1|s1|tool_bind|"));
}
#[test]
fn needs_ledger_only_for_mutating_effects() {
assert_eq!(
tools_needs_ledger(&json!({"effect": "read"})).unwrap()["needs_ledger"],
false
);
assert_eq!(
tools_needs_ledger(&json!({"effect": "write"})).unwrap()["needs_ledger"],
true
);
assert_eq!(
tools_needs_ledger(&json!({"effect": "execute"})).unwrap()["needs_ledger"],
true
);
}
#[test]
fn refuse_unsupported_schema_keywords() {
let err = tools_register(&json!({
"id": "bad",
"input_schema": {
"type": "object",
"oneOf": [{"type": "object"}]
}
}));
assert!(err.is_err());
}
}
+111 -31
View File
@@ -38,6 +38,7 @@ type invokeRoute struct {
BodyMode string
ReturnMode string
Class string
Path string
}
func parseInvokeRoute(v any) invokeRoute {
@@ -66,6 +67,7 @@ func (st *state) mountInvokeRoutes(mux *http.ServeMux) {
for _, key := range sortedKeys(st.invokeRoutes) {
cfg := parseInvokeRoute(st.invokeRoutes[key])
path := routePathKey(key)
cfg.Path = path
method := cfg.Method
if method == "" {
method = http.MethodPost
@@ -140,6 +142,25 @@ func (st *state) handleInvoke(w http.ResponseWriter, r *http.Request, route invo
payload["api_key"] = key
}
}
if last := strings.TrimSpace(r.Header.Get("Last-Event-ID")); last != "" {
if _, exists := payload["last_event_id"]; !exists {
payload["last_event_id"] = last
}
}
// Merge Go ServeMux path wildcards (e.g. /turns/{id}/events → id / turn_id).
if route.Path != "" {
pathVals := pathValuesOf(r, route.Path)
for k, v := range pathVals {
if _, exists := payload[k]; !exists {
payload[k] = v
}
}
if id, ok := pathVals["id"]; ok {
if _, exists := payload["turn_id"]; !exists {
payload["turn_id"] = id
}
}
}
args := invokeArgsFromPayload(payload)
@@ -151,9 +172,14 @@ func (st *state) handleInvoke(w http.ResponseWriter, r *http.Request, route invo
class := resolveInvokeClass(route, liveSSE)
switch class {
case "execute":
st.handleInvokeIsolated(w, r, route, args, liveSSE)
// Isolated workers: do not take parent INVOKE_LOCK (ADR 0009).
st.handleInvokeIsolated(w, r, route, args, liveSSE, class)
return
case "short", "read", "control":
// Stay on parent: execute already runs off-process, so parent lock is free.
// Putting short/read/control on the 2-slot execute worker pool caused
// systemic no_slot (and zombies held slots after observer disconnect).
// Product cancel/events prefer /_runtime/* (lock-free).
st.handleInvokeParent(w, r, route, args)
return
default:
@@ -243,14 +269,17 @@ func (st *state) handleInvokeParent(w http.ResponseWriter, r *http.Request, rout
}
}
// handleInvokeIsolated runs execute-class invokes on a Supervisor worker (no
// parent CallLibPath, no process Setenv, no legacySSEBridgeMu).
func (st *state) handleInvokeIsolated(w http.ResponseWriter, r *http.Request, route invokeRoute, args map[string]any, liveSSE bool) {
// handleInvokeIsolated runs admits on a Supervisor worker (no parent
// CallLibPath / Setenv / legacySSEBridgeMu). admissionClass is execute|short|read|control.
func (st *state) handleInvokeIsolated(w http.ResponseWriter, r *http.Request, route invokeRoute, args map[string]any, liveSSE bool, admissionClass string) {
if admissionClass == "" {
admissionClass = "execute"
}
taskID := fmt.Sprintf("exec_%d", time.Now().UnixNano())
adm, err := runtimeQuery("admit", map[string]any{
"task_id": taskID,
"idempotency_key": taskID,
"class": "execute",
"class": admissionClass,
"payload": map[string]any{"fn": route.FnPath},
})
if err != nil {
@@ -324,6 +353,14 @@ func (st *state) handleInvokeIsolated(w http.ResponseWriter, r *http.Request, ro
st.waitIsolatedJSON(w, r, route, taskID, eventPath, cancelTok, emitResult)
}
// cancelOnDisconnect reports whether the client opted into legacy
// disconnect=cancel (header X-Marqdo-Cancel-On-Disconnect: 1|true).
// Default is false: subscription close must not cancel the task (ADR 0009 / design §7.2).
func cancelOnDisconnect(r *http.Request) bool {
v := strings.TrimSpace(strings.ToLower(r.Header.Get("X-Marqdo-Cancel-On-Disconnect")))
return v == "1" || v == "true" || v == "yes"
}
func (st *state) streamIsolatedSSE(w http.ResponseWriter, r *http.Request, route invokeRoute, taskID, eventPath, cancelTok, emitResult string) {
w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
w.Header().Set("Cache-Control", "no-cache")
@@ -384,27 +421,46 @@ func (st *state) streamIsolatedSSE(w http.ResponseWriter, r *http.Request, route
}
}
doCancelOnDisconnect := cancelOnDisconnect(r)
for {
select {
case <-ctx.Done():
_, _ = runtimeQuery("cancel", map[string]any{"task_id": taskID})
_ = writeCancelToken(cancelTok)
writeEvent(map[string]any{
"schema": "RuntimeEventV1", "schema_version": 1, "type": "run.interrupted",
"payload": map[string]any{
"reason": "client_disconnect",
"cancel_propagated": cancelTok != "",
"status": "stopping",
"task_id": taskID,
},
})
// Brief wait so worker can notice cancel and flush.
deadline := time.Now().Add(3 * time.Second)
for time.Now().Before(deadline) {
if workerDone(taskID, emitResult) {
break
// Default: observer gone ≠ cancel. Task keeps running; client may
// reattach via GET /_runtime/tasks/{id}/events (Last-Event-ID).
if doCancelOnDisconnect {
_, _ = runtimeQuery("cancel", map[string]any{"task_id": taskID})
_ = writeCancelToken(cancelTok)
writeEvent(map[string]any{
"schema": "RuntimeEventV1", "schema_version": 1, "type": "run.interrupted",
"payload": map[string]any{
"reason": "client_disconnect",
"cancel_propagated": cancelTok != "",
"status": "stopping",
"task_id": taskID,
},
})
deadline := time.Now().Add(3 * time.Second)
for time.Now().Before(deadline) {
if workerDone(taskID, emitResult) {
break
}
time.Sleep(50 * time.Millisecond)
}
time.Sleep(50 * time.Millisecond)
} else {
writeEvent(map[string]any{
"schema": "RuntimeEventV1", "schema_version": 1, "type": "run.interrupted",
"payload": map[string]any{
"reason": "client_disconnect",
"cancel_propagated": false,
"status": "observer_closed",
"task_id": taskID,
"resume": "/_runtime/tasks/" + taskID + "/events",
},
})
// Observer gone ≠ cancel, but still reap when the worker exits so
// execute slots are not held forever by zombies.
go reapIsolatedTask(taskID, emitResult, 10*time.Minute)
}
finish(true)
return
@@ -476,23 +532,47 @@ func (st *state) waitIsolatedJSON(w http.ResponseWriter, r *http.Request, route
}
}
func workerDone(taskID, emitResult string) bool {
if emitResult != "" {
if st, err := os.Stat(emitResult); err == nil && st.Size() > 0 {
return true
// reapIsolatedTask polls runtime get until the worker exits (or timeout),
// so supervisor/scheduler slots are released after observer disconnect.
func reapIsolatedTask(taskID, emitResult string, budget time.Duration) {
deadline := time.Now().Add(budget)
for time.Now().Before(deadline) {
if workerDone(taskID, emitResult) {
return
}
time.Sleep(200 * time.Millisecond)
}
// Sibling of event file written by Supervisor even if emit_result was omitted.
if taskID != "" {
// Last-chance cancel so slots can free.
_, _ = runtimeQuery("cancel", map[string]any{"task_id": taskID})
for i := 0; i < 25; i++ {
if workerDone(taskID, emitResult) {
return
}
time.Sleep(200 * time.Millisecond)
}
}
func workerDone(taskID, emitResult string) bool {
// Always runtime.get when probing completion: get runs try_reap and
// releases execute slots. Do not return early on emit_result alone —
// that left zombie workers holding both pool slots (no_slot).
if taskID == "" {
return false
}
g, err := runtimeQuery("get", map[string]any{"task_id": taskID})
if err != nil {
// Fallback: result file present (get may fail during early boot).
if emitResult != "" {
if st, err := os.Stat(emitResult); err == nil && st.Size() > 0 {
return true
}
}
if dir := os.Getenv("MARQDO_RUNTIME_DIR"); dir != "" {
p := filepath.Join(dir, "events", taskID+".result.json")
if st, err := os.Stat(p); err == nil && st.Size() > 0 {
return true
}
}
}
g, err := runtimeQuery("get", map[string]any{"task_id": taskID})
if err != nil {
return false
}
if _, ok := g["exit_code"]; ok {
@@ -45,7 +45,8 @@ func TestLegacySSEBridgeSingleFlight(t *testing.T) {
}
}
// M-R0: disconnect marks cancel; token file must not be deleted while holder waits.
// M-R0: cancel-token file must not be deleted while bridge holder waits.
// (sse-live observer disconnect no longer cancels by default — see cancelOnDisconnect.)
func TestCancelTokenSurvivesUntilHolderExits(t *testing.T) {
dir := t.TempDir()
tok := filepath.Join(dir, "cancel.tok")
+15 -6
View File
@@ -27,6 +27,13 @@ need curl curl
need tar tar
need xz xz-utils
# /tmp is often a small tmpfs; vendor + Rust extract exceed quota. Prefer disk.
if [ -z "${TMPDIR:-}" ] || [ "$TMPDIR" = /tmp ] || [ "$TMPDIR" = /var/tmp ]; then
TMPDIR="${HOME}/.cache/marqdo-ppa/work"
fi
mkdir -p "$TMPDIR"
export TMPDIR
VER="$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -1)"
# Debian revision comes from debian/changelog (e.g. 1.0.2-1ppa2); we append ~series.
CHG_VER="$(dpkg-parsechangelog -l debian/changelog -S Version)"
@@ -43,7 +50,7 @@ if [[ "$BASE_DEB_VER" != "$VER"-* ]]; then
fi
fi
DEB_VER="${BASE_DEB_VER}~${SERIES}"
PKG_ROOT="${TMPDIR:-/tmp}/marqdo-ppa/${VER}"
PKG_ROOT="${TMPDIR}/marqdo-ppa/${VER}"
BUILD_AREA="${ROOT}/../build-area"
GPG_KEY="${MARQDO_PPA_GPG_KEY:-505943294D04C803}"
RUST_VER="${MARQDO_PPA_RUST_VERSION:-1.85.0}"
@@ -212,18 +219,20 @@ PY
exit 1
fi
# Launchpad builds need only rustc + cargo + rust-std (debian/rules PATH).
# Skip docs/json-docs/rustfmt/rls — ~1G of dead weight in the orig tarball.
# install.sh's --without is a *single* comma-separated valopt; repeating
# --without=… keeps only the last flag, so rust-docs still installed and
# blew /tmp quota. Prefer explicit --components= instead.
bash "$INSTALL_SH" \
--prefix="$PKG_ROOT/third_party/rust" \
--without=rust-docs \
--without=rust-docs-json-preview \
--without=rustfmt-preview \
--without=rls-preview \
--components="rustc,cargo,rust-std-${RUST_TRIPLE}" \
--disable-ldconfig
# Belt: docs must never ship in .orig (even if component list drifts).
rm -rf "$PKG_ROOT/third_party/rust/share/doc"
rm -rf "$RUST_EXTRACT"
trap - EXIT
"$PKG_ROOT/third_party/rust/bin/rustc" --version
"$PKG_ROOT/third_party/rust/bin/cargo" --version
du -sh "$PKG_ROOT/third_party/rust"
cd "$(dirname "$PKG_ROOT")"
echo "==> packing ${ORIG_NAME} (vendor + third_party/rust)"
+38 -34
View File
@@ -114,7 +114,23 @@ pub fn ekc_graph_dir(out_dir: &Path) -> std::path::PathBuf {
out_dir.join("ekc").join("graph")
}
/// Path of the full IR snapshot used by warm query paths (preflight/find/reuse).
pub fn ir_snapshot_path(out_dir: &Path) -> std::path::PathBuf {
ekc_graph_dir(out_dir).join("ir.json")
}
/// Load a previously compiled KnowledgeGraph without re-extracting sources.
/// Prefers `ekc/graph/ir.json`. Does **not** walk the source tree.
pub fn load_graph(out_dir: &Path) -> Result<KnowledgeGraph> {
let ir_path = ir_snapshot_path(out_dir);
if ir_path.exists() {
let raw = fs::read_to_string(&ir_path)
.with_context(|| format!("read {}", ir_path.display()))?;
let graph: KnowledgeGraph = serde_json::from_str(&raw)
.with_context(|| format!("parse {}", ir_path.display()))?;
return Ok(graph);
}
let graph_path = ekc_graph_dir(out_dir).join("graph.json");
let edges_path = ekc_graph_dir(out_dir).join("edges.json");
if !graph_path.exists() {
@@ -123,47 +139,19 @@ pub fn load_graph(out_dir: &Path) -> Result<KnowledgeGraph> {
graph_path.display()
);
}
// Prefer re-extract for freshness when source path known; for query commands
// we rebuild from JSON snapshot fields + re-scan if catalog sibling exists.
// Snapshot load: reconstruct minimal IR from written pages + edges.json.
// Legacy projections without ir.json: edges-only fallback (no source walk).
let edges_raw = fs::read_to_string(&edges_path).unwrap_or_else(|_| "{\"edges\":[]}".into());
let edges_v: serde_json::Value = serde_json::from_str(&edges_raw)?;
let graph_raw = fs::read_to_string(&graph_path)?;
let graph_v: serde_json::Value = serde_json::from_str(&graph_raw)?;
// Re-compile from recorded root if present in graph.json
if let Some(root) = graph_v
.pointer("/repository/root")
.and_then(|v| v.as_str())
{
let root_path = Path::new(root);
if root_path.exists() {
return extract_graph(&ExtractOptions {
path: root_path.to_path_buf(),
out_dir: out_dir.to_path_buf(),
});
}
}
// Fallback: empty-ish graph with edges only
let mut edges = Vec::new();
if let Some(arr) = edges_v.get("edges").and_then(|e| e.as_array()) {
for e in arr {
let kind = match e.get("kind").and_then(|k| k.as_str()).unwrap_or("") {
"implements" => crate::knowledge::ir::EdgeKind::Implements,
"uses" => crate::knowledge::ir::EdgeKind::Uses,
"depends_on" => crate::knowledge::ir::EdgeKind::DependsOn,
"tested_by" => crate::knowledge::ir::EdgeKind::TestedBy,
"documented_by" => crate::knowledge::ir::EdgeKind::DocumentedBy,
"constrained_by" => crate::knowledge::ir::EdgeKind::ConstrainedBy,
"decided_by" => crate::knowledge::ir::EdgeKind::DecidedBy,
"supersedes" => crate::knowledge::ir::EdgeKind::Supersedes,
"conflicts_with" => crate::knowledge::ir::EdgeKind::ConflictsWith,
"deprecated_by" => crate::knowledge::ir::EdgeKind::DeprecatedBy,
"derived_from" => crate::knowledge::ir::EdgeKind::DerivedFrom,
"failed_by" => crate::knowledge::ir::EdgeKind::FailedBy,
_ => crate::knowledge::ir::EdgeKind::RelatedTo,
};
let kind = crate::knowledge::ir::EdgeKind::parse(
e.get("kind").and_then(|k| k.as_str()).unwrap_or(""),
);
edges.push(crate::knowledge::ir::Edge {
from: e.get("from").and_then(|v| v.as_str()).unwrap_or("").into(),
to: e.get("to").and_then(|v| v.as_str()).unwrap_or("").into(),
@@ -204,14 +192,27 @@ pub fn load_graph(out_dir: &Path) -> Result<KnowledgeGraph> {
})
}
/// Force a full knowledge compile (write path / `--refresh`).
pub fn ensure_compiled(path: &Path, out_dir: &Path) -> Result<KnowledgeGraph> {
// Always refresh from source when path is given.
compile(KnowledgeOptions {
path: path.to_path_buf(),
out_dir: out_dir.to_path_buf(),
})
}
/// Query path loader: compile if missing (or `refresh`), else hot-load `ir.json`.
pub fn graph_for_query(path: &Path, out_dir: &Path, refresh: bool) -> Result<KnowledgeGraph> {
if refresh {
return ensure_compiled(path, out_dir);
}
let has_ir = ir_snapshot_path(out_dir).exists();
let has_graph = ekc_graph_dir(out_dir).join("graph.json").exists();
if has_ir || has_graph {
return load_graph(out_dir);
}
ensure_compiled(path, out_dir)
}
fn write_projections(out_dir: &Path, graph: &KnowledgeGraph) -> Result<()> {
let dirs = [
"catalog/modules",
@@ -299,6 +300,9 @@ fn write_projections(out_dir: &Path, graph: &KnowledgeGraph) -> Result<()> {
fs::write(ekc.join("graph.json"), graph_json)?;
let edges_json = serde_json::to_string_pretty(&graph.to_edges_json())?;
fs::write(ekc.join("edges.json"), edges_json)?;
// Full IR snapshot for warm query paths (preflight/find/reuse) — no re-extract.
let ir_json = serde_json::to_string(&graph)?;
fs::write(ekc.join("ir.json"), ir_json)?;
// Search index
let index = json!({
+67 -9
View File
@@ -1,5 +1,6 @@
//! Engineering Knowledge IR (L0–L4) — projections of `.mq.md`, not a second source of truth.
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use serde_json::{json, Value};
use std::collections::BTreeMap;
@@ -13,6 +14,19 @@ pub enum Lifecycle {
Superseded,
}
impl Serialize for Lifecycle {
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.serialize_str(self.as_str())
}
}
impl<'de> Deserialize<'de> for Lifecycle {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let s = String::deserialize(deserializer)?;
Ok(Self::parse(&s))
}
}
impl Lifecycle {
pub fn as_str(&self) -> &'static str {
match self {
@@ -35,7 +49,7 @@ impl Lifecycle {
}
}
#[derive(Debug, Clone, Default)]
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct Evidence {
pub sources: Vec<String>,
pub tests: Vec<String>,
@@ -55,7 +69,7 @@ impl Evidence {
}
/// Graded confidence with explanation (not a bare float).
#[derive(Debug, Clone)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Confidence {
pub level: String, // high | medium | low
pub implementation: String,
@@ -87,7 +101,7 @@ impl Confidence {
}
}
#[derive(Debug, Clone)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RepositoryInfo {
pub title: String,
pub root: String,
@@ -98,7 +112,7 @@ pub struct RepositoryInfo {
pub knowledge_count: usize,
}
#[derive(Debug, Clone)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModuleInfo {
pub id: String,
pub resource: String,
@@ -111,7 +125,7 @@ pub struct ModuleInfo {
pub status: Lifecycle,
}
#[derive(Debug, Clone)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SymbolInfo {
pub id: String,
pub name: String,
@@ -135,7 +149,7 @@ pub struct SymbolInfo {
pub confidence: Confidence,
}
#[derive(Debug, Clone)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CapabilityInfo {
pub id: String,
pub name: String,
@@ -215,7 +229,20 @@ impl KnowledgeKind {
}
}
#[derive(Debug, Clone)]
impl Serialize for KnowledgeKind {
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.serialize_str(self.as_str())
}
}
impl<'de> Deserialize<'de> for KnowledgeKind {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let s = String::deserialize(deserializer)?;
Ok(Self::parse(&s))
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct KnowledgeItem {
pub id: String,
pub kind: KnowledgeKind,
@@ -269,9 +296,40 @@ impl EdgeKind {
Self::RelatedTo => "related_to",
}
}
pub fn parse(s: &str) -> Self {
match s.trim() {
"implements" => Self::Implements,
"uses" => Self::Uses,
"depends_on" => Self::DependsOn,
"tested_by" => Self::TestedBy,
"documented_by" => Self::DocumentedBy,
"constrained_by" => Self::ConstrainedBy,
"decided_by" => Self::DecidedBy,
"supersedes" => Self::Supersedes,
"conflicts_with" => Self::ConflictsWith,
"deprecated_by" => Self::DeprecatedBy,
"derived_from" => Self::DerivedFrom,
"failed_by" => Self::FailedBy,
_ => Self::RelatedTo,
}
}
}
#[derive(Debug, Clone)]
impl Serialize for EdgeKind {
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.serialize_str(self.as_str())
}
}
impl<'de> Deserialize<'de> for EdgeKind {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let s = String::deserialize(deserializer)?;
Ok(Self::parse(&s))
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Edge {
pub from: String,
pub to: String,
@@ -336,7 +394,7 @@ pub struct ReuseResult {
pub recommended: Vec<String>,
}
#[derive(Debug, Clone)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct KnowledgeGraph {
pub repository: RepositoryInfo,
pub modules: Vec<ModuleInfo>,
+7 -2
View File
@@ -20,7 +20,10 @@ pub mod preflight;
pub mod reuse;
pub mod util;
pub use compile::{compile, ekc_graph_dir, ensure_compiled, load_graph, KnowledgeOptions};
pub use compile::{
compile, ekc_graph_dir, ensure_compiled, graph_for_query, ir_snapshot_path, load_graph,
KnowledgeOptions,
};
pub use duplicate::{find_duplicates, format_duplicates_text};
pub use find::{find, find_json, format_find_text};
pub use impact::{format_impact_text, impact, impact_json};
@@ -32,7 +35,9 @@ pub use lifecycle::{
};
pub use metrics::{load_metrics, record_decision, save_metrics, ReuseMetrics};
pub use policy::compile_policy;
pub use preflight::{format_preflight_yaml, preflight, preflight_json, PreflightResult};
pub use preflight::{
format_preflight_yaml, preflight, preflight_from_reuse, preflight_json, PreflightResult,
};
pub use reuse::{format_reuse_text, resolve, reuse_json, ReuseBudget};
use std::path::{Path, PathBuf};
+11 -1
View File
@@ -33,6 +33,16 @@ pub fn preflight(
out_dir: Option<&Path>,
) -> Result<PreflightResult> {
let reuse = resolve(graph, task, budget);
preflight_from_reuse(graph, task, &reuse, out_dir)
}
/// Build a Context Pack from an already-resolved reuse result (avoids a second `resolve`).
pub fn preflight_from_reuse(
graph: &KnowledgeGraph,
task: &str,
reuse: &crate::knowledge::ir::ReuseResult,
out_dir: Option<&Path>,
) -> Result<PreflightResult> {
let intent = reuse
.capability
.clone()
@@ -46,7 +56,7 @@ pub fn preflight(
.map(|c| c.title.clone())
.collect();
let pack = render_context_pack(task, &intent, &reuse, graph);
let pack = render_context_pack(task, &intent, reuse, graph);
let mut context_path = None;
if let Some(out) = out_dir {
let contexts = out.join("agent/contexts");
+58 -17
View File
@@ -9,12 +9,12 @@ use marqdo::diagnostics::{Diagnostic, Span};
use marqdo::ext_cli::{add_ext, list_ext, remove_ext};
use marqdo::input_feed::load_stdin_file;
use marqdo::knowledge::{
compile_policy, conflicts_json, ensure_compiled, find, find_conflicts, find_duplicates,
find_json, find_stale, format_conflicts_text, format_duplicates_text, format_find_text,
format_impact_text, format_preflight_yaml, format_reuse_text, format_stale_text,
format_verify_text, impact, impact_json, learn, preflight, preflight_json, record_decision,
resolve, reuse_json, stale_json, verify, verify_json, write_knowledge, KnowledgeOptions,
LearnInput, ReuseBudget,
compile_policy, conflicts_json, find, find_conflicts, find_duplicates, find_json, find_stale,
format_conflicts_text, format_duplicates_text, format_find_text, format_impact_text,
format_preflight_yaml, format_reuse_text, format_stale_text, format_verify_text, graph_for_query,
impact, impact_json, learn, preflight_from_reuse, preflight_json, record_decision, resolve,
reuse_json, stale_json, verify, verify_json, write_knowledge, KnowledgeOptions, LearnInput,
ReuseBudget,
};
use marqdo::view::{
serve, serve_debug, write_capture, write_static, CaptureOptions, DebugOptions, OutputOptions,
@@ -265,6 +265,10 @@ enum Commands {
#[arg(long, global = true)]
json: bool,
/// Force a full knowledge recompile before query actions (preflight, …)
#[arg(long, global = true)]
refresh: bool,
},
/// Find engineering capabilities / symbols / knowledge
Find {
@@ -282,6 +286,10 @@ enum Commands {
#[arg(long)]
json: bool,
/// Force a full knowledge recompile before querying
#[arg(long)]
refresh: bool,
},
/// Engineering First Information: REUSE / ADAPT / CREATE
Reuse {
@@ -306,6 +314,10 @@ enum Commands {
#[arg(long)]
json: bool,
/// Force a full knowledge recompile before querying
#[arg(long)]
refresh: bool,
},
/// Knowledge impact of changed paths
Impact {
@@ -320,6 +332,10 @@ enum Commands {
#[arg(long)]
json: bool,
/// Force a full knowledge recompile before querying
#[arg(long)]
refresh: bool,
},
/// Detect knowledge conflicts / possible duplicates edges
Conflicts {
@@ -335,6 +351,10 @@ enum Commands {
/// Exit non-zero when conflicts found (CI gate; default remains report-only)
#[arg(long)]
fail: bool,
/// Force a full knowledge recompile before querying
#[arg(long)]
refresh: bool,
},
/// List stale / deprecated / superseded knowledge
Stale {
@@ -350,6 +370,10 @@ enum Commands {
/// Exit non-zero when stale items found (CI gate; default remains report-only)
#[arg(long)]
fail: bool,
/// Force a full knowledge recompile before querying
#[arg(long)]
refresh: bool,
},
/// Detect duplicate capabilities via symbol fingerprints
Duplicate {
@@ -368,6 +392,10 @@ enum Commands {
#[arg(long)]
json: bool,
/// Force a full knowledge recompile before querying
#[arg(long)]
refresh: bool,
},
/// Verify code ↔ knowledge consistency (EKC structural; exit 1 only on errors)
Verify {
@@ -383,6 +411,10 @@ enum Commands {
/// Also fail on warnings (does not change default success-when-no-errors)
#[arg(long)]
fail_on_warning: bool,
/// Force a full knowledge recompile before querying
#[arg(long)]
refresh: bool,
},
/// Official extension installer (`list` / `add` / `remove`)
Ext {
@@ -1235,6 +1267,7 @@ fn try_main(cli: Cli) -> Result<i32> {
path,
out,
json,
refresh,
} => {
let path = path.unwrap_or_else(|| PathBuf::from("."));
match action.unwrap_or(KnowledgeAction::Compile) {
@@ -1479,14 +1512,15 @@ fn try_main(cli: Cli) -> Result<i32> {
min_candidates,
allow_create_after,
} => {
let graph = ensure_compiled(&path, &out)?;
let graph = graph_for_query(&path, &out, refresh)?;
let budget = ReuseBudget {
min_candidates,
allow_create_after,
..ReuseBudget::default()
};
let pf = preflight(&graph, &task, &budget, Some(&out))?;
let _ = compile_policy(&out, &task, &resolve(&graph, &task, &budget));
let reuse = resolve(&graph, &task, &budget);
let pf = preflight_from_reuse(&graph, &task, &reuse, Some(&out))?;
let _ = compile_policy(&out, &task, &reuse);
if json {
println!("{}", preflight_json(&pf));
} else {
@@ -1554,9 +1588,10 @@ fn try_main(cli: Cli) -> Result<i32> {
out,
limit,
json,
refresh,
} => {
let path = path.unwrap_or_else(|| PathBuf::from("."));
let graph = ensure_compiled(&path, &out)?;
let graph = graph_for_query(&path, &out, refresh)?;
let hits = find(&graph, &query, limit);
if json {
println!("{}", find_json(&query, &hits));
@@ -1573,9 +1608,10 @@ fn try_main(cli: Cli) -> Result<i32> {
min_candidates,
allow_create_after,
json,
refresh,
} => {
let path = path.unwrap_or_else(|| PathBuf::from("."));
let graph = ensure_compiled(&path, &out)?;
let graph = graph_for_query(&path, &out, refresh)?;
let budget = ReuseBudget {
min_candidates,
allow_create_after,
@@ -1584,7 +1620,7 @@ fn try_main(cli: Cli) -> Result<i32> {
let result = resolve(&graph, &task, &budget);
let _ = compile_policy(&out, &task, &result);
if do_preflight {
let _ = preflight(&graph, &task, &budget, Some(&out))?;
let _ = preflight_from_reuse(&graph, &task, &result, Some(&out))?;
}
if json {
println!("{}", reuse_json(&task, &result));
@@ -1598,8 +1634,9 @@ fn try_main(cli: Cli) -> Result<i32> {
root,
out,
json,
refresh,
} => {
let graph = ensure_compiled(&root, &out)?;
let graph = graph_for_query(&root, &out, refresh)?;
let path_strs: Vec<String> = paths
.iter()
.map(|p| p.to_string_lossy().replace('\\', "/"))
@@ -1617,9 +1654,10 @@ fn try_main(cli: Cli) -> Result<i32> {
out,
json,
fail,
refresh,
} => {
let path = path.unwrap_or_else(|| PathBuf::from("."));
let graph = ensure_compiled(&path, &out)?;
let graph = graph_for_query(&path, &out, refresh)?;
let items = find_conflicts(&graph);
if json {
println!("{}", conflicts_json(&items));
@@ -1633,9 +1671,10 @@ fn try_main(cli: Cli) -> Result<i32> {
out,
json,
fail,
refresh,
} => {
let path = path.unwrap_or_else(|| PathBuf::from("."));
let graph = ensure_compiled(&path, &out)?;
let graph = graph_for_query(&path, &out, refresh)?;
let items = find_stale(&graph, &path);
if json {
println!("{}", stale_json(&items));
@@ -1650,9 +1689,10 @@ fn try_main(cli: Cli) -> Result<i32> {
threshold,
fail,
json,
refresh,
} => {
let path = path.unwrap_or_else(|| PathBuf::from("."));
let graph = ensure_compiled(&path, &out)?;
let graph = graph_for_query(&path, &out, refresh)?;
let pairs = find_duplicates(&graph.symbols, threshold);
if json {
println!(
@@ -1682,9 +1722,10 @@ fn try_main(cli: Cli) -> Result<i32> {
out,
json,
fail_on_warning,
refresh,
} => {
let path = path.unwrap_or_else(|| PathBuf::from("."));
let graph = ensure_compiled(&path, &out)?;
let graph = graph_for_query(&path, &out, refresh)?;
let issues = verify(&graph);
if json {
println!("{}", verify_json(&issues));
+15 -1
View File
@@ -77,6 +77,13 @@ fn dispatch(req: &Value) -> Result<Value, Value> {
"mlsp.unsupported",
"view.document requires the view feature",
)),
#[cfg(feature = "view")]
Some("resource.view") => resource_view(&params),
#[cfg(not(feature = "view"))]
Some("resource.view") => Err(err(
"mlsp.unsupported",
"resource.view requires the view feature",
)),
Some("view.reference_resolve") => crate::workbench::resolve_reference(&params),
// `<TAB>` M9: occlusion label search (two-tier vocabulary).
Some("labels.search") => labels_search(&params),
@@ -84,7 +91,7 @@ fn dispatch(req: &Value) -> Result<Value, Value> {
Some("session.summary") => session_summary(),
other => Err(err(
"mlsp.unknown_method",
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute / artifact.reuse_execute / artifact.patch / artifact.extract_pure / document.extract / capabilities / view.document / view.reference_resolve"),
format!("未知方法 {other:?};可用:locate / syntax / validate / repair_targets / repair_apply / schema / artifact.find / artifact.inspect / link.resolve / artifact.verify / artifact.impact / artifact.bind / artifact.execute / artifact.reuse_execute / artifact.patch / artifact.extract_pure / document.extract / capabilities / view.document / resource.view / view.reference_resolve"),
)),
}
}
@@ -96,6 +103,13 @@ fn view_document(params: &Value) -> Result<Value, Value> {
crate::workbench::build_document_view(&req)
}
#[cfg(feature = "view")]
fn resource_view(params: &Value) -> Result<Value, Value> {
let req = crate::workbench::ResourceViewRequest::from_params(params)
.map_err(|e| err("mlsp.bad_request", e))?;
crate::workbench::build_resource_view(&req)
}
fn artifact_extract_pure(params: &Value) -> Result<Value, Value> {
let name = params
.get("name")
+33 -1
View File
@@ -47,6 +47,14 @@ pub fn probe_capabilities(params: &Value) -> Value {
json!({"format": "pdf", "available": false}),
json!({"format": "docx", "available": false}),
json!({"format": "ocr", "available": false}),
// M-A0 freeze: format matrix rows remain unavailable until M-A3/M-A5.
json!({"format": "json", "available": true}),
json!({"format": "csv", "available": true}),
json!({"format": "image", "available": false}),
json!({"format": "html", "available": false}),
json!({"format": "svg", "available": false}),
json!({"format": "xlsx", "available": false}),
json!({"format": "pptx", "available": false}),
];
let loaded_plugins = probe_loaded_plugins(params);
@@ -95,7 +103,8 @@ pub fn probe_capabilities(params: &Value) -> Value {
// task_control_v2 / event_replay: host_query("runtime") + /_runtime/* system routes.
features.insert("runtime.task_control_v2".into(), json!(1));
features.insert("runtime.event_replay".into(), json!(1));
features.insert("runtime.read_lane".into(), json!(0));
// short/read/control HTTP invokes use isolated admission (no parent INVOKE_LOCK).
features.insert("runtime.read_lane".into(), json!(1));
#[cfg(feature = "view")]
{
features.insert("view.analysis_cache_v2".into(), json!(1));
@@ -108,6 +117,20 @@ pub fn probe_capabilities(params: &Value) -> Value {
features.insert("view.document".into(), json!(0));
features.insert("view.reference_resolve".into(), json!(0));
}
// M-A0–M-A4: protocol capability bits.
features.insert("agent.error_v1".into(), json!(1));
features.insert("agent.checkpoint_v2".into(), json!(1));
features.insert("agent.tool_schema_v1".into(), json!(1));
features.insert("agent.output_channels_v1".into(), json!(1));
features.insert("agent.context_pack_v2".into(), json!(1));
#[cfg(feature = "view")]
{
features.insert("resource.view_v1".into(), json!(1));
}
#[cfg(not(feature = "view"))]
{
features.insert("resource.view_v1".into(), json!(0));
}
json!({
"schema_version": 1,
@@ -220,5 +243,14 @@ mod tests {
assert_eq!(caps["features"]["runtime.event_stream"], 0);
assert_eq!(caps["features"]["runtime.cancel"], 0);
assert_eq!(caps["features"]["llm.messages"], 0);
assert_eq!(caps["features"]["agent.error_v1"], 1);
assert_eq!(caps["features"]["agent.checkpoint_v2"], 1);
assert_eq!(caps["features"]["agent.tool_schema_v1"], 1);
assert_eq!(caps["features"]["agent.output_channels_v1"], 1);
assert_eq!(caps["features"]["agent.context_pack_v2"], 1);
#[cfg(feature = "view")]
assert_eq!(caps["features"]["resource.view_v1"], 1);
#[cfg(not(feature = "view"))]
assert_eq!(caps["features"]["resource.view_v1"], 0);
}
}
+4
View File
@@ -10,6 +10,8 @@ pub mod capabilities;
pub mod document_view;
pub mod event_sink;
pub mod locator;
#[cfg(feature = "view")]
pub mod resource_view;
pub mod run_context;
pub mod selection;
pub mod snapshot;
@@ -24,6 +26,8 @@ pub use capabilities::probe_capabilities;
#[cfg(feature = "view")]
pub use document_view::{build_document_view, DocumentViewRequest};
pub use event_sink::{bind_event_sink, clear_event_sink, emit_event, emit_message_delta};
#[cfg(feature = "view")]
pub use resource_view::{build_resource_view, ResourceViewRequest};
pub use locator::{resolve_reference, KnowledgeLocator};
pub use run_context::{
cancel_requested, cancel_token_body_means_cancel, RequestContext, RunContext,
File diff suppressed because it is too large. Load diff
+55
View File
@@ -0,0 +1,55 @@
---
markup: occlusion
title: agent-effects-run-tool
description: >-
M-A5a / MA-T03 subset — mutating run_tool goes through EffectLedger;
committed effects dedupe; started-without-commit becomes unknown (no re-exec).
import:
agent: /home/cflmy/work/marqdo/ext/ai/agent.mq.md
json: lib/json.mq.md
sys: lib/sys.mq.md
table: lib/table.mq.md
text: lib/text.mq.md
---
## write_probe
Probe side-effect tool body (count stays in ledger, not here).
*"wrote"*
# main
**schema = > json.parse text={"type":"object","properties":{},"additionalProperties":true}**
**scopes = > json.parse text=["workspace:write"]**
`spec` =
| id | version | description | input_schema | effect | scopes | availability |
|----|---------|-------------|--------------|--------|--------|--------------|
| write_probe | 1 | test write tool | `schema` | write | `scopes` | ready |
> agent.tools_clear
**reg = > agent.tools_register spec=`spec`**
**allow = > json.parse text=["write_probe"]**
**args = > json.parse text={}**
**out1 = > agent.run_tool tools=`allow` name="write_probe" arguments=`args` logical_run_id="run_ma5a" step_id="s1" call_id="c1" operation_id="op_write_probe_c1" ledger_dir=".marqdo/agent-effects-ma5a"**
**ok1 = > json.get value=`out1` key="ok"**
**st1 = > json.get value=`out1` key="status"**
**rc1 = > json.get value=`out1` key="effect_receipt_ref"**
> print text=`ok1`
> print text=`st1`
> print text=`rc1`
**out2 = > agent.run_tool tools=`allow` name="write_probe" arguments=`args` logical_run_id="run_ma5a" step_id="s1" call_id="c1" operation_id="op_write_probe_c1" ledger_dir=".marqdo/agent-effects-ma5a"**
**sum2 = > json.get value=`out2` key="summary"**
> print text=`sum2`
**wm = > agent.effects_watermark ledger_dir=".marqdo/agent-effects-ma5a" logical_run_id="run_ma5a"**
**safe = > json.get value=`wm` key="write_auto_resume_safe"**
> print text=`safe`
**got = > agent.effects_get operation_id="op_write_probe_c1" ledger_dir=".marqdo/agent-effects-ma5a"**
**rec = > json.get value=`got` key="record"**
**state = > json.get value=`rec` key="state"**
> print text=`state`
+10 -1
View File
@@ -5,12 +5,21 @@ description: Dual-stream execute + short models for ADR 0009 gold sample.
import:
web: ext/web/web.mq.md
site: ./site.mq.md
sys: lib/sys.mq.md
---
# main
**port_s = > sys.env_get name="MARQDO_SITE_PORT"**
**port = 18220**
1. `port_s`
**port = `port_s`**
2. *
**_ = 1**
**pg = > web.page title="isolated-execute"**
**app = > web.app page=`pg` host="127.0.0.1" port=18220**
**app = > web.app page=`pg` host="127.0.0.1" port=`port`**
**app = > web.route app=`app` path="/v1/chat/completions" method="POST" fn="site.chat" request="json" response="sse-live" class="execute"**
**app = > web.route app=`app` path="/v1/models" method="GET" fn="site.models" request="query" response="json" class="short"**
**app = > web.route app=`app` path="/v1/ping" method="GET" fn="site.ping" request="query" response="json" class="control"**
> `app`.listen
@@ -70,3 +70,16 @@ Short-class read: list models without holding an execute slot.
| list | True |
*out*
# ping
+ `payload`=None
Control-class noop: must succeed under dual execute without parent INVOKE_LOCK.
`out` =
| ok | lane |
|----|------|
| True | control |
*out*
+43
View File
@@ -1431,6 +1431,49 @@ fn knowledge_preflight_writes_context_pack() {
assert!(!packs.is_empty(), "expected context pack");
}
#[test]
fn knowledge_preflight_warm_loads_ir_without_recompile() {
let dir = tempfile_dir("mq-pf-warm");
let out = dir.to_str().unwrap();
let (code, _, stderr) = run(&["knowledge", "tests/engineering", "-o", out]);
assert_eq!(code, 0, "{stderr}");
assert!(
dir.join("ekc/graph/ir.json").exists(),
"expected ir.json snapshot after compile"
);
let gens = dir.join("generations");
let before: Vec<_> = if gens.exists() {
std::fs::read_dir(&gens).unwrap().flatten().collect()
} else {
Vec::new()
};
let (code2, stdout, stderr2) = run(&[
"knowledge",
"tests/engineering",
"preflight",
"resolve configuration",
"-o",
out,
"--json",
]);
assert_eq!(code2, 0, "{stderr2}\n{stdout}");
assert!(stdout.contains("create_allowed"), "{stdout}");
assert!(
!stderr2.contains("marqdo knowledge timing_ms:"),
"warm preflight must not full-compile: {stderr2}"
);
let after: Vec<_> = if gens.exists() {
std::fs::read_dir(&gens).unwrap().flatten().collect()
} else {
Vec::new()
};
assert_eq!(
before.len(),
after.len(),
"warm preflight must not create a new generations/ tree"
);
}
#[test]
fn catalog_hooks_knowledge_by_default() {
let dir = tempfile_dir("mq-cat-ekc");
+221
View File
@@ -417,5 +417,226 @@ fn mr01_dual_isolated_execute_and_short_reads() {
assert!(sok > 10, "expected many short 200s, got ok={sok} fail={sfail}");
assert_eq!(sfail, 0, "short reads failed: {sfail}");
assert_eq!(
caps["features"]["runtime.read_lane"],
1,
"read_lane must be on; caps={caps}"
);
let _ = std::fs::remove_dir_all(&runtime_dir);
}
/// Observer disconnect must not cancel the execute task (default).
#[test]
fn disconnect_keeps_running_and_replay() {
if TcpListener::bind("127.0.0.1:0").is_err() {
eprintln!("skip disconnect-keeps-running: local sockets unavailable");
return;
}
ensure_plugins();
let secs: u64 = 6;
let (base_a, stop_a, join_a) = spawn_fake_sse("A", secs, 10);
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let site = root.join("tests/ext/isolated-execute-site");
let runtime_dir = std::env::temp_dir().join(format!("mq-disc-rt-{}", std::process::id()));
let _ = std::fs::create_dir_all(&runtime_dir);
let bin = env!("CARGO_BIN_EXE_marqdo");
let mut child: Child = Command::new(bin)
.args(["run", "serve.mq.md"])
.current_dir(&site)
.env("MARQDO_EXT", root.join("ext"))
.env("MARQDO_WEB_PLUGIN", std::env::var_os("MARQDO_WEB_PLUGIN").unwrap())
.env("MARQDO_LLM_PLUGIN", std::env::var_os("MARQDO_LLM_PLUGIN").unwrap())
.env("MARQDO_RUNTIME_DIR", &runtime_dir)
.env("MARQDO_SITE_PORT", "18221")
.env("OPENAI_API_KEY", "mr01-key")
.stdout(Stdio::null())
.stderr(Stdio::piped())
.spawn()
.expect("spawn site");
let base = "http://127.0.0.1:18221";
if !wait_http_ok(&format!("{base}/v1/models"), Duration::from_secs(30)) {
let _ = child.kill();
panic!("site did not start for disconnect test");
}
let chat_url = format!("{base}/v1/chat/completions");
let body = format!(
r#"{{"model":"mr01","stream":true,"base_url":"{base_a}","messages":[{{"role":"user","content":"hi"}}]}}"#
);
// Observer disconnects after ~1.2s; task must keep running.
let out = Command::new("curl")
.args([
"-s",
"-N",
"--max-time",
"1",
"-H",
"Content-Type: application/json",
"-d",
&body,
&chat_url,
])
.output()
.expect("curl disconnect");
let text = String::from_utf8_lossy(&out.stdout);
let mut task_id = String::new();
for line in text.lines() {
let line = line.trim();
if let Some(rest) = line.strip_prefix("data: ") {
if let Ok(v) = serde_json::from_str::<serde_json::Value>(rest) {
if v.get("type").and_then(|t| t.as_str()) == Some("run.started") {
if let Some(tid) = v.pointer("/payload/task_id").and_then(|x| x.as_str()) {
task_id = tid.to_string();
}
}
}
}
}
assert!(!task_id.is_empty(), "missing task_id in early SSE; raw={text}");
// Wait until task finishes (observer already gone).
let mut terminal = false;
let deadline = Instant::now() + Duration::from_secs(secs + 8);
while Instant::now() < deadline {
let get_url = format!("{base}/_runtime/tasks/{task_id}");
let out = Command::new("curl")
.args(["-s", &get_url])
.output()
.expect("runtime get");
let body = String::from_utf8_lossy(&out.stdout);
if body.contains("\"completed\"")
|| body.contains("\"succeeded\"")
|| body.contains("\"failed\"")
|| body.contains("\"cancelled\"")
{
assert!(
!body.contains("\"cancelled\""),
"disconnect must not cancel task: {body}"
);
terminal = true;
break;
}
thread::sleep(Duration::from_millis(200));
}
assert!(terminal, "task {task_id} did not finish after observer disconnect");
// Replay via events (JSON after_seq=0).
let ev_url = format!("{base}/_runtime/tasks/{task_id}/events?after_seq=0");
let ev = Command::new("curl")
.args(["-s", &ev_url])
.output()
.expect("events");
let ev_body = String::from_utf8_lossy(&ev.stdout);
assert!(
ev_body.contains('A') || ev_body.contains("delta") || ev_body.contains("event"),
"replay empty: {ev_body}"
);
stop_a.store(true, Ordering::Relaxed);
let _ = join_a.join();
let _ = child.kill();
let _ = child.wait();
let _ = std::fs::remove_dir_all(&runtime_dir);
}
/// Control + short reads stay 200 while two execute streams hold slots.
#[test]
fn control_under_dual_execute() {
if TcpListener::bind("127.0.0.1:0").is_err() {
eprintln!("skip control-under-dual-execute: local sockets unavailable");
return;
}
ensure_plugins();
let secs: u64 = 8;
let (base_a, stop_a, join_a) = spawn_fake_sse("A", secs, 10);
let (base_b, stop_b, join_b) = spawn_fake_sse("B", secs, 10);
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let site = root.join("tests/ext/isolated-execute-site");
let runtime_dir = std::env::temp_dir().join(format!("mq-ctl-rt-{}", std::process::id()));
let _ = std::fs::create_dir_all(&runtime_dir);
let bin = env!("CARGO_BIN_EXE_marqdo");
let mut child: Child = Command::new(bin)
.args(["run", "serve.mq.md"])
.current_dir(&site)
.env("MARQDO_EXT", root.join("ext"))
.env("MARQDO_WEB_PLUGIN", std::env::var_os("MARQDO_WEB_PLUGIN").unwrap())
.env("MARQDO_LLM_PLUGIN", std::env::var_os("MARQDO_LLM_PLUGIN").unwrap())
.env("MARQDO_RUNTIME_DIR", &runtime_dir)
.env("MARQDO_SITE_PORT", "18222")
.env("OPENAI_API_KEY", "mr01-key")
.stdout(Stdio::null())
.stderr(Stdio::piped())
.spawn()
.expect("spawn site");
let base = "http://127.0.0.1:18222";
if !wait_http_ok(&format!("{base}/v1/models"), Duration::from_secs(30)) {
let _ = child.kill();
panic!("site did not start for control test");
}
let chat_url = format!("{base}/v1/chat/completions");
let body_tmpl = r#"{"model":"mr01","stream":true,"base_url":"__BASE__","messages":[{"role":"user","content":"hi"}]}"#;
let t_a = {
let u = chat_url.clone();
let b = body_tmpl.to_string();
let ba = base_a.clone();
thread::spawn(move || {
let _ = collect_sse_deltas(&u, &b, &ba);
})
};
let t_b = {
let u = chat_url.clone();
let b = body_tmpl.to_string();
let bb = base_b.clone();
thread::spawn(move || {
let _ = collect_sse_deltas(&u, &b, &bb);
})
};
thread::sleep(Duration::from_secs(1));
let mut ok_n = 0u32;
let mut fail_n = 0u32;
let start = Instant::now();
while start.elapsed() < Duration::from_secs(3) {
for path in ["/v1/models", "/v1/ping"] {
let url = format!("{base}{path}");
let t0 = Instant::now();
let out = Command::new("curl")
.args(["-s", "-o", "/dev/null", "-w", "%{http_code}", &url])
.output();
let elapsed = t0.elapsed();
match out {
Ok(o) if String::from_utf8_lossy(&o.stdout) == "200" => {
assert!(
elapsed < Duration::from_millis(1500),
"{path} p95 budget; took {elapsed:?}"
);
ok_n += 1;
}
_ => fail_n += 1,
}
}
thread::sleep(Duration::from_millis(80));
}
assert!(ok_n > 4, "expected control/short 200s, ok={ok_n} fail={fail_n}");
assert_eq!(fail_n, 0, "control/short failed under dual execute: {fail_n}");
let _ = t_a.join();
let _ = t_b.join();
stop_a.store(true, Ordering::Relaxed);
stop_b.store(true, Ordering::Relaxed);
let _ = join_a.join();
let _ = join_b.join();
let _ = child.kill();
let _ = child.wait();
let _ = std::fs::remove_dir_all(&runtime_dir);
}
@@ -0,0 +1,14 @@
{
"schema": "AgentErrorV1",
"schema_version": 1,
"code": "tool.timeout",
"category": "transient",
"stage": "tool",
"message": "读取资源超时",
"retryable": true,
"retry_after_ms": 1200,
"effect_state": "none",
"recovery_action": "retry_step",
"call_id": "call_01",
"details_ref": "resource:diagnostic_01"
}
@@ -0,0 +1,15 @@
{
"schema": "AgentErrorV1",
"schema_version": 99,
"code": "tool.timeout",
"category": "transient",
"stage": "tool",
"message": "读取资源超时",
"retryable": true,
"retry_after_ms": 1200,
"effect_state": "none",
"recovery_action": "retry_step",
"call_id": "call_01",
"details_ref": "resource:diagnostic_01",
"future_field": true
}
@@ -0,0 +1,11 @@
{
"schema": "AgentOutputV1",
"schema_version": 1,
"status": "failed",
"answer": {"format": "markdown", "text": "文档门禁未通过,草稿仍可打开。"},
"artifacts": [],
"citations": [],
"validation": {"status": "failed", "report_ref": "resource:verify_fail"},
"finish_reason": "validation_failed",
"recovery_options": [{"action": "repair_once", "label": "修复后重试"}]
}
@@ -0,0 +1,11 @@
{
"schema": "AgentOutputV1",
"schema_version": 1,
"status": "succeeded",
"answer": {"format": "markdown", "text": "已整理为三点,完整笔记见右侧。"},
"artifacts": [{"resource_id": "res_note_01", "revision": "sha256:example"}],
"citations": [],
"validation": {"status": "passed", "report_ref": "resource:verify_01"},
"finish_reason": "completed",
"recovery_options": []
}
@@ -0,0 +1,13 @@
{
"id": "legacy_resume_01",
"updated_at": "2026-10-27T02:49:00Z",
"goal": "回答用户问题",
"task": "你好",
"status": "interrupted",
"workbook": ".marqdo/agent-kb/resources/你好.mq.md",
"events": [],
"route": {},
"result": null,
"round": 1,
"meta": {}
}
@@ -0,0 +1,17 @@
{
"schema": "CheckpointV2",
"schema_version": 2,
"checkpoint_id": "ckpt_01",
"logical_run_id": "run_logic_01",
"task_id": "task_01",
"attempt_id": "attempt_01",
"step_id": "step_01",
"parent_checkpoint_id": null,
"principal_ref": "principal_01",
"workspace_id": "ws_01",
"session_id": "sess_01",
"completed_steps": [],
"pending_operation": null,
"deadline": "2026-10-27T12:00:00Z",
"committed_at": "2026-10-27T02:49:00Z"
}
@@ -0,0 +1,14 @@
{
"schema": "ContextPackV2",
"schema_version": 2,
"items": [
{
"origin": "user",
"trust": "user",
"resource_ref": "res_01",
"revision": "sha256:example",
"token_estimate": 120,
"priority": 1
}
]
}
@@ -0,0 +1,12 @@
{
"schema": "EffectLedgerRecordV1",
"schema_version": 1,
"operation_id": "op_01",
"idempotency_key": "idem_01",
"args_digest": "sha256:args",
"resource_scope": "workspace:ws_01",
"expected_revision": "sha256:example",
"effect_class": "write",
"result_ref": null,
"state": "prepared"
}
@@ -0,0 +1,14 @@
{
"schema": "ResourceRefV1",
"schema_version": 1,
"resource_id": "res_01",
"workspace_id": "ws_01",
"kind": "file",
"media_type": "text/markdown",
"revision": "sha256:example",
"digest": "sha256:example",
"title": "设计说明",
"size": 12,
"origin": "workspace",
"locator": null
}
@@ -0,0 +1,24 @@
{
"schema": "ResourceViewV1",
"schema_version": 1,
"resource": {
"resource_id": "res_01",
"workspace_id": "ws_01",
"kind": "file",
"revision": "sha256:example",
"media_type": "text/markdown",
"title": "设计说明",
"digest": "sha256:example",
"size": 12,
"origin": "workspace",
"locator": null
},
"renderer": {"id": "markdown", "version": "1", "trust": "sanitized"},
"render": {"format": "sanitized_html", "fragment": "<p>正文</p>"},
"outline": [],
"locators": [],
"completeness": "complete",
"no_exec": true,
"diagnostics": [],
"next_cursor": null
}
@@ -0,0 +1,24 @@
{
"schema": "RuntimeEventV2",
"schema_version": 2,
"event_id": "evt_01",
"seq": 7,
"task_id": "task_01",
"run_id": "run_01",
"attempt_id": "attempt_01",
"type": "tool.failed",
"payload": {
"schema": "AgentErrorV1",
"schema_version": 1,
"code": "tool.timeout",
"category": "transient",
"stage": "tool",
"message": "读取资源超时",
"retryable": true,
"retry_after_ms": 1200,
"effect_state": "none",
"recovery_action": "retry_step",
"call_id": "call_01",
"details_ref": "resource:diagnostic_01"
}
}
@@ -0,0 +1,10 @@
{
"schema": "ToolCallV1",
"schema_version": 1,
"call_id": "call_01",
"tool_id": "workspace.read",
"tool_version": "1",
"arguments": {"resource_id": "res_01", "start_line": 1, "max_lines": 40},
"operation_id": "op_01",
"parent_span_id": "span_01"
}
@@ -0,0 +1,15 @@
{
"schema": "ToolResultV1",
"schema_version": 1,
"ok": true,
"status": "succeeded",
"summary": "已读取 12 行",
"structured_content": {"lines": ["a", "b"]},
"resources": [{"resource_id": "res_01", "revision": "sha256:example"}],
"citations": [],
"error": null,
"usage": {"elapsed_ms": 12},
"truncated": false,
"next_cursor": null,
"effect_receipt_ref": null
}
@@ -0,0 +1,26 @@
{
"schema": "ToolSpecV1",
"schema_version": 1,
"id": "workspace.read",
"version": "1",
"description": "读取授权资源的指定行范围",
"input_schema": {
"type": "object",
"properties": {
"resource_id": {"type": "string"},
"revision": {"type": "string"},
"start_line": {"type": "integer", "minimum": 1},
"max_lines": {"type": "integer", "minimum": 1, "maximum": 500}
},
"required": ["resource_id"],
"additionalProperties": false
},
"output_schema_ref": "ResourceReadV1",
"effect": "read",
"scopes": ["workspace:read"],
"timeout_ms": 10000,
"max_result_bytes": 65536,
"idempotency": "safe",
"concurrency_group": "resource-read",
"availability": "ready"
}
@@ -0,0 +1,22 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "marqdo://contracts/AgentErrorV1",
"title": "AgentErrorV1",
"type": "object",
"required": ["schema", "schema_version", "code", "category", "stage", "message", "retryable", "effect_state", "recovery_action"],
"properties": {
"schema": { "const": "AgentErrorV1" },
"schema_version": { "const": 1 },
"code": { "type": "string" },
"category": { "type": "string" },
"stage": { "type": "string" },
"message": { "type": "string" },
"retryable": { "type": "boolean" },
"retry_after_ms": { "type": ["integer", "null"] },
"effect_state": { "type": "string" },
"recovery_action": { "type": "string" },
"call_id": { "type": ["string", "null"] },
"details_ref": { "type": ["string", "null"] }
},
"additionalProperties": true
}
@@ -0,0 +1,19 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "marqdo://contracts/AgentOutputV1",
"title": "AgentOutputV1",
"type": "object",
"required": ["schema", "schema_version", "status", "answer", "finish_reason"],
"properties": {
"schema": { "const": "AgentOutputV1" },
"schema_version": { "const": 1 },
"status": { "enum": ["succeeded", "partial", "failed", "needs_input", "cancelled"] },
"answer": { "type": "object" },
"artifacts": { "type": "array" },
"citations": { "type": "array" },
"validation": { "type": "object" },
"finish_reason": { "type": "string" },
"recovery_options": { "type": "array" }
},
"additionalProperties": true
}
@@ -0,0 +1,25 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "marqdo://contracts/CheckpointV2",
"title": "CheckpointV2",
"type": "object",
"required": ["schema", "schema_version", "checkpoint_id", "logical_run_id", "task_id", "attempt_id", "committed_at"],
"properties": {
"schema": { "const": "CheckpointV2" },
"schema_version": { "const": 2 },
"checkpoint_id": { "type": "string" },
"logical_run_id": { "type": "string" },
"task_id": { "type": "string" },
"attempt_id": { "type": "string" },
"step_id": { "type": ["string", "null"] },
"parent_checkpoint_id": { "type": ["string", "null"] },
"principal_ref": { "type": ["string", "null"] },
"workspace_id": { "type": ["string", "null"] },
"session_id": { "type": ["string", "null"] },
"completed_steps": { "type": "array" },
"pending_operation": {},
"deadline": { "type": ["string", "null"] },
"committed_at": { "type": "string" }
},
"additionalProperties": true
}
@@ -0,0 +1,19 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "marqdo://contracts/ContextPackV2",
"title": "ContextPackV2",
"type": "object",
"required": ["schema", "schema_version", "items"],
"properties": {
"schema": { "const": "ContextPackV2" },
"schema_version": { "const": 2 },
"items": {
"type": "array",
"items": {
"type": "object",
"required": ["origin", "trust", "resource_ref", "revision", "token_estimate", "priority"]
}
}
},
"additionalProperties": true
}
@@ -0,0 +1,46 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "marqdo://contracts/EffectLedgerRecordV1",
"title": "EffectLedgerRecordV1",
"type": "object",
"required": [
"schema",
"schema_version",
"operation_id",
"idempotency_key",
"args_digest",
"effect_class",
"state"
],
"properties": {
"schema": { "const": "EffectLedgerRecordV1" },
"schema_version": { "const": 1 },
"operation_id": { "type": "string" },
"idempotency_key": { "type": "string" },
"args_digest": { "type": "string" },
"resource_scope": { "type": ["string", "null"] },
"expected_revision": { "type": ["string", "null"] },
"effect_class": {
"type": "string",
"enum": ["read", "write", "execute", "external_write", "none"]
},
"result_ref": { "type": ["string", "null"] },
"state": {
"type": "string",
"enum": [
"prepared",
"started",
"committed",
"failed_no_effect",
"unknown",
"reconciled_committed",
"reconciled_no_effect",
"needs_input"
]
},
"logical_run_id": { "type": ["string", "null"] },
"step_id": { "type": ["string", "null"] },
"attempt_id": { "type": ["string", "null"] }
},
"additionalProperties": true
}
@@ -0,0 +1,22 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "marqdo://contracts/ResourceRefV1",
"title": "ResourceRefV1",
"type": "object",
"required": ["schema", "schema_version", "resource_id", "workspace_id", "kind", "media_type", "revision", "digest", "title", "size", "origin"],
"properties": {
"schema": { "const": "ResourceRefV1" },
"schema_version": { "const": 1 },
"resource_id": { "type": "string" },
"workspace_id": { "type": "string" },
"kind": { "type": "string" },
"media_type": { "type": "string" },
"revision": { "type": "string" },
"digest": { "type": "string" },
"title": { "type": "string" },
"size": { "type": "integer" },
"origin": { "type": "string" },
"locator": {}
},
"additionalProperties": true
}
@@ -0,0 +1,21 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "marqdo://contracts/ResourceViewV1",
"title": "ResourceViewV1",
"type": "object",
"required": ["schema", "schema_version", "resource", "renderer", "completeness", "no_exec"],
"properties": {
"schema": { "const": "ResourceViewV1" },
"schema_version": { "const": 1 },
"resource": { "type": "object" },
"renderer": { "type": "object" },
"render": { "type": "object" },
"outline": { "type": "array" },
"locators": { "type": "array" },
"completeness": { "type": "string" },
"no_exec": { "const": true },
"diagnostics": { "type": "array" },
"next_cursor": { "type": ["string", "null"] }
},
"additionalProperties": true
}
@@ -0,0 +1,18 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "marqdo://contracts/ToolCallV1",
"title": "ToolCallV1",
"type": "object",
"required": ["schema", "schema_version", "call_id", "tool_id", "tool_version", "arguments", "operation_id"],
"properties": {
"schema": { "const": "ToolCallV1" },
"schema_version": { "const": 1 },
"call_id": { "type": "string" },
"tool_id": { "type": "string" },
"tool_version": { "type": "string" },
"arguments": { "type": "object" },
"operation_id": { "type": "string" },
"parent_span_id": { "type": ["string", "null"] }
},
"additionalProperties": true
}
@@ -0,0 +1,23 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "marqdo://contracts/ToolResultV1",
"title": "ToolResultV1",
"type": "object",
"required": ["schema", "schema_version", "ok", "status", "summary"],
"properties": {
"schema": { "const": "ToolResultV1" },
"schema_version": { "const": 1 },
"ok": { "type": "boolean" },
"status": { "type": "string" },
"summary": { "type": "string" },
"structured_content": {},
"resources": { "type": "array" },
"citations": { "type": "array" },
"error": {},
"usage": {},
"truncated": { "type": "boolean" },
"next_cursor": { "type": ["string", "null"] },
"effect_receipt_ref": { "type": ["string", "null"] }
},
"additionalProperties": true
}
@@ -0,0 +1,24 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "marqdo://contracts/ToolSpecV1",
"title": "ToolSpecV1",
"type": "object",
"required": ["schema", "schema_version", "id", "version", "description", "input_schema", "effect", "scopes", "timeout_ms", "availability"],
"properties": {
"schema": { "const": "ToolSpecV1" },
"schema_version": { "const": 1 },
"id": { "type": "string" },
"version": { "type": "string" },
"description": { "type": "string" },
"input_schema": { "type": "object" },
"output_schema_ref": { "type": ["string", "null"] },
"effect": { "type": "string" },
"scopes": { "type": "array" },
"timeout_ms": { "type": "integer" },
"max_result_bytes": { "type": ["integer", "null"] },
"idempotency": { "type": "string" },
"concurrency_group": { "type": ["string", "null"] },
"availability": { "type": "string" }
},
"additionalProperties": true
}
+182
View File
@@ -100,6 +100,188 @@ fn m00_fixtures_consume_and_capabilities() {
assert_eq!(down["result"]["features"]["runtime.cancel"], 0);
}
/// M-A0: freeze Agent reliability protocol fixtures; capability bits stay 0.
#[test]
fn ma0_agent_reliability_protocol_freeze() {
let err = fixture("agent_error_v1.json");
assert_required(&err, &schema("AgentErrorV1.schema.json"), "agent_error");
assert_eq!(err["schema"], "AgentErrorV1");
assert_eq!(err["schema_version"], 1);
let degrade = fixture("agent_error_v1_unknown_version.json");
assert_eq!(degrade["schema"], "AgentErrorV1");
assert_eq!(degrade["schema_version"], 99);
assert_eq!(degrade["future_field"], true);
let tool = fixture("tool_spec_v1.json");
assert_required(&tool, &schema("ToolSpecV1.schema.json"), "tool_spec");
assert_required(
&fixture("tool_call_v1.json"),
&schema("ToolCallV1.schema.json"),
"tool_call",
);
assert_required(
&fixture("tool_result_v1.json"),
&schema("ToolResultV1.schema.json"),
"tool_result",
);
let ckpt = fixture("checkpoint_v2.json");
assert_required(&ckpt, &schema("CheckpointV2.schema.json"), "checkpoint");
assert_eq!(ckpt["schema_version"], 2);
let legacy = fixture("checkpoint_legacy_resume.json");
assert!(legacy.get("schema").is_none());
assert!(legacy.get("effect_class").is_none());
assert_eq!(legacy["id"], "legacy_resume_01");
let ledger = fixture("effect_ledger_v1.json");
assert_required(
&ledger,
&schema("EffectLedgerRecordV1.schema.json"),
"effect_ledger",
);
assert_eq!(ledger["schema"], "EffectLedgerRecordV1");
assert_eq!(ledger["state"], "prepared");
assert_eq!(ledger["effect_class"], "write");
let out_ok = fixture("agent_output_v1_succeeded.json");
assert_required(&out_ok, &schema("AgentOutputV1.schema.json"), "agent_output_ok");
assert_eq!(out_ok["status"], "succeeded");
let out_fail = fixture("agent_output_v1_failed.json");
assert_required(
&out_fail,
&schema("AgentOutputV1.schema.json"),
"agent_output_fail",
);
assert_eq!(out_fail["status"], "failed");
let pack = fixture("context_pack_v2.json");
assert_required(&pack, &schema("ContextPackV2.schema.json"), "context_pack");
assert_eq!(pack["schema_version"], 2);
let item = &pack["items"][0];
for key in [
"origin",
"trust",
"resource_ref",
"revision",
"token_estimate",
"priority",
] {
assert!(item.get(key).is_some(), "context item missing {key}");
}
assert_required(
&fixture("resource_ref_v1.json"),
&schema("ResourceRefV1.schema.json"),
"resource_ref",
);
let view = fixture("resource_view_v1.json");
assert_required(&view, &schema("ResourceViewV1.schema.json"), "resource_view");
assert_eq!(view["no_exec"], true);
let tev = fixture("runtime_event_tool_failed.json");
assert_eq!(tev["schema"], "RuntimeEventV2");
assert_eq!(tev["type"], "tool.failed");
assert_eq!(tev["payload"]["schema"], "AgentErrorV1");
let caps = mlsp("capabilities", serde_json::json!({}));
assert_eq!(caps["ok"], true, "{caps}");
let features = &caps["result"]["features"];
// M-A1–M-A4: agent reliability emitters are live.
assert_eq!(features["agent.error_v1"], 1);
assert_eq!(features["agent.checkpoint_v2"], 1);
assert_eq!(features["agent.tool_schema_v1"], 1);
assert_eq!(features["agent.output_channels_v1"], 1);
assert_eq!(features["agent.context_pack_v2"], 1);
assert_eq!(features["resource.view_v1"], 1);
let formats = caps["result"]["extract_formats"]
.as_array()
.expect("extract_formats");
let pdf = formats
.iter()
.find(|f| f["format"] == "pdf")
.expect("pdf row");
assert_eq!(pdf["available"], false);
let json_fmt = formats
.iter()
.find(|f| f["format"] == "json")
.expect("json row");
assert_eq!(json_fmt["available"], true);
let csv_fmt = formats
.iter()
.find(|f| f["format"] == "csv")
.expect("csv row");
assert_eq!(csv_fmt["available"], true);
// Live contracts list still excludes unimplemented agent schemas.
let contracts = caps["result"]["contracts"].as_array().unwrap();
assert!(!contracts.iter().any(|c| c.as_str() == Some("AgentErrorV1")));
let down = mlsp(
"capabilities",
serde_json::json!({
"force_unloaded": true,
"force_stream_off": true,
"force_cancel_off": true
}),
);
assert_eq!(down["result"]["features"]["agent.error_v1"], 1);
assert_eq!(down["result"]["features"]["agent.checkpoint_v2"], 1);
assert_eq!(down["result"]["features"]["agent.tool_schema_v1"], 1);
assert_eq!(down["result"]["features"]["agent.output_channels_v1"], 1);
assert_eq!(down["result"]["features"]["agent.context_pack_v2"], 1);
assert_eq!(down["result"]["features"]["resource.view_v1"], 1);
}
#[test]
fn ma3_resource_view_static_no_exec() {
use std::io::Write;
use std::time::{SystemTime, UNIX_EPOCH};
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_nanos();
let dir = std::env::temp_dir().join(format!("marqdo-ma3-rv-{nanos}"));
std::fs::create_dir_all(&dir).unwrap();
let md = dir.join("readme.md");
{
let mut f = std::fs::File::create(&md).unwrap();
writeln!(f, "# Hello\n\n<script>x</script>").unwrap();
}
let resp = mlsp(
"resource.view",
serde_json::json!({
"workspace_root": dir.to_string_lossy(),
"path": "readme.md",
"mode": "read"
}),
);
assert_eq!(resp["ok"], true, "{resp}");
let view = &resp["result"];
assert_required(view, &schema("ResourceViewV1.schema.json"), "resource_view_live");
assert_eq!(view["no_exec"], true);
assert_eq!(view["schema"], "ResourceViewV1");
let frag = view["render"]["fragment"].as_str().unwrap();
assert!(frag.contains("Hello"));
assert!(frag.contains("&lt;script&gt;") || !frag.contains("<script>"));
let escape = mlsp(
"resource.view",
serde_json::json!({
"workspace_root": dir.to_string_lossy(),
"path": "../outside.txt",
"mode": "read"
}),
);
assert_eq!(escape["ok"], false, "{escape}");
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn m00_strict_selection_rejects_missing() {
let bad = serde_json::json!({"schema_version": 1, "model_id": "x"});