Merge native AI flow workflow into main

Integrate the v2.8.0-based native agent workflow branch:
- durable open/next/inspect/list/commit/cancel step state with resume_dir isolation
- verified small-model choices, scoped context and bounded parallel recovery
- failed-only read-only retry through the Agent ABI plugin
- offline interpreter fixtures, contract checks and focused CI gates
This commit is contained in:
cflmy committed 2026-11-18 12:33:54 +08:00
commit b37387e6da
23 files changed
+2712 -51

No files matched your search

@@ -15,6 +15,22 @@ 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)
env:
MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so
run: |
cargo run --locked -- run tests/ext/ai-native-flow.mq.md
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md
- name: Workbench contracts (M00–M06 / F-subset)
run: cargo test --test workbench_contracts --locked
- name: Offline executable-knowledge gate
+40
View File
@@ -0,0 +1,40 @@
name: native-ai-flow
on:
push:
branches:
- feat/native-ai-flow-recovery-20261118
pull_request:
paths:
- 'plugins/agent/**'
- 'ext/ai/flow.mq.md'
- 'ext/ai/context.mq.md'
- 'ext/ai/recovery.mq.md'
- 'ext/ai/workflow.mq.md'
- 'tests/ext/ai-native-*.mq.md'
- '.github/workflows/native-ai-flow.yml'
jobs:
agent:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- name: Build the agent plugin
run: cargo build -p marqdo_plugin_agent --locked
- name: Run native agent and workflow tests
run: cargo test -p marqdo_plugin_agent --locked
- name: Check the public Marqdo ABI libraries
run: |
cargo run --locked -- check ext/ai/flow.mq.md
cargo run --locked -- check ext/ai/context.mq.md
cargo run --locked -- check ext/ai/recovery.mq.md
cargo run --locked -- check ext/ai/workflow.mq.md
cargo run --locked -- check tests/ext/ai-native-flow.mq.md
cargo run --locked -- check tests/ext/ai-native-workflow.mq.md
- name: Exercise offline integration through Marqdo
env:
MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so
run: |
cargo run --locked -- run tests/ext/ai-native-flow.mq.md
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md
+2
View File
@@ -1,5 +1,7 @@
/target/
/dist/
# Plugin unit tests use package-relative scratch checkpoints.
/plugins/agent/target/
# Copied by gold harness for ABI plugins
/tests/lib/demo.dll
+22
View File
@@ -2,6 +2,28 @@
## Unreleased
### Added
- `ext/ai/workflow` now exposes read-only `inspect`/`list`, a host-relative
`resume_dir` on every operation, and repeatable offline workflow fixtures.
- Agent ABI registers `agent_workflow_inspect` and `agent_workflow_list`.
- AI 工作流拓展库新增只读 `inspect`/`list`、各操作的 `resume_dir` 隔离,
离线集成夹具改为按时间戳生成运行 ID,可重复执行。
### Fixed
- `flow.choose` no longer leaks a branch-local `parsed` value into the function
contract; the repaired-choice path is fully scoped.
- CI builds the agent cdylib and runs offline integration without the removed
`run --effects` flag, using `MARQDO_AGENT_PLUGIN` instead.
### Changed
- 分支已合并 v2.8.0:`Cargo.toml`/`Cargo.lock`、发布工作流与全部拓展包
统一到 2.8.0 依赖锁,后续发版不再从 2.7.1 基线分叉。
- The branch now includes v2.8.0, so its crate versions, lockfile and release
workflows match the current release line instead of the 2.7.1 baseline.
## v2.8.0 — 2026-11-17
`marqdo prove` 正式发布:定理表 → Lean 4 证明 → 自动判定。离线符号执行(F1–F5)无工具链可用,`checked` 永远弱于 `proved`;单调性护栏让判定器缺陷显式失败;假定理给出反例见证;证书缓存与目录模式面向智能体批量出证。
Generated
+1
View File
@@ -668,6 +668,7 @@ version = "0.1.0"
dependencies = [
"chrono",
"marqdo-plugin-sdk",
"pulldown-cmark",
"serde_json",
]
+140
View File
@@ -0,0 +1,140 @@
# Marqdo native agent flow — implementation contract
Status: **incremental, draft**. The core orchestration now has a plugin-only
alternative to interpreter-stack suspension: a durable finite step state machine
with explicit safe commit boundaries. Do not claim arbitrary stack-level
continuation or exactly-once external writes based on a checkpoint file.
## Author surface (implemented in this branch)
| Module | Function | Contract |
|---|---|---|
| ext/ai/context.mq.md | scope | Select a bounded source excerpt using parsed Markdown headings; ambiguous names fail closed |
| ext/ai/context.mq.md | pack | Compact caller-provided file/class/function text via ContextPackV2 |
| ext/ai/flow.mq.md | ask/choose/parse_choice | One short decision, allowed-choice verification, at most one format repair |
| ext/ai/flow.mq.md | input/reply | Durable step-boundary user-input gate keyed by id + source revision and scope |
| ext/ai/flow.mq.md | start/wait/parallel | Existing Marqdo subtask scheduler, failure-preserving parallel result aggregation |
| ext/ai/flow.mq.md | enter | Resolve only author-supplied registered skill name, run via standard subtask path |
| ext/ai/recovery.mq.md | decide/save/load | Native error policy and CheckpointV2; no implicit unsafe re-execution |
| ext/ai/workflow.mq.md | open/next/commit/cancel | Durable forward-only step machine with per-step commit boundaries |
| ext/ai/workflow.mq.md | inspect/list | Read-only progress summary and checkpoint discovery scoped by session/principal |
| ext/ai/workflow.mq.md | tick/retry_plan/retry_commit/retry_failed | One-step execution and failed-only read-only recovery |
The native agent plugin provides `agent_choice_parse`, `agent_context_scope`,
`agent_input_open`, `agent_input_resume`, `agent_parallel_report`, and the
`agent_workflow_*` primitives including `inspect` and `list`.
Plugin errors must be visible, never converted into a fabricated successful answer.
All workflow wrappers accept a host-relative `resume_dir`, so tests and callers
can isolate checkpoints instead of sharing the default `.marqdo/agent-resume`.
## Invariants
- A model choice is untrusted data until verified against an explicit option list.
- An imported module is **not** automatically part of a model prompt.
- The requested heading scope, not the entire source file, is the prompt source.
- A pending user-input gate owns a persistent checkpoint, not a blocked interpreter thread.
- The same answer may be returned repeatedly; a competing answer or stale revision conflicts.
- A completed subtask wait is distinct from a successful child exit.
- Existing successful siblings remain visible when one subtask fails.
- Writes, executable effects and external writes remain under ToolSpec permissions,
the EffectLedger and source-version checks.
- No component may silently broaden a tool's authorization on failure.
## Important limitations in this branch
The input/reply gate stores an explicit **step boundary**. It does not yet persist
an arbitrary bytecode interpreter frame. Applications must choose and re-enter
their next Marqdo function explicitly after receiving a verified input answer.
The current source selector relies on a Markdown parser plus Marqdo heading
conventions, not on the compiler's resolved module/class/function AST and symbols.
Host identity inputs are supplied by the caller; production applications must
attest them from their authenticated session, never use model-generated identity.
The parallel wrapper reuses `subtask.run_many` and does not add durable child
lease orchestration. Live provider tests and real 1B-model benchmarking remain open.
## Required VM/runtime completion: suspended execution
1. Introduce `WaitingInput` as a scheduler state, distinct from terminal failure.
Save the logical run, program counter at a safe suspension boundary, bound
inputs, variable snapshot, module and tool digests, and effect watermark.
2. Resume via a new attempt linked to the original logical run, but never
automatically repeat committed effects. Preserve cancellation and budget.
3. The resume endpoint must be atomic (revision CAS), authenticate principal
and workspace, verify source and tool schema revisions, and deduplicate
repeated reply requests. Do not trust IDs inside model text.
4. Handle interrupted worker, partial snapshot, stale input, invalid choice and
unknown external write as separate outcomes. Treat unknown writes as
reconciliation-required; do not invent exactly-once guarantees.
5. Persist only serializable language values at declared safe points. If a
foreign kernel, socket or native handle is live, explicitly refuse
transparent frame recovery and preserve a safe step-level restart option.
## Required durable parallel execution
A parent dispatches child `.mq.md` functions using registered paths, grants
minimal capabilities, shares budget and rate limits, and persists a child task
manifest. Child completion records a status, value ref, output digest and ledger
watermark before the parent merges results. For same-resource writes, use
serialized revisions and explicit commit order. On parent cancellation, stop
new children and request child cancellation; do not assume remote writes rolled
back. On recovery, reconcile child attempts and reuse successful results.
## Release gates
| Test | Required observation |
|---|---|
| compiler/import check | All new `.mq.md` functions pass contract checks and execute via ABI |
| small model outputs | Exact, labeled, fenced and numeric options normalize; mixed options fail |
| input gate crash | After checkpoint, reply is committed once; alternate reply conflicts |
| source drift | Original gate cannot resume against changed source revision |
| context isolation | Class/function selectors reject ambiguity and ignore fenced headings |
| concurrent partial | Failed/uncertain child never discards successful siblings |
| unknown write | Neither retry nor recovered child duplicates an unconfirmed effect |
| long-run cancellation | Worker/child task termination preserves usable artifacts and receipts |
| compatibility | Existing `agent.step/plan/run` and workbooks remain callable |
| model evaluation | Tokens/decision, semantic validity, end-to-end completion, recovery overhead |
Do not merge the branch as a completed runtime refactor until the relevant
runtime gates, including crash injection and multi-worker concurrency, pass.
## Plugin-only workflow (November 18 revision)
The Agent ABI plugin implements
`agent_workflow_open/next/inspect/list/commit/cancel` plus the failed-only
retry primitives. The small `ext/ai/workflow.mq.md` library wraps these
primitives and provides `tick` to execute exactly one safe decision or document
task per call. `inspect` and `list` are strictly read-only: they report progress
or discover checkpoints without advancing a cursor or running a step.
Source definitions have only five step kinds: `model`, `input`, `skill`,
`parallel` and `return`. Model text is verified against declared options.
`input` intentionally returns a waiting status; the UI supplies an answer
through `commit` on a later invocation. There is no interpreter thread to
hold and no need for a separate qdagent orchestration server.
The checkpoint records the source revision, caller-provided session and
principal scope, next step index and the completed outputs. The same step
cannot be silently committed twice. Mixed child outcomes preserve completed
siblings in the checkpoint and **block** further automatic execution until
the unknown/failed child operations are reconciled.
The state engine does not execute arbitrary unregistered tools directly:
`tick` delegates to existing Marqdo ABI-backed SKILL/subtask functions.
This is an implementation of **durable step-state recovery**, not a claim
of transparent recovery for a suspended foreign function or native call.
It provides the practical workflow needed for short qdagent SKILLs without
altering the Marqdo interpreter.
### Security/reliability boundary still required for production
- The host must attest source digest, principal, session, permissions and
registry, rather than accepting values copied from an LLM response.
- Effectful child tools must use the existing EffectLedger and external
receipt reconciliation; no automatic re-dispatch after an uncertain write.
- Cancelling a workflow checkpoint does not automatically cancel previously
spawned external children; the supervisor must propagate cancellation.
- The current task runner is step-atomic, not a durable parallel child lease
scheduler. A future plugin-only child manifest may use the host's existing
`runtime` query API, but must not bypass process.exec or file-root grants.
- Cross-process locks need a lease/owner-aware stale-lock recovery path;
a stale lock currently fails closed and requires operator review.
+113
View File
@@ -0,0 +1,113 @@
---
markup: occlusion
title: AI context — short, explicit source scopes
description: Pack user input and caller-provided file/class/function excerpts.
import:
agent: ext/ai/agent.mq.md
plugin: lib/plugin.mq.md
json: lib/json.mq.md
---
Pass only the documentation that the next model decision needs. The supplied
file/class/function snippets are data; they do not execute as Marqdo source.
A future compiler-backed selector can supply these arguments from AST spans.
This helper does not yet infer class/function scopes automatically.
## pack
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| user | text | required | Latest user input |
| file | text | "" | File-level description excerpt |
| class | text | "" | Current class excerpt |
| function | text | "" | Current function excerpt |
| budget_tokens | number | 2048 | Small-model context budget |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Bounded ContextPackV2 and compaction evidence |
Use `user`, `file`="", `class`="", `function`="", `budget_tokens`=2048 as the inputs for this operation.
Keep the latest request and current function first. Low-priority file context
may be dropped under pressure; any important constraint must be in a retained
field, not in a discardable tool transcript.
`items` =
| @ | origin | trust | priority | text | retain |
|---|---|---|---|---|---|
| 1 | user | user | 0 | `user` | True |
| 2 | function | unknown | 1 | `function` | True |
| 3 | class | unknown | 2 | `class` | False |
| 4 | file | unknown | 3 | `file` | False |
Return *[Pack the supplied scopes and compact redundant context](agent.context_pack_compact(items=`items`, budget_tokens=`budget_tokens`, goal=`user`))*.
## scope
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| scope | text | "function" | file / class / function / tool |
| class | text | None | Class heading for disambiguation |
| function | text | None | Function/tool heading |
| source | text | None | Source override; otherwise current entry module |
| max_chars | number | 1600 | Maximum Unicode characters |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Exact source excerpt, line range, or explicit ambiguity |
Use `scope`="function", `class`=None, `function`=None, `source`=None, `max_chars`=1600 as the inputs for this operation.
The native selector respects Markdown headings and ignores fenced-code heading
lookalikes. Repeated function names require a class; missing/ambiguous scopes
return an error value, never an unrelated or whole-file fallback.
We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load native agent plugin](plugin.load(path=`p`))**.
2. *
Return *[No native parser available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\",\"text\":null}"))*.
Return *[Project the requested document scope](agent_context_scope(source=`source`, scope=`scope`, class=`class`, function=`function`, max_chars=`max_chars`))*.
## compose
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| user | text | required | Latest user input |
| class | text | required | Current class name |
| function | text | required | Current function name |
| source | text | None | Override current entry source |
| budget_tokens | number | 2048 | Small-model context budget |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | ContextPackV2 or an explicit failed selector |
Use `user`, `class`, `function`, `source`=None, `budget_tokens`=2048 as the inputs for this operation.
Project file, class and function scopes independently. Refuse ambiguous names
rather than silently importing an unrelated class or the entire source. The
latest user input stays in the retained portion of the resulting context pack.
We retain **f = [Select file preface](scope(scope="file", source=`source`, max_chars=500))**.
We retain **c = [Select current class](scope(scope="class", class=`class`, source=`source`, max_chars=800))**.
We retain **n = [Select current function](scope(scope="function", class=`class`, function=`function`, source=`source`, max_chars=1500))**.
We retain **f_ok = [Check file selection](json.get(value=`f`, key="ok"))**.
We retain **c_ok = [Check class selection](json.get(value=`c`, key="ok"))**.
We retain **n_ok = [Check function selection](json.get(value=`n`, key="ok"))**.
1. not `f_ok`
Return *f*.
2. not `c_ok`
Return *c*.
3. not `n_ok`
Return *n*.
4. *
We retain **ft = [Read file preface](json.get(value=`f`, key="text"))**.
We retain **ct = [Read class explanation](json.get(value=`c`, key="text"))**.
We retain **nt = [Read function explanation](json.get(value=`n`, key="text"))**.
Return *[Compact only the selected scopes](pack(user=`user`, file=`ft`, class=`ct`, function=`nt`, budget_tokens=`budget_tokens`))*.
+246
View File
@@ -0,0 +1,246 @@
---
markup: occlusion
title: AI flow — small-model choices and bounded subtasks
description: Short model decisions, verified options and concurrent Marqdo documents.
import:
llm: ext/ai/llm.mq.md
json: lib/json.mq.md
plugin: lib/plugin.mq.md
subtask: lib/subtask.mq.md
---
This is the thin author-facing layer. A model returns a candidate; Marqdo checks
it before routing. Invalid choices are not SKILL paths and never execute.
Only the requested function and its inputs need to be in the model prompt.
## parse_choice
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| reply | text | required | Raw model reply, treated as data |
| options | list | required | Allowed names, not paths or commands |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | {ok,value,status} or {ok:false,error} |
Use `reply`, `options` as the inputs for this operation.
Parsing accepts one exact name, a labeled name, a fenced name or a 1-based
index. Ambiguous prose fails closed. Parsing never runs a tool or SKILL.
We retain **p = [Locate the installed agent plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load the agent plugin](plugin.load(path=`p`))**.
2. *
Return *[Missing native parser](json.parse(text="{\"ok\":false,\"status\":\"unavailable\",\"value\":null}"))*.
Return *[Parse and verify the choice](agent_choice_parse(reply=`reply`, options=`options`))*.
## choose
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| input | text | required | Current user request or local decision |
| options | list | required | Small list of registered option names |
| model | any | None | Existing provider model identifier |
| repair | bool | True | Allow one format-only repair attempt |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Verified choice result, or explicit failure |
Use `input`, `options`, `model`=None, `repair`=True as the inputs for this operation.
Only ask for the option name. A failed first parse can receive one short
format correction; never silently select the nearest-looking option.
We retain **opts = [Encode allowed values](json.stringify(value=`options`))**.
We retain **prompt = "Choose exactly one of these options. Return its name only, no explanation:\n" + opts + "\nInput:\n" + input**.
We retain **m = [Build one model handle](llm.create(model=`model`))**.
We retain **turn = [Ask the model once](m.ask(prompt=`prompt`))**.
We retain **err = [Check model transport error](json.get(value=`turn`, key="error"))**.
1. `err`
Return *turn*.
2. *
We retain **reply = [Read model answer](json.get(value=`turn`, key="text"))**.
We retain **parsed = [Validate the model reply](parse_choice(reply=`reply`, options=`options`))**.
We retain **ok = [Read validation status](json.get(value=`parsed`, key="ok"))**.
1. `ok`
Return *parsed*.
2. `repair`
We retain **fix = "Your answer was not an exact allowed option. Return only ONE option name from:\n" + opts**.
We retain **fixed = [Retry the format only once](m.ask(prompt=`fix`))**.
We retain **repair_error = [Read transport error](json.get(value=`fixed`, key="error"))**.
1. `repair_error`
Return *fixed*.
2. *
We retain **again = [Read corrected answer](json.get(value=`fixed`, key="text"))**.
Return *[Validate the repaired reply](parse_choice(reply=`again`, options=`options`))*.
3. *
Return *parsed*.
## parallel
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| tasks | list | required | Existing .mq.md file tasks with arguments |
| limit | number | 2 | Maximum simultaneously running tasks |
| timeout_ms | number | 30000 | Execution timeout in milliseconds |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Succeeded, partial, failed or uncertain child outcomes |
Use `tasks`, `limit`=2, `timeout_ms`=30000 as the inputs for this operation.
Reuse the built-in subtask scheduler. Each child document returns via its
`# main`, and successful siblings remain visible if another child fails.
We retain **results = [Run bounded Marqdo document tasks](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))**.
We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load native agent plugin](plugin.load(path=`p`))**.
Return *[Preserve success, failure and uncertain child outcomes](agent_parallel_report(results=`results`))*.
2. *
Return *[Native result classifier unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## input
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable step ID |
| question | text | required | User-visible question |
| options | list | required | User-visible choices |
| source_revision | text | required | Pinned Marqdo source revision |
| session_id | text | None | Host-attested session |
| principal_ref | text | None | Host-attested user scope |
| freeform | bool | True | Allow custom user reply |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | waiting_input or previously committed reply |
Use `id`, `question`, `options`, `source_revision`, `session_id`=None, `principal_ref`=None, `freeform`=True as the inputs for this operation.
This does not park an interpreter stack. The caller persists a step-boundary
checkpoint, displays the question, and on a new turn uses reply to continue.
The host, not the LLM, must attest session and principal IDs.
We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load native agent plugin](plugin.load(path=`p`))**.
2. *
Return *[No native gate available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
Return *[Persist one waiting input gate](agent_input_open(id=`id`, question=`question`, options=`options`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, freeform=`freeform`))*.
## reply
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Existing waiting step |
| reply | text | required | New user response |
| source_revision | text | required | Current pinned source revision |
| session_id | text | None | Host-attested session |
| principal_ref | text | None | Host-attested user scope |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Resolved answer, invalid reply or explicit conflict |
Use `id`, `reply`, `source_revision`, `session_id`=None, `principal_ref`=None as the inputs for this operation.
Matching repeated replies are idempotent. A conflicting reply, changed document
or changed session fails without executing any SKILL or side effect.
We retain **p = [Locate native agent plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load native agent plugin](plugin.load(path=`p`))**.
2. *
Return *[No native gate available](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
Return *[Commit the verified user reply](agent_input_resume(id=`id`, reply=`reply`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))*.
## enter
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| skill | text | required | Model-selected registered name |
| registry | map | required | Trusted name → path mapping |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Subtask result, or blocked unknown skill |
Use `skill`, `registry` as the inputs for this operation.
Never execute a raw model-generated path. Resolve a registered skill name to
an author-controlled document, then call its `# main` through the normal Marqdo
subtask and effect permissions. The caller must provide a trusted registry.
We retain **path = [Resolve registered SKILL](json.get(value=`registry`, key=`skill`))**.
1. not `path`
Return *[Unknown skill is blocked](json.parse(text="{\"ok\":false,\"status\":\"unsupported_skill\"}"))*.
2. *
We retain **task = [Spawn registered Marqdo document](subtask.spawn(path=`path`))**.
Return *[Await the subtask result](subtask.wait(id=`task`))*.
## ask
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| prompt | text | required | Short local prompt |
| model | any | None | Configured model selection |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | Model reply (not yet a verified tool call) |
Use `prompt`, `model`=None as the inputs for this operation.
Ask only what the current function needs. The reply remains data until an
explicit verifier accepts it. The LLM adapter owns provider configuration.
Return *[Ask the configured model](llm.ask(prompt=`prompt`, model=`model`))*.
## start
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | Trusted registered Marqdo document |
| args | list | None | Optional child CLI arguments |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | Child task handle |
Use `path`, `args`=None as the inputs for this operation.
Start an isolated SKILL document asynchronously, after the calling host has
validated its path and required process.exec permission. No model-generated
raw path is a valid grant.
Return *[Start one Marqdo document](subtask.spawn(path=`path`, args=`args`))*.
## wait
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | number | required | Child task handle |
| timeout_ms | number | 30000 | Maximum wait time |
| cancel | bool | False | Cancel on timeout |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Child result, timeout or cancellation |
Use `id`, `timeout_ms`=30000, `cancel`=False as the inputs for this operation.
A successful wait protocol is not proof of a successful child execution:
inspect the child exit code before using its result.
Return *[Wait for the child](subtask.wait_timeout(id=`id`, timeout_ms=`timeout_ms`, cancel=`cancel`))*.
+7 -1
View File
@@ -9,7 +9,13 @@ Start here to choose an AI task. [Model calls](llm.mq.md) own prompts, model con
stream collection and usage; [provider adapters](llm/index.mq.md) describe OpenAI-compatible
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; [workflow](workflow.mq.md) drives a durable forward-only step plan with
`inspect`/`list` progress queries and failed-only read recovery; [context](context.mq.md)
packs explicit source scopes; [recovery](recovery.mq.md)
uses the native error policy and versioned checkpoints. These are lightweight
interfaces, not a second agent runtime.
[Step routing](policies/step-route.mq.md) is readable
policy data, not a second agent language. Chinese users can start at [索引](索引.mq.md).
Begin with this offline stream example; it does not request credentials, install a plugin or
+70
View File
@@ -0,0 +1,70 @@
---
markup: occlusion
title: AI recovery — safe defaults for short SKILL functions
description: Reuse the native error policy, durable checkpoints and effect ledger.
import:
agent: ext/ai/agent.mq.md
---
Error handling belongs to Marqdo, not the model's prompt. The native policy
never blindly repeats uncertain writes. Every resume must revalidate the
current permission and source revision; a saved checkpoint is not authorization.
## decide
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| error | map | required | Structured AgentErrorV1 |
| attempts | number | 0 | Number of attempts already made |
| effect_class | text | "read" | Declared tool effect |
| cancelled | bool | False | Parent cancellation status |
| fingerprint_repeats | number | 0 | Identical failures without new evidence |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Safe recovery action with budget |
Use `error`, `attempts`=0, `effect_class`="read", `cancelled`=False, `fingerprint_repeats`=0 as the inputs for this operation.
This returns an action, not an automatic retry or permission to execute. For
write or unknown effect, consult the effect ledger before taking another step.
Return *[Select a bounded recovery action](agent.error_decide_retry(error=`error`, attempts=`attempts`, effect_class=`effect_class`, cancelled=`cancelled`, fingerprint_repeats=`fingerprint_repeats`))*.
## save
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable logical run ID |
| task | any | None | Current task or user request |
| status | text | "waiting_input" | Current run status |
| effect_ledger_watermark | any | None | Durable ledger boundary if available |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | CheckpointV2 write result |
Use `id`, `task`=None, `status`="waiting_input", `effect_ledger_watermark`=None as the inputs for this operation.
Use the existing atomic checkpoint writer. When ledger evidence is absent,
a resumed writer requires manual review rather than automatic repetition.
This function saves metadata; it does not suspend a Rust execution frame.
Return *[Save a versioned checkpoint](agent.resume_save(id=`id`, task=`task`, status=`status`, checkpoint_v2=True, effect_ledger_watermark=`effect_ledger_watermark`))*.
## load
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Previously saved logical run ID |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Checkpoint or missing/unsafe recovery status |
Use `id` as the inputs for this operation.
Loading a checkpoint does not execute any saved step. The caller must inspect
recovery_mode and write_auto_resume before dispatching any effectful operation.
Return *[Inspect the saved checkpoint](agent.resume_load(id=`id`))*.
+330
View File
@@ -0,0 +1,330 @@
---
markup: occlusion
title: Native AI workflow — durable, short, one-step-at-a-time execution
description: Plugin-managed checkpointed decision flow without an external agent runtime.
import:
plugin: lib/plugin.mq.md
json: lib/json.mq.md
flow: ext/ai/flow.mq.md
subtask: lib/subtask.mq.md
---
Every step is an explicit commit boundary. The plugin stores accepted outputs,
refuses stale documents and conflicting decisions, and exposes the next action.
The caller must supply trusted session, principal and source revision fields;
model text is never an identity or permission token. `resume_dir` is a
host-relative checkpoint directory, never an absolute client path.
## open
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable run ID |
| steps | list | required | 1–128 ordered step records |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Created, resumed, or explicit conflict |
Use `id`, `steps`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Opening the same ID with the same steps, source revision, session and principal
returns the current action instead of resetting progress. Reusing an ID with a
different plan or identity fails closed.
We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Open durable workflow](agent_workflow_open(id=`id`, steps=`steps`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## next
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable run ID |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Current action or terminal state |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
`next` is read-only: it does not call a model, run a child document or consume
the current step. Stopped states (`blocked`, `uncertain`, `cancelled`) and
unclassified child effects are reported explicitly.
We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Find the next committed boundary](agent_workflow_next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## inspect
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable run ID |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Progress summary with cursor, step and partial results |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Use inspect for a UI progress panel or an operator audit. It returns the
durable checkpoint `status`, the next `action` (for example `waiting_model`),
cursor, total and completed step counts, the current step, and retained partial
child results without advancing the workflow.
We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Read workflow progress](agent_workflow_inspect(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## list
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| session_id | text | None | Trusted session filter |
| principal_ref | text | None | Trusted principal filter |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Workflow summaries, newest metadata included separately |
Use `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Only native workflow checkpoints are listed; unrelated resume records and
corrupt files are omitted. Pass host-attested filters to keep one session or
principal from seeing another's run identifiers.
We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[List workflow checkpoints](agent_workflow_list(session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## commit
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable run ID |
| step_id | text | required | Exact current step |
| response | any | required | Completed step output |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Committed next step or explicit failure |
Use `id`, `step_id`, `response`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
A completed step cannot be committed twice. Replaying the same value returns
the already-committed result; a different value for the same step conflicts.
We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Validate and commit one step](agent_workflow_commit(id=`id`, step_id=`step_id`, response=`response`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## cancel
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Stable run ID |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Cancelled checkpoint status |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Cancelling prevents future commits. It does not claim that children already
started by the supervisor were rolled back.
We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Commit cancellation](agent_workflow_cancel(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Missing ABI plugin](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## tick
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Running workflow |
| source_revision | text | required | Pinned source revision |
| registry | map | None | Trusted SKILL registry |
| model | any | None | Configured LLM |
| session_id | text | None | Host-attested session |
| principal_ref | text | None | Host-attested principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | New checkpoint state, or waiting_input for the UI |
Use `id`, `source_revision`, `registry`=None, `model`=None, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Advance at most one step. Model text is a candidate, never direct
execution. Waiting for a user returns immediately without holding a thread.
A caller repeats tick after verified completion; UI replies use commit.
`tick` is the only wrapper that may execute a document child, and it only does
so after the checkpoint reports a read-only `ready_tool` step. When the action
is `waiting_input`, return the state unchanged so the host can display the
question and commit the attested answer on a later call. A blocked, uncertain
or cancelled checkpoint is returned as-is; recovery must use `retry_plan` or an
operator decision instead of silently ticking again. The returned state always
describes the committed boundary, not an optimistic guess about a running
child.
We retain **state = [Load the next action](next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))**.
We retain **status = [Read action status](json.get(value=`state`, key="status"))**.
1. `status` == "waiting_model"
We retain **step = [Read model step](json.get(value=`state`, key="step"))**.
We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**.
We retain **prompt = [Read local prompt](json.get(value=`step`, key="prompt"))**.
We retain **options = [Read allowed decisions](json.get(value=`step`, key="options"))**.
We retain **answer = [Make a bounded choice](flow.choose(input=`prompt`, options=`options`, model=`model`))**.
We retain **valid = [Check model decision](json.get(value=`answer`, key="ok"))**.
1. `valid`
We retain **chosen = [Read verified model answer](json.get(value=`answer`, key="value"))**.
Return *[Commit the model choice](commit(id=`id`, step_id=`step_id`, response=`chosen`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *answer*.
2. `status` == "ready_tool"
We retain **step = [Read tool step](json.get(value=`state`, key="step"))**.
We retain **kind = [Read operation kind](json.get(value=`step`, key="kind"))**.
We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**.
1. `kind` == "parallel"
We retain **tasks = [Read child tasks](json.get(value=`step`, key="tasks"))**.
We retain **report = [Run bounded parallel documents](flow.parallel(tasks=`tasks`))**.
Return *[Commit all child outcomes](commit(id=`id`, step_id=`step_id`, response=`report`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. `kind` == "skill"
We retain **name = [Read registered skill name](json.get(value=`step`, key="skill"))**.
We retain **out = [Run registered SKILL only](flow.enter(skill=`name`, registry=`registry`))**.
Return *[Commit verified child result](commit(id=`id`, step_id=`step_id`, response=`out`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
3. *
Return *state*.
3. `status` == "ready_return"
We retain **step = [Read return step](json.get(value=`state`, key="step"))**.
We retain **step_id = [Read step identifier](json.get(value=`step`, key="id"))**.
We retain **value = [Read final value](json.get(value=`step`, key="value"))**.
Return *[Commit the completed workflow](commit(id=`id`, step_id=`step_id`, response=`value`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
4. *
Return *state*.
## retry_plan
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Blocked workflow ID |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Failed-only read-task list or manual_review |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Only a parallel step explicitly declared read-only and with no uncertain
effects may return a retry plan. Completed siblings are not included.
We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Select failed read-only children](agent_workflow_retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Native plugin unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## retry_commit
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Blocked workflow ID |
| results | list | required | New outcomes for failed children only |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Merged persistent report, or still blocked |
Use `id`, `results`, `source_revision`, `session_id`=None, `principal_ref`=None, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Re-use successful child results from the checkpoint. New results fill failed
slots only, in original order; a newly uncertain outcome blocks further work.
We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**.
1. `p`
We **[Load Agent ABI plugin](plugin.load(path=`p`))**.
Return *[Merge verified read-only retries](agent_workflow_retry_commit(id=`id`, results=`results`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *[Native plugin unavailable](json.parse(text="{\"ok\":false,\"status\":\"unavailable\"}"))*.
## retry_failed
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | text | required | Blocked workflow ID |
| source_revision | text | required | Pinned source revision |
| session_id | text | None | Trusted session |
| principal_ref | text | None | Trusted principal |
| limit | number | 2 | Max concurrent failed children |
| timeout_ms | number | 30000 | Child timeout |
| resume_dir | text | ".marqdo/agent-resume" | Host-relative checkpoint directory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Recovered workflow, partial results or manual review |
Use `id`, `source_revision`, `session_id`=None, `principal_ref`=None, `limit`=2, `timeout_ms`=30000, `resume_dir`=".marqdo/agent-resume" as the inputs for this operation.
Run only the failed read-only tasks returned by the native checkpoint checker.
Unknown external writes never reach this path.
We retain **plan = [Inspect safe retry manifest](retry_plan(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))**.
We retain **can_retry = [Check permitted recovery](json.get(value=`plan`, key="ok"))**.
1. `can_retry`
We retain **tasks = [Read failed-only children](json.get(value=`plan`, key="tasks"))**.
We retain **outcomes = [Execute failed read-only children only](subtask.run_many(tasks=`tasks`, limit=`limit`, timeout_ms=`timeout_ms`))**.
Return *[Merge with preserved completed children](retry_commit(id=`id`, results=`outcomes`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`, resume_dir=`resume_dir`))*.
2. *
Return *plan*.
+1
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");
}
}
+31
View File
@@ -1,19 +1,24 @@
//! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb + v2 memory + adaptive route.
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,19 @@ kb_ffi!(agent_resume_save, resume::resume_save, "agent_resume_save");
kb_ffi!(agent_resume_load, resume::resume_load, "agent_resume_load");
kb_ffi!(agent_resume_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_inspect, workflow::inspect, "agent_workflow_inspect");
kb_ffi!(agent_workflow_list, workflow::list, "agent_workflow_list");
kb_ffi!(agent_workflow_commit, workflow::commit, "agent_workflow_commit");
kb_ffi!(agent_workflow_cancel, workflow::cancel, "agent_workflow_cancel");
kb_ffi!(agent_workflow_retry_plan, workflow::retry_plan, "agent_workflow_retry_plan");
kb_ffi!(agent_workflow_retry_commit, workflow::retry_commit, "agent_workflow_retry_commit");
kb_ffi!(agent_error_make, error::make_error, "agent_error_make");
kb_ffi!(agent_error_decide_retry, error::decide_retry, "agent_error_decide_retry");
kb_ffi!(agent_tools_register, tools::tools_register, "agent_tools_register");
@@ -963,6 +981,19 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
("agent_resume_load", "id,resume_dir", agent_resume_load),
("agent_resume_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,session_id,principal_ref,resume_dir", agent_workflow_open),
("agent_workflow_next", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_next),
("agent_workflow_inspect", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_inspect),
("agent_workflow_list", "session_id,principal_ref,resume_dir", agent_workflow_list),
("agent_workflow_commit", "id,step_id,response,source_revision,session_id,principal_ref,resume_dir", agent_workflow_commit),
("agent_workflow_cancel", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_cancel),
("agent_workflow_retry_plan", "id,source_revision,session_id,principal_ref,resume_dir", agent_workflow_retry_plan),
("agent_workflow_retry_commit", "id,results,source_revision,session_id,principal_ref,resume_dir", agent_workflow_retry_commit),
("agent_error_make", "code,message,category", agent_error_make),
("agent_error_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);
}
}
+679
View File
@@ -0,0 +1,679 @@
//! Plugin-only durable step workflow.
//! No interpreter-frame serialization: every model/tool decision is a checkpointed
//! transition. This state machine issues actions but never executes arbitrary code.
use std::fs::{self, OpenOptions};
use std::path::PathBuf;
use serde_json::{json, Value};
use crate::{choice, parallel, resume};
const MAX_STEPS: usize = 128;
struct Guard(PathBuf);
impl Drop for Guard {
fn drop(&mut self) { let _ = fs::remove_file(&self.0); }
}
fn field<'a>(v: &'a Value, key: &str) -> Result<&'a str, String> {
v.get(key).and_then(Value::as_str).filter(|x| !x.is_empty())
.ok_or_else(|| format!("workflow requires text {key}"))
}
fn safe_key(s: &str) -> bool {
!s.is_empty() && s.len() <= 100
&& s.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
}
fn storage(args: &Value) -> Result<PathBuf, String> {
let rel = args.get("resume_dir").and_then(Value::as_str)
.unwrap_or(".marqdo/agent-resume");
let path = PathBuf::from(rel);
if path.is_absolute() || path.components().any(|part|
matches!(part, std::path::Component::ParentDir | std::path::Component::Prefix(_)))
{
return Err("resume_dir must be relative with no parent traversal".into());
}
let base = crate::host_query_json("cwd").ok()
.and_then(|v| v.as_str().map(PathBuf::from))
.unwrap_or(std::env::current_dir().map_err(|e| e.to_string())?);
let dir = base.join(path);
fs::create_dir_all(&dir).map_err(|e| format!("workflow mkdir: {e}"))?;
Ok(dir)
}
fn lock(args: &Value, id: &str) -> Result<Guard, String> {
if !safe_key(id) {
return Err("workflow id must be <=100 ASCII letters, numbers, - or _".into());
}
let path = storage(args)?.join(format!("{id}.flow-lock"));
OpenOptions::new().write(true).create_new(true).open(&path)
.map_err(|e| format!("workflow busy or stale lock; review before recovering: {e}"))?;
Ok(Guard(path))
}
fn checkpoint_args(args: &Value, id: &str) -> Value {
json!({"id": id, "resume_dir": args.get("resume_dir")})
}
fn read(args: &Value, id: &str) -> Result<Value, String> {
resume::resume_load(&checkpoint_args(args,id))
}
fn context(args: &Value) -> Value {
json!({
"source_revision": args.get("source_revision").cloned().unwrap_or(Value::Null),
"session_id": args.get("session_id").cloned().unwrap_or(Value::Null),
"principal_ref": args.get("principal_ref").cloned().unwrap_or(Value::Null)
})
}
fn check_context(args: &Value, ckpt: &Value) -> bool {
ckpt["meta"]["identity"] == context(args)
}
fn validate_steps(args: &Value) -> Result<Value, String> {
let steps = args.get("steps").and_then(Value::as_array)
.ok_or_else(|| "steps must be a list".to_string())?;
if steps.is_empty() || steps.len() > MAX_STEPS {
return Err("steps must contain 1..=128 items".into());
}
let mut seen = std::collections::HashSet::new();
for s in steps {
let id = field(s, "id")?;
if !safe_key(id) || !seen.insert(id) {
return Err("step ids must be unique safe identifiers".into());
}
let kind = field(s, "kind")?;
if !matches!(kind, "model" | "input" | "skill" | "parallel" | "return") {
return Err(format!("unsupported step kind: {kind}"));
}
if matches!(kind, "model" | "input") {
let options = s.get("options").and_then(Value::as_array)
.ok_or_else(|| "choice step requires options list".to_string())?;
let _ = choice::parse_choice(&json!({"reply":"","options":options}))?;
if kind == "input" { let _ = field(s, "question")?; }
if kind == "model" { let _ = field(s, "prompt")?; }
}
if kind == "skill" { let _ = field(s, "skill")?; }
if kind == "parallel" && !s.get("tasks").is_some_and(Value::is_array) {
return Err("parallel step requires tasks array".into());
}
}
// Resolve all branch targets against frozen, forward-only step IDs.
for (i, s) in steps.iter().enumerate() {
let targets = s.get("next").and_then(Value::as_str).into_iter()
.chain(s.get("routes").and_then(Value::as_object)
.into_iter().flat_map(|m| m.values().filter_map(Value::as_str)));
for target in targets {
let position = steps.iter().position(|x|x["id"]==target)
.ok_or_else(|| format!("unknown workflow target: {target}"))?;
if position <= i {
return Err("workflow routes must move forward to avoid loops".into());
}
}
if let Some(routes)=s.get("routes").and_then(Value::as_object) {
if !matches!(s["kind"].as_str(),Some("model"|"input")) {
return Err("only choice steps may declare routes".into());
}
for key in routes.keys() {
if !s["options"].as_array().is_some_and(|opts|
opts.iter().any(|x|x.as_str()==Some(key.as_str()))) {
return Err("route label is not a declared choice".into());
}
}
}
}
Ok(Value::Array(steps.clone()))
}
fn advance_cursor(step:&Value, value:&Value, steps:&[Value], current:usize)->Result<usize,String> {
let target=if let Some(routes)=step.get("routes").and_then(Value::as_object) {
let label=value.as_str().ok_or("routed choice must return a text label")?;
Some(routes.get(label).and_then(Value::as_str)
.ok_or("chosen option is missing a declared route")?)
} else {
step.get("next").and_then(Value::as_str)
};
match target {
None=>Ok(current+1),
Some(name)=> {
let n=steps.iter().position(|s|s["id"]==name)
.ok_or("unknown target after checkpoint recovery")?;
if n<=current {return Err("cyclic route refused".into())}
Ok(n)
}
}
}
fn state(ckpt: &Value) -> Result<(&Value,usize),String> {
let meta = ckpt.get("meta").ok_or("missing workflow metadata")?;
if meta.get("kind").and_then(Value::as_str) != Some("MarqdoAgentFlowV1") {
return Err("checkpoint is not a workflow".into());
}
let index = meta.get("cursor").and_then(Value::as_u64)
.ok_or("missing workflow cursor")? as usize;
Ok((meta,index))
}
fn save(args: &Value, id: &str, meta: &Value, status: &str) -> Result<(),String> {
let result = resume::resume_save(&json!({
"id": id,
"resume_dir": args.get("resume_dir"),
"checkpoint_v2": true,
"status": status,
"meta": meta,
"completed_steps": meta["completed"],
"step_id": meta["steps"].get(meta["cursor"].as_u64().unwrap_or(0) as usize)
.and_then(|x| x.get("id")).cloned().unwrap_or(Value::Null)
}))?;
if result["ok"] != true { return Err("workflow checkpoint write failed".into()); }
Ok(())
}
/// Register a bounded, frozen plan. Re-opening never resets a progressed plan.
pub fn open(args: &Value) -> Result<Value,String> {
let id = field(args,"id")?;
let _guard = lock(args,id)?;
let revision = field(args,"source_revision")?;
if revision.len()>256 { return Err("source_revision too long".into()); }
let steps = validate_steps(args)?;
let existing = read(args,id)?;
let identity = context(args);
if existing["found"] == true {
if existing["ok"] == true
&& existing["meta"]["identity"] == identity
&& existing["meta"]["steps"] == steps
{
return next_doc(&existing,id,true);
}
return Ok(json!({"ok":false,"status":"conflict","error":"workflow.id_or_revision_reused"}));
}
let meta = json!({
"kind":"MarqdoAgentFlowV1",
"identity":identity,
"steps":steps,
"cursor":0,
"completed":[],
});
save(args,id,&meta,"running")?;
Ok(json!({"ok":true,"id":id,"status":"created","cursor":0}))
}
fn next_doc(ckpt: &Value, id: &str, reused: bool) -> Result<Value,String> {
let (meta,index)=state(ckpt)?;
let steps = meta["steps"].as_array().ok_or("invalid steps")?;
if index>=steps.len() {
return Ok(json!({"ok":true,"id":id,"status":"succeeded",
"cursor":index,"completed":meta["completed"],"reused":reused}));
}
let step=&steps[index];
let status=ckpt["status"].as_str().unwrap_or("running");
if status=="blocked" || status=="uncertain" || status=="cancelled" {
return Ok(json!({"ok":false,"id":id,"status":status,
"cursor":index,"step":step,"completed":meta["completed"],
"partial": meta.get("partial").cloned().unwrap_or(Value::Null)}));
}
// Never auto-dispatch effectful or unclassified child documents.
// Those must be executed using the existing EffectLedger policy and an
// independently verified receipt, not an arbitrary model instruction.
if (step["kind"]=="skill" || step["kind"]=="parallel")
&& step["effect_class"]!="read"
{
return Ok(json!({"ok":false,"id":id,"status":"manual_review",
"cursor":index,"step":step,
"reason":"automatic child dispatch requires an explicit read-only effect class"}));
}
let waiting=match step["kind"].as_str().unwrap_or("") {
"model"=>"waiting_model",
"input"=>"waiting_input",
"skill" | "parallel"=>"ready_tool",
"return"=>"ready_return",
_=>"blocked"
};
Ok(json!({"ok":true,"id":id,"status":waiting,
"cursor":index,"step":step,"completed":meta["completed"],"reused":reused}))
}
/// Query the durable next action. This is non-blocking and does not invoke LLM.
pub fn next(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"id":id,"status":"not_found_or_mismatched"}));
}
next_doc(&ckpt,id,false)
}
/// Read a workflow summary without advancing it or running any step.
/// The caller-supplied identity must match the checkpoint, exactly like next.
pub fn inspect(args:&Value)->Result<Value,String> {
let id=field(args,"id")?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"id":id,"status":"not_found_or_mismatched"}));
}
let (meta,index)=state(&ckpt)?;
let steps=meta["steps"].as_array().ok_or("invalid steps")?;
let completed=meta["completed"].as_array().ok_or("invalid completed")?;
// `status` is the durable checkpoint status; `action` is what tick would
// observe next (waiting_model, waiting_input, ready_tool, ...).
let action=next_doc(&ckpt,id,false)?.get("status").cloned().unwrap_or(Value::Null);
Ok(json!({
"ok":true,"id":id,
"status":ckpt["status"].as_str().unwrap_or("running"),
"action":action,
"cursor":index,
"total_steps":steps.len(),
"completed_steps":completed.len(),
"completed":meta["completed"],
"step":steps.get(index).cloned().unwrap_or(Value::Null),
"partial":meta.get("partial").cloned().unwrap_or(Value::Null),
"identity":meta["identity"],
"updated_at":ckpt.get("updated_at").cloned().unwrap_or(Value::Null)
}))
}
/// List workflow checkpoints in the (host-relative) resume directory.
/// Non-workflow checkpoints and corrupt entries are omitted. When the caller
/// supplies an attested session or principal, only matching runs are returned.
pub fn list(args:&Value)->Result<Value,String> {
let dir=storage(args)?;
let session=args.get("session_id").and_then(Value::as_str);
let principal=args.get("principal_ref").and_then(Value::as_str);
let mut items=Vec::new();
let rd=fs::read_dir(&dir).map_err(|e|format!("workflow list: {e}"))?;
for ent in rd.flatten() {
let path=ent.path();
if path.extension().and_then(|x|x.to_str())!=Some("json") { continue; }
if path.file_name().and_then(|x|x.to_str())
.map(|x|x.starts_with('.')).unwrap_or(false) { continue; }
let Ok(text)=fs::read_to_string(&path) else { continue };
let Ok(doc)=serde_json::from_str::<Value>(&text) else { continue };
let meta=&doc["meta"];
if meta["kind"].as_str()!=Some("MarqdoAgentFlowV1") { continue; }
if session.is_some() && meta["identity"]["session_id"].as_str()!=session { continue; }
if principal.is_some() && meta["identity"]["principal_ref"].as_str()!=principal { continue; }
let steps=meta["steps"].as_array().map(|x|x.len()).unwrap_or(0);
let completed=meta["completed"].as_array().map(|x|x.len()).unwrap_or(0);
items.push(json!({
"id":doc.get("id").cloned().unwrap_or(Value::Null),
"status":doc.get("status").cloned().unwrap_or(Value::Null),
"cursor":meta.get("cursor").cloned().unwrap_or(Value::Null),
"total_steps":steps,
"completed_steps":completed,
"source_revision":meta["identity"]["source_revision"],
"updated_at":doc.get("updated_at").cloned().unwrap_or(Value::Null)
}));
}
items.sort_by(|a,b| a["id"].as_str().cmp(&b["id"].as_str()));
Ok(json!({"ok":true,"items":items,"resume_dir":dir.to_string_lossy()}))
}
/// Commit a verified result for the exact current step. All mutations are
/// serialized with a lock; a completed step cannot be committed a second time.
pub fn commit(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let _guard=lock(args,id)?;
let step_id=field(args,"step_id")?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"status":"not_found_or_mismatched"}));
}
let (meta,index)=state(&ckpt)?;
let steps=meta["steps"].as_array().ok_or("invalid steps")?;
let response=args.get("response").ok_or("missing response")?;
if index>=steps.len() {
let previous = meta["completed"].as_array().ok_or("invalid completed")?;
if previous.iter().any(|x|x["step_id"]==step_id && x["value"]==*response) {
return Ok(json!({"ok":true,"status":"succeeded","reused":true}));
}
return Ok(json!({"ok":false,"status":"already_finished"}));
}
let step=&steps[index];
if step["id"]!=step_id {
if meta["completed"].as_array().is_some_and(|list|
list.iter().any(|x|x["step_id"]==step_id && x["value"]==*response))
{
return Ok(json!({"ok":true,"status":"already_committed","reused":true}));
}
return Ok(json!({"ok":false,"status":"step_conflict"}));
}
if ckpt["status"]!="running" {
return Ok(json!({"ok":false,"status":"blocked","reason":ckpt["status"]}));
}
let kind=field(step,"kind")?;
let value = match kind {
"model" | "input" => {
let reply = response.as_str().ok_or("model/input response must be text")?;
let valid=choice::parse_choice(&json!({"options":step["options"],"reply":reply}))?;
if valid["ok"]!=true {
return Ok(json!({"ok":false,"status":"invalid_choice",
"error":valid["error"]}));
}
valid["value"].clone()
}
"skill" => {
// A completed wait is not equivalent to a successful child process.
let exit = response.get("value").and_then(|v| v.get("code"))
.or_else(|| response.get("code")).and_then(Value::as_i64);
if response["ok"]==false || exit != Some(0) {
return Ok(json!({"ok":false,
"status":if exit.is_none() {"uncertain"} else {"failed"},
"reason":"child process exit code zero is required before commit"}));
}
response.clone()
}
"parallel" => {
let report=if response["schema"]=="AgentParallelResultV1" {
response.clone()
} else {
parallel::report(&json!({"results":response}))?
};
if report["ok"]!=true {
let status=if report["uncertain"].as_u64().unwrap_or(0)>0 {
"uncertain"
} else {"blocked"};
// Save the full manifest of successful and failed siblings before
// returning. Do not run failed/unknown children automatically.
let mut frozen=meta.clone();
frozen["partial"]=report.clone();
save(args,id,&frozen,status)?;
return Ok(json!({"ok":false,"status":status,
"report":report,"reason":"child results retained for reconciliation"}));
}
report
}
"return" => response.clone(),
_ => return Err("invalid step kind".into()),
};
let target=advance_cursor(step,&value,steps,index)?;
let mut new_meta=meta.clone();
new_meta["cursor"]=json!(target);
new_meta["completed"].as_array_mut().ok_or("completed not array")?
.push(json!({"step_id":step_id,"value":value}));
let terminal=target==steps.len();
save(args,id,&new_meta,if terminal {"succeeded"} else {"running"})?;
Ok(json!({"ok":true,"id":id,
"status":if terminal {"succeeded"} else {"advanced"},
"cursor":target,"value":value,"reused":false}))
}
/// Produce a plan containing only previously failed *read-only* child tasks.
/// "uncertain" children and effectful plans cannot be blindly retried.
pub fn retry_plan(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"status":"not_found_or_mismatched"}));
}
let (meta,index)=state(&ckpt)?;
if ckpt["status"]!="blocked" {
return Ok(json!({"ok":false,"status":"not_retryable"}));
}
let step=&meta["steps"][index];
if step["kind"]!="parallel" || step["effect_class"]!="read"
|| meta["partial"]["uncertain"].as_u64().unwrap_or(1)!=0
{
return Ok(json!({"ok":false,"status":"manual_reconciliation_required"}));
}
let Some(items)=meta["partial"]["items"].as_array() else {
return Err("partial report has no items".into());
};
let Some(tasks)=step["tasks"].as_array() else {
return Err("parallel plan has no tasks".into());
};
if items.len()!=tasks.len() {
return Err("partial report task count mismatch".into());
}
let mut failed=Vec::new();
let mut indices=Vec::new();
for (i,item) in items.iter().enumerate() {
if item["index"]!=i {
return Err("out-of-order child result index".into());
}
if item["status"]=="failed" {
failed.push(tasks[i].clone());
indices.push(i);
} else if item["status"]!="succeeded" {
return Ok(json!({"ok":false,"status":"manual_reconciliation_required"}));
}
}
Ok(json!({"ok":true,"status":"retry_read_only",
"id":id,"step_id":step["id"],"tasks":failed,"indices":indices}))
}
/// Merge only the failed child slots with verified new outcomes.
/// Successful results and their order remain untouched.
pub fn retry_commit(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let _guard=lock(args,id)?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"status":"not_found_or_mismatched"}));
}
let (meta,index)=state(&ckpt)?;
if ckpt["status"]!="blocked" {
return Ok(json!({"ok":false,"status":"not_retryable"}));
}
let step=&meta["steps"][index];
if step["kind"]!="parallel" || step["effect_class"]!="read"
|| meta["partial"]["uncertain"].as_u64().unwrap_or(1)!=0
{
return Ok(json!({"ok":false,"status":"manual_reconciliation_required"}));
}
let items=meta["partial"]["items"].as_array()
.ok_or("invalid partial report")?;
let incoming=args.get("results").and_then(Value::as_array)
.ok_or("retry_commit requires results list")?;
let expected=items.iter().filter(|it|it["status"]=="failed").count();
if incoming.len()!=expected {
return Err("retry result count differs from failed child count".into());
}
let mut next=Vec::with_capacity(items.len());
let mut replacement=incoming.iter();
for item in items {
if item["status"]=="succeeded" {
next.push(item["result"].clone());
} else if item["status"]=="failed" {
next.push(replacement.next().ok_or("missing retry result")?.clone());
} else {
return Ok(json!({"ok":false,"status":"manual_reconciliation_required"}));
}
}
let report=parallel::report(&json!({"results":next}))?;
let mut updated=meta.clone();
if report["ok"]==true {
let target=advance_cursor(step,&report,
updated["steps"].as_array().ok_or("steps missing")?,index)?;
updated["cursor"]=json!(target);
updated["partial"]=Value::Null;
updated["completed"].as_array_mut().ok_or("completed not list")?
.push(json!({"step_id":step["id"],"value":report}));
let finished=target==updated["steps"].as_array().ok_or("steps missing")?.len();
save(args,id,&updated,if finished {"succeeded"} else {"running"})?;
Ok(json!({"ok":true,"status":if finished {"succeeded"} else {"advanced"},
"cursor":target,"result":report}))
} else {
updated["partial"]=report.clone();
save(args,id,&updated,if report["uncertain"].as_u64().unwrap_or(0)>0 {
"uncertain" } else {"blocked"})?;
Ok(json!({"ok":false,"status":"blocked","report":report}))
}
}
pub fn cancel(args: &Value) -> Result<Value,String> {
let id=field(args,"id")?;
let _guard=lock(args,id)?;
let ckpt=read(args,id)?;
if ckpt["ok"]!=true || !check_context(args,&ckpt) {
return Ok(json!({"ok":false,"status":"not_found_or_mismatched"}));
}
if ckpt["status"]=="succeeded" {
return Ok(json!({"ok":false,"status":"already_finished"}));
}
let (meta,_)=state(&ckpt)?;
save(args,id,meta,"cancelled")?;
Ok(json!({"ok":true,"id":id,"status":"cancelled"}))
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::{AtomicU64,Ordering};
static SEQ: AtomicU64=AtomicU64::new(0);
fn fixture()->Value {
let n=SEQ.fetch_add(1,Ordering::Relaxed);
json!({"id":format!("wf-{}-{n}",std::process::id()),
"resume_dir":format!("target/workflow-test-{}-{n}",std::process::id()),
"source_revision":"v1",
"steps":[
{"id":"choose","kind":"model","prompt":"Choose a skill","options":["chat","office"]},
{"id":"answer","kind":"input","question":"OK?","options":["yes","no"]},
{"id":"end","kind":"return"}
]})
}
#[test]
fn nonblocking_model_then_input_then_terminal() {
let a=fixture();
assert_eq!(open(&a).unwrap()["status"],"created");
assert_eq!(next(&a).unwrap()["status"],"waiting_model");
let mut c=a.clone();
c["step_id"]=json!("choose");
c["response"]=json!("office");
assert_eq!(commit(&c).unwrap()["status"],"advanced");
assert_eq!(next(&a).unwrap()["status"],"waiting_input");
assert_eq!(commit(&c).unwrap()["status"],"already_committed");
c["step_id"]=json!("answer");
c["response"]=json!("yes");
assert_eq!(commit(&c).unwrap()["status"],"advanced");
c["step_id"]=json!("end");
c["response"]=json!("ok");
assert_eq!(commit(&c).unwrap()["status"],"succeeded");
assert_eq!(next(&a).unwrap()["status"],"succeeded");
assert_eq!(open(&a).unwrap()["status"],"succeeded");
}
#[test]
fn unknown_and_write_effects_never_auto_dispatch() {
let mut a=fixture();
a["steps"]=json!([{"id":"publish","kind":"skill","skill":"office"}]);
open(&a).unwrap();
assert_eq!(next(&a).unwrap()["status"],"manual_review");
}
#[test]
fn routes_skip_unselected_skill_branches() {
let mut a=fixture();
a["steps"]=json!([
{"id":"decide","kind":"model","prompt":"Pick","options":["chat","office"],
"routes":{"chat":"chat_skill","office":"office_skill"}},
{"id":"chat_skill","kind":"skill","skill":"chat","effect_class":"read","next":"done"},
{"id":"office_skill","kind":"skill","skill":"office","effect_class":"read","next":"done"},
{"id":"done","kind":"return"}
]);
open(&a).unwrap();
let mut c=a.clone();
c["step_id"]=json!("decide");
c["response"]=json!("office");
assert_eq!(commit(&c).unwrap()["cursor"],2);
assert_eq!(next(&a).unwrap()["step"]["id"],"office_skill");
c["step_id"]=json!("office_skill");
c["response"]=json!({"ok":true,"value":{"code":0}});
assert_eq!(commit(&c).unwrap()["cursor"],3);
assert_eq!(next(&a).unwrap()["step"]["id"],"done");
}
#[test]
fn source_change_conflict_and_invalid_model_choice() {
let a=fixture();
open(&a).unwrap();
let mut bad=a.clone();
bad["source_revision"]=json!("v2");
assert_eq!(next(&bad).unwrap()["status"],"not_found_or_mismatched");
assert_eq!(open(&bad).unwrap()["status"],"conflict");
let mut c=a.clone();
c["step_id"]=json!("choose");
c["response"]=json!("chat or office");
assert_eq!(commit(&c).unwrap()["status"],"invalid_choice");
assert_eq!(next(&a).unwrap()["status"],"waiting_model");
}
#[test]
fn partial_children_remain_durable_and_unknown_requires_reconciliation() {
let mut a=fixture();
a["steps"]=json!([{"id":"batch","kind":"parallel","tasks":[{"skill":"a"},{"skill":"b"}]}]);
open(&a).unwrap();
let mut c=a.clone();
c["step_id"]=json!("batch");
c["response"]=json!([
{"ok":true,"value":{"code":0,"value":"useful"}},
{"ok":false,"error":"connection lost"}
]);
assert_eq!(commit(&c).unwrap()["status"],"blocked");
let after=next(&a).unwrap();
assert_eq!(after["status"],"blocked");
assert_eq!(after["partial"]["succeeded"],1);
assert_eq!(after["partial"]["failed"],1);
assert_eq!(commit(&c).unwrap()["status"],"blocked");
}
#[test]
fn retries_only_failed_read_only_children_without_redoing_successes() {
let mut a=fixture();
a["steps"]=json!([{"id":"batch","kind":"parallel","effect_class":"read",
"tasks":[{"path":"a.mq.md"},{"path":"b.mq.md"}]}]);
open(&a).unwrap();
let mut c=a.clone();
c["step_id"]=json!("batch");
c["response"]=json!([
{"ok":true,"value":{"code":0,"value":"keep"}},
{"ok":false,"error":"temporary timeout"}
]);
assert_eq!(commit(&c).unwrap()["status"],"blocked");
let plan=retry_plan(&a).unwrap();
assert_eq!(plan["indices"],json!([1]));
assert_eq!(plan["tasks"].as_array().unwrap().len(),1);
let mut retry=a.clone();
retry["results"]=json!([{"ok":true,"value":{"code":0,"value":"fixed"}}]);
assert_eq!(retry_commit(&retry).unwrap()["status"],"succeeded");
let out=next(&a).unwrap();
assert_eq!(out["completed"][0]["value"]["items"][0]["result"]["value"]["value"],"keep");
assert_eq!(out["completed"][0]["value"]["items"][1]["result"]["value"]["value"],"fixed");
}
#[test]
fn inspect_and_list_are_read_only_and_session_scoped() {
let mut a=fixture();
a["session_id"]=json!("s1");
a["principal_ref"]=json!("u1");
open(&a).unwrap();
let seen=inspect(&a).unwrap();
assert_eq!(seen["status"],"running");
assert_eq!(seen["action"],"waiting_model");
assert_eq!(seen["total_steps"],3);
assert_eq!(seen["completed_steps"],0);
assert_eq!(seen["step"]["id"],"choose");
// Inspection must not consume the current step.
assert_eq!(next(&a).unwrap()["status"],"waiting_model");
let listed=list(&a).unwrap();
assert!(listed["items"].as_array().unwrap()
.iter().any(|x|x["id"]==a["id"]));
let mut other=a.clone();
other["session_id"]=json!("s2");
assert_eq!(inspect(&other).unwrap()["status"],"not_found_or_mismatched");
assert!(list(&other).unwrap()["items"].as_array().unwrap().is_empty());
}
#[test]
fn explicit_cancel_stops_future_commits() {
let a=fixture();
open(&a).unwrap();
assert_eq!(cancel(&a).unwrap()["status"],"cancelled");
let mut c=a.clone();
c["step_id"]=json!("choose");
c["response"]=json!("chat");
assert_eq!(commit(&c).unwrap()["status"],"blocked");
}
}
+70
View File
@@ -0,0 +1,70 @@
---
markup: occlusion
title: AI native flow offline smoke
import:
flow: ext/ai/flow.mq.md
context: ext/ai/context.mq.md
json: lib/json.mq.md
sys: lib/sys.mq.md
---
# main
This fixture tests the real Marqdo interface without a model provider.
It refuses an invalid choice and retrieves only the designated function
rather than guessing another SKILL or importing the full document.
**opts = > json.parse text=["chat","office"]**
**pick = > flow.parse_choice reply="选择:office" options=`opts`**
**value = > json.get value=`pick` key="value"**
1. `value` == "office"
**_ = 1**
2. *
**debug_pick = > json.stringify value=`pick`**
> print text=`debug_pick`
> sys.exit code=11
**structured = > flow.parse_choice reply="{\"choice\":\"chat\"}" options=`opts`**
**structure_value = > json.get value=`structured` key="value"**
1. `structure_value` == "chat"
**_ = 1**
2. *
> sys.exit code=16
**invalid = > flow.parse_choice reply="chat 或 office" options=`opts`**
**not_ok = > json.get value=`invalid` key="ok"**
1. `not_ok`
> sys.exit code=12
2. *
**_ = 1**
**ctx = > context.scope scope="function" class="main" function="probe" max_chars=200**
**ok = > json.get value=`ctx` key="ok"**
1. `ok`
**_ = 1**
2. *
> sys.exit code=13
**packed = > context.compose user="Test the route" class="main" function="probe" budget_tokens=2048**
**pack_schema = > json.get value=`packed` key="schema"**
1. `pack_schema` == "ContextPackV2"
**_ = 1**
2. *
> sys.exit code=15
**gate = > flow.input id="ai_native_flow_ci_gate" question="Continue?" options=`opts` source_revision="fixture-v1" freeform=False**
**answered = > flow.reply id="ai_native_flow_ci_gate" reply="office" source_revision="fixture-v1"**
**answer = > json.get value=`answered` key="value"**
1. `answer` == "office"
**_ = 1**
2. *
> sys.exit code=14
Return *"ai-flow-native-ok"*.
## probe
This private helper's narrative should be extracted by the scoped selector
without including the root SKILL or neighboring function definitions.
Return *"probe"*.
+124
View File
@@ -0,0 +1,124 @@
---
markup: occlusion
title: ABI-native durable agent workflow test
import:
workflow: ext/ai/workflow.mq.md
json: lib/json.mq.md
sys: lib/sys.mq.md
time: lib/time.mq.md
---
# main
Offline test: the same Marqdo program advances through model choice, user
input and terminal state with plugin-owned durable checkpoints. The run ID and
checkpoint directory include the current millisecond so repeated local runs
start clean instead of reopening yesterday's completed workflow.
**now = > time.now_ms**
**stamp = > json.stringify value=`now`**
**rid = "abi_flow_ci_" + stamp**
**dir = ".marqdo/ai-native-workflow-" + stamp**
**steps = > json.parse text=[{"id":"intent","kind":"model","prompt":"Choose next skill","options":["chat","office"]},{"id":"confirm","kind":"input","question":"Continue?","options":["yes","no"]},{"id":"end","kind":"return"}]**
**opened = > workflow.open id=`rid` steps=`steps` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**o = > json.get value=`opened` key="ok"**
1. `o`
**_ = 1**
2. *
> sys.exit code=21
**seen = > workflow.inspect id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**seen_status = > json.get value=`seen` key="action"**
**seen_total = > json.get value=`seen` key="total_steps"**
1. `seen_status` == "waiting_model"
1. `seen_total` == 3
**_ = 1**
2. *
> sys.exit code=30
2. *
> sys.exit code=31
**listed = > workflow.list session_id="ci-session" resume_dir=`dir`**
**listed_ok = > json.get value=`listed` key="ok"**
**listed_items = > json.get value=`listed` key="items"**
**listed_n = > len value=`listed_items`**
1. `listed_ok`
1. `listed_n` > 0
**_ = 1**
2. *
> sys.exit code=32
2. *
> sys.exit code=33
**first = > workflow.next id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**first_state = > json.get value=`first` key="status"**
1. `first_state` == "waiting_model"
**_ = 1**
2. *
> sys.exit code=22
**c1 = > workflow.commit id=`rid` step_id="intent" response="chat" source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**done1 = > json.get value=`c1` key="ok"**
1. `done1`
**_ = 1**
2. *
> sys.exit code=23
**progress = > workflow.inspect id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**progress_done = > json.get value=`progress` key="completed_steps"**
1. `progress_done` == 1
**_ = 1**
2. *
> sys.exit code=34
**second = > workflow.tick id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**second_state = > json.get value=`second` key="status"**
1. `second_state` == "waiting_input"
**_ = 1**
2. *
> sys.exit code=24
**c2 = > workflow.commit id=`rid` step_id="confirm" response="yes" source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**done2 = > json.get value=`c2` key="ok"**
1. `done2`
**_ = 1**
2. *
> sys.exit code=25
**c3 = > workflow.tick id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**complete = > workflow.next id=`rid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**status = > json.get value=`complete` key="status"**
1. `status` == "succeeded"
**_ = 1**
2. *
> sys.exit code=26
**partial_steps = > json.parse text=[{"id":"children","kind":"parallel","effect_class":"read","tasks":[{"path":"worker-a.mq.md"},{"path":"worker-b.mq.md"}]}]**
**prid = "abi_flow_partial_ci_" + stamp**
**new_batch = > workflow.open id=`prid` steps=`partial_steps` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**parts = > json.parse text=[{"ok":true,"value":{"code":0,"value":"useful"}},{"ok":false,"error":"timeout"}]**
**stopped = > workflow.commit id=`prid` step_id="children" response=`parts` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**reloaded = > workflow.next id=`prid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**partial = > json.get value=`reloaded` key="partial"**
**survivors = > json.get value=`partial` key="succeeded"**
1. `survivors` == 1
**_ = 1**
2. *
> sys.exit code=27
**retry_plan = > workflow.retry_plan id=`prid` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**allowed = > json.get value=`retry_plan` key="ok"**
1. `allowed`
**_ = 1**
2. *
> sys.exit code=28
**repaired = > json.parse text=[{"ok":true,"value":{"code":0,"value":"repaired"}}]**
**merged = > workflow.retry_commit id=`prid` results=`repaired` source_revision="flow-v1" session_id="ci-session" resume_dir=`dir`**
**merged_ok = > json.get value=`merged` key="ok"**
1. `merged_ok`
**_ = 1**
2. *
> sys.exit code=29
Return *"durable-agent-flow-ok"*.