From 38c07d9a0e710190f1be58af0c2c567c9fdaa84c Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 18 Nov 2026 11:57:12 +0800 Subject: [PATCH] feat(agent): add workflow inspection and durable isolation - add agent_workflow_inspect/list primitives and ext/ai wrappers - expose host-relative resume_dir on every workflow operation - make offline workflow fixture repeatable with a timestamped run id - fix flow.choose branch scoping contract diagnostic - build the agent cdylib and drop the removed run --effects flag in CI --- .github/workflows/executable-knowledge.yml | 6 +- .github/workflows/native-ai-flow.yml | 12 ++- .gitignore | 2 + CHANGELOG.md | 15 +++ doc/design/native-agent-flow-v3.md | 17 ++- ext/ai/flow.mq.md | 28 ++--- ext/ai/index.mq.md | 4 +- ext/ai/workflow.mq.md | 120 +++++++++++++++++---- plugins/agent/src/lib.rs | 16 +-- plugins/agent/src/workflow.rs | 88 +++++++++++++++ tests/ext/ai-native-workflow.mq.md | 65 ++++++++--- 11 files changed, 308 insertions(+), 65 deletions(-) diff --git a/.github/workflows/executable-knowledge.yml b/.github/workflows/executable-knowledge.yml index 430e086..e6cc297 100644 --- a/.github/workflows/executable-knowledge.yml +++ b/.github/workflows/executable-knowledge.yml @@ -26,9 +26,11 @@ jobs: 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 --effects plugin,fs.write - cargo run --locked -- run tests/ext/ai-native-workflow.mq.md --effects plugin,fs.write + 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 index 7496adc..da1c944 100644 --- a/.github/workflows/native-ai-flow.yml +++ b/.github/workflows/native-ai-flow.yml @@ -20,7 +20,9 @@ jobs: steps: - uses: actions/checkout@v4 - uses: dtolnay/rust-toolchain@stable - - name: Build plugin and run native tests + - 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: | @@ -28,7 +30,11 @@ jobs: 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 --effects plugin,fs.write - cargo run --locked -- run tests/ext/ai-native-workflow.mq.md --effects plugin,fs.write + 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 100644 --- 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 b910e1a..5f3f859 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,21 @@ ## 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. + ## v2.7.1 — 2026-11-11 CLI 修复发布:View 实际逻辑的手动开合不再被布局重排或运行结果刷新覆盖;函数、链接、列表和记录按内容排版,手机详情整行展示。核心仍为 19 个构造;拓展库保留 2.7.0。 diff --git a/doc/design/native-agent-flow-v3.md b/doc/design/native-agent-flow-v3.md index 54b6cf7..ce85b0c 100644 --- a/doc/design/native-agent-flow-v3.md +++ b/doc/design/native-agent-flow-v3.md @@ -16,10 +16,16 @@ continuation or exactly-once external writes based on a checkpoint file. | 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` and `agent_parallel_report`. +`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 @@ -94,9 +100,12 @@ runtime gates, including crash injection and multi-worker concurrency, pass. ## Plugin-only workflow (November 18 revision) -The Agent ABI plugin implements `agent_workflow_open/next/commit/cancel`. -The small `ext/ai/workflow.mq.md` library wraps these primitives and provides -`tick` to execute exactly one safe decision or document task per call. +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 diff --git a/ext/ai/flow.mq.md b/ext/ai/flow.mq.md index 346fd69..a005f15 100644 --- a/ext/ai/flow.mq.md +++ b/ext/ai/flow.mq.md @@ -65,20 +65,20 @@ We retain **err = [Check model transport error](json.get(value=`turn`, key="erro 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*. + 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 diff --git a/ext/ai/index.mq.md b/ext/ai/index.mq.md index 197615e..0015ff9 100644 --- a/ext/ai/index.mq.md +++ b/ext/ai/index.mq.md @@ -10,7 +10,9 @@ stream collection and usage; [provider adapters](llm/index.mq.md) describe OpenA 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. [Native flow](flow.mq.md) provides short, verified model choices and bounded document -concurrency; [context](context.mq.md) packs explicit source scopes; [recovery](recovery.mq.md) +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 diff --git a/ext/ai/workflow.mq.md b/ext/ai/workflow.mq.md index 352b8ce..52014df 100644 --- a/ext/ai/workflow.mq.md +++ b/ext/ai/workflow.mq.md @@ -12,7 +12,8 @@ import: 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. +model text is never an identity or permission token. `resume_dir` is a +host-relative checkpoint directory, never an absolute client path. ## open @@ -23,17 +24,22 @@ model text is never an identity or permission token. | 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 as the inputs for this operation. +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`))*. + 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\"}"))*. @@ -45,17 +51,75 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* | 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 as the inputs for this operation. +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`))*. + 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\"}"))*. @@ -69,17 +133,21 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* | 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 as the inputs for this operation. +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`))*. + 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\"}"))*. @@ -91,17 +159,21 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* | 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 as the inputs for this operation. +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`))*. + 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\"}"))*. @@ -116,18 +188,19 @@ We retain **p = [Locate the Agent ABI plugin](plugin.native_path(name="agent"))* | 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 as the inputs for this operation. +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. -We retain **state = [Load the next action](next(id=`id`, source_revision=`source_revision`, session_id=`session_id`, principal_ref=`principal_ref`))**. +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"))**. @@ -138,7 +211,7 @@ We retain **status = [Read action status](json.get(value=`state`, key="status")) 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`))*. + 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" @@ -148,18 +221,18 @@ We retain **status = [Read action status](json.get(value=`state`, key="status")) 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`))*. + 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`))*. + 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`))*. + 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*. @@ -172,12 +245,13 @@ We retain **status = [Read action status](json.get(value=`state`, key="status")) | 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 as the inputs for this operation. +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. @@ -185,7 +259,7 @@ 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`))*. + 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\"}"))*. @@ -198,12 +272,13 @@ We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. | 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 as the inputs for this operation. +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. @@ -211,7 +286,7 @@ 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`))*. + 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\"}"))*. @@ -225,21 +300,22 @@ We retain **p = [Locate Agent ABI plugin](plugin.native_path(name="agent"))**. | 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 as the inputs for this operation. +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`))**. +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`))*. + 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/src/lib.rs b/plugins/agent/src/lib.rs index eaac5a9..9234f45 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -846,6 +846,8 @@ 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"); @@ -984,12 +986,14 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int ("agent_input_open", "id,question,options,source_revision", agent_input_open), ("agent_input_resume", "id,reply,source_revision", agent_input_resume), ("agent_parallel_report", "results", agent_parallel_report), - ("agent_workflow_open", "id,steps,source_revision", agent_workflow_open), - ("agent_workflow_next", "id,source_revision", agent_workflow_next), - ("agent_workflow_commit", "id,step_id,response,source_revision", agent_workflow_commit), - ("agent_workflow_cancel", "id,source_revision", agent_workflow_cancel), - ("agent_workflow_retry_plan", "id,source_revision", agent_workflow_retry_plan), - ("agent_workflow_retry_commit", "id,results,source_revision", agent_workflow_retry_commit), + ("agent_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/workflow.rs b/plugins/agent/src/workflow.rs index 5e10548..f7d3578 100644 --- a/plugins/agent/src/workflow.rs +++ b/plugins/agent/src/workflow.rs @@ -245,6 +245,71 @@ pub fn next(args: &Value) -> Result { 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 { @@ -578,6 +643,29 @@ mod tests { 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(); diff --git a/tests/ext/ai-native-workflow.mq.md b/tests/ext/ai-native-workflow.mq.md index 418f787..83d8ca0 100644 --- a/tests/ext/ai-native-workflow.mq.md +++ b/tests/ext/ai-native-workflow.mq.md @@ -5,51 +5,89 @@ 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. +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="abi_flow_ci_20261118" steps=`steps` source_revision="flow-v1"** +**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 -**first = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**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="abi_flow_ci_20261118" step_id="intent" response="chat" source_revision="flow-v1"** +**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 -**second = > workflow.tick id="abi_flow_ci_20261118" source_revision="flow-v1"** +**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="abi_flow_ci_20261118" step_id="confirm" response="yes" source_revision="flow-v1"** +**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="abi_flow_ci_20261118" source_revision="flow-v1"** -**complete = > workflow.next id="abi_flow_ci_20261118" source_revision="flow-v1"** +**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** @@ -57,10 +95,11 @@ input and terminal state with plugin-owned durable checkpoints. > sys.exit code=26 **partial_steps = > json.parse text=[{"id":"children","kind":"parallel","effect_class":"read","tasks":[{"path":"worker-a.mq.md"},{"path":"worker-b.mq.md"}]}]** -**new_batch = > workflow.open id="abi_flow_partial_ci_20261118" steps=`partial_steps` source_revision="flow-v1"** +**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="abi_flow_partial_ci_20261118" step_id="children" response=`parts` source_revision="flow-v1"** -**reloaded = > workflow.next id="abi_flow_partial_ci_20261118" source_revision="flow-v1"** +**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 @@ -68,14 +107,14 @@ input and terminal state with plugin-owned durable checkpoints. 2. * > sys.exit code=27 -**retry_plan = > workflow.retry_plan id="abi_flow_partial_ci_20261118" source_revision="flow-v1"** +**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="abi_flow_partial_ci_20261118" results=`repaired` source_revision="flow-v1"** +**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**