Compare commits

..
Author SHA1 Message Date
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
cflmy 6d6f580d24 docs: lead with Markdown-to-execution film and original View imagery 2026-11-13 12:06:30 +08:00
github-actions[bot] af05f19301 docs: publish cinematic Markdown-to-execution promotional film 2026-11-13 04:05:04 +00:00
cflmy 3201369470 docs: build cinematic 3-view Markdown execution promotion from original screenshots 2026-11-13 12:04:18 +08:00
cflmy 05197378b3 assets: add original procurement View screenshot and Markdown three-view concept art 2026-11-13 12:01:22 +08:00
github-actions[bot] f3b3152f07 docs: render Marqdo 2.7.1 promotional video from existing assets 2026-11-13 03:35:16 +00:00
cflmy 22364f2f1b feat(docs): add reproducible Marqdo v2.7.1 promotional video editor 2026-11-13 11:34:12 +08:00
35 changed files with 3252 additions and 55 deletions

No files matched your search

@@ -0,0 +1,46 @@
name: Build cinematic Markdown-to-execution video
on:
push:
branches: [docs/markdown-execution-cinematic-v2]
paths:
- "scripts/render-markdown-execution-promo.py"
- ".github/workflows/build-markdown-execution-video.yml"
workflow_dispatch:
permissions:
contents: write
jobs:
video:
if: github.ref_name == 'docs/markdown-execution-cinematic-v2'
runs-on: ubuntu-latest
timeout-minutes: 25
steps:
- uses: actions/checkout@v4
with:
persist-credentials: true
- name: Prepare fonts, Chrome and Python tools
run: |
sudo apt-get update -qq
sudo apt-get install -y -qq ffmpeg fonts-noto-cjk
python -m pip install --quiet pillow numpy markdown-it-py selenium
google-chrome --version
- name: Render promo video from two original images and Marqdo source
run: python scripts/render-markdown-execution-promo.py
- name: Check resulting video
run: |
test -s assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4
test -s assets/marketing/marqdo-2.7.1-markdown-to-execution-cover.jpg
test -s assets/marketing/marqdo-2.7.1-markdown-to-execution.srt
ffprobe -v error -show_entries format=duration,size:stream=codec_name,width,height -of json assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4
- name: Commit compiled video, poster and subtitles
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4 \
assets/marketing/marqdo-2.7.1-markdown-to-execution-cover.jpg \
assets/marketing/marqdo-2.7.1-markdown-to-execution.srt \
assets/marketing/marqdo-procurement-standard-markdown.png
git diff --cached --quiet || git commit -m "docs: publish cinematic Markdown-to-execution promotional film"
git push origin HEAD:docs/markdown-execution-cinematic-v2
@@ -15,6 +15,20 @@ jobs:
run: |
cargo build -p marqdo_plugin_agent --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)
run: |
cargo run --locked -- run tests/ext/ai-native-flow.mq.md --effects plugin,fs.write
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md --effects plugin,fs.write
- name: Workbench contracts (M00–M06 / F-subset)
run: cargo test --test workbench_contracts --locked
- name: Offline executable-knowledge gate
+34
View File
@@ -0,0 +1,34 @@
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 plugin and run native 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
- name: Exercise offline integration through Marqdo
run: |
cargo run --locked -- run tests/ext/ai-native-flow.mq.md --effects plugin,fs.write
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md --effects plugin,fs.write
+43
View File
@@ -0,0 +1,43 @@
name: Build Marqdo promotional video
on:
push:
branches: [docs/promo-video-271]
paths:
- scripts/make-procurement-promo.py
- .github/workflows/promo-video.yml
workflow_dispatch:
permissions:
contents: write
jobs:
build-video:
if: github.ref_name == 'docs/promo-video-271'
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
with:
persist-credentials: true
- name: Prepare video environment
run: |
sudo apt-get update -qq
sudo apt-get install -qq -y ffmpeg fonts-noto-cjk
python -m pip install --quiet --disable-pip-version-check pillow numpy
ffmpeg -version | head -n 2
- name: Compose 32-second Marqdo video
run: python scripts/make-procurement-promo.py
- name: Verify deliverable
run: |
test -s assets/marketing/marqdo-2.7.1-promo.mp4
test -s assets/marketing/marqdo-2.7.1-poster.jpg
test -s assets/marketing/marqdo-2.7.1-promo.srt
ffprobe -v error -show_entries format=duration,size -of default=noprint_wrappers=1 assets/marketing/marqdo-2.7.1-promo.mp4
- name: Commit video into promotional branch
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add assets/marketing/marqdo-2.7.1-promo.mp4 assets/marketing/marqdo-2.7.1-poster.jpg assets/marketing/marqdo-2.7.1-promo.srt
git diff --cached --quiet || git commit -m "docs: render Marqdo 2.7.1 promotional video from existing assets"
git push origin HEAD:docs/promo-video-271
Generated
+1
View File
@@ -668,6 +668,7 @@ version = "0.1.0"
dependencies = [
"chrono",
"marqdo-plugin-sdk",
"pulldown-cmark",
"serde_json",
]
+26 -4
View File
@@ -15,6 +15,7 @@
**Not a prompt wrapper.** The document is interpreted as a program by Marqdo; its tool functions are not merely natural-language instructions.
<p align="center">
<a href="#one-markdown-file-three-views-real-execution">56s film</a> ·
<a href="#quickstart--one-function-one-command">Quickstart</a> ·
<a href="#a-procurement-skill-with-a-600-budget">Procurement demo</a> ·
<a href="#explore-the-view">View</a> ·
@@ -23,9 +24,26 @@
<a href="doc/releases/v2.7.1.md">Release notes</a>
</p>
![Verified Marqdo procurement calls animated from actual CLI results](assets/marketing/procurement-cli.gif)
## One Markdown file. Three views. Real execution.
[![Watch Marqdo 2.7.1 — from Markdown to execution](assets/marketing/marqdo-2.7.1-markdown-to-execution-cover.jpg)](assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4)
**[▶ Watch the 56-second film](assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4)** · [Bilingual captions](assets/marketing/marqdo-2.7.1-markdown-to-execution.srt) · [Reproducible video source](scripts/render-markdown-execution-promo.py)
> **The point is not to invent a new document format.** A `.mq.md` file uses Markdown headings, paragraphs and tables. Ordinary Markdown renderers still show a readable document. Marqdo adds explicit execution semantics and a View that can inspect functions, values and their relationships on the same document.
![Three views, one source — source Markdown, rendered Markdown, executable View](assets/marketing/source-markdown-view-concept.png)
<sub>**Concept artwork** showing the design principle: **source → ordinary Markdown rendering → Marqdo View**. Illustrative labels are not a live execution trace. The video includes [a real View screenshot](assets/marketing/user-procurement-view.png), [a standard Markdown rendering](assets/marketing/marqdo-procurement-standard-markdown.png) produced from the actual procurement source, and a business example verified with the 2.7.1 CLI.</sub>
**One `.mq.md` source, three ways to interact:**
| Source | Standard Markdown | Marqdo runtime + View |
|---|---|---|
| Edit the same Markdown text | Read headings, prose and data tables | Inspect the same document's calls, values and effects |
| No separate prompt or tool implementation specification needed | Works as ordinary readable documentation | Call named functions with `marqdo call` |
<sub>Animated walkthrough assembled from **real Marqdo 2.7.1 function-call results**, including the accepted **simulated** order and an over-budget refusal. Curated frames, not a recording of typing or a production transaction. [Reproduce the capture](scripts/capture-procurement-showcase.py) · [CI run](https://github.com/cflmy/marqdo/actions/runs/43358103498).</sub>
## Quickstart — one function, one command
@@ -44,6 +62,10 @@ The function heading is the callable name. The function's explanation, parameter
This is a **seven-tool, offline demonstration**. It knows the local supplier directory, queries a static price catalog, checks the budget, and conditionally creates a **simulated** work order. It also documents receipt handling, negotiation and supplier switching as unconnected stubs.
![Animated results from real Marqdo 2.7.1 function calls](assets/marketing/procurement-cli.gif)
<sub>**Real CLI results**, edited into a short animation; the accepted order is explicitly **simulated** and never sent. [Capture workflow](scripts/capture-procurement-showcase.py) · [Passing checks](https://github.com/cflmy/marqdo/actions/runs/43358288563).</sub>
```bash
# 1. Approve suppliers: paused or blacklisted entries are excluded.
marqdo call examples/procurement/index.mq.md 查询采购商 "采购商状态='正常'" --json
@@ -79,9 +101,9 @@ Marqdo 2.7.1 improves the interactive reading experience: implementation details
marqdo view examples/procurement --no-open
```
![Actual Marqdo 2.7.1 View screenshot of procurement function](assets/marketing/procurement-view.png)
![Marqdo View — original detailed screenshot provided by the project author](assets/marketing/user-procurement-view.png)
<sub>**Actual screenshot** captured in Chromium from a Marqdo **2.7.1** View static export, scrolled to `向采购商发工单`. It shows the real rendered document, not a promotional mockup. [Screenshot generation source](scripts/capture-procurement-showcase.py).</sub>
<sub>**Original View screenshot provided by the project author.** Notice the natural document typography, values in the margins, and curved connections originating from function calls in the prose. [Additional automated View capture](assets/marketing/procurement-view.png) · [Static Markdown rendering](assets/marketing/marqdo-procurement-standard-markdown.png).</sub>
## One document, multiple uses
Binary file not shown.

After

Width:  |  Height:  |  Size: 132 KiB

@@ -0,0 +1,35 @@
1
00:00:00,000 --> 00:00:04,800
Your SKILL is now a TOOL.
让 Markdown 直接承载可执行语义。
2
00:00:04,800 --> 00:00:11,600
源码态:标题、段落、表格都沿用 Markdown。
执行逻辑就在文档之中。
3
00:00:11,600 --> 00:00:18,000
渲染态:同一份代码也能成为普通 Markdown 文档。
4
00:00:18,000 --> 00:00:25,000
源码态、标准 Markdown 渲染态、Marqdo View 态。
三种视图,同一份源文件。
5
00:00:25,000 --> 00:00:32,500
一份 .mq.md,既可以阅读,也可以编译执行。
6
00:00:32,500 --> 00:00:42,000
真实 View 截图:函数调用和值沿着优雅曲线呈现。
7
00:00:42,000 --> 00:00:50,800
预算校验不是文字承诺,而是函数执行。
模拟订单通过或拒绝,均由运行时返回结果。
8
00:00:50,800 --> 00:00:56,000
Marqdo 2.7.1 · github.com/cflmy/marqdo
Binary file not shown.

After

Width:  |  Height:  |  Size: 78 KiB

Binary file not shown.
+29
View File
@@ -0,0 +1,29 @@
1
00:00:00,000 --> 00:00:03,900
Your SKILL is now a TOOL.
让 SKILL 真正成为工具。
2
00:00:03,900 --> 00:00:09,000
One readable document. Callable business logic.
规则、数据、工具在同一份文档里。
3
00:00:09,000 --> 00:00:17,400
Five verified CLI calls, from quote to decision.
真实 CLI 结果:询价、预算、模拟发单。
4
00:00:17,400 --> 00:00:23,400
¥120 spent: mock order. ¥360 spent: rejected.
¥120 时模拟通过;¥360 时预算不足。
5
00:00:23,400 --> 00:00:29,000
Inspect the actual document in Marqdo View.
查看 Marqdo 真实 View 页面。
6
00:00:29,000 --> 00:00:32,000
github.com/cflmy/marqdo
开源 · Marqdo 2.7.1
Binary file not shown.

After

Width:  |  Height:  |  Size: 161 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.9 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 523 KiB

+131
View File
@@ -0,0 +1,131 @@
# 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 |
The native agent plugin provides `agent_choice_parse`, `agent_context_scope`,
`agent_input_open`, `agent_input_resume` and `agent_parallel_report`.
Plugin errors must be visible, never converted into a fabricated successful answer.
## 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/commit/cancel`.
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.
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.
+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`))*.
+5 -1
View File
@@ -9,7 +9,11 @@ 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
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)
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; [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).
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`))*.
+245
View File
@@ -0,0 +1,245 @@
---
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.
## 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 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Created, resumed, or explicit conflict |
Use `id`, `steps`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation.
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`))*.
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 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Current action or terminal state |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation.
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`))*.
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 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Committed next step or explicit failure |
Use `id`, `step_id`, `response`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation.
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`))*.
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 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Cancelled checkpoint status |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation.
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`))*.
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 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 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 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.
We retain **state = [Load the next action](next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))**.
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`))*.
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`))*.
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`))*.
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`))*.
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 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Failed-only read-task list or manual_review |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None 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`))*.
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 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Merged persistent report, or still blocked |
Use `id`, `results`, `source_revision`, `session_id`=None, `principal_ref`=None 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`))*.
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 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Recovered workflow, partial results or manual review |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `limit`=2, `timeout_ms`=30000 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`))**.
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`))*.
2. *
Return *plan*.
+1
View File
@@ -13,4 +13,5 @@ crate-type = ["cdylib"]
[dependencies]
marqdo-plugin-sdk = { path = "../../crates/marqdo-plugin-sdk" }
serde_json = "1"
pulldown-cmark = "0.12"
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}"))
}
static EFFECT_TEMP_SEQUENCE: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> {
let parent = path
.parent()
@@ -102,7 +104,8 @@ fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> {
.and_then(|s| s.to_str())
.unwrap_or("op.json"),
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 text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?;
@@ -425,12 +428,16 @@ fn fnv64(s: &str) -> u64 {
mod tests {
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 {
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-{}-{}-{}",
tag,
std::process::id(),
now_rfc3339().replace(':', "")
tag, std::process::id(), seq
));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
@@ -440,14 +447,13 @@ mod tests {
#[test]
fn prepare_dedupe_and_collision() {
let dir = scratch("prep");
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
let ledger_dir = dir.join("led").to_string_lossy().to_string();
let a = effects_prepare(&json!({
"operation_id": "op1",
"idempotency_key": "idem1",
"args_digest": "sha256:a",
"effect_class": "write",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
"logical_run_id": "run1",
}))
.unwrap();
@@ -458,7 +464,7 @@ mod tests {
"operation_id": "op1",
"idempotency_key": "idem1",
"args_digest": "sha256:a",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
}))
.unwrap();
assert_eq!(again["deduped"], true);
@@ -467,43 +473,41 @@ mod tests {
"operation_id": "op2",
"idempotency_key": "idem1",
"args_digest": "sha256:b",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
}));
assert!(clash.unwrap_err().contains("collision"));
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir);
}
#[test]
fn transition_and_watermark_gates_write_resume() {
let dir = scratch("wm");
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
let ledger_dir = dir.join("led").to_string_lossy().to_string();
effects_prepare(&json!({
"operation_id": "op_w",
"idempotency_key": "idem_w",
"args_digest": "sha256:w",
"effect_class": "write",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
"logical_run_id": "run1",
}))
.unwrap();
effects_transition(&json!({
"operation_id": "op_w",
"state": "started",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
}))
.unwrap();
// Crash window: unknown — write auto-resume must stay closed.
effects_transition(&json!({
"operation_id": "op_w",
"state": "unknown",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
}))
.unwrap();
let wm1 = effects_watermark(&json!({
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
"logical_run_id": "run1",
}))
.unwrap();
@@ -513,12 +517,12 @@ mod tests {
effects_reconcile(&json!({
"operation_id": "op_w",
"outcome": "committed",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
"result_ref": "receipt:1",
}))
.unwrap();
let wm2 = effects_watermark(&json!({
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
"logical_run_id": "run1",
}))
.unwrap();
@@ -526,7 +530,6 @@ mod tests {
assert_eq!(wm2["open_unknown"], 0);
assert!(wm2["watermark"].as_str().unwrap().starts_with("sha256-lite:"));
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir);
}
@@ -535,32 +538,31 @@ mod tests {
// Write "succeeds" locally only after reconcile; retry while unknown must not
// look write_auto_resume_safe (MA-T03 watermark gate).
let dir = scratch("mat03");
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
let ledger_dir = dir.join("led").to_string_lossy().to_string();
effects_prepare(&json!({
"operation_id": "op_kill",
"idempotency_key": "run|s|write_probe|sha256-lite:1",
"args_digest": "sha256-lite:1",
"effect_class": "write",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
"logical_run_id": "run_kill",
}))
.unwrap();
effects_transition(&json!({
"operation_id": "op_kill",
"state": "started",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
}))
.unwrap();
// Crash before commit:
effects_transition(&json!({
"operation_id": "op_kill",
"state": "unknown",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
}))
.unwrap();
let wm = effects_watermark(&json!({
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
"logical_run_id": "run_kill",
}))
.unwrap();
@@ -572,7 +574,7 @@ mod tests {
"idempotency_key": "run|s|write_probe|sha256-lite:1",
"args_digest": "sha256-lite:1",
"effect_class": "write",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
"logical_run_id": "run_kill",
}))
.unwrap();
@@ -582,42 +584,39 @@ mod tests {
effects_reconcile(&json!({
"operation_id": "op_kill",
"outcome": "committed",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
"result_ref": "effect:op_kill",
}))
.unwrap();
let wm2 = effects_watermark(&json!({
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
"logical_run_id": "run_kill",
}))
.unwrap();
assert_eq!(wm2["write_auto_resume_safe"], true);
assert_eq!(wm2["pending_writes"], 0);
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir);
}
#[test]
fn illegal_skip_started() {
let dir = scratch("bad");
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
let ledger_dir = dir.join("led").to_string_lossy().to_string();
effects_prepare(&json!({
"operation_id": "op_x",
"idempotency_key": "idem_x",
"args_digest": "sha256:x",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
}))
.unwrap();
let err = effects_transition(&json!({
"operation_id": "op_x",
"state": "committed",
"ledger_dir": "led",
"ledger_dir": ledger_dir.clone(),
}))
.unwrap_err();
assert!(err.contains("illegal transition"));
std::env::set_current_dir(prev).unwrap();
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")
.and_then(|v| v.as_u64())
.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
.get("effect_class")
.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(
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(
"needs_input",
category,
@@ -172,13 +182,17 @@ fn decision(action: &str, reason: &str, attempts: u32, max_attempts: u32) -> Val
"reason": reason,
"attempts_used": 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 {
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"
} else if c.contains("schema") || c.contains("argument") {
"invalid_arguments"
@@ -212,6 +226,8 @@ fn default_recovery(category: &str, effect_state: &str) -> &'static str {
match category {
"transient" => "retry_step",
"invalid_arguments" => "repair_args",
"invalid_output" => "repair_output",
"context_overflow" => "compact_context",
"auth" | "forbidden" | "policy_denied" | "needs_input" => "needs_input",
"budget_exhausted" => "return_partial",
"cancelled" => "stop",
@@ -259,6 +275,27 @@ mod tests {
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]
fn fingerprint_loop_stops() {
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");
}
}
+27
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.
mod choice;
mod context_pack;
mod context_scope;
mod corpus;
mod effects;
mod eng;
mod error;
mod input;
mod kb;
mod mcp_client;
mod mcp_server;
mod memory;
mod output;
mod parallel;
mod resume;
mod route;
mod sandbox;
mod tools;
mod workflow;
use std::collections::HashMap;
use std::ffi::CString;
@@ -834,6 +839,17 @@ kb_ffi!(agent_resume_save, resume::resume_save, "agent_resume_save");
kb_ffi!(agent_resume_load, resume::resume_load, "agent_resume_load");
kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear");
kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list");
kb_ffi!(agent_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_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_decide_retry, error::decide_retry, "agent_error_decide_retry");
kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register");
@@ -963,6 +979,17 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
("agent_resume_load", "id,resume_dir", agent_resume_load),
("agent_resume_clear", "id,resume_dir", agent_resume_clear),
("agent_resume_list", "resume_dir", agent_resume_list),
("agent_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", agent_workflow_open),
("agent_workflow_next", "id,source_revision", agent_workflow_next),
("agent_workflow_commit", "id,step_id,response,source_revision", agent_workflow_commit),
("agent_workflow_cancel", "id,source_revision", agent_workflow_cancel),
("agent_workflow_retry_plan", "id,source_revision", agent_workflow_retry_plan),
("agent_workflow_retry_commit", "id,results,source_revision", agent_workflow_retry_commit),
("agent_error_make", "code,message,category", agent_error_make),
("agent_error_decide_retry", "error,attempts,effect_class", agent_error_decide_retry),
("agent_tools_register", "spec,specs", agent_tools_register),
+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.
static TEMP_SEQUENCE: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> {
let parent = path
.parent()
@@ -96,7 +98,8 @@ fn atomic_write_json(path: &Path, doc: &Value) -> Result<(), String> {
.and_then(|s| s.to_str())
.unwrap_or("ckpt.json"),
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 text = serde_json::to_string_pretty(doc).map_err(|e| e.to_string())?;
@@ -396,7 +399,8 @@ mod tests {
.duration_since(UNIX_EPOCH)
.unwrap()
.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();
dir
}
@@ -410,10 +414,7 @@ mod tests {
#[test]
fn atomic_v2_roundtrip_and_legacy_manual_review() {
let dir = scratch("v2");
// Use relative path via env cwd — chdir into scratch for this test.
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
let rel = "ckpts";
let rel = dir.join("ckpts").to_string_lossy().to_string();
let saved = resume_save(&json!({
"id": "run1",
"schema": "CheckpointV2",
@@ -491,23 +492,20 @@ mod tests {
assert_eq!(unsafe_ck["recovery_mode"], "checkpoint_v2_read_only");
assert_eq!(unsafe_ck["write_auto_resume"], false);
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir);
}
#[test]
fn corrupt_checkpoint_reports_error() {
let dir = scratch("corrupt");
let prev = std::env::current_dir().unwrap();
std::env::set_current_dir(&dir).unwrap();
fs::create_dir_all("ckpts").unwrap();
fs::write("ckpts/bad.json", "{not-json").unwrap();
let loaded = resume_load(&json!({"id": "bad", "resume_dir": "ckpts"})).unwrap();
let ckpts = dir.join("ckpts");
fs::create_dir_all(&ckpts).unwrap();
fs::write(ckpts.join("bad.json"), "{not-json").unwrap();
let loaded = resume_load(&json!({"id": "bad", "resume_dir": ckpts.to_string_lossy()})).unwrap();
assert_eq!(loaded["found"], true);
assert_eq!(loaded["ok"], false);
assert_eq!(loaded["error"]["code"], "checkpoint.corrupt");
assert_eq!(loaded["recovery_mode"], "manual_review");
std::env::set_current_dir(prev).unwrap();
let _ = fs::remove_dir_all(&dir);
}
}
+591
View File
@@ -0,0 +1,591 @@
//! 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)
}
/// 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 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");
}
}
+369
View File
@@ -0,0 +1,369 @@
#!/usr/bin/env python3
"""Make a 16:9 Marqdo promotional video from checked-in repository assets.
Inputs: GIF generated from actual v2.7.1 CLI results, and screenshot captured
from actual v2.7.1 View. The budget scenario is explicitly simulated.
Everything used to reproduce this movie is in the repository.
No third-party soundtrack or music clips are used.
"""
from __future__ import annotations
import math
import os
import subprocess
import tempfile
import wave
from bisect import bisect_right
from pathlib import Path
import numpy as np
from PIL import Image, ImageDraw, ImageFont, ImageOps
ROOT = Path(__file__).resolve().parents[1]
ASSETS = ROOT / "assets" / "marketing"
GIF = ASSETS / "procurement-cli.gif"
VIEW = ASSETS / "procurement-view.png"
PROC = ROOT / "examples" / "procurement" / "index.mq.md"
OUT = ASSETS / "marqdo-2.7.1-promo.mp4"
POSTER = ASSETS / "marqdo-2.7.1-poster.jpg"
SUBTITLES = ASSETS / "marqdo-2.7.1-promo.srt"
W, H, FPS = 1280, 720, 24
DURATION = 32.0
CUTS = [0.0, 3.9, 9.0, 17.4, 23.4, 29.0, DURATION]
DARK = (11, 19, 32)
GOLD = (232, 187, 123)
LIGHT = (248, 246, 238)
MUTED = (155, 174, 197)
GREEN = (125, 224, 174)
RED = (251, 151, 155)
def rgb(c):
return tuple(c)
def choose_font(size, bold=False, serif=False):
paths = [
"/usr/share/fonts/opentype/noto/NotoSerifCJK-Bold.ttc" if serif and bold else "",
"/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc" if serif else "",
"/usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc" if bold else "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf" if bold else "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
]
for p in paths:
if not p:
continue
try:
return ImageFont.truetype(p, size)
except OSError:
continue
return ImageFont.load_default()
F = {
"hero": choose_font(72, True),
"big": choose_font(55, True),
"h1": choose_font(42, True),
"h2": choose_font(31, True),
"mid": choose_font(25, True),
"code": choose_font(23),
"body": choose_font(22),
"small": choose_font(17),
"micro": choose_font(14),
"zh": choose_font(28, serif=True),
}
def text(draw, xy, msg, font, color=LIGHT, anchor=None):
draw.text(xy, str(msg), font=font, fill=color, anchor=anchor)
def panel(draw, xy, fill=(24,35,54), outline=(51,67,89), rad=23, width=2):
draw.rounded_rectangle(xy, radius=rad, fill=fill, outline=outline, width=width)
def mix(a, b, t):
return a + (b-a)*t
def ease(x):
u = max(0., min(1., x))
return u*u*(3-2*u)
def appear(t, delay=0., span=.65):
return ease((t-delay)/span)
def xshift(t, delay=.0):
return int(38*(1-appear(t,delay)))
def opacity_overlay(base, overlay, alpha):
return Image.blend(base, overlay, max(0.,min(1.,alpha)))
def clipped(src, size, center=(.5,.5), zoom=1):
w,h=size
if zoom > 1:
p=ImageOps.fit(src,(int(w*zoom),int(h*zoom)),method=Image.Resampling.LANCZOS,centering=center)
z=(p.width-w)//2
v=(p.height-h)//2
return p.crop((z,v,z+w,v+h))
return ImageOps.fit(src,size,method=Image.Resampling.LANCZOS,centering=center)
def background(seed=0):
im = Image.new("RGB",(W,H),DARK)
pix=im.load()
for y in range(H):
for x in range(W):
glow= max(0,1-math.hypot((x-1090)/1.3,(y-95)/1.1)/520)
edge= max(0,1-math.hypot((x-25),y-690)/500)
pix[x,y]=(int(11+14*glow+7*edge),int(19+9*glow+7*edge),int(32+13*glow+10*edge))
d=ImageDraw.Draw(im)
for x in range(45,W,82):
d.line((x,0,x,H),fill=(18,29,45),width=1)
for y in range(48,H,82):
d.line((0,y,W,y),fill=(18,29,45),width=1)
return im
BG=background()
def base_frame(t,scene):
im=BG.copy()
d=ImageDraw.Draw(im)
# top identity, bottom running progress
text(d,(63,35),"MARQDO",F["small"],GOLD)
text(d,(168,36),"/ EXECUTABLE AI SKILLS",F["micro"],MUTED)
d.rounded_rectangle((1079,21,1211,57),radius=15,fill=(40,51,68))
text(d,(1095,30),"v2.7.1",F["small"],LIGHT)
d.line((62,76,1214,76),fill=(48,61,80),width=2)
d.line((62,694,1214,694),fill=(47,61,80),width=2)
d.line((62,694,62+int((1152)*(t/DURATION)),694),fill=GOLD,width=4)
text(d,(64,705),"DOCUMENT → FUNCTION → TOOL",F["micro"],(104,120,141))
text(d,(1115,705),"%02d / 06" % (scene+1),F["micro"],(104,120,141))
return im,d
def scene_hero(local,global_t):
im,d=base_frame(global_t,0)
a=appear(local,.07)
yy=xshift(local,.08)
text(d,(69,167+yy),"Your SKILL",F["hero"],LIGHT)
text(d,(69,264+yy),"is now a",F["hero"],LIGHT)
text(d,(69,361+yy),"TOOL.",F["hero"],GOLD)
# typographic bar
x=69
d.rounded_rectangle((x,485,x+min(643,int(643*a)),489),radius=2,fill=GOLD)
text(d,(71,520),"Write it. Inspect it. Call it.",F["mid"],LIGHT)
text(d,(71,573),"让可读文档中的函数,真正成为可调用工具。",F["zh"],(224,219,205))
d.rounded_rectangle((975,207,1169,493),radius=25,fill=(26,37,57),outline=(84,99,118),width=2)
text(d,(1017,276),".mq.md",F["h2"],GOLD)
text(d,(1017,357),"01 Read",F["small"],MUTED)
text(d,(1017,399),"02 Call",F["small"],MUTED)
text(d,(1017,441),"03 Check",F["small"],MUTED)
return im
SOURCE_LINES=[
"## 向采购商发工单",
"采购商标识符 数量 单价 已花费",
"",
"正常商户 = 查询采购商(...)",
"报价 = 查询采购商价格(...)",
"预算 = 查询余额(已花费=...)",
"",
"1. 剩余额度 < 本单金额",
" → 拒绝模拟工单",
]
def scene_source(local,global_t):
im,d=base_frame(global_t,1)
text(d,(71,110),"ONE DOCUMENT.",F["h1"],LIGHT)
text(d,(71,159),"Contract, data, policy and implementation in the same .mq.md.",F["body"],MUTED)
panel(d,(67,205,842,642),fill=(18,28,44),outline=(72,91,113))
d.rounded_rectangle((67,205,842,254),radius=17,fill=(35,48,67))
text(d,(93,218),"index.mq.md / procurement skill",F["small"],GOLD)
ready=int(len(SOURCE_LINES)*ease((local-.40)/3.8))
for i,ln in enumerate(SOURCE_LINES[:ready]):
clr=GOLD if i in (0,7) else GREEN if i==8 else (178,204,232)
text(d,(101,279+i*37),ln,F["code"],clr)
panel(d,(863,205,1214,642),fill=(24,35,55),outline=(74,88,107))
for j,(label,desc) in enumerate([
("01 READ","human-readable"),
("02 CHECK","typed contracts"),
("03 CALL","marqdo call"),
("04 RETURN","structured values")
]):
y=268+j*96
d.rounded_rectangle((888,y,1187,y+66),radius=13,fill=(30,48,65))
text(d,(907,y+11),label,F["small"],GOLD)
text(d,(907,y+34),desc,F["micro"],(186,203,220))
text(d,(71,662),"Excerpt simplified for screen layout; the full source is linked in the repository.",F["micro"],(110,135,154))
return im
GIF_FRAMES=[]
GIF_DURATIONS=[]
if GIF.exists():
im=Image.open(GIF)
for i in range(getattr(im,"n_frames",1)):
im.seek(i)
GIF_FRAMES.append(im.convert("RGB").copy())
GIF_DURATIONS.append(max(.3, im.info.get("duration",1600)/1000))
if len(GIF_FRAMES) < 5:
raise RuntimeError(f"Expected >= 5 real CLI demonstration frames, found {len(GIF_FRAMES)}")
else:
raise FileNotFoundError(GIF)
GIF_CUM=[0.]
for dur in GIF_DURATIONS:
GIF_CUM.append(GIF_CUM[-1]+dur)
GIF_CYCLE=GIF_CUM[-1]
GIF_FITTED=[clipped(im,(1136,620)) for im in GIF_FRAMES]
def scene_cli(local,global_t):
im,d=base_frame(global_t,2)
# The 5 panels are constructed from real calls and validated in the original capture script.
k=min(len(GIF_FITTED)-1,bisect_right(GIF_CUM,(local+.3)%GIF_CYCLE)-1)
im.paste(GIF_FITTED[k],(72,73))
d=ImageDraw.Draw(im)
d.rectangle((73,73,1210,113),fill=(15,24,37))
text(d,(91,82),"REAL CLI RETURNS / CURATED ANIMATED WALKTHROUGH",F["small"],GOLD)
d.rectangle((76,664,1206,688),fill=(15,24,37))
text(d,(87,665),"Supplier → Quote → Balance → Mock order → Over-budget refusal",F["small"],LIGHT)
return im
def scene_outcomes(local,global_t):
im,d=base_frame(global_t,3)
text(d,(70,113),"THE LIMIT IS EXECUTED.",F["h1"])
text(d,(70,164),"Two calls. Same unit price. Different accumulated spend.",F["body"],MUTED)
q=ease((local-.6)/1.5)
left=120+int(288*q)
right=360+int(288*q)
panel(d,(70,219,616,610),fill=(17,49,43),outline=(69,124,102))
panel(d,(652,219,1202,610),fill=(55,29,39),outline=(150,78,90))
text(d,(99,253),"ALLOWED · SIMULATION",F["small"],GREEN)
text(d,(681,253),"DENIED · RUNTIME CHECK",F["small"],RED)
text(d,(99,304),"¥120 + ¥288",F["h2"],LIGHT)
text(d,(681,304),"¥360 + ¥288",F["h2"],LIGHT)
text(d,(99,396),"¥"+str(left),F["hero"],GREEN)
text(d,(681,396),"¥"+str(right),F["hero"],RED)
text(d,(103,445),"≤ ¥600",F["mid"],(196,239,212))
text(d,(686,445),"> ¥600",F["mid"],(255,202,211))
d.line((100,476,581,476),fill=(77,119,101),width=2)
d.line((681,476,1170,476),fill=(135,80,90),width=2)
text(d,(101,497),"ok: true",F["mid"],GREEN)
text(d,(680,497),"ok: false",F["mid"],RED)
text(d,(101,553),"本地模拟,未发送",F["body"],(211,233,220))
text(d,(680,553),"采购金额超过剩余额度",F["body"],(251,213,217))
text(d,(71,651),"The function re-checks its own budget constraints. This is an offline example, not a real purchase.",F["micro"],MUTED)
return im
VIEW_IMAGE=Image.open(VIEW).convert("RGB")
VIEW_PANEL=(101,195,1179,635)
VIEW_MASK=Image.new("L",(VIEW_PANEL[2]-VIEW_PANEL[0],VIEW_PANEL[3]-VIEW_PANEL[1]),0)
ImageDraw.Draw(VIEW_MASK).rounded_rectangle((0,0,VIEW_MASK.width-1,VIEW_MASK.height-1),radius=18,fill=255)
def scene_view(local,global_t):
im,d=base_frame(global_t,4)
text(d,(70,111),"THE SAME SOURCE, BEAUTIFULLY INSPECTABLE.",F["h2"])
text(d,(71,158),"Marqdo 2.7.1 View — an actual screenshot of the procurement function.",F["body"],MUTED)
factor=1+.06*ease(local/5)
content=clipped(VIEW_IMAGE,(VIEW_MASK.width,VIEW_MASK.height),center=(.50,.38),zoom=factor)
im.paste(content,(VIEW_PANEL[0],VIEW_PANEL[1]),VIEW_MASK)
d=ImageDraw.Draw(im)
d.rounded_rectangle(VIEW_PANEL,radius=18,outline=(199,165,118),width=3)
text(d,(104,665),"From marqdo view output • function 向采购商发工单",F["small"],(187,207,222))
return im
def scene_outro(local,global_t):
im,d=base_frame(global_t,5)
text(d,(71,163),"One .mq.md",F["hero"],LIGHT)
text(d,(71,260),"Many ways to use it.",F["h1"],GOLD)
d.rounded_rectangle((70,365,1212,436),radius=19,fill=(33,49,67),outline=(81,101,124),width=2)
text(d,(107,381),"Write it. Inspect it. Call it.",F["h2"],LIGHT)
text(d,(73,490),"github.com/cflmy/marqdo",F["h1"],GOLD)
text(d,(73,548),"Marqdo 2.7.1 • Rust-based document-native runtime",F["body"],MUTED)
text(d,(73,613),"Demo uses simulated supplier data. No ERP connection or actual purchase.",F["small"],(176,190,204))
return im
SCENE_FNS=[scene_hero,scene_source,scene_cli,scene_outcomes,scene_view,scene_outro]
def render(t):
i=min(len(SCENE_FNS)-1,bisect_right(CUTS,t)-1)
im=SCENE_FNS[i](t-CUTS[i],t)
end=CUTS[i+1]
if i<len(SCENE_FNS)-1 and t > end-.43:
other=SCENE_FNS[i+1](0,t)
im=Image.blend(im,other,ease((t-(end-.43))/.43))
return im
def make_audio(path):
sr=24000
count=round(DURATION*sr)
times=np.arange(count,dtype=np.float64)/sr
signal=np.zeros(count,dtype=np.float64)
chords=[(110.0,164.8,220.0),(123.5,185.0,246.9),(130.8,196.0,261.6),(110.0,174.6,220.0),(123.5,185.0,246.9),(130.8,196.0,261.6)]
for idx in range(6):
start,end=CUTS[idx],CUTS[idx+1]
mask=(times>=start)&(times<end)
t=times[mask]-start
fade=np.minimum(1,np.minimum(t/.8, (end-start-t)/.85).clip(min=0))
notes=chords[idx]
wavepad=(np.sin(2*np.pi*notes[0]*t)*0.54+
np.sin(2*np.pi*notes[1]*t)*0.18+
np.sin(2*np.pi*notes[2]*t)*0.12)
signal[mask] += 0.12*fade*wavepad
for at in CUTS[:-1]:
start=int(at*sr)
length=int(.16*sr)
n=np.arange(length,dtype=np.float64)/sr
chirp=(np.sin(2*np.pi*(640*n+680*n*n))*np.exp(-24*n))*0.12
signal[start:start+length] += chirp
signal *= np.minimum(1,np.minimum(times/1.2, (DURATION-times)/1.2).clip(min=0))
pcm=np.clip(signal*32767,-32767,32767).astype(np.int16)
with wave.open(str(path),"wb") as wav:
wav.setnchannels(1);wav.setsampwidth(2);wav.setframerate(sr)
wav.writeframes(pcm.tobytes())
def make_srt():
times=[("00:00:00,000","00:00:03,900","Your SKILL is now a TOOL.\n让 SKILL 真正成为工具。"),
("00:00:03,900","00:00:09,000","One readable document. Callable business logic.\n规则、数据、工具在同一份文档里。"),
("00:00:09,000","00:00:17,400","Five verified CLI calls, from quote to decision.\n真实 CLI 结果:询价、预算、模拟发单。"),
("00:00:17,400","00:00:23,400","¥120 spent: mock order. ¥360 spent: rejected.\n¥120 时模拟通过;¥360 时预算不足。"),
("00:00:23,400","00:00:29,000","Inspect the actual document in Marqdo View.\n查看 Marqdo 真实 View 页面。"),
("00:00:29,000","00:00:32,000","github.com/cflmy/marqdo\n开源 · Marqdo 2.7.1")]
txt="\n\n".join(f"{i+1}\n{a} --> {b}\n{c}" for i,(a,b,c) in enumerate(times))+"\n"
SUBTITLES.write_text(txt,encoding="utf-8")
def main():
if not PROC.exists() or not VIEW.exists():
raise FileNotFoundError("Expected procurement source and actual View screenshot")
source=PROC.read_text("utf-8")
assert "## 向采购商发工单" in source and "查询余额" in source
assert VIEW_IMAGE.width >= 1200 and VIEW_IMAGE.height >= 700
OUT.parent.mkdir(parents=True,exist_ok=True)
POSTER_IMG=render(1.8)
POSTER_IMG.save(POSTER,quality=92,optimize=True)
make_srt()
frames=int(DURATION*FPS)
with tempfile.TemporaryDirectory() as tmp:
unscored=Path(tmp)/"silent.mp4"
music=Path(tmp)/"music.wav"
cmd=["ffmpeg","-y","-hide_banner","-loglevel","error","-f","rawvideo",
"-pixel_format","rgb24","-video_size",f"{W}x{H}","-framerate",str(FPS),
"-i","pipe:0","-an","-c:v","libx264","-preset","veryfast","-crf","21",
"-pix_fmt","yuv420p","-movflags","+faststart",str(unscored)]
proc=subprocess.Popen(cmd,stdin=subprocess.PIPE,stderr=subprocess.PIPE)
try:
for k in range(frames):
fr=render(k/FPS)
proc.stdin.write(fr.tobytes())
if k%120==0:
print("rendered",k,"/",frames,flush=True)
finally:
if proc.stdin:
proc.stdin.close()
stderr=proc.stderr.read().decode(errors="replace")
rc=proc.wait(timeout=70)
if rc:
raise RuntimeError("Video encoder error: "+stderr)
make_audio(music)
subprocess.run(["ffmpeg","-y","-hide_banner","-loglevel","error",
"-i",str(unscored),"-i",str(music),"-c:v","copy","-c:a",
"aac","-b:a","128k","-shortest","-movflags","+faststart",
str(OUT)],check=True,timeout=90)
print("VIDEO_WRITTEN",OUT,OUT.stat().st_size,flush=True)
print("POSTER_WRITTEN",POSTER,POSTER.stat().st_size,flush=True)
print("SUBTITLES_WRITTEN",SUBTITLES,SUBTITLES.stat().st_size,flush=True)
ffprobe=subprocess.run(["ffprobe","-v","error","-show_entries",
"format=duration,size:stream=codec_name,width,height",
"-of","json",str(OUT)],capture_output=True,text=True,check=True)
print("FFPROBE",ffprobe.stdout,flush=True)
assert OUT.stat().st_size>1000000, "Suspiciously small encoded video"
if __name__=="__main__":
main()
+251
View File
@@ -0,0 +1,251 @@
#!/usr/bin/env python3
"""Rebuild the Marqdo Markdown → View → execution promotional film.
Source imagery:
- assets/marketing/user-procurement-view.png: original user-provided View capture
- assets/marketing/source-markdown-view-concept.png: original generated concept art
Other images are generated from the repository's actual procurement source.
The purchasing demo is simulated, not an ERP transaction.
"""
from pathlib import Path
import math, subprocess, wave, tempfile
import numpy as np
from PIL import Image, ImageDraw, ImageFont, ImageFilter, ImageOps
from markdown_it import MarkdownIt
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
ROOT=Path(__file__).resolve().parents[1]
A=ROOT/"assets"/"marketing"
OUT=A/"marqdo-2.7.1-markdown-to-execution.mp4"
POSTER=A/"marqdo-2.7.1-markdown-to-execution-cover.jpg"
SRT=A/"marqdo-2.7.1-markdown-to-execution.srt"
W,H=1600,900
D=[4.8,6.8,6.4,7.0,7.5,9.5,8.8,5.2]
IVORY=(249,247,242);INK=(37,35,34);GOLD=(191,146,81);PEARL=(242,232,214);DIM=(122,114,105);NIGHT=(18,23,32)
REG="/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc"
BOLD="/usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc"
SERIF="/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc"
SERIFB="/usr/share/fonts/opentype/noto/NotoSerifCJK-Bold.ttc"
def f(size,mode="regular"):
return ImageFont.truetype({"regular":REG,"bold":BOLD,"serif":SERIF,"serifbold":SERIFB}[mode],size)
def txt(d,xy,s,size=26,color=INK,style="regular"):
d.text(xy,str(s),font=f(size,style),fill=color)
def card(d,box,fill=IVORY,stroke=(220,210,195),r=24):
d.rounded_rectangle(box,radius=r,fill=fill,outline=stroke,width=2)
def base(dark=False):
im=Image.new("RGB",(W,H),NIGHT if dark else IVORY)
d=ImageDraw.Draw(im)
if dark:
for j in range(8):
d.arc((880+j*32,-200+j*26,1760+j*28,1030+j*25),158,268,fill=(68+j*7,60+j*6,51+j*4),width=2)
else:
for j in range(7):
d.arc((-430+j*14,-500+j*14,500+j*25,520+j*25),35,150,fill=(238,224+j*2,207+j*2),width=2)
return im
def rounded_image(im,src,box,focus=(.5,.5)):
x1,y1,x2,y2=box
crop=ImageOps.fit(src,(x2-x1,y2-y1),method=Image.Resampling.LANCZOS,centering=focus)
mask=Image.new("L",crop.size,0)
ImageDraw.Draw(mask).rounded_rectangle((0,0,crop.width-1,crop.height-1),radius=18,fill=255)
im.paste(crop,(x1,y1),mask)
ImageDraw.Draw(im).rounded_rectangle(box,radius=18,outline=(200,177,145),width=2)
def footer(d,text,dark=False):
txt(d,(80,855),text,18,(148,158,171) if dark else DIM)
def make_intro():
im=base(True);d=ImageDraw.Draw(im)
txt(d,(94,113),"MARQDO / v2.7.1",21,(233,197,146))
txt(d,(90,221),"Your SKILL",83,IVORY,"serifbold")
txt(d,(90,327),"is now a",83,IVORY,"serifbold")
txt(d,(90,435),"TOOL.",91,(244,201,148),"serifbold")
d.line((100,562,1040,562),fill=GOLD,width=3)
txt(d,(102,613),"不只是让 AI 阅读文档。",35,(232,230,224),"serif")
txt(d,(102,681),"让同一份 Markdown 承载可控执行流。",35,(232,230,224),"serif")
footer(d,"WRITE ONCE · RENDER AS MARKDOWN · INSPECT AS RUNTIME",True)
return im
source=(ROOT/"examples/procurement/index.mq.md").read_text(encoding="utf8")
assert "## 查询采购商价格" in source
section=source.split("## 查询采购商价格",1)[1].split("\n## ",1)[0]
excerpt="## 查询采购商价格\n"+section
lines=excerpt.splitlines()
content=[]
for line in lines:
if len(content)>=18:break
content.append(line)
assert len(content)>10
md=MarkdownIt("commonmark").enable("table")
html=md.render("\n".join(content))
document=f"""<!DOCTYPE html><html lang='zh'><head><meta charset='utf-8'>
<style>html,body{{margin:0;background:#fcfbf6;color:#34302d}}
body{{font-family:'Noto Serif CJK SC',serif;padding:64px 96px;font-size:26px;line-height:1.75}}
h2{{font-size:43px;font-weight:700;margin:0 0 33px}}
p{{margin:17px 0}}table{{font:20px/1.7 'Noto Sans CJK SC',sans-serif;width:100%;border-collapse:collapse;margin:26px 0}}
td,th{{padding:12px 18px;border:1px solid #e1d7c8;text-align:left}}
th{{background:#efe7d9}}tr:nth-child(even){{background:#f7f2e9}}em{{color:#8c704f}}
</style></head><body>{html}</body></html>"""
opts=Options()
for arg in ["--headless=new","--no-sandbox","--disable-dev-shm-usage","--disable-gpu","--window-size=1450,1600"]:
opts.add_argument(arg)
browser=webdriver.Chrome(options=opts)
try:
browser.set_window_size(1450,1600)
browser.get("data:text/html;charset=utf-8,"+__import__("urllib.parse",fromlist=["quote"]).quote(document))
htmlscreen=A/"marqdo-procurement-standard-markdown.png"
browser.save_screenshot(str(htmlscreen))
assert htmlscreen.stat().st_size>20000
finally:
browser.quit()
RENDER=Image.open(htmlscreen).convert("RGB")
USER=Image.open(A/"user-procurement-view.png").convert("RGB")
CONCEPT=Image.open(A/"source-markdown-view-concept.png").convert("RGB")
def make_source():
im=base(True);d=ImageDraw.Draw(im)
txt(d,(78,69),"01 / SOURCE",21,(226,192,141))
txt(d,(77,123),"源码态:它本来就是 Markdown",54,IVORY,"serifbold")
txt(d,(80,209),"普通段落保持可读,标题、参数表和返回契约仍是 Markdown。",28,(187,198,213))
card(d,(75,265,1520,797),(28,38,51),(78,89,105),23)
card(d,(76,265,1519,332),(43,53,70),(43,53,70),23)
for j,col in enumerate([(190,97,91),(224,173,97),(109,173,130)]):
d.ellipse((105+j*33,293,122+j*33,310),fill=col)
txt(d,(256,282),"index.mq.md · 查询采购商价格",24,(227,227,222))
for i,line in enumerate(content[:16]):
value=line[:77].replace("\t"," ")
clr=(232,193,133) if value.startswith("#") or "返回" in value else ((164,214,201) if "正常" in value else (221,226,230))
txt(d,(106,358+i*25),f"{i+1:02d} {value}",20,clr)
footer(d,"ACTUAL .mq.md EXCERPT · source: examples/procurement/index.mq.md",True)
return im
def make_render():
im=base();d=ImageDraw.Draw(im)
txt(d,(81,69),"02 / STANDARD MARKDOWN",21,(170,126,67))
txt(d,(77,128),"渲染态:它首先是一篇文档",56,INK,"serifbold")
txt(d,(80,205),"同一段源码,无需定制语法高亮,也可以按 Markdown 阅读。",29,DIM)
card(d,(80,265,1516,839),(255,254,251))
rounded_image(im,RENDER,(120,290,1469,814),(.5,.19))
txt(ImageDraw.Draw(im),(1145,280),"STANDARD MARKDOWN",18,(167,115,55))
footer(ImageDraw.Draw(im),"A MARKDOWN-IT RENDER · FROM THE SAME SOURCE")
return im
def make_triple():
im=base();d=ImageDraw.Draw(im)
txt(d,(75,60),"03 / THREE VIEWS, ONE FILE",21,(170,126,67))
txt(d,(76,130),"同一份 .mq.md,三种视图",55,INK,"serifbold")
txt(d,(81,211),"源码能编写,Markdown 能阅读,View 能看到函数、值和执行依赖。",27,DIM)
screens=[("SOURCE / 源码",make_source()),("MARKDOWN / 渲染",RENDER),("VIEW / 执行",USER)]
xlist=[75,578,1081]
for i,(label,src) in enumerate(screens):
x=xlist[i];tw=442
card(d,(x,280,x+tw,777),(255,254,250))
txt(d,(x+21,301),label,23,(130,95,56))
rounded_image(im,src,(x+15,349,x+tw-15,749),(.50,.38))
d=ImageDraw.Draw(im)
for x in [523,1026]:
d.line((x,530,x+49,530),fill=GOLD,width=4)
d.polygon([(x+49,530),(x+32,519),(x+32,541)],fill=GOLD)
footer(d,"NOT THREE FILES · ONE DOCUMENT + EXECUTION SEMANTICS")
return im
def make_concept():
im=base();d=ImageDraw.Draw(im)
txt(d,(72,58),"04 / DESIGN LANGUAGE",21,(170,126,67))
rounded_image(im,CONCEPT,(55,112,1545,850),(.5,.5))
txt(ImageDraw.Draw(im),(92,855),"CONCEPT ART · Source → Rendered Markdown → Marqdo View",18,DIM)
return im
def make_view():
im=base();d=ImageDraw.Draw(im)
txt(d,(78,62),"05 / REAL MARQDO VIEW",21,(170,126,67))
txt(d,(78,127),"在文档上,看见它的执行流",58,INK,"serifbold")
txt(d,(80,216),"自然语言依然是主体,执行信息沿优雅的曲线引出。",28,DIM)
card(d,(70,278,1530,841),(255,254,250))
rounded_image(im,USER,(88,295,1513,817),(.50,.50))
footer(ImageDraw.Draw(im),"ACTUAL VIEW SCREENSHOT · PROVIDED BY THE PROJECT AUTHOR")
return im
def make_execution():
im=base(True);d=ImageDraw.Draw(im)
txt(d,(80,66),"06 / EXECUTABLE FUNCTIONS",21,(230,192,137))
txt(d,(80,132),"在哪里执行?就在同一份文档的函数里。",53,IVORY,"serifbold")
txt(d,(84,216),"说明是可读的,规则却会通过函数调用实际检查。",28,(183,198,211))
card(d,(76,275,1519,367),(30,42,57),(78,88,100))
txt(d,(99,303),"marqdo call examples/procurement/index.mq.md 查询余额 已花费=120",25,(233,218,188))
card(d,(76,418,760,775),(25,55,48),(70,124,96))
card(d,(790,418,1520,775),(58,34,43),(154,85,96))
txt(d,(110,455),"PASS / LOCAL SIMULATION",24,(150,227,185))
txt(d,(822,455),"DENIED / BUDGET CHECK",24,(249,164,170))
txt(d,(112,533),"¥120 + ¥288",43,IVORY)
txt(d,(823,533),"¥360 + ¥288",43,IVORY)
txt(d,(113,606),"¥408",86,(146,229,185),"bold")
txt(d,(823,606),"¥648",86,(250,162,166),"bold")
txt(d,(115,720),"ok: true · 本地模拟,未发送",23,(217,237,224))
txt(d,(824,720),"ok: false · 超预算拒绝",23,(248,216,217))
footer(d,"OUTCOMES VERIFIED WITH MARQDO 2.7.1 CLI · NO REAL ORDER WAS SENT",True)
return im
def make_outro():
im=base(True);d=ImageDraw.Draw(im)
txt(d,(97,157),"Marqdo",90,IVORY,"serifbold")
txt(d,(98,313),"Write it. Read it. Run it.",61,(238,195,136),"serifbold")
d.line((99,431,1480,431),fill=GOLD,width=3)
txt(d,(101,500),"A document-native runtime for executable AI skills.",31,(217,221,225))
txt(d,(101,649),"github.com/cflmy/marqdo",43,IVORY)
footer(d,"Marqdo v2.7.1 · Apache 2.0 · simulated procurement demo",True)
return im
slides=[make_intro(),make_source(),make_render(),make_triple(),make_concept(),make_view(),make_execution(),make_outro()]
A.mkdir(parents=True,exist_ok=True)
slides[0].save(POSTER,quality=95)
with tempfile.TemporaryDirectory() as tmp:
tmp=Path(tmp);clips=[]
for i,(still,dur) in enumerate(zip(slides,D)):
imagefile=tmp/f"slide_{i:02d}.png"
still.save(imagefile)
clip=tmp/f"clip_{i:02d}.mp4"
filt=f"scale=1280:720,zoompan=z='min(zoom+0.00016,1.02)':x='iw/2-iw/zoom/2':y='ih/2-ih/zoom/2':d=1:s=1280x720:fps=24,fade=t=in:st=0:d=0.4,fade=t=out:st={dur-.5}:d=0.5,format=yuv420p"
cmd=["ffmpeg","-y","-hide_banner","-loglevel","error","-loop","1","-framerate","24","-t",str(dur),"-i",str(imagefile),"-vf",filt,"-an","-c:v","libx264","-preset","veryfast","-crf","19","-pix_fmt","yuv420p",str(clip)]
subprocess.run(cmd,check=True,timeout=200)
clips.append(clip)
print("RENDERED_SLIDE",i,flush=True)
playlist=tmp/"concat.txt"
playlist.write_text("\n".join(f"file '{c}'" for c in clips)+"\n")
silent=tmp/"silent.mp4"
subprocess.run(["ffmpeg","-y","-hide_banner","-loglevel","error","-f","concat","-safe","0","-i",str(playlist),"-c","copy",str(silent)],check=True,timeout=90)
sr=24000
total=sum(D);ts=np.arange(int(total*sr))/sr
sound=np.zeros(len(ts))
at=0.
for i,dur in enumerate(D):
mask=(ts>=at)&(ts<at+dur);tt=ts[mask]-at
a=np.minimum(np.minimum(tt/.8,(dur-tt)/.8),1).clip(0,1)
note=[110.,123.47,130.81,146.83,110.,123.47,130.81,110.][i]
sound[mask]+=a*.12*(.55*np.sin(2*np.pi*note*tt)+.2*np.sin(2*np.pi*note*1.5*tt)+.12*np.sin(2*np.pi*note*2*tt))
at+=dur
sound*=np.minimum(np.minimum(ts/1.2,(total-ts)/1.2),1).clip(0,1)
wav=tmp/"ambience.wav"
with wave.open(str(wav),"wb") as w:
w.setnchannels(1);w.setsampwidth(2);w.setframerate(sr)
w.writeframes((sound*32767).astype(np.int16).tobytes())
subprocess.run(["ffmpeg","-y","-hide_banner","-loglevel","error","-i",str(silent),"-i",str(wav),"-c:v","copy","-c:a","aac","-b:a","160k","-shortest","-movflags","+faststart",str(OUT)],check=True,timeout=90)
times=[0,4.8,11.6,18,25,32.5,42,50.8,56]
messages=[
"Your SKILL is now a TOOL.\n让 Markdown 直接承载可执行语义。",
"源码态:标题、段落、表格都沿用 Markdown。\n执行逻辑就在文档之中。",
"渲染态:同一份代码也能成为普通 Markdown 文档。",
"源码态、标准 Markdown 渲染态、Marqdo View 态。\n三种视图,同一份源文件。",
"一份 .mq.md,既可以阅读,也可以编译执行。",
"真实 View 截图:函数调用和值沿着优雅曲线呈现。",
"预算校验不是文字承诺,而是函数执行。\n模拟订单通过或拒绝,均由运行时返回结果。",
"Marqdo 2.7.1 · github.com/cflmy/marqdo"
]
def stamp(s):
ms=int(round(s*1000))
h=ms//3600000;ms%=3600000;m=ms//60000;ms%=60000
return f"{h:02d}:{m:02d}:{ms//1000:02d},{ms%1000:03d}"
SRT.write_text("\n\n".join(f"{i+1}\n{stamp(times[i])} --> {stamp(times[i+1])}\n{msg}" for i,msg in enumerate(messages))+"\n",encoding="utf-8")
print("VIDEO",OUT,OUT.stat().st_size)
print("COVER",POSTER,POSTER.stat().st_size)
print("SRT",SRT,SRT.stat().st_size)
assert OUT.stat().st_size>800000 and sum(D)==56
+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"*.
+85
View File
@@ -0,0 +1,85 @@
---
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
---
# main
Offline test: the same Marqdo program advances through model choice, user
input and terminal state with plugin-owned durable checkpoints.
**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="abi_flow_ci_20261118" steps=`steps` source_revision="flow-v1"**
**o = > json.get value=`opened` key="ok"**
1. `o`
**_ = 1**
2. *
> sys.exit code=21
**first = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"**
**first_state = > json.get value=`first` key="status"**
1. `first_state` == "waiting_model"
**_ = 1**
2. *
> sys.exit code=22
**c1 = > workflow.commit id="abi_flow_ci_20261118" step_id="intent" response="chat" source_revision="flow-v1"**
**done1 = > json.get value=`c1` key="ok"**
1. `done1`
**_ = 1**
2. *
> sys.exit code=23
**second = > workflow.tick id="abi_flow_ci_20261118" source_revision="flow-v1"**
**second_state = > json.get value=`second` key="status"**
1. `second_state` == "waiting_input"
**_ = 1**
2. *
> sys.exit code=24
**c2 = > workflow.commit id="abi_flow_ci_20261118" step_id="confirm" response="yes" source_revision="flow-v1"**
**done2 = > json.get value=`c2` key="ok"**
1. `done2`
**_ = 1**
2. *
> sys.exit code=25
**c3 = > workflow.tick id="abi_flow_ci_20261118" source_revision="flow-v1"**
**complete = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"**
**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"}]}]**
**new_batch = > workflow.open id="abi_flow_partial_ci_20261118" steps=`partial_steps` source_revision="flow-v1"**
**parts = > json.parse text=[{"ok":true,"value":{"code":0,"value":"useful"}},{"ok":false,"error":"timeout"}]**
**stopped = > workflow.commit id="abi_flow_partial_ci_20261118" step_id="children" response=`parts` source_revision="flow-v1"**
**reloaded = > workflow.next id="abi_flow_partial_ci_20261118" source_revision="flow-v1"**
**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="abi_flow_partial_ci_20261118" source_revision="flow-v1"**
**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="abi_flow_partial_ci_20261118" results=`repaired` source_revision="flow-v1"**
**merged_ok = > json.get value=`merged` key="ok"**
1. `merged_ok`
**_ = 1**
2. *
> sys.exit code=29
Return *"durable-agent-flow-ok"*.