Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
41587f319e | ||
|
|
298fbd51ea | ||
|
|
265dfdbcc4 | ||
|
|
42a43f5ffd | ||
|
|
037a963547 | ||
|
|
a32638e935 | ||
|
|
43eebe5671 | ||
|
|
e833dc05e2 | ||
|
|
11bb7ef277 | ||
|
|
6bd90bb2d0 | ||
|
|
4683f2e067 | ||
|
|
5912164039 | ||
|
|
303c06f773 | ||
|
|
a1086fd6c3 | ||
|
|
6ffe5ceb19 | ||
|
|
6b568aff3d | ||
|
|
16f26d7d60 | ||
|
|
b8265a92aa | ||
|
|
9af929971c | ||
|
|
2c4fa4bb05 |
No files matched your search
@@ -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
|
||||
|
||||
@@ -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
@@ -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
@@ -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"
|
||||
|
||||
@@ -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,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)"
|
||||
|
||||
Vendored
+7
@@ -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
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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 保持不可用,不阻塞已经完成的只读预览切片。
|
||||
@@ -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
@@ -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 < 300 ms;核心工具发现 p95 < 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
@@ -1 +1 @@
|
||||
2.1.4
|
||||
2.1.5
|
||||
+485
-11
@@ -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`**
|
||||
|
||||
@@ -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");
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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
@@ -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),
|
||||
|
||||
@@ -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
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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());
|
||||
}
|
||||
}
|
||||
@@ -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")
|
||||
|
||||
@@ -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
@@ -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
@@ -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>,
|
||||
|
||||
@@ -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};
|
||||
|
||||
@@ -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
@@ -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
@@ -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(¶ms),
|
||||
#[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(¶ms),
|
||||
// `<TAB>` M9: occlusion label search (two-tier vocabulary).
|
||||
Some("labels.search") => labels_search(¶ms),
|
||||
@@ -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")
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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
@@ -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`
|
||||
@@ -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*
|
||||
@@ -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");
|
||||
|
||||
@@ -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
|
||||
}
|
||||
@@ -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("<script>") || !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"});
|
||||
|
||||
Reference in new issue
Block a user