diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index 2dcecd5..e6cc297 100755 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -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 diff --git a/.github/workflows/native-ai-flow.yml b/.github/workflows/native-ai-flow.yml new file mode 100644 index 0000000..da1c944 --- /dev/null +++ b/.github/workflows/native-ai-flow.yml @@ -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 diff --git a/.gitignore b/.gitignore index 919c8d5..94642b7 100755 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 25baeac..7676640 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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`;单调性护栏让判定器缺陷显式失败;假定理给出反例见证;证书缓存与目录模式面向智能体批量出证。 diff --git a/Cargo.lock b/Cargo.lock index 1f83758..62a9995 100755 --- a/Cargo.lock +++ b/Cargo.lock @@ -668,6 +668,7 @@ version = "0.1.0" dependencies = [ "chrono", "marqdo-plugin-sdk", + "pulldown-cmark", "serde_json", ] diff --git a/doc/design/native-agent-flow-v3.md b/doc/design/native-agent-flow-v3.md new file mode 100644 index 0000000..ce85b0c --- /dev/null +++ b/doc/design/native-agent-flow-v3.md @@ -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. diff --git a/ext/ai/context.mq.md b/ext/ai/context.mq.md new file mode 100644 index 0000000..375ba07 --- /dev/null +++ b/ext/ai/context.mq.md @@ -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`))*. diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md new file mode 100644 index 0000000..a005f15 --- /dev/null +++ b/ext/ai/flow.mq.md @@ -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`))*. diff --git a/ext/ai/index.mq.md b/ext/ai/index.mq.md index 70ac986..0015ff9 100755 --- a/ext/ai/index.mq.md +++ b/ext/ai/index.mq.md @@ -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 diff --git a/ext/ai/recovery.mq.md b/ext/ai/recovery.mq.md new file mode 100644 index 0000000..afe2e47 --- /dev/null +++ b/ext/ai/recovery.mq.md @@ -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`))*. diff --git a/ext/ai/workflow.mq.md b/ext/ai/workflow.mq.md new file mode 100644 index 0000000..8c8137b --- /dev/null +++ b/ext/ai/workflow.mq.md @@ -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*. diff --git a/plugins/agent/Cargo.toml b/plugins/agent/Cargo.toml index 663e5b8..4965693 100755 --- a/plugins/agent/Cargo.toml +++ b/plugins/agent/Cargo.toml @@ -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"] } diff --git a/plugins/agent/src/choice.rs b/plugins/agent/src/choice.rs new file mode 100644 index 0000000..cb63e68 --- /dev/null +++ b/plugins/agent/src/choice.rs @@ -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 { + 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 { + 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::() { + 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 { + 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); + } +} diff --git a/plugins/agent/src/context_scope.rs b/plugins/agent/src/context_scope.rs new file mode 100644 index 0000000..b970d57 --- /dev/null +++ b/plugins/agent/src/context_scope.rs @@ -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
{ + let mut out = Vec::new(); + let mut pending: Option
= 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 { + 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
= 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); + } +} diff --git a/plugins/agent/src/effects.rs b/plugins/agent/src/effects.rs index bd80c0f..0cc35ed 100755 --- a/plugins/agent/src/effects.rs +++ b/plugins/agent/src/effects.rs @@ -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); } } diff --git a/plugins/agent/src/error.rs b/plugins/agent/src/error.rs index 5223b82..d9a6317 100755 --- a/plugins/agent/src/error.rs +++ b/plugins/agent/src/error.rs @@ -82,6 +82,10 @@ pub fn decide_retry(args: &Value) -> Result { .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 { "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(); diff --git a/plugins/agent/src/input.rs b/plugins/agent/src/input.rs new file mode 100644 index 0000000..7e11b1e --- /dev/null +++ b/plugins/agent/src/input.rs @@ -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 { + 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 { + 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 { + 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 { + 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 { + 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"); + } +} diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 1bcabef..9234f45 100755 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -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), diff --git a/plugins/agent/src/parallel.rs b/plugins/agent/src/parallel.rs new file mode 100644 index 0000000..e5d6ad2 --- /dev/null +++ b/plugins/agent/src/parallel.rs @@ -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 { + 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); + } +} diff --git a/plugins/agent/src/resume.rs b/plugins/agent/src/resume.rs index 25835fa..821aec1 100755 --- a/plugins/agent/src/resume.rs +++ b/plugins/agent/src/resume.rs @@ -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); } } diff --git a/plugins/agent/src/workflow.rs b/plugins/agent/src/workflow.rs new file mode 100644 index 0000000..f7d3578 --- /dev/null +++ b/plugins/agent/src/workflow.rs @@ -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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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::(&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 { + 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 { + 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 { + 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 { + 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"); + } +} diff --git a/tests/ext/ai-native-flow.mq.md b/tests/ext/ai-native-flow.mq.md new file mode 100644 index 0000000..f5598c5 --- /dev/null +++ b/tests/ext/ai-native-flow.mq.md @@ -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"*. diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md new file mode 100644 index 0000000..83d8ca0 --- /dev/null +++ b/tests/ext/ai-native-workflow.mq.md @@ -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"*.