- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
253 KiB
Executable File
markup, title, description, import
| markup | title | description | import | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| occlusion | ext/ai/agent | Document-driven agent v2 — step / plan / run; Skill Compilation via ABI plugin (episodes → learn → llm_free). |
|
This file owns agent orchestration: call-site context, explicit tools, routing, workbooks, observations and continuation. Start with the AI workflows for package choices and native dependencies. Use step for one turn, run for reuse and learning, and plan for a bounded workbook lifecycle. Internal helpers are documented for development but are not automatically model-callable tools. Changes must preserve source authority, effect deduplication and the location of writeback.
build_step_context
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| agent | any | required | Agent configuration or receiver created by this package |
| task | any | required | Structured task or text supplied to the agent |
| source_depth | any | "default" | Source-context depth; default follows the documented context budget |
| skill_depth | any | "default" | Skill-context depth; default follows the documented context budget |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Assemble a readable prompt: standing, task, call site, tools, budgeted source + skill, and the act protocol. The runbook .mq.md is ground truth (code as documentation). Default budgets keep long files from exploding the window; emit READ:source / READ:skill (Chinese 读取:) to deepen, then answer or CALL:. |
Use agent, task, source_depth="default", skill_depth="default" as the inputs for this operation.
Assemble a readable prompt: standing, task, call site, tools, budgeted source + skill, and the act protocol.
The runbook .mq.md is ground truth (code as documentation). Default budgets keep long files from exploding the window; emit READ:source / READ:skill (Chinese 读取:) to deepen, then answer or CALL:.
The sections have different authority. Standing text sets the agent's role, task text states the current request, and the call site identifies the exact source location that requested it. Source and skill excerpts are bounded evidence for that location. They are not a replacement for the author's runbook. The returned prompt is plain text; constructing it does not call a model or execute any listed tool.
Tool descriptions come from the supplied whitelist. The act instructions restrict CALL names to that section, so an internal helper mentioned elsewhere is not automatically callable. A truncated excerpt can request a deeper source or skill read through the explicit READ protocol. The caller must enforce its read budget and tool permissions; these instructions alone are not an authorization mechanism.
We retain standing = [Read the standing field](json.get(value=agent, key="standing")).
standingWe retain up = standing.-
We retain up = None.
We retain tools = [Read the tools field](json.get(value=agent, key="tools")).
We retain tools_s = Format tools.
We retain src = Source brief.
We retain site = Call site.
We retain site_s = Encode the structured value as JSON text.
We retain skill = Skill brief.
We retain task_s = Encode the structured value as JSON text.
Keep this text as ordered lines so its instructions and blank-line boundaries can be read directly.
_literal_esc_g_lines =
| line |
|---|
| "" |
| "" |
| "--- how to act ---" |
| "Call ONLY names listed under --- tools --- (whitelist). If that section is empty or says none, do NOT emit CALL / 调用 — reply with the final answer only." |
| "Never CALL internal framework helpers (build_step_context, plan, inspect_workbook, etc.)." |
| "Context is budgeted: if you see a [truncated …] marker, you may first emit exactly one line READ:source or READ:skill (Chinese: 读取:source|skill) to deepen, then you will be re-prompted." |
| "When calling an allowed tool, reply with exactly one line: CALL:" |
| "(Chinese ok: 调用:)" |
| "Otherwise reply with the final answer only." |
| "If a capability cannot truly be wired, do NOT fake it silently and never claim it works: write an occlusion with an explicit status, e.g. 按关键词检索,接口未接,待开发. Stubs must run without error and must state their return value (None is acceptable). Before finishing, check your own declarations with labels.search." |
| "Tools run via Marqdo subtask (spawn fn / wait)." |
| "" |
Join exactly those lines into _literal_esc_g_text = [Retain the original newline boundaries](text.str_join(xs=_literal_esc_g_lines, sep="\n")).
The following record names each literal field without a JSON construction chain.
_literal_esc_fields =
| @ | key | value |
|---|---|---|
| 1 | "a" | "\n\n--- standing ---\n" |
| 2 | "b" | "\n\n--- task ---\n" |
| 3 | "c" | "\n\n--- tools ---\n" |
| 4 | "d" | "\n\n--- call site ---\n" |
| 5 | "e" | "\n\n--- source (.mq.md) ---\n" |
| 6 | "f" | "\n\n--- marqdo skill ---\n" |
| 7 | "g" | _literal_esc_g_text |
We build esc = Collect these named fields into one record.
We retain a = [Read the a field](json.get(value=esc, key="a")).
We retain b = [Read the b field](json.get(value=esc, key="b")).
We retain c = [Read the c field](json.get(value=esc, key="c")).
We retain d = [Read the d field](json.get(value=esc, key="d")).
We retain e = [Read the e field](json.get(value=esc, key="e")).
We retain f = [Read the f field](json.get(value=esc, key="f")).
We retain g = [Read the g field](json.get(value=esc, key="g")).
We retain p = "You are a Marqdo agent. Code is documentation: this runbook source and call site are your ground truth — not a hidden system prompt. When you cannot wire a capability, declare it in the description (待开发 / 模拟) instead of faking success.". We retain p = p + a + up + b + task_s + d + site_s + c + tools_s + e + src + f + skill + g. Return p.
model_turn
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| model | any | required | Model resource or provider model identifier, as required by this operation |
| prompt | any | required | Prompt text or structured prompt expected by this adapter |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| stream_kind | any | "delta" | Streaming event projection selected by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | One LLM turn via the semantic surface (ask / stream+collect). Returns {text,llm_calls,tokens} for episode metrics; transport failures set error + llm_calls=0 (never abort). |
Use model, prompt, stream=False, echo=False, stream_kind="delta" as the inputs for this operation.
One LLM turn via the semantic surface (ask / stream+collect). Returns {text,llm_calls,tokens} for episode metrics; transport failures set error + llm_calls=0 (never abort).
stream_kind=plan publishes protocol tokens onto the process trail (not the answer bubble).
streamWe retainevs= [Stream](>model.stream prompt=promptecho=echostream_kind=stream_kind). We retaintext= Collect. We retaintokens= Collect usage.tokens== None We retain tokens = 0.-
**_ = 1**
We retain err = None. We retain calls = 1.
- not
textWe retaine0= [At](at(value=evs, index=0)). We retaine0_s= Encode the structured value as JSON text. We retaine0_map= [Starts with](text.starts_with(text=e0_s, prefix="{")). 1.e0_mapWe retainerr= [Read the message field](json.get(value=e0, key="message")).errWe retain calls = 0. 2. * _ = 1
-
We retain r = [Ask](> model.ask prompt=prompt ).
We retain r_s = Encode the structured value as JSON text.
We retain r_map = [Starts with](text.starts_with(text=r_s, prefix="{")).
r_mapWe retaintext= [Read the text field](json.get(value=r, key="text")). We retaintokens= [Read the tokens field](json.get(value=r, key="tokens")). We retainerr= [Read the error field](json.get(value=r, key="error")). We retainfin= [Read the finish field](json.get(value=r, key="finish")). 1.tokens== None We retainusage= [Read the usage field](json.get(value=r, key="usage")).usageWe retaintokens= [Read the total_tokens field](json.get(value=usage, key="total_tokens")).
-
We retain **`text` = [Str](str(value=`r`))**.
We retain **tokens = 0**.
We retain **err = None**.
We retain **fin = None**.
tokens== None We retain tokens = 0.-
**_ = 1**
errWe retain calls = 0.fin== "error" We retain calls = 0. 1. noterrWe retain err = "llm transport error".-
We retain **calls = 1**.
out =
| text | llm_calls | tokens | error |
|---|---|---|---|
text |
calls |
tokens |
err |
Return out.
dump_step_context
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| agent | any | required | Agent configuration or receiver created by this package |
| task | any | "" | Structured task or text supplied to the agent |
| source_depth | any | "default" | Source-context depth; default follows the documented context budget |
| skill_depth | any | "default" | Skill-context depth; default follows the documented context budget |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Inspect what build_step_context would send — no LLM. Returns a map: prompt, call_site, prompt_chars, truncated (true when budget markers appear). Use for harness / debugging the code-as-doc pipeline. |
Use agent, task="", source_depth="default", skill_depth="default" as the inputs for this operation.
Inspect what build_step_context would send — no LLM. Returns a map: prompt, call_site, prompt_chars, truncated (true when budget markers appear). Use for harness / debugging the code-as-doc pipeline.
We retain prompt = [Build step context](build_step_context(agent=agent, task=task, source_depth=source_depth, skill_depth=skill_depth)).
We retain site = Call site.
We retain chars = Len.
We retain parts = [Split](split(value=prompt, sep="[truncated")).
We retain n = Len.
We retain truncated = False.
n> 1 We retain truncated = True.-
_ = 1
out =
| prompt | call_site | prompt_chars | truncated |
|---|---|---|---|
prompt |
site |
chars |
truncated |
Return out.
extract_tool_name
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| reply | any | required | Model reply to parse as data; it is not permission to execute arbitrary code |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Find a human-readable call line: CALL:<name> or 调用:<name> / 调用:<name>. |
Use reply as the inputs for this operation.
Find a human-readable call line: CALL:<name> or 调用:<name> / 调用:<name>.
Keep the literal separator as esc = [Keep the exact separator](table.put(in=None, at="nl", value="\n")).
We retain nl = [Read the nl field](json.get(value=esc, key="nl")).
We retain text = Trim.
We retain lines = [Split](split(value=text, sep=nl)).
We retain found = None.
- [line](遍历
lines为line) We retaint= Trim. We retainparts= [Split](split(value=t, sep=":")). We retainn= Len.n> 1 We retainhead= [At](at(value=parts, index=0)). We retainhead= Trim. We retainrest= [At](at(value=parts, index=1)). We retainrest= Trim.head== CALL We retain found = rest.head== 调用 We retain found = rest.-
**_ = 1**
Return found.
run_tool
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| tools | any | required | Explicit tool whitelist or tool-specification records |
| name | any | required | Name registered or looked up by this operation |
| arguments | any | None | Named argument record for the selected registered tool |
| ledger_dir | any | ".marqdo/agent-effects" | Directory holding the durable effect ledger |
| logical_run_id | any | None | Stable logical execution identifier shared by retries |
| step_id | any | None | Identifier of the current workbook step |
| call_id | any | None | Identifier of this tool invocation |
| operation_id | any | None | Stable idempotent operation identifier |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Allowlist and ToolSpec prepare (M-A2), then invoke the runbook section via lib/subtask. Unauthorized or invalid-args calls return ToolResultV1 failure without spawning (0 executions). Mutating effects (write / execute / external_write) go through EffectLedger (M-A5a). State flow is prepared then started then spawn then committed, failed_no_effect, or unknown. Read tools skip the ledger. Matching idempotency_key and args_digest that already committed skips re-exec. |
Use tools, name, arguments=None, ledger_dir=".marqdo/agent-effects", logical_run_id=None, step_id=None, call_id=None, operation_id=None as the inputs for this operation.
Allowlist and ToolSpec prepare (M-A2), then invoke the runbook section via lib/subtask. Unauthorized or invalid-args calls return ToolResultV1 failure without spawning (0 executions). Mutating effects (write / execute / external_write) go through EffectLedger (M-A5a). State flow is prepared then started then spawn then committed, failed_no_effect, or unknown. Read tools skip the ledger. Matching idempotency_key and args_digest that already committed skips re-exec.
Preparation and execution are separate stages. A registered ToolSpec is validated before a child task is created. If preparation fails, its structured failure is returned immediately. The operation identifiers connect retries to the same logical effect; changing arguments under an old identity must not be treated as a successful replay. Supplying these identifiers is the orchestration caller's responsibility.
For effects that need a ledger, an existing committed record yields a receipt instead of another child execution. A previously started record without a completion record is uncertain: the code marks it unknown and requires reconciliation. It cannot infer that the external write failed merely because the process stopped. Read-only tools follow the shorter path and return the awaited child result.
The compatibility path when no native agent plugin is found is narrower: it checks the name whitelist and spawns the runbook section. It does not provide ToolSpec validation or durable effect deduplication. Applications that require those guarantees must prepare the native plugin and inspect the returned status and receipt, rather than treating every nonempty value as proof of completion.
We retain p = Locate the installed native plugin.
_ = 1
- not
argumentsWe retainarguments= Empty map. -
_ = 1
We retain prepared = None. We retain needs = False. We retain opid = None. We retain digest = None. We retain idem = None. We retain effect = "read". We retain receipt = None. We retain raw = None.
- not
pWe retainallowed= [Tool allowed](agent_tool_allowed(tools=tools, name=name)). - not
allowedWe retain msg = "Tool not allowed:". Return msg + name. -
We retain **`id` = [Spawn](subtask.spawn(fn=`name`))**.
Return *[Wait](subtask.wait(id=`id`))*.
We retain prepared = [Tools prepare call](agent_tools_prepare_call(tool_id=name, tools=tools, arguments=arguments, call_id=call_id, operation_id=operation_id, logical_run_id=logical_run_id, step_id=step_id)).
We retain pok = [Read the ok field](json.get(value=prepared, key="ok")).
- not
pokReturn prepared. -
_ = 1
We retain needs = [Read the needs_ledger field](json.get(value=prepared, key="needs_ledger")).
We retain call = [Read the call field](json.get(value=prepared, key="call")).
We retain opid = [Read the operation_id field](json.get(value=call, key="operation_id")).
We retain digest = [Read the args_digest field](json.get(value=prepared, key="args_digest")).
We retain idem = [Read the idempotency_key field](json.get(value=prepared, key="idempotency_key")).
We retain tspec = [Read the spec field](json.get(value=prepared, key="spec")).
We retain effect = [Read the effect field](json.get(value=tspec, key="effect")).
needsWe retainled= [Effects prepare](agent_effects_prepare(operation_id=opid, idempotency_key=idem, args_digest=digest, effect_class=effect, logical_run_id=logical_run_id, step_id=step_id, ledger_dir=ledger_dir)). We retainrec= [Read the record field](json.get(value=led, key="record")). We retainst0= [Read the state field](json.get(value=rec, key="state")).st0== "committed" We retainreceipt= [Read the result_ref field](json.get(value=rec, key="result_ref")). 1. notreceiptWe retain receipt = "effect:" +opid. Return [Tools wrap result](agent_tools_wrap_result(ok=True, status="succeeded", summary="deduped committed effect; skipped re-exec", structured_content=rec, effect_receipt_ref=receipt)).-
1. `st0` == "reconciled_committed"
We retain **`receipt` = [Read the result_ref field](json.get(value=`rec`, key="result_ref"))**.
1. not `receipt`
We retain **receipt = "effect:" + `opid`**.
Return *[Tools wrap result](agent_tools_wrap_result(ok=True, status="succeeded", summary="deduped reconciled effect; skipped re-exec", structured_content=`rec`, effect_receipt_ref=`receipt`))*.
2. *
1. `st0` == "unknown"
We retain **receipt = "effect:" + `opid`**.
Return *[Tools wrap result](agent_tools_wrap_result(ok=False, status="unknown_effect", summary="prior effect unknown; reconcile before retry", structured_content=`rec`, effect_receipt_ref=`receipt`))*.
2. *
1. `st0` == "started"
We **[Effects transition](agent_effects_transition(operation_id=`opid`, state="unknown", note="retry saw started without commit; mark unknown", ledger_dir=`ledger_dir`))**.
We retain **receipt = "effect:" + `opid`**.
Return *[Tools wrap result](agent_tools_wrap_result(ok=False, status="unknown_effect", summary="interrupted after started; reconcile before retry", structured_content=`rec`, effect_receipt_ref=`receipt`))*.
2. *
1. `st0` == "needs_input"
We retain **receipt = "effect:" + `opid`**.
Return *[Tools wrap result](agent_tools_wrap_result(ok=False, status="needs_input", summary="effect needs_input; will not re-exec", structured_content=`rec`, effect_receipt_ref=`receipt`))*.
2. *
We **[Effects transition](agent_effects_transition(operation_id=`opid`, state="started", ledger_dir=`ledger_dir`))**.
**_ = 1**
_ = 1
We retain id = Spawn.
We retain raw = Wait.
needsWe retainraw_s= Encode the structured value as JSON text.- not
rawWe [Effects transition](agent_effects_transition(operation_id=opid, state="unknown", note="empty tool outcome; reconcile required", ledger_dir=ledger_dir)). We retain receipt = "effect:" +opid. Return [Tools wrap result](agent_tools_wrap_result(ok=False, status="unknown_effect", summary="tool outcome empty after started; ledger=unknown", structured_content=raw, effect_receipt_ref=receipt)). -
We retain **`is_err` = [Starts with](text.starts_with(text=`raw_s`, prefix="Tool not allowed"))**.
1. `is_err`
We **[Effects transition](agent_effects_transition(operation_id=`opid`, state="failed_no_effect", note="rejected before effect", ledger_dir=`ledger_dir`))**.
We retain **receipt = "effect:" + `opid`**.
Return *[Tools wrap result](agent_tools_wrap_result(ok=False, status="failed", summary=`raw_s`, effect_receipt_ref=`receipt`))*.
2. *
We retain **receipt = "effect:" + `opid`**.
We **[Effects transition](agent_effects_transition(operation_id=`opid`, state="committed", result_ref=`receipt`, ledger_dir=`ledger_dir`))**.
Return *[Tools wrap result](agent_tools_wrap_result(ok=True, status="succeeded", summary="tool executed; effect committed", structured_content=`raw`, effect_receipt_ref=`receipt`))*.
Return raw.
tools_register
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| spec | any | None | One structured tool or operation specification |
| specs | any | None | List of structured specifications |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Register ToolSpecV1 document(s). Unsupported schema keywords are refused. |
Use spec=None, specs=None as the inputs for this operation.
Register ToolSpecV1 document(s). Unsupported schema keywords are refused.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Tools register](agent_tools_register(spec=spec, specs=specs)).
tools_clear
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Clear the in-process ToolSpec registry (tests / reseeding). |
Clear the in-process ToolSpec registry (tests / reseeding).
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return Tools clear.
tools_search
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| query | any | "" | Text used to search the bounded catalog or tool registry |
| tools | any | None | Explicit tool whitelist or tool-specification records |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Search authorized registered tools (summaries only). |
Use query="", tools=None as the inputs for this operation.
Search authorized registered tools (summaries only).
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Tools search](agent_tools_search(query=query, tools=tools)).
tools_describe
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| tools | any | None | Explicit tool whitelist or tool-specification records |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Return full ToolSpecV1 for an authorized tool id. |
Use id, tools=None as the inputs for this operation.
Return full ToolSpecV1 for an authorized tool id.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Tools describe](agent_tools_describe(id=id, tools=tools)).
tools_register_eng_defaults
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Seed the five engineering tool specs (tool_find … tool_summarize). |
Seed the five engineering tool specs (tool_find … tool_summarize).
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return Tools register eng defaults.
tools_prepare_call
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| tool_id | any | required | Registered tool identifier, not an arbitrary function name |
| arguments | any | None | Named argument record for the selected registered tool |
| tools | any | None | Explicit tool whitelist or tool-specification records |
| call_id | any | None | Identifier of this tool invocation |
| operation_id | any | None | Stable idempotent operation identifier |
| logical_run_id | any | None | Stable logical execution identifier shared by retries |
| step_id | any | None | Identifier of the current workbook step |
| idempotency_key | any | None | Key identifying the same logical effect across retries |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Validate schema + authorize; returns ToolCallV1 or ToolResultV1 error (no side effects). Also returns args_digest / idempotency_key / needs_ledger for EffectLedger wiring. |
Use tool_id, arguments=None, tools=None, call_id=None, operation_id=None, logical_run_id=None, step_id=None, idempotency_key=None as the inputs for this operation.
Validate schema + authorize; returns ToolCallV1 or ToolResultV1 error (no side effects).
Also returns args_digest / idempotency_key / needs_ledger for EffectLedger wiring.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Tools prepare call](agent_tools_prepare_call(tool_id=tool_id, arguments=arguments, tools=tools, call_id=call_id, operation_id=operation_id, logical_run_id=logical_run_id, step_id=step_id, idempotency_key=idempotency_key)).
output_build
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| status | any | "succeeded" | Domain status recorded in the structured result |
| text | any | "" | Text supplied to the transformation or adapter |
| format | any | "markdown" | Output representation selected by the caller |
| answer | any | None | Final answer text to project into the output |
| artifacts | any | None | Structured artifact references accompanying the result |
| citations | any | None | Source references accompanying the result |
| validation | any | None | Explicit validation evidence; not a self-reported success flag |
| finish_reason | any | None | Reason the operation stopped |
| recovery_options | any | None | Allowed recovery choices for the caller |
| channels | any | None | Structured output-channel records |
| allow_passed_without_report | any | False | Whether policy permits a passed status without a validation report |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Build an AgentOutputV1 document (M-A4). validation.status=passed requires report_ref. |
Use status="succeeded", text="", format="markdown", answer=None, artifacts=None, citations=None, validation=None, finish_reason=None, recovery_options=None, channels=None, allow_passed_without_report=False as the inputs for this operation.
Build an AgentOutputV1 document (M-A4). validation.status=passed requires report_ref.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Output build](agent_output_build(status=status, text=text, format=format, answer=answer, artifacts=artifacts, citations=citations, validation=validation, finish_reason=finish_reason, recovery_options=recovery_options, channels=channels, allow_passed_without_report=allow_passed_without_report)).
output_apply_policy
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| status | any | "succeeded" | Domain status recorded in the structured result |
| text | any | "" | Text supplied to the transformation or adapter |
| format | any | "markdown" | Output representation selected by the caller |
| answer | any | None | Final answer text to project into the output |
| artifacts | any | None | Structured artifact references accompanying the result |
| citations | any | None | Source references accompanying the result |
| validation | any | None | Explicit validation evidence; not a self-reported success flag |
| policy | any | None | Policy data governing this operation |
| schema | any | None | Structured schema used to validate or project output |
| schema_version | any | None | Version of the structured schema |
| finish_reason | any | None | Reason the operation stopped |
| recovery_options | any | None | Allowed recovery choices for the caller |
| channels | any | None | Structured output-channel records |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Apply ResponsePolicy (detail / max_chars / max_output_tokens / artifact_allowed) to an AgentOutputV1 or raw text. |
Use status="succeeded", text="", format="markdown", answer=None, artifacts=None, citations=None, validation=None, policy=None, schema=None, schema_version=None, finish_reason=None, recovery_options=None, channels=None as the inputs for this operation.
Apply ResponsePolicy (detail / max_chars / max_output_tokens / artifact_allowed) to an AgentOutputV1 or raw text.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Output apply policy](agent_output_apply_policy(status=status, text=text, format=format, answer=answer, artifacts=artifacts, citations=citations, validation=validation, policy=policy, schema=schema, schema_version=schema_version, finish_reason=finish_reason, recovery_options=recovery_options, channels=channels)).
output_channel_event
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| channel | any | required | Output channel identifier |
| delta | any | "" | Incremental text or record update |
| resource_id | any | None | Referenced resource identifier |
| meta | any | None | Metadata associated with the structured item |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Split a stream delta by channel. Only answer sets append_to_chat=true. |
Use channel, delta="", resource_id=None, meta=None as the inputs for this operation.
Split a stream delta by channel. Only answer sets append_to_chat=true.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Output channel event](agent_output_channel_event(channel=channel, delta=delta, resource_id=resource_id, meta=meta)).
output_project_conclusion
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| document | any | "" | Document record being packed or projected |
| text | any | "" | Text supplied to the transformation or adapter |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Deterministic chat projection from # 结论 / # conclusion (F01 transition). Falls back to the first body paragraph. |
Use document="", text="" as the inputs for this operation.
Deterministic chat projection from # 结论 / # conclusion (F01 transition). Falls back to the first body paragraph.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Output project conclusion](agent_output_project_conclusion(document=document, text=text)).
context_pack_build
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| items | any | None | Ordered context or output items |
| budget_tokens | any | 8000 | Maximum context token budget |
| output_reserve_pct | any | 20 | Percentage of the context budget reserved for output |
| compact_threshold_pct | any | 70 | Budget usage threshold triggering compaction |
| goal | any | None | Human task goal represented by this operation |
| constraints | any | None | Explicit task constraints |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Assemble ContextPackV2 with origin/trust/priority. Web/tool items cannot be trust=trusted. |
Use items=None, budget_tokens=8000, output_reserve_pct=20, compact_threshold_pct=70, goal=None, constraints=None as the inputs for this operation.
Assemble ContextPackV2 with origin/trust/priority. Web/tool items cannot be trust=trusted.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Context pack build](agent_context_pack_build(items=items, budget_tokens=budget_tokens, output_reserve_pct=output_reserve_pct, compact_threshold_pct=compact_threshold_pct, goal=goal, constraints=constraints)).
context_pack_compact
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| items | any | None | Ordered context or output items |
| budget_tokens | any | 8000 | Maximum context token budget |
| output_reserve_pct | any | 20 | Percentage of the context budget reserved for output |
| compact_threshold_pct | any | 70 | Budget usage threshold triggering compaction |
| goal | any | None | Human task goal represented by this operation |
| constraints | any | None | Explicit task constraints |
| schema | any | None | Structured schema used to validate or project output |
| schema_version | any | None | Version of the structured schema |
| available_tokens | any | None | Token budget available to the next turn |
| used_tokens | any | None | Observed token usage, not a guessed count |
| source_event_range | any | None | Event range represented by a compacted context item |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Compact over-threshold packs; retain goal/constraints/pending_write/plan/trusted anchors (F19). |
Use items=None, budget_tokens=8000, output_reserve_pct=20, compact_threshold_pct=70, goal=None, constraints=None, schema=None, schema_version=None, available_tokens=None, used_tokens=None, source_event_range=None as the inputs for this operation.
Compact over-threshold packs; retain goal/constraints/pending_write/plan/trusted anchors (F19).
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Context pack compact](agent_context_pack_compact(items=items, budget_tokens=budget_tokens, output_reserve_pct=output_reserve_pct, compact_threshold_pct=compact_threshold_pct, goal=goal, constraints=constraints, schema=schema, schema_version=schema_version, available_tokens=available_tokens, used_tokens=used_tokens, source_event_range=source_event_range)).
render_workbook_skeleton
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| goal | any | required | Human task goal represented by this operation |
| skeleton | any | "single" | Workbook source template to instantiate |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Build a runnable workbook. skeleton=single (default): one worker step. skeleton=dual: research then write agents. On success the parent chooses DONE; runtime agent_workbook_solidify freezes the answer. |
Use goal, skeleton="single" as the inputs for this operation.
Build a runnable workbook. skeleton=single (default): one worker step. skeleton=dual: research then write agents. On success the parent chooses DONE; runtime agent_workbook_solidify freezes the answer.
This function produces source text, not a running worker. The caller owns choosing a destination, writing that text, starting the child, and inspecting the child's exit status and returned value. Generation alone neither proves the task solved nor freezes a reusable skill. The templates are data in this function: their marker characters must remain literal until a later Marqdo process parses the generated workbook.
The common header names the libraries the generated program imports. Its Goal section explains where the parent goal is embedded, while its Solidify section explains who may freeze the answer. The entry begins by loading environment configuration. This makes the generated program usable by the existing workbook runner without adding a second template interpreter or hidden workflow format.
The single-worker branch creates one model and an empty tools list, then asks one worker to solve the embedded task. The empty whitelist is intentional: mentioning a capability in the task does not register a callable tool. A worker must answer directly unless the author later adds an actual tool definition and explicitly supplies it. The returned child value is the result field from the worker's structured turn.
The dual-worker branch uses the same model configuration for two roles. A research worker first returns notes. Those notes are serialized into the writing worker's task, and the writing worker returns the final text. The roles describe sequencing; they do not imply independent evidence collection, browser access, or any permission beyond the configured whitelist and runtime grants.
The goal is JSON-quoted before it is inserted into either source template. Quotes and line breaks in a user's goal therefore stay data rather than becoming workbook statements. The surrounding fragments retain the exact original newlines, imports and return markers. When changing this generator, review both complete outputs, parse them as ordinary source, and test goals containing quotes, backticks and newlines.
Environment variables are looked up when the child runs. No credentials are fetched or written by this generator. Missing model configuration consequently belongs to the execution result, not to template construction. A parent should await that result before deciding RUN, CONTINUE or DONE. Successful execution may then be solidified by the existing runtime mechanism; this function does not silently promote its generated text into trusted knowledge.
We retain q = Quote the JSON text value.
Keep this text as ordered lines so its instructions and blank-line boundaries can be read directly.
_literal_esc_h_lines =
| line |
|---|
| "---" |
| "title: agent workbook" |
| "import:" |
| " llm: ext/ai/llm.mq.md" |
| " agent: ext/ai/agent.mq.md" |
| " json: lib/json.mq.md" |
| " sys: lib/sys.mq.md" |
| " table: lib/table.mq.md" |
| " wb: lib/writeback.mq.md" |
| " subtask: lib/subtask.mq.md" |
| "---" |
| "" |
| "# Goal" |
| "" |
| "Parent goal is embedded as JSON in # main." |
| "" |
| "## Solidify" |
| "" |
| "When the child returns a good value, parent DECISION: DONE — runtime agent_workbook_solidify freezes the answer as return (do not invent long FIND/REPLACE)." |
| "" |
| "# main" |
| "" |
| "> llm.load_env" |
| "" |
| "" |
Join exactly those lines into _literal_esc_h_text = [Retain the original newline boundaries](text.str_join(xs=_literal_esc_h_lines, sep="\n")).
Keep this text as ordered lines so its instructions and blank-line boundaries can be read directly.
_literal_esc_s1_lines =
| line |
|---|
| "\x60env_model\x60 = > sys.env_get name="OPENAI_MODEL"" |
| "\x60env_base\x60 = > sys.env_get name="OPENAI_BASE_URL"" |
| "\x60env_key\x60 = > sys.env_get name="OPENAI_API_KEY"" |
| "\x60model\x60 = > llm.create model=\x60env_model\x60 base_url=\x60env_base\x60 api_key=\x60env_key\x60 backend="openai-compatible" name="workbook"" |
| "" |
Join exactly those lines into _literal_esc_s1_text = [Retain the original newline boundaries](text.str_join(xs=_literal_esc_s1_lines, sep="\n")).
Keep this text as ordered lines so its instructions and blank-line boundaries can be read directly.
_literal_esc_s3_lines =
| line |
|---|
| "\x60worker\x60 = > agent.agent model=\x60model\x60 tools=\x60tools\x60 standing="You are a workbook worker. tools=[] means never CALL. Finish the task with a direct final answer; do not invent tools."" |
| "" |
Join exactly those lines into _literal_esc_s3_text = [Retain the original newline boundaries](text.str_join(xs=_literal_esc_s3_lines, sep="\n")).
The following record names each literal field without a JSON construction chain.
_literal_esc_fields =
| @ | key | value |
|---|---|---|
| 1 | "d10" | "\x60wt\x60 = \x60wt\x60 + \x60ns\x60\n" |
| 2 | "d11" | "\x60out\x60 = > \x60writer\x60.step task=\x60wt\x60 stream=True\n" |
| 3 | "d11b" | "\x60text\x60 = > json.get value=\x60out\x60 key="result"\n" |
| 4 | "d12" | "\x60text\x60\n" |
| 5 | "d3" | "\x60research\x60 = > agent.agent model=\x60model\x60 tools=\x60tools\x60 standing="You gather facts for the goal. Be concise. Do not invent tools."\n" |
| 6 | "d3b" | "\x60writer\x60 = > agent.agent model=\x60model\x60 tools=\x60tools\x60 standing="You write the final answer from research notes. Do not invent tools."\n" |
| 7 | "d4" | "**\x60wrap\x60 = > json.parse text={"task":" |
| 8 | "d5" | "}**\n" |
| 9 | "d6" | "\x60task\x60 = > json.get value=\x60wrap\x60 key="task"\n" |
| 10 | "d7" | "\x60notes\x60 = > \x60research\x60.step task=\x60task\x60 stream=True\n" |
| 11 | "d8" | "\x60ns\x60 = > json.stringify value=\x60notes\x60\n" |
| 12 | "d9" | "\x60wt\x60 = "Write the final answer. Research notes:"\n" |
| 13 | "h" | _literal_esc_h_text |
| 14 | "s1" | _literal_esc_s1_text |
| 15 | "s2" | "\x60tools\x60 = > table.empty_list\n" |
| 16 | "s3" | _literal_esc_s3_text |
| 17 | "s4" | "**\x60wrap\x60 = > json.parse text={"task":" |
| 18 | "s5" | "}**\n" |
| 19 | "s6" | "\x60task\x60 = > json.get value=\x60wrap\x60 key="task"\n" |
| 20 | "s7" | "\x60out\x60 = > \x60worker\x60.step task=\x60task\x60 stream=True\n" |
| 21 | "s7b" | "\x60text\x60 = > json.get value=\x60out\x60 key="result"\n" |
| 22 | "s8" | "\x60text\x60\n" |
We build esc = Collect these named fields into one record.
We retain h = [Read the h field](json.get(value=esc, key="h")).
We retain s1 = [Read the s1 field](json.get(value=esc, key="s1")).
We retain s2 = [Read the s2 field](json.get(value=esc, key="s2")).
skeleton== dual We retains3= [Read the d3 field](json.get(value=esc, key="d3")). We retains3b= [Read the d3b field](json.get(value=esc, key="d3b")). We retains4= [Read the d4 field](json.get(value=esc, key="d4")). We retains5= [Read the d5 field](json.get(value=esc, key="d5")). We retains6= [Read the d6 field](json.get(value=esc, key="d6")). We retains7= [Read the d7 field](json.get(value=esc, key="d7")). We retains8= [Read the d8 field](json.get(value=esc, key="d8")). We retains9= [Read the d9 field](json.get(value=esc, key="d9")). We retains10= [Read the d10 field](json.get(value=esc, key="d10")). We retains11= [Read the d11 field](json.get(value=esc, key="d11")). We retains11b= [Read the d11b field](json.get(value=esc, key="d11b")). We retains12= [Read the d12 field](json.get(value=esc, key="d12")). Return h + s1 + s2 + s3 + s3b + s4 + q + s5 + s6 + s7 + s8 + s9 + s10 + s11 + s11b + s12.-
We retain s3 = [Read the s3 field](json.get(value=esc, key="s3")).
We retain s4 = [Read the s4 field](json.get(value=esc, key="s4")).
We retain s5 = [Read the s5 field](json.get(value=esc, key="s5")).
We retain s6 = [Read the s6 field](json.get(value=esc, key="s6")).
We retain s7 = [Read the s7 field](json.get(value=esc, key="s7")).
We retain s7b = [Read the s7b field](json.get(value=esc, key="s7b")).
We retain s8 = [Read the s8 field](json.get(value=esc, key="s8")).
Return h + s1 + s2 + s3 + s4 + q + s5 + s6 + s7 + s7b + s8.
inspect_workbook
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| exit_code | any | None | Child process or tool exit status |
| value | any | None | Value supplied to this operation; immutable transformations return a new value |
| stdout | any | None | Captured standard output |
| stderr | any | None | Captured standard error |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Structured observation for the parent developer-agent: source, named writeback slots, exit code, optional child return value, and quiet-captured I/O. |
Use path, exit_code=None, value=None, stdout=None, stderr=None as the inputs for this operation.
Structured observation for the parent developer-agent: source, named writeback slots, exit code, optional child return value, and quiet-captured I/O.
We retain source = Read UTF-8 text from the selected file.
We retain slots = Scan path.
obs =
| path | source | slots | exit_code |
|---|---|---|---|
path |
source |
slots |
exit_code |
valueWe retainobs= [Set the value field in the new record](table.put(in=obs, at="value", value=value)).-
_ = 1
stdoutWe retainobs= [Set the stdout field in the new record](table.put(in=obs, at="stdout", value=stdout)).-
_ = 1
stderrWe retainobs= [Set the stderr field in the new record](table.put(in=obs, at="stderr", value=stderr)).-
_ = 1
We retain last_ok = None. We retain last_error = None.
- [slot](遍历
slots为slot) We retaink= [Read the key field](json.get(value=slot, key="key")). We retainbody= [Read the body field](json.get(value=slot, key="body")).k== "ok" We retain last_ok = body.k== "error" We retain last_error = body.-
last_okWe retainobs= [Set the last_ok field in the new record](table.put(in=obs, at="last_ok", value=last_ok)).-
_ = 1
last_errorWe retainobs= [Set the last_error field in the new record](table.put(in=obs, at="last_error", value=last_error)).-
_ = 1
Return obs.
trial
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| source | any | None | Source text inspected or prepared by this operation |
| root | any | None | Explicit root directory for discovery or isolated execution |
| write_path | any | None | Explicit output path or None |
| text | any | None | Text supplied to the transformation or adapter |
| commit | any | True | Whether to promote trial changes after successful validation |
| profile | any | "default" | Capability profile selected for the trial |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Opt-in CoW trial (O1): open → optional upper write → optional run → diff → commit on success else discard. Host tree unchanged until a successful commit. Return map is a GFM table (link-index readable). |
Use path=None, source=None, root=None, write_path=None, text=None, commit=True, profile="default" as the inputs for this operation.
Opt-in CoW trial (O1): open → optional upper write → optional run → diff → commit on success else discard. Host tree unchanged until a successful commit. Return map is a GFM table (link-index readable).
We retain sb = [Open](sandbox.open(root=root, profile=profile)).
We retain id = [Read the id field](json.get(value=sb, key="id")).
We retain prof = [Read the profile field](json.get(value=sb, key="profile")).
We retain ok = True.
We retain stdout = "".
We retain stderr = "".
write_pathtextWe [Write](sandbox.write(id=id, path=write_path, text=text)).-
**_ = 1**
_ = 1
sourceWe retainret= [Run](sandbox.run(id=id, source=source)). We retainok= [Read the ok field](json.get(value=ret, key="ok")). We retainstdout= [Read the stdout field](json.get(value=ret, key="stdout")). We retainstderr= [Read the stderr field](json.get(value=ret, key="stderr")).pathWe retainret= [Run](sandbox.run(id=id, path=path)). We retainok= [Read the ok field](json.get(value=ret, key="ok")). We retainstdout= [Read the stdout field](json.get(value=ret, key="stdout")). We retainstderr= [Read the stderr field](json.get(value=ret, key="stderr")).-
_ = 1
We retain pending = Diff.
We retain committed = False.
okcommitWe Commit. We retain committed = True.-
We **[Discard](sandbox.discard(id=`id`))**.
We Discard.
**out = **
| ok | committed | diff | stdout | stderr | id | profile |
|---|---|---|---|---|---|---|
ok |
committed |
pending |
stdout |
stderr |
id |
prof |
Return out.
step_route
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| kind | any | "default" | Operation or factorization kind listed in this function's behavior |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | O3: map step class (lookup | patch | sandbox_run | net | default) → Adaptive Routing backend. Authority is the GFM table in ext/ai/policies/step-route.mq.md (mirrored here for offline reads). |
Use kind="default" as the inputs for this operation.
O3: map step class (lookup | patch | sandbox_run | net | default) → Adaptive Routing backend.
Authority is the GFM table in ext/ai/policies/step-route.mq.md (mirrored here for offline reads).
kind== "lookup" We retain backend = "marqdo".kind== "patch" We retain backend = "small-llm".kind== "sandbox_run" We retain backend = "marqdo".kind== "net" We retain backend = "llm".-
We retain backend = "auto".
We retain out = [Set the kind field in the new record](table.put(in=None, at="kind", value=kind)).
We retain out = [Set the backend field in the new record](table.put(in=out, at="backend", value=backend)).
Return out.
await_workbook
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| sandbox | any | False | Whether to use the CoW trial path |
| sandbox_root | any | None | Root directory of the CoW trial |
| sandbox_profile | any | "default" | Capability profile for CoW execution |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Spawn a workbook file (quiet by default), wait, and inspect. With sandbox=True, run via ## trial first (commit on ok); host unchanged until that commit. |
Use path, sandbox=False, sandbox_root=None, sandbox_profile="default" as the inputs for this operation.
Spawn a workbook file (quiet by default), wait, and inspect.
With sandbox=True, run via ## trial first (commit on ok); host unchanged until that commit.
sandboxWe retaintr= [Trial](trial(path=path, root=sandbox_root, profile=sandbox_profile, commit=True)). We retainok= [Read the ok field](json.get(value=tr, key="ok")). We retainstdout= [Read the stdout field](json.get(value=tr, key="stdout")). We retainstderr= [Read the stderr field](json.get(value=tr, key="stderr")).okWe retain code = 0.-
We retain **code = 1**.
We retain value = stdout.
We retain obs = [Inspect workbook](inspect_workbook(path=path, exit_code=code, value=value, stdout=stdout, stderr=stderr)).
**out = **
| code | value | observation | sandbox |
|---|---|---|---|
code |
value |
obs |
tr |
Return out.
2. *
We retain id = Spawn.
We retain waited = Wait.
We retain code = [Read the code field](json.get(value=waited, key="code")).
We retain value = [Read the value field](json.get(value=waited, key="value")).
We retain stdout = [Read the stdout field](json.get(value=waited, key="stdout")).
We retain stderr = [Read the stderr field](json.get(value=waited, key="stderr")).
We retain obs = [Inspect workbook](inspect_workbook(path=path, exit_code=code, value=value, stdout=stdout, stderr=stderr)).
**out = **
| code | value | observation |
|---|---|---|
code |
value |
obs |
Return out.
text_head_lines
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| text | any | required | Text supplied to the transformation or adapter |
| max_lines | any | 80 | Maximum retained lines in the text excerpt |
| max_chars | any | 4000 | Maximum retained characters in the text excerpt |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Keep at most the requested leading lines of text when preparing a bounded context excerpt. |
Use text, max_lines=80, max_chars=4000 as the inputs for this operation.
Keep at most the requested leading lines of text when preparing a bounded context excerpt.
Keep the literal separator as esc = [Keep the exact separator](table.put(in=None, at="nl", value="\n")).
We retain nl = [Read the nl field](json.get(value=esc, key="nl")).
We retain raw = Str.
We retain lines = [Split](split(value=raw, sep=nl)).
We retain acc = Empty list.
We retain chars = 0.
We retain count = 0.
- [line](遍历
lines为line)count<max_linesWe retainln= Len. We retain next = chars + ln.next>max_charsWe retain count = max_lines.-
We retain **`acc` = [Append this item to the new list](table.append(list=`acc`, item=`line`))**. We retain **chars = next**. We retain **count = count + 1**.acc, sep=nl)).
text_tail_lines
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| text | any | required | Text supplied to the transformation or adapter |
| max_lines | any | 40 | Maximum retained lines in the text excerpt |
| max_chars | any | 2000 | Maximum retained characters in the text excerpt |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Keep at most the requested trailing lines of text when preparing a bounded context excerpt. |
Use text, max_lines=40, max_chars=2000 as the inputs for this operation.
Keep at most the requested trailing lines of text when preparing a bounded context excerpt.
Keep the literal separator as esc = [Keep the exact separator](table.put(in=None, at="nl", value="\n")).
We retain nl = [Read the nl field](json.get(value=esc, key="nl")).
We retain raw = Str.
We retain lines = [Split](split(value=raw, sep=nl)).
We retain n = Len.
We retain start = n - max_lines.
start< 0 We retain start = 0.-
_ = 1
We retain acc = Empty list.
We retain i = 0.
We retain chars = 0.
- [line](遍历
lines为line)i>=startWe retainln= Len. We retain next = chars + ln.next>max_charsWe retain i = n.-
We retain **`acc` = [Append this item to the new list](table.append(list=`acc`, item=`line`))**. We retain **chars = next**.acc, sep=nl)).
strip_html_comments
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| text | any | required | Text supplied to the transformation or adapter |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Drop <!-- … --> blocks (including marqdo-out bodies) so parent excerpts stay structural. |
Use text as the inputs for this operation.
Drop <!-- … --> blocks (including marqdo-out bodies) so parent excerpts stay structural.
This is a line-oriented removal helper for workbook inspection. It tracks whether a comment span is open across lines, so hidden author notes do not inflate the excerpt. It is not an HTML parser and does not sanitize rendered pages.
Keep the literal separator as esc = [Keep the exact separator](table.put(in=None, at="nl", value="\n")).
We retain nl = [Read the nl field](json.get(value=esc, key="nl")).
We retain raw = Str.
We retain lines = [Split](split(value=raw, sep=nl)).
We retain acc = Empty list.
We retain skip = None.
- [line](遍历
lines为line)skipWe retainend_parts= [Split](split(value=line, sep="-->")). We retainen= Len.en> 1 We retain skip = None.-
**_ = 1**start_parts= [Split](split(value=line, sep="<!--")). We retainsn= Len.sn> 1 We retainbefore= [At](at(value=start_parts, index=0)). We retainbefore= Trim. 1.beforeWe retainacc= [Append this item to the new list](table.append(list=acc, item=before)). 2. * _ = 1 We retaintail= [At](at(value=start_parts, index=1)). We retainend_parts= [Split](split(value=tail, sep="-->")). We retainen= Len. 1.en> 1 We retain skip = None. 2. * We retain skip = 1.-
We retain **`acc` = [Append this item to the new list](table.append(list=`acc`, item=`line`))**.
Return [Join](join(value=acc, sep=nl)).
workbook_source_excerpt
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| source | any | required | Source text inspected or prepared by this operation |
| max_lines | any | 80 | Maximum retained lines in the text excerpt |
| max_chars | any | 4000 | Maximum retained characters in the text excerpt |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Select a bounded excerpt from workbook source for the next planning observation. |
Use source, max_lines=80, max_chars=4000 as the inputs for this operation.
Select a bounded excerpt from workbook source for the next planning observation.
We retain clean = Strip html comments.
Return [Text head lines](text_head_lines(text=clean, max_lines=max_lines, max_chars=max_chars)).
workbook_excerpt
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| max_lines | any | 80 | Maximum retained lines in the text excerpt |
| max_chars | any | 4000 | Maximum retained characters in the text excerpt |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Read a workbook excerpt using explicit depth and length budgets. |
Use path, max_lines=80, max_chars=4000 as the inputs for this operation.
Read a workbook excerpt using explicit depth and length budgets.
We retain src = Read UTF-8 text from the selected file.
Return [Workbook source excerpt](workbook_source_excerpt(source=src, max_lines=max_lines, max_chars=max_chars)).
workbook_read
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| depth | any | "default" | Requested context or discovery depth |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Read a workbook by path and expose the budgeted view required by the planner. |
Use path, depth="default" as the inputs for this operation.
We retain src = Read UTF-8 text from the selected file.
depth== deep Return [Workbook source excerpt](workbook_source_excerpt(source=src, max_lines=200, max_chars=12000)).-
Return [Workbook source excerpt](workbook_source_excerpt(source=src, max_lines=80, max_chars=4000)).
lib_catalog
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Callable dotted names (whitelist for CALL:lib…) plus static module file list for workbook imports. Parent also exposes evidence tools corpus_search / mcp_list_tools / mcp_call (not authority). |
Callable dotted names (whitelist for CALL:lib…) plus static module file list for workbook imports. Parent also exposes evidence tools corpus_search / mcp_list_tools / mcp_call (not authority).
The import files are a list of source modules. They are not all enabled as direct parent tools.
The two lists answer different questions: files can be imported into a workbook, while callable records name the limited actions understood by the parent dispatcher. This is not a complete catalog of the standard library. New source functions remain discoverable through the normal source catalog and MLSP; adding a file here does not grant it execution permission.
_literal_files =
| file |
|---|
| "fs.mq.md" |
| "json.mq.md" |
| "subtask.mq.md" |
| "sys.mq.md" |
| "writeback.mq.md" |
| "text.mq.md" |
| "time.mq.md" |
| "math.mq.md" |
| "net.mq.md" |
| "table.mq.md" |
| "plugin.mq.md" |
| "foreign.mq.md" |
Only the following names belong to this parent dispatcher. The description explains the action; a name still passes through the normal allowlist and its effect boundary at execution.
_literal_callable =
| @ | desc | name |
|---|---|---|
| 1 | "Read UTF-8 text file" | "lib.fs.read_text" |
| 2 | "Path exists?" | "lib.fs.exists" |
| 3 | "List directory entries" | "lib.fs.list_dir" |
| 4 | "Parse JSON text" | "lib.json.parse" |
| 5 | "Serialize JSON" | "lib.json.stringify" |
| 6 | "Process working directory" | "lib.sys.cwd" |
| 7 | "Local markdown/text keyword search (evidence)" | "corpus_search" |
| 8 | "List tools from MCP JSON fixture" | "mcp_list_tools" |
| 9 | "Call a tool from MCP JSON fixture" | "mcp_call" |
The note is returned with both lists, so a caller can distinguish an importable file from an allowed CALL name. Evidence adapters read fixtures here; they do not establish workbook authority.
out =
| callable | files | note |
|---|---|---|
_literal_callable |
_literal_files |
"Direct CALL:lib.. + optional ARGS:{json} for whitelist only. Or import via frontmatter > lib/.mq.md then PATCH / scratch_tool_write. Evidence tools: CALL:corpus_search | mcp_list_tools | mcp_call (fixture RAG/MCP) — workbook .mq.md remains authority." |
| Return out. |
corpus_search
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| query | any | required | Text used to search the bounded catalog or tool registry |
| root | any | ".marqdo/agent-corpus" | Explicit root directory for discovery or isolated execution |
| limit | any | 6 | Maximum returned entries or candidates; this is not a success threshold |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Local keyword search over .md / .mq.md / .txt under root. Returns ranked excerpts. Evidence only — runnable workbook / OKF skill stays authority (authority=workbook). Ensures the native agent plugin is loaded so plain marqdo run (without constructing # agent) can call this. |
Use query, root=".marqdo/agent-corpus", limit=6 as the inputs for this operation.
Local keyword search over .md / .mq.md / .txt under root. Returns ranked excerpts. Evidence only — runnable workbook / OKF skill stays authority (authority=workbook).
Ensures the native agent plugin is loaded so plain marqdo run (without constructing # agent) can call this.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent)")). We End this run with the selected exit status.
Return [Corpus search](agent_corpus_search(query=query, root=root, limit=limit)).
mcp_list_tools
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| fixture | any | required | Deterministic fixture data used for offline behavior |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | List tools from an offline MCP-shaped JSON fixture (tools array). Evidence only. |
Use fixture as the inputs for this operation.
List tools from an offline MCP-shaped JSON fixture (tools array). Evidence only.
Return [Mcp fixture](agent_mcp_fixture(action="list", fixture=fixture)).
mcp_call
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| name | any | required | Name registered or looked up by this operation |
| fixture | any | required | Deterministic fixture data used for offline behavior |
| arguments | any | None | Named argument record for the selected registered tool |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Call a named tool from a MCP-shaped fixture (results / calls map). Optional arguments echoed; fixture results are keyed by name. Evidence only. |
Use name, fixture, arguments=None as the inputs for this operation.
Call a named tool from a MCP-shaped fixture (results / calls map). Optional arguments echoed; fixture results are keyed by name. Evidence only.
argumentsReturn [Mcp fixture](agent_mcp_fixture(action="call", fixture=fixture, name=name, arguments=arguments)).-
Return [Mcp fixture](agent_mcp_fixture(action="call", fixture=fixture, name=name)).
mcp_connect
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| command | any | required | Configured external command |
| args | any | None | Arguments passed to the selected command or operation |
| session | any | "default" | Existing session handle returned by the corresponding connector |
| name | any | "mcp" | Name registered or looked up by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Open a stdio MCP client session (spawn command + args, JSON-RPC initialize). Evidence only — workbook remains authority. |
Use command, args=None, session="default", name="mcp" as the inputs for this operation.
Open a stdio MCP client session (spawn command + args, JSON-RPC initialize). Evidence only — workbook remains authority.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
argsReturn [Mcp client](agent_mcp_client(action="connect", command=command, args=args, session=session, name=name)).-
Return [Mcp client](agent_mcp_client(action="connect", command=command, session=session, name=name)).
mcp_client_list
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| session | any | "default" | Existing session handle returned by the corresponding connector |
| command | any | None | Configured external command |
| args | any | None | Arguments passed to the selected command or operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | List tools from an open MCP session, or one-shot when command= is set (no session retained). |
Use session="default", command=None, args=None as the inputs for this operation.
List tools from an open MCP session, or one-shot when command= is set (no session retained).
commandargsReturn [Mcp client](agent_mcp_client(action="list", command=command, args=args)).-
Return *[Mcp client](agent_mcp_client(action="list", command=`command`))*.
Return [Mcp client](agent_mcp_client(action="list", session=session)).
mcp_client_call
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| name | any | None | Name registered or looked up by this operation |
| session | any | "default" | Existing session handle returned by the corresponding connector |
| arguments | any | None | Named argument record for the selected registered tool |
| command | any | None | Configured external command |
| args | any | None | Arguments passed to the selected command or operation |
| tool | any | None | Registered tool or tool name selected by policy |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Call a tool on an open MCP session, or one-shot when command= is set. Prefer tool= for oneshot when name would collide with server name. |
Use name=None, session="default", arguments=None, command=None, args=None, tool=None as the inputs for this operation.
Call a tool on an open MCP session, or one-shot when command= is set. Prefer tool= for oneshot when name would collide with server name.
commandtoolWe retain tn = tool.-
We retain **tn = name**.
argsReturn [Mcp client](agent_mcp_client(action="call", command=command, args=args, tool=tn, arguments=arguments)).-
Return *[Mcp client](agent_mcp_client(action="call", command=`command`, tool=`tn`, arguments=`arguments`))*.
Return [Mcp client](agent_mcp_client(action="call", session=session, name=name, arguments=arguments)).
mcp_disconnect
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| session | any | "default" | Existing session handle returned by the corresponding connector |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Close a stdio MCP client session. |
Use session="default" as the inputs for this operation.
Close a stdio MCP client session.
Return [Mcp client](agent_mcp_client(action="close", session=session)).
resume_save
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| goal | any | None | Human task goal represented by this operation |
| task | any | None | Structured task or text supplied to the agent |
| status | any | "running" | Domain status recorded in the structured result |
| round | any | 0 | Current planning round number |
| workbook | any | None | Workbook path or structured workbook reference |
| events | any | None | Ordered semantic or provider stream-event records |
| route | any | None | Selected route or route-policy data |
| result | any | None | Structured result from the preceding operation |
| resume_dir | any | ".marqdo/agent-resume" | Directory holding continuation checkpoints |
| checkpoint_v2 | any | False | Versioned continuation checkpoint record |
| attempt_id | any | None | Identifier for this execution attempt |
| effect_ledger_watermark | any | None | Last durable effect-ledger position included by the checkpoint |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Persist a plan/run checkpoint as .marqdo/agent-resume/<id>.json (atomic write). Pass checkpoint_v2=True for CheckpointV2 schema. resume_dir must be host-relative. |
Use id, goal=None, task=None, status="running", round=0, workbook=None, events=None, route=None, result=None, resume_dir=".marqdo/agent-resume", checkpoint_v2=False, attempt_id=None, effect_ledger_watermark=None as the inputs for this operation.
Persist a plan/run checkpoint as .marqdo/agent-resume/<id>.json (atomic write).
Pass checkpoint_v2=True for CheckpointV2 schema. resume_dir must be host-relative.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Resume save](agent_resume_save(id=id, goal=goal, task=task, status=status, round=round, workbook=workbook, events=events, route=route, result=result, resume_dir=resume_dir, checkpoint_v2=checkpoint_v2, attempt_id=attempt_id, effect_ledger_watermark=effect_ledger_watermark)).
resume_load
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| resume_dir | any | ".marqdo/agent-resume" | Directory holding continuation checkpoints |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Load a resume checkpoint (or {ok:false,found:false}). Legacy / missing effect ledger → recovery_mode=manual_review, write_auto_resume=false. |
Use id, resume_dir=".marqdo/agent-resume" as the inputs for this operation.
Load a resume checkpoint (or {ok:false,found:false}).
Legacy / missing effect ledger → recovery_mode=manual_review, write_auto_resume=false.
Return [Resume load](agent_resume_load(id=id, resume_dir=resume_dir)).
error_make
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| code | any | required | Stable failure category or bound code value, as stated by this function |
| message | any | None | Outgoing WebSocket or application message |
| category | any | None | Failure category used by recovery policy |
| stage | any | "agent" | Execution stage where the failure occurred |
| retryable | any | None | Whether policy considers this failure eligible for retry |
| effect_state | any | "none" | Observed state of the logical effect |
| recovery_action | any | None | Selected recovery operation |
| call_id | any | None | Identifier of this tool invocation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Build an AgentErrorV1 document (M-A1). |
Use code, message=None, category=None, stage="agent", retryable=None, effect_state="none", recovery_action=None, call_id=None as the inputs for this operation.
Build an AgentErrorV1 document (M-A1).
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Error make](agent_error_make(code=code, message=message, category=category, stage=stage, retryable=retryable, effect_state=effect_state, recovery_action=recovery_action, call_id=call_id)).
error_decide_retry
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| error | any | required | Structured failure information supplied by the caller |
| attempts | any | 0 | Retry or exploration attempts already performed |
| effect_class | any | "read" | Declared kind of effect for this operation |
| cancelled | any | False | Whether cancellation has already been requested |
| fingerprint_repeats | any | 0 | Number of repeated identical failure fingerprints |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Bounded recovery decision. Write / unknown effect → manual_review (no auto redo). |
Use error, attempts=0, effect_class="read", cancelled=False, fingerprint_repeats=0 as the inputs for this operation.
Bounded recovery decision. Write / unknown effect → manual_review (no auto redo).
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Error decide retry](agent_error_decide_retry(error=error, attempts=attempts, effect_class=effect_class, cancelled=cancelled, fingerprint_repeats=fingerprint_repeats)).
resume_clear
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| resume_dir | any | ".marqdo/agent-resume" | Directory holding continuation checkpoints |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Delete a resume checkpoint. |
Use id, resume_dir=".marqdo/agent-resume" as the inputs for this operation.
Delete a resume checkpoint.
Return [Resume clear](agent_resume_clear(id=id, resume_dir=resume_dir)).
resume_list
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| resume_dir | any | ".marqdo/agent-resume" | Directory holding continuation checkpoints |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | List checkpoint ids under resume_dir. |
Use resume_dir=".marqdo/agent-resume" as the inputs for this operation.
List checkpoint ids under resume_dir.
Return Resume list.
resume
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| resume_dir | any | ".marqdo/agent-resume" | Directory holding continuation checkpoints |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Author entry: load checkpoint for continuation. Returns the checkpoint map (found/round/workbook/…). Callers continue with plan/run using saved fields; clear when done. |
Use id, resume_dir=".marqdo/agent-resume" as the inputs for this operation.
Author entry: load checkpoint for continuation. Returns the checkpoint map (found/round/workbook/…). Callers continue with plan/run using saved fields; clear when done.
Return [Resume load](resume_load(id=id, resume_dir=resume_dir)).
effects_prepare
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| operation_id | any | required | Stable idempotent operation identifier |
| idempotency_key | any | required | Key identifying the same logical effect across retries |
| args_digest | any | required | Digest of the exact operation arguments |
| effect_class | any | "write" | Declared kind of effect for this operation |
| resource_scope | any | None | Resource boundary to which the operation applies |
| expected_revision | any | None | Revision the controlled update expects |
| result_ref | any | None | Durable reference to an already-produced result |
| logical_run_id | any | None | Stable logical execution identifier shared by retries |
| step_id | any | None | Identifier of the current workbook step |
| attempt_id | any | None | Identifier for this execution attempt |
| ledger_dir | any | ".marqdo/agent-effects" | Directory holding the durable effect ledger |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Create (or dedupe) an EffectLedgerRecordV1 in prepared. Same idempotency_key + args_digest returns the existing record; same key with different digest is rejected. |
Use operation_id, idempotency_key, args_digest, effect_class="write", resource_scope=None, expected_revision=None, result_ref=None, logical_run_id=None, step_id=None, attempt_id=None, ledger_dir=".marqdo/agent-effects" as the inputs for this operation.
Create (or dedupe) an EffectLedgerRecordV1 in prepared. Same idempotency_key + args_digest returns the existing record; same key with different digest is rejected.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Effects prepare](agent_effects_prepare(operation_id=operation_id, idempotency_key=idempotency_key, args_digest=args_digest, effect_class=effect_class, resource_scope=resource_scope, expected_revision=expected_revision, result_ref=result_ref, logical_run_id=logical_run_id, step_id=step_id, attempt_id=attempt_id, ledger_dir=ledger_dir)).
effects_transition
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| operation_id | any | required | Stable idempotent operation identifier |
| state | any | required | Structured current state |
| result_ref | any | None | Durable reference to an already-produced result |
| note | any | None | Human-readable context associated with the record |
| reconcile_hint | any | None | Hint for reconciling an uncertain effect, not authorization to repeat it |
| ledger_dir | any | ".marqdo/agent-effects" | Directory holding the durable effect ledger |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Advance ledger state (prepared→started→committed|failed_no_effect|unknown→reconciled_*). |
Use operation_id, state, result_ref=None, note=None, reconcile_hint=None, ledger_dir=".marqdo/agent-effects" as the inputs for this operation.
Advance ledger state (prepared→started→committed|failed_no_effect|unknown→reconciled_*).
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Effects transition](agent_effects_transition(operation_id=operation_id, state=state, result_ref=result_ref, note=note, reconcile_hint=reconcile_hint, ledger_dir=ledger_dir)).
effects_get
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| operation_id | any | required | Stable idempotent operation identifier |
| ledger_dir | any | ".marqdo/agent-effects" | Directory holding the durable effect ledger |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Load one ledger record. |
Use operation_id, ledger_dir=".marqdo/agent-effects" as the inputs for this operation.
Load one ledger record.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Effects get](agent_effects_get(operation_id=operation_id, ledger_dir=ledger_dir)).
effects_list
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| ledger_dir | any | ".marqdo/agent-effects" | Directory holding the durable effect ledger |
| logical_run_id | any | None | Stable logical execution identifier shared by retries |
| state | any | None | Structured current state |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | List ledger records (optional filters). |
Use ledger_dir=".marqdo/agent-effects", logical_run_id=None, state=None as the inputs for this operation.
List ledger records (optional filters).
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Effects list](agent_effects_list(ledger_dir=ledger_dir, logical_run_id=logical_run_id, state=state)).
effects_watermark
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| ledger_dir | any | ".marqdo/agent-effects" | Directory holding the durable effect ledger |
| logical_run_id | any | None | Stable logical execution identifier shared by retries |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Digest committed/open effects for CheckpointV2. write_auto_resume_safe is false while unknown or pending writes remain. |
Use ledger_dir=".marqdo/agent-effects", logical_run_id=None as the inputs for this operation.
Digest committed/open effects for CheckpointV2. write_auto_resume_safe is false while unknown or pending writes remain.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Effects watermark](agent_effects_watermark(ledger_dir=ledger_dir, logical_run_id=logical_run_id)).
effects_reconcile
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| operation_id | any | required | Stable idempotent operation identifier |
| outcome | any | required | Observed domain result |
| result_ref | any | None | Durable reference to an already-produced result |
| note | any | None | Human-readable context associated with the record |
| ledger_dir | any | ".marqdo/agent-effects" | Directory holding the durable effect ledger |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Reconcile an unknown record: outcome = committed | no_effect | needs_input. |
Use operation_id, outcome, result_ref=None, note=None, ledger_dir=".marqdo/agent-effects" as the inputs for this operation.
Reconcile an unknown record: outcome = committed | no_effect | needs_input.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found")). We End this run with the selected exit status.
Return [Effects reconcile](agent_effects_reconcile(operation_id=operation_id, outcome=outcome, result_ref=result_ref, note=note, ledger_dir=ledger_dir)).
extract_call_args
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| reply | any | None | Model reply to parse as data; it is not permission to execute arbitrary code |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Parse ARGS:{…} JSON line, or a bare {…} line after CALL. |
Use reply=None as the inputs for this operation.
Parse ARGS:{…} JSON line, or a bare {…} line after CALL.
The following record names each literal field without a JSON construction chain.
Only the explicit ARGS line is parsed as JSON. Other reply prose remains inert, and absent arguments stay absent. This extraction does not validate the selected tool's schema or execute the reply; the dispatcher performs those later checks.
_literal_esc_fields =
| @ | key | value |
|---|---|---|
| 1 | "brace" | "{" |
| 2 | "mark" | "ARGS:" |
| 3 | "nl" | "\n" |
We build esc = Collect these named fields into one record.
We retain nl = [Read the nl field](json.get(value=esc, key="nl")).
We retain mark = [Read the mark field](json.get(value=esc, key="mark")).
We retain brace = [Read the brace field](json.get(value=esc, key="brace")).
We retain empty = Empty map.
replyWe retaintext= Trim. We retainlines= [Split](split(value=text, sep=nl)). We retain found = None.
- [line](遍历
lines为line)found_ = 1-
t= Trim. We retainchunks= [Split](split(value=t, sep=mark)). We retaincn= Len.cn> 1 We retainrest= [At](at(value=chunks, index=1)). We retainfound= Trim.-
We retain **`chunks` = [Split](split(value=`t`, sep=`brace`))**. We retain **`cn` = [Len](len(value=`chunks`))**. We retain **`prefix` = [At](at(value=`chunks`, index=0))**. 1. `cn` > 1 1. `prefix` **_ = 1** 2. * We retain **found = t**. 2. * **_ = 1**
foundReturn Parse the JSON transport text.-
Return *empty*.
Return empty.
tool_result_brief
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| value | any | None | Value supplied to this operation; immutable transformations return a new value |
| max_chars | any | 1024 | Maximum retained characters in the text excerpt |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Truncate a tool result for tool_end events (~1KiB). |
Use value=None, max_chars=1024 as the inputs for this operation.
Truncate a tool result for tool_end events (~1KiB).
valueWe retains= Encode the structured value as JSON text. Return [Text head lines](text_head_lines(text=s, max_lines=40, max_chars=max_chars)).-
Return None.
plan_append_tool
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| events | any | required | Ordered semantic or provider stream-event records |
| type | any | required | Structured item or event type |
| name | any | required | Name registered or looked up by this operation |
| kind | any | required | Operation or factorization kind listed in this function's behavior |
| result | any | None | Structured result from the preceding operation |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Always append tool_start / tool_end to events for audit / view process cards. SSE publish only when stream=True. |
Use events, type, name, kind, result=None, stream=False as the inputs for this operation.
Always append tool_start / tool_end to events for audit / view process cards. SSE publish only when stream=True.
ev =
| type | name | kind |
|---|---|---|
type |
name |
kind |
resultWe retainev= [Set the result field in the new record](table.put(in=ev, at="result", value=result)).-
_ = 1
We retain events = [Append this item to the new list](table.append(list=events, item=ev)).
streamWe Stream publish.-
_ = 1
Return events.
run_lib_call
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| name | any | required | Name registered or looked up by this operation |
| reply | any | None | Model reply to parse as data; it is not permission to execute arbitrary code |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Whitelist CALL:lib.<mod>.<fn> (+ ARGS). Rejects net/exec/write/delete. |
Use name, reply=None as the inputs for this operation.
Whitelist CALL:lib.<mod>.<fn> (+ ARGS). Rejects net/exec/write/delete.
We retain args = Extract call args.
Keep the literal separator as errs = [Keep the exact separator](table.put(in=None, at="deny", value="Lib CALL not allowed: ")).
name== lib.fs.exists We retainpath= [Read the path field](json.get(value=args, key="path")). Return Exists.name== lib.fs.read_text We retainpath= [Read the path field](json.get(value=args, key="path")). Return Read UTF-8 text from the selected file.name== lib.fs.list_dir We retainpath= [Read the path field](json.get(value=args, key="path")). Return List dir.name== lib.json.parse We retaintext= [Read the text field](json.get(value=args, key="text")). Return Parse the JSON transport text.name== lib.json.stringify We retainvalue= [Read the value field](json.get(value=args, key="value")). Return Encode the structured value as JSON text.name== lib.sys.cwd Return Cwd.-
We retain deny = [Read the deny field](json.get(value=errs, key="deny")).
Return deny + name.
scratch_tool_write
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| name | any | required | Name registered or looked up by this operation |
| text | any | required | Text supplied to the transformation or adapter |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Write a scratch tool workbook under .marqdo/agent-runs/tools/<name>.mq.md. |
Use name, text as the inputs for this operation.
Write a scratch tool workbook under .marqdo/agent-runs/tools/<name>.mq.md.
The following record names each literal field without a JSON construction chain.
_literal_esc_fields =
| @ | key | value |
|---|---|---|
| 1 | "a" | ".marqdo/agent-runs/tools/" |
| 2 | "b" | ".mq.md" |
We build esc = Collect these named fields into one record.
We retain a = [Read the a field](json.get(value=esc, key="a")).
We retain b = [Read the b field](json.get(value=esc, key="b")).
We retain dir = ".marqdo/agent-runs/tools".
We Make dir.
We retain path = a + name + b.
We [Write the prepared text to the selected file](fs.write_text(path=path, text=text)).
out =
| ok | path |
|---|---|
| True | path |
Return out.
skill_core_card
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Protected v2.1 Occlusion card always prepended to skill_brief (M05). Must not be truncated by budget. |
Protected v2.1 Occlusion card always prepended to skill_brief (M05). Must not be truncated by budget.
The card is kept as ordered lines so changes to any syntax instruction remain visible in review.
These rules precede the budgeted skill excerpt so essential marker meanings remain available when a long skill is shortened. The card describes the runtime surface, including legacy explicit parameters; new library authors use narrative parameters as required by the development guide. Keep both explanations consistent when evolving the language.
_literal_core_lines =
| line |
|---|
| "## CORE SYNTAX (v2.1 Occlusion)" |
| "1. Print with > print / > 打印 — never use bold markers to print." |
| "2. Bold markers = statement; italic markers = return." |
| "3. desc = occlusion; brackets never execute." |
| "4. Read with access(coll, key) — never Classic key index." |
| "5. Foreach: - [desc](for coll as item). import + one language per file." |
| "6. # type · ## function · + params · numbered branches · - loops." |
| "" |
We preserve _literal_core_text = [Join the protected instructions with their exact newlines](text.str_join(xs=_literal_core_lines, sep="\n"))
and retain esc = [Name the complete protected card](table.put(in=None, at="card", value=_literal_core_text)).
Return [Read the card field](json.get(value=esc, key="card")).
skill_brief
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| max_chars | any | 1200 | Maximum retained characters in the text excerpt |
| depth | any | "default" | Requested context or discovery depth |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Budgeted marqdo skill text for prompts. Core Occlusion card is always included; remaining budget truncates the rest. depth=deep raises the char budget. |
Use max_chars=1200, depth="default" as the inputs for this operation.
Budgeted marqdo skill text for prompts. Core Occlusion card is always included; remaining budget truncates the rest. depth=deep raises the char budget.
depth== deep We retain budget = 4000.-
We retain budget = max_chars.
We retain core = Skill core card.
We retain core_len = Len.
We retain rest_budget = budget - core_len - 2.
rest_budget< 200 We retain rest_budget = 200.-
_ = 1
We retain skill = Marqdo skill.
We retain full = Len.
We retain rest = [Text head lines](text_head_lines(text=skill, max_lines=80, max_chars=rest_budget)).
Keep the literal separator as esc = [Keep the exact separator](table.put(in=None, at="nl", value="\n\n")).
We retain nl = [Read the nl field](json.get(value=esc, key="nl")).
We retain ex = core + nl + rest.
We retain used = Len.
used<full+core_lenThe following record names each literal field without a JSON construction chain.
_literal_esc2_fields =
| @ | key | value |
|---|---|---|
| 1 | "a" | "\n…[truncated skill_len=" |
| 2 | "b" | " budget_chars=" |
| 3 | "c" | "; emit READ:skill to deepen]" |
We build esc2 = Collect these named fields into one record.
We retain a = [Read the a field](json.get(value=esc2, key="a")).
We retain b = [Read the b field](json.get(value=esc2, key="b")).
We retain c = [Read the c field](json.get(value=esc2, key="c")).
Return ex + a + full + b + budget + c.
2. *
Return ex.
source_brief
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| depth | any | "default" | Requested context or discovery depth |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Budgeted current-module .mq.md source for step prompts. Default ~80 lines / 4KiB; depth=deep ~200 / 12KiB. |
Use depth="default" as the inputs for this operation.
Budgeted current-module .mq.md source for step prompts. Default ~80 lines / 4KiB; depth=deep ~200 / 12KiB.
We retain src = Module source.
We retain full = Len.
depth== deep We retainex= [Workbook source excerpt](workbook_source_excerpt(source=src, max_lines=200, max_chars=12000)). We retain budget = 12000.-
We retain ex = [Workbook source excerpt](workbook_source_excerpt(source=src, max_lines=80, max_chars=4000)).
We retain budget = 4000.
We retain used = Len.
used<fullThe following record names each literal field without a JSON construction chain.
_literal_esc_fields =
| @ | key | value |
|---|---|---|
| 1 | "a" | "\n…[truncated source_len=" |
| 2 | "b" | " budget_chars=" |
| 3 | "c" | "; emit READ:source to deepen]" |
We build esc = Collect these named fields into one record.
We retain a = [Read the a field](json.get(value=esc, key="a")).
We retain b = [Read the b field](json.get(value=esc, key="b")).
We retain c = [Read the c field](json.get(value=esc, key="c")).
Return ex + a + full + b + budget + c.
2. *
Return ex.
extract_plan_read
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| reply | any | required | Model reply to parse as data; it is not permission to execute arbitrary code |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Parse READ:source|stderr|stdout|slots|skill (Chinese: 读取:…). |
Use reply as the inputs for this operation.
Parse READ:source|stderr|stdout|slots|skill (Chinese: 读取:…).
The following record names each literal field without a JSON construction chain.
A READ request asks the orchestration loop for a bounded excerpt, rather than reading a file directly. The parser extracts the named context kind from a reply line. The caller still chooses which kinds it supports and how many additional turns it permits.
_literal_esc_fields =
| @ | key | value |
|---|---|---|
| 1 | "fw" | ":" |
| 2 | "nl" | "\n" |
We build esc = Collect these named fields into one record.
We retain nl = [Read the nl field](json.get(value=esc, key="nl")).
We retain fw = [Read the fw field](json.get(value=esc, key="fw")).
We retain text = Trim.
We retain lines = [Split](split(value=text, sep=nl)).
We retain found = None.
- [line](遍历
lines为line) We retaint= Trim. We retainparts= [Split](split(value=t, sep=":")). We retainn= Len.n> 1 We retainhead= [At](at(value=parts, index=0)). We retainhead= Trim. We retainrest= [At](at(value=parts, index=1)). We retainrest= Trim.head== READ We retain found = rest.head== 读取 We retain found = rest.-
**_ = 1**parts= [Split](split(value=t, sep=fw)). We retainn= Len.n> 1 We retainhead= [At](at(value=parts, index=0)). We retainhead= Trim. We retainrest= [At](at(value=parts, index=1)). We retainrest= Trim. 1.head== 读取 We retain found = rest. 2.head== READ We retain found = rest. 3. * _ = 1-
**_ = 1**
Return found.
extract_plan_act
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| reply | any | required | Model reply to parse as data; it is not permission to execute arbitrary code |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Priority: CALL → READ → DECISION. Returns {kind,name}. |
Use reply as the inputs for this operation.
Priority: CALL → READ → DECISION. Returns {kind,name}.
We retain tool = Extract tool name.
tool
out =
| kind | name |
|---|---|
| call | tool |
Return out.
2. *
_ = 1
We retain rk = Extract plan read.
rk
out =
| kind | name |
|---|---|
| read | rk |
Return out.
2. *
_ = 1
We retain dec = Extract plan decision.
dec
out =
| kind | name |
|---|---|
| decision | dec |
Return out. 2. *
out =
| kind |
|---|
| unknown |
Return out.
extract_scratch_tool
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| reply | any | required | Model reply to parse as data; it is not permission to execute arbitrary code |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Parse NAME: id plus a triple-angle body after CALL:scratch_tool_write. |
Use reply as the inputs for this operation.
Parse NAME: id plus a triple-angle body after CALL:scratch_tool_write.
The following record names each literal field without a JSON construction chain.
The tool name and source body are returned as data. The body starts only at the explicit triple-angle opening line and ends at its matching closing line; surrounding commentary is excluded. This function does not write or run that source. The scratch writer remains responsible for destination checks, and the dispatcher still decides whether the requested tool is allowed.
_literal_esc_fields =
| @ | key | value |
|---|---|---|
| 1 | "close" | ">>>" |
| 2 | "nl" | "\n" |
| 3 | "open" | "<<<" |
We build esc = Collect these named fields into one record.
We retain nl = [Read the nl field](json.get(value=esc, key="nl")).
We retain open = [Read the open field](json.get(value=esc, key="open")).
We retain close = [Read the close field](json.get(value=esc, key="close")).
We retain text = Trim.
We retain lines = [Split](split(value=text, sep=nl)).
We retain name = None.
We retain body_lines = Empty list.
We retain in_body = None.
- [line](遍历
lines为line)in_bodyWe retaint= Trim.t==closeWe retain in_body = None.-
We retain **`body_lines` = [Append this item to the new list](table.append(list=`body_lines`, item=`line`))**.t= Trim. We retainparts= [Split](split(value=t, sep=":")). We retainn= Len.n> 1 We retainhead= [At](at(value=parts, index=0)). We retainhead= Trim. We retainrest= [At](at(value=parts, index=1)). We retainrest= Trim. 1.head== NAME We retain name = rest. 2.head== 名称 We retain name = rest. 3. * _ = 1-
**_ = 1**t==openWe retain in_body = 1.-
**_ = 1**
We retain body = [Join](join(value=body_lines, sep=nl)).
out =
| name | text |
|---|---|
name |
body |
Return out.
run_parent_tool
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| name | any | required | Name registered or looked up by this operation |
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| observation | any | None | Tool observation or workbook result retained for the next turn |
| reply | any | None | Model reply to parse as data; it is not permission to execute arbitrary code |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Parent Plan-and-Move tools (helpers + whitelist CALL:lib…). |
Use name, path, observation=None, reply=None as the inputs for this operation.
Parent Plan-and-Move tools (helpers + whitelist CALL:lib…).
name== workbook_read This dispatcher has a fixed set of parent operations. Workbook readers operate on the selected workbook path; catalog lookup returns data; scratch creation first extracts a name and body. The corpus and MCP-shaped evidence branches parse explicit ARGS records and report missing required fields before calling their adapters. Those fixture adapters are not a live MCP transport.
Arguments are deliberately read only after the value has been recognized as a record. Optional root, limit and argument fields are passed only when present, allowing the target helper to apply its own defaults. An unknown name reaches the restricted library dispatcher; it does not become an arbitrary function call. Editing this branch list therefore changes the parent tool surface and needs an allowlist regression, in addition to a prose update.
Return [Workbook read](workbook_read(path=path, depth="deep")).
2. name == workbook_excerpt
Return Workbook excerpt.
3. name == lib_catalog
Return Lib catalog.
4. name == scratch_tool_write
We retain parsed = Extract scratch tool.
We retain parsed_s = Encode the structured value as JSON text.
We retain parsed_map = [Starts with](text.starts_with(text=parsed_s, prefix="{")).
We retain tn = None.
We retain tt = None.
parsed_mapWe retaintn= [Read the name field](json.get(value=parsed, key="name")). We retaintt= [Read the text field](json.get(value=parsed, key="text")).-
**_ = 1**
The following record names each literal field without a JSON construction chain.
_literal_errs_fields =
| @ | key | value |
|---|---|---|
| 1 | "a" | "scratch_tool_write needs NAME line and fenced body" |
| 2 | "b" | "scratch_tool_write needs NAME id" |
We build errs = Collect these named fields into one record.
tn1.ttReturn [Scratch tool write](scratch_tool_write(name=tn, text=tt)). 2. * Return [Read the a field](json.get(value=errs, key="a")).-
Return *[Read the b field](json.get(value=`errs`, key="b"))*.
name== corpus_search We retainargs= Extract call args. We retainargs_s= Encode the structured value as JSON text. We retainargs_map= [Starts with](text.starts_with(text=args_s, prefix="{")). We retain q = None. We retain root = None. We retain limit = None.args_mapWe retainq= [Read the query field](json.get(value=args, key="query")). We retainroot= [Read the root field](json.get(value=args, key="root")). We retainlimit= [Read the limit field](json.get(value=args, key="limit")).-
**_ = 1**
Keep the literal separator as cerrs = [Keep the exact separator](table.put(in=None, at="q", value="corpus_search needs ARGS.query")).
- not
qReturn [Read the q field](json.get(value=cerrs, key="q")). root1.limitReturn [Corpus search](corpus_search(query=q, root=root, limit=limit)). 2. * Return [Corpus search](corpus_search(query=q, root=root)).limitReturn [Corpus search](corpus_search(query=q, limit=limit)).-
Return *[Corpus search](corpus_search(query=`q`))*.
name== mcp_list_tools We retainargs= Extract call args. We retainargs_s= Encode the structured value as JSON text. We retainargs_map= [Starts with](text.starts_with(text=args_s, prefix="{")). We retain fx = None.args_mapWe retainfx= [Read the fixture field](json.get(value=args, key="fixture")).-
**_ = 1**
Keep the literal separator as merrs = [Keep the exact separator](table.put(in=None, at="f", value="mcp_list_tools needs ARGS.fixture")).
fxReturn Mcp list tools.-
Return *[Read the f field](json.get(value=`merrs`, key="f"))*.
name== mcp_call We retainargs= Extract call args. We retainargs_s= Encode the structured value as JSON text. We retainargs_map= [Starts with](text.starts_with(text=args_s, prefix="{")). We retain fx = None. We retain tn = None. We retain targ = None.args_mapWe retainfx= [Read the fixture field](json.get(value=args, key="fixture")). We retaintn= [Read the name field](json.get(value=args, key="name")). We retaintarg= [Read the arguments field](json.get(value=args, key="arguments")).-
**_ = 1**
The following record names each literal field without a JSON construction chain.
_literal_xerrs_fields =
| @ | key | value |
|---|---|---|
| 1 | "f" | "mcp_call needs ARGS.fixture" |
| 2 | "n" | "mcp_call needs ARGS.name" |
We build xerrs = Collect these named fields into one record.
fx1.tntargReturn [Mcp call](mcp_call(name=tn, fixture=fx, arguments=targ)).-
tn, fixture=fx)). 2. * Return [Read the n field](json.get(value=xerrs, key="n")).-
Return *[Read the f field](json.get(value=`xerrs`, key="f"))*.
We retain dots = [Split](split(value=name, sep=".*")).
We retain head = [At](at(value=dots, index=0)).
head== lib Return [Run lib call](run_lib_call(name=name, reply=reply)).-
We retain **msg = "Parent tool not allowed:"**.
Return *msg + name*.
plan_read_deepen
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| observation | any | required | Tool observation or workbook result retained for the next turn |
| kind | any | required | Operation or factorization kind listed in this function's behavior |
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Apply the requested source or skill depth increase before preparing another planning turn. |
Use observation, kind, path as the inputs for this operation.
We retain obs = observation.
kind== source We retainex= [Workbook read](workbook_read(path=path, depth="deep")). We retainobs= [Set the source_excerpt field in the new record](table.put(in=obs, at="source_excerpt", value=ex)). We retainobs= [Set the read_source field in the new record](table.put(in=obs, at="read_source", value=True)).kind== stderr We retainerr= [Read the stderr field](json.get(value=obs, key="stderr")). We retaintail= [Text tail lines](text_tail_lines(text=err, max_lines=80, max_chars=6000)). We retainobs= [Set the stderr_tail field in the new record](table.put(in=obs, at="stderr_tail", value=tail)). We retainobs= [Set the read_stderr field in the new record](table.put(in=obs, at="read_stderr", value=True)).kind== stdout We retainout= [Read the stdout field](json.get(value=obs, key="stdout")). We retaintail= [Text tail lines](text_tail_lines(text=out, max_lines=80, max_chars=6000)). We retainobs= [Set the stdout_tail field in the new record](table.put(in=obs, at="stdout_tail", value=tail)). We retainobs= [Set the read_stdout field in the new record](table.put(in=obs, at="read_stdout", value=True)).kind== slots We retainslots= [Read the slots field](json.get(value=obs, key="slots")). We retainobs= [Set the slots_detail field in the new record](table.put(in=obs, at="slots_detail", value=slots)). We retainobs= [Set the read_slots field in the new record](table.put(in=obs, at="read_slots", value=True)).kind== skill We retainbrief= Skill brief. We retainobs= [Set the skill_brief field in the new record](table.put(in=obs, at="skill_brief", value=brief)). We retainobs= [Set the read_skill field in the new record](table.put(in=obs, at="read_skill", value=True)).-
_ = 1 Return obs.
compact_plan_observation
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| observation | any | required | Tool observation or workbook result retained for the next turn |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Bounded observation for the parent prompt (actionable, short). Tolerates missing/non-map observation (empty compact) instead of json get needs map. Map check via stringify prefix { — never hard-get on None / bare text / list. |
Use observation as the inputs for this operation.
Bounded observation for the parent prompt (actionable, short).
Tolerates missing/non-map observation (empty compact) instead of json get needs map.
Map check via stringify prefix { — never hard-get on None / bare text / list.
A child observation can contain a full workbook, process output and slot values. Sending all of that on every parent turn wastes context and can obscure the next decision. This projection retains the execution path and exit status, records source size, and carries selected excerpts or tails for repair. It returns a new record; it neither edits the workbook nor changes the original observation.
The source marker check is a structural hint: it looks for worker.step in the source text. That hint is not evidence that a model ran or that its answer is correct. Likewise, an exit status of zero is useful execution evidence, but a parent still needs a returned value and task-specific verification before DONE. The compact record's note communicates that decision protocol without granting the helper authority to declare success.
When an observation already supplies a source excerpt or an output tail, that bounded view is reused. Otherwise the existing excerpt and tail helpers derive it from the full field. This keeps the same repair window available without transporting every log line. Missing source, output or slots simply leave the corresponding optional information absent.
The initial record test protects None, ordinary text and lists from map-only access. A compact observation is therefore usable even after a child fails before producing its usual record. Consumers should read the available status and diagnostic fields instead of assuming that absence means an empty successful result. To investigate beyond these bounds, request an explicit deeper read through the parent protocol.
For example, a failed child may provide stderr and source but no value. Keep the diagnostic tail for repair and leave result absent; replacing the missing value with a successful placeholder would destroy that evidence.
We retain obs_path = None.
We retain obs_code = None.
We retain obs_val = None.
We retain obs_slots = None.
We retain obs_src = None.
We retain obs_stdout = None.
We retain obs_stderr = None.
We retain obs_s = Encode the structured value as JSON text.
We retain obs_map = [Starts with](text.starts_with(text=obs_s, prefix="{")).
obs_mapWe retainobs_path= [Read the path field](json.get(value=observation, key="path")). We retainobs_code= [Read the exit_code field](json.get(value=observation, key="exit_code")). We retainobs_val= [Read the value field](json.get(value=observation, key="value")). We retainobs_slots= [Read the slots field](json.get(value=observation, key="slots")). We retainobs_src= [Read the source field](json.get(value=observation, key="source")). We retainobs_stdout= [Read the stdout field](json.get(value=observation, key="stdout")). We retainobs_stderr= [Read the stderr field](json.get(value=observation, key="stderr")).-
_ = 1 We retain src_len = 0. We retain has_step = False.
obs_srcWe retainsrc_len= Len. We retainstep_parts= [Split](split(value=obs_src, sep="worker.step")). We retainn_step= Len.n_step> 1 We retain has_step = True.-
**_ = 1**
_ = 1
compact =
| note | path | exit_code | source_len | has_worker_step | solidify_on_done |
|---|---|---|---|---|---|
| Plan-and-Move: CALL/READ then DECISION. Success (exit 0 + has_value) → DONE. solidify_on_done. No long prose. | obs_path |
obs_code |
src_len |
has_step |
True |
obs_mapobs_srcWe retainex= [Read the source_excerpt field](json.get(value=observation, key="source_excerpt")). 1.exWe retaincompact= [Set the source_excerpt field in the new record](table.put(in=compact, at="source_excerpt", value=ex)). 2. * We retainex= Workbook source excerpt. We retaincompact= [Set the source_excerpt field in the new record](table.put(in=compact, at="source_excerpt", value=ex)).-
**_ = 1**
obs_stderrWe retaintail= [Read the stderr_tail field](json.get(value=observation, key="stderr_tail")). 1.tailWe retaincompact= [Set the stderr_tail field in the new record](table.put(in=compact, at="stderr_tail", value=tail)). 2. * We retaintail= Text tail lines. We retaincompact= [Set the stderr_tail field in the new record](table.put(in=compact, at="stderr_tail", value=tail)).-
**_ = 1**
obs_stdoutWe retaintail= [Read the stdout_tail field](json.get(value=observation, key="stdout_tail")). 1.tailWe retaincompact= [Set the stdout_tail field in the new record](table.put(in=compact, at="stdout_tail", value=tail)). 2. * We retaintail= Text tail lines. We retaincompact= [Set the stdout_tail field in the new record](table.put(in=compact, at="stdout_tail", value=tail)).-
**_ = 1**
We retain val_txt = Str.
We retain val_len = Len.
obs_valWe retaincompact= [Set the has_value field in the new record](table.put(in=compact, at="has_value", value=True)). We retaincompact= [Set the value_len field in the new record](table.put(in=compact, at="value_len", value=val_len)). 1.val_len> 200 We retainpreview= [Text head lines](text_head_lines(text=val_txt, max_lines=4, max_chars=200)). We retaincompact= [Set the value_preview field in the new record](table.put(in=compact, at="value_preview", value=preview)). 2. * We retaincompact= [Set the value field in the new record](table.put(in=compact, at="value", value=obs_val)).-
We retain **`compact` = [Set the has_value field in the new record](table.put(in=`compact`, at="has_value", value=False))**.
We retain slots_brief = Empty list.
-
obs_slots- [slot](遍历obs_slots为slot) We retainsk= [Read the key field](json.get(value=slot, key="key")). We retainsl= [Read the line field](json.get(value=slot, key="line")). We retainsb= [Read the body field](json.get(value=slot, key="body")). We retainsb_txt= Str. We retainsb_len= Len.brief=key line body_len skslsb_lensk== error We retainprev= [Text head lines](text_head_lines(text=sb_txt, max_lines=8, max_chars=400)). We retainbrief= [Set the body_preview field in the new record](table.put(in=brief, at="body_preview", value=prev)).-
_ = 1 We retain
slots_brief= [Append this item to the new list](table.append(list=slots_brief, item=brief)). -
**_ = 1**
We retain compact = [Set the slots field in the new record](table.put(in=compact, at="slots", value=slots_brief)).
We retain detail = [Read the slots_detail field](json.get(value=observation, key="slots_detail")).
detailWe retaincompact= [Set the slots_detail field in the new record](table.put(in=compact, at="slots_detail", value=detail)).-
**_ = 1**
We retain tool_result = [Read the tool_result field](json.get(value=observation, key="tool_result")).
tool_resultWe retaintr= Str. We retaintr= [Text head lines](text_head_lines(text=tr, max_lines=40, max_chars=3000)). We retaincompact= [Set the tool_result field in the new record](table.put(in=compact, at="tool_result", value=tr)).-
**_ = 1**
We retain last_error = [Read the last_error field](json.get(value=observation, key="last_error")).
last_errorWe retainerr_txt= Str. We retainerr_len= Len. 1.err_len> 200 We retainprev= [Text head lines](text_head_lines(text=err_txt, max_lines=8, max_chars=400)). We retaincompact= [Set the last_error_preview field in the new record](table.put(in=compact, at="last_error_preview", value=prev)). We retaincompact= [Set the last_error_len field in the new record](table.put(in=compact, at="last_error_len", value=err_len)). 2. * We retaincompact= [Set the last_error field in the new record](table.put(in=compact, at="last_error", value=last_error)).-
**_ = 1**
We retain compact = [Set the has_value field in the new record](table.put(in=compact, at="has_value", value=False)).
We retain empty_slots = Empty list.
We retain compact = [Set the slots field in the new record](table.put(in=compact, at="slots", value=empty_slots)).
Return compact.
extract_plan_decision
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| reply | any | required | Model reply to parse as data; it is not permission to execute arbitrary code |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Parse DECISION: DONE / CONTINUE / RUN (Chinese: 决定:完成 / 继续 / 运行). First matching DECISION / 决定 line wins (ignore later conflicting decisions in the same reply). |
Use reply as the inputs for this operation.
Parse DECISION: DONE / CONTINUE / RUN (Chinese: 决定:完成 / 继续 / 运行).
First matching DECISION / 决定 line wins (ignore later conflicting decisions in the same reply).
The following record names each literal field without a JSON construction chain.
A decision is extracted from the model's protocol text and returned to the orchestration loop. It is not executed here. The loop must still distinguish RUN, CONTINUE and DONE and verify whether the workbook has a usable result.
_literal_esc_fields =
| @ | key | value |
|---|---|---|
| 1 | "fw" | ":" |
| 2 | "nl" | "\n" |
We build esc = Collect these named fields into one record.
We retain nl = [Read the nl field](json.get(value=esc, key="nl")).
We retain fw = [Read the fw field](json.get(value=esc, key="fw")).
We retain text = Trim.
We retain lines = [Split](split(value=text, sep=nl)).
We retain found = None.
- [line](遍历
lines为line)found_ = 1-
t= Trim. We retainparts= [Split](split(value=t, sep=":")). We retainn= Len.n> 1 We retainhead= [At](at(value=parts, index=0)). We retainhead= Trim. We retainrest= [At](at(value=parts, index=1)). We retainrest= Trim. 1.head== DECISION We retain found = rest. 2.head== 决定 We retain found = rest. 3. * _ = 1-
We retain **`parts` = [Split](split(value=`t`, sep=`fw`))**. We retain **`n` = [Len](len(value=`parts`))**. 1. `n` > 1 We retain **`head` = [At](at(value=`parts`, index=0))**. We retain **`head` = [Trim](trim(value=`head`))**. We retain **`rest` = [At](at(value=`parts`, index=1))**. We retain **`rest` = [Trim](trim(value=`rest`))**. 1. `head` == 决定 We retain **found = rest**. 2. `head` == DECISION We retain **found = rest**. 3. * **_ = 1** 2. * **_ = 1**
foundTake the first token only (DECISION: RUN please→ RUN). We retaintoks= [Split](split(value=found, sep=" ")). We retainfound= [At](at(value=toks, index=0)). We retainfound= Trim.-
_ = 1
found== DONE Return "DONE".found== CONTINUE Return "CONTINUE".found== RUN Return "RUN".found== REUSE Return "REUSE".found== NEW Return "NEW".found== 完成 Return "DONE".found== 继续 Return "CONTINUE".found== 运行 Return "RUN".found== 复用 Return "REUSE".found== 新建 Return "NEW".found== PATCH Models sometimes inventDECISION: PATCH— treat as CONTINUE. Return "CONTINUE".-
If the reply carries a FIND/REPLACE block, treat unknown labels as CONTINUE.
We retain has_find = [Split](split(value=text, sep="<<<")).
We retain n_find = Len.
n_find> 1 Return "CONTINUE".-
Return *found*.
extract_soft_match_slug
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| reply | any | required | Model reply to parse as data; it is not permission to execute arbitrary code |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Parse SLUG: … / 标识:… after a soft-match REUSE decision. |
Use reply as the inputs for this operation.
Parse SLUG: … / 标识:… after a soft-match REUSE decision.
The following record names each literal field without a JSON construction chain.
The returned slug identifies a candidate from the proposed knowledge entries. It is a lookup result rather than a filesystem authorization. The later route-application stage must resolve it against the knowledge directory before any workbook is executed.
_literal_esc_fields =
| @ | key | value |
|---|---|---|
| 1 | "fw" | ":" |
| 2 | "nl" | "\n" |
We build esc = Collect these named fields into one record.
We retain nl = [Read the nl field](json.get(value=esc, key="nl")).
We retain fw = [Read the fw field](json.get(value=esc, key="fw")).
We retain text = Trim.
We retain lines = [Split](split(value=text, sep=nl)).
We retain found = None.
- [line](遍历
lines为line) We retaint= Trim. We retainparts= [Split](split(value=t, sep=":")). We retainn= Len.n> 1 We retainhead= [At](at(value=parts, index=0)). We retainhead= Trim. We retainrest= [At](at(value=parts, index=1)). We retainrest= Trim.head== SLUG We retain found = rest.head== 标识 We retain found = rest.-
**_ = 1**parts= [Split](split(value=t, sep=fw)). We retainn= Len.n> 1 We retainhead= [At](at(value=parts, index=0)). We retainhead= Trim. We retainrest= [At](at(value=parts, index=1)). We retainrest= Trim. 1.head== 标识 We retain found = rest. 2.head== SLUG We retain found = rest. 3. * _ = 1-
**_ = 1**
Return found.
build_soft_match_prompt
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| goal | any | required | Human task goal represented by this operation |
| tasks | any | required | Ordered task records |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Short parent prompt: REUSE+SLUG or NEW only. Candidates may include lexical score (prefer higher). list_tasks rows may also carry description / status / llm_free. |
Use goal, tasks as the inputs for this operation.
Short parent prompt: REUSE+SLUG or NEW only. Candidates may include lexical score (prefer higher). list_tasks rows may also carry description / status / llm_free.
Keep this text as ordered lines so its instructions and blank-line boundaries can be read directly.
Candidate rows are evidence for a reuse choice, not executable instructions. Their slugs identify existing knowledge; titles and optional metadata help the parent compare task fit. A lexical score measures local text similarity, while llm_free describes whether the selected skill can run without a parent model. Neither alone establishes that its answer satisfies this new goal.
The output protocol deliberately permits only REUSE with a listed slug or NEW. The caller parses that decision and applies the selected resource through the ordinary route path. Building this prompt does not execute a candidate, alter its status, or add model-generated names to the tool whitelist.
_literal_esc_c_lines =
| line |
|---|
| "" |
| "" |
| "--- how to act ---" |
| "Exact reuse miss; candidates are ranked by local n-gram score when present. Prefer higher scores and llm_free=true skills. Reply with ONE protocol only:" |
| "DECISION: REUSE" |
| "SLUG: " |
| "or" |
| "DECISION: NEW" |
| "No other prose." |
| "" |
Join exactly those lines into _literal_esc_c_text = [Retain the original newline boundaries](text.str_join(xs=_literal_esc_c_lines, sep="\n")).
The following record names each literal field without a JSON construction chain.
_literal_esc_fields =
| @ | key | value |
|---|---|---|
| 1 | "a" | "\n\n--- goal ---\n" |
| 2 | "b" | "\n\n--- candidate tasks (slug | title | meta) ---\n" |
| 3 | "c" | _literal_esc_c_text |
| 4 | "lf" | "llm_free=" |
| 5 | "nl" | "\n" |
| 6 | "sep" | " | " |
| 7 | "sp" | "score=" |
| 8 | "st" | "status=" |
We build esc = Collect these named fields into one record.
We retain a = [Read the a field](json.get(value=esc, key="a")).
We retain b = [Read the b field](json.get(value=esc, key="b")).
We retain c = [Read the c field](json.get(value=esc, key="c")).
We retain nl = [Read the nl field](json.get(value=esc, key="nl")).
We retain sep = [Read the sep field](json.get(value=esc, key="sep")).
We retain sp = [Read the sp field](json.get(value=esc, key="sp")).
We retain st = [Read the st field](json.get(value=esc, key="st")).
We retain lf = [Read the lf field](json.get(value=esc, key="lf")).
We retain lines = Empty list.
- [t](遍历
tasks为t) We retainslug= [Read the slug field](json.get(value=t, key="slug")). We retaintitle= [Read the title field](json.get(value=t, key="title")). We retain row = slug + sep + title. We retainscore= [Read the score field](json.get(value=t, key="score")).scoreWe retain row = row + sep + sp + score.-
status= [Read the status field](json.get(value=t, key="status")).statusWe retain row = row + sep + st + status.-
free= [Read the llm_free field](json.get(value=t, key="llm_free")).free== True We retain row = row + sep + lf + "true".free== true We retain row = row + sep + lf + "true".free== False We retain row = row + sep + lf + "false".free== false We retain row = row + sep + lf + "false".-
desc= [Read the description field](json.get(value=t, key="description")).descWe retain row = row + sep + desc.-
lines= [Append this item to the new list](table.append(list=lines, item=row)). We retaincatalog= [Join](join(value=lines, sep=nl)). We retain p = "Soft-match: same task intent?". Return p + a + goal + b + catalog + c.
extract_plan_summary
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| reply | any | required | Model reply to parse as data; it is not permission to execute arbitrary code |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | First SUMMARY: / 汇总: / 汇总: line body, else trimmed reply. |
Use reply as the inputs for this operation.
First SUMMARY: / 汇总: / 汇总: line body, else trimmed reply.
The following record names each literal field without a JSON construction chain.
The summary is the short human-facing explanation attached to the plan result. It is kept separate from the decision so a sentence that happens to mention DONE does not itself finish a run. Source patches and tool requests are handled by their own extractors.
_literal_esc_fields =
| @ | key | value |
|---|---|---|
| 1 | "fw" | ":" |
| 2 | "nl" | "\n" |
We build esc = Collect these named fields into one record.
We retain nl = [Read the nl field](json.get(value=esc, key="nl")).
We retain fw = [Read the fw field](json.get(value=esc, key="fw")).
We retain text = Trim.
We retain lines = [Split](split(value=text, sep=nl)).
We retain found = None.
- [line](遍历
lines为line) We retaint= Trim. We retainparts= [Split](split(value=t, sep=":")). We retainn= Len.n> 1 We retainhead= [At](at(value=parts, index=0)). We retainhead= Trim. We retainrest= [At](at(value=parts, index=1)). We retainrest= Trim.head== SUMMARY We retain found = rest.head== 汇总 We retain found = rest.-
**_ = 1**parts= [Split](split(value=t, sep=fw)). We retainn= Len.n> 1 We retainhead= [At](at(value=parts, index=0)). We retainhead= Trim. We retainrest= [At](at(value=parts, index=1)). We retainrest= Trim. 1.head== 汇总 We retain found = rest. 2.head== SUMMARY We retain found = rest. 3. * _ = 1-
**_ = 1**
foundReturn found.-
Return text.
build_plan_context
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| agent | any | required | Agent configuration or receiver created by this package |
| goal | any | required | Human task goal represented by this operation |
| observation | any | required | Tool observation or workbook result retained for the next turn |
| explore_attempt | any | None | Current exploration attempt number |
| explore_n | any | None | Maximum configured exploration attempts |
| phase | any | "revise" | Named execution phase |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Parent Plan-and-Move prompt. Short protocol only — no long monologues. |
Use agent, goal, observation, explore_attempt=None, explore_n=None, phase="revise" as the inputs for this operation.
Parent Plan-and-Move prompt. Short protocol only — no long monologues.
The parent receives a decision surface rather than the whole child process. Its goal is serialized as data, standing instructions supply the agent role, and a compact observation conveys the last execution outcome. If the observation carries a skill brief, that already selected context is reused; otherwise the normal budgeted skill brief is loaded. Source remains authoritative even when an evidence adapter contributes useful facts.
There are two instruction branches. Before the first run, the decompose phase checks whether the generated skeleton can be executed as written. It may request evidence, propose a short patch, or choose RUN. During revision, the parent sees the child's outcome and chooses whether to repair or finish. A successful child with a usable value can lead to DONE; the mere presence of a worker call is not a reason to keep rewriting the workbook.
The protocol text is stored in visible line tables. Literal examples of CALL, READ, DECISION and patch delimiters are instructions for a later model reply, not commands executed while assembling the prompt. Their exact line breaks matter to the corresponding extractors. Do not replace this representation with a second workflow language, or hide a new tool behind a descriptive label without wiring its implementation.
The parent-tools section explains the restricted workbook, source and evidence actions. An explicit library CALL uses the dispatcher's whitelist and argument parsing. READ requests deepen context through the caller's budget. Scratch tool creation returns to the ordinary source-and-tool path; a sentence in the prompt cannot bypass filesystem roots, runtime effects or ToolSpec preparation.
Exploration metadata tells the parent which attempt it is inspecting and how many variants the surrounding planner configured. It does not create a loop here. This function only returns text; the plan loop owns round accounting, child execution, patch application and writeback. When debugging a wrong decision, inspect the returned sections alongside the actual observation and call site before changing model instructions.
To extend a parent's capabilities, first implement a real dispatcher branch with its input contract and tests. Then update the visible tool instructions. Changing this prompt alone only changes what the model sees and cannot establish a callable implementation.
We retain standing = [Read the standing field](json.get(value=agent, key="standing")).
standingWe retain up = standing.-
We retain up = None.
We retain skill_from_obs = None.
We retain obs_probe = Encode the structured value as JSON text.
We retain obs_is_map = [Starts with](text.starts_with(text=obs_probe, prefix="{")).
obs_is_mapWe retainskill_from_obs= [Read the skill_brief field](json.get(value=observation, key="skill_brief")).-
_ = 1
skill_from_obsWe retain skill = skill_from_obs.-
We retain skill = Skill brief.
We retain compact = Compact plan observation.
We retain obs_s = Encode the structured value as JSON text.
We retain goal_s = Encode the structured value as JSON text.
Keep this text as ordered lines so its instructions and blank-line boundaries can be read directly.
_literal_esc_e_dec_lines =
| line |
|---|
| "" |
| "" |
| "--- how to act ---" |
| "PRE-RUN decompose. Reply with ONE protocol only (no long reasoning). Exactly one DECISION line." |
| "1) Skeleton OK → DECISION: RUN (preferred). Do not rewrite imports; they are already nested import: (llm/agent/…)." |
| "2) Need evidence → READ:source or READ:skill or CALL:workbook_read / lib_catalog / corpus_search / mcp_call." |
| "3) Reshape body/logic only → DECISION: CONTINUE + short PATCH (<20 lines)." |
| "4) Fixed answer without LLM → PATCH to return, then RUN or DONE." |
| "PATCH must use <<< FIND === REPLACE >>> only (no \x60\x60\x60find / Begin Patch)." |
| "Protocols:" |
| "CALL:name" |
| "READ:kind" |
| "DECISION: RUN" |
| "DECISION: DONE" |
| "SUMMARY: one line" |
| "DECISION: CONTINUE" |
| "" |
Join exactly those lines into _literal_esc_e_dec_text = [Retain the original newline boundaries](text.str_join(xs=_literal_esc_e_dec_lines, sep="\n")).
Keep this text as ordered lines so its instructions and blank-line boundaries can be read directly.
_literal_esc_e_rev_lines =
| line |
|---|
| "" |
| "" |
| "--- how to act ---" |
| "Plan-and-Move parent. Reply with ONE protocol only (no long reasoning). Exactly one DECISION line." |
| "1) exit_code=0 and has_value → DECISION: DONE + one-line SUMMARY. solidify_on_done. Do not CONTINUE just because has_worker_step." |
| "2) Need more evidence → READ:kind or CALL:tool (then you will be re-prompted)." |
| "3) Failure / wrong value → DECISION: CONTINUE + short PATCH (<20 lines). Never paste user prose into REPLACE." |
| "4) Do NOT CONTINUE only to rewrite frontmatter imports; skeleton already uses nested import: map (llm/agent/json…)." |
| "PATCH must use triple-angle blocks only:" |
| "<<<" |
| "FIND" |
| "" |
| "===" |
| "REPLACE" |
| "" |
| ">>>" |
| "Do not use \x60\x60\x60find, \x60\x60\x60replace, or *** Begin Patch ***." |
| "Protocols:" |
| "CALL:name" |
| "READ:kind" |
| "DECISION: DONE" |
| "SUMMARY: one line" |
| "DECISION: CONTINUE" |
| "" |
Join exactly those lines into _literal_esc_e_rev_text = [Retain the original newline boundaries](text.str_join(xs=_literal_esc_e_rev_lines, sep="\n")).
Keep this text as ordered lines so its instructions and blank-line boundaries can be read directly.
_literal_esc_tools_lines =
| line |
|---|
| "" |
| "" |
| "--- parent tools ---" |
| "CALL:workbook_read | workbook_excerpt | lib_catalog | scratch_tool_write" |
| "CALL:corpus_search | mcp_list_tools | mcp_call (ARGS:{…}; evidence only — workbook authority)" |
| "CALL:lib.fs.read_text|exists|list_dir | lib.json.parse|stringify | lib.sys.cwd (+ ARGS:{json})" |
| "READ:source | stderr | stdout | slots | skill" |
| "Create tools: CONTINUE PATCH add ##, or CALL:scratch_tool_write with NAME line and fenced body." |
| "" |
Join exactly those lines into _literal_esc_tools_text = [Retain the original newline boundaries](text.str_join(xs=_literal_esc_tools_lines, sep="\n")).
The following record names each literal field without a JSON construction chain.
_literal_esc_fields =
| @ | key | value |
|---|---|---|
| 1 | "a" | "\n\n--- standing ---\n" |
| 2 | "b" | "\n\n--- goal ---\n" |
| 3 | "c" | "\n\n--- observation ---\n" |
| 4 | "d" | "\n\n--- skill brief ---\n" |
| 5 | "e_dec" | _literal_esc_e_dec_text |
| 6 | "e_rev" | _literal_esc_e_rev_text |
| 7 | "f" | "\n\n--- explore ---\n" |
| 8 | "tools" | _literal_esc_tools_text |
We build esc = Collect these named fields into one record.
We retain a = [Read the a field](json.get(value=esc, key="a")).
We retain b = [Read the b field](json.get(value=esc, key="b")).
We retain c = [Read the c field](json.get(value=esc, key="c")).
We retain d = [Read the d field](json.get(value=esc, key="d")).
We retain tools = [Read the tools field](json.get(value=esc, key="tools")).
We retain f = [Read the f field](json.get(value=esc, key="f")).
phase== decompose We retaine= [Read the e_dec field](json.get(value=esc, key="e_dec")). We retain p = "Plan-and-Move: decompose before first run.".-
We retain e = [Read the e_rev field](json.get(value=esc, key="e_rev")).
We retain p = "Plan-and-Move: revise after child run.".
We retain p = p + a + up + b + goal_s + c + obs_s + tools + d + skill + e.
explore_attemptWe retain p = p + f. We retain p = p + "Attempt". We retain p = p + explore_attempt. We retain p = p + "of". We retain p = p + explore_n. We retain p = p + ". Different path; prefer code when fixed.".-
_ = 1 Return p.
plan_llm_act_loop
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| agent | any | required | Agent configuration or receiver created by this package |
| goal | any | required | Human task goal represented by this operation |
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| observation | any | required | Tool observation or workbook result retained for the next turn |
| phase | any | "revise" | Named execution phase |
| explore_attempt | any | None | Current exploration attempt number |
| explore_n | any | None | Maximum configured exploration attempts |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| events | any | required | Ordered semantic or provider stream-event records |
| max_acts | any | 6 | Maximum model/tool actions for this planning loop |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | LLM Plan → CALL/READ/DECISION loop. Returns {decision,reply,observation,events,llm_calls,tokens}. |
Use agent, goal, path, observation, phase="revise", explore_attempt=None, explore_n=None, stream=False, echo=False, events, max_acts=6 as the inputs for this operation.
LLM Plan → CALL/READ/DECISION loop. Returns {decision,reply,observation,events,llm_calls,tokens}.
Each model turn may answer directly, request context, or ask for one allowed parent action. The loop records the resulting observation and rebuilds context before asking again. Its bounded iteration prevents an endless READ or CALL exchange; it does not automatically authorize a tool mentioned by the model. Transport errors and exhausted budgets remain visible to the enclosing planner.
We retain model = [Read the model field](json.get(value=agent, key="model")).
We retain last_obs = observation.
We retain left = max_acts.
We retain decision = None.
We retain last_reply = None.
We retain evs_all = events.
We retain llm_calls = 0.
We retain tokens = 0.
We retain transport_err = None.
left> 0decisionWe retain left = 0.transport_errWe retain left = 0.-
ctx= [Build plan context](build_plan_context(agent=agent, goal=goal, observation=last_obs, explore_attempt=explore_attempt, explore_n=explore_n, phase=phase)). Plan protocol streams asstream_kind=plan(process trail). Answer tokens still come from workbookworker.step stream=True(stream_kind=delta).streamWe retainturn= [Model turn](model_turn(model=model, prompt=ctx, stream=True, echo=echo, stream_kind="plan")).-
We retainWe retain **`turn` = [Model turn](model_turn(model=`model`, prompt=`ctx`, stream=False, echo=`echo`))**.turn_s= Encode the structured value as JSON text. We retainturn_map= [Starts with](text.starts_with(text=turn_s, prefix="{")). We retain terr = None. We retain last_reply = "".- not
turn_mapWe retain transport_err = "model_turn_not_map". We retain left = 0. -
We retain **`terr` = [Read the error field](json.get(value=`turn`, key="error"))**. 1. `terr` We retain **transport_err = `terr`**. We retain **left = 0**. 2. * We retain **`last_reply` = [Read the text field](json.get(value=`turn`, key="text"))**. We retain **`c` = [Read the llm_calls field](json.get(value=`turn`, key="llm_calls"))**. We retain **`t` = [Read the tokens field](json.get(value=`turn`, key="tokens"))**. 1. not `c` We retain **c = 0**. 2. * **_ = 1** 1. not `t` We retain **t = 0**. 2. * **_ = 1** We retain **llm_calls = llm_calls + c**. We retain **tokens = tokens + t**.transport_errWe retain decision = "TRANSPORT_ERROR". We retain last_reply =transport_err. We retain left = 0.-
1. not `last_reply` We retain **last_reply = ""**. 2. * We retain **`last_reply` = [Trim](trim(value=`last_reply`))**. Plan replies often embed CALL: inside PATCH bodies — prefer an explicit DECISION line when present so protocol exit is not stolen by a false CALL. We retain **`dec_line` = [Extract plan decision](extract_plan_decision(reply=`last_reply`))**. We retain **kind = "unknown"**. We retain **name = None**. 1. `dec_line` We retain **kind = "decision"**. We retain **name = `dec_line`**. 2. * We retain **`act` = [Extract plan act](extract_plan_act(reply=`last_reply`))**. We retain **`act_s` = [Encode the structured value as JSON text](json.stringify(value=`act`))**. We retain **`act_map` = [Starts with](text.starts_with(text=`act_s`, prefix="{"))**. 1. `act_map` We retain **`kind` = [Read the kind field](json.get(value=`act`, key="kind"))**. We retain **`name` = [Read the name field](json.get(value=`act`, key="name"))**. 2. * **_ = 1** Live act marker so the UI never goes silent between plan tokens and the next step. 1. `stream` `act_ev` = | type | kind | name | |------|------|------| | plan_act | `kind` | `name` | We **[Stream publish](sys.stream_publish(event=`act_ev`))**. 2. * **_ = 1** 1. `kind` == call We retain **`evs_all` = [Plan append tool](plan_append_tool(events=`evs_all`, type="tool_start", name=`name`, kind="call", stream=`stream`))**. We retain **`tool_out` = [Run parent tool](run_parent_tool(name=`name`, path=`path`, observation=`last_obs`, reply=`last_reply`))**. We retain **`brief` = [Tool result brief](tool_result_brief(value=`tool_out`))**. We retain **`evs_all` = [Plan append tool](plan_append_tool(events=`evs_all`, type="tool_end", name=`name`, kind="call", result=`brief`, stream=`stream`))**. We retain **`obs_s` = [Encode the structured value as JSON text](json.stringify(value=`last_obs`))**. We retain **`obs_map` = [Starts with](text.starts_with(text=`obs_s`, prefix="{"))**. 1. `obs_map` We retain **`last_obs` = [Set the tool_result field in the new record](table.put(in=`last_obs`, at="tool_result", value=`tool_out`))**. 2. * **_ = 1** We retain **left = left - 1**. 2. `kind` == read We retain **`evs_all` = [Plan append tool](plan_append_tool(events=`evs_all`, type="tool_start", name=`name`, kind="read", stream=`stream`))**. We retain **`last_obs` = [Plan read deepen](plan_read_deepen(observation=`last_obs`, kind=`name`, path=`path`))**. We retain **`brief` = [Tool result brief](tool_result_brief(value=`last_obs`))**. We retain **`evs_all` = [Plan append tool](plan_append_tool(events=`evs_all`, type="tool_end", name=`name`, kind="read", result=`brief`, stream=`stream`))**. We retain **left = left - 1**. 3. `kind` == decision We retain **decision = name**. We retain **`evs_all` = [Plan append decision](plan_append_decision(events=`evs_all`, decision=`decision`, stream=`stream`))**. We retain **left = 0**. 4. * We retain **decision = "unknown"**. We retain **left = 0**.
out =
| decision | reply | observation | events | llm_calls | tokens |
|---|---|---|---|---|---|
decision |
last_reply |
last_obs |
evs_all |
llm_calls |
tokens |
transport_errWe retainout= [Set the error field in the new record](table.put(in=out, at="error", value=transport_err)).-
_ = 1 Return out.
plan_echo_decompose
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| workbook | any | required | Workbook path or structured workbook reference |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Pre-run parent decompose marker. With stream=True, publish {type:decompose} so view is not silent before the first child. |
Use workbook, stream=False, echo=False as the inputs for this operation.
Pre-run parent decompose marker. With stream=True, publish {type:decompose} so view is not silent before the first child.
stream
ev =
| type | workbook |
|---|---|
| decompose | workbook |
We Stream publish.
echoWe Print the prepared message.-
**_ = 1**
Return ev. 2. * Return None.
plan_echo_await
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| round | any | required | Current planning round number |
| workbook | any | required | Workbook path or structured workbook reference |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Marker before await_workbook. With stream=True, publish {type:await,round,workbook} so the Stream panel shows progress while the quiet child runs (TTY echo optional). |
Use round, workbook, stream=False, echo=False as the inputs for this operation.
Marker before await_workbook. With stream=True, publish {type:await,round,workbook} so the Stream panel shows progress while the quiet child runs (TTY echo optional).
stream
ev =
| type | round | workbook |
|---|---|---|
| await | round |
workbook |
We Stream publish.
echoWe Print the prepared message. We Print the prepared message.-
**_ = 1**
Return ev. 2. * Return None.
workbook_has_worker_step
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | True when source still contains worker.step or .单步. |
Use path as the inputs for this operation.
True when source still contains worker.step or .单步.
We retain src = Read UTF-8 text from the selected file.
We retain a = [Split](split(value=src, sep="worker.step")).
We retain na = Len.
We retain b = [Split](split(value=src, sep=".单步")).
We retain nb = Len.
na> 1 Return 1.nb> 1 Return 1.-
Return 0.
plan_append_round
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| events | any | required | Ordered semantic or provider stream-event records |
| round | any | required | Current planning round number |
| workbook | any | required | Workbook path or structured workbook reference |
| exit_code | any | required | Child process or tool exit status |
| result | any | None | Structured result from the preceding operation |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Always append a round event (child workbook finished) for audit / view. Optional result is the child # main return. SSE + optional TTY plan:round only when stream / echo. |
Use events, round, workbook, exit_code, result=None, stream=False, echo=False as the inputs for this operation.
Always append a round event (child workbook finished) for audit / view. Optional result is the child # main return. SSE + optional TTY plan:round only when stream / echo.
ev =
| type | round | workbook | exit_code |
|---|---|---|---|
| round | round |
workbook |
exit_code |
resultWe retainev= [Set the result field in the new record](table.put(in=ev, at="result", value=result)).-
_ = 1
We retain events = [Append this item to the new list](table.append(list=events, item=ev)).
streamWe Stream publish.-
_ = 1
echoWe Print the prepared message.-
_ = 1
Return events.
plan_append_decision
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| events | any | required | Ordered semantic or provider stream-event records |
| decision | any | required | Structured planning decision |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| summary | any | None | Summary text or record from the preceding phase |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Always append a decision event. SSE publish only when stream=True. |
Use events, decision, stream=False, summary=None as the inputs for this operation.
Always append a decision event. SSE publish only when stream=True.
ev =
| type | decision |
|---|---|
| decision | decision |
summaryWe retainev= [Set the summary field in the new record](table.put(in=ev, at="summary", value=summary)).-
_ = 1
We retain events = [Append this item to the new list](table.append(list=events, item=ev)).
streamWe Stream publish.-
_ = 1
Return events.
plan_merge_deltas
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| events | any | required | Ordered semantic or provider stream-event records |
| from | any | required | Source value of the transformation |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Bubble parent complete stream=True reasoning/deltas (and errors) into the plan event list. Skip nested done so plan owns the final done. Always merge into events when present; stream reserved for callers that also SSE-publish upstream. |
Use events, from, stream=False as the inputs for this operation.
Bubble parent complete stream=True reasoning/deltas (and errors) into the plan event list. Skip nested done so plan owns the final done. Always merge into events when present; stream reserved for callers that also SSE-publish upstream.
- [ev](遍历
from为ev) We retaint= [Read the type field](json.get(value=ev, key="type")).t== delta We retainevents= [Append this item to the new list](table.append(list=events, item=ev)).t== reasoning We retainevents= [Append this item to the new list](table.append(list=events, item=ev)).t== error We retainevents= [Append this item to the new list](table.append(list=events, item=ev)).-
Return events.
plan_finish_stream
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| out | any | required | Structured output accumulated by the operation |
| events | any | required | Ordered semantic or provider stream-event records |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| trace | any | False | Whether to retain the documented execution trace |
| result | any | None | Structured result from the preceding operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Always append done and attach events on the result map (process audit even when not streaming). SSE publish of done only when stream=True. Optional trace=True writes the event list to writeback slot trace. |
Use out, events, stream=False, trace=False, result=None as the inputs for this operation.
Always append done and attach events on the result map (process audit even when not streaming). SSE publish of done only when stream=True. Optional trace=True writes the event list to writeback slot trace.
We retain ev = [Set the type field in the new record](table.put(in=None, at="type", value="done")).
resultWe retainev= [Set the result field in the new record](table.put(in=ev, at="result", value=result)).-
_ = 1
eventsWe retainevents= [Append this item to the new list](table.append(list=events, item=ev)).-
We retain events = [Append this item to the new list](table.append(list=None, item=ev)).
streamWe Stream publish.-
_ = 1
- not
outWe retainout= Empty map. -
_ = 1
We retain out = [Set the events field in the new record](table.put(in=out, at="events", value=events)).
traceWe retainbody= Encode the structured value as JSON text. We [Record](wb.record(value=body, key="trace")).-
_ = 1
Return out.
agent
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| model | any | required | Model resource or provider model identifier, as required by this operation |
| tools | any | required | Explicit tool whitelist or tool-specification records |
| standing | any | required | Standing instructions supplied by the author |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Load ABI v2 agent plugin once (session bag + context queries). |
Use model, tools, standing as the inputs for this operation.
Load ABI v2 agent plugin once (session bag + context queries).
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent)")). We End this run with the selected exit status.
We retain id = Alloc.
h =
| _type | id | model | tools |
|---|---|---|---|
| agent | id |
model |
tools |
standingWe retainh= [Set the standing field in the new record](table.put(in=h, at="standing", value=standing)).-
_ = 1
Return h.
clear_history
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Clear the plugin session bag for this agent id. |
Clear the plugin session bag for this agent id.
We retain id = [Read the id field](json.get(value=self, key="id")).
We History clear.
Return None.
resolve
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| task | any | required | Structured task or text supplied to the agent |
| kb_dir | any | ".marqdo/agent-kb" | Knowledge-library directory used for discovery and writeback |
| near_match | any | True | Whether to consider near-match candidates |
| near_threshold | any | 0.78 | Minimum similarity score for near-match candidates |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Skill resolver (v2): exact → alias → canonical → near. Returns mode / resource / llm_free / confidence. Plugin ABI — no core host_* calls. |
Use task, kb_dir=".marqdo/agent-kb", near_match=True, near_threshold=0.78 as the inputs for this operation.
Skill resolver (v2): exact → alias → canonical → near. Returns mode / resource / llm_free / confidence. Plugin ABI — no core host_* calls.
We retain tools = [Read the tools field](json.get(value=self, key="tools")).
Return [Resolve](agent_resolve(task=task, kb_dir=kb_dir, near_match=near_match, near_threshold=near_threshold, tools=tools)).
route
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| task | any | required | Structured task or text supplied to the agent |
| backend | any | "auto" | Configured execution or provider backend |
| kb_dir | any | ".marqdo/agent-kb" | Knowledge-library directory used for discovery and writeback |
| memory_dir | any | ".marqdo/agent-memory" | Directory holding learned episodes or policy memory |
| threshold | any | 0.78 | Policy threshold required by this operation |
| step_kind | any | None | Class of workbook step |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Adaptive Routing (Phase 4): abstract router — marqdo | small-llm | llm | auto. jev is accepted as a compat alias of small-llm (not a first-class backend). auto cascades policy → kb → small-llm request. May return needs_llm=True + prompt for the caller to complete with router_model (any llm handle), then route_apply. Optional step_kind= (O3) selects backend via module ## step_route before the ABI call. |
Use task, backend="auto", kb_dir=".marqdo/agent-kb", memory_dir=".marqdo/agent-memory", threshold=0.78, step_kind=None as the inputs for this operation.
Adaptive Routing (Phase 4): abstract router — marqdo | small-llm | llm | auto. jev is accepted as a compat alias of small-llm (not a first-class backend). auto cascades policy → kb → small-llm request. May return needs_llm=True + prompt for the caller to complete with router_model (any llm handle), then route_apply.
Optional step_kind= (O3) selects backend via module ## step_route before the ABI call.
step_kindWe retainsr= Step route. We retainbackend= [Read the backend field](json.get(value=sr, key="backend")).-
_ = 1
We retain tools = [Read the tools field](json.get(value=self, key="tools")).
Return [Route](agent_route(task=task, backend=backend, kb_dir=kb_dir, memory_dir=memory_dir, threshold=threshold, tools=tools)).
route_apply
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| task | any | required | Structured task or text supplied to the agent |
| reply | any | required | Model reply to parse as data; it is not permission to execute arbitrary code |
| kb_dir | any | ".marqdo/agent-kb" | Knowledge-library directory used for discovery and writeback |
| backend | any | "small-llm" | Configured execution or provider backend |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Apply a router model line (SKILL:<slug> / EXPLORE) to a kb skill hit. |
Use task, reply, kb_dir=".marqdo/agent-kb", backend="small-llm" as the inputs for this operation.
Apply a router model line (SKILL:<slug> / EXPLORE) to a kb skill hit.
Return [Route apply](agent_route_apply(task=task, reply=reply, kb_dir=kb_dir, backend=backend)).
compile_policy
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| memory_dir | any | ".marqdo/agent-memory" | Directory holding learned episodes or policy memory |
| min_evidence | any | 3 | Minimum evidence count required before promotion |
| force | any | False | Explicit override supported by this operation; it does not bypass host authorization |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Policy Compilation: stable episode skill selections → policies/router.mq.md (deterministic Marqdo rules). |
Use memory_dir=".marqdo/agent-memory", min_evidence=3, force=False as the inputs for this operation.
Policy Compilation: stable episode skill selections → policies/router.mq.md (deterministic Marqdo rules).
Return [Compile policy](agent_compile_policy(memory_dir=memory_dir, min_evidence=min_evidence, force=force)).
maybe_compile_policy
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| memory_dir | any | ".marqdo/agent-memory" | Directory holding learned episodes or policy memory |
| min_evidence | any | 3 | Minimum evidence count required before promotion |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Learn gate for the Adaptive Router policy layer. |
Use memory_dir=".marqdo/agent-memory", min_evidence=3 as the inputs for this operation.
Learn gate for the Adaptive Router policy layer.
Return [Maybe compile policy](agent_maybe_compile_policy(memory_dir=memory_dir, min_evidence=min_evidence)).
record_episode
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| task | any | required | Structured task or text supplied to the agent |
| status | any | "ok" | Domain status recorded in the structured result |
| result | any | None | Structured result from the preceding operation |
| mode | any | "explore" | Operation mode listed in the function behavior |
| skill | any | "none" | Skill source or identifier selected for inspection |
| observation | any | None | Tool observation or workbook result retained for the next turn |
| workbook | any | None | Workbook path or structured workbook reference |
| cache | any | None | Whether to use the documented result cache |
| match | any | None | Resolved match or match policy |
| llm_calls | any | 0 | Observed model-call count |
| tool_calls | any | 0 | Observed tool-call count |
| error | any | None | Structured failure information supplied by the caller |
| memory_dir | any | ".marqdo/agent-memory" | Directory holding learned episodes or policy memory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Persist one run as .mq.md under memory_dir/episodes/YYYY/MM/ (v2 Phase 1). Memory is executable documentation, not a vector bag. |
Use task, status="ok", result=None, mode="explore", skill="none", observation=None, workbook=None, cache=None, match=None, llm_calls=0, tool_calls=0, error=None, memory_dir=".marqdo/agent-memory" as the inputs for this operation.
Persist one run as .mq.md under memory_dir/episodes/YYYY/MM/ (v2 Phase 1). Memory is executable documentation, not a vector bag.
Return [Record episode](agent_record_episode(task=task, status=status, result=result, mode=mode, skill=skill, observation=observation, workbook=workbook, cache=cache, match=match, llm_calls=llm_calls, tool_calls=tool_calls, error=error, memory_dir=memory_dir)).
quarantine
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| slug | any | required | Knowledge entry identifier within the configured knowledge directory |
| kb_dir | any | ".marqdo/agent-kb" | Knowledge-library directory used for discovery and writeback |
| reason | any | "sandbox_or_harness_failed" | Human-readable explanation for the recorded decision |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | O5: mark OKF skill status: quarantine and force llm_free: false. Regression fixtures stay with the slug. |
Use slug, kb_dir=".marqdo/agent-kb", reason="sandbox_or_harness_failed" as the inputs for this operation.
O5: mark OKF skill status: quarantine and force llm_free: false. Regression fixtures stay with the slug.
Return [Kb quarantine](agent_kb_quarantine(kb_dir=kb_dir, slug=slug, reason=reason)).
maybe_learn
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| task | any | required | Structured task or text supplied to the agent |
| kb_dir | any | ".marqdo/agent-kb" | Knowledge-library directory used for discovery and writeback |
| memory_dir | any | ".marqdo/agent-memory" | Directory holding learned episodes or policy memory |
| improve_every | any | 3 | Number of observations between improvement attempts |
| promote | any | True | Whether successful evidence may be promoted |
| candidate_only | any | False | Whether to retain a candidate without publishing it |
| product_gate_ok | any | True | Result of the external product gate |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Offline learn gate: when ≥ improve_every successful episodes share a task hash, generalize → synthesize → compile → optional OKF promote (llm_free). Also attempts Policy Compilation for Adaptive Routing. O2: promote path requires sandbox proof unless require_proof=false. M04: candidate_only=True or product_gate_ok=False forces promote off via eng_publish_gate. |
Use task, kb_dir=".marqdo/agent-kb", memory_dir=".marqdo/agent-memory", improve_every=3, promote=True, candidate_only=False, product_gate_ok=True as the inputs for this operation.
Offline learn gate: when ≥ improve_every successful episodes share a task hash, generalize → synthesize → compile → optional OKF promote (llm_free). Also attempts Policy Compilation for Adaptive Routing.
O2: promote path requires sandbox proof unless require_proof=false.
M04: candidate_only=True or product_gate_ok=False forces promote off via eng_publish_gate.
We retain gate = [Eng publish gate](> self.eng_publish_gate project="." candidate_only=candidate_only product_gate_ok=product_gate_ok ).
We retain may_prom = [Read the may_promote field](json.get(value=gate, key="may_promote")).
- not
may_promWe retain promote = False. -
_ = 1
We retain skill_learn = [Maybe learn](agent_maybe_learn(task=task, kb_dir=kb_dir, memory_dir=memory_dir, improve_every=improve_every, promote=promote)).
We retain policy_learn = [Maybe compile policy](agent_maybe_compile_policy(memory_dir=memory_dir, min_evidence=improve_every)).
We retain sl = [Read the learned field](json.get(value=skill_learn, key="learned")).
out =
| learned | skill | policy | promote_allowed | gate |
|---|---|---|---|---|
sl |
skill_learn |
policy_learn |
may_prom |
gate |
Return out.
compile
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| task | any | required | Structured task or text supplied to the agent |
| kb_dir | any | ".marqdo/agent-kb" | Knowledge-library directory used for discovery and writeback |
| memory_dir | any | ".marqdo/agent-memory" | Directory holding learned episodes or policy memory |
| min_evidence | any | 3 | Minimum evidence count required before promotion |
| promote | any | True | Whether successful evidence may be promoted |
| force | any | False | Explicit override supported by this operation; it does not bypass host authorization |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Compile a candidate skill into versioned skills/<slug>/vN.mq.md and optionally promote into agent-kb. |
Use task, kb_dir=".marqdo/agent-kb", memory_dir=".marqdo/agent-memory", min_evidence=3, promote=True, force=False as the inputs for this operation.
Compile a candidate skill into versioned skills/<slug>/vN.mq.md and optionally promote into agent-kb.
Return [Compile skill](agent_compile_skill(task=task, kb_dir=kb_dir, memory_dir=memory_dir, min_evidence=min_evidence, promote=promote, force=force)).
metrics
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| memory_dir | any | ".marqdo/agent-memory" | Directory holding learned episodes or policy memory |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Reasoning amortization stats over recorded episodes (avg_llm_calls, compiled_runs, …). |
Use memory_dir=".marqdo/agent-memory" as the inputs for this operation.
Reasoning amortization stats over recorded episodes (avg_llm_calls, compiled_runs, …).
Return Metrics.
run
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| task | any | required | Structured task or text supplied to the agent |
| kb_dir | any | ".marqdo/agent-kb" | Knowledge-library directory used for discovery and writeback |
| memory_dir | any | ".marqdo/agent-memory" | Directory holding learned episodes or policy memory |
| learn | any | True | Whether to record or learn from this operation |
| verify | any | True | Whether to run the documented verifier |
| writeback | any | True | Whether to write the observation back to its author document |
| reuse | any | True | Whether to search for reusable knowledge before new work |
| near_match | any | True | Whether to consider near-match candidates |
| near_threshold | any | 0.78 | Minimum similarity score for near-match candidates |
| promote | any | True | Whether successful evidence may be promoted |
| improve_every | any | 3 | Number of observations between improvement attempts |
| explore_n | any | 3 | Maximum configured exploration attempts |
| max_rounds | any | 4 | Maximum workbook planning rounds |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| trace | any | False | Whether to retain the documented execution trace |
| force | any | False | Explicit override supported by this operation; it does not bypass host authorization |
| router | any | "auto" | Router configuration or route-policy resource |
| router_model | any | None | Model resource used for routing |
| resume_id | any | None | Identifier of the stored continuation checkpoint |
| resume_dir | any | ".marqdo/agent-resume" | Directory holding continuation checkpoints |
| sandbox | any | False | Whether to use the CoW trial path |
| sandbox_profile | any | "default" | Capability profile for CoW execution |
| efi | any | True | Structured effect and failure information |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Primary author entry (v2 + P4): Adaptive route → execute (policy/kb skill) or plan → record episode → maybe_learn (skill + policy). router = auto|marqdo|small-llm|llm (jev→small-llm alias). Optional router_model (llm handle) answers needs_llm prompts — small models welcome. |
Use task, kb_dir=".marqdo/agent-kb", memory_dir=".marqdo/agent-memory", learn=True, verify=True, writeback=True, reuse=True, near_match=True, near_threshold=0.78, promote=True, improve_every=3, explore_n=3, max_rounds=4, stream=False, echo=False, trace=False, force=False, router="auto", router_model=None, resume_id=None, resume_dir=".marqdo/agent-resume", sandbox=False, sandbox_profile="default", efi=True as the inputs for this operation.
Primary author entry (v2 + P4): Adaptive route → execute (policy/kb skill) or plan → record episode → maybe_learn (skill + policy). router = auto|marqdo|small-llm|llm (jev→small-llm alias). Optional router_model (llm handle) answers needs_llm prompts — small models welcome.
sandbox=True (O1 opt-in): workbook paths run via CoW trial before host commit. efi=True (O3): EKC preflight before explore; REUSE short-circuits. Pass efi=False to keep legacy golds that skip eng knowledge.
Use this entry when the application wants the full reuse-and-learning lifecycle. A single conversational turn belongs in step; run first tries existing executable knowledge and can fall back to a workbook plan. The output records which execution mode actually supplied the result, allowing callers to distinguish compiled reuse, router-assisted reuse and exploration instead of inferring that distinction from answer text.
Routing precedes exploration. A matched resource is awaited as a workbook; a failed child does not count as a reusable success. When a route needs a model, the configured routing model, or the agent's normal model, produces the restricted selection reply. Applying that reply resolves it to an actual knowledge resource. Model words alone never stand in for the child's returned value.
Engineering preflight supplies an additional reuse gate. A REUSE result can bind and execute an existing engineering capability; a refusal to create is returned as an error rather than ignored. Missing engineering knowledge is distinguished from a positive refusal. The lower resolver then checks reusable skills, including whether an entry is marked llm_free, before a new plan is requested. Preserve this order when extending the method so new capabilities do not quietly skip existing knowledge.
The workbook await helper owns the execution boundary. With sandbox enabled it uses the configured CoW path; attaching a profile name to an answer is insufficient. Native plugin loading and explicit runtime grants are still required by the selected resource. A successful reused child can therefore avoid parent model calls, while an exploratory result carries the usage reported by its plan.
After execution, the method extracts task status, result, skill and observation for the episode record. Verification here is a recorded execution-status check; it is not an independent domain proof of the answer. Applications with stronger requirements must validate the returned value using their own task-specific assertions. Do not interpret a status string as evidence that files, network writes or generated source were reviewed.
Episodes persist the observed outcome for later reuse decisions. Learning is attempted only for successful outcomes when enabled, and promotion follows the existing evidence path. The result attaches execution details, model usage, routing information and the episode reference. An optional resume identifier also saves a checkpoint and effect-ledger watermark. These records describe what happened; they do not make an uncertain external effect safe to repeat.
For a reproducible investigation, retain the returned workbook reference and observation together. The same goal text can resolve differently after knowledge promotion, so a later rerun of the request is not a substitute for examining the recorded resource.
We retain efi_pf = None.
efiWe retainefi_pf= [Preflight](>self.preflight task=task).-
_ = 1
We retain routed = [Route](> self.route task=task backend=router kb_dir=kb_dir memory_dir=memory_dir threshold=near_threshold ).
We retain route_matched = [Read the matched field](json.get(value=routed, key="matched")).
We retain needs_llm = [Read the needs_llm field](json.get(value=routed, key="needs_llm")).
We retain exec_mode = "explore".
We retain llm_calls = 0.
We retain tokens = 0.
We retain token_cost = 0.
We retain out = None.
We retain route_backend = [Read the backend field](json.get(value=routed, key="backend")).
-
route_matchedWe retainpath= [Read the resource field](json.get(value=routed, key="resource")). -
pathWe retainaw= [Await workbook](await_workbook(path=path, sandbox=sandbox, sandbox_profile=sandbox_profile)). We retaincode= [Read the code field](json.get(value=aw, key="code")). We retainchild_val= [Read the value field](json.get(value=aw, key="value")). We retainlast_obs= [Read the observation field](json.get(value=aw, key="observation")). 1.code== 0 We [Kb record hit](agent_kb_record_hit(kb_dir=kb_dir, goal=task, improve_every=improve_every)). We retainlf= [Read the llm_free field](json.get(value=routed, key="llm_free")).lfWe retain exec_mode = "compiled".-
We retain exec_mode = "routed". We retain
rmode= [Read the mode field](json.get(value=routed, key="mode")). We retainsk= [Read the skill field](json.get(value=routed, key="skill")). **out = **status goal result workbook cache match skill observation summary route ok taskchild_valpathhit rmodesklast_obsadaptive route hit routedWe retain llm_calls = 0.
streamWe retain_ev= Empty list. We retain_ev= [Plan append decision](plan_append_decision(events=_ev, decision="REUSE", stream=True, summary="adaptive route hit")). We retain_ev= [Plan append round](plan_append_round(events=_ev, round=1, workbook=path, exit_code=code, result=child_val, stream=True)).-
_ = 1 2. * We retain route_matched = False.
-
We retain **route_matched = False**.
_ = 1
-
route_matched_ = 1 -
needs_llm -
router_modelWe retainprompt= [Read the prompt field](json.get(value=routed, key="prompt")). We retainturn= [Model turn](model_turn(model=router_model, prompt=prompt, stream=stream, echo=echo)). We retainreply= [Read the text field](json.get(value=turn, key="text")). We retainllm_calls= [Read the llm_calls field](json.get(value=turn, key="llm_calls")). We retaintokens= [Read the tokens field](json.get(value=turn, key="tokens")). We retainapplied= [Route apply](>self.route_apply task=taskreply=replykb_dir=kb_dirbackend=router). We retainam= [Read the matched field](json.get(value=applied, key="matched")). 1.amWe retainpath= [Read the resource field](json.get(value=applied, key="resource")). We retainaw= [Await workbook](await_workbook(path=path, sandbox=sandbox, sandbox_profile=sandbox_profile)). We retaincode= [Read the code field](json.get(value=aw, key="code")). We retainchild_val= [Read the value field](json.get(value=aw, key="value")). We retainlast_obs= [Read the observation field](json.get(value=aw, key="observation")).code== 0 We retain exec_mode = "routed". We retainsk= [Read the skill field](json.get(value=applied, key="skill")). **out = **
status goal result workbook cache match skill observation summary route ok taskchild_valpathsoft-hit routed sklast_obsrouter model selected skill appliedWe retain route_matched = True. 2. * We retain route_matched = False. 2. * We retain route_matched = False.
-
We retain **route_matched = False**.
_ = 1
-
route_matched_ = 1 -
-
efi_pfWe retainefi_st= [Read the status field](json.get(value=efi_pf, key="status")). We retainefi_dec= [Read the decision field](json.get(value=efi_pf, key="decision")). We retainefi_allow= [Read the create_allowed field](json.get(value=efi_pf, key="create_allowed")). 1.efi_st== "missing_knowledge" _ = 1 2.efi_dec== "REUSE" We retainefi_exec= [Eng bind execute](agent_eng_bind_execute(project=".", query=task, policy="pure", candidate_only=False)). We retainefi_ok= [Read the ok field](json.get(value=efi_exec, key="ok")).efi_okWe retain exec_mode = "efi_bound". **out = **
status goal result summary efi reuse_trace ok taskefi_execEFI REUSE bound+executed efi_pfefi_exec_ = 1 3.
efi_dec== "ADAPT" _ = 1 4.efi_allow_ = 1 5. * **out = **status goal error summary efi error taskefi_create_denied EKC preflight denied CREATE efi_pfWe retain exec_mode = "efi".
-
**_ = 1**
out_ = 1-
We retain resolved = [Resolve](> self.resolve task=task kb_dir=kb_dir near_match=near_match near_threshold=near_threshold ).
We retain mode = [Read the mode field](json.get(value=resolved, key="mode")).
We retain llm_free = [Read the llm_free field](json.get(value=resolved, key="llm_free")).
-
not
llm_freeWe retain llm_free = False. -
llm_freeWe retainpath= [Read the resource field](json.get(value=resolved, key="resource")). We retainaw= [Await workbook](await_workbook(path=path, sandbox=sandbox, sandbox_profile=sandbox_profile)). We retaincode= [Read the code field](json.get(value=aw, key="code")). We retainchild_val= [Read the value field](json.get(value=aw, key="value")). We retainlast_obs= [Read the observation field](json.get(value=aw, key="observation")). 1.code== 0 We [Kb record hit](agent_kb_record_hit(kb_dir=kb_dir, goal=task, improve_every=improve_every)). We retain exec_mode = "compiled". We retainsk= [Read the skill field](json.get(value=resolved, key="skill")). **out = **status goal result workbook cache match skill observation summary ok taskchild_valpathhit modesklast_obscompiled skill (llm_free) We retain llm_calls = 0. 2. * We retain
out= [Plan](>self.plan goal=taskkb_dir=kb_dirwriteback=writebackreuse=reusenear_match=near_matchnear_threshold=near_thresholdpromote=promoteimprove_every=improve_everyexplore_n=explore_nmax_rounds=max_roundsstream=streamecho=echotrace=traceforce=force). We retain exec_mode = "explore". We retainllm_calls= [Read the llm_calls field](json.get(value=out, key="llm_calls")). We retaintokens= [Read the tokens field](json.get(value=out, key="tokens")).llm_calls== None We retain llm_calls = 1.tokens== None We retain tokens = 0.
-
We retain **`out` = [Plan](> `self`.plan goal=`task` kb_dir=`kb_dir` writeback=`writeback` reuse=`reuse` near_match=`near_match` near_threshold=`near_threshold` promote=`promote` improve_every=`improve_every` explore_n=`explore_n` max_rounds=`max_rounds` stream=`stream` echo=`echo` trace=`trace` force=`force` )**.
We retain **`cache` = [Read the cache field](json.get(value=`out`, key="cache"))**.
1. `cache` == "hit"
We retain **exec_mode = "compiled"**.
We retain **llm_calls = 0**.
We retain **tokens = 0**.
2. `cache` == "soft-hit"
We retain **exec_mode = "near"**.
We retain **llm_calls = 0**.
We retain **tokens = 0**.
3. *
We retain **exec_mode = "explore"**.
We retain **`llm_calls` = [Read the llm_calls field](json.get(value=`out`, key="llm_calls"))**.
We retain **`tokens` = [Read the tokens field](json.get(value=`out`, key="tokens"))**.
1. `llm_calls` == None
We retain **llm_calls = 1**.
1. `tokens` == None
We retain **tokens = 0**.
We retain st = [Read the status field](json.get(value=out, key="status")).
We retain res = [Read the result field](json.get(value=out, key="result")).
We retain wb_path = [Read the workbook field](json.get(value=out, key="workbook")).
We retain obs = [Read the observation field](json.get(value=out, key="observation")).
We retain sk2 = [Read the skill field](json.get(value=out, key="skill")).
We retain cache2 = [Read the cache field](json.get(value=out, key="cache")).
We retain match2 = [Read the match field](json.get(value=out, key="match")).
We retain err = [Read the error field](json.get(value=out, key="error")).
verifyst== "ok" We retain verification = "status: passed".-
We retain **verification = "status: failed"**.
We retain verification = "status: skipped".
We retain ep = [Record episode](> self.record_episode task=task status=st result=res mode=exec_mode skill=sk2 observation=obs workbook=wb_path cache=cache2 match=match2 llm_calls=llm_calls tokens=tokens error=err memory_dir=memory_dir ).
We retain learning = None.
learnst== "ok" We retainlearning= [Maybe learn](>self.maybe_learn task=taskkb_dir=kb_dirmemory_dir=memory_dirimprove_every=improve_everypromote=promote).-
We retain **learning = None**.
_ = 1
We retain token_cost = tokens. **usage = **
| llm_calls | tokens | token_cost |
|---|---|---|
llm_calls |
tokens |
token_cost |
**execution = **
| mode | llm_calls | tokens | token_cost | skill | router |
|---|---|---|---|---|---|
exec_mode |
llm_calls |
tokens |
token_cost |
sk2 |
route_backend |
We retain out = [Set the execution field in the new record](table.put(in=out, at="execution", value=execution)).
We retain out = [Set the episode field in the new record](table.put(in=out, at="episode", value=ep)).
We retain out = [Set the route field in the new record](table.put(in=out, at="route", value=routed)).
We retain out = [Set the usage field in the new record](table.put(in=out, at="usage", value=usage)).
We retain out = [Set the token_cost field in the new record](table.put(in=out, at="token_cost", value=token_cost)).
learningWe retainout= [Set the learning field in the new record](table.put(in=out, at="learning", value=learning)).-
_ = 1
efi_pfWe retainout= [Set the efi field in the new record](table.put(in=out, at="efi", value=efi_pf)).-
_ = 1
resume_idWe retain_wm= [Effects watermark](effects_watermark(ledger_dir=".marqdo/agent-effects", logical_run_id=resume_id)). We retain_ckpt= [Resume save](resume_save(id=resume_id, goal=task, task=task, status=st, round=1, workbook=wb_path, result=res, route=routed, resume_dir=resume_dir, checkpoint_v2=True, attempt_id="attempt_1", effect_ledger_watermark=_wm)). We retainout= [Set the resume field in the new record](table.put(in=out, at="resume", value=_ckpt)). We retainout= [Set the effect_ledger_watermark field in the new record](table.put(in=out, at="effect_ledger_watermark", value=_wm)).-
_ = 1
Return out.
step
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| task | any | required | Structured task or text supplied to the agent |
| writeback | any | True | Whether to write the observation back to its author document |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| max_reads | any | 2 | Maximum context-deepening reads |
| sandbox | any | False | Whether to use the CoW trial path |
| sandbox_profile | any | "default" | Capability profile for CoW execution |
| resume_id | any | None | Identifier of the stored continuation checkpoint |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | One atomic turn: budgeted context → LLM → optional READ: deepen → optional tool via subtask. Returns a map (status, task, decision, and on success result plus optional tool / tool_result; on failure error). By default (writeback=True) persists that map under named slots ok / error at the call site; pass writeback=False to skip. Optional resume_id scopes EffectLedger idempotency for mutating tools. With stream=True, the model call uses SSE; echo=True prints delta text to stdout as it arrives. The returned map is unchanged (final result string). Context source/skill start at default budget; up to max_reads of READ:source / READ:skill deepen before CALL/answer. |
Use task, writeback=True, stream=False, echo=False, max_reads=2, sandbox=False, sandbox_profile="default", resume_id=None as the inputs for this operation.
One atomic turn: budgeted context → LLM → optional READ: deepen → optional tool via subtask. Returns a map (status, task, decision, and on success result plus optional tool / tool_result; on failure error). By default (writeback=True) persists that map under named slots ok / error at the call site; pass writeback=False to skip.
Optional resume_id scopes EffectLedger idempotency for mutating tools.
With stream=True, the model call uses SSE; echo=True prints delta text to stdout as it arrives. The returned map is unchanged (final result string). Context source/skill start at default budget; up to max_reads of READ:source / READ:skill deepen before CALL/answer.
sandbox=True (O1 opt-in): attach the sandbox profile row on the result map (trial via ## trial / run sandbox=).
We retain id = [Read the id field](json.get(value=self, key="id")).
We retain model = [Read the model field](json.get(value=self, key="model")).
We retain tools = [Read the tools field](json.get(value=self, key="tools")).
user_turn =
| role | content |
|---|---|
| user | task |
We [Append this item to the new list](agent_history_append(id=id, item=user_turn)).
We retain source_depth = "default". We retain skill_depth = "default". We retain reads_left = max_reads. We retain reply = None. We retain decision = None. We retain llm_calls = 0. We retain tokens = 0.
We retain transport_err = None.
reads_left> 0decisionWe retain reads_left = 0.transport_errWe retain reads_left = 0.-
ctx= [Build step context](build_step_context(agent=self, task=task, source_depth=source_depth, skill_depth=skill_depth)). We retainturn= [Model turn](model_turn(model=model, prompt=ctx, stream=stream, echo=echo)). We retainterr= [Read the error field](json.get(value=turn, key="error")).terrWe retain transport_err =terr. We retain reads_left = 0.-
We retain **`reply` = [Read the text field](json.get(value=`turn`, key="text"))**. We retain **`c` = [Read the llm_calls field](json.get(value=`turn`, key="llm_calls"))**. We retain **`t` = [Read the tokens field](json.get(value=`turn`, key="tokens"))**. 1. not `c` We retain **c = 0**. 2. * **_ = 1** 1. not `t` We retain **t = 0**. 2. * **_ = 1** We retain **llm_calls = llm_calls + c**. We retain **tokens = tokens + t**. We retain **`reply` = [Trim](trim(value=`reply`))**. We retain **`rk` = [Extract plan read](extract_plan_read(reply=`reply`))**. 1. `rk` == source We retain **source_depth = "deep"**. We retain **reads_left = reads_left - 1**. 2. `rk` == skill We retain **skill_depth = "deep"**. We retain **reads_left = reads_left - 1**. 3. * We retain **decision = reply**. We retain **reads_left = 0**.
transport_err
out =
| status | task | error | llm_calls | tokens |
|---|---|---|---|---|
| error | task |
transport_err |
llm_calls |
tokens |
writebackWe retainbody= Encode the structured value as JSON text. We [Record](wb.record(value=body, key="error")).-
**_ = 1**
Return out. 2. * _ = 1
We retain reply = Trim.
We retain decision = reply.
We retain tool_name = Extract tool name.
out =
| status | task | decision |
|---|---|---|
| ok | task |
decision |
tool_nameWe retaintool_out= [Run tool](run_tool(tools=tools, name=tool_name, logical_run_id=resume_id)). We retaintool_s= Encode the structured value as JSON text. We retaindeny= [Split](split(value=tool_s, sep="Tool not allowed")). We retaindeny_n= Len.deny_n> 1 We retaintask_s= Encode the structured value as JSON text. We retain fp = "Tool CALL was rejected (not on the tools whitelist). Do NOT emit CALL. Answer the user task directly with the final answer only.\n\nUser task:\n". We retain fp = fp + task_s. We retainturn2= [Model turn](model_turn(model=model, prompt=fp, stream=stream, echo=echo)). We retainreply= [Read the text field](json.get(value=turn2, key="text")). We retainc= [Read the llm_calls field](json.get(value=turn2, key="llm_calls")). We retaint= [Read the tokens field](json.get(value=turn2, key="tokens")). 1. notcWe retain c = 0. 2. * _ = 1 1. nottWe retain t = 0. 2. * _ = 1 We retain llm_calls = llm_calls + c. We retain tokens = tokens + t. We retainout= [Set the denied_tool field in the new record](table.put(in=out, at="denied_tool", value=tool_name)). We retainout= [Set the result field in the new record](table.put(in=out, at="result", value=reply)).-
We retain **`task_s` = [Encode the structured value as JSON text](json.stringify(value=`task`))**.
We retain **fp = "The user asked:"**.
We retain **fp = fp + task_s**.
We retain **fp = fp + ". Tool"**.
We retain **fp = fp + tool_name**.
We retain **fp = fp + "ran via subtask and returned:"**.
We retain **fp = fp + tool_s**.
We retain **fp = fp + ". Reply to the user briefly."**.
We retain **`turn2` = [Model turn](model_turn(model=`model`, prompt=`fp`, stream=`stream`, echo=`echo`))**.
We retain **`reply` = [Read the text field](json.get(value=`turn2`, key="text"))**.
We retain **`c` = [Read the llm_calls field](json.get(value=`turn2`, key="llm_calls"))**.
We retain **`t` = [Read the tokens field](json.get(value=`turn2`, key="tokens"))**.
1. not `c`
We retain **c = 0**.
2. *
**_ = 1**
1. not `t`
We retain **t = 0**.
2. *
**_ = 1**
We retain **llm_calls = llm_calls + c**.
We retain **tokens = tokens + t**.
We retain **`out` = [Set the tool field in the new record](table.put(in=`out`, at="tool", value=`tool_name`))**.
We retain **`out` = [Set the tool_result field in the new record](table.put(in=`out`, at="tool_result", value=`tool_s`))**.
We retain **`out` = [Set the result field in the new record](table.put(in=`out`, at="result", value=`reply`))**.
We retain out = [Set the result field in the new record](table.put(in=out, at="result", value=reply)).
We retain out = [Set the llm_calls field in the new record](table.put(in=out, at="llm_calls", value=llm_calls)).
We retain out = [Set the tokens field in the new record](table.put(in=out, at="tokens", value=tokens)).
sandboxWe retainprof= Profile. We retainout= [Set the sandbox_profile field in the new record](table.put(in=out, at="sandbox_profile", value=prof)).-
_ = 1
as_turn =
| role | content |
|---|---|
| assistant | reply |
We [Append this item to the new list](agent_history_append(id=id, item=as_turn)).
writebackWe retainbody= Encode the structured value as JSON text. We retainst= [Read the status field](json.get(value=out, key="status")).st== "ok" We [Record](wb.record(value=body, key="ok")).-
We **[Record](wb.record(value=`body`, key="error"))**.
_ = 1
Return out.
preflight
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| task | any | required | Structured task or text supplied to the agent |
| root | any | "." | Explicit root directory for discovery or isolated execution |
| marqdo_dir | any | None | Marqdo project directory used for engineering discovery |
| min_candidates | any | 3 | Minimum reusable candidates to seek before adaptation |
| allow_create_after | any | 2 | Number of bounded attempts before new work may be proposed |
| reuse_threshold | any | 0.72 | Score required to choose reuse |
| adapt_threshold | any | 0.45 | Score required to choose adaptation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Engineering First Information gate (008 / EKC). Reads compiled .marqdo knowledge. Returns {status,decision,create_allowed,existing,constraints,decisions,failures,recommended,context_path}. Hard rule: generate only when create_allowed is true (or decision is REUSE/ADAPT). |
Use task, root=".", marqdo_dir=None, min_candidates=3, allow_create_after=2, reuse_threshold=0.72, adapt_threshold=0.45 as the inputs for this operation.
Engineering First Information gate (008 / EKC). Reads compiled .marqdo knowledge.
Returns {status,decision,create_allowed,existing,constraints,decisions,failures,recommended,context_path}.
Hard rule: generate only when create_allowed is true (or decision is REUSE/ADAPT).
marqdo_dirWe retainpf= [Eng preflight](agent_eng_preflight(task=task, root=root, marqdo_dir=marqdo_dir, min_candidates=min_candidates, allow_create_after=allow_create_after, reuse_threshold=reuse_threshold, adapt_threshold=adapt_threshold)).-
We retain pf = [Eng preflight](agent_eng_preflight(task=task, root=root, min_candidates=min_candidates, allow_create_after=allow_create_after, reuse_threshold=reuse_threshold, adapt_threshold=adapt_threshold)).
Return pf.
eng_reuse
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| task | any | required | Structured task or text supplied to the agent |
| root | any | "." | Explicit root directory for discovery or isolated execution |
| marqdo_dir | any | None | Marqdo project directory used for engineering discovery |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Alias of preflight focused on REUSE / ADAPT / CREATE payload (discovery_only). |
Use task, root=".", marqdo_dir=None as the inputs for this operation.
Alias of preflight focused on REUSE / ADAPT / CREATE payload (discovery_only).
marqdo_dirReturn [Eng reuse](agent_eng_reuse(task=task, root=root, marqdo_dir=marqdo_dir)).-
Return [Eng reuse](agent_eng_reuse(task=task, root=root)).
eng_bind_execute
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| project | any | "." | Project root or project metadata |
| query | any | required | Text used to search the bounded catalog or tool registry |
| policy | any | "pure" | Policy data governing this operation |
| inputs | any | None | Structured input record for the bound engineering capability |
| candidate_only | any | False | Whether to retain a candidate without publishing it |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | M04: discover → bind → execute → record. Prefer over treating eng_reuse scores as execution. |
Use project=".", query, policy="pure", inputs=None, candidate_only=False as the inputs for this operation.
M04: discover → bind → execute → record. Prefer over treating eng_reuse scores as execution.
inputsReturn [Eng bind execute](agent_eng_bind_execute(project=project, query=query, policy=policy, inputs=inputs, candidate_only=candidate_only)).-
Return [Eng bind execute](agent_eng_bind_execute(project=project, query=query, policy=policy, candidate_only=candidate_only)).
eng_publish_gate
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| project | any | "." | Project root or project metadata |
| artifact_id | any | None | Resolved artifact identifier from the compiler/catalog |
| candidate_only | any | False | Whether to retain a candidate without publishing it |
| product_gate_ok | any | True | Result of the external product gate |
| policy | any | "business" | Policy data governing this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Refuse promote when candidate_only or product/verification gate fails. |
Use project=".", artifact_id=None, candidate_only=False, product_gate_ok=True, policy="business" as the inputs for this operation.
Refuse promote when candidate_only or product/verification gate fails.
Return [Eng publish gate](agent_eng_publish_gate(project=project, artifact_id=artifact_id, candidate_only=candidate_only, product_gate_ok=product_gate_ok, policy=policy)).
eng_record
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| decision | any | required | Structured planning decision |
| root | any | "." | Explicit root directory for discovery or isolated execution |
| marqdo_dir | any | None | Marqdo project directory used for engineering discovery |
| duplicated | any | False | Whether a duplicate capability was detected |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Record REUSE/ADAPT/CREATE into .marqdo/agent/episodes/reuse_metrics.json. |
Use decision, root=".", marqdo_dir=None, duplicated=False as the inputs for this operation.
Record REUSE/ADAPT/CREATE into .marqdo/agent/episodes/reuse_metrics.json.
marqdo_dirReturn [Eng record](agent_eng_record(decision=decision, root=root, marqdo_dir=marqdo_dir, duplicated=duplicated)).-
Return [Eng record](agent_eng_record(decision=decision, root=root, duplicated=duplicated)).
plan
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| goal | any | required | Human task goal represented by this operation |
| workbook_dir | any | None | Directory in which the planner owns its workbook files |
| workbook | any | None | Workbook path or structured workbook reference |
| max_rounds | any | 4 | Maximum workbook planning rounds |
| confirm | any | False | Whether decomposition confirmation is requested |
| writeback | any | True | Whether to write the observation back to its author document |
| skeleton | any | "single" | Workbook source template to instantiate |
| reuse | any | True | Whether to search for reusable knowledge before new work |
| optimize | any | False | Whether to run the documented improvement path |
| force | any | False | Explicit override supported by this operation; it does not bypass host authorization |
| soft_match | any | False | Whether bounded soft matching is enabled |
| near_match | any | True | Whether to consider near-match candidates |
| near_threshold | any | 0.78 | Minimum similarity score for near-match candidates |
| promote | any | True | Whether successful evidence may be promoted |
| kb_dir | any | ".marqdo/agent-kb" | Knowledge-library directory used for discovery and writeback |
| improve_every | any | 3 | Number of observations between improvement attempts |
| explore_n | any | 3 | Maximum configured exploration attempts |
| stream | any | False | Whether to preserve streaming behavior or emit stream events |
| echo | any | False | Whether to print the documented incremental output |
| trace | any | False | Whether to retain the documented execution trace |
| resume_id | any | None | Identifier of the stored continuation checkpoint |
| resume_dir | any | ".marqdo/agent-resume" | Directory holding continuation checkpoints |
| eng_preflight | any | False | Whether to run engineering reuse preflight |
| marqdo_dir | any | ".marqdo" | Marqdo project directory used for engineering discovery |
| allow_create_after | any | 2 | Number of bounded attempts before new work may be proposed |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Multi-step with OKF agent-kb. Default workbook is kb_dir/resources/<slug>.mq.md. While task file count < explore_n and skill is not llm_free, force a new explore variant under kb_dir/explore/<slug>/. Code-first: llm_free hits skip parent LLM. File children return via # main; plan exposes that as result. Engineering Knowledge preflight when eng_preflight=True: REUSE/ADAPT preferred; CREATE only if create_allowed. Production agents should enable this; tests that only exercise agent-kb may leave it false. Reuse lookup: exact → alias → canonicalize → optional local n-gram near when near_match=True and score ≥ near_threshold. Non-hit path: optional soft_match=True parent REUSE/NEW over ranked agent_kb_near_match candidates; else decompose before first child spawn (DECISION: RUN / CONTINUE+patch / solidified DONE). Then await → revise loop. Process events (decision / round / done / tools) are always attached on the result map for audit and view process cards; stream=True additionally SSE-publishes them (and parent delta). echo=True prints plan:decompose / plan:await / deltas. trace=True writes events to writeback slot trace. Quiet child subtasks stay quiet. |
Use goal, workbook_dir=None, workbook=None, max_rounds=4, confirm=False, writeback=True, skeleton="single", reuse=True, optimize=False, force=False, soft_match=False, near_match=True, near_threshold=0.78, promote=True, kb_dir=".marqdo/agent-kb", improve_every=3, explore_n=3, stream=False, echo=False, trace=False, resume_id=None, resume_dir=".marqdo/agent-resume", eng_preflight=False, marqdo_dir=".marqdo", allow_create_after=2 as the inputs for this operation.
Multi-step with OKF agent-kb. Default workbook is kb_dir/resources/<slug>.mq.md. While task file count < explore_n and skill is not llm_free, force a new explore variant under kb_dir/explore/<slug>/. Code-first: llm_free hits skip parent LLM. File children return via # main; plan exposes that as result.
Engineering Knowledge preflight when eng_preflight=True: REUSE/ADAPT preferred; CREATE only if create_allowed. Production agents should enable this; tests that only exercise agent-kb may leave it false.
Reuse lookup: exact → alias → canonicalize → optional local n-gram near when near_match=True and score ≥ near_threshold. Non-hit path: optional soft_match=True parent REUSE/NEW over ranked agent_kb_near_match candidates; else decompose before first child spawn (DECISION: RUN / CONTINUE+patch / solidified DONE). Then await → revise loop. Process events (decision / round / done / tools) are always attached on the result map for audit and view process cards; stream=True additionally SSE-publishes them (and parent delta). echo=True prints plan:decompose / plan:await / deltas. trace=True writes events to writeback slot trace. Quiet child subtasks stay quiet.
This method coordinates a workbook lifecycle. The workbook is an ordinary executable document with a main entry, not a private planner data format. The parent proposes decisions and short repairs; the runtime writes or awaits source, captures an observation and returns the child's actual value. Choose this method when reuse and a bounded revise loop are appropriate. Choose step for a single model turn with an optional tool.
The first gate can consult engineering knowledge. REUSE and ADAPT are recorded as such; creating new work requires the configured create decision. A missing knowledge store is a separate state from an explicit denial. This gate does not manufacture a candidate merely to satisfy a minimum count. Callers should retain its diagnostics when deciding whether their project has enough reusable context.
Knowledge lookup then establishes the resource and cache state. Exact, alias and canonical matches are tried before optional near matches. A similarity threshold filters candidates but does not prove semantic equivalence. An llm_free resource can execute through the existing code path without a parent model. The returned cache, match and resource fields let the application explain which path was chosen and inspect the source that ran.
Exploration uses owned workbook files. With no explicit workbook path, the configured knowledge directory supplies the resource location; bounded variants live under its exploration subtree. The exploration count controls attempts to establish useful reusable evidence. It should not be confused with the maximum revision rounds of one workbook. Keep both directory ownership and attempt accounting intact when changing the planner.
An optional soft-match turn compares existing candidates and produces either REUSE with a concrete slug or NEW. The reply is parsed and resolved before execution. It cannot authorize an invented slug or silently replace a failed child with model prose. When reuse does not yield a result, the chosen single-worker or dual-worker template provides a starting document, with the goal embedded as quoted data.
Before the first child execution, decomposition asks whether that starting document is sufficient. RUN accepts the structure. CONTINUE supplies a bounded source patch, and evidence requests go through the restricted parent tool dispatcher. DONE belongs to the existing solidification path and must have a usable value. Rewriting already valid imports is not itself progress toward the user's goal.
Child execution is awaited before revision. The observation contains process status, returned value, slots and bounded output; the parent prompt uses a compact projection so large logs do not drown out the next repair. If the child fails or its value is unsuitable, a short patch can be applied and another round attempted. Exhausting the round budget is reported by the result path, rather than hidden behind a fabricated successful answer.
The confirm option concerns the decomposition stage; it is not a substitute for host permissions. File creation, source patches, subprocess execution and model transport retain their own effect boundaries. Quiet subtasks remain quiet. Turning on echo changes incremental terminal output, while stream publishes process events. Neither option changes the requirement to inspect the final structured result.
Events are retained for audit even when streaming is disabled. Decisions, rounds and completion events describe the work that actually ran. Trace writeback is separately controlled, and normal writeback stores the result at its source call site. Consumers should use these fields to diagnose a plan instead of scraping console messages or assuming every emitted event represents a completed child.
Successful outcomes may be promoted through the knowledge mechanism when enabled. Promotion preserves the workbook as inspectable source and uses the configured evidence process; generating a file alone is not compilation into a trusted skill. Optimization and force options select existing improvement behavior, while the regular reuse gates remain visible in the outcome. A later author can open the resulting resource and reproduce its invocation.
With a resume identifier, checkpoint records connect the goal, round, workbook and result to a logical run. The checkpoint is continuation data, not a replay authorization for uncertain external writes. Tools with effects still use their own ledger and reconciliation rules. Preserve these references when integrating a scheduler or another application so continuation does not duplicate work that already committed.
We retain tools = [Read the tools field](json.get(value=self, key="tools")).
We retain cache = "miss".
We retain path = None.
We retain improve = None.
We retain explore = None.
We retain explore_attempt = None.
We retain skel_kind = skeleton.
We retain events = Empty list.
We retain eng = None.
eng_preflightWe retaineng= [Eng preflight](agent_eng_preflight(task=goal, marqdo_dir=marqdo_dir, allow_create_after=allow_create_after)). We retaineng_status= [Read the status field](json.get(value=eng, key="status")). We retaineng_decision= [Read the decision field](json.get(value=eng, key="decision")). We retaineng_allowed= [Read the create_allowed field](json.get(value=eng, key="create_allowed")).eng_status== missing_knowledge _ = 1eng_decision== REUSE We [Eng record](agent_eng_record(decision="REUSE", marqdo_dir=marqdo_dir)). _ = 1eng_decision== ADAPT We [Eng record](agent_eng_record(decision="ADAPT", marqdo_dir=marqdo_dir)). _ = 1eng_allowedWe [Eng record](agent_eng_record(decision="CREATE", marqdo_dir=marqdo_dir)). _ = 1-
`out` =
| status | cache | eng | decision | preflight | events |
|--------|-------|-----|----------|-----------|--------|
| blocked | eng-block | true | BLOCKED | `eng` | `events` |
Return *out*.
_ = 1
We retain tf = [Kb task files](agent_kb_task_files(kb_dir=kb_dir, goal=goal, tools=tools)).
We retain nfiles = [Read the count field](json.get(value=tf, key="count")).
-
force_ = 1 -
optimize_ = 1 -
reuseWe retainhit= [Kb lookup](agent_kb_lookup(kb_dir=kb_dir, goal=goal, tools=tools, near_match=near_match, near_threshold=near_threshold)). -
hitWe retainmatch_kind= [Read the match field](json.get(value=hit, key="match")). 1.match_kind== alias We retain cache_label = "soft-hit". 2.match_kind== canonical We retain cache_label = "soft-hit". We retainhit_slug= [Read the slug field](json.get(value=hit, key="slug")). We [Kb add alias](agent_kb_add_alias(kb_dir=kb_dir, slug=hit_slug, alias=goal)). 3.match_kind== near We retain cache_label = "soft-hit". We retainhit_slug= [Read the slug field](json.get(value=hit, key="slug")). We [Kb add alias](agent_kb_add_alias(kb_dir=kb_dir, slug=hit_slug, alias=goal)). 4.match_kind== soft We retain cache_label = "soft-hit". 5. * We retain cache_label = "hit". We retainlf= [Read the llm_free field](json.get(value=hit, key="llm_free")). 1.lfWe retainpath= [Read the resource field](json.get(value=hit, key="resource")). We retainaw= Await workbook. We retaincode= [Read the code field](json.get(value=aw, key="code")). We retainchild_val= [Read the value field](json.get(value=aw, key="value")). We retainlast_obs= [Read the observation field](json.get(value=aw, key="observation")).code== 0 We [Kb record hit](agent_kb_record_hit(kb_dir=kb_dir, goal=goal, tools=tools, improve_every=improve_every)). We retain cache = cache_label. We retainhit_score= [Read the score field](json.get(value=hit, key="score")). We retainsk= [Read the skill field](json.get(value=hit, key="skill")). We retainst= [Read the status field](json.get(value=hit, key="status")). The following record names each literal field without a JSON construction chain.
_literal_sum_fields=@ key value 1 "a" "OKF llm_free skill hit (" 2 "b" "); spawned resource" We build sum = Collect these named fields into one record.
We retain
suma= [Read the a field](json.get(value=sum, key="a")). We retainsumb= [Read the b field](json.get(value=sum, key="b")). We retain sum = suma + match_kind + sumb.out=status goal workbook rounds cache match skill skill_status summary observation result ok goalpath1 cache_labelmatch_kindskstsumlast_obschild_valhit_scoreWe retainout= [Set the score field in the new record](table.put(in=out, at="score", value=hit_score)).-
**_ = 1**We retain
events= [Plan append decision](plan_append_decision(events=events, decision="REUSE", stream=stream, summary=sum)). We retainevents= [Plan append round](plan_append_round(events=events, round=1, workbook=path, exit_code=code, result=child_val, stream=stream, echo=echo)).writebackWe retainbody= Encode the structured value as JSON text. We [Record](wb.record(value=body, key="ok")).-
**_ = 1**We retain
out= [Plan finish stream](plan_finish_stream(out=out, events=events, stream=stream, trace=trace, result=child_val)). Return out. 2. * We retain path = None. 2.nfiles<explore_nWe retain explore = 1. We retain cache = "explore". We retain path = None. We retain explore_attempt = nfiles + 1.explore_attempt== 2 We retain skel_kind = "dual".-
We retain skel_kind = skeleton. 3. * We retain
path= [Read the resource field](json.get(value=hit, key="resource")). We retainaw= Await workbook. We retaincode= [Read the code field](json.get(value=aw, key="code")). We retainchild_val= [Read the value field](json.get(value=aw, key="value")). We retainlast_obs= [Read the observation field](json.get(value=aw, key="observation")).code== 0 We retainrec= [Kb record hit](agent_kb_record_hit(kb_dir=kb_dir, goal=goal, tools=tools, improve_every=improve_every)). We retaindue= [Read the improve_due field](json.get(value=rec, key="improve_due")).dueWe retain improve = 1. We retain cache = "improve".-
We retain **cache = cache_label**. We retain **`hit_score` = [Read the score field](json.get(value=`hit`, key="score"))**. We retain **`sk` = [Read the skill field](json.get(value=`hit`, key="skill"))**. We retain **`st` = [Read the status field](json.get(value=`hit`, key="status"))**. The following record names each literal field without a JSON construction chain. `_literal_sum_fields` = | @ | key | value | |---|---|---| | 1 | "a" | "OKF skill hit (" | | 2 | "b" | "); spawned resource" | We build **sum = [Collect these named fields into one record](table.from_pairs(pairs=`_literal_sum_fields`))**. We retain **`suma` = [Read the a field](json.get(value=`sum`, key="a"))**. We retain **`sumb` = [Read the b field](json.get(value=`sum`, key="b"))**. We retain **sum = suma + match_kind + sumb**. `out` = | status | goal | workbook | rounds | cache | match | skill | skill_status | summary | observation | result | |--------|------|----------|--------|-------|-------|-------|--------------|---------|-------------|--------| | ok | `goal` | `path` | 1 | `cache_label` | `match_kind` | `sk` | `st` | `sum` | `last_obs` | `child_val` | 1. `hit_score` We retain **`out` = [Set the score field in the new record](table.put(in=`out`, at="score", value=`hit_score`))**. 2. * **_ = 1** We retain **`events` = [Plan append decision](plan_append_decision(events=`events`, decision="REUSE", stream=`stream`, summary=`sum`))**. We retain **`events` = [Plan append round](plan_append_round(events=`events`, round=1, workbook=`path`, exit_code=`code`, result=`child_val`, stream=`stream`, echo=`echo`))**. 1. `writeback` We retain **`body` = [Encode the structured value as JSON text](json.stringify(value=`out`))**. We **[Record](wb.record(value=`body`, key="ok"))**. 2. * **_ = 1** We retain **`out` = [Plan finish stream](plan_finish_stream(out=`out`, events=`events`, stream=`stream`, trace=`trace`, result=`child_val`))**. Return *out*.We retain path = None.
-
1. `soft_match`
We retain **`near` = [Kb near match](agent_kb_near_match(kb_dir=`kb_dir`, goal=`goal`))**.
We retain **`tasks` = [Read the candidates field](json.get(value=`near`, key="candidates"))**.
We retain **`tn` = [Len](len(value=`tasks`))**.
1. `tn` < 1
We retain **`listed` = [Kb list tasks](agent_kb_list_tasks(kb_dir=`kb_dir`))**.
We retain **`tasks` = [Read the tasks field](json.get(value=`listed`, key="tasks"))**.
We retain **`tn` = [Len](len(value=`tasks`))**.
2. *
**_ = 1**
1. `tn` > 0
We retain **`soft_prompt` = [Build soft match prompt](build_soft_match_prompt(goal=`goal`, tasks=`tasks`))**.
We retain **`model` = [Read the model field](json.get(value=`self`, key="model"))**.
1. `stream`
We retain **`evs` = [Stream](model.stream(prompt=`soft_prompt`, echo=`echo`))**.
We retain **`soft_reply` = [Collect](llm.collect(events=`evs`))**.
We retain **`events` = [Plan merge deltas](plan_merge_deltas(events=`events`, from=`evs`, stream=`stream`))**.
2. *
We retain **`soft_turn` = [Model turn](model_turn(model=`model`, prompt=`soft_prompt`, stream=False, echo=`echo`))**.
We retain **`soft_reply` = [Read the text field](json.get(value=`soft_turn`, key="text"))**.
We retain **`soft_reply` = [Trim](trim(value=`soft_reply`))**.
We retain **`soft_dec` = [Extract plan decision](extract_plan_decision(reply=`soft_reply`))**.
We retain **`events` = [Plan append decision](plan_append_decision(events=`events`, decision=`soft_dec`, stream=`stream`))**.
1. `soft_dec` == REUSE
We retain **`reuse_slug` = [Extract soft match slug](extract_soft_match_slug(reply=`soft_reply`))**.
1. `reuse_slug`
We retain **`hit` = [Kb lookup](agent_kb_lookup(kb_dir=`kb_dir`, slug=`reuse_slug`, goal=`goal`, tools=`tools`))**.
1. `hit`
We **[Kb add alias](agent_kb_add_alias(kb_dir=`kb_dir`, slug=`reuse_slug`, alias=`goal`))**.
We retain **cache_label = "soft-hit"**.
We retain **`path` = [Read the resource field](json.get(value=`hit`, key="resource"))**.
We retain **`aw` = [Await workbook](await_workbook(path=`path`))**.
We retain **`code` = [Read the code field](json.get(value=`aw`, key="code"))**.
We retain **`child_val` = [Read the value field](json.get(value=`aw`, key="value"))**.
We retain **`last_obs` = [Read the observation field](json.get(value=`aw`, key="observation"))**.
1. `code` == 0
We **[Kb record hit](agent_kb_record_hit(kb_dir=`kb_dir`, goal=`goal`, tools=`tools`, improve_every=`improve_every`))**.
We retain **cache = "soft-hit"**.
We retain **`sk` = [Read the skill field](json.get(value=`hit`, key="skill"))**.
We retain **`st` = [Read the status field](json.get(value=`hit`, key="status"))**.
We retain **sum = "OKF soft_match REUSE; spawned resource"**.
`out` =
| status | goal | workbook | rounds | cache | match | skill | skill_status | summary | observation | result |
|--------|------|----------|--------|-------|-------|-------|--------------|---------|-------------|--------|
| ok | `goal` | `path` | 1 | soft-hit | soft | `sk` | `st` | `sum` | `last_obs` | `child_val` |
We retain **`events` = [Plan append decision](plan_append_decision(events=`events`, decision="REUSE", stream=`stream`, summary=`sum`))**.
We retain **`events` = [Plan append round](plan_append_round(events=`events`, round=1, workbook=`path`, exit_code=`code`, result=`child_val`, stream=`stream`, echo=`echo`))**.
1. `writeback`
We retain **`body` = [Encode the structured value as JSON text](json.stringify(value=`out`))**.
We **[Record](wb.record(value=`body`, key="ok"))**.
2. *
**_ = 1**
We retain **`out` = [Plan finish stream](plan_finish_stream(out=`out`, events=`events`, stream=`stream`, trace=`trace`, result=`child_val`))**.
Return *out*.
2. *
We retain **path = None**.
2. *
**_ = 1**
2. *
**_ = 1**
2. *
**_ = 1**
2. *
**_ = 1**
2. *
**_ = 1**
1. `nfiles` < `explore_n`
We retain **explore = 1**.
We retain **cache = "explore"**.
We retain **explore_attempt = nfiles + 1**.
1. `explore_attempt` == 2
We retain **skel_kind = "dual"**.
2. *
We retain **skel_kind = skeleton**.
2. *
**_ = 1**
-
nfiles<explore_nWe retain explore = 1. We retain cache = "explore". We retain explore_attempt = nfiles + 1.-
**_ = 1**
We retain skel = [Render workbook skeleton](render_workbook_skeleton(goal=goal, skeleton=skel_kind)).
workbookWe retain path = workbook. We retainex= Exists.ex_ = 1-
We **[Write the prepared text to the selected file](fs.write_text(path=`path`, text=`skel`))**.
-
path_ = 1-
We retain **`slug` = [Goal slug](agent_goal_slug(goal=`goal`))**.
1. `workbook_dir`
We **[Make dir](fs.make_dir(path=`workbook_dir`))**.
We retain **`ts` = [Now ms](time.now_ms())**.
The following record names each literal field without a JSON construction chain.
`_literal_parts_fields` =
| @ | key | value |
|---|---|---|
| 1 | "a" | "/workbook-" |
| 2 | "b" | "-" |
| 3 | "c" | ".mq.md" |
We build **parts = [Collect these named fields into one record](table.from_pairs(pairs=`_literal_parts_fields`))**.
We retain **`a` = [Read the a field](json.get(value=`parts`, key="a"))**.
We retain **`b` = [Read the b field](json.get(value=`parts`, key="b"))**.
We retain **`c` = [Read the c field](json.get(value=`parts`, key="c"))**.
We retain **path = workbook_dir + a + slug + b + ts + c**.
We **[Write the prepared text to the selected file](fs.write_text(path=`path`, text=`skel`))**.
2. `explore`
The following record names each literal field without a JSON construction chain.
`_literal_parts_fields` =
| @ | key | value |
|---|---|---|
| 1 | "a" | "/explore/" |
| 2 | "b" | "/" |
| 3 | "c" | ".mq.md" |
We build **parts = [Collect these named fields into one record](table.from_pairs(pairs=`_literal_parts_fields`))**.
We retain **`a` = [Read the a field](json.get(value=`parts`, key="a"))**.
We retain **`b` = [Read the b field](json.get(value=`parts`, key="b"))**.
We retain **`c` = [Read the c field](json.get(value=`parts`, key="c"))**.
We retain **path = kb_dir + a + slug + b + explore_attempt + c**.
We retain **`ex` = [Exists](fs.exists(path=`path`))**.
1. `ex`
**_ = 1**
2. *
We **[Write the prepared text to the selected file](fs.write_text(path=`path`, text=`skel`))**.
3. *
The following record names each literal field without a JSON construction chain.
`_literal_parts_fields` =
| @ | key | value |
|---|---|---|
| 1 | "a" | "/resources/" |
| 2 | "b" | ".mq.md" |
We build **parts = [Collect these named fields into one record](table.from_pairs(pairs=`_literal_parts_fields`))**.
We retain **`a` = [Read the a field](json.get(value=`parts`, key="a"))**.
We retain **`b` = [Read the b field](json.get(value=`parts`, key="b"))**.
We retain **path = kb_dir + a + slug + b**.
We retain **`ex` = [Exists](fs.exists(path=`path`))**.
1. `ex`
**_ = 1**
2. *
We **[Write the prepared text to the selected file](fs.write_text(path=`path`, text=`skel`))**.
confirm
out =
| status | goal | workbook | summary | cache |
|---|---|---|---|---|
| pending | goal |
path |
workbook created; confirm to run | bypass |
writebackWe retainbody= Encode the structured value as JSON text. We [Record](wb.record(value=body, key="ok")).-
**_ = 1**
We retain out = [Plan finish stream](plan_finish_stream(out=out, events=events, stream=stream, trace=trace)).
Return out.
2. *
_ = 1
We retain model = [Read the model field](json.get(value=self, key="model")).
We retain round = 0.
We retain last_obs = None.
We retain last_reply = None.
We retain child_val = None.
We retain done = None.
We retain summary = None.
We retain status = "error".
We retain err = "max_rounds exhausted".
We retain skip_loop = None.
We retain plan_llm_calls = 0.
We retain plan_tokens = 0.
We [Plan echo decompose](plan_echo_decompose(workbook=path, stream=stream, echo=echo)).
We retain last_obs = Inspect workbook.
We retain turn = [Plan llm act loop](plan_llm_act_loop(agent=self, goal=goal, path=path, observation=last_obs, phase="decompose", explore_attempt=explore_attempt, explore_n=explore_n, stream=stream, echo=echo, events=events)).
We retain turn_s = Encode the structured value as JSON text.
We retain turn_map = [Starts with](text.starts_with(text=turn_s, prefix="{")).
We retain dec = None.
We retain last_reply = None.
turn_mapWe retaindec= [Read the decision field](json.get(value=turn, key="decision")). We retainlast_reply= [Read the reply field](json.get(value=turn, key="reply")). We retainlast_obs= [Read the observation field](json.get(value=turn, key="observation")). We retainevents= [Read the events field](json.get(value=turn, key="events")). We retain_c= [Read the llm_calls field](json.get(value=turn, key="llm_calls")). We retain_t= [Read the tokens field](json.get(value=turn, key="tokens"))._c!= None We retain plan_llm_calls = plan_llm_calls + _c._t!= None We retain plan_tokens = plan_tokens + _t.-
We retain dec = "TRANSPORT_ERROR".
We retain last_reply = "plan_llm_act_loop_not_map".
We retain err = last_reply.
dec== "TRANSPORT_ERROR" We retain done = 1. We retain status = "error". We retain err =last_reply.turn_mapWe retaine2= [Read the error field](json.get(value=turn, key="error")). 1.e2We retain err =e2. We retain summary = "llm transport error". We retain skip_loop = 1.dec== CONTINUE We retainn= [Apply patch blocks](fs.apply_patch_blocks(path=path, text=last_reply, soft=True)).n_ = 1-
We retain **done = 1**.
We retain **status = "error"**.
We retain **err = "no patches applied"**.
We retain **`summary` = [Extract plan summary](extract_plan_summary(reply=`last_reply`))**.
We retain **skip_loop = 1**.
dec== RUN _ = 1dec== DONE We retainhas_step= Workbook has worker step.has_step_ = 1-
We **[Plan echo await](plan_echo_await(round=1, workbook=`path`, stream=`stream`, echo=`echo`))**.
We retain **`aw` = [Await workbook](await_workbook(path=`path`))**.
We retain **`code` = [Read the code field](json.get(value=`aw`, key="code"))**.
We retain **`child_val` = [Read the value field](json.get(value=`aw`, key="value"))**.
We retain **`last_obs` = [Read the observation field](json.get(value=`aw`, key="observation"))**.
We retain **round = 1**.
We retain **`events` = [Plan append round](plan_append_round(events=`events`, round=1, workbook=`path`, exit_code=`code`, result=`child_val`, stream=`stream`, echo=`echo`))**.
1. `code` == 0
We retain **done = 1**.
We retain **status = "ok"**.
We retain **`summary` = [Extract plan summary](extract_plan_summary(reply=`last_reply`))**.
We retain **err = None**.
We retain **skip_loop = 1**.
2. *
**_ = 1**
Free-form parent reply with no DECISION/CALL/READ (dec=unknown): accept as DONE when there is prose — chat soft-recover depends on result/summary surviving.
dec== "unknown" 1.last_replyWe retain done = 1. We retain status = "ok". We retain err = None. We retain summary =last_reply. We retain skip_loop = 1. 2. * We retain done = 1. We retain status = "error". We retain err = "unrecognized plan decision". We retain summary = last_reply. We retain skip_loop = 1.-
We retain **done = 1**.
We retain **status = "error"**.
We retain **err = "unrecognized plan decision"**.
We retain **summary = last_reply**.
We retain **skip_loop = 1**.
skip_loopWe retain left = 0.improveWe retain left = 1.-
We retain left = max_rounds.
left> 0doneWe retain left = 0.-
round, workbook=path, stream=stream, echo=echo)). We retainaw= Await workbook. We retaincode= [Read the code field](json.get(value=aw, key="code")). We retainchild_val= [Read the value field](json.get(value=aw, key="value")). We retainlast_obs= [Read the observation field](json.get(value=aw, key="observation")). We retainevents= [Plan append round](plan_append_round(events=events, round=round, workbook=path, exit_code=code, result=child_val, stream=stream, echo=echo)).
Deterministic success stop (loop engineering): when the child already returned a value, do not ask the parent LLM to invent solidify patches — DONE + runtime solidify.
1. `code` == 0
1. `child_val`
1. `improve`
We retain **auto_done = None**.
2. *
We retain **auto_done = 1**.
2. *
We retain **auto_done = None**.
2. *
We retain **auto_done = None**.
1. `auto_done`
We **[Workbook solidify](agent_workbook_solidify(path=`path`, observation=`last_obs`))**.
We retain **done = 1**.
We retain **status = "ok"**.
We retain **summary = "child returned value; solidified"**.
We retain **err = None**.
We retain **dec = "DONE"**.
We retain **`events` = [Plan append decision](plan_append_decision(events=`events`, decision=`dec`, stream=`stream`, summary=`summary`))**.
We retain **left = 0**.
2. *
We retain **`turn` = [Plan llm act loop](plan_llm_act_loop(agent=`self`, goal=`goal`, path=`path`, observation=`last_obs`, phase="revise", explore_attempt=`explore_attempt`, explore_n=`explore_n`, stream=`stream`, echo=`echo`, events=`events`))**.
We retain **`dec` = [Read the decision field](json.get(value=`turn`, key="decision"))**.
We retain **`last_reply` = [Read the reply field](json.get(value=`turn`, key="reply"))**.
We retain **`last_obs` = [Read the observation field](json.get(value=`turn`, key="observation"))**.
We retain **`events` = [Read the events field](json.get(value=`turn`, key="events"))**.
We retain **`_c` = [Read the llm_calls field](json.get(value=`turn`, key="llm_calls"))**.
We retain **`_t` = [Read the tokens field](json.get(value=`turn`, key="tokens"))**.
1. `_c` != None
We retain **plan_llm_calls = plan_llm_calls + _c**.
1. `_t` != None
We retain **plan_tokens = plan_tokens + _t**.
1. `dec` == DONE
We **[Workbook solidify](agent_workbook_solidify(path=`path`, observation=`last_obs`))**.
We retain **done = 1**.
We retain **status = "ok"**.
We retain **`summary` = [Extract plan summary](extract_plan_summary(reply=`last_reply`))**.
We retain **err = None**.
We retain **left = 0**.
2. `dec` == CONTINUE
We retain **`n` = [Apply patch blocks](fs.apply_patch_blocks(path=`path`, text=`last_reply`, soft=True))**.
1. `n`
We retain **left = left - 1**.
2. *
We retain **done = 1**.
We retain **status = "error"**.
We retain **err = "no patches applied"**.
We retain **`summary` = [Extract plan summary](extract_plan_summary(reply=`last_reply`))**.
We retain **left = 0**.
3. `dec` == RUN
We retain **left = left - 1**.
4. *
1. `dec` == "unknown"
1. `last_reply`
We retain **done = 1**.
We retain **status = "ok"**.
We retain **err = None**.
We retain **summary = `last_reply`**.
We retain **left = 0**.
2. *
We retain **done = 1**.
We retain **status = "error"**.
We retain **err = "unrecognized plan decision"**.
We retain **summary = last_reply**.
We retain **left = 0**.
2. *
We retain **done = 1**.
We retain **status = "error"**.
We retain **err = "unrecognized plan decision"**.
We retain **summary = last_reply**.
We retain **left = 0**.
status== "ok"promoteWe retainprom= [Kb promote](agent_kb_promote(kb_dir=kb_dir, goal=goal, workbook=path, tools=tools)). We retain cache = "refreshed".-
We retain **cache = "miss"**.
_ = 1
out =
| status | goal | workbook | rounds | cache | llm_calls | tokens |
|---|---|---|---|---|---|---|
status |
goal |
path |
round |
cache |
plan_llm_calls |
plan_tokens |
summaryWe retainout= [Set the summary field in the new record](table.put(in=out, at="summary", value=summary)).-
_ = 1
errWe retainout= [Set the error field in the new record](table.put(in=out, at="error", value=err)).-
_ = 1
last_obsWe retainout= [Set the observation field in the new record](table.put(in=out, at="observation", value=last_obs)).-
_ = 1
child_valWe retainout= [Set the result field in the new record](table.put(in=out, at="result", value=child_val)). We retain plan_result = child_val.summaryWe retainout= [Set the result field in the new record](table.put(in=out, at="result", value=summary)). We retain plan_result = summary.-
We retain plan_result = None.
writebackWe retainbody= Encode the structured value as JSON text.status== "ok" We [Record](wb.record(value=body, key="ok")).-
We **[Record](wb.record(value=`body`, key="error"))**.
_ = 1
We retain out = [Plan finish stream](plan_finish_stream(out=out, events=events, stream=stream, trace=trace, result=plan_result)).
Return out.
mcp_server
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| name | any | "marqdo" | Name registered or looked up by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Minimal MCP Server host (stdio JSON-RPC / Streamable HTTP). Tools point at entry-module lib.member functions (same bridge as ext/web invoke). Evidence/results may carry authority=workbook. |
Use name="marqdo" as the inputs for this operation.
Minimal MCP Server host (stdio JSON-RPC / Streamable HTTP). Tools point at entry-module lib.member functions (same bridge as ext/web invoke). Evidence/results may carry authority=workbook.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/agent: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent)")). We End this run with the selected exit status.
We retain tools0 = Empty list.
h =
| _type | tools | name |
|---|---|---|
| mcp_server | tools0 |
name |
Return h.
tool
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| name | any | required | Name registered or looked up by this operation |
| fn | any | required | Registered function target |
| description | any | "" | Human-readable tool description |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Register one tool. fn must be lib.member imported on the entry workbook. |
Use name, fn, description="" as the inputs for this operation.
Register one tool. fn must be lib.member imported on the entry workbook.
We retain tools = [Read the tools field](json.get(value=self, key="tools")).
- not
toolsWe retaintools= Empty list.
row =
| name | fn | description |
|---|---|---|
name |
fn |
description |
We retain tools = [Append this item to the new list](table.append(list=tools, item=row)).
We retain h = [Set the tools field in the new record](table.put(in=self, at="tools", value=tools)).
Return h.
serve
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| transport | any | "stdio" | Connector transport type |
| host | any | "127.0.0.1" | Explicit bind or remote host |
| port | any | 7434 | Explicit server port |
| path | any | "/mcp" | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Block on MCP: stdio (line JSON-RPC) or http / streamable-http (Streamable HTTP, POST JSON-RPC + optional GET SSE). Spec 2025-03-26. |
Use transport="stdio", host="127.0.0.1", port=7434, path="/mcp" as the inputs for this operation.
Block on MCP: stdio (line JSON-RPC) or http / streamable-http (Streamable HTTP, POST JSON-RPC + optional GET SSE). Spec 2025-03-26.
We retain name = [Read the name field](json.get(value=self, key="name")).
We retain tools = [Read the tools field](json.get(value=self, key="tools")).
Return [Mcp serve](agent_mcp_serve(name=name, tools=tools, transport=transport, host=host, port=port, path=path)).