Compare commits

...
Author SHA1 Message Date
cflmy 24959a0ba8 fix: validate Windows extension packs with 7-Zip 2026-11-18 14:40:07 +08:00
cflmyandCursor afbb9f191c ci: retrigger EK for ext-v2.8.1 release gate
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-18 13:41:29 +08:00
cflmy 8db699191e release(ext-2.8.1): AI durable workflow pack with Windows packaging fixes 2026-11-18 13:37:02 +08:00
cflmy e5580d9640 release(ext-2.8.3): use Windows System32 tar for pack ZIP encoding 2026-11-18 13:25:09 +08:00
cflmy 9ce2ae1037 release(ext-2.8.2): fix Windows packs.ci root and ship AI durable workflow 2026-11-18 13:08:59 +08:00
cflmy 166b01c86b release(ext-2.8.1): AI native durable workflow pack notes and VERSION 2026-11-18 12:41:57 +08:00
cflmyandCursor 87cfe05095 docs(next): add 014 knowledge-anchor compilation direction
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-18 12:40:41 +08:00
cflmy b37387e6da Merge native AI flow workflow into main
Integrate the v2.8.0-based native agent workflow branch:
- durable open/next/inspect/list/commit/cancel step state with resume_dir isolation
- verified small-model choices, scoped context and bounded parallel recovery
- failed-only read-only retry through the Agent ABI plugin
- offline interpreter fixtures, contract checks and focused CI gates
2026-11-18 12:33:54 +08:00
cflmy 895752a1fd Merge v2.8.0 into native AI flow branch
- take the 2.8.0 crate versions, Cargo.lock dependency graph and release workflows
- keep the native workflow inspect/list, resume_dir isolation and repeatable fixtures
- satisfy the 2.8.0 library narrative gate for workflow.tick
- resolve CHANGELOG ordering with the v2.8.0 release entry
2026-11-18 12:14:03 +08:00
cflmy 38c07d9a0e feat(agent): add workflow inspection and durable isolation
- add agent_workflow_inspect/list primitives and ext/ai wrappers
- expose host-relative resume_dir on every workflow operation
- make offline workflow fixture repeatable with a timestamped run id
- fix flow.choose branch scoping contract diagnostic
- build the agent cdylib and drop the removed run --effects flag in CI
2026-11-18 11:57:12 +08:00
cflmy 8e437e2cd3 ci(agent): permit native ABI loading in offline Agent integration tests 2026-11-18 10:17:47 +08:00
cflmy 23229a6ac9 ci(agent): permit native ABI loading in offline Agent integration tests 2026-11-18 10:17:44 +08:00
cflmy 58b65215a1 test(agent): show the failed native choice result in interpreter smoke diagnostics 2026-11-18 10:16:43 +08:00
cflmy 92c3f80055 fix(agent): compare branch labels using explicit text conversion 2026-11-18 09:59:27 +08:00
cflmy 8a66f803cb feat(agent): add validated forward-only branching from model choices to registered SKILL steps 2026-11-18 09:59:16 +08:00
cflmy 3ce59a4da8 test(ai): verify JSON-formatted small-model option parsing from Marqdo 2026-11-18 09:57:47 +08:00
cflmy 90688741c5 feat(agent): parse bounded JSON choice envelopes without relaxing skill allowlist 2026-11-18 09:57:37 +08:00
cflmy 70b88b3767 security(agent): require explicit read-only classification before automatic SKILL/parallel dispatch 2026-11-18 09:57:06 +08:00
cflmy f859e6eeea test(ai): include required short model prompt in workflow fixture 2026-11-18 09:56:55 +08:00
cflmy 6705e2e6b7 fix(agent): require explicit local prompt for model workflow steps 2026-11-18 09:56:49 +08:00
cflmy 6e8a62928b test(ai): verify plugin-only tick returns waiting input and commits final step 2026-11-18 09:56:39 +08:00
cflmy 398a0b7222 ci(agent): introduce focused plugin-only native workflow gate separate from long EK suite 2026-11-18 09:56:28 +08:00
cflmy e8f1a3e126 fix(agent): deduplicate equivalent numbered and labeled user replies 2026-11-18 09:56:16 +08:00
cflmy 8ea56cbe30 test(ai): exercise ABI failed-only recovery without executing already successful children 2026-11-18 09:55:42 +08:00
cflmy 8085d06124 feat(ai): expose failed-only read-only child recovery as a short Marqdo workflow 2026-11-18 09:55:30 +08:00
cflmy 6f929dc2da feat(agent): publish safe partial fan-out recovery through Agent ABI 2026-11-18 09:55:19 +08:00
cflmy dd22180269 feat(agent): recover failed read-only children only, preserving successful subtask results 2026-11-18 09:55:11 +08:00
cflmy cc48bf6d05 docs(agent): document plugin-only durable step state engine and safety boundaries 2026-11-18 09:54:45 +08:00
cflmy 19f986953a test(ai): prove successful parallel child outputs survive failed sibling and checkpoint reload 2026-11-18 09:54:21 +08:00
cflmy 770dee5199 fix(agent): prevent EffectLedger atomic temp collisions under parallel operations 2026-11-18 09:54:06 +08:00
cflmy f6612813e3 fix(agent): remove resume test global cwd races and make atomic temp names unique 2026-11-18 09:53:58 +08:00
cflmy 643ea06340 feat(ai): add one-step native workflow driver for model input and bounded child tasks 2026-11-18 09:53:17 +08:00
cflmy 0cd64a7450 fix(agent): persist partial child outcomes and require verified process success before workflow commit 2026-11-18 09:53:02 +08:00
cflmy 981faac022 ci(ai): test native workflow plugin through actual Marqdo interpreter 2026-11-18 09:52:42 +08:00
cflmy f818834ec1 test(ai): exercise ABI-only durable workflow in actual Marqdo interpreter 2026-11-18 09:52:35 +08:00
cflmy 8d47507d15 feat(ai): expose a concise ABI-backed durable workflow library 2026-11-18 09:52:13 +08:00
cflmy 1e1f05c087 feat(agent): register ABI workflow state transitions and cancellation 2026-11-18 09:51:59 +08:00
cflmy 06e61efc51 feat(agent): implement plugin-only durable step workflow with deterministic next/commit/cancel and tests 2026-11-18 09:51:51 +08:00
cflmy 2dfa0b2a5b fix(ai): do not mistake LLM transport errors for choices or trigger format repair 2026-11-18 09:46:24 +08:00
cflmy 629ad8ed39 feat(agent): tolerate short deterministic small-model selection phrases 2026-11-18 09:43:59 +08:00
cflmy ee677478be test(ai): verify file/class/function context composition in Marqdo interpreter 2026-11-18 09:43:30 +08:00
cflmy edbf241d99 feat(ai): compose current user and scoped file/class/function source into a bounded context pack 2026-11-18 09:43:24 +08:00
cflmy add6a7d32c docs(agent): record implemented contracts and precise VM/runtime completion gates 2026-11-18 09:42:07 +08:00
cflmy c64ec99115 feat(ai): expose minimal ask/start/wait on top of native LLM and subtask APIs 2026-11-18 09:41:28 +08:00
cflmy 60a3b84a84 test(ai): exercise durable input and reply from a real Marqdo program 2026-11-18 09:41:08 +08:00
cflmy 02a4f2d20d fix(agent): skip YAML setext lookalikes in document-scope parser 2026-11-18 09:40:50 +08:00
cflmy 88490e3092 ci(ai): execute real native choice and scoped-context Marqdo smoke 2026-11-18 09:40:15 +08:00
cflmy 9031c106a1 test(ai): add offline Marqdo interpreter smoke for native choice and scoped context 2026-11-18 09:40:08 +08:00
cflmy 633436e40f fix(agent): compare owned JSON values with dereferenced optional identity values 2026-11-18 09:39:53 +08:00
cflmy cf73fcf1ef feat(ai): add allowlisted SKILL enter via standard Marqdo subtasks 2026-11-18 09:39:37 +08:00
cflmy e48fd5b0f4 feat(ai): aggregate concurrent child status without losing successful siblings 2026-11-18 09:39:06 +08:00
cflmy b2f97e72c3 build(agent): lock pulldown-cmark dependency for native scoped context 2026-11-18 09:38:58 +08:00
cflmy c7c0f66d1f feat(agent): register typed concurrent task result aggregator 2026-11-18 09:38:33 +08:00
cflmy d5ab9daebb feat(agent): classify parallel child successes, failures and unknown outcomes 2026-11-18 09:38:26 +08:00
cflmy 5795236d1f feat(ai): expose durable step-boundary input/reply in flow SKILL 2026-11-18 09:37:56 +08:00
cflmy e8d6dc92fc feat(agent): register user-input pause/reply gate primitives 2026-11-18 09:37:44 +08:00
cflmy afe31cb2a8 feat(agent): durable user-input gate with idempotent reply, revision and session checks 2026-11-18 09:37:35 +08:00
cflmy 905a67df32 feat(ai): expose native Markdown scope selection to Marqdo authors 2026-11-18 09:37:18 +08:00
cflmy f63b7ef48d feat(agent): register scoped context projection in native plugin 2026-11-18 09:37:02 +08:00
cflmy 393558ca97 feat(agent): register scoped context projection in native plugin 2026-11-18 09:36:59 +08:00
cflmy 0d9bd99fc0 feat(agent): add Markdown heading-scoped bounded file/class/function prompt projection with tests 2026-11-18 09:36:52 +08:00
cflmy a0c779e022 fix(ai): declare function parameters in Marqdo prose syntax 2026-11-18 09:36:31 +08:00
cflmy a82b6fdde1 fix(ai): declare function parameters in Marqdo prose syntax 2026-11-18 09:36:28 +08:00
cflmy 3613ed7c4e fix(ai): declare function parameters in Marqdo prose syntax 2026-11-18 09:36:26 +08:00
cflmy 9564dff777 docs(ai): link the new native flow, context and recovery modules 2026-11-18 09:34:13 +08:00
cflmy f56deffefe test(agent): isolate EffectLedger tests without process-global cwd races 2026-11-18 09:33:28 +08:00
cflmy bdedf3ecd8 ci(ai): include scoped context pack in syntax gates 2026-11-18 09:32:55 +08:00
cflmy b0ee958fcf feat(ai): add explicit small-model file/class/function context pack 2026-11-18 09:32:48 +08:00
cflmy e64f6b23b4 fix(ai): use valid Marqdo branch expressions and literal main reference 2026-11-18 09:32:04 +08:00
cflmy eed4f05ea4 ci(agent): test native parser and check the new Marqdo flow modules 2026-11-18 09:31:14 +08:00
cflmy d88ed274ed feat(ai): expose short checkpoint and bounded recovery functions 2026-11-18 09:30:49 +08:00
cflmy 7fdd97f675 feat(agent): classify invalid model output and bound local recovery 2026-11-18 09:30:33 +08:00
cflmy c299efe589 feat(ai): add thin model-choice and parallel-document flow library 2026-11-18 09:30:22 +08:00
cflmy b3867c46db feat(agent): register native choice parser in plugin ABI 2026-11-18 09:30:10 +08:00
cflmy 1a39a53d93 feat(agent): add fail-closed small-model choice parser and tests 2026-11-18 09:30:03 +08:00
31 changed files with 3431 additions and 68 deletions

No files matched your search

@@ -15,6 +15,22 @@ jobs:
run: | run: |
cargo build -p marqdo_plugin_agent --locked cargo build -p marqdo_plugin_agent --locked
cargo build -p marqdo_plugin_llm --locked cargo build -p marqdo_plugin_llm --locked
- name: Native agent choice and bounded recovery unit tests
run: cargo test -p marqdo_plugin_agent --locked
- name: Check short AI flow documents
run: |
cargo run --locked -- check ext/ai/flow.mq.md
cargo run --locked -- check ext/ai/recovery.mq.md
cargo run --locked -- check ext/ai/context.mq.md
cargo run --locked -- check tests/ext/ai-native-flow.mq.md
cargo run --locked -- check ext/ai/workflow.mq.md
cargo run --locked -- check tests/ext/ai-native-workflow.mq.md
- name: Native AI flow interpreter smoke (offline)
env:
MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so
run: |
cargo run --locked -- run tests/ext/ai-native-flow.mq.md
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md
- name: Workbench contracts (M00–M06 / F-subset) - name: Workbench contracts (M00–M06 / F-subset)
run: cargo test --test workbench_contracts --locked run: cargo test --test workbench_contracts --locked
- name: Offline executable-knowledge gate - name: Offline executable-knowledge gate
+21 -5
View File
@@ -2,7 +2,15 @@
name: Extension Release name: Extension Release
on: on:
workflow_dispatch:
inputs:
version:
description: Extension version to validate
required: true
type: string
push: push:
branches:
- codex/ext-release-validation
tags: tags:
- "ext-v*" - "ext-v*"
@@ -14,6 +22,7 @@ jobs:
runs-on: windows-latest runs-on: windows-latest
env: env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GITHUB_REF_NAME_OVERRIDE: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || format('ext-v{0}', inputs.version || '2.8.1') }}
steps: steps:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
with: with:
@@ -32,17 +41,23 @@ jobs:
cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering
bash scripts/build-web-plugin.sh bash scripts/build-web-plugin.sh
- name: Build and validate the runner's exact pack bytes - name: Build and validate the runner's exact pack bytes
shell: pwsh shell: bash
run: ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.write,environment.read --fs-root . --require-ok --json run: |
set -euo pipefail
GITHUB_REF_NAME="$GITHUB_REF_NAME_OVERRIDE" ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json
- name: Attach source and Windows native packs without replacement - name: Attach source and Windows native packs without replacement
shell: pwsh if: startsWith(github.ref, 'refs/tags/ext-v')
run: ./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json shell: bash
run: |
set -euo pipefail
./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json
linux: linux:
runs-on: ubuntu-latest runs-on: ubuntu-latest
needs: windows needs: windows
env: env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GITHUB_REF_NAME_OVERRIDE: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || format('ext-v{0}', inputs.version || '2.8.1') }}
steps: steps:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
with: with:
@@ -59,6 +74,7 @@ jobs:
cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering
bash scripts/build-web-plugin.sh bash scripts/build-web-plugin.sh
- name: Build and validate the runner's exact pack bytes - name: Build and validate the runner's exact pack bytes
run: target/release/marqdo call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.write,environment.read --fs-root . --require-ok --json run: GITHUB_REF_NAME="$GITHUB_REF_NAME_OVERRIDE" target/release/marqdo call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json
- name: Attach Linux native pack without replacement - name: Attach Linux native pack without replacement
if: startsWith(github.ref, 'refs/tags/ext-v')
run: target/release/marqdo call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json run: target/release/marqdo call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json
+40
View File
@@ -0,0 +1,40 @@
name: native-ai-flow
on:
push:
branches:
- feat/native-ai-flow-recovery-20261118
pull_request:
paths:
- 'plugins/agent/**'
- 'ext/ai/flow.mq.md'
- 'ext/ai/context.mq.md'
- 'ext/ai/recovery.mq.md'
- 'ext/ai/workflow.mq.md'
- 'tests/ext/ai-native-*.mq.md'
- '.github/workflows/native-ai-flow.yml'
jobs:
agent:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- name: Build the agent plugin
run: cargo build -p marqdo_plugin_agent --locked
- name: Run native agent and workflow tests
run: cargo test -p marqdo_plugin_agent --locked
- name: Check the public Marqdo ABI libraries
run: |
cargo run --locked -- check ext/ai/flow.mq.md
cargo run --locked -- check ext/ai/context.mq.md
cargo run --locked -- check ext/ai/recovery.mq.md
cargo run --locked -- check ext/ai/workflow.mq.md
cargo run --locked -- check tests/ext/ai-native-flow.mq.md
cargo run --locked -- check tests/ext/ai-native-workflow.mq.md
- name: Exercise offline integration through Marqdo
env:
MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so
run: |
cargo run --locked -- run tests/ext/ai-native-flow.mq.md
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md
+2
View File
@@ -1,5 +1,7 @@
/target/ /target/
/dist/ /dist/
# Plugin unit tests use package-relative scratch checkpoints.
/plugins/agent/target/
# Copied by gold harness for ABI plugins # Copied by gold harness for ABI plugins
/tests/lib/demo.dll /tests/lib/demo.dll
+42
View File
@@ -2,6 +2,48 @@
## Unreleased ## Unreleased
## Ext pack v2.8.1 — 2026-11-18
### Highlights
**AI native durable workflow(CLI 仍为 v2.8.0)**:`ext/ai` 以插件侧步骤机交付持久化
工作流(`workflow`/`flow`/`context`/`recovery`),含有界模型选择、作用域上下文、
只读失败恢复、`inspect`/`list` 与可隔离 `resume_dir`。Windows 打包使用 `path.join`
根路径与 `System32\tar.exe`。详见 [双语发布说明](doc/releases/ext-2.8.1.md)。
```bash
marqdo ext add agent # CDN latest → 2.8.1
# 或:MARQDO_EXT_VERSION=2.8.1 marqdo ext add agent
```
**核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime。
### Added
- `ext/ai/workflow`:`open/next/commit/cancel/tick/retry_*`,以及只读 `inspect`/`list`
与各操作的 host-relative `resume_dir`。
- `ext/ai/flow` · `context` · `recovery`:ask/choose、作用域打包、CheckpointV2 恢复面。
- Agent ABI:`agent_workflow_*`、`agent_choice_parse`、`agent_context_scope`、
`agent_input_*`、`agent_parallel_report`。
- Offline fixtures:`tests/ext/ai-native-flow.mq.md`、`tests/ext/ai-native-workflow.mq.md`;
CI:`.github/workflows/native-ai-flow.yml`。
### Fixed
- `flow.choose` no longer leaks a branch-local `parsed` value into the function
contract; the repaired-choice path is fully scoped.
- CI builds the agent cdylib and runs offline integration without the removed
`run --effects` flag, using `MARQDO_AGENT_PLUGIN` instead.
- Atomic checkpoint/effect temp names no longer collide under parallel writes;
resume tests no longer race on process-wide cwd.
- Windows `extension-release`:engineering root 使用 `path.join` / cwd 回退;
ZIP 显式调用 `System32\tar.exe`(bsdtar);`packs.ci` 授予 `fs.read`。
### Changed
- 扩展包 SemVer **2.8.1**(`ext/VERSION`);与 CLI **v2.8.0** 可独立安装。
- 分支已合并 v2.8.0 依赖锁后的 AI 工作流增量,不再从 2.7.1 基线分叉。
## v2.8.0 — 2026-11-17 ## v2.8.0 — 2026-11-17
`marqdo prove` 正式发布:定理表 → Lean 4 证明 → 自动判定。离线符号执行(F1–F5)无工具链可用,`checked` 永远弱于 `proved`;单调性护栏让判定器缺陷显式失败;假定理给出反例见证;证书缓存与目录模式面向智能体批量出证。 `marqdo prove` 正式发布:定理表 → Lean 4 证明 → 自动判定。离线符号执行(F1–F5)无工具链可用,`checked` 永远弱于 `proved`;单调性护栏让判定器缺陷显式失败;假定理给出反例见证;证书缓存与目录模式面向智能体批量出证。
Generated
+1
View File
@@ -668,6 +668,7 @@ version = "0.1.0"
dependencies = [ dependencies = [
"chrono", "chrono",
"marqdo-plugin-sdk", "marqdo-plugin-sdk",
"pulldown-cmark",
"serde_json", "serde_json",
] ]
+5 -1
View File
@@ -117,7 +117,7 @@ marqdo view examples/procurement --no-open
Agent Skills already support scripts; Marqdo's claim is **one document-native language surface** for authoring, inspecting, executing and reusing functions. This is **not** a claim of full formal verification, zero-delay execution, or OS-level isolation of all plugin/process behavior. Agent Skills already support scripts; Marqdo's claim is **one document-native language surface** for authoring, inspecting, executing and reusing functions. This is **not** a claim of full formal verification, zero-delay execution, or OS-level isolation of all plugin/process behavior.
**Resources:** [Release v2.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/) **Resources:** [Release v2.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Ext pack 2.8.1](https://github.com/cflmy/marqdo/releases/tag/ext-v2.8.1) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/)
--- ---
@@ -128,8 +128,12 @@ Agent Skills already support scripts; Marqdo's claim is **one document-native la
当前 CLI **2.8.0** 新增 `marqdo prove`:知识文件的定理表编译为 Lean 4 并自动判定真假——没有 Lean 工具链也能离线符号执行(诚实降级,绝不冒充证明),有 Lean 时全链路证明并给出反例见证。参见[发布说明](doc/releases/v2.8.0.md)。 当前 CLI **2.8.0** 新增 `marqdo prove`:知识文件的定理表编译为 Lean 4 并自动判定真假——没有 Lean 工具链也能离线符号执行(诚实降级,绝不冒充证明),有 Lean 时全链路证明并给出反例见证。参见[发布说明](doc/releases/v2.8.0.md)。
独立拓展包 **2.8.1**(CLI 仍为 2.8.0):`ext/ai` 插件侧持久化工作流(选择 / 作用域上下文 / 只读失败恢复 / `inspect`)。`marqdo ext add agent` → CDN latest。参见[拓展包说明](doc/releases/ext-2.8.1.md)。
CLI **2.8.0** adds `marqdo prove`: theorem tables in knowledge files compile to Lean 4 and are judged automatically — offline symbolic execution without a toolchain (honest degradation, never impersonating a proof), full proofs with counterexample witnesses when Lean is available. CLI **2.8.0** adds `marqdo prove`: theorem tables in knowledge files compile to Lean 4 and are judged automatically — offline symbolic execution without a toolchain (honest degradation, never impersonating a proof), full proofs with counterexample witnesses when Lean is available.
Ext pack **2.8.1** (CLI remains 2.8.0): plugin-only durable AI workflows with bounded choice, scoped context, failed-only read-only recovery and `inspect`.
## 核心优势:可执行知识(Executable Knowledge) ## 核心优势:可执行知识(Executable Knowledge)
> **Knowledge That Can Run —— 知识即可执行。** > **Knowledge That Can Run —— 知识即可执行。**
+140
View File
@@ -0,0 +1,140 @@
# Marqdo native agent flow — implementation contract
Status: **incremental, draft**. The core orchestration now has a plugin-only
alternative to interpreter-stack suspension: a durable finite step state machine
with explicit safe commit boundaries. Do not claim arbitrary stack-level
continuation or exactly-once external writes based on a checkpoint file.
## Author surface (implemented in this branch)
| Module | Function | Contract |
|---|---|---|
| ext/ai/context.mq.md | scope | Select a bounded source excerpt using parsed Markdown headings; ambiguous names fail closed |
| ext/ai/context.mq.md | pack | Compact caller-provided file/class/function text via ContextPackV2 |
| ext/ai/flow.mq.md | ask/choose/parse_choice | One short decision, allowed-choice verification, at most one format repair |
| ext/ai/flow.mq.md | input/reply | Durable step-boundary user-input gate keyed by id + source revision and scope |
| ext/ai/flow.mq.md | start/wait/parallel | Existing Marqdo subtask scheduler, failure-preserving parallel result aggregation |
| ext/ai/flow.mq.md | enter | Resolve only author-supplied registered skill name, run via standard subtask path |
| ext/ai/recovery.mq.md | decide/save/load | Native error policy and CheckpointV2; no implicit unsafe re-execution |
| ext/ai/workflow.mq.md | open/next/commit/cancel | Durable forward-only step machine with per-step commit boundaries |
| ext/ai/workflow.mq.md | inspect/list | Read-only progress summary and checkpoint discovery scoped by session/principal |
| ext/ai/workflow.mq.md | tick/retry_plan/retry_commit/retry_failed | One-step execution and failed-only read-only recovery |
The native agent plugin provides `agent_choice_parse`, `agent_context_scope`,
`agent_input_open`, `agent_input_resume`, `agent_parallel_report`, and the
`agent_workflow_*` primitives including `inspect` and `list`.
Plugin errors must be visible, never converted into a fabricated successful answer.
All workflow wrappers accept a host-relative `resume_dir`, so tests and callers
can isolate checkpoints instead of sharing the default `.marqdo/agent-resume`.
## Invariants
- A model choice is untrusted data until verified against an explicit option list.
- An imported module is **not** automatically part of a model prompt.
- The requested heading scope, not the entire source file, is the prompt source.
- A pending user-input gate owns a persistent checkpoint, not a blocked interpreter thread.
- The same answer may be returned repeatedly; a competing answer or stale revision conflicts.
- A completed subtask wait is distinct from a successful child exit.
- Existing successful siblings remain visible when one subtask fails.
- Writes, executable effects and external writes remain under ToolSpec permissions,
the EffectLedger and source-version checks.
- No component may silently broaden a tool's authorization on failure.
## Important limitations in this branch
The input/reply gate stores an explicit **step boundary**. It does not yet persist
an arbitrary bytecode interpreter frame. Applications must choose and re-enter
their next Marqdo function explicitly after receiving a verified input answer.
The current source selector relies on a Markdown parser plus Marqdo heading
conventions, not on the compiler's resolved module/class/function AST and symbols.
Host identity inputs are supplied by the caller; production applications must
attest them from their authenticated session, never use model-generated identity.
The parallel wrapper reuses `subtask.run_many` and does not add durable child
lease orchestration. Live provider tests and real 1B-model benchmarking remain open.
## Required VM/runtime completion: suspended execution
1. Introduce `WaitingInput` as a scheduler state, distinct from terminal failure.
Save the logical run, program counter at a safe suspension boundary, bound
inputs, variable snapshot, module and tool digests, and effect watermark.
2. Resume via a new attempt linked to the original logical run, but never
automatically repeat committed effects. Preserve cancellation and budget.
3. The resume endpoint must be atomic (revision CAS), authenticate principal
and workspace, verify source and tool schema revisions, and deduplicate
repeated reply requests. Do not trust IDs inside model text.
4. Handle interrupted worker, partial snapshot, stale input, invalid choice and
unknown external write as separate outcomes. Treat unknown writes as
reconciliation-required; do not invent exactly-once guarantees.
5. Persist only serializable language values at declared safe points. If a
foreign kernel, socket or native handle is live, explicitly refuse
transparent frame recovery and preserve a safe step-level restart option.
## Required durable parallel execution
A parent dispatches child `.mq.md` functions using registered paths, grants
minimal capabilities, shares budget and rate limits, and persists a child task
manifest. Child completion records a status, value ref, output digest and ledger
watermark before the parent merges results. For same-resource writes, use
serialized revisions and explicit commit order. On parent cancellation, stop
new children and request child cancellation; do not assume remote writes rolled
back. On recovery, reconcile child attempts and reuse successful results.
## Release gates
| Test | Required observation |
|---|---|
| compiler/import check | All new `.mq.md` functions pass contract checks and execute via ABI |
| small model outputs | Exact, labeled, fenced and numeric options normalize; mixed options fail |
| input gate crash | After checkpoint, reply is committed once; alternate reply conflicts |
| source drift | Original gate cannot resume against changed source revision |
| context isolation | Class/function selectors reject ambiguity and ignore fenced headings |
| concurrent partial | Failed/uncertain child never discards successful siblings |
| unknown write | Neither retry nor recovered child duplicates an unconfirmed effect |
| long-run cancellation | Worker/child task termination preserves usable artifacts and receipts |
| compatibility | Existing `agent.step/plan/run` and workbooks remain callable |
| model evaluation | Tokens/decision, semantic validity, end-to-end completion, recovery overhead |
Do not merge the branch as a completed runtime refactor until the relevant
runtime gates, including crash injection and multi-worker concurrency, pass.
## Plugin-only workflow (November 18 revision)
The Agent ABI plugin implements
`agent_workflow_open/next/inspect/list/commit/cancel` plus the failed-only
retry primitives. The small `ext/ai/workflow.mq.md` library wraps these
primitives and provides `tick` to execute exactly one safe decision or document
task per call. `inspect` and `list` are strictly read-only: they report progress
or discover checkpoints without advancing a cursor or running a step.
Source definitions have only five step kinds: `model`, `input`, `skill`,
`parallel` and `return`. Model text is verified against declared options.
`input` intentionally returns a waiting status; the UI supplies an answer
through `commit` on a later invocation. There is no interpreter thread to
hold and no need for a separate qdagent orchestration server.
The checkpoint records the source revision, caller-provided session and
principal scope, next step index and the completed outputs. The same step
cannot be silently committed twice. Mixed child outcomes preserve completed
siblings in the checkpoint and **block** further automatic execution until
the unknown/failed child operations are reconciled.
The state engine does not execute arbitrary unregistered tools directly:
`tick` delegates to existing Marqdo ABI-backed SKILL/subtask functions.
This is an implementation of **durable step-state recovery**, not a claim
of transparent recovery for a suspended foreign function or native call.
It provides the practical workflow needed for short qdagent SKILLs without
altering the Marqdo interpreter.
### Security/reliability boundary still required for production
- The host must attest source digest, principal, session, permissions and
registry, rather than accepting values copied from an LLM response.
- Effectful child tools must use the existing EffectLedger and external
receipt reconciliation; no automatic re-dispatch after an uncertain write.
- Cancelling a workflow checkpoint does not automatically cancel previously
spawned external children; the supervisor must propagate cancellation.
- The current task runner is step-atomic, not a durable parallel child lease
scheduler. A future plugin-only child manifest may use the host's existing
`runtime` query API, but must not bypass process.exec or file-root grants.
- Cross-process locks need a lease/owner-aware stale-lock recovery path;
a stale lock currently fails closed and requires operator review.
+575
View File
@@ -0,0 +1,575 @@
我会在后续继续完成开发,接下来我比较关心marqdo的知识编译的问题,你认为我将marqdo的函数内的语句成为锚点,或者说带标记的内容都成为锚点,方便使用[]()引用,成为知识编译的一种可行吗?
**我认为完全可行,而且这可能是 Marqdo 实现“知识编译”最有价值的方向之一。**
但我建议对你的设想做一个关键调整:
> **所有可执行语句都成为编译器内部可定位的节点;所有具有明确标记的内容,都可以提升为稳定、可引用的知识锚点。**
>
> 锚点不仅用于跳转,还应该具备语义身份、依赖关系、执行能力、版本和验证状态。
这样,Marqdo 的函数就不再是一个只能整体调用的黑盒,而是一组能够逐层寻址、复用、验证和追溯的知识节点。
## **一、你的设想实际上已经有实现基础**
我重新查看了 Marqdo `main` 分支的代码,发现你的想法与仓库已有设计高度一致,并不需要从零开始。
在 [可执行知识系统设计](https://github.com/cflmy/marqdo/blob/main/doc/design/executable-knowledge-system.md?utm_source=chatgpt.com) 中,你已经提出:
- `#`:知识命名空间、类或知识实体。
- `##`:具备参数和返回契约的可复用函数。
- `[]()`:为函数内部的知识步骤命名,并保留原有执行语义。
- 编译器将命名步骤转化为 `KnowledgeStep`,关联依赖、类型、来源和效果。
更重要的是,这不只是文档构想。目前 `src/sema/ir.rs` 已经实现了 `KnowledgeRef`、`KnowledgeStep` 和 `collect_named_steps`,并且能够识别部分遮蔽表达式、函数调用、循环和正文知识引用。
不过,现在的内部步骤 ID 采用类似 `#step-1`、`#step-2` 的序号形式。这种身份适合单次编译,却不适合长期知识引用:在函数前面插入一条新步骤,就可能改变后面所有步骤的编号。
因此,我认为下一阶段的重点不是“再增加一种锚点语法”,而是:
**将已有的 KnowledgeStep 从编译期记录,升级为具备稳定身份的知识制品。**
## **二、建议采用“两级锚点体系”**
这比“把每一条语句都暴露为知识”更合理。
| 层级 | 生成规则 | 作用 |
| ------ | -------------------------- | ------------------ |
| 内部锚点 | 所有可执行 AST 语句自动生成 | 调试、数据流、执行追踪、增量编译 |
| 公共知识锚点 | `#`、`##`、带标记的表达式、显式标记的知识内容 | 跨函数引用、搜索、依赖分析、知识复用 |
例如:
```
# 订单定价
## 计算税额
根据订单地区查询税率,再计算应缴税额。
**税率 = [查询适用税率](税率库.查询(地区))**
**税额 = [计算应缴税额](金额 * 税率)**
*税额*
```
编译器可以从这段普通 Marqdo 文档中建立以下结构:
**订单定价**
Class · 知识命名空间
**计算税额**
Function · 公开可调用知识单元
**查询适用税率**
Observe / Reuse
**计算应缴税额**
Derive
数据依赖:税率 → 税额
**返回税额**
Return · 函数结果
在这个结构中,两个标记步骤各有自己的地址,并且可以独立被查询、检查来源、进行影响分析。
这和普通代码索引有根本区别:它不仅知道“这个函数在哪里”,还知道**函数为什么得到这个结果,以及结果依赖哪些知识**。
## **三、最关键的语义区分:可引用不等于可执行**
我认为这里必须制定严格的语义规范。
假设一个函数内部存在名为“查询适用税率”的锚点。
那么,其他文档引用它时,实际上存在三种不同需求:
| 操作 | 期望行为 |
| ---- | --------------------- |
| 引用知识 | 找到该步骤,读取说明、实现和出处 |
| 获取结果 | 在已知输入和执行环境中取得该步骤的计算结果 |
| 复用执行 | 重新执行该步骤,产生新的计算结果 |
**不能因为一个锚点存在,就允许它在任何地方被直接执行。**
例如,函数内部的“计算应缴税额”依赖局部变量 `金额` 和 `税率`。假如其他函数直接引用这个步骤,编译器必须确认它需要哪些输入。
有两种合理的处理方式:
- 默认只允许引用它的定义、来源和契约。
- 需要独立执行时,必须拥有完整输入绑定;否则将它提取为独立 `##` 函数。
后续可以考虑由编译器自动将满足纯度、闭包与输入条件的知识步骤提升为可调用能力。但这应是第二阶段,不能在最初就隐式执行任何锚点。
### **不必重新设计&#x20;**`[]()`**&#x20;的基本语法**
可以继续保留现有语义:
```
**税额 = [计算应缴税额](金额 * 税率)**
```
这里 `[]` 提供知识描述,`()` 保留表达式的执行含义。
另外,知识定位可以使用编译后的稳定地址,例如以下**拟议形式**:
```
[查看税率依据](mq://pricing/订单定价/计算税额#查询适用税率)
```
这应当被解释为知识引用,而不是自动重新执行“查询适用税率”。这里的 `mq://` 是建议的地址表示,不是说当前版本已经支持这样的写法。
我建议将 `KnowledgeRef` 按所在上下文分为:
- 正文:解析目标和展示证据,不产生副作用。
- 可执行表达式:按原有求值语义执行,并附带引用元数据。
- 工具或智能体调用:额外要求可调用契约、输入闭合与权限验证。
这样 `[]()` 就能成为统一引用形式,同时不破坏现有 Markdown 的可读性。
## **四、怎样让锚点稳定**
这是整个方案技术上最难、也最重要的地方。
**知识锚点不能用行号或内容哈希直接作为永久身份。**
因为代码修改时:
- 插入语句会改变行号。
- 修改公式会改变哈希,但可能仍是同一个知识概念。
- 修改描述名称不一定意味着知识实体改变。
- 两个函数可能有相同的步骤名称。
因此,建议将三个概念拆开:
| 概念 | 意义 | 变化规则 |
| ---------------- | --------- | --------- |
| `AnchorId` | 知识单元的稳定身份 | 尽量跨版本保持 |
| `ContentDigest` | 当前定义与实现 | 实现发生变化就更新 |
| `EvidenceDigest` | 来源与验证证据 | 证据变化时更新 |
对于自动生成的锚点,可以先根据模块身份、所属函数、局部名称和结构位置确定候选身份,再通过上一版编译产物中的映射记录保持身份连续。
对于需要长期跨文档引用的公共知识锚点,可以允许显式稳定 ID,或者由编译器自动登记到知识索引中。**显式 ID 不必强制写在每个&#x20;**`[]()`**&#x20;中**,这样才能保持 Marqdo 的简洁性。
如果两个同级锚点都叫“查询适用税率”,编译器必须报告歧义,要求进一步限定,不能按出现顺序选择。
## **五、知识编译的最终产物应该是什么**
我认为一个知识锚点至少需要这些字段:
```
{
"anchor_id": "pricing.tax.lookup",
"owner": "订单定价.计算税额",
"label": "查询适用税率",
"kind": "observe",
"inputs": ["地区"],
"outputs": ["税率"],
"dependencies": ["税率库.查询"],
"effects": ["read"],
"source_span": {
"file": "pricing.mq.md",
"line": 8
},
"content_digest": "...",
"evidence": [],
"verification": {
"resolved": true,
"tested": false,
"source_verified": false
}
}
```
这是一份拟议的数据结构,`anchor_id` 仅为示例。
这里还有一项值得强调的区别:**知识可以编译成功,但并不代表知识在事实上正确。**
例如读取“某地区税率”,编译器可以验证依赖、参数、数据类型、调用目标,却无法仅凭这些信息证明外部税率数据仍然有效。
所以应当把编译状态、测试状态、来源验证状态和领域正确性分别记录,而不能用一个 `verified=true` 概括所有问题。
### **推荐的编译流水线**
1\. Parse
读取 Markdown 与 Marqdo AST
2\. Anchor
为语句与标记内容建立地址和身份
3\. Resolve
绑定函数、变量、知识引用和依赖
4\. Verify
检查类型、契约、权限、来源和版本
5\. Emit
生成知识图、锚点索引、引用锁与执行制品
这基本可以落在当前 `src/sema/` 和 `src/knowledge/` 的基础上,不需要开发第二套语言执行器。特别是现有 `SemanticProject` 已能导出 `steps.json`、`refs.json` 和 `artifacts`;真正需要扩展的是步骤的稳定身份、数据依赖、引用绑定以及验证信息。
## **六、我建议下一步怎么实现**
优先做三个阶段,而不是一下将所有 Markdown 内容变成公开知识。
| 阶段 | 主要工作 | 验收 |
| ------- | ---------------------------------------- | ------------------ |
| M1:锚点身份 | 扩展 `KnowledgeStep`,建立稳定 `AnchorId` 和增量映射 | 插入其他语句后,原引用不漂移 |
| M2:锚点引用 | 扩展 `KnowledgeRef` 和语义解析,支持跨函数、跨文档的知识定位 | 能解析、检测歧义、建立反向依赖 |
| M3:知识制品 | 生成可查询的知识图、版本锁、验证与影响分析 | 改一条规则,可定位受影响的结果与叙述 |
之后再增加局部知识步骤的独立执行、缓存、自动提取为函数,以及智能体按需发现知识的能力。
## **七、这对 Marqdo 的真正价值**
我觉得这一方向比单纯强调“Markdown 可以执行”更有研究价值。
传统函数提供的是函数级抽象。你现在提出的机制则能够把抽象进一步下沉:
**文档 → 类 → 函数 → 知识步骤 → 依赖与证据。**
当智能体发现某个已有知识满足任务需求时,不需要再次生成代码,也不需要复制一段函数实现。它能够先定位知识节点,查询其契约与依据,再决定是引用现有结果、调用已有函数,还是创建新的知识。
但需要避免一个研究上的陷阱:**把语句赋予 ID 本身,不足以构成有说服力的知识编译创新。** 它仍可能被认为只是代码索引或细粒度程序分析。
真正值得验证的主张是:
> **Marqdo 能否把自然语言标记与可执行语义编译为统一、稳定、可验证的知识节点,并在知识发生改变时,自动维护其引用、依赖和可信状态?**
如果能够证明这件事,就形成了一条从可读 Markdown 到可执行知识库的清晰技术路径。
因此,我最推荐你的方案是:**函数内所有语句可定位,带标记的内容可公开引用,经过契约验证的知识节点才可独立复用执行。**
这比让所有语句无差别地成为公共锚点更严谨,也更符合 Marqdo“代码即文档,文档即知识库,知识即可执行”的设计理念。
现在的marqdo更新到了2.8.0,我觉得自动证明和上面的知识编译有关系,你怎么看,可以给我什么建议?
我认为 **Marqdo 2.8.0 的自动证明,与我们此前讨论的知识锚点和知识编译,实际上是同一技术体系中缺失的两块拼图**。
而且在重新阅读 2.8.0 的实现之后,我认为可以提出比“把代码变成知识图,再给函数附加证明”更进一步的目标:
> **将&#x20;**`.mq.md`**&#x20;编译为可寻址、可执行、可组合,并携带机器可核验证据的知识制品。**
这与 Marqdo 原来的“代码即文档,文档即知识库,知识即可执行”并不矛盾,而是让“知识”拥有了可以接受形式化检查的语义。
不过,我不建议把它直接表述为“Marqdo 自动证明知识正确”。当前 2.8.0 证明的是限定语义模型下的程序性质,而不是自然语言知识的全部真实性。
## **一、2.8.0 已经完成了哪些关键基础**
我检查了 [2.8.0 发布说明](https://github.com/cflmy/marqdo/blob/main/doc/releases/v2.8.0.md?utm_source=chatgpt.com)、`src/prove/`、`src/sema/ir.rs` 和相关测试。
| 能力 | 2.8.0 的实际情况 | 与知识编译的关系 |
| ---- | ---------------------------------------------- | ----------------- |
| 语义编译 | 已有 SemanticArtifact、KnowledgeRef、KnowledgeStep | 知识的身份与结构 |
| 自动证明 | `marqdo prove` 将定理表及函数降级为 Lean 4 | 知识的形式化约束 |
| 离线判定 | F1–F5 符号执行;`checked` 不等于 `proved` | 快速、低成本检查 |
| 证明证书 | 记录证明状态、源码与工具链哈希 | 知识的可核验证据 |
| 反例 | 部分假命题能得到路径或区间见证 | 知识修复依据 |
| 组合证明 | 同模块简单纯函数有限内联 | 已有基础,但尚未形成模块化证明体系 |
当前最值得注意的是:**语义编译器与证明编译器还没有围绕知识锚点形成完整的统一体系。**
知识编译能够生成步骤和依赖,证明编译能够生成定理和证书,但尚不能自然地表达:
“这个知识步骤依赖哪些已经证明的知识?证明依赖的知识修改后,哪些证书需要失效?调用者能否直接复用被调用知识的证明,而不必重新展开整个函数?”
我认为,这就是 Marqdo 2.9 最值得解决的问题。
## **二、从知识锚点到可证明知识图**
我建议让知识编译和证明编译共享同一套稳定的语义身份。
**Marqdo&#x20;**`.mq.md`
叙述、类、函数、`[]()`、定理表
**统一知识语义 IR**
稳定身份 · 知识锚点 · 数据依赖 · 效果 · 契约
**知识编译**
知识图、引用解析、影响分析、执行绑定
**证明编译**
Proof IR、Lean、反例、证书
**可验证知识制品**
Artifact + Contract + Proof Certificate + Dependencies
关键变化不是简单地增加几条图上的 `proved_by` 边,而是让编译器能够基于同一份语义结构,分别生成执行内容、知识引用和证明义务。
我建议采用这样的分工:
- `#`、`##` 为知识提供作用域和可调用边界。
- `[]()` 为内部知识步骤提供可读名称和可寻址身份。
- 现有契约表定义输入、输出及其他约束。
- 现有定理表表达需要成立的命题。
- `prove` 为满足证明条件的命题生成证书。
- 知识编译器关联上述信息,生成统一知识制品。
**不需要为知识证明额外发明一套 Markdown 标记。**
## **三、最值得实现的功能:证明能够沿知识引用传播**
假设有三个知识单元:
**A · 查询适用税率**
契约:根据地区和时间,返回适用税率
证明:在已声明的数据有效性条件下,返回值满足范围约束
**B · 计算税额**
依赖 A,并根据金额和税率进行计算
证明:假设 A 的契约成立,B 满足自己的计算性质
**C · 订单结算**
依赖 B,并生成最终金额
证明:在 B 的前提与其他结算条件成立时,满足结算约束
现在修改 A 的内部实现。
传统方式下,B、C 可能要重新进行大量测试,或者依赖开发者人工检查。
我希望 Marqdo 能够做到:
1. 重新编译 A,确认其契约与实现发生了哪些变化。
2. 如果 A 的实现改变,但原契约仍被新证明支持,B 可以在依赖和证明上下文未变时继续复用已有证明。
3. 如果 A 的契约不再得到支持,则 B 的相关证明变成 `stale` 或 `unverified`,并进一步影响 C。
4. 只对受影响的证明义务重新运行 Lean,而不是重新证明所有知识。
**这就让知识图成为证明依赖图,同时使证明能够参与增量知识编译。**
它与 2.8.0 当前的证书缓存有明显区别。当前缓存主要根据源码、Proof IR、库和工具链版本等生成复合键;未来应该进一步细化为:
- 某个知识锚点的实现指纹。
- 该锚点的公开契约。
- 证明依赖的其他知识及其契约指纹。
- 使用的假设和证明规则。
- Lean 内核接受的证明及其环境身份。
这样才能精确控制哪些结果可以复用。
## **四、证明不一定只属于函数,也可以属于知识步骤**
这是我认为你原先“所有带标记的内容成为锚点”构想最有价值的延伸。
2.8.0 的定理表目前属于函数级声明,位于函数首条可执行语句之前。这很合理,也应该保留为默认的公开契约。
例如:
```
# 审批
## 审批订单
| 定理 | 结论 | 前提 | 策略 |
|---|---|---|---|
| 大额必经人工 | 包含(轨迹, "人工审核") | 金额 > 10000 | auto |
1. `金额` > 10000
**回执 = [提交人工审核](人工审核(金额=`金额`))**
2. *
**回执 = [小额自动处理](自动处理(金额=`金额`))**
*回执*
```
这个示例主要展示已有的定理表与遮蔽表达式如何结合,具体调用仍需要项目中的函数定义和类型契约。
现在证明的对象主要是 `## 审批订单` 的行为性质。
我认为将来可以增加一步:
**把函数证明所涉及的知识步骤,映射到相应的锚点与依赖边。**
例如,“大额必经人工”定理可以关联到“提交人工审核”知识锚点,同时记录证明是在什么输入条件和语义模型下成立的。
但是这里必须非常严格:
- 证明整个函数满足某个性质,不意味着函数内部每个步骤都被单独证明正确。
- `[提交人工审核]` 这个自然语言标签,不能自动当成形式化命题。
- 证明轨迹包含“人工审核”,也不能证明外部审核服务真的完成了审核。
因此,**先做函数级证明向锚点的精确关联,再考虑锚点级局部证明**,会更稳妥。
## **五、建议的统一知识制品结构**
我建议在现有 `SemanticArtifact`、`KnowledgeStep`、`KnowledgeRef` 之上增加证明关联层,而不是让 `src/prove` 生成第二套互不相认的知识身份。
下面是建议结构,并非 2.8.0 已有的完整 Schema。
```
{
"anchor_id": "pricing.tax.calculate",
"symbol_id": "mq://project/pricing/function/calculate",
"kind": "derive",
"contract": {
"inputs": ["amount", "rate"],
"outputs": ["tax"]
},
"dependencies": [
"pricing.tax.lookup"
],
"verification": {
"parse": "valid",
"resolve": "valid",
"proof": {
"status": "proved",
"claims": ["tax_formula"],
"certificate": "sha256:...",
"assumptions": [],
"scope": "function"
},
"source": "unverified"
},
"hashes": {
"interface": "...",
"implementation": "...",
"proof_dependencies": "..."
}
}
```
一个很重要的设计是:`proof`**&#x20;不应该只是一个全局布尔值**。
不同知识锚点可能有不同性质:某个命题已经证明,另一个命题尚未证明,还有一个证明依赖不可靠的外部假设。
因此最小证明单元应当是:
`(AnchorId, ClaimId, Assumptions, SemanticDigest, ProofCertificate)`
而不是:
`AnchorId → proved: true`
这样调用者才能明确知道自己究竟复用了什么保证。
## **六、2.9 最应该优先实现的四项工作**
| 优先级 | 工作 | 为什么重要 |
| --- | ----------------------------------------- | -------------- |
| P0 | 统一 `SymbolId`、`AnchorId`、定理身份 | 解决知识与证明的长期稳定绑定 |
| P1 | 将证明证书关联到 SemanticArtifact / KnowledgeStep | 建立知识与证明的直接关系 |
| P2 | 跨模块 assume-guarantee 证明组合 | 使证明可以跨知识引用传播 |
| P3 | 证明依赖图与增量失效分析 | 使大型知识库不必每次全量重证 |
我尤其强调 P2。
因为从 2.8.0 发布说明可以看到,**跨模块调用目前仍视为不透明操作,而 assume-guarantee 后置条件复用明确延期到 2.9**。
这恰好是知识编译与自动证明结合的突破点。
假设 Marqdo 有两个函数:
- `A` 已经证明后置条件 \\(Q_A\\)。
- `B` 调用 `A`,希望证明自己的后置条件 \\(Q_B\\)。
那么 B 不必知道 A 的完整实现,只需要建立调用点的输入满足 A 前置条件,并利用 A 已经证明的后置条件完成自己的证明。
这正是契约组合推理的基本思路。
但证明必须明确依赖:A 的证书、其适用条件、A 与 B 的语义模型是否一致,以及任何外部假设。不能把未经验证的函数描述当作公理。
### **还需要优先修复两个证明语义边界**
2.8.0 有两项已记录的差异,我建议不要在强化知识证明时忽略:
- **i64 溢出**:解释器按有界整数处理并可能报错,而当前 Lean 模型使用无界 `Int`。
- **除零/模零**:解释器产生运行时错误,Lean 底座目前存在返回 `.int 0` 的建模差异。
这意味着证明证书必须记录实际覆盖的数值范围和语义前提。未修复或没有证明等价的部分,不能被上层知识引用当成无条件可信的计算保证。
## **七、与智能体结合后,会产生什么变化?**
这部分可能最符合你未来做科研智能体的方向。
过去智能体调用知识库时,主要依据名字、描述、检索相似度来选择已有能力。
未来可以让它先查询知识图,获得知识制品的:
- 可执行入口与输入契约。
- 形式化证明过的性质。
- 来源与版本。
- 未证明的假设和适用边界。
- 是否受到近期源码或依赖修改的影响。
于是智能体不再只是“找到一个看起来相关的 SKILL”,而是可以选择一个**在当前任务条件下,拥有足够验证依据的知识能力**。
例如,量子科研智能体在寻找电路优化方法时,可以优先寻找具有等价性证明的电路变换,而不是每次重新生成并尝试未经验证的优化。
当然,这需要专门定义量子电路语义、等价关系和可信的验证过程;现有 2.8.0 的控制流证明还不能直接证明任意量子电路等价。
## **八、研究上怎样证明这条路线有价值?**
我建议至少设计三个实验,不要只展示“Lean 可以证明 Marqdo”。
**实验 E1:知识修改与证明增量失效**
在拥有大量相互引用的知识函数的项目中,修改其中某个函数,对比全量重新证明和基于锚点依赖的增量重新证明。
指标:重新证明的命题数、证明耗时、失效检测准确率,以及错误复用证书的次数(目标为零)。
**实验 E2:跨函数与跨文档证明复用**
与 2.8.0 通过内联或不透明调用处理函数的方案相比,验证契约组合是否显著提升可证覆盖率。
指标:proved 比例、unverified/rejected 比例、证明时间、需要人工声明的假设数量。
**实验 E3:证明感知的智能体知识复用**
让相同模型完成知识检索、函数复用与程序修改任务,对比普通语义检索、只使用知识图、知识图加证明证书三种方案。
指标:错误知识复用率、任务成功率、人工审核量、输入 Token 和总执行成本。
这三个实验分别验证“知识编译”、“证明组合”和“智能体使用价值”,能够避免把三个研究主张混成一个难以检验的宏大叙事。
## **我的总体判断**
如果按照技术潜力排序,我会这样看:
| 方向 | 评价 |
| ----------------- | ---------------- |
| 给所有语句生成锚点 | 必要的基础设施,但单独创新性有限 |
| 让 `[]()` 成为稳定知识引用 | 很有价值,能形成统一知识身份 |
| 让知识锚点携带可验证契约和证书 | 更有研究深度 |
| 让证明沿知识依赖传播并支持增量复用 | 我认为是最值得集中攻关的核心 |
而且现在你拥有了一个很好的技术条件:**2.8.0 已经实现了真正的 Lean 证明路径,不再只是设计中的设想。**
我建议将 Marqdo 2.9 的主线收敛成:
**Proof-Carrying Executable Knowledge(携带证明的可执行知识)**
但需要注意,Proof-Carrying Code、契约式程序验证和模块化证明本身都是已有研究。Marqdo 真正需要体现的区别,是它如何把 Markdown 原生描述、稳定知识锚点、可执行语义、证明义务与增量知识依赖统一编译为同一个制品体系,而非仅仅给代码加上证明。
一句话总结我的建议:
**2.8.0 实现了“文档中的程序可以被证明”;2.9 应当实现“证明可以成为知识的一部分,并随着知识被引用、组合、验证和复用”。**
我认为,这比单纯继续扩展 `marqdo prove` 可支持的表达式范围,更符合 Marqdo 的长期方向。
+64
View File
@@ -0,0 +1,64 @@
# Ext pack v2.8.1 发布说明 · Release Notes(AI native flow)
## 1. 一句话
独立拓展包 **2.8.1**(CLI 仍为 **2.8.0**):`ext/ai` 交付插件侧持久化工作流——显式
`open/next/commit/cancel`、有界模型选择、作用域上下文、只读失败恢复,以及
`inspect/list` 与可隔离的 `resume_dir`。Windows `extension-release` 使用原生
`path.join` 根路径与 `C:\Windows\System32\tar.exe`(bsdtar)打包。不改解释器栈
挂起语义,也不宣称外部写的 exactly-once。
Independent extension pack **2.8.1** (CLI remains **2.8.0**): `ext/ai` ships a
plugin-only durable workflow — explicit `open/next/commit/cancel`, bounded model
choice, scoped context packing, failed-only read-only recovery, plus
`inspect/list` and isolatable `resume_dir`. Windows `extension-release` packs
with native `path.join` roots and `C:\Windows\System32\tar.exe` (bsdtar). No
interpreter-stack suspension and no exactly-once external-write claim.
## 2. 亮点(Highlights)
| | |
|---|---|
| 持久步骤机 | `plugins/agent` `workflow`:`open/next/commit/cancel/retry_*`,CheckpointV2,逐步提交边界 |
| 作者面 | `ext/ai/workflow` · `flow` · `context` · `recovery`;`tick` 单步执行,等待输入不阻塞解释器线程 |
| 选择解析 | 精确 / 编号 / 标签 / 短中英句 / JSON 信封;歧义与未知路径失败关闭 |
| 作用域上下文 | Markdown 感知的 file/class/function 摘录;歧义拒绝;不把整库 import 塞进提示 |
| 安全并行恢复 | 保留成功兄弟结果;仅重试已分类为只读的失败子任务;写/未知效应不自动派发 |
| 可观测性 | `inspect`/`list` 只读进度;测试与调用方可传入 host-relative `resume_dir` |
| Windows CI | engineering root 用 `path.join`;ZIP 用 `System32\tar.exe --format=zip` |
设计契约:[native-agent-flow-v3.md](../design/native-agent-flow-v3.md)。
## 3. 安装(Install)
```bash
marqdo ext add agent # CDN / Releases → 2.8.1
# 或:MARQDO_EXT_VERSION=2.8.1 marqdo ext add agent
marqdo ext add llm
```
产物:`marqdo-2.8.1-ext.zip` 与双平台 native ZIP(含 agent / llm 等既有原生库)。
## 4. 验证(Validation)
```bash
cargo test -p marqdo_plugin_agent --locked
cargo run --locked -- check ext/ai/flow.mq.md
cargo run --locked -- check ext/ai/context.mq.md
cargo run --locked -- check ext/ai/recovery.mq.md
cargo run --locked -- check ext/ai/workflow.mq.md
cargo run --locked -- run tests/ext/ai-native-flow.mq.md
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md
```
CI:`.github/workflows/native-ai-flow.yml` 与 `extension-release.yml`(`ext-v2.8.1`)。
## 5. 已知限制(Known limitations)
- 输入闸门保存的是**步骤边界**,不是任意字节码解释器帧;回复后须显式进入下一 Marqdo 函数。
- 作用域选择依赖 Markdown 标题约定,不是编译器已解析的 AST 符号表。
- 调用方提供的 principal/session/source revision 须由已认证宿主证明,不能来自模型文本。
- 并行复用 `subtask.run_many`;跨进程子任务租约与已在跑外部进程的取消传播仍待专项注入验证。
- 实时大模型与目标 1B 本地模型评测仍开放;写效应自动重试仍被拒绝,直至 EffectLedger 对账完成。
**核心表面 Δ**:无增删——19 个核心构造不变;本包为 Extension / Agent Runtime。
+1 -1
View File
@@ -1 +1 @@
2.7.0 2.8.1
+113
View File
@@ -0,0 +1,113 @@
---
markup: occlusion
title: AI context — short, explicit source scopes
description: Pack user input and caller-provided file/class/function excerpts.
import:
agent: ext/ai/agent.mq.md
plugin: lib/plugin.mq.md
json: lib/json.mq.md
---
Pass only the documentation that the next model decision needs. The supplied
file/class/function snippets are data; they do not execute as Marqdo source.
A future compiler-backed selector can supply these arguments from AST spans.
This helper does not yet infer class/function scopes automatically.
## pack
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| user | text | required | Latest user input |
| file | text | "" | File-level description excerpt |
| class | text | "" | Current class excerpt |
| function | text | "" | Current function excerpt |
| budget_tokens | number | 2048 | Small-model context budget |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Bounded ContextPackV2 and compaction evidence |
Use `user`, `file`="", `class`="", `function`="", `budget_tokens`=2048 as the inputs for this operation.
Keep the latest request and current function first. Low-priority file context
may be dropped under pressure; any important constraint must be in a retained
field, not in a discardable tool transcript.
`items` =
| @ | origin | trust | priority | text | retain |
|---|---|---|---|---|---|
| 1 | user | user | 0 | `user` | True |
| 2 | function | unknown | 1 | `function` | True |
| 3 | class | unknown | 2 | `class` | False |
| 4 | file | unknown | 3 | `file` | False |
Return *[Pack the supplied scopes and compact redundant context](agent.context_pack_compact(items=`items`, budget_tokens=`budget_tokens`, goal=`user`))*.
## scope
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| scope | text | "function" | file / class / function / tool |
| class | text | None | Class heading for disambiguation |
| function | text | None | Function/tool heading |
| source | text | None | Source override; otherwise current entry module |
| max_chars | number | 1600 | Maximum Unicode characters |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Exact source excerpt, line range, or explicit ambiguity |
Use `scope`="function", `class`=None, `function`=None, `source`=None, `max_chars`=1600 as the inputs for this operation.
The native selector respects Markdown headings and ignores fenced-code heading
lookalikes. Repeated function names require a class; missing/ambiguous scopes
return an error value, never an unrelated or whole-file fallback.
We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load native agent plugin](plugin.load(path=`p`))**.
2. *
Return *[No native parser available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\",\"text\":null}"))*.
Return *[Project the requested document scope](agent_context_scope(source=`source`, scope=`scope`, class=`class`, function=`function`, max_chars=`max_chars`))*.
## compose
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| user | text | required | Latest user input |
| class | text | required | Current class name |
| function | text | required | Current function name |
| source | text | None | Override current entry source |
| budget_tokens | number | 2048 | Small-model context budget |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | ContextPackV2 or an explicit failed selector |
Use `user`, `class`, `function`, `source`=None, `budget_tokens`=2048 as the inputs for this operation.
Project file, class and function scopes independently. Refuse ambiguous names
rather than silently importing an unrelated class or the entire source. The
latest user input stays in the retained portion of the resulting context pack.
We retain **f = [Select file preface](scope(scope="file", source=`source`, max_chars=500))**.
We retain **c = [Select current class](scope(scope="class", class=`class`, source=`source`, max_chars=800))**.
We retain **n = [Select current function](scope(scope="function", class=`class`, function=`function`, source=`source`, max_chars=1500))**.
We retain **f_ok = [Check file selection](json.get(value=`f`, key="ok"))**.
We retain **c_ok = [Check class selection](json.get(value=`c`, key="ok"))**.
We retain **n_ok = [Check function selection](json.get(value=`n`, key="ok"))**.
1. not `f_ok`
Return *f*.
2. not `c_ok`
Return *c*.
3. not `n_ok`
Return *n*.
4. *
We retain **ft = [Read file preface](json.get(value=`f`, key="text"))**.
We retain **ct = [Read class explanation](json.get(value=`c`, key="text"))**.
We retain **nt = [Read function explanation](json.get(value=`n`, key="text"))**.
Return *[Compact only the selected scopes](pack(user=`user`, file=`ft`, class=`ct`, function=`nt`, budget_tokens=`budget_tokens`))*.
+246
View File
@@ -0,0 +1,246 @@
---
markup: occlusion
title: AI flow — small-model choices and bounded subtasks
description: Short model decisions, verified options and concurrent Marqdo documents.
import:
llm: ext/ai/llm.mq.md
json: lib/json.mq.md
plugin: lib/plugin.mq.md
subtask: lib/subtask.mq.md
---
This is the thin author-facing layer. A model returns a candidate; Marqdo checks
it before routing. Invalid choices are not SKILL paths and never execute.
Only the requested function and its inputs need to be in the model prompt.
## parse_choice
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| reply | text | required | Raw model reply, treated as data |
| options | list | required | Allowed names, not paths or commands |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | {ok,value,status} or {ok:false,error} |
Use `reply`, `options` as the inputs for this operation.
Parsing accepts one exact name, a labeled name, a fenced name or a 1-based
index. Ambiguous prose fails closed. Parsing never runs a tool or SKILL.
We retain **p = [Locate the installed agent plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load the agent plugin](plugin.load(path=`p`))**.
2. *
Return *[Missing native parser](json.parse(text="{\"ok\":false,\"status\":\"unavailable\",\"value\":null}"))*.
Return *[Parse and verify the choice](agent_choice_parse(reply=`reply`, options=`options`))*.
## choose
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| input | text | required | Current user request or local decision |
| options | list | required | Small list of registered option names |
| model | any | None | Existing provider model identifier |
| repair | bool | True | Allow one format-only repair attempt |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Verified choice result, or explicit failure |
Use `input`, `options`, `model`=None, `repair`=True as the inputs for this operation.
Only ask for the option name. A failed first parse can receive one short
format correction; never silently select the nearest-looking option.
We retain **opts = [Encode allowed values](json.stringify(value=`options`))**.
We retain **prompt = "Choose exactly one of these options. Return its name only, no explanation:\n" + opts + "\nInput:\n" + input**.
We retain **m = [Build one model handle](llm.create(model=`model`))**.
We retain **turn = [Ask the model once](m.ask(prompt=`prompt`))**.
We retain **err = [Check model transport error](json.get(value=`turn`, key="error"))**.
1. `err`
Return *turn*.
2. *
We retain **reply = [Read model answer](json.get(value=`turn`, key="text"))**.
We retain **parsed = [Validate the model reply](parse_choice(reply=`reply`, options=`options`))**.
We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**.
1. `ok`
Return *parsed*.
2. `repair`
We retain **fix = "Your answer was not an exact allowed option. Return only ONE option name from:\n" + opts**.
We retain **fixed = [Retry the format only once](m.ask(prompt=`fix`))**.
We retain **repair_error = [Read transport error](json.get(value=`fixed`, key="error"))**.
1. `repair_error`
Return *fixed*.
2. *
We retain **again = [Read corrected answer](json.get(value=`fixed`, key="text"))**.
Return *[Validate the repaired reply](parse_choice(reply=`again`, options=`options`))*.
3. *
Return *parsed*.
## parallel
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| tasks | list | required | Existing .mq.md file tasks with arguments |
| limit | number | 2 | Maximum simultaneously running tasks |
| timeout_ms | number | 30000 | Execution timeout in milliseconds |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Succeeded, partial, failed or uncertain child outcomes |
Use `tasks`, `limit`=2, `timeout_ms`=30000 as the inputs for this operation.
Reuse the built-in subtask scheduler. Each child document returns via its
`# main`, and successful siblings remain visible if another child fails.
We retain **results = [Run bounded Marqdo document tasks](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))**.
We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load native agent plugin](plugin.load(path=`p`))**.
Return *[Preserve success, failure and uncertain child outcomes](agent_parallel_report(results=`results`))*.
2. *
Return *[Native result classifier unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## input
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable step ID |
| question | text | required | User-visible question |
| options | list | required | User-visible choices |
| source_revision | text | required | Pinned Marqdo source revision |
| session_id | text | None | Host-attested session |
| principal_ref | text | None | Host-attested user scope |
| freeform | bool | True | Allow custom user reply |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | waiting_input or previously committed reply |
Use `id`, `question`, `options`, `source_revision`, `session_id`=None, `principal_ref`=None, `freeform`=True as the inputs for this operation.
This does not park an interpreter stack. The caller persists a step-boundary
checkpoint, displays the question, and on a new turn uses reply to continue.
The host, not the LLM, must attest session and principal IDs.
We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load native agent plugin](plugin.load(path=`p`))**.
2. *
Return *[No native gate available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
Return *[Persist one waiting input gate](agent_input_open(id=`id`, question=`question`, options=`options`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, freeform=`freeform`))*.
## reply
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Existing waiting step |
| reply | text | required | New user response |
| source_revision | text | required | Current pinned source revision |
| session_id | text | None | Host-attested session |
| principal_ref | text | None | Host-attested user scope |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Resolved answer, invalid reply or explicit conflict |
Use `id`, `reply`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation.
Matching repeated replies are idempotent. A conflicting reply, changed document
or changed session fails without executing any SKILL or side effect.
We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load native agent plugin](plugin.load(path=`p`))**.
2. *
Return *[No native gate available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
Return *[Commit the verified user reply](agent_input_resume(id=`id`, reply=`reply`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*.
## enter
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| skill | text | required | Model-selected registered name |
| registry | map | required | Trusted name → path mapping |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Subtask result, or blocked unknown skill |
Use `skill`, `registry` as the inputs for this operation.
Never execute a raw model-generated path. Resolve a registered skill name to
an author-controlled document, then call its `# main` through the normal Marqdo
subtask and effect permissions. The caller must provide a trusted registry.
We retain **path = [Resolve registered SKILL](json.get(value=`registry`, key=`skill`))**.
1. not `path`
Return *[Unknown skill is blocked](json.parse(text="{\"ok\":false,\"status\":\"unsupported_skill\"}"))*.
2. *
We retain **task = [Spawn registered Marqdo document](subtask.spawn(path=`path`))**.
Return *[Await the subtask result](subtask.wait(id=`task`))*.
## ask
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | text | required | Short local prompt |
| model | any | None | Configured model selection |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | Model reply (not yet a verified tool call) |
Use `prompt`, `model`=None as the inputs for this operation.
Ask only what the current function needs. The reply remains data until an
explicit verifier accepts it. The LLM adapter owns provider configuration.
Return *[Ask the configured model](llm.ask(prompt=`prompt`, model=`model`))*.
## start
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Trusted registered Marqdo document |
| args | list | None | Optional child CLI arguments |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Child task handle |
Use `path`, `args`=None as the inputs for this operation.
Start an isolated SKILL document asynchronously, after the calling host has
validated its path and required process.exec permission. No model-generated
raw path is a valid grant.
Return *[Start one Marqdo document](subtask.spawn(path=`path`, args=`args`))*.
## wait
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | number | required | Child task handle |
| timeout_ms | number | 30000 | Maximum wait time |
| cancel | bool | False | Cancel on timeout |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Child result, timeout or cancellation |
Use `id`, `timeout_ms`=30000, `cancel`=False as the inputs for this operation.
A successful wait protocol is not proof of a successful child execution:
inspect the child exit code before using its result.
Return *[Wait for the child](subtask.wait_timeout(id=`id`, timeout_ms=`timeout_ms`, cancel=`cancel`))*.
+7 -1
View File
@@ -9,7 +9,13 @@ Start here to choose an AI task. [Model calls](llm.mq.md) own prompts, model con
stream collection and usage; [provider adapters](llm/index.mq.md) describe OpenAI-compatible stream collection and usage; [provider adapters](llm/index.mq.md) describe OpenAI-compatible
and Ollama requests. [Agents](agent.mq.md) own call-site context, the explicit tool registry, and Ollama requests. [Agents](agent.mq.md) own call-site context, the explicit tool registry,
policy routing, observations, workbook planning and continuation. [CoW trials](sandbox.mq.md) policy routing, observations, workbook planning and continuation. [CoW trials](sandbox.mq.md)
own isolated file changes and promotion. [Step routing](policies/step-route.mq.md) is readable own isolated file changes and promotion. [Native flow](flow.mq.md) provides short, verified model choices and bounded document
concurrency; [workflow](workflow.mq.md) drives a durable forward-only step plan with
`inspect`/`list` progress queries and failed-only read recovery; [context](context.mq.md)
packs explicit source scopes; [recovery](recovery.mq.md)
uses the native error policy and versioned checkpoints. These are lightweight
interfaces, not a second agent runtime.
[Step routing](policies/step-route.mq.md) is readable
policy data, not a second agent language. Chinese users can start at [索引](索引.mq.md). policy data, not a second agent language. Chinese users can start at [索引](索引.mq.md).
Begin with this offline stream example; it does not request credentials, install a plugin or Begin with this offline stream example; it does not request credentials, install a plugin or
+70
View File
@@ -0,0 +1,70 @@
---
markup: occlusion
title: AI recovery — safe defaults for short SKILL functions
description: Reuse the native error policy, durable checkpoints and effect ledger.
import:
agent: ext/ai/agent.mq.md
---
Error handling belongs to Marqdo, not the model's prompt. The native policy
never blindly repeats uncertain writes. Every resume must revalidate the
current permission and source revision; a saved checkpoint is not authorization.
## decide
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| error | map | required | Structured AgentErrorV1 |
| attempts | number | 0 | Number of attempts already made |
| effect_class | text | "read" | Declared tool effect |
| cancelled | bool | False | Parent cancellation status |
| fingerprint_repeats | number | 0 | Identical failures without new evidence |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Safe recovery action with budget |
Use `error`, `attempts`=0, `effect_class`="read", `cancelled`=False, `fingerprint_repeats`=0 as the inputs for this operation.
This returns an action, not an automatic retry or permission to execute. For
write or unknown effect, consult the effect ledger before taking another step.
Return *[Select a bounded recovery action](agent.error_decide_retry(error=`error`, attempts=`attempts`, effect_class=`effect_class`, cancelled=`cancelled`, fingerprint_repeats=`fingerprint_repeats`))*.
## save
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable logical run ID |
| task | any | None | Current task or user request |
| status | text | "waiting_input" | Current run status |
| effect_ledger_watermark | any | None | Durable ledger boundary if available |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | CheckpointV2 write result |
Use `id`, `task`=None, `status`="waiting_input", `effect_ledger_watermark`=None as the inputs for this operation.
Use the existing atomic checkpoint writer. When ledger evidence is absent,
a resumed writer requires manual review rather than automatic repetition.
This function saves metadata; it does not suspend a Rust execution frame.
Return *[Save a versioned checkpoint](agent.resume_save(id=`id`, task=`task`, status=`status`, checkpoint_v2=True, effect_ledger_watermark=`effect_ledger_watermark`))*.
## load
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Previously saved logical run ID |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Checkpoint or missing/unsafe recovery status |
Use `id` as the inputs for this operation.
Loading a checkpoint does not execute any saved step. The caller must inspect
recovery_mode and write_auto_resume before dispatching any effectful operation.
Return *[Inspect the saved checkpoint](agent.resume_load(id=`id`))*.
+330
View File
@@ -0,0 +1,330 @@
---
markup: occlusion
title: Native AI workflow — durable, short, one-step-at-a-time execution
description: Plugin-managed checkpointed decision flow without an external agent runtime.
import:
plugin: lib/plugin.mq.md
json: lib/json.mq.md
flow: ext/ai/flow.mq.md
subtask: lib/subtask.mq.md
---
Every step is an explicit commit boundary. The plugin stores accepted outputs,
refuses stale documents and conflicting decisions, and exposes the next action.
The caller must supply trusted session, principal and source revision fields;
model text is never an identity or permission token. `resume_dir` is a
host-relative checkpoint directory, never an absolute client path.
## open
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable run ID |
| steps | list | required | 1–128 ordered step records |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Created, resumed, or explicit conflict |
Use `id`, `steps`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Opening the same ID with the same steps, source revision, session and principal
returns the current action instead of resetting progress. Reusing an ID with a
different plan or identity fails closed.
We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Open durable workflow](agent_workflow_open(id=`id`, steps=`steps`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## next
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable run ID |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Current action or terminal state |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
`next` is read-only: it does not call a model, run a child document or consume
the current step. Stopped states (`blocked`, `uncertain`, `cancelled`) and
unclassified child effects are reported explicitly.
We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Find the next committed boundary](agent_workflow_next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## inspect
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable run ID |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Progress summary with cursor, step and partial results |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Use inspect for a UI progress panel or an operator audit. It returns the
durable checkpoint `status`, the next `action` (for example `waiting_model`),
cursor, total and completed step counts, the current step, and retained partial
child results without advancing the workflow.
We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Read workflow progress](agent_workflow_inspect(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## list
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| session_id | text | None | Trusted session filter |
| principal_ref | text | None | Trusted principal filter |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Workflow summaries, newest metadata included separately |
Use `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Only native workflow checkpoints are listed; unrelated resume records and
corrupt files are omitted. Pass host-attested filters to keep one session or
principal from seeing another's run identifiers.
We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[List workflow checkpoints](agent_workflow_list(session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## commit
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable run ID |
| step_id | text | required | Exact current step |
| response | any | required | Completed step output |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Committed next step or explicit failure |
Use `id`, `step_id`, `response`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
A completed step cannot be committed twice. Replaying the same value returns
the already-committed result; a different value for the same step conflicts.
We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Validate and commit one step](agent_workflow_commit(id=`id`, step_id=`step_id`, response=`response`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## cancel
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable run ID |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Cancelled checkpoint status |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Cancelling prevents future commits. It does not claim that children already
started by the supervisor were rolled back.
We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Commit cancellation](agent_workflow_cancel(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## tick
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Running workflow |
| source_revision | text | required | Pinned source revision |
| registry | map | None | Trusted SKILL registry |
| model | any | None | Configured LLM |
| session_id | text | None | Host-attested session |
| principal_ref | text | None | Host-attested principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | New checkpoint state, or waiting_input for the UI |
Use `id`, `source_revision`, `registry`=None, `model`=None, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Advance at most one step. Model text is a candidate, never direct
execution. Waiting for a user returns immediately without holding a thread.
A caller repeats tick after verified completion; UI replies use commit.
`tick` is the only wrapper that may execute a document child, and it only does
so after the checkpoint reports a read-only `ready_tool` step. When the action
is `waiting_input`, return the state unchanged so the host can display the
question and commit the attested answer on a later call. A blocked, uncertain
or cancelled checkpoint is returned as-is; recovery must use `retry_plan` or an
operator decision instead of silently ticking again. The returned state always
describes the committed boundary, not an optimistic guess about a running
child.
We retain **state = [Load the next action](next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))**.
We retain **status = [Read action status](json.get(value=`state`, key="status"))**.
1. `status` == "waiting_model"
We retain **step = [Read model step](json.get(value=`state`, key="step"))**.
We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**.
We retain **prompt = [Read local prompt](json.get(value=`step`, key="prompt"))**.
We retain **options = [Read allowed decisions](json.get(value=`step`, key="options"))**.
We retain **answer = [Make a bounded choice](flow.choose(input=`prompt`, options=`options`, model=`model`))**.
We retain **valid = [Check model decision](json.get(value=`answer`, key="ok"))**.
1. `valid`
We retain **chosen = [Read verified model answer](json.get(value=`answer`, key="value"))**.
Return *[Commit the model choice](commit(id=`id`, step_id=`step_id`, response=`chosen`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *answer*.
2. `status` == "ready_tool"
We retain **step = [Read tool step](json.get(value=`state`, key="step"))**.
We retain **kind = [Read operation kind](json.get(value=`step`, key="kind"))**.
We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**.
1. `kind` == "parallel"
We retain **tasks = [Read child tasks](json.get(value=`step`, key="tasks"))**.
We retain **report = [Run bounded parallel documents](flow.parallel(tasks=`tasks`))**.
Return *[Commit all child outcomes](commit(id=`id`, step_id=`step_id`, response=`report`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. `kind` == "skill"
We retain **name = [Read registered skill name](json.get(value=`step`, key="skill"))**.
We retain **out = [Run registered SKILL only](flow.enter(skill=`name`, registry=`registry`))**.
Return *[Commit verified child result](commit(id=`id`, step_id=`step_id`, response=`out`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
3. *
Return *state*.
3. `status` == "ready_return"
We retain **step = [Read return step](json.get(value=`state`, key="step"))**.
We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**.
We retain **value = [Read final value](json.get(value=`step`, key="value"))**.
Return *[Commit the completed workflow](commit(id=`id`, step_id=`step_id`, response=`value`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
4. *
Return *state*.
## retry_plan
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Blocked workflow ID |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Failed-only read-task list or manual_review |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Only a parallel step explicitly declared read-only and with no uncertain
effects may return a retry plan. Completed siblings are not included.
We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Select failed read-only children](agent_workflow_retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Native plugin unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## retry_commit
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Blocked workflow ID |
| results | list | required | New outcomes for failed children only |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Merged persistent report, or still blocked |
Use `id`, `results`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Re-use successful child results from the checkpoint. New results fill failed
slots only, in original order; a newly uncertain outcome blocks further work.
We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Merge verified read-only retries](agent_workflow_retry_commit(id=`id`, results=`results`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Native plugin unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## retry_failed
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Blocked workflow ID |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| limit | number | 2 | Max concurrent failed children |
| timeout_ms | number | 30000 | Child timeout |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Recovered workflow, partial results or manual review |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `limit`=2, `timeout_ms`=30000, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Run only the failed read-only tasks returned by the native checkpoint checker.
Unknown external writes never reach this path.
We retain **plan = [Inspect safe retry manifest](retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))**.
We retain **can_retry = [Check permitted recovery](json.get(value=`plan`, key="ok"))**.
1. `can_retry`
We retain **tasks = [Read failed-only children](json.get(value=`plan`, key="tasks"))**.
We retain **outcomes = [Execute failed read-only children only](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))**.
Return *[Merge with preserved completed children](retry_commit(id=`id`, results=`outcomes`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *plan*.
+1 -1
View File
@@ -71,7 +71,7 @@ authentication is resolved inside the plugin from existing stores.
We **loaded = [Load this package's native boundary](_load())** and We **loaded = [Load this package's native boundary](_load())** and
**base = [Read the granted runtime working root](sys.cwd())** and **resolved_root = root**. **base = [Read the granted runtime working root](sys.cwd())** and **resolved_root = root**.
1. not [The requested root is already absolute](paths.is_absolute(path=`root`)) 1. not [The requested root is already absolute](paths.is_absolute(path=`root`))
We **resolved_root = base + "/" + root** so process and native filesystem locations agree. We **resolved_root = [Join the runtime cwd with the relative grant](paths.join(a=`base`, b=`root`))** so Windows and Unix separators stay native.
`request_data` = `request_data` =
+1
View File
@@ -13,4 +13,5 @@ crate-type = ["cdylib"]
[dependencies] [dependencies]
marqdo-plugin-sdk = { path = "../../crates/marqdo-plugin-sdk" } marqdo-plugin-sdk = { path = "../../crates/marqdo-plugin-sdk" }
serde_json = "1" serde_json = "1"
pulldown-cmark = "0.12"
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] } chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
+197
View File
@@ -0,0 +1,197 @@
//! Fail-closed choice parsing for small-model routing.
//! This module only extracts a value; it never resolves or executes a SKILL.
use serde_json::{json, Value};
fn canonical(s: &str) -> String {
s.trim()
.trim_matches(|c: char| matches!(c, '"' | '\'' | '`' | '“' | '”' | '‘' | '’'))
.trim()
.to_lowercase()
}
fn strip_fence(s: &str) -> &str {
let s = s.trim();
if !s.starts_with("```") {
return s;
}
let Some(start) = s.find('\n') else {
return s;
};
let body = &s[start + 1..];
let Some(end) = body.find("```") else {
return s;
};
if !body[end + 3..].trim().is_empty() {
return s;
}
body[..end].trim()
}
fn strip_label(s: &str) -> &str {
let s = s.trim();
let Some((head, tail)) = s.split_once([':', ':']) else {
return s;
};
if matches!(
head.trim().to_lowercase().as_str(),
"choice" | "option" | "selected" | "选择" | "选项" | "答案"
) {
tail.trim()
} else {
s
}
}
fn structured_reply(raw: &str) -> Option<String> {
let parsed: Value = serde_json::from_str(raw).ok()?;
if let Some(s) = parsed.as_str() {
return Some(s.to_string());
}
if let Some(list) = parsed.as_array() {
if list.len() == 1 {
return list[0].as_str().map(str::to_string);
}
return None;
}
let map = parsed.as_object()?;
// Refuse conflicting structured decisions instead of choosing first.
let values: Vec<&str> = ["choice", "selected", "option", "选择"]
.iter()
.filter_map(|key| map.get(*key).and_then(Value::as_str))
.collect();
if values.is_empty() || values.iter().any(|s| *s != values[0]) {
return None;
}
Some(values[0].to_string())
}
fn single_choice(options: &[String], reply: &str) -> Option<String> {
let raw = strip_label(strip_fence(reply));
// Structured single-choice replies are accepted only through known fields,
// and then still validated against the caller's exact allowlist.
let decoded = structured_reply(raw);
let raw = decoded.as_deref().unwrap_or(raw);
// Small models often prepend a short selection verb. Accept only the
// verb followed by a complete allowed value; explanations stay invalid.
let raw = raw.trim();
let raw = ["我选择", "我选", "I choose ", "I pick ", "选中"].iter()
.find_map(|p| raw.strip_prefix(p).map(str::trim))
.unwrap_or(raw);
let value = canonical(raw);
// Never infer a routing decision from arbitrary prose.
let matches: Vec<&String> = options
.iter()
.filter(|opt| canonical(opt) == value)
.collect();
if matches.len() == 1 {
return Some(matches[0].clone());
}
// A bare number denotes a 1-based index into the allowed list.
if let Ok(index) = value.parse::<usize>() {
if index > 0 && index <= options.len() {
return Some(options[index - 1].clone());
}
}
None
}
/// Parse one permitted option from a small model response.
/// Returns a status rather than treating arbitrary prose as a tool target.
pub fn parse_choice(args: &Value) -> Result<Value, String> {
let reply = args
.get("reply")
.and_then(Value::as_str)
.ok_or_else(|| "missing text `reply`".to_string())?;
let options = args
.get("options")
.and_then(Value::as_array)
.ok_or_else(|| "options must be an array of strings".to_string())?;
if options.is_empty() || options.len() > 64 {
return Err("options must contain 1..=64 entries".to_string());
}
let mut allowed = Vec::with_capacity(options.len());
for option in options {
let name = option
.as_str()
.ok_or_else(|| "each option must be a string".to_string())?;
if name.trim().is_empty() || name.len() > 128 {
return Err("each option must contain 1..=128 UTF-8 bytes".to_string());
}
if allowed.iter().any(|p: &String| canonical(p) == canonical(name)) {
return Err("options must be unique after normalization".to_string());
}
allowed.push(name.to_string());
}
if let Some(value) = single_choice(&allowed, reply) {
Ok(json!({"ok": true, "value": value, "status": "accepted"}))
} else {
Ok(json!({
"ok": false,
"value": null,
"status": "invalid",
"error": {
"code": "model.invalid_choice",
"category": "invalid_output",
"retryable": false,
"recovery_action": "repair_output"
}
}))
}
}
#[cfg(test)]
mod tests {
use super::*;
fn check(reply: &str) -> Value {
parse_choice(&json!({"options": ["chat", "office"], "reply": reply})).unwrap()
}
#[test]
fn accepts_exact_label_fence_and_number() {
assert_eq!(check("chat")["value"], "chat");
assert_eq!(check(" CHAT ")["value"], "chat");
assert_eq!(check("选择:office")["value"], "office");
assert_eq!(check("```text\nchat\n```")["value"], "chat");
assert_eq!(check("2")["value"], "office");
assert_eq!(check("我选择 chat")["value"], "chat");
assert_eq!(check("I choose office")["value"], "office");
assert_eq!(check(r#"{"choice":"chat"}"#)["value"], "chat");
assert_eq!(check("[\"office\"]")["value"], "office");
assert_eq!(check("```json\n{\"selected\":\"office\"}\n```")["value"], "office");
}
#[test]
fn refuses_prose_conflicts_and_out_of_range() {
for reply in ["请选择 chat", "chat 或 office", "choice: chat,因为更合适", "3", ""] {
let result = check(reply);
assert_eq!(result["ok"], false, "accepted {reply:?}");
assert_eq!(result["value"], Value::Null);
}
}
#[test]
fn refuses_conflicting_structured_decisions() {
assert_eq!(check(r#"{"choice":"chat","option":"office"}"#)["ok"], false);
assert_eq!(check(r#"{"choice":"../private.mq.md"}"#)["ok"], false);
assert_eq!(check(r#"["chat","office"]"#)["ok"], false);
}
#[test]
fn rejects_invalid_options_before_parsing() {
for options in [
json!([]),
json!(["chat", "CHAT"]),
json!(["chat", 10]),
json!([""]),
] {
assert!(parse_choice(&json!({"options": options, "reply": "chat"})).is_err());
}
}
#[test]
fn never_extracts_arbitrary_skill_path() {
assert_eq!(check("../../private.mq.md")["ok"], false);
}
}
+207
View File
@@ -0,0 +1,207 @@
//! Markdown-heading-backed, bounded context projection for Marqdo SKILLs.
//! This is source selection, not execution: quoted text never becomes tool authority.
//! Markdown events ignore fenced-code headings; ambiguous functions fail closed.
use pulldown_cmark::{Event, HeadingLevel, Parser, Tag, TagEnd};
use serde_json::{json, Value};
#[derive(Clone, Debug)]
struct Section {
level: u8,
title: String,
start: usize,
}
fn level_num(h: HeadingLevel) -> u8 {
match h {
HeadingLevel::H1 => 1,
HeadingLevel::H2 => 2,
HeadingLevel::H3 => 3,
HeadingLevel::H4 => 4,
HeadingLevel::H5 => 5,
HeadingLevel::H6 => 6,
}
}
fn headings(source: &str) -> Vec<Section> {
let mut out = Vec::new();
let mut pending: Option<Section> = None;
for (event, range) in Parser::new(source).into_offset_iter() {
match event {
Event::Start(Tag::Heading { level, .. }) => {
pending = Some(Section {
level: level_num(level),
title: String::new(),
start: range.start,
});
}
Event::Text(text) | Event::Code(text) => {
if let Some(section) = pending.as_mut() {
section.title.push_str(&text);
}
}
Event::End(TagEnd::Heading(_)) => {
if let Some(mut section) = pending.take() {
section.title = section.title.trim().to_string();
out.push(section);
}
}
_ => {}
}
}
out
}
fn class_for(headings: &[Section], index: usize) -> Option<&str> {
headings[..index]
.iter()
.rev()
.find(|h| h.level == 1)
.map(|h| h.title.as_str())
}
fn frontmatter_end(source: &str) -> usize {
if !source.starts_with("---\n") {
return 0;
}
let mut pos = 4;
for line in source[4..].split_inclusive('\n') {
pos += line.len();
if line.trim() == "---" {
return pos;
}
}
0
}
fn truncate_chars(text: &str, max_chars: usize) -> (&str, bool) {
let Some((end, _)) = text.char_indices().nth(max_chars) else {
return (text, false);
};
(&text[..end], true)
}
pub fn project(args: &Value) -> Result<Value, String> {
let source = match args.get("source").and_then(Value::as_str) {
Some(s) => s.to_string(),
None => crate::host_query_json("module_source")?
.as_str()
.ok_or_else(|| "module_source unavailable".to_string())?
.to_string(),
};
let scope = args.get("scope").and_then(Value::as_str).unwrap_or("function");
let class = args.get("class").and_then(Value::as_str);
let function = args.get("function").and_then(Value::as_str);
let maximum = args
.get("max_chars")
.and_then(Value::as_u64)
.unwrap_or(1600)
.clamp(32, 16000) as usize;
// YAML frontmatter may look like a setext Markdown heading; never treat it
// as a Marqdo class or function boundary.
let front_end = frontmatter_end(&source);
let marks: Vec<Section> = headings(&source)
.into_iter()
.filter(|heading| heading.start >= front_end)
.collect();
let results: Vec<(usize, usize)> = match scope {
"file" => {
let end = marks.first().map_or(source.len(), |h| h.start);
let start = frontmatter_end(&source).min(end);
vec![(start, end)]
}
"class" | "function" | "tool" => {
let level = match scope {
"class" => 1,
"function" => 2,
_ => 3,
};
let target = if level == 1 { class } else { function };
let wanted = target.ok_or_else(|| format!("{scope} selector required"))?;
marks
.iter()
.enumerate()
.filter(|(i, h)| {
h.level == level
&& h.title == wanted
&& (level == 1 || class.is_none() || class_for(&marks, *i) == class)
})
.map(|(i, h)| {
let end = marks[i + 1..]
.iter()
.find(|next| next.level <= level)
.map_or(source.len(), |next| next.start);
let end = if level == 1 {
marks[i + 1..]
.iter()
.find(|next| next.level <= 2)
.map_or(end, |next| next.start)
} else {
end
};
(h.start, end)
})
.collect()
}
_ => return Err("scope must be file, class, function or tool".to_string()),
};
if results.len() != 1 {
return Ok(json!({
"ok": false,
"status": if results.is_empty() { "not_found" } else { "ambiguous" },
"scope": scope,
"matches": results.len(),
"text": null
}));
}
let (start, end) = results[0];
let (slice, truncated) = truncate_chars(source[start..end].trim(), maximum);
let line_start = source[..start].bytes().filter(|c| *c == b'\n').count() + 1;
Ok(json!({
"ok": true, "status": "accepted", "scope": scope,
"text": slice, "truncated": truncated,
"start_byte": start, "end_byte": end,
"start_line": line_start,
"source_kind": "markdown_headings"
}))
}
#[cfg(test)]
mod tests {
use super::*;
const DOC: &str = "---\ntitle: example\n---\nEntry instructions.\n\n# main\nClass instructions.\n\n## route\nReal body.\n```md\n## route\nfake\n```\n\n## other\nOther body.\n\n# helper\nHelper prose.\n\n## route\nSecond body.\n";
#[test]
fn scope_is_bounded_and_fenced_headings_ignored() {
let v = project(&json!({"source": DOC, "scope": "function", "class": "main", "function": "route"})).unwrap();
assert_eq!(v["ok"], true);
assert!(v["text"].as_str().unwrap().contains("Real body."));
assert!(v["text"].as_str().unwrap().contains("fake"));
assert!(!v["text"].as_str().unwrap().contains("Other body."));
assert!(!v["text"].as_str().unwrap().contains("Second body."));
}
#[test]
fn ambiguous_function_fails_closed() {
let v = project(&json!({"source": DOC, "scope": "function", "function": "route"})).unwrap();
assert_eq!(v["status"], "ambiguous");
assert_eq!(v["text"], Value::Null);
}
#[test]
fn file_scope_removes_frontmatter_and_class_prose_excludes_functions() {
let a = project(&json!({"source": DOC, "scope": "file"})).unwrap();
assert_eq!(a["text"], "Entry instructions.");
let b = project(&json!({"source": DOC, "scope": "class", "class": "main"})).unwrap();
assert!(b["text"].as_str().unwrap().contains("Class instructions."));
assert!(!b["text"].as_str().unwrap().contains("Real body."));
}
#[test]
fn unicode_truncation_does_not_split_characters() {
let v = project(&json!({"source": "汉".repeat(100), "scope": "file", "max_chars": 32})).unwrap();
assert_eq!(v["text"].as_str().unwrap().chars().count(), 32);
assert_eq!(v["truncated"], true);
}
}
+34 -35
View File
@@ -91,6 +91,8 @@ fn ensure_dir(root: &Path) -> Result<(), String> {
fs::create_dir_all(root).map_err(|e| format!("effects mkdir: {e}")) fs::create_dir_all(root).map_err(|e| format!("effects mkdir: {e}"))
} }
static EFFECT_TEMP_SEQUENCE: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> { fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> {
let parent = path let parent = path
.parent() .parent()
@@ -102,7 +104,8 @@ fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> {
.and_then(|s| s.to_str()) .and_then(|s| s.to_str())
.unwrap_or("op.json"), .unwrap_or("op.json"),
std::process::id(), std::process::id(),
now_rfc3339().replace(':', "") format!("{}-{}", now_rfc3339().replace(':', ""),
EFFECT_TEMP_SEQUENCE.fetch_add(1, std::sync::atomic::Ordering::Relaxed))
); );
let tmp = parent.join(tmp_name); let tmp = parent.join(tmp_name);
let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?; let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?;
@@ -425,12 +428,16 @@ fn fnv64(s: &str) -> u64 {
mod tests { mod tests {
use super::*; use super::*;
// Avoid process-global set_current_dir: Rust executes tests concurrently.
// Keep each ledger in its own repository-relative, unique directory.
static SCRATCH_SEQ: std::sync::atomic::AtomicU64 =
std::sync::atomic::AtomicU64::new(0);
fn scratch(tag: &str) -> PathBuf { fn scratch(tag: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!( let seq = SCRATCH_SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
let dir = PathBuf::from("target").join(format!(
"mq-effects-{}-{}-{}", "mq-effects-{}-{}-{}",
tag, tag, std::process::id(), seq
std::process::id(),
now_rfc3339().replace(':', "")
)); ));
let _ = fs::remove_dir_all(&dir); let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap(); fs::create_dir_all(&dir).unwrap();
@@ -440,14 +447,13 @@ mod tests {
#[test] #[test]
fn prepare_dedupe_and_collision() { fn prepare_dedupe_and_collision() {
let dir = scratch("prep"); let dir = scratch("prep");
let prev = std::env::current_dir().unwrap(); let ledger_dir = dir.join("led").to_string_lossy().to_string();
std::env::set_current_dir(&dir).unwrap();
let a = effects_prepare(&json!({ let a = effects_prepare(&json!({
"operation_id": "op1", "operation_id": "op1",
"idempotency_key": "idem1", "idempotency_key": "idem1",
"args_digest": "sha256:a", "args_digest": "sha256:a",
"effect_class": "write", "effect_class": "write",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
"logical_run_id": "run1", "logical_run_id": "run1",
})) }))
.unwrap(); .unwrap();
@@ -458,7 +464,7 @@ mod tests {
"operation_id": "op1", "operation_id": "op1",
"idempotency_key": "idem1", "idempotency_key": "idem1",
"args_digest": "sha256:a", "args_digest": "sha256:a",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
})) }))
.unwrap(); .unwrap();
assert_eq!(again["deduped"], true); assert_eq!(again["deduped"], true);
@@ -467,43 +473,41 @@ mod tests {
"operation_id": "op2", "operation_id": "op2",
"idempotency_key": "idem1", "idempotency_key": "idem1",
"args_digest": "sha256:b", "args_digest": "sha256:b",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
})); }));
assert!(clash.unwrap_err().contains("collision")); assert!(clash.unwrap_err().contains("collision"));
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir); let _ = fs::remove_dir_all(&dir);
} }
#[test] #[test]
fn transition_and_watermark_gates_write_resume() { fn transition_and_watermark_gates_write_resume() {
let dir = scratch("wm"); let dir = scratch("wm");
let prev = std::env::current_dir().unwrap(); let ledger_dir = dir.join("led").to_string_lossy().to_string();
std::env::set_current_dir(&dir).unwrap();
effects_prepare(&json!({ effects_prepare(&json!({
"operation_id": "op_w", "operation_id": "op_w",
"idempotency_key": "idem_w", "idempotency_key": "idem_w",
"args_digest": "sha256:w", "args_digest": "sha256:w",
"effect_class": "write", "effect_class": "write",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
"logical_run_id": "run1", "logical_run_id": "run1",
})) }))
.unwrap(); .unwrap();
effects_transition(&json!({ effects_transition(&json!({
"operation_id": "op_w", "operation_id": "op_w",
"state": "started", "state": "started",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
})) }))
.unwrap(); .unwrap();
// Crash window: unknown — write auto-resume must stay closed. // Crash window: unknown — write auto-resume must stay closed.
effects_transition(&json!({ effects_transition(&json!({
"operation_id": "op_w", "operation_id": "op_w",
"state": "unknown", "state": "unknown",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
})) }))
.unwrap(); .unwrap();
let wm1 = effects_watermark(&json!({ let wm1 = effects_watermark(&json!({
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
"logical_run_id": "run1", "logical_run_id": "run1",
})) }))
.unwrap(); .unwrap();
@@ -513,12 +517,12 @@ mod tests {
effects_reconcile(&json!({ effects_reconcile(&json!({
"operation_id": "op_w", "operation_id": "op_w",
"outcome": "committed", "outcome": "committed",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
"result_ref": "receipt:1", "result_ref": "receipt:1",
})) }))
.unwrap(); .unwrap();
let wm2 = effects_watermark(&json!({ let wm2 = effects_watermark(&json!({
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
"logical_run_id": "run1", "logical_run_id": "run1",
})) }))
.unwrap(); .unwrap();
@@ -526,7 +530,6 @@ mod tests {
assert_eq!(wm2["open_unknown"], 0); assert_eq!(wm2["open_unknown"], 0);
assert!(wm2["watermark"].as_str().unwrap().starts_with("sha256-lite:")); assert!(wm2["watermark"].as_str().unwrap().starts_with("sha256-lite:"));
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir); let _ = fs::remove_dir_all(&dir);
} }
@@ -535,32 +538,31 @@ mod tests {
// Write "succeeds" locally only after reconcile; retry while unknown must not // Write "succeeds" locally only after reconcile; retry while unknown must not
// look write_auto_resume_safe (MA-T03 watermark gate). // look write_auto_resume_safe (MA-T03 watermark gate).
let dir = scratch("mat03"); let dir = scratch("mat03");
let prev = std::env::current_dir().unwrap(); let ledger_dir = dir.join("led").to_string_lossy().to_string();
std::env::set_current_dir(&dir).unwrap();
effects_prepare(&json!({ effects_prepare(&json!({
"operation_id": "op_kill", "operation_id": "op_kill",
"idempotency_key": "run|s|write_probe|sha256-lite:1", "idempotency_key": "run|s|write_probe|sha256-lite:1",
"args_digest": "sha256-lite:1", "args_digest": "sha256-lite:1",
"effect_class": "write", "effect_class": "write",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
"logical_run_id": "run_kill", "logical_run_id": "run_kill",
})) }))
.unwrap(); .unwrap();
effects_transition(&json!({ effects_transition(&json!({
"operation_id": "op_kill", "operation_id": "op_kill",
"state": "started", "state": "started",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
})) }))
.unwrap(); .unwrap();
// Crash before commit: // Crash before commit:
effects_transition(&json!({ effects_transition(&json!({
"operation_id": "op_kill", "operation_id": "op_kill",
"state": "unknown", "state": "unknown",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
})) }))
.unwrap(); .unwrap();
let wm = effects_watermark(&json!({ let wm = effects_watermark(&json!({
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
"logical_run_id": "run_kill", "logical_run_id": "run_kill",
})) }))
.unwrap(); .unwrap();
@@ -572,7 +574,7 @@ mod tests {
"idempotency_key": "run|s|write_probe|sha256-lite:1", "idempotency_key": "run|s|write_probe|sha256-lite:1",
"args_digest": "sha256-lite:1", "args_digest": "sha256-lite:1",
"effect_class": "write", "effect_class": "write",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
"logical_run_id": "run_kill", "logical_run_id": "run_kill",
})) }))
.unwrap(); .unwrap();
@@ -582,42 +584,39 @@ mod tests {
effects_reconcile(&json!({ effects_reconcile(&json!({
"operation_id": "op_kill", "operation_id": "op_kill",
"outcome": "committed", "outcome": "committed",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
"result_ref": "effect:op_kill", "result_ref": "effect:op_kill",
})) }))
.unwrap(); .unwrap();
let wm2 = effects_watermark(&json!({ let wm2 = effects_watermark(&json!({
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
"logical_run_id": "run_kill", "logical_run_id": "run_kill",
})) }))
.unwrap(); .unwrap();
assert_eq!(wm2["write_auto_resume_safe"], true); assert_eq!(wm2["write_auto_resume_safe"], true);
assert_eq!(wm2["pending_writes"], 0); assert_eq!(wm2["pending_writes"], 0);
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir); let _ = fs::remove_dir_all(&dir);
} }
#[test] #[test]
fn illegal_skip_started() { fn illegal_skip_started() {
let dir = scratch("bad"); let dir = scratch("bad");
let prev = std::env::current_dir().unwrap(); let ledger_dir = dir.join("led").to_string_lossy().to_string();
std::env::set_current_dir(&dir).unwrap();
effects_prepare(&json!({ effects_prepare(&json!({
"operation_id": "op_x", "operation_id": "op_x",
"idempotency_key": "idem_x", "idempotency_key": "idem_x",
"args_digest": "sha256:x", "args_digest": "sha256:x",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
})) }))
.unwrap(); .unwrap();
let err = effects_transition(&json!({ let err = effects_transition(&json!({
"operation_id": "op_x", "operation_id": "op_x",
"state": "committed", "state": "committed",
"ledger_dir": "led", "ledger_dir": ledger_dir.clone(),
})) }))
.unwrap_err(); .unwrap_err();
assert!(err.contains("illegal transition")); assert!(err.contains("illegal transition"));
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir); let _ = fs::remove_dir_all(&dir);
} }
} }
+39 -2
View File
@@ -82,6 +82,10 @@ pub fn decide_retry(args: &Value) -> Result<Value, String> {
.get("max_arg_repairs") .get("max_arg_repairs")
.and_then(|v| v.as_u64()) .and_then(|v| v.as_u64())
.unwrap_or(1) as u32; .unwrap_or(1) as u32;
let max_output_repair = args
.get("max_output_repairs")
.and_then(|v| v.as_u64())
.unwrap_or(1) as u32;
let effect_class = args let effect_class = args
.get("effect_class") .get("effect_class")
.and_then(|v| v.as_str()) .and_then(|v| v.as_str())
@@ -145,6 +149,12 @@ pub fn decide_retry(args: &Value) -> Result<Value, String> {
"invalid_arguments" if recovery == "repair_args" && attempts < max_arg_repair => Ok( "invalid_arguments" if recovery == "repair_args" && attempts < max_arg_repair => Ok(
decision("repair_args", "one_arg_repair", attempts, max_arg_repair), decision("repair_args", "one_arg_repair", attempts, max_arg_repair),
), ),
"invalid_output" if recovery == "repair_output" && attempts < max_output_repair => Ok(
decision("repair_output", "one_format_repair", attempts, max_output_repair),
),
"context_overflow" if recovery == "compact_context" && attempts == 0 => Ok(
decision("compact_context", "one_bounded_compaction", attempts, 1),
),
"auth" | "forbidden" | "policy_denied" => Ok(decision( "auth" | "forbidden" | "policy_denied" => Ok(decision(
"needs_input", "needs_input",
category, category,
@@ -172,13 +182,17 @@ fn decision(action: &str, reason: &str, attempts: u32, max_attempts: u32) -> Val
"reason": reason, "reason": reason,
"attempts_used": attempts, "attempts_used": attempts,
"max_attempts": max_attempts, "max_attempts": max_attempts,
"auto": matches!(action, "retry_step" | "repair_args"), "auto": matches!(action, "retry_step" | "repair_args" | "repair_output" | "compact_context"),
}) })
} }
fn infer_category(code: &str) -> &'static str { fn infer_category(code: &str) -> &'static str {
let c = code.to_ascii_lowercase(); let c = code.to_ascii_lowercase();
if c.contains("timeout") || c.contains("429") || c.contains("5xx") || c.contains("connect") { if c.contains("context_overflow") || c.contains("context_length") {
"context_overflow"
} else if c.contains("invalid_choice") || c.contains("invalid_output") {
"invalid_output"
} else if c.contains("timeout") || c.contains("429") || c.contains("5xx") || c.contains("connect") {
"transient" "transient"
} else if c.contains("schema") || c.contains("argument") { } else if c.contains("schema") || c.contains("argument") {
"invalid_arguments" "invalid_arguments"
@@ -212,6 +226,8 @@ fn default_recovery(category: &str, effect_state: &str) -> &'static str {
match category { match category {
"transient" => "retry_step", "transient" => "retry_step",
"invalid_arguments" => "repair_args", "invalid_arguments" => "repair_args",
"invalid_output" => "repair_output",
"context_overflow" => "compact_context",
"auth" | "forbidden" | "policy_denied" | "needs_input" => "needs_input", "auth" | "forbidden" | "policy_denied" | "needs_input" => "needs_input",
"budget_exhausted" => "return_partial", "budget_exhausted" => "return_partial",
"cancelled" => "stop", "cancelled" => "stop",
@@ -259,6 +275,27 @@ mod tests {
assert_eq!(d["auto"], false); assert_eq!(d["auto"], false);
} }
#[test]
fn output_repair_is_bounded_and_read_only() {
let err = make_error(&json!({"code": "model.invalid_choice"})).unwrap();
assert_eq!(err["category"], "invalid_output");
let first = decide_retry(&json!({"error": err, "attempts": 0})).unwrap();
assert_eq!(first["action"], "repair_output");
let next = decide_retry(&json!({"error": err, "attempts": 1})).unwrap();
assert_eq!(next["action"], "stop");
let write = decide_retry(&json!({
"error": err, "attempts": 0, "effect_class": "write"
})).unwrap();
assert_eq!(write["action"], "manual_review");
}
#[test]
fn compaction_is_not_an_unbounded_model_loop() {
let err = make_error(&json!({"code": "model.context_overflow"})).unwrap();
assert_eq!(decide_retry(&json!({"error": err, "attempts": 0})).unwrap()["action"], "compact_context");
assert_eq!(decide_retry(&json!({"error": err, "attempts": 1})).unwrap()["action"], "stop");
}
#[test] #[test]
fn fingerprint_loop_stops() { fn fingerprint_loop_stops() {
let err = make_error(&json!({"code": "tool.timeout"})).unwrap(); let err = make_error(&json!({"code": "tool.timeout"})).unwrap();
+251
View File
@@ -0,0 +1,251 @@
//! Durable input gates for document-native SKILLs.
//! Pausing is a committed *step boundary*, not serialization of a Rust stack.
//! The caller resumes the next documented step with the saved answer.
use std::fs::{self, OpenOptions};
use std::path::PathBuf;
use serde_json::{json, Value};
use crate::resume;
struct GateLock(PathBuf);
impl Drop for GateLock {
fn drop(&mut self) {
let _ = fs::remove_file(&self.0);
}
}
fn text_arg<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
args.get(key)
.and_then(Value::as_str)
.filter(|s| !s.is_empty())
.ok_or_else(|| format!("missing text `{key}`"))
}
fn valid_id(s: &str) -> bool {
!s.is_empty()
&& s.len() <= 100
&& s.bytes().all(|c| c.is_ascii_alphanumeric() || c == b'-' || c == b'_')
}
fn root(args: &Value) -> Result<PathBuf, String> {
let name = args
.get("resume_dir")
.and_then(Value::as_str)
.unwrap_or(".marqdo/agent-resume");
let path = PathBuf::from(name);
if path.is_absolute()
|| path.components().any(|part| matches!(part, std::path::Component::ParentDir))
{
return Err("resume_dir must be a relative path without '..'".to_string());
}
fs::create_dir_all(&path).map_err(|e| format!("input gate mkdir: {e}"))?;
Ok(path)
}
fn lock(args: &Value, id: &str) -> Result<GateLock, String> {
if !valid_id(id) {
return Err("input gate id must be 1..=100 ASCII letters, numbers, '_' or '-'".into());
}
let path = root(args)?.join(format!("{id}.input-lock"));
OpenOptions::new()
.write(true)
.create_new(true)
.open(&path)
.map_err(|e| format!("input gate is busy or needs reconciliation: {e}"))?;
Ok(GateLock(path))
}
fn options(args: &Value) -> Result<Value, String> {
let choices = args.get("options").and_then(Value::as_array)
.ok_or_else(|| "options must be a list of 1..=32 short labels".to_string())?;
if choices.is_empty() || choices.len() > 32 {
return Err("options must contain 1..=32 choices".into());
}
for v in choices {
let Some(s) = v.as_str() else {
return Err("every option must be text".into());
};
if s.is_empty() || s.len() > 256 {
return Err("each option must contain 1..=256 bytes".into());
}
}
let empty = crate::choice::parse_choice(&json!({
"options": choices, "reply": "__invalid_choice_probe__"
}))?;
// The parser checks duplicates and option size; the probe must not be accepted.
if empty["ok"] == true {
return Err("invalid reserved choice option".into());
}
Ok(Value::Array(choices.to_vec()))
}
/// Create a durable waiting-input checkpoint. Repeated open never resets a
/// previously answered gate. No external effect is performed.
pub fn input_open(args: &Value) -> Result<Value, String> {
let id = text_arg(args, "id")?;
let _lock = lock(args, id)?;
let labels = options(args)?;
let query = text_arg(args, "question")?;
let version = text_arg(args, "source_revision")?;
let read_args = json!({"id": id, "resume_dir": args.get("resume_dir")});
let existing = resume::resume_load(&read_args)?;
if existing["found"] == true {
let meta = &existing["meta"];
let same = meta["question"] == query
&& meta["options"] == labels
&& meta["source_revision"] == version
&& meta["session_id"] == *args.get("session_id").unwrap_or(&Value::Null)
&& meta["principal_ref"] == *args.get("principal_ref").unwrap_or(&Value::Null);
if same && existing["ok"] == true {
let status = existing["status"].as_str().unwrap_or("unknown");
return Ok(json!({
"ok": true, "id": id, "status": status,
"value": existing["result"], "reused": true,
"question": query, "options": labels
}));
}
return Ok(json!({"ok":false,"id":id,"status":"conflict",
"error":{"code":"input.stale_or_reused_gate"}}));
}
let saved = resume::resume_save(&json!({
"id": id, "resume_dir": args.get("resume_dir"),
"checkpoint_v2": true,
"status": "waiting_input",
"task": query,
"meta": {
"question": query,
"options": labels,
"source_revision": version,
"session_id": args.get("session_id").unwrap_or(&Value::Null),
"principal_ref": args.get("principal_ref").unwrap_or(&Value::Null),
"freeform": args.get("freeform").and_then(Value::as_bool).unwrap_or(true)
}
}))?;
if saved["ok"] != true {
return Err("unable to save input checkpoint".into());
}
Ok(json!({"ok": true, "id":id, "status":"waiting_input", "value":null,
"question":query,"options":labels,"reused":false}))
}
/// Resume a specific gate with a user response. Only a committed answer can be
/// replayed: different duplicate replies conflict instead of re-triggering work.
pub fn input_resume(args: &Value) -> Result<Value, String> {
let id = text_arg(args, "id")?;
let _lock = lock(args, id)?;
let reply = text_arg(args, "reply")?;
if reply.len() > 4096 {
return Err("input reply must not exceed 4096 bytes".into());
}
let version = text_arg(args, "source_revision")?;
let read_args = json!({"id": id, "resume_dir": args.get("resume_dir")});
let existing = resume::resume_load(&read_args)?;
if existing["ok"] != true || existing["schema"] != "CheckpointV2" {
return Ok(json!({"ok":false,"status":"not_found_or_corrupt","id":id}));
}
let meta = &existing["meta"];
if meta["source_revision"] != version
|| meta["session_id"] != *args.get("session_id").unwrap_or(&Value::Null)
|| meta["principal_ref"] != *args.get("principal_ref").unwrap_or(&Value::Null)
{
return Ok(json!({"ok":false,"status":"conflict","id":id,
"error":{"code":"input.scope_or_revision_changed"}}));
}
// Normalize the answer before duplicate detection: the index "2" and
// the selected label "office" must be the same committed response.
let allowed = crate::choice::parse_choice(&json!({
"options": meta["options"], "reply": reply
}))?;
let normalized = if allowed["ok"] == true {
allowed["value"].clone()
} else if meta["freeform"] == true && !reply.trim().is_empty() {
json!(reply.trim())
} else {
return Ok(json!({"ok":false,"status":"invalid","id":id,
"error":{"code":"input.invalid_choice"}}));
};
if existing["status"] == "resumed" {
if existing["result"] == normalized {
return Ok(json!({"ok":true,"status":"resumed","id":id,
"value":normalized,"reused":true}));
}
return Ok(json!({"ok":false,"status":"conflict","id":id,
"error":{"code":"input.already_answered"}}));
}
if existing["status"] != "waiting_input" {
return Ok(json!({"ok":false,"status":"conflict","id":id}));
}
let saved = resume::resume_save(&json!({
"id": id, "resume_dir": args.get("resume_dir"),
"checkpoint_v2": true,
"status": "resumed",
"task": existing["task"],
"meta": meta,
"result": normalized
}))?;
if saved["ok"] != true {
return Err("unable to commit resumed input".into());
}
Ok(json!({"ok":true,"status":"resumed","id":id,
"value":normalized,"reused":false}))
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::{AtomicU64, Ordering};
static SEQ: AtomicU64 = AtomicU64::new(0);
fn fixture() -> (String, String) {
let id = format!("gate_{}_{}",std::process::id(),SEQ.fetch_add(1,Ordering::Relaxed));
let dir = format!("target/mq-gate-test-{id}");
(id, dir)
}
#[test]
fn persists_answer_without_duplicate_side_effect_or_changed_reply() {
let (id, dir) = fixture();
let initial = json!({"id":id,"resume_dir":dir,"question":"Choose?",
"options":["chat","office"],"source_revision":"v1",
"session_id":"s1","principal_ref":"u1","freeform":false});
assert_eq!(input_open(&initial).unwrap()["status"], "waiting_input");
assert_eq!(input_open(&initial).unwrap()["reused"], true);
let v = json!({"id":id,"resume_dir":dir,"reply":"2",
"source_revision":"v1","session_id":"s1","principal_ref":"u1"});
assert_eq!(input_resume(&v).unwrap()["value"], "office");
assert_eq!(input_resume(&v).unwrap()["reused"], true);
assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir,
"reply":"office","source_revision":"v1","session_id":"s1",
"principal_ref":"u1"})).unwrap()["reused"], true);
assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir,
"reply":"chat","source_revision":"v1","session_id":"s1",
"principal_ref":"u1"})).unwrap()["status"], "conflict");
assert_eq!(input_open(&initial).unwrap()["status"], "resumed");
}
#[test]
fn prevents_changed_source_or_unauthorized_session() {
let (id, dir) = fixture();
let initial = json!({"id":id,"resume_dir":dir,"question":"Proceed?",
"options":["yes","no"],"source_revision":"v1",
"session_id":"s1","principal_ref":"u1"});
input_open(&initial).unwrap();
for (rev,session) in [("v2","s1"),("v1","other")] {
assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir,"reply":"yes",
"source_revision":rev,"session_id":session,
"principal_ref":"u1"})).unwrap()["status"], "conflict");
}
}
#[test]
fn invalid_choice_keeps_gate_open_and_no_freeform_is_enforced() {
let (id, dir) = fixture();
input_open(&json!({"id":id,"resume_dir":dir,"question":"Pick",
"options":["a","b"],"freeform":false,
"source_revision":"v1"})).unwrap();
assert_eq!(input_resume(&json!({"id":id,"resume_dir":dir,"reply":"??",
"source_revision":"v1"})).unwrap()["status"], "invalid");
assert_eq!(resume::resume_load(&json!({"id":id,"resume_dir":dir})).unwrap()["status"], "waiting_input");
}
}
+31
View File
@@ -1,19 +1,24 @@
//! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb + v2 memory + adaptive route. //! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb + v2 memory + adaptive route.
mod choice;
mod context_pack; mod context_pack;
mod context_scope;
mod corpus; mod corpus;
mod effects; mod effects;
mod eng; mod eng;
mod error; mod error;
mod input;
mod kb; mod kb;
mod mcp_client; mod mcp_client;
mod mcp_server; mod mcp_server;
mod memory; mod memory;
mod output; mod output;
mod parallel;
mod resume; mod resume;
mod route; mod route;
mod sandbox; mod sandbox;
mod tools; mod tools;
mod workflow;
use std::collections::HashMap; use std::collections::HashMap;
use std::ffi::CString; use std::ffi::CString;
@@ -834,6 +839,19 @@ 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_load, resume::resume_load, "agent_resume_load");
kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear"); 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_resume_list, resume::resume_list, "agent_resume_list");
kb_ffi!(agent_choice_parse, choice::parse_choice, "agent_choice_parse");
kb_ffi!(agent_context_scope, context_scope::project, "agent_context_scope");
kb_ffi!(agent_input_open, input::input_open, "agent_input_open");
kb_ffi!(agent_input_resume, input::input_resume, "agent_input_resume");
kb_ffi!(agent_parallel_report, parallel::report, "agent_parallel_report");
kb_ffi!(agent_workflow_open, workflow::open, "agent_workflow_open");
kb_ffi!(agent_workflow_next, workflow::next, "agent_workflow_next");
kb_ffi!(agent_workflow_inspect, workflow::inspect, "agent_workflow_inspect");
kb_ffi!(agent_workflow_list, workflow::list, "agent_workflow_list");
kb_ffi!(agent_workflow_commit, workflow::commit, "agent_workflow_commit");
kb_ffi!(agent_workflow_cancel, workflow::cancel, "agent_workflow_cancel");
kb_ffi!(agent_workflow_retry_plan, workflow::retry_plan, "agent_workflow_retry_plan");
kb_ffi!(agent_workflow_retry_commit, workflow::retry_commit, "agent_workflow_retry_commit");
kb_ffi!(agent_error_make, error::make_error, "agent_error_make"); 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_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_register, tools::tools_register, "agent_tools_register");
@@ -963,6 +981,19 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
("agent_resume_load", "id,resume_dir", agent_resume_load), ("agent_resume_load", "id,resume_dir", agent_resume_load),
("agent_resume_clear", "id,resume_dir", agent_resume_clear), ("agent_resume_clear", "id,resume_dir", agent_resume_clear),
("agent_resume_list", "resume_dir", agent_resume_list), ("agent_resume_list", "resume_dir", agent_resume_list),
("agent_choice_parse", "reply,options", agent_choice_parse),
("agent_context_scope", "source,scope,class,function", agent_context_scope),
("agent_input_open", "id,question,options,source_revision", agent_input_open),
("agent_input_resume", "id,reply,source_revision", agent_input_resume),
("agent_parallel_report", "results", agent_parallel_report),
("agent_workflow_open", "id,steps,source_revision,session_id,principal_ref,resume_dir", agent_workflow_open),
("agent_workflow_next", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_next),
("agent_workflow_inspect", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_inspect),
("agent_workflow_list", "session_id,principal_ref,resume_dir", agent_workflow_list),
("agent_workflow_commit", "id,step_id,response,source_revision,session_id,principal_ref,resume_dir", agent_workflow_commit),
("agent_workflow_cancel", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_cancel),
("agent_workflow_retry_plan", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_retry_plan),
("agent_workflow_retry_commit", "id,results,source_revision,session_id,principal_ref,resume_dir", agent_workflow_retry_commit),
("agent_error_make", "code,message,category", agent_error_make), ("agent_error_make", "code,message,category", agent_error_make),
("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry), ("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry),
("agent_tools_register", "spec,specs", agent_tools_register), ("agent_tools_register", "spec,specs", agent_tools_register),
+81
View File
@@ -0,0 +1,81 @@
//! Deterministic fan-out results: never discard a successful sibling and never
//! infer success from a completed wait protocol alone.
use serde_json::{json, Value};
pub fn report(args: &Value) -> Result<Value, String> {
let results = args
.get("results")
.and_then(Value::as_array)
.ok_or_else(|| "results must be ordered subtask result list".to_string())?;
if results.len() > 10_000 {
return Err("parallel result count exceeds scheduler limit".into());
}
let mut passed = 0usize;
let mut failed = 0usize;
let mut unknown = 0usize;
let mut entries = Vec::with_capacity(results.len());
for (index, child) in results.iter().enumerate() {
let transport = child.get("ok").and_then(Value::as_bool);
let body = child.get("value").unwrap_or(&Value::Null);
let status = match (transport, body.get("code").and_then(Value::as_i64)) {
(Some(true), Some(0)) => { passed += 1; "succeeded" }
(Some(true), Some(_)) | (Some(false), _) => { failed += 1; "failed" }
_ => { unknown += 1; "uncertain" }
};
// Raw child result is kept as data; the model sees only an optional
// bounded summary. The host may store detailed output as an artifact.
let detail = child.get("error")
.and_then(Value::as_str)
.or_else(|| body.get("stderr").and_then(Value::as_str))
.unwrap_or("");
let brief: String = detail.chars().take(280).collect();
entries.push(json!({
"index": index,
"status": status,
"summary": brief,
"result": child
}));
}
let status = if unknown != 0 {
"uncertain"
} else if failed == 0 {
"succeeded"
} else if passed > 0 {
"partial"
} else {
"failed"
};
Ok(json!({
"ok": failed == 0 && unknown == 0,
"schema": "AgentParallelResultV1",
"status": status,
"succeeded": passed,
"failed": failed,
"uncertain": unknown,
"items": entries
}))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn preserves_success_and_exposes_failed_child() {
let result = report(&json!({"results":[
{"ok":true,"value":{"code":0,"value":"good"}},
{"ok":true,"value":{"code":2,"stderr":"failed"}},
{"ok":false,"error":"timeout"}
]})).unwrap();
assert_eq!(result["status"], "partial");
assert_eq!(result["succeeded"], 1);
assert_eq!(result["failed"], 2);
assert_eq!(result["items"][0]["status"], "succeeded");
}
#[test]
fn unknown_child_cannot_be_mislabeled_successful() {
let value = report(&json!({"results":[{"ok":true,"value":{"value":"no code"}}]})).unwrap();
assert_eq!(value["status"], "uncertain");
assert_eq!(value["ok"], false);
}
}
+11 -13
View File
@@ -85,6 +85,8 @@ fn ensure_dir(root: &Path) -> Result<(), String> {
} }
/// Atomic durable write: unique temp → write → flush/fsync → rename. /// Atomic durable write: unique temp → write → flush/fsync → rename.
static TEMP_SEQUENCE: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> { fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> {
let parent = path let parent = path
.parent() .parent()
@@ -96,7 +98,8 @@ fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> {
.and_then(|s| s.to_str()) .and_then(|s| s.to_str())
.unwrap_or("ckpt.json"), .unwrap_or("ckpt.json"),
std::process::id(), std::process::id(),
now_rfc3339().replace(':', "") format!("{}-{}", now_rfc3339().replace(':', ""),
TEMP_SEQUENCE.fetch_add(1, std::sync::atomic::Ordering::Relaxed))
); );
let tmp = parent.join(tmp_name); let tmp = parent.join(tmp_name);
let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?; let text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?;
@@ -396,7 +399,8 @@ mod tests {
.duration_since(UNIX_EPOCH) .duration_since(UNIX_EPOCH)
.unwrap() .unwrap()
.as_nanos(); .as_nanos();
let dir = std::env::temp_dir().join(format!("marqdo-resume-{label}-{nanos}")); // Do not mutate process-wide cwd from concurrent Rust unit tests.
let dir = PathBuf::from("target").join(format!("marqdo-resume-{label}-{nanos}"));
fs::create_dir_all(&dir).unwrap(); fs::create_dir_all(&dir).unwrap();
dir dir
} }
@@ -410,10 +414,7 @@ mod tests {
#[test] #[test]
fn atomic_v2_roundtrip_and_legacy_manual_review() { fn atomic_v2_roundtrip_and_legacy_manual_review() {
let dir = scratch("v2"); let dir = scratch("v2");
// Use relative path via env cwd — chdir into scratch for this test. let rel = dir.join("ckpts").to_string_lossy().to_string();
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
let rel = "ckpts";
let saved = resume_save(&json!({ let saved = resume_save(&json!({
"id": "run1", "id": "run1",
"schema": "CheckpointV2", "schema": "CheckpointV2",
@@ -491,23 +492,20 @@ mod tests {
assert_eq!(unsafe_ck["recovery_mode"], "checkpoint_v2_read_only"); assert_eq!(unsafe_ck["recovery_mode"], "checkpoint_v2_read_only");
assert_eq!(unsafe_ck["write_auto_resume"], false); assert_eq!(unsafe_ck["write_auto_resume"], false);
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir); let _ = fs::remove_dir_all(&dir);
} }
#[test] #[test]
fn corrupt_checkpoint_reports_error() { fn corrupt_checkpoint_reports_error() {
let dir = scratch("corrupt"); let dir = scratch("corrupt");
let prev = std::env::current_dir().unwrap(); let ckpts = dir.join("ckpts");
std::env::set_current_dir(&dir).unwrap(); fs::create_dir_all(&ckpts).unwrap();
fs::create_dir_all("ckpts").unwrap(); fs::write(ckpts.join("bad.json"), "{not-json").unwrap();
fs::write("ckpts/bad.json", "{not-json").unwrap(); let loaded = resume_load(&json!({"id": "bad", "resume_dir": ckpts.to_string_lossy()})).unwrap();
let loaded = resume_load(&json!({"id": "bad", "resume_dir": "ckpts"})).unwrap();
assert_eq!(loaded["found"], true); assert_eq!(loaded["found"], true);
assert_eq!(loaded["ok"], false); assert_eq!(loaded["ok"], false);
assert_eq!(loaded["error"]["code"], "checkpoint.corrupt"); assert_eq!(loaded["error"]["code"], "checkpoint.corrupt");
assert_eq!(loaded["recovery_mode"], "manual_review"); assert_eq!(loaded["recovery_mode"], "manual_review");
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir); let _ = fs::remove_dir_all(&dir);
} }
} }
+679
View File
@@ -0,0 +1,679 @@
//! Plugin-only durable step workflow.
//! No interpreter-frame serialization: every model/tool decision is a checkpointed
//! transition. This state machine issues actions but never executes arbitrary code.
use std::fs::{self, OpenOptions};
use std::path::PathBuf;
use serde_json::{json, Value};
use crate::{choice, parallel, resume};
const MAX_STEPS: usize = 128;
struct Guard(PathBuf);
impl Drop for Guard {
fn drop(&mut self) { let _ = fs::remove_file(&self.0); }
}
fn field<'a>(v: &'a Value, key: &str) -> Result<&'a str, String> {
v.get(key).and_then(Value::as_str).filter(|x| !x.is_empty())
.ok_or_else(|| format!("workflow requires text {key}"))
}
fn safe_key(s: &str) -> bool {
!s.is_empty() && s.len() <= 100
&& s.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
}
fn storage(args: &Value) -> Result<PathBuf, String> {
let rel = args.get("resume_dir").and_then(Value::as_str)
.unwrap_or(".marqdo/agent-resume");
let path = PathBuf::from(rel);
if path.is_absolute() || path.components().any(|part|
matches!(part, std::path::Component::ParentDir | std::path::Component::Prefix(_)))
{
return Err("resume_dir must be relative with no parent traversal".into());
}
let base = crate::host_query_json("cwd").ok()
.and_then(|v| v.as_str().map(PathBuf::from))
.unwrap_or(std::env::current_dir().map_err(|e| e.to_string())?);
let dir = base.join(path);
fs::create_dir_all(&dir).map_err(|e| format!("workflow mkdir: {e}"))?;
Ok(dir)
}
fn lock(args: &Value, id: &str) -> Result<Guard, String> {
if !safe_key(id) {
return Err("workflow id must be <=100 ASCII letters, numbers, - or _".into());
}
let path = storage(args)?.join(format!("{id}.flow-lock"));
OpenOptions::new().write(true).create_new(true).open(&path)
.map_err(|e| format!("workflow busy or stale lock; review before recovering: {e}"))?;
Ok(Guard(path))
}
fn checkpoint_args(args: &Value, id: &str) -> Value {
json!({"id": id, "resume_dir": args.get("resume_dir")})
}
fn read(args: &Value, id: &str) -> Result<Value, String> {
resume::resume_load(&checkpoint_args(args,id))
}
fn context(args: &Value) -> Value {
json!({
"source_revision": args.get("source_revision").cloned().unwrap_or(Value::Null),
"session_id": args.get("session_id").cloned().unwrap_or(Value::Null),
"principal_ref": args.get("principal_ref").cloned().unwrap_or(Value::Null)
})
}
fn check_context(args: &Value, ckpt: &Value) -> bool {
ckpt["meta"]["identity"] == context(args)
}
fn validate_steps(args: &Value) -> Result<Value, String> {
let steps = args.get("steps").and_then(Value::as_array)
.ok_or_else(|| "steps must be a list".to_string())?;
if steps.is_empty() || steps.len() > MAX_STEPS {
return Err("steps must contain 1..=128 items".into());
}
let mut seen = std::collections::HashSet::new();
for s in steps {
let id = field(s, "id")?;
if !safe_key(id) || !seen.insert(id) {
return Err("step ids must be unique safe identifiers".into());
}
let kind = field(s, "kind")?;
if !matches!(kind, "model" | "input" | "skill" | "parallel" | "return") {
return Err(format!("unsupported step kind: {kind}"));
}
if matches!(kind, "model" | "input") {
let options = s.get("options").and_then(Value::as_array)
.ok_or_else(|| "choice step requires options list".to_string())?;
let _ = choice::parse_choice(&json!({"reply":"","options":options}))?;
if kind == "input" { let _ = field(s, "question")?; }
if kind == "model" { let _ = field(s, "prompt")?; }
}
if kind == "skill" { let _ = field(s, "skill")?; }
if kind == "parallel" && !s.get("tasks").is_some_and(Value::is_array) {
return Err("parallel step requires tasks array".into());
}
}
// Resolve all branch targets against frozen, forward-only step IDs.
for (i, s) in steps.iter().enumerate() {
let targets = s.get("next").and_then(Value::as_str).into_iter()
.chain(s.get("routes").and_then(Value::as_object)
.into_iter().flat_map(|m| m.values().filter_map(Value::as_str)));
for target in targets {
let position = steps.iter().position(|x|x["id"]==target)
.ok_or_else(|| format!("unknown workflow target: {target}"))?;
if position <= i {
return Err("workflow routes must move forward to avoid loops".into());
}
}
if let Some(routes)=s.get("routes").and_then(Value::as_object) {
if !matches!(s["kind"].as_str(),Some("model"|"input")) {
return Err("only choice steps may declare routes".into());
}
for key in routes.keys() {
if !s["options"].as_array().is_some_and(|opts|
opts.iter().any(|x|x.as_str()==Some(key.as_str()))) {
return Err("route label is not a declared choice".into());
}
}
}
}
Ok(Value::Array(steps.clone()))
}
fn advance_cursor(step:&Value, value:&Value, steps:&[Value], current:usize)->Result<usize,String> {
let target=if let Some(routes)=step.get("routes").and_then(Value::as_object) {
let label=value.as_str().ok_or("routed choice must return a text label")?;
Some(routes.get(label).and_then(Value::as_str)
.ok_or("chosen option is missing a declared route")?)
} else {
step.get("next").and_then(Value::as_str)
};
match target {
None=>Ok(current+1),
Some(name)=> {
let n=steps.iter().position(|s|s["id"]==name)
.ok_or("unknown target after checkpoint recovery")?;
if n<=current {return Err("cyclic route refused".into())}
Ok(n)
}
}
}
fn state(ckpt: &Value) -> Result<(&Value,usize),String> {
let meta = ckpt.get("meta").ok_or("missing workflow metadata")?;
if meta.get("kind").and_then(Value::as_str) != Some("MarqdoAgentFlowV1") {
return Err("checkpoint is not a workflow".into());
}
let index = meta.get("cursor").and_then(Value::as_u64)
.ok_or("missing workflow cursor")? as usize;
Ok((meta,index))
}
fn save(args: &Value, id: &str, meta: &Value, status: &str) -> Result<(),String> {
let result = resume::resume_save(&json!({
"id": id,
"resume_dir": args.get("resume_dir"),
"checkpoint_v2": true,
"status": status,
"meta": meta,
"completed_steps": meta["completed"],
"step_id": meta["steps"].get(meta["cursor"].as_u64().unwrap_or(0) as usize)
.and_then(|x| x.get("id")).cloned().unwrap_or(Value::Null)
}))?;
if result["ok"] != true { return Err("workflow checkpoint write failed".into()); }
Ok(())
}
/// Register a bounded, frozen plan. Re-opening never resets a progressed plan.
pub fn open(args: &Value) -> Result<Value,String> {
let id = field(args,"id")?;
let _guard = lock(args,id)?;
let revision = field(args,"source_revision")?;
if revision.len()>256 { return Err("source_revision too long".into()); }
let steps = validate_steps(args)?;
let existing = read(args,id)?;
let identity = context(args);
if existing["found"] == true {
if existing["ok"] == true
&& existing["meta"]["identity"] == identity
&& existing["meta"]["steps"] == steps
{
return next_doc(&existing,id,true);
}
return Ok(json!({"ok":false,"status":"conflict","error":"workflow.id_or_revision_reused"}));
}
let meta = json!({
"kind":"MarqdoAgentFlowV1",
"identity":identity,
"steps":steps,
"cursor":0,
"completed":[],
});
save(args,id,&meta,"running")?;
Ok(json!({"ok":true,"id":id,"status":"created","cursor":0}))
}
fn next_doc(ckpt: &Value, id: &str, reused: bool) -> Result<Value,String> {
let (meta,index)=state(ckpt)?;
let steps = meta["steps"].as_array().ok_or("invalid steps")?;
if index>=steps.len() {
return Ok(json!({"ok":true,"id":id,"status":"succeeded",
"cursor":index,"completed":meta["completed"],"reused":reused}));
}
let step=&steps[index];
let status=ckpt["status"].as_str().unwrap_or("running");
if status=="blocked" || status=="uncertain" || status=="cancelled" {
return Ok(json!({"ok":false,"id":id,"status":status,
"cursor":index,"step":step,"completed":meta["completed"],
"partial": meta.get("partial").cloned().unwrap_or(Value::Null)}));
}
// Never auto-dispatch effectful or unclassified child documents.
// Those must be executed using the existing EffectLedger policy and an
// independently verified receipt, not an arbitrary model instruction.
if (step["kind"]=="skill" || step["kind"]=="parallel")
&& step["effect_class"]!="read"
{
return Ok(json!({"ok":false,"id":id,"status":"manual_review",
"cursor":index,"step":step,
"reason":"automatic child dispatch requires an explicit read-only effect class"}));
}
let waiting=match step["kind"].as_str().unwrap_or("") {
"model"=>"waiting_model",
"input"=>"waiting_input",
"skill" | "parallel"=>"ready_tool",
"return"=>"ready_return",
_=>"blocked"
};
Ok(json!({"ok":true,"id":id,"status":waiting,
"cursor":index,"step":step,"completed":meta["completed"],"reused":reused}))
}
/// Query the durable next action. This is non-blocking and does not invoke LLM.
pub fn next(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"id":id,"status":"not_found_or_mismatched"}));
}
next_doc(&ckpt,id,false)
}
/// Read a workflow summary without advancing it or running any step.
/// The caller-supplied identity must match the checkpoint, exactly like next.
pub fn inspect(args:&Value)->Result<Value,String> {
let id=field(args,"id")?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"id":id,"status":"not_found_or_mismatched"}));
}
let (meta,index)=state(&ckpt)?;
let steps=meta["steps"].as_array().ok_or("invalid steps")?;
let completed=meta["completed"].as_array().ok_or("invalid completed")?;
// `status` is the durable checkpoint status; `action` is what tick would
// observe next (waiting_model, waiting_input, ready_tool, ...).
let action=next_doc(&ckpt,id,false)?.get("status").cloned().unwrap_or(Value::Null);
Ok(json!({
"ok":true,"id":id,
"status":ckpt["status"].as_str().unwrap_or("running"),
"action":action,
"cursor":index,
"total_steps":steps.len(),
"completed_steps":completed.len(),
"completed":meta["completed"],
"step":steps.get(index).cloned().unwrap_or(Value::Null),
"partial":meta.get("partial").cloned().unwrap_or(Value::Null),
"identity":meta["identity"],
"updated_at":ckpt.get("updated_at").cloned().unwrap_or(Value::Null)
}))
}
/// List workflow checkpoints in the (host-relative) resume directory.
/// Non-workflow checkpoints and corrupt entries are omitted. When the caller
/// supplies an attested session or principal, only matching runs are returned.
pub fn list(args:&Value)->Result<Value,String> {
let dir=storage(args)?;
let session=args.get("session_id").and_then(Value::as_str);
let principal=args.get("principal_ref").and_then(Value::as_str);
let mut items=Vec::new();
let rd=fs::read_dir(&dir).map_err(|e|format!("workflow list: {e}"))?;
for ent in rd.flatten() {
let path=ent.path();
if path.extension().and_then(|x|x.to_str())!=Some("json") { continue; }
if path.file_name().and_then(|x|x.to_str())
.map(|x|x.starts_with('.')).unwrap_or(false) { continue; }
let Ok(text)=fs::read_to_string(&path) else { continue };
let Ok(doc)=serde_json::from_str::<Value>(&text) else { continue };
let meta=&doc["meta"];
if meta["kind"].as_str()!=Some("MarqdoAgentFlowV1") { continue; }
if session.is_some() && meta["identity"]["session_id"].as_str()!=session { continue; }
if principal.is_some() && meta["identity"]["principal_ref"].as_str()!=principal { continue; }
let steps=meta["steps"].as_array().map(|x|x.len()).unwrap_or(0);
let completed=meta["completed"].as_array().map(|x|x.len()).unwrap_or(0);
items.push(json!({
"id":doc.get("id").cloned().unwrap_or(Value::Null),
"status":doc.get("status").cloned().unwrap_or(Value::Null),
"cursor":meta.get("cursor").cloned().unwrap_or(Value::Null),
"total_steps":steps,
"completed_steps":completed,
"source_revision":meta["identity"]["source_revision"],
"updated_at":doc.get("updated_at").cloned().unwrap_or(Value::Null)
}));
}
items.sort_by(|a,b| a["id"].as_str().cmp(&b["id"].as_str()));
Ok(json!({"ok":true,"items":items,"resume_dir":dir.to_string_lossy()}))
}
/// Commit a verified result for the exact current step. All mutations are
/// serialized with a lock; a completed step cannot be committed a second time.
pub fn commit(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let _guard=lock(args,id)?;
let step_id=field(args,"step_id")?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"status":"not_found_or_mismatched"}));
}
let (meta,index)=state(&ckpt)?;
let steps=meta["steps"].as_array().ok_or("invalid steps")?;
let response=args.get("response").ok_or("missing response")?;
if index>=steps.len() {
let previous = meta["completed"].as_array().ok_or("invalid completed")?;
if previous.iter().any(|x|x["step_id"]==step_id && x["value"]==*response) {
return Ok(json!({"ok":true,"status":"succeeded","reused":true}));
}
return Ok(json!({"ok":false,"status":"already_finished"}));
}
let step=&steps[index];
if step["id"]!=step_id {
if meta["completed"].as_array().is_some_and(|list|
list.iter().any(|x|x["step_id"]==step_id && x["value"]==*response))
{
return Ok(json!({"ok":true,"status":"already_committed","reused":true}));
}
return Ok(json!({"ok":false,"status":"step_conflict"}));
}
if ckpt["status"]!="running" {
return Ok(json!({"ok":false,"status":"blocked","reason":ckpt["status"]}));
}
let kind=field(step,"kind")?;
let value = match kind {
"model" | "input" => {
let reply = response.as_str().ok_or("model/input response must be text")?;
let valid=choice::parse_choice(&json!({"options":step["options"],"reply":reply}))?;
if valid["ok"]!=true {
return Ok(json!({"ok":false,"status":"invalid_choice",
"error":valid["error"]}));
}
valid["value"].clone()
}
"skill" => {
// A completed wait is not equivalent to a successful child process.
let exit = response.get("value").and_then(|v| v.get("code"))
.or_else(|| response.get("code")).and_then(Value::as_i64);
if response["ok"]==false || exit != Some(0) {
return Ok(json!({"ok":false,
"status":if exit.is_none() {"uncertain"} else {"failed"},
"reason":"child process exit code zero is required before commit"}));
}
response.clone()
}
"parallel" => {
let report=if response["schema"]=="AgentParallelResultV1" {
response.clone()
} else {
parallel::report(&json!({"results":response}))?
};
if report["ok"]!=true {
let status=if report["uncertain"].as_u64().unwrap_or(0)>0 {
"uncertain"
} else {"blocked"};
// Save the full manifest of successful and failed siblings before
// returning. Do not run failed/unknown children automatically.
let mut frozen=meta.clone();
frozen["partial"]=report.clone();
save(args,id,&frozen,status)?;
return Ok(json!({"ok":false,"status":status,
"report":report,"reason":"child results retained for reconciliation"}));
}
report
}
"return" => response.clone(),
_ => return Err("invalid step kind".into()),
};
let target=advance_cursor(step,&value,steps,index)?;
let mut new_meta=meta.clone();
new_meta["cursor"]=json!(target);
new_meta["completed"].as_array_mut().ok_or("completed not array")?
.push(json!({"step_id":step_id,"value":value}));
let terminal=target==steps.len();
save(args,id,&new_meta,if terminal {"succeeded"} else {"running"})?;
Ok(json!({"ok":true,"id":id,
"status":if terminal {"succeeded"} else {"advanced"},
"cursor":target,"value":value,"reused":false}))
}
/// Produce a plan containing only previously failed *read-only* child tasks.
/// "uncertain" children and effectful plans cannot be blindly retried.
pub fn retry_plan(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"status":"not_found_or_mismatched"}));
}
let (meta,index)=state(&ckpt)?;
if ckpt["status"]!="blocked" {
return Ok(json!({"ok":false,"status":"not_retryable"}));
}
let step=&meta["steps"][index];
if step["kind"]!="parallel" || step["effect_class"]!="read"
|| meta["partial"]["uncertain"].as_u64().unwrap_or(1)!=0
{
return Ok(json!({"ok":false,"status":"manual_reconciliation_required"}));
}
let Some(items)=meta["partial"]["items"].as_array() else {
return Err("partial report has no items".into());
};
let Some(tasks)=step["tasks"].as_array() else {
return Err("parallel plan has no tasks".into());
};
if items.len()!=tasks.len() {
return Err("partial report task count mismatch".into());
}
let mut failed=Vec::new();
let mut indices=Vec::new();
for (i,item) in items.iter().enumerate() {
if item["index"]!=i {
return Err("out-of-order child result index".into());
}
if item["status"]=="failed" {
failed.push(tasks[i].clone());
indices.push(i);
} else if item["status"]!="succeeded" {
return Ok(json!({"ok":false,"status":"manual_reconciliation_required"}));
}
}
Ok(json!({"ok":true,"status":"retry_read_only",
"id":id,"step_id":step["id"],"tasks":failed,"indices":indices}))
}
/// Merge only the failed child slots with verified new outcomes.
/// Successful results and their order remain untouched.
pub fn retry_commit(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let _guard=lock(args,id)?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"status":"not_found_or_mismatched"}));
}
let (meta,index)=state(&ckpt)?;
if ckpt["status"]!="blocked" {
return Ok(json!({"ok":false,"status":"not_retryable"}));
}
let step=&meta["steps"][index];
if step["kind"]!="parallel" || step["effect_class"]!="read"
|| meta["partial"]["uncertain"].as_u64().unwrap_or(1)!=0
{
return Ok(json!({"ok":false,"status":"manual_reconciliation_required"}));
}
let items=meta["partial"]["items"].as_array()
.ok_or("invalid partial report")?;
let incoming=args.get("results").and_then(Value::as_array)
.ok_or("retry_commit requires results list")?;
let expected=items.iter().filter(|it|it["status"]=="failed").count();
if incoming.len()!=expected {
return Err("retry result count differs from failed child count".into());
}
let mut next=Vec::with_capacity(items.len());
let mut replacement=incoming.iter();
for item in items {
if item["status"]=="succeeded" {
next.push(item["result"].clone());
} else if item["status"]=="failed" {
next.push(replacement.next().ok_or("missing retry result")?.clone());
} else {
return Ok(json!({"ok":false,"status":"manual_reconciliation_required"}));
}
}
let report=parallel::report(&json!({"results":next}))?;
let mut updated=meta.clone();
if report["ok"]==true {
let target=advance_cursor(step,&report,
updated["steps"].as_array().ok_or("steps missing")?,index)?;
updated["cursor"]=json!(target);
updated["partial"]=Value::Null;
updated["completed"].as_array_mut().ok_or("completed not list")?
.push(json!({"step_id":step["id"],"value":report}));
let finished=target==updated["steps"].as_array().ok_or("steps missing")?.len();
save(args,id,&updated,if finished {"succeeded"} else {"running"})?;
Ok(json!({"ok":true,"status":if finished {"succeeded"} else {"advanced"},
"cursor":target,"result":report}))
} else {
updated["partial"]=report.clone();
save(args,id,&updated,if report["uncertain"].as_u64().unwrap_or(0)>0 {
"uncertain" } else {"blocked"})?;
Ok(json!({"ok":false,"status":"blocked","report":report}))
}
}
pub fn cancel(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let _guard=lock(args,id)?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"status":"not_found_or_mismatched"}));
}
if ckpt["status"]=="succeeded" {
return Ok(json!({"ok":false,"status":"already_finished"}));
}
let (meta,_)=state(&ckpt)?;
save(args,id,meta,"cancelled")?;
Ok(json!({"ok":true,"id":id,"status":"cancelled"}))
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::{AtomicU64,Ordering};
static SEQ: AtomicU64=AtomicU64::new(0);
fn fixture()->Value {
let n=SEQ.fetch_add(1,Ordering::Relaxed);
json!({"id":format!("wf-{}-{n}",std::process::id()),
"resume_dir":format!("target/workflow-test-{}-{n}",std::process::id()),
"source_revision":"v1",
"steps":[
{"id":"choose","kind":"model","prompt":"Choose a skill","options":["chat","office"]},
{"id":"answer","kind":"input","question":"OK?","options":["yes","no"]},
{"id":"end","kind":"return"}
]})
}
#[test]
fn nonblocking_model_then_input_then_terminal() {
let a=fixture();
assert_eq!(open(&a).unwrap()["status"],"created");
assert_eq!(next(&a).unwrap()["status"],"waiting_model");
let mut c=a.clone();
c["step_id"]=json!("choose");
c["response"]=json!("office");
assert_eq!(commit(&c).unwrap()["status"],"advanced");
assert_eq!(next(&a).unwrap()["status"],"waiting_input");
assert_eq!(commit(&c).unwrap()["status"],"already_committed");
c["step_id"]=json!("answer");
c["response"]=json!("yes");
assert_eq!(commit(&c).unwrap()["status"],"advanced");
c["step_id"]=json!("end");
c["response"]=json!("ok");
assert_eq!(commit(&c).unwrap()["status"],"succeeded");
assert_eq!(next(&a).unwrap()["status"],"succeeded");
assert_eq!(open(&a).unwrap()["status"],"succeeded");
}
#[test]
fn unknown_and_write_effects_never_auto_dispatch() {
let mut a=fixture();
a["steps"]=json!([{"id":"publish","kind":"skill","skill":"office"}]);
open(&a).unwrap();
assert_eq!(next(&a).unwrap()["status"],"manual_review");
}
#[test]
fn routes_skip_unselected_skill_branches() {
let mut a=fixture();
a["steps"]=json!([
{"id":"decide","kind":"model","prompt":"Pick","options":["chat","office"],
"routes":{"chat":"chat_skill","office":"office_skill"}},
{"id":"chat_skill","kind":"skill","skill":"chat","effect_class":"read","next":"done"},
{"id":"office_skill","kind":"skill","skill":"office","effect_class":"read","next":"done"},
{"id":"done","kind":"return"}
]);
open(&a).unwrap();
let mut c=a.clone();
c["step_id"]=json!("decide");
c["response"]=json!("office");
assert_eq!(commit(&c).unwrap()["cursor"],2);
assert_eq!(next(&a).unwrap()["step"]["id"],"office_skill");
c["step_id"]=json!("office_skill");
c["response"]=json!({"ok":true,"value":{"code":0}});
assert_eq!(commit(&c).unwrap()["cursor"],3);
assert_eq!(next(&a).unwrap()["step"]["id"],"done");
}
#[test]
fn source_change_conflict_and_invalid_model_choice() {
let a=fixture();
open(&a).unwrap();
let mut bad=a.clone();
bad["source_revision"]=json!("v2");
assert_eq!(next(&bad).unwrap()["status"],"not_found_or_mismatched");
assert_eq!(open(&bad).unwrap()["status"],"conflict");
let mut c=a.clone();
c["step_id"]=json!("choose");
c["response"]=json!("chat or office");
assert_eq!(commit(&c).unwrap()["status"],"invalid_choice");
assert_eq!(next(&a).unwrap()["status"],"waiting_model");
}
#[test]
fn partial_children_remain_durable_and_unknown_requires_reconciliation() {
let mut a=fixture();
a["steps"]=json!([{"id":"batch","kind":"parallel","tasks":[{"skill":"a"},{"skill":"b"}]}]);
open(&a).unwrap();
let mut c=a.clone();
c["step_id"]=json!("batch");
c["response"]=json!([
{"ok":true,"value":{"code":0,"value":"useful"}},
{"ok":false,"error":"connection lost"}
]);
assert_eq!(commit(&c).unwrap()["status"],"blocked");
let after=next(&a).unwrap();
assert_eq!(after["status"],"blocked");
assert_eq!(after["partial"]["succeeded"],1);
assert_eq!(after["partial"]["failed"],1);
assert_eq!(commit(&c).unwrap()["status"],"blocked");
}
#[test]
fn retries_only_failed_read_only_children_without_redoing_successes() {
let mut a=fixture();
a["steps"]=json!([{"id":"batch","kind":"parallel","effect_class":"read",
"tasks":[{"path":"a.mq.md"},{"path":"b.mq.md"}]}]);
open(&a).unwrap();
let mut c=a.clone();
c["step_id"]=json!("batch");
c["response"]=json!([
{"ok":true,"value":{"code":0,"value":"keep"}},
{"ok":false,"error":"temporary timeout"}
]);
assert_eq!(commit(&c).unwrap()["status"],"blocked");
let plan=retry_plan(&a).unwrap();
assert_eq!(plan["indices"],json!([1]));
assert_eq!(plan["tasks"].as_array().unwrap().len(),1);
let mut retry=a.clone();
retry["results"]=json!([{"ok":true,"value":{"code":0,"value":"fixed"}}]);
assert_eq!(retry_commit(&retry).unwrap()["status"],"succeeded");
let out=next(&a).unwrap();
assert_eq!(out["completed"][0]["value"]["items"][0]["result"]["value"]["value"],"keep");
assert_eq!(out["completed"][0]["value"]["items"][1]["result"]["value"]["value"],"fixed");
}
#[test]
fn inspect_and_list_are_read_only_and_session_scoped() {
let mut a=fixture();
a["session_id"]=json!("s1");
a["principal_ref"]=json!("u1");
open(&a).unwrap();
let seen=inspect(&a).unwrap();
assert_eq!(seen["status"],"running");
assert_eq!(seen["action"],"waiting_model");
assert_eq!(seen["total_steps"],3);
assert_eq!(seen["completed_steps"],0);
assert_eq!(seen["step"]["id"],"choose");
// Inspection must not consume the current step.
assert_eq!(next(&a).unwrap()["status"],"waiting_model");
let listed=list(&a).unwrap();
assert!(listed["items"].as_array().unwrap()
.iter().any(|x|x["id"]==a["id"]));
let mut other=a.clone();
other["session_id"]=json!("s2");
assert_eq!(inspect(&other).unwrap()["status"],"not_found_or_mismatched");
assert!(list(&other).unwrap()["items"].as_array().unwrap().is_empty());
}
#[test]
fn explicit_cancel_stops_future_commits() {
let a=fixture();
open(&a).unwrap();
assert_eq!(cancel(&a).unwrap()["status"],"cancelled");
let mut c=a.clone();
c["step_id"]=json!("choose");
c["response"]=json!("chat");
assert_eq!(commit(&c).unwrap()["status"],"blocked");
}
}
+25 -3
View File
@@ -32,10 +32,16 @@ fn read_bounded(mut r: impl Read, max: u64) -> Result<Vec<u8>, String> {
if b.len() as u64 > max { return Err("bounded input limit exceeded".into()); } if b.len() as u64 > max { return Err("bounded input limit exceeded".into()); }
Ok(b) Ok(b)
} }
fn strip_verbatim(path: &Path) -> &Path {
path.strip_prefix(r"\\?\").unwrap_or(path)
}
fn scoped(root: &Path, relative: &str) -> Result<PathBuf, String> { fn scoped(root: &Path, relative: &str) -> Result<PathBuf, String> {
let p = root.join(relative).canonicalize().map_err(|_| "path does not exist")?; let p = root.join(relative).canonicalize().map_err(|_| "path does not exist")?;
if !p.starts_with(root) { return Err("artifact path escapes the selected root".into()); } if p.starts_with(root) || strip_verbatim(&p).starts_with(strip_verbatim(root)) {
Ok(p) return Ok(p);
}
Err("artifact path escapes the selected root".into())
} }
fn homes(root: &Path) -> Vec<PathBuf> { fn homes(root: &Path) -> Vec<PathBuf> {
let mut out = Vec::new(); let mut out = Vec::new();
@@ -498,8 +504,24 @@ fn gzip_text(p: &Value) -> Answer {
Ok(json!(String::from_utf8(plain).map_err(|_| "gzip text is not UTF-8")?)) Ok(json!(String::from_utf8(plain).map_err(|_| "gzip text is not UTF-8")?))
} }
fn resolve_root(request: &Value) -> Result<PathBuf, String> {
let raw = request.get("root").and_then(Value::as_str).unwrap_or(".");
let selected = PathBuf::from(raw);
if let Ok(path) = selected.canonicalize() {
return Ok(path);
}
// Relative grants must still resolve when the caller only passed "." and the
// process cwd is the intended checkout (Windows runners are sensitive here).
if raw == "." || raw.is_empty() {
return std::env::current_dir()
.and_then(|p| p.canonicalize())
.map_err(|e| format!("root does not exist ({raw}: {e})"));
}
Err(format!("root does not exist ({raw})"))
}
fn dispatch(request:&Value)->Answer { fn dispatch(request:&Value)->Answer {
let root=PathBuf::from(request.get("root").and_then(Value::as_str).unwrap_or(".")).canonicalize().map_err(|_|"root does not exist")?; let root=resolve_root(request)?;
let op=field(request,"operation")?; let op=field(request,"operation")?;
let empty=json!({});let p=request.get("payload").unwrap_or(&empty); let empty=json!({});let p=request.get("payload").unwrap_or(&empty);
match op { match op {
+7 -6
View File
@@ -15,7 +15,7 @@ import:
This leaf builds source and one platform's native extension archives for an authorized version. It does not publish, choose a version, create a tag or edit version files. The extension-release workflow runs the same tasks on Windows and Linux after local.tag pushes ext-vX.Y.Z. Its attach_ci task creates the exact tagged release through the native service boundary and attaches three assets with the existing gh upload tool; assets.publish subsequently verifies those exact bytes before R2 publication. This leaf builds source and one platform's native extension archives for an authorized version. It does not publish, choose a version, create a tag or edit version files. The extension-release workflow runs the same tasks on Windows and Linux after local.tag pushes ext-vX.Y.Z. Its attach_ci task creates the exact tagged release through the native service boundary and attaches three assets with the existing gh upload tool; assets.publish subsequently verifies those exact bytes before R2 publication.
Build all six maintained native plugins first. The native_dir contract is a directory containing their platform library names, normally target/release. Source discovery and staging use native Marqdo filesystem operations. Only ZIP encoding uses the existing platform tool: Info-ZIP on Linux, the installed bsdtar on Windows. Compiler and format boundaries do not require Python or a generated shell program. Build all six maintained native plugins first. The native_dir contract is a directory containing their platform library names, normally target/release. Source discovery and staging use native Marqdo filesystem operations. Only ZIP encoding uses the existing platform tool: Info-ZIP on Linux, 7-Zip on Windows. Compiler and format boundaries do not require Python or a generated shell program.
## libraries ## libraries
@@ -74,7 +74,7 @@ Return *[Reject an unsupported native target](result.error(code="packs.platform"
Use `stage`, `entry`, `output` and `platform` only after build preflight. Native resolution validates the stage and output paths first; the encoder receives individual arguments and one named staging subtree. It cannot expand a generated shell expression. A failed encoder can leave the selected incomplete archive for inspection; this task never reuses it as successful output or deletes unrelated files. Use `stage`, `entry`, `output` and `platform` only after build preflight. Native resolution validates the stage and output paths first; the encoder receives individual arguments and one named staging subtree. It cannot expand a generated shell expression. A failed encoder can leave the selected incomplete archive for inspection; this task never reuses it as successful output or deletes unrelated files.
The Windows runner supplies bsdtar with ZIP format support; Linux supplies Info-ZIP. Format encoding is the only external operation here. Reads, directory creation, copies, hashes and final ZIP validation remain separate explicit native tasks. The caller removes only its owned temporary stage after the child exits. Existing archives require inspection or a different output directory, keeping reruns from silently replacing publication candidates. The Windows runner supplies 7-Zip with ZIP format support; Linux supplies Info-ZIP. Format encoding is the only external operation here. Reads, directory creation, copies, hashes and final ZIP validation remain separate explicit native tasks. The caller removes only its owned temporary stage after the child exits. Existing archives require inspection or a different output directory, keeping reruns from silently replacing publication candidates.
1. [This output already belongs to an earlier attempt](fs.exists(path=`output`)) 1. [This output already belongs to an earlier attempt](fs.exists(path=`output`))
Return *[Preserve the existing archive](result.error(code="packs.output_exists", message=`output`, operation="_archive"))*. Return *[Preserve the existing archive](result.error(code="packs.output_exists", message=`output`, operation="_archive"))*.
@@ -96,13 +96,14 @@ We **destination = [Resolve the new archive inside the granted root](fs.resolve(
| argument | | argument |
|---| |---|
| tar | | "C:\\Program Files\\7-Zip\\7z.exe" |
| "--format=zip" | | a |
| "-cf" | | "-tzip" |
| `destination` | | `destination` |
| `entry` | | `entry` |
Return *[Encode only the explicitly staged format subtree](engineering.checked(argv=`argv`, cwd=`stage`, timeout_ms=300000, max_output=65536))*. We **checkout = [Use the absolute runtime checkout as the plugin root](sys.cwd())**.
Return *[Encode only the explicitly staged format subtree](engineering.checked(argv=`argv`, cwd=`stage`, timeout_ms=300000, max_output=65536, root=`checkout`))*.
## _receipt ## _receipt
+70
View File
@@ -0,0 +1,70 @@
---
markup: occlusion
title: AI native flow offline smoke
import:
flow: ext/ai/flow.mq.md
context: ext/ai/context.mq.md
json: lib/json.mq.md
sys: lib/sys.mq.md
---
# main
This fixture tests the real Marqdo interface without a model provider.
It refuses an invalid choice and retrieves only the designated function
rather than guessing another SKILL or importing the full document.
**opts = > json.parse text=["chat","office"]**
**pick = > flow.parse_choice reply="选择:office" options=`opts`**
**value = > json.get value=`pick` key="value"**
1. `value` == "office"
**_ = 1**
2. *
**debug_pick = > json.stringify value=`pick`**
> print text=`debug_pick`
> sys.exit code=11
**structured = > flow.parse_choice reply="{\"choice\":\"chat\"}" options=`opts`**
**structure_value = > json.get value=`structured` key="value"**
1. `structure_value` == "chat"
**_ = 1**
2. *
> sys.exit code=16
**invalid = > flow.parse_choice reply="chat 或 office" options=`opts`**
**not_ok = > json.get value=`invalid` key="ok"**
1. `not_ok`
> sys.exit code=12
2. *
**_ = 1**
**ctx = > context.scope scope="function" class="main" function="probe" max_chars=200**
**ok = > json.get value=`ctx` key="ok"**
1. `ok`
**_ = 1**
2. *
> sys.exit code=13
**packed = > context.compose user="Test the route" class="main" function="probe" budget_tokens=2048**
**pack_schema = > json.get value=`packed` key="schema"**
1. `pack_schema` == "ContextPackV2"
**_ = 1**
2. *
> sys.exit code=15
**gate = > flow.input id="ai_native_flow_ci_gate" question="Continue?" options=`opts` source_revision="fixture-v1" freeform=False**
**answered = > flow.reply id="ai_native_flow_ci_gate" reply="office" source_revision="fixture-v1"**
**answer = > json.get value=`answered` key="value"**
1. `answer` == "office"
**_ = 1**
2. *
> sys.exit code=14
Return *"ai-flow-native-ok"*.
## probe
This private helper's narrative should be extracted by the scoped selector
without including the root SKILL or neighboring function definitions.
Return *"probe"*.
+124
View File
@@ -0,0 +1,124 @@
---
markup: occlusion
title: ABI-native durable agent workflow test
import:
workflow: ext/ai/workflow.mq.md
json: lib/json.mq.md
sys: lib/sys.mq.md
time: lib/time.mq.md
---
# main
Offline test: the same Marqdo program advances through model choice, user
input and terminal state with plugin-owned durable checkpoints. The run ID and
checkpoint directory include the current millisecond so repeated local runs
start clean instead of reopening yesterday's completed workflow.
**now = > time.now_ms**
**stamp = > json.stringify value=`now`**
**rid = "abi_flow_ci_" + stamp**
**dir = ".marqdo/ai-native-workflow-" + stamp**
**steps = > json.parse text=[{"id":"intent","kind":"model","prompt":"Choose next skill","options":["chat","office"]},{"id":"confirm","kind":"input","question":"Continue?","options":["yes","no"]},{"id":"end","kind":"return"}]**
**opened = > workflow.open id=`rid` steps=`steps` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**o = > json.get value=`opened` key="ok"**
1. `o`
**_ = 1**
2. *
> sys.exit code=21
**seen = > workflow.inspect id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**seen_status = > json.get value=`seen` key="action"**
**seen_total = > json.get value=`seen` key="total_steps"**
1. `seen_status` == "waiting_model"
1. `seen_total` == 3
**_ = 1**
2. *
> sys.exit code=30
2. *
> sys.exit code=31
**listed = > workflow.list session_id="ci-session" resume_dir=`dir`**
**listed_ok = > json.get value=`listed` key="ok"**
**listed_items = > json.get value=`listed` key="items"**
**listed_n = > len value=`listed_items`**
1. `listed_ok`
1. `listed_n` > 0
**_ = 1**
2. *
> sys.exit code=32
2. *
> sys.exit code=33
**first = > workflow.next id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**first_state = > json.get value=`first` key="status"**
1. `first_state` == "waiting_model"
**_ = 1**
2. *
> sys.exit code=22
**c1 = > workflow.commit id=`rid` step_id="intent" response="chat" source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**done1 = > json.get value=`c1` key="ok"**
1. `done1`
**_ = 1**
2. *
> sys.exit code=23
**progress = > workflow.inspect id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**progress_done = > json.get value=`progress` key="completed_steps"**
1. `progress_done` == 1
**_ = 1**
2. *
> sys.exit code=34
**second = > workflow.tick id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**second_state = > json.get value=`second` key="status"**
1. `second_state` == "waiting_input"
**_ = 1**
2. *
> sys.exit code=24
**c2 = > workflow.commit id=`rid` step_id="confirm" response="yes" source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**done2 = > json.get value=`c2` key="ok"**
1. `done2`
**_ = 1**
2. *
> sys.exit code=25
**c3 = > workflow.tick id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**complete = > workflow.next id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**status = > json.get value=`complete` key="status"**
1. `status` == "succeeded"
**_ = 1**
2. *
> sys.exit code=26
**partial_steps = > json.parse text=[{"id":"children","kind":"parallel","effect_class":"read","tasks":[{"path":"worker-a.mq.md"},{"path":"worker-b.mq.md"}]}]**
**prid = "abi_flow_partial_ci_" + stamp**
**new_batch = > workflow.open id=`prid` steps=`partial_steps` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**parts = > json.parse text=[{"ok":true,"value":{"code":0,"value":"useful"}},{"ok":false,"error":"timeout"}]**
**stopped = > workflow.commit id=`prid` step_id="children" response=`parts` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**reloaded = > workflow.next id=`prid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**partial = > json.get value=`reloaded` key="partial"**
**survivors = > json.get value=`partial` key="succeeded"**
1. `survivors` == 1
**_ = 1**
2. *
> sys.exit code=27
**retry_plan = > workflow.retry_plan id=`prid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**allowed = > json.get value=`retry_plan` key="ok"**
1. `allowed`
**_ = 1**
2. *
> sys.exit code=28
**repaired = > json.parse text=[{"ok":true,"value":{"code":0,"value":"repaired"}}]**
**merged = > workflow.retry_commit id=`prid` results=`repaired` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**merged_ok = > json.get value=`merged` key="ok"**
1. `merged_ok`
**_ = 1**
2. *
> sys.exit code=29
Return *"durable-agent-flow-ok"*.