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:
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
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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
@@ -668,6 +668,7 @@ version = "0.1.0"
|
||||
dependencies = [
|
||||
"chrono",
|
||||
"marqdo-plugin-sdk",
|
||||
"pulldown-cmark",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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`))*.
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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`))*.
|
||||
@@ -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*.
|
||||
@@ -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"] }
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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();
|
||||
|
||||
@@ -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");
|
||||
}
|
||||
}
|
||||
@@ -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),
|
||||
|
||||
@@ -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
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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");
|
||||
}
|
||||
}
|
||||
@@ -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"*.
|
||||
@@ -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"*.
|
||||
Reference in new issue
Block a user