Files
marqdo/ext/ai/flow.mq.md
cflmy 38c07d9a0e 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
2026-11-18 11:57:12 +08:00

9.6 KiB

markup, title, description, import
markup title description import
occlusion AI flow — small-model choices and bounded subtasks Short model decisions, verified options and concurrent Marqdo documents.
llm json plugin subtask
ext/ai/llm.mq.md lib/json.mq.md lib/plugin.mq.md 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.

  1. p We Load the agent plugin.

Return Missing native parser.

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. 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. We retain turn = Ask the model once. We retain err = [Check model transport error](json.get(value=turn, key="error")).

  1. err Return turn.

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. 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)).
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.

  1. p We Load native agent plugin. Return Preserve success, failure and uncertain child outcomes.

Return Native result classifier 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.

  1. p We Load native agent plugin.

Return No native gate available.

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.

  1. p We Load native agent plugin.

Return No native gate available.

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.

We retain task = Spawn registered Marqdo document. Return Await the subtask result.

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)).