Files
marqdo/ext/ai/workflow.mq.md
cflmy 895752a1fd Merge v2.8.0 into native AI flow branch
- take the 2.8.0 crate versions, Cargo.lock dependency graph and release workflows
- keep the native workflow inspect/list, resume_dir isolation and repeatable fixtures
- satisfy the 2.8.0 library narrative gate for workflow.tick
- resolve CHANGELOG ordering with the v2.8.0 release entry
2026-11-18 12:14:03 +08:00

16 KiB
Raw Permalink Blame History

markup, title, description, import
markup title description import
occlusion Native AI workflow — durable, short, one-step-at-a-time execution Plugin-managed checkpointed decision flow without an external agent runtime.
plugin json flow subtask
lib/plugin.mq.md lib/json.mq.md ext/ai/flow.mq.md 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.

  1. p We Load Agent ABI plugin. 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)).

Return Missing ABI plugin.

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.

  1. p We Load Agent ABI plugin. 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)).

Return Missing ABI plugin.

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.

  1. p We Load Agent ABI plugin. 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)).

Return Missing ABI plugin.

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.

  1. p We Load Agent ABI plugin. Return [List workflow checkpoints](agent_workflow_list(session_id=session_id, principal_ref=principal_ref, resume_dir=resume_dir)).

Return Missing ABI plugin.

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.

  1. p We Load Agent ABI plugin. 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)).

Return Missing ABI plugin.

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.

  1. p We Load Agent ABI plugin. Return [Commit cancellation](agent_workflow_cancel(id=id, source_revision=source_revision, session_id=session_id, principal_ref=principal_ref, resume_dir=resume_dir)).

Return Missing ABI plugin.

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")).
  2. 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)).
Return *answer*.
  1. 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")).
  2. kind == "parallel" We retain tasks = [Read child tasks](json.get(value=step, key="tasks")). We retain report = Run bounded parallel documents. 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)).
  3. 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)).
Return *state*.
  1. 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)).

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.

  1. p We Load Agent ABI plugin. 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)).

Return Native plugin 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.

  1. p We Load Agent ABI plugin. 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)).

Return Native plugin 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)).

Return plan.