两处: 1) how-to-act 协议段(每轮都带):无法真正接通的capability 不许静默伪造、不许声称完成, 改写成带状态的遮蔽,例如 [按关键词检索,接口未接,待开发](None); 桩必须能跑并写清返回值(None 亦可);收尾用 labels.search 自查。 2) 默认 standing(p):追加一句"接不了就在描述里申报(待开发/模拟),别假装成功"。 为什么两处:standing 定基调(每轮开头),how-to-act 定动作(每轮), 只写一处会被长上下文冲淡或缺动机。 设计要点:给范式而非规则(可直接抄)、给返回值要求(对应 label.empty_payload)、 给自查动作(labels.search)、用英文与既有协议一致。 验证:marqdo check ext/ai/agent.mq.md(occlusion 模式)通过; grep 确认两处文本落地;全量回归 587 passed / 0 failed(不改逻辑)。 文档:doc/design/change-m10-engineering-habits.md
97 KiB
title: ext/ai/agent description: Document-driven agent v2 — step / plan / run; Skill Compilation via ABI plugin (episodes → learn → llm_free). import llm:ext/ai/llm.mq.md import json:lib/json.mq.md import sys:lib/sys.mq.md import fs:lib/fs.mq.md import time:lib/time.mq.md import wb:lib/writeback.mq.md import subtask:lib/subtask.mq.md import plugin:lib/plugin.mq.md import sandbox:ext/ai/sandbox.mq.md import table:lib/table.mq.md
build_step_context
+ `agent`
+ `task`
+ `source_depth`=default
+ `skill_depth`=default
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:.
standing = > json.get value=agent key="standing"
standingup = standing-
up = None
tools = > json.get value=agent key="tools"
tools_s = > agent_format_tools tools=tools
src = > source_brief depth=source_depth
site = > agent_call_site
site_s = > json.stringify value=site
skill = > skill_brief depth=skill_depth
task_s = > json.stringify value=task
esc = > json.parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- task ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source (.mq.md) ---\n","f":"\n\n--- marqdo skill ---\n","g":"\n\n--- how to act ---\nCall ONLY names listed under --- tools --- (whitelist). If that section is empty or says none, do NOT emit CALL / 调用 — reply with the final answer only.\nNever CALL internal framework helpers (build_step_context, plan, inspect_workbook, etc.).\nContext 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.\nWhen calling an allowed tool, reply with exactly one line: CALL:\n(Chinese ok: 调用:)\nOtherwise reply with the final answer only.\nIf 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.\nTools run via Marqdo subtask (spawn fn / wait).\n"}
a = > json.get value=esc key="a"
b = > json.get value=esc key="b"
c = > json.get value=esc key="c"
d = > json.get value=esc key="d"
e = > json.get value=esc key="e"
f = > json.get value=esc key="f"
g = > json.get value=esc key="g"
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." p = p + a + up + b + task_s + d + site_s + c + tools_s + e + src + f + skill + g p
model_turn
+ `model`
+ `prompt`
+ `stream`=False
+ `echo`=False
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).
streamevs = > model.stream prompt=promptecho=echotext = > llm.collect events=evstokens = 0 err = None calls = 1- not
texte0 = > at value=evsindex=0 err = > json.get value=e0key="message" 1.errcalls = 0 -
r = > model.ask prompt=prompt
text = > json.get value=r key="text"
tokens = > json.get value=r key="tokens"
err = > json.get value=r key="error"
fin = > json.get value=r key="finish"
tokens_ = 1-
**tokens = 0**
errcalls = 0fin== "error" calls = 0 1. noterrerr = "llm transport error"-
**calls = 1**
out =
| text | llm_calls | tokens | error |
|---|---|---|---|
text |
calls |
tokens |
err |
out
dump_step_context
+ `agent`
+ `task`=""
+ `source_depth`=default
+ `skill_depth`=default
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.
prompt = > build_step_context agent=agent task=task source_depth=source_depth skill_depth=skill_depth
site = > agent_call_site
chars = > len value=prompt
parts = > split value=prompt sep="[truncated"
n = > len value=parts
truncated = False
n> 1 truncated = True-
_ = 1
out =
| prompt | call_site | prompt_chars | truncated |
|---|---|---|---|
prompt |
site |
chars |
truncated |
out
extract_tool_name
+ `reply`
Find a human-readable call line: CALL:<name> or 调用:<name> / 调用:<name>.
esc = > json.parse text={"nl":"\n"}
nl = > json.get value=esc key="nl"
text = > trim value=reply
lines = > split value=text sep=nl
found = None
linet = > trim value=lineparts = > split value=tsep=":" n = > len value=partsn> 1 head = > at value=partsindex=0 head = > trim value=headrest = > at value=partsindex=1 rest = > trim value=resthead== CALL found = resthead== 调用 found = rest-
**_ = 1**
found
run_tool
+ `tools`
+ `name`
Allowlist check, then invoke the runbook ## via lib/subtask (spawn fn= → wait).
allowed = > agent_tool_allowed tools=tools name=name
allowedid = > subtask.spawn fn=name> subtask.wait id=id-
msg = "Tool not allowed:" msg + name
render_workbook_skeleton
+ `goal`
+ `skeleton`=single
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.
q = > json.quote text=goal
esc = > json.parse text={"h":"---\ntitle: agent workbook\nimport llm:ext/ai/llm.mq.md\nimport agent:ext/ai/agent.mq.md\nimport json:lib/json.mq.md\nimport sys:lib/sys.mq.md\nimport wb:lib/writeback.mq.md\nimport subtask:lib/subtask.mq.md\n---\n\n# Goal\n\nParent goal is embedded as JSON in # main.\n\n## Solidify\n\nWhen the child returns a good value, parent DECISION: DONE — runtime agent_workbook_solidify freezes the answer as return (do not invent long FIND/REPLACE).\n\n# main\n\n> llm.load_env\n\n","s1":"\u002a\u0060model\u0060 = > llm.llm \u002a\n","s2":"\u002a\u0060tools\u0060 = > table.empty_list \u002a\n","s3":"\u002a\u0060worker\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You are a workbook worker. tools=[] means never CALL. Finish the task with a direct final answer; do not invent tools. \u002a\n","s4":"\u002a\u0060wrap\u0060 = > json.parse text={"task":","s5":"} \u002a\n","s6":"\u002a\u0060task\u0060 = > json.get value=\u0060wrap\u0060 key=task \u002a\n","s7":"\u002a\u0060out\u0060 = > \u0060worker\u0060.step task=\u0060task\u0060 stream=False \u002a\n","s7b":"\u002a\u0060text\u0060 = > json.get value=\u0060out\u0060 key=result \u002a\n","s8":"\u002a\u002a\u0060text\u0060\u002a\u002a\n","d3":"\u002a\u0060research\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You gather facts for the goal. Be concise. Do not invent tools. \u002a\n","d3b":"\u002a\u0060writer\u0060 = > agent.agent model=\u0060model\u0060 tools=\u0060tools\u0060 standing=You write the final answer from research notes. Do not invent tools. \u002a\n","d4":"\u002a\u0060wrap\u0060 = > json.parse text={"task":","d5":"} \u002a\n","d6":"\u002a\u0060task\u0060 = > json.get value=\u0060wrap\u0060 key=task \u002a\n","d7":"\u002a\u0060notes\u0060 = > \u0060research\u0060.step task=\u0060task\u0060 stream=False \u002a\n","d8":"\u002a\u0060ns\u0060 = > json.stringify value=\u0060notes\u0060 \u002a\n","d9":"\u002a\u0060wt\u0060 = Write the final answer. Research notes: \u002a\n","d10":"\u002a\u0060wt\u0060 = \u0060wt\u0060 + \u0060ns\u0060 \u002a\n","d11":"\u002a\u0060out\u0060 = > \u0060writer\u0060.step task=\u0060wt\u0060 stream=False \u002a\n","d11b":"\u002a\u0060text\u0060 = > json.get value=\u0060out\u0060 key=result \u002a\n","d12":"\u002a\u002a\u0060text\u0060\u002a\u002a\n"}
h = > json.get value=esc key="h"
s1 = > json.get value=esc key="s1"
s2 = > json.get value=esc key="s2"
skeleton== dual s3 = > json.get value=esckey="d3" s3b = > json.get value=esckey="d3b" s4 = > json.get value=esckey="d4" s5 = > json.get value=esckey="d5" s6 = > json.get value=esckey="d6" s7 = > json.get value=esckey="d7" s8 = > json.get value=esckey="d8" s9 = > json.get value=esckey="d9" s10 = > json.get value=esckey="d10" s11 = > json.get value=esckey="d11" s11b = > json.get value=esckey="d11b" s12 = > json.get value=esckey="d12" h + s1 + s2 + s3 + s3b + s4 + q + s5 + s6 + s7 + s8 + s9 + s10 + s11 + s11b + s12-
s3 = > json.get value=esc key="s3"
s4 = > json.get value=esc key="s4"
s5 = > json.get value=esc key="s5"
s6 = > json.get value=esc key="s6"
s7 = > json.get value=esc key="s7"
s7b = > json.get value=esc key="s7b"
s8 = > json.get value=esc key="s8"
h + s1 + s2 + s3 + s4 + q + s5 + s6 + s7 + s7b + s8
inspect_workbook
+ `path`
+ `exit_code`=None
+ `value`=None
+ `stdout`=None
+ `stderr`=None
Structured observation for the parent developer-agent: source, named writeback slots, exit code, optional child return value, and quiet-captured I/O.
source = > fs.read_text path=path
slots = > wb.scan_path path=path
obs =
| path | source | slots | exit_code |
|---|---|---|---|
path |
source |
slots |
exit_code |
valueobs = table.put in=obsat="value" value=value-
_ = 1
stdoutobs = table.put in=obsat="stdout" value=stdout-
_ = 1
stderrobs = table.put in=obsat="stderr" value=stderr-
_ = 1
last_ok = None last_error = None
slotk = > json.get value=slotkey="key" body = > json.get value=slotkey="body"k== "ok" last_ok = bodyk== "error" last_error = body-
last_okobs = table.put in=obsat="last_ok" value=last_ok-
_ = 1
last_errorobs = table.put in=obsat="last_error" value=last_error-
_ = 1
obs
trial
+ `path`=None
+ `source`=None
+ `root`=None
+ `write_path`=None
+ `text`=None
+ `commit`=True
+ `profile`=default
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).
sb = sandbox.open root=root profile=profile
id = > json.get value=sb key="id"
prof = > json.get value=sb key="profile"
ok = True
stdout = ""
stderr = ""
write_pathtext> sandbox.write id=idpath=write_pathtext=text-
**_ = 1**
_ = 1
sourceret = sandbox.run id=idsource=sourceok = > json.get value=retkey="ok" stdout = > json.get value=retkey="stdout" stderr = > json.get value=retkey="stderr"pathret = sandbox.run id=idpath=pathok = > json.get value=retkey="ok" stdout = > json.get value=retkey="stdout" stderr = > json.get value=retkey="stderr"-
_ = 1
pending = sandbox.diff id=id
committed = False
okcommit> sandbox.commit id=idcommitted = True-
> sandbox.discard id=`id`
sandbox.discard id=
id
**out = **
| ok | committed | diff | stdout | stderr | id | profile |
|---|---|---|---|---|---|---|
ok |
committed |
pending |
stdout |
stderr |
id |
prof |
out
step_route
+ `kind`=default
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" backend = "marqdo"kind== "patch" backend = "small-llm"kind== "sandbox_run" backend = "marqdo"kind== "net" backend = "llm"-
backend = "auto"
out = table.put in=None at="kind" value=kind
out = table.put in=out at="backend" value=backend
out
await_workbook
+ `path`
+ `sandbox`=False
+ `sandbox_root`=None
+ `sandbox_profile`=default
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.
sandboxtr = trial path=pathroot=sandbox_rootprofile=sandbox_profilecommit=True ok = > json.get value=trkey="ok" stdout = > json.get value=trkey="stdout" stderr = > json.get value=trkey="stderr"okcode = 0-
**code = 1**
value = stdout
obs = inspect_workbook path=path exit_code=code value=value stdout=stdout stderr=stderr
**out = **
| code | value | observation | sandbox |
|---|---|---|---|
code |
value |
obs |
tr |
out
2. *
id = subtask.spawn path=path
waited = subtask.wait id=id
code = > json.get value=waited key="code"
value = > json.get value=waited key="value"
stdout = > json.get value=waited key="stdout"
stderr = > json.get value=waited key="stderr"
obs = inspect_workbook path=path exit_code=code value=value stdout=stdout stderr=stderr
**out = **
| code | value | observation |
|---|---|---|
code |
value |
obs |
out
text_head_lines
+ `text`
+ `max_lines`=80
+ `max_chars`=4000
esc = > json.parse text={"nl":"\n"}
nl = > json.get value=esc key="nl"
raw = > str value=text
lines = > split value=raw sep=nl
acc = > table.empty_list
chars = 0
count = 0
linecount<max_linesln = > len value=linenext = chars + lnnext>max_charscount = max_lines-
**acc = > table.append list=`acc` item=`line`** **chars = next** **count = count + 1**accsep=nl
text_tail_lines
+ `text`
+ `max_lines`=40
+ `max_chars`=2000
esc = > json.parse text={"nl":"\n"}
nl = > json.get value=esc key="nl"
raw = > str value=text
lines = > split value=raw sep=nl
n = > len value=lines
start = n - max_lines
start< 0 start = 0-
_ = 1 acc = > table.empty_list i = 0 chars = 0
linei>=startln = > len value=linenext = chars + lnnext>max_charsi = n-
**acc = > table.append list=`acc` item=`line`** **chars = next**accsep=nl
strip_html_comments
+ `text`
Drop <!-- … --> blocks (including marqdo-out bodies) so parent excerpts stay structural.
esc = > json.parse text={"nl":"\n"}
nl = > json.get value=esc key="nl"
raw = > str value=text
lines = > split value=raw sep=nl
acc = > table.empty_list
skip = None
lineskipend_parts = > split value=linesep="-->" en = > len value=end_partsen> 1 skip = None-
**_ = 1**linesep="<!--" sn = > len value=start_partssn> 1 before = > at value=start_partsindex=0 before = > trim value=before1.beforeacc = > table.append list=accitem=before2. * _ = 1 tail = > at value=start_partsindex=1 end_parts = > split value=tailsep="-->" en = > len value=end_parts1.en> 1 skip = None 2. * skip = 1-
**acc = > table.append list=`acc` item=`line`**
> join value=acc sep=nl
workbook_source_excerpt
+ `source`
+ `max_lines`=80
+ `max_chars`=4000
clean = > strip_html_comments text=source
> text_head_lines text=clean max_lines=max_lines max_chars=max_chars
workbook_excerpt
+ `path`
+ `max_lines`=80
+ `max_chars`=4000
src = > fs.read_text path=path
> workbook_source_excerpt source=src max_lines=max_lines max_chars=max_chars
workbook_read
+ `path`
+ `depth`=default
src = > fs.read_text path=path
depth== deep > workbook_source_excerpt source=srcmax_lines=200 max_chars=12000-
> workbook_source_excerpt source=src max_lines=80 max_chars=4000
lib_catalog
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).
out = > json.parse text={"note":"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.","files":["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"],"callable":[{"name":"lib.fs.read_text","desc":"Read UTF-8 text file"},{"name":"lib.fs.exists","desc":"Path exists?"},{"name":"lib.fs.list_dir","desc":"List directory entries"},{"name":"lib.json.parse","desc":"Parse JSON text"},{"name":"lib.json.stringify","desc":"Serialize JSON"},{"name":"lib.sys.cwd","desc":"Process working directory"},{"name":"corpus_search","desc":"Local markdown/text keyword search (evidence)"},{"name":"mcp_list_tools","desc":"List tools from MCP JSON fixture"},{"name":"mcp_call","desc":"Call a tool from MCP JSON fixture"}]} out
corpus_search
+ `query`
+ `root`=.marqdo/agent-corpus
+ `limit`=6
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.
p = > plugin.native_path name="agent"
p
plugin.load path=
p
print text=ext/ai/agent: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent) sys.exit code=1
> agent_corpus_search query=query root=root limit=limit
mcp_list_tools
+ `fixture`
List tools from an offline MCP-shaped JSON fixture (tools array). Evidence only.
> agent_mcp_fixture action="list" fixture=fixture
mcp_call
+ `name`
+ `fixture`
+ `arguments`=None
Call a named tool from a MCP-shaped fixture (results / calls map). Optional arguments echoed; fixture results are keyed by name. Evidence only.
arguments> agent_mcp_fixture action="call" fixture=fixturename=namearguments=arguments-
> agent_mcp_fixture action="call" fixture=fixture name=name
mcp_connect
+ `command`
+ `args`=None
+ `session`="default"
+ `name`="mcp"
Open a stdio MCP client session (spawn command + args, JSON-RPC initialize). Evidence only — workbook remains authority.
p = > plugin.native_path name="agent"
p
plugin.load path=
p
print text=ext/ai/agent: native agent plugin not found sys.exit code=1
args> agent_mcp_client action="connect" command=commandargs=argssession=sessionname=name-
> agent_mcp_client action="connect" command=command session=session name=name
mcp_client_list
+ `session`="default"
+ `command`=None
+ `args`=None
List tools from an open MCP session, or one-shot when command= is set (no session retained).
commandargs> agent_mcp_client action="list" command=commandargs=args-
*> agent_mcp_client action="list" command=`command`*
> agent_mcp_client action="list" session=session
mcp_client_call
+ `name`=None
+ `session`="default"
+ `arguments`=None
+ `command`=None
+ `args`=None
+ `tool`=None
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.
commandtooltn = tool-
**tn = name**
args> agent_mcp_client action="call" command=commandargs=argstool=tnarguments=arguments-
*> agent_mcp_client action="call" command=`command` tool=`tn` arguments=`arguments`*
> agent_mcp_client action="call" session=session name=name arguments=arguments
mcp_disconnect
+ `session`="default"
Close a stdio MCP client session.
> agent_mcp_client action="close" session=session
resume_save
+ `id`
+ `goal`=None
+ `task`=None
+ `status`=running
+ `round`=0
+ `workbook`=None
+ `events`=None
+ `route`=None
+ `result`=None
+ `resume_dir`=.marqdo/agent-resume
Persist a plan/run checkpoint as .marqdo/agent-resume/<id>.json.
p = > plugin.native_path name="agent"
p
plugin.load path=
p
print text=ext/ai/agent: native agent plugin not found sys.exit code=1
> 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
resume_load
+ `id`
+ `resume_dir`=.marqdo/agent-resume
Load a resume checkpoint (or {ok:false,found:false}).
> agent_resume_load id=id resume_dir=resume_dir
resume_clear
+ `id`
+ `resume_dir`=.marqdo/agent-resume
Delete a resume checkpoint.
> agent_resume_clear id=id resume_dir=resume_dir
resume_list
+ `resume_dir`=.marqdo/agent-resume
List checkpoint ids under resume_dir.
> agent_resume_list resume_dir=resume_dir
resume
+ `id`
+ `resume_dir`=.marqdo/agent-resume
Author entry: load checkpoint for continuation. Returns the checkpoint map (found/round/workbook/…). Callers continue with plan/run using saved fields; clear when done.
> resume_load id=id resume_dir=resume_dir
extract_call_args
+ `reply`=None
Parse ARGS:{…} JSON line, or a bare {…} line after CALL.
esc = > json.parse text={"nl":"\n","mark":"ARGS:","brace":"{"}
nl = > json.get value=esc key="nl"
mark = > json.get value=esc key="mark"
brace = > json.get value=esc key="brace"
empty = > table.empty_map
replytext = > trim value=replylines = > split value=textsep=nlfound = None
linefound_ = 1-
linechunks = > split value=tsep=markcn = > len value=chunkscn> 1 rest = > at value=chunksindex=1 found = > trim value=rest-
**chunks = > split value=`t` sep=`brace`** **cn = > len value=`chunks`** **prefix = > at value=`chunks` index=0** 1. `cn` > 1 1. `prefix` **_ = 1** 2. * **found = t** 2. * **_ = 1**
found> json.parse text=found-
*empty*
empty
tool_result_brief
+ `value`=None
+ `max_chars`=1024
Truncate a tool result for tool_end events (~1KiB).
values = > json.stringify value=value> text_head_lines text=smax_lines=40 max_chars=max_chars-
plan_append_tool
+ `events`
+ `type`
+ `name`
+ `kind`
+ `result`=None
+ `stream`=False
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 |
resultev = table.put in=evat="result" value=result-
_ = 1
events = > table.append list=events item=ev
stream
sys.stream_publish event=
ev
_ = 1
events
run_lib_call
+ `name`
+ `reply`=None
Whitelist CALL:lib.<mod>.<fn> (+ ARGS). Rejects net/exec/write/delete.
args = > extract_call_args reply=reply
errs = > json.parse text={"deny":"Lib CALL not allowed: "}
name== lib.fs.exists path = > json.get value=argskey="path" > fs.exists path=pathname== lib.fs.read_text path = > json.get value=argskey="path" > fs.read_text path=pathname== lib.fs.list_dir path = > json.get value=argskey="path" > fs.list_dir path=pathname== lib.json.parse text = > json.get value=argskey="text" > json.parse text=textname== lib.json.stringify value = > json.get value=argskey="value" > json.stringify value=valuename== lib.sys.cwd > sys.cwd-
deny = > json.get value=errs key="deny"
deny + name
scratch_tool_write
+ `name`
+ `text`
Write a scratch tool workbook under .marqdo/agent-runs/tools/<name>.mq.md.
esc = > json.parse text={"a":".marqdo/agent-runs/tools/","b":".mq.md"}
a = > json.get value=esc key="a"
b = > json.get value=esc key="b"
dir = ".marqdo/agent-runs/tools"
fs.make_dir path=
dirpath = a + name + b fs.write_text path=pathtext=textout=
| ok | path |
|---|---|
| True | path |
out
skill_brief
+ `max_chars`=1200
+ `depth`=default
Budgeted marqdo skill text for prompts. depth=deep raises the char budget.
depth== deep budget = 4000-
budget = max_chars
skill = > agent_marqdo_skill
full = > len value=skill
ex = > text_head_lines text=skill max_lines=80 max_chars=budget
used = > len value=ex
used<fullesc = > json.parse text={"a":"\n…[truncated skill_len=","b":" budget_chars=","c":"; emit READ:skill to deepen]"} a = > json.get value=esckey="a" b = > json.get value=esckey="b" c = > json.get value=esckey="c" ex + a + full + b + budget + c-
ex
source_brief
+ `depth`=default
Budgeted current-module .mq.md source for step prompts. Default ~80 lines / 4KiB; depth=deep ~200 / 12KiB.
src = > agent_module_source
full = > len value=src
depth== deep ex = > workbook_source_excerpt source=srcmax_lines=200 max_chars=12000 budget = 12000-
ex = > workbook_source_excerpt source=src max_lines=80 max_chars=4000
budget = 4000
used = > len value=ex
used<fullesc = > json.parse text={"a":"\n…[truncated source_len=","b":" budget_chars=","c":"; emit READ:source to deepen]"} a = > json.get value=esckey="a" b = > json.get value=esckey="b" c = > json.get value=esckey="c" ex + a + full + b + budget + c-
ex
extract_plan_read
+ `reply`
Parse READ:source|stderr|stdout|slots|skill (Chinese: 读取:…).
esc = > json.parse text={"nl":"\n","fw":":"}
nl = > json.get value=esc key="nl"
fw = > json.get value=esc key="fw"
text = > trim value=reply
lines = > split value=text sep=nl
found = None
linet = > trim value=lineparts = > split value=tsep=":" n = > len value=partsn> 1 head = > at value=partsindex=0 head = > trim value=headrest = > at value=partsindex=1 rest = > trim value=resthead== READ found = resthead== 读取 found = rest-
**_ = 1**tsep=fwn = > len value=partsn> 1 head = > at value=partsindex=0 head = > trim value=headrest = > at value=partsindex=1 rest = > trim value=rest1.head== 读取 found = rest 2.head== READ found = rest 3. * _ = 1-
**_ = 1**
found
extract_plan_act
+ `reply`
Priority: CALL → READ → DECISION. Returns {kind,name}.
tool = > extract_tool_name reply=reply
toolout=
| kind | name |
|---|---|
| call | tool |
out
2. *
_ = 1
rk = > extract_plan_read reply=reply
rkout=
| kind | name |
|---|---|
| read | rk |
out
2. *
_ = 1
dec = > extract_plan_decision reply=reply
decout=
| kind | name |
|---|---|
| decision | dec |
out
2. *
out =
| kind |
|---|
| unknown |
out
extract_scratch_tool
+ `reply`
Parse NAME: id plus a triple-angle body after CALL:scratch_tool_write.
esc = > json.parse text={"nl":"\n","open":"<<<","close":">>>"}
nl = > json.get value=esc key="nl"
open = > json.get value=esc key="open"
close = > json.get value=esc key="close"
text = > trim value=reply
lines = > split value=text sep=nl
name = None
body_lines = > table.empty_list
in_body = None
linein_bodyt = > trim value=linet==closein_body = None-
**body_lines = > table.append list=`body_lines` item=`line`**lineparts = > split value=tsep=":" n = > len value=partsn> 1 head = > at value=partsindex=0 head = > trim value=headrest = > at value=partsindex=1 rest = > trim value=rest1.head== NAME name = rest 2.head== 名称 name = rest 3. * _ = 1-
**_ = 1**t==openin_body = 1-
**_ = 1**
body = > join value=body_lines sep=nl
out =
| name | text |
|---|---|
name |
body |
out
run_parent_tool
+ `name`
+ `path`
+ `observation`=None
+ `reply`=None
Parent Plan-and-Move tools (helpers + whitelist CALL:lib…).
name== workbook_read > workbook_read path=pathdepth="deep"name== workbook_excerpt > workbook_excerpt path=pathname== lib_catalog > lib_catalogname== scratch_tool_write parsed = > extract_scratch_tool reply=replytn = > json.get value=parsedkey="name" tt = > json.get value=parsedkey="text" errs = > json.parse text={"a":"scratch_tool_write needs NAME line and fenced body","b":"scratch_tool_write needs NAME id"}tn1.tt> scratch_tool_write name=tntext=tt2. * > json.get value=errskey="a"-
*> json.get value=`errs` key="b"*
name== corpus_search args = > extract_call_args reply=replyq = > json.get value=argskey="query" root = > json.get value=argskey="root" limit = > json.get value=argskey="limit" cerrs = > json.parse text={"q":"corpus_search needs ARGS.query"}- not
q> json.get value=cerrskey="q" root1.limit> corpus_search query=qroot=rootlimit=limit2. * > corpus_search query=qroot=rootlimit> corpus_search query=qlimit=limit-
*> corpus_search query=`q`*
name== mcp_list_tools args = > extract_call_args reply=replyfx = > json.get value=argskey="fixture" merrs = > json.parse text={"f":"mcp_list_tools needs ARGS.fixture"}fx> mcp_list_tools fixture=fx-
*> json.get value=`merrs` key="f"*
name== mcp_call args = > extract_call_args reply=replyfx = > json.get value=argskey="fixture" tn = > json.get value=argskey="name" targ = > json.get value=argskey="arguments" xerrs = > json.parse text={"f":"mcp_call needs ARGS.fixture","n":"mcp_call needs ARGS.name"}fx1.tntarg> mcp_call name=tnfixture=fxarguments=targ-
tnfixture=fx2. * > json.get value=xerrskey="n"-
*> json.get value=`xerrs` key="f"*
dots = > split value=name sep=".*"
head = > at value=dots index=0
head== lib > run_lib_call name=namereply=reply-
**msg = "Parent tool not allowed:"**
*msg + name*
plan_read_deepen
+ `observation`
+ `kind`
+ `path`
obs = observation
kind== source ex = > workbook_read path=pathdepth="deep" obs = table.put in=obsat="source_excerpt" value=exobs = table.put in=obsat="read_source" value=Truekind== stderr err = > json.get value=obskey="stderr" tail = > text_tail_lines text=errmax_lines=80 max_chars=6000 obs = table.put in=obsat="stderr_tail" value=tailobs = table.put in=obsat="read_stderr" value=Truekind== stdout out = > json.get value=obskey="stdout" tail = > text_tail_lines text=outmax_lines=80 max_chars=6000 obs = table.put in=obsat="stdout_tail" value=tailobs = table.put in=obsat="read_stdout" value=Truekind== slots slots = > json.get value=obskey="slots" obs = table.put in=obsat="slots_detail" value=slotsobs = table.put in=obsat="read_slots" value=Truekind== skill brief = > skill_brief depth="deep" obs = table.put in=obsat="skill_brief" value=briefobs = table.put in=obsat="read_skill" value=True-
_ = 1 obs
compact_plan_observation
+ `observation`
Bounded observation for the parent prompt (actionable, short).
obs_path = > json.get value=observation key="path"
obs_code = > json.get value=observation key="exit_code"
obs_val = > json.get value=observation key="value"
obs_slots = > json.get value=observation key="slots"
obs_src = > json.get value=observation key="source"
obs_stdout = > json.get value=observation key="stdout"
obs_stderr = > json.get value=observation key="stderr"
src_len = 0
has_step = False
obs_srcsrc_len = > len value=obs_srcstep_parts = > split value=obs_srcsep="worker.step" n_step = > len value=step_partsn_step> 1 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_srcex = > json.get value=observationkey="source_excerpt"excompact = table.put in=compactat="source_excerpt" value=ex-
**ex = > workbook_source_excerpt source=`obs_src`**
**compact = table.put in=`compact` at="source_excerpt" value=`ex`**
_ = 1
obs_stderrtail = > json.get value=observationkey="stderr_tail"tailcompact = table.put in=compactat="stderr_tail" value=tail-
**tail = > text_tail_lines text=`obs_stderr`**
**compact = table.put in=`compact` at="stderr_tail" value=`tail`**
_ = 1
obs_stdouttail = > json.get value=observationkey="stdout_tail"tailcompact = table.put in=compactat="stdout_tail" value=tail-
**tail = > text_tail_lines text=`obs_stdout`**
**compact = table.put in=`compact` at="stdout_tail" value=`tail`**
_ = 1
val_txt = > str value=obs_val
val_len = > len value=val_txt
obs_valcompact = table.put in=compactat="has_value" value=True compact = table.put in=compactat="value_len" value=val_lenval_len> 200 preview = > text_head_lines text=val_txtmax_lines=4 max_chars=200 compact = table.put in=compactat="value_preview" value=preview-
**compact = table.put in=`compact` at="value" value=`obs_val`**
compact = table.put in=compact at="has_value" value=False
slots_brief = > table.empty_list
obs_slots
-
slotsk = > json.get value=slotkey="key" sl = > json.get value=slotkey="line" sb = > json.get value=slotkey="body" sb_txt = > str value=sbsb_len = > len value=sb_txtbrief=key line body_len skslsb_lensk== error prev = > text_head_lines text=sb_txtmax_lines=8 max_chars=400 brief = table.put in=briefat="body_preview" value=prev-
_ = 1 slots_brief = > table.append list=
slots_briefitem=brief
_ = 1
compact = table.put in=compact at="slots" value=slots_brief
detail = > json.get value=observation key="slots_detail"
detailcompact = table.put in=compactat="slots_detail" value=detail-
_ = 1
tool_result = > json.get value=observation key="tool_result"
tool_resulttr = > str value=tool_resulttr = > text_head_lines text=trmax_lines=40 max_chars=3000 compact = table.put in=compactat="tool_result" value=tr-
_ = 1
last_error = > json.get value=observation key="last_error"
last_errorerr_txt = > str value=last_errorerr_len = > len value=err_txterr_len> 200 prev = > text_head_lines text=err_txtmax_lines=8 max_chars=400 compact = table.put in=compactat="last_error_preview" value=prevcompact = table.put in=compactat="last_error_len" value=err_len-
**compact = table.put in=`compact` at="last_error" value=`last_error`**
_ = 1
compact
extract_plan_decision
+ `reply`
Parse DECISION: DONE / CONTINUE / RUN (Chinese: 决定:完成 / 继续 / 运行).
First matching DECISION / 决定 line wins (ignore later conflicting decisions in the same reply).
esc = > json.parse text={"nl":"\n","fw":":"}
nl = > json.get value=esc key="nl"
fw = > json.get value=esc key="fw"
text = > trim value=reply
lines = > split value=text sep=nl
found = None
linefound_ = 1-
lineparts = > split value=tsep=":" n = > len value=partsn> 1 head = > at value=partsindex=0 head = > trim value=headrest = > at value=partsindex=1 rest = > trim value=rest1.head== DECISION found = rest 2.head== 决定 found = rest 3. * _ = 1-
**parts = > split value=`t` sep=`fw`** **n = > len value=`parts`** 1. `n` > 1 **head = > at value=`parts` index=0** **head = > trim value=`head`** **rest = > at value=`parts` index=1** **rest = > trim value=`rest`** 1. `head` == 决定 **found = rest** 2. `head` == DECISION **found = rest** 3. * **_ = 1** 2. * **_ = 1**
found== DONE "DONE"found== CONTINUE "CONTINUE"found== RUN "RUN"found== REUSE "REUSE"found== NEW "NEW"found== 完成 "DONE"found== 继续 "CONTINUE"found== 运行 "RUN"found== 复用 "REUSE"found== 新建 "NEW"-
found
extract_soft_match_slug
+ `reply`
Parse SLUG: … / 标识:… after a soft-match REUSE decision.
esc = > json.parse text={"nl":"\n","fw":":"}
nl = > json.get value=esc key="nl"
fw = > json.get value=esc key="fw"
text = > trim value=reply
lines = > split value=text sep=nl
found = None
linet = > trim value=lineparts = > split value=tsep=":" n = > len value=partsn> 1 head = > at value=partsindex=0 head = > trim value=headrest = > at value=partsindex=1 rest = > trim value=resthead== SLUG found = resthead== 标识 found = rest-
**_ = 1**tsep=fwn = > len value=partsn> 1 head = > at value=partsindex=0 head = > trim value=headrest = > at value=partsindex=1 rest = > trim value=rest1.head== 标识 found = rest 2.head== SLUG found = rest 3. * _ = 1-
**_ = 1**
found
build_soft_match_prompt
+ `goal`
+ `tasks`
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.
esc = > json.parse text={"a":"\n\n--- goal ---\n","b":"\n\n--- candidate tasks (slug | title | meta) ---\n","c":"\n\n--- how to act ---\nExact 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:\nDECISION: REUSE\nSLUG: \nor\nDECISION: NEW\nNo other prose.\n","nl":"\n","sep":" | ","sp":"score=","st":"status=","lf":"llm_free="}
a = > json.get value=esc key="a"
b = > json.get value=esc key="b"
c = > json.get value=esc key="c"
nl = > json.get value=esc key="nl"
sep = > json.get value=esc key="sep"
sp = > json.get value=esc key="sp"
st = > json.get value=esc key="st"
lf = > json.get value=esc key="lf"
lines = > table.empty_list
tslug = > json.get value=tkey="slug" title = > json.get value=tkey="title" row = slug + sep + title score = > json.get value=tkey="score"scorerow = row + sep + sp + score-
tkey="status"statusrow = row + sep + st + status-
tkey="llm_free"free== True row = row + sep + lf + "true"free== true row = row + sep + lf + "true"free== False row = row + sep + lf + "false"free== false row = row + sep + lf + "false"-
tkey="description"descrow = row + sep + desc-
linesitem=rowcatalog = > join value=linessep=nlp = "Soft-match: same task intent?" p + a + goal + b + catalog + c
extract_plan_summary
+ `reply`
First SUMMARY: / 汇总: / 汇总: line body, else trimmed reply.
esc = > json.parse text={"nl":"\n","fw":":"}
nl = > json.get value=esc key="nl"
fw = > json.get value=esc key="fw"
text = > trim value=reply
lines = > split value=text sep=nl
found = None
linet = > trim value=lineparts = > split value=tsep=":" n = > len value=partsn> 1 head = > at value=partsindex=0 head = > trim value=headrest = > at value=partsindex=1 rest = > trim value=resthead== SUMMARY found = resthead== 汇总 found = rest-
**_ = 1**tsep=fwn = > len value=partsn> 1 head = > at value=partsindex=0 head = > trim value=headrest = > at value=partsindex=1 rest = > trim value=rest1.head== 汇总 found = rest 2.head== SUMMARY found = rest 3. * _ = 1-
**_ = 1**
foundfound-
text
build_plan_context
+ `agent`
+ `goal`
+ `observation`
+ `explore_attempt`=None
+ `explore_n`=None
+ `phase`=revise
Parent Plan-and-Move prompt. Short protocol only — no long monologues.
standing = > json.get value=agent key="standing"
standingup = standing-
up = None
skill_from_obs = > json.get value=observation key="skill_brief"
skill_from_obsskill = skill_from_obs-
skill = > skill_brief
compact = > compact_plan_observation observation=observation
obs_s = > json.stringify value=compact
goal_s = > json.stringify value=goal
**esc = > json.parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- goal ---\n","c":"\n\n--- observation ---\n","d":"\n\n--- skill brief ---\n","tools":"\n\n--- parent tools ---\nCALL:workbook_read | workbook_excerpt | lib_catalog | scratch_tool_write\nCALL:corpus_search | mcp_list_tools | mcp_call (ARGS:{…}; evidence only — workbook authority)\nCALL:lib.fs.read_text|exists|list_dir | lib.json.parse|stringify | lib.sys.cwd (+ ARGS:{json})\nREAD:source | stderr | stdout | slots | skill\nCreate tools: CONTINUE PATCH add ##, or CALL:scratch_tool_write with NAME line and fenced body.\n","e_rev":"\n\n--- how to act ---\nPlan-and-Move parent. Reply with ONE protocol only (no long reasoning). Exactly one DECISION line.\n1) exit_code=0 and has_value → DECISION: DONE + one-line SUMMARY. solidify_on_done. Do not CONTINUE just because has_worker_step.\n2) Need more evidence → READ:kind or CALL:tool (then you will be re-prompted).\n3) Failure / wrong value → DECISION: CONTINUE + short PATCH (<20 lines). Never paste user prose into REPLACE.\n4) Do NOT CONTINUE only to rewrite frontmatter imports; skeleton already uses import llm:/agent:/json:….\nPATCH must use triple-angle blocks only:\n<<<\nFIND\n\n===\nREPLACE\n\n>>>\nDo not use \u0060\u0060\u0060find, \u0060\u0060\u0060replace, or *** Begin Patch *.\nProtocols:\nCALL:name\nREAD:kind\nDECISION: DONE\nSUMMARY: one line\nDECISION: CONTINUE\n","e_dec":"\n\n--- how to act ---\nPRE-RUN decompose. Reply with ONE protocol only (no long reasoning). Exactly one DECISION line.\n1) Skeleton OK → DECISION: RUN (preferred). Do not rewrite imports; they are already import llm:/agent:/….\n2) Need evidence → READ:source or READ:skill or CALL:workbook_read / lib_catalog / corpus_search / mcp_call.\n3) Reshape body/logic only → DECISION: CONTINUE + short PATCH (<20 lines).\n4) Fixed answer without LLM → PATCH to return, then RUN or DONE.\nPATCH must use <<< FIND === REPLACE >>> only (no \u0060\u0060\u0060find / Begin Patch).\nProtocols:\nCALL:name\nREAD:kind\nDECISION: RUN\nDECISION: DONE\nSUMMARY: one line\nDECISION: CONTINUE\n","f":"\n\n--- explore ---\n"}
a = > json.get value=esc key="a"
b = > json.get value=esc key="b"
c = > json.get value=esc key="c"
d = > json.get value=esc key="d"
tools = > json.get value=esc key="tools"
f = > json.get value=esc key="f"
phase== decompose e = > json.get value=esckey="e_dec" p = "Plan-and-Move: decompose before first run."-
e = > json.get value=esc key="e_rev"
p = "Plan-and-Move: revise after child run."
p = p + a + up + b + goal_s + c + obs_s + tools + d + skill + e
explore_attemptp = p + f p = p + "Attempt" p = p + explore_attempt p = p + "of" p = p + explore_n p = p + ". Different path; prefer code when fixed."-
_ = 1 p
plan_llm_act_loop
+ `agent`
+ `goal`
+ `path`
+ `observation`
+ `phase`=revise
+ `explore_attempt`=None
+ `explore_n`=None
+ `stream`=False
+ `echo`=False
+ `events`
+ `max_acts`=6
LLM Plan → CALL/READ/DECISION loop. Returns {decision,reply,observation,events,llm_calls,tokens}.
model = > json.get value=agent key="model"
last_obs = observation
left = max_acts
decision = None
last_reply = None
evs_all = events
llm_calls = 0
tokens = 0
transport_err = None
left> 0decisionleft = 0transport_errleft = 0-
agentgoal=goalobservation=last_obsexplore_attempt=explore_attemptexplore_n=explore_nphase=phasestreamevs = > model.stream prompt=ctxecho=echolast_reply = > llm.collect events=evsevs_all = > plan_merge_deltas events=evs_allfrom=evsstream=streame0 = > at value=evsindex=0 terr = > json.get value=e0key="message" etype = > json.get value=e0key="type" 1.etype== "error" transport_err =terr- not
transport_errtransport_err = "llm stream transport error" left = 0 2. * llm_calls = llm_calls + 1
- not
-
**turn = > model_turn model=`model` prompt=`ctx` stream=False echo=`echo`** **terr = > json.get value=`turn` key="error"** 1. `terr` **transport_err = `terr`** **left = 0** 2. * **last_reply = > json.get value=`turn` key="text"** **c = > json.get value=`turn` key="llm_calls"** **t = > json.get value=`turn` key="tokens"** **llm_calls = llm_calls + c** **tokens = tokens + t**transport_errdecision = "TRANSPORT_ERROR" last_reply =transport_errleft = 0-
**last_reply = > trim value=`last_reply`** **act = > extract_plan_act reply=`last_reply`** **kind = > json.get value=`act` key="kind"** **name = > json.get value=`act` key="name"** 1. `kind` == call **evs_all = > plan_append_tool events=`evs_all` type="tool_start" name=`name` kind="call" stream=`stream`** **tool_out = > run_parent_tool name=`name` path=`path` observation=`last_obs` reply=`last_reply`** **brief = > tool_result_brief value=`tool_out`** **evs_all = > plan_append_tool events=`evs_all` type="tool_end" name=`name` kind="call" result=`brief` stream=`stream`** **last_obs = table.put in=`last_obs` at="tool_result" value=`tool_out`** **left = left - 1** 2. `kind` == read **evs_all = > plan_append_tool events=`evs_all` type="tool_start" name=`name` kind="read" stream=`stream`** **last_obs = > plan_read_deepen observation=`last_obs` kind=`name` path=`path`** **brief = > tool_result_brief value=`last_obs`** **evs_all = > plan_append_tool events=`evs_all` type="tool_end" name=`name` kind="read" result=`brief` stream=`stream`** **left = left - 1** 3. `kind` == decision **decision = name** **evs_all = > plan_append_decision events=`evs_all` decision=`decision` stream=`stream`** **left = 0** 4. * **decision = "unknown"** **left = 0**
out =
| decision | reply | observation | events | llm_calls | tokens |
|---|---|---|---|---|---|
decision |
last_reply |
last_obs |
evs_all |
llm_calls |
tokens |
transport_errout = table.put in=outat="error" value=transport_err-
_ = 1 out
plan_echo_decompose
+ `workbook`
+ `stream`=False
+ `echo`=False
Pre-run parent decompose marker. With stream=True, publish {type:decompose} so view is not silent before the first child.
streamev=
| type | workbook |
|---|---|
| decompose | workbook |
sys.stream_publish event=
ev
echo> print text=plan:decompose-
**_ = 1**
ev 2. *
plan_echo_await
+ `round`
+ `workbook`
+ `stream`=False
+ `echo`=False
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).
streamev=
| type | round | workbook |
|---|---|---|
| await | round |
workbook |
sys.stream_publish event=
ev
echo> print text=plan:await > print text=round-
**_ = 1**
ev 2. *
workbook_has_worker_step
+ `path`
True when source still contains worker.step or .单步.
src = > fs.read_text path=path
a = > split value=src sep="worker.step"
na = > len value=a
b = > split value=src sep=".单步"
nb = > len value=b
na> 1 1nb> 1 1-
0
plan_append_round
+ `events`
+ `round`
+ `workbook`
+ `exit_code`
+ `result`=None
+ `stream`=False
+ `echo`=False
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 |
resultev = table.put in=evat="result" value=result-
_ = 1
events = > table.append list=events item=ev
stream
sys.stream_publish event=
ev
_ = 1
echo
print text=plan:round
_ = 1
events
plan_append_decision
+ `events`
+ `decision`
+ `stream`=False
+ `summary`=None
Always append a decision event. SSE publish only when stream=True.
ev =
| type | decision |
|---|---|
| decision | decision |
summaryev = table.put in=evat="summary" value=summary-
_ = 1
events = > table.append list=events item=ev
stream
sys.stream_publish event=
ev
_ = 1
events
plan_merge_deltas
+ `events`
+ `from`
+ `stream`=False
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.
evt = > json.get value=evkey="type"t== delta events = > table.append list=eventsitem=evt== reasoning events = > table.append list=eventsitem=evt== error events = > table.append list=eventsitem=ev-
events
plan_finish_stream
+ `out`
+ `events`
+ `stream`=False
+ `trace`=False
+ `result`=None
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.
ev = > table.put in=None at="type" value="done"
resultev = > table.put in=evat="result" value=result-
_ = 1
eventsevents = > table.append list=eventsitem=ev-
events = > table.append list=None item=ev
stream
sys.stream_publish event=
ev
_ = 1
- not
outout = > table.empty_map -
_ = 1
out = > table.put in=out at="events" value=events
tracebody = > json.stringify value=events
wb.record value=
bodykey="trace"
_ = 1
out
agent
+ `model`
+ `tools`
+ `standing`
Load ABI v2 agent plugin once (session bag + context queries).
p = > plugin.native_path name="agent"
p
plugin.load path=
p
print text=ext/ai/agent: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent) sys.exit code=1
id = > agent_alloc
h =
| _type | id | model | tools |
|---|---|---|---|
| agent | id |
model |
tools |
standingh = table.put in=hat="standing" value=standing-
_ = 1
h
clear_history
Clear the plugin session bag for this agent id.
id = > json.get value=self key="id"
agent_history_clear id=
id
resolve
+ `task`
+ `kb_dir`=.marqdo/agent-kb
+ `near_match`=True
+ `near_threshold`=0.78
Skill resolver (v2): exact → alias → canonical → near. Returns mode / resource / llm_free / confidence. Plugin ABI — no core host_* calls.
tools = > json.get value=self key="tools"
> agent_resolve task=task kb_dir=kb_dir near_match=near_match near_threshold=near_threshold tools=tools
route
+ `task`
+ `backend`=auto
+ `kb_dir`=.marqdo/agent-kb
+ `memory_dir`=.marqdo/agent-memory
+ `threshold`=0.78
+ `step_kind`=None
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_kindsr = step_route kind=step_kindbackend = > json.get value=srkey="backend"-
_ = 1
tools = > json.get value=self key="tools"
> agent_route task=task backend=backend kb_dir=kb_dir memory_dir=memory_dir threshold=threshold tools=tools
route_apply
+ `task`
+ `reply`
+ `kb_dir`=.marqdo/agent-kb
+ `backend`=small-llm
Apply a router model line (SKILL:<slug> / EXPLORE) to a kb skill hit.
> agent_route_apply task=task reply=reply kb_dir=kb_dir backend=backend
compile_policy
+ `memory_dir`=.marqdo/agent-memory
+ `min_evidence`=3
+ `force`=False
Policy Compilation: stable episode skill selections → policies/router.mq.md (deterministic Marqdo rules).
> agent_compile_policy memory_dir=memory_dir min_evidence=min_evidence force=force
maybe_compile_policy
+ `memory_dir`=.marqdo/agent-memory
+ `min_evidence`=3
Learn gate for the Adaptive Router policy layer.
> agent_maybe_compile_policy memory_dir=memory_dir min_evidence=min_evidence
record_episode
+ `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
Persist one run as .mq.md under memory_dir/episodes/YYYY/MM/ (v2 Phase 1). Memory is executable documentation, not a vector bag.
> 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`
+ `kb_dir`=.marqdo/agent-kb
+ `reason`=sandbox_or_harness_failed
O5: mark OKF skill status: quarantine and force llm_free: false. Regression fixtures stay with the slug.
> agent_kb_quarantine kb_dir=kb_dir slug=slug reason=reason
maybe_learn
+ `task`
+ `kb_dir`=.marqdo/agent-kb
+ `memory_dir`=.marqdo/agent-memory
+ `improve_every`=3
+ `promote`=True
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.
skill_learn = > agent_maybe_learn task=task kb_dir=kb_dir memory_dir=memory_dir improve_every=improve_every promote=promote
policy_learn = > agent_maybe_compile_policy memory_dir=memory_dir min_evidence=improve_every
sl = > json.get value=skill_learn key="learned"
out =
| learned | skill | policy |
|---|---|---|
sl |
skill_learn |
policy_learn |
out
compile
+ `task`
+ `kb_dir`=.marqdo/agent-kb
+ `memory_dir`=.marqdo/agent-memory
+ `min_evidence`=3
+ `promote`=True
+ `force`=False
Compile a candidate skill into versioned skills/<slug>/vN.mq.md and optionally promote into agent-kb.
> agent_compile_skill task=task kb_dir=kb_dir memory_dir=memory_dir min_evidence=min_evidence promote=promote force=force
metrics
+ `memory_dir`=.marqdo/agent-memory
Reasoning amortization stats over recorded episodes (avg_llm_calls, compiled_runs, …).
> agent_metrics memory_dir=memory_dir
run
+ `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
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.
efi_pf = None
efiefi_pf = >self.preflight task=task-
_ = 1
routed = > self.route task=task backend=router kb_dir=kb_dir memory_dir=memory_dir threshold=near_threshold
route_matched = > json.get value=routed key="matched"
needs_llm = > json.get value=routed key="needs_llm"
exec_mode = "explore"
llm_calls = 0
tokens = 0
token_cost = 0
out = None
route_backend = > json.get value=routed key="backend"
-
route_matchedpath = > json.get value=routedkey="resource" -
pathaw = await_workbook path=pathsandbox=sandboxsandbox_profile=sandbox_profilecode = > json.get value=awkey="code" child_val = > json.get value=awkey="value" last_obs = > json.get value=awkey="observation" 1.code== 0agent_kb_record_hit kb_dir=
kb_dirgoal=taskimprove_every=improve_everylf = > json.get value=routedkey="llm_free"lfexec_mode = "compiled"-
exec_mode = "routed" rmode = > json.get value=
routedkey="mode" sk = > json.get value=routedkey="skill" **out = **status goal result workbook cache match skill observation summary route ok taskchild_valpathhit rmodesklast_obsadaptive route hit routedllm_calls = 0 2. * route_matched = False
-
**route_matched = False**
_ = 1
-
route_matched_ = 1 -
needs_llm -
router_modelprompt = > json.get value=routedkey="prompt" turn = model_turn model=router_modelprompt=promptstream=streamecho=echoreply = > json.get value=turnkey="text" llm_calls = > json.get value=turnkey="llm_calls" tokens = > json.get value=turnkey="tokens" applied = >self.route_apply task=taskreply=replykb_dir=kb_dirbackend=routeram = > json.get value=appliedkey="matched" 1.ampath = > json.get value=appliedkey="resource" aw = await_workbook path=pathsandbox=sandboxsandbox_profile=sandbox_profilecode = > json.get value=awkey="code" child_val = > json.get value=awkey="value" last_obs = > json.get value=awkey="observation"code== 0 exec_mode = "routed" sk = > json.get value=appliedkey="skill" **out = **
status goal result workbook cache match skill observation summary route ok taskchild_valpathsoft-hit routed sklast_obsrouter model selected skill appliedroute_matched = True 2. * route_matched = False 2. * route_matched = False
-
**route_matched = False**
_ = 1
-
route_matched_ = 1 -
-
efi_pfefi_st = > json.get value=efi_pfkey="status" efi_dec = > json.get value=efi_pfkey="decision" efi_allow = > json.get value=efi_pfkey="create_allowed" 1.efi_st== "missing_knowledge" _ = 1 2.efi_dec== "REUSE" _ = 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_pfexec_mode = "efi"
-
**_ = 1**
out_ = 1-
resolved = > self.resolve task=task kb_dir=kb_dir near_match=near_match near_threshold=near_threshold
mode = > json.get value=resolved key="mode"
llm_free = > json.get value=resolved key="llm_free"
-
not
llm_freellm_free = False -
llm_freepath = > json.get value=resolvedkey="resource" aw = await_workbook path=pathsandbox=sandboxsandbox_profile=sandbox_profilecode = > json.get value=awkey="code" child_val = > json.get value=awkey="value" last_obs = > json.get value=awkey="observation" 1.code== 0agent_kb_record_hit kb_dir=
kb_dirgoal=taskimprove_every=improve_everyexec_mode = "compiled" sk = > json.get value=resolvedkey="skill" **out = **status goal result workbook cache match skill observation summary ok taskchild_valpathhit modesklast_obscompiled skill (llm_free) llm_calls = 0 2. * out = >
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=forceexec_mode = "explore" llm_calls = 1 -
**out = > `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`**
**cache = > json.get value=`out` key="cache"**
1. `cache` == "hit"
**exec_mode = "compiled"**
**llm_calls = 0**
2. `cache` == "soft-hit"
**exec_mode = "near"**
**llm_calls = 0**
3. *
**exec_mode = "explore"**
**llm_calls = 1**
st = > json.get value=out key="status"
res = > json.get value=out key="result"
wb_path = > json.get value=out key="workbook"
obs = > json.get value=out key="observation"
sk2 = > json.get value=out key="skill"
cache2 = > json.get value=out key="cache"
match2 = > json.get value=out key="match"
err = > json.get value=out key="error"
verifyst== "ok" verification = "status: passed"-
**verification = "status: failed"**
verification = "status: skipped"
ep = > 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
learning = None
learnst== "ok" learning = >self.maybe_learn task=taskkb_dir=kb_dirmemory_dir=memory_dirimprove_every=improve_everypromote=promote-
**learning = None**
_ = 1
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 |
out = table.put in=out at="execution" value=execution
out = table.put in=out at="episode" value=ep
out = table.put in=out at="route" value=routed
out = table.put in=out at="usage" value=usage
out = table.put in=out at="token_cost" value=token_cost
learningout = table.put in=outat="learning" value=learning-
_ = 1
efi_pfout = table.put in=outat="efi" value=efi_pf-
_ = 1
resume_id_ckpt = resume_save id=resume_idgoal=tasktask=taskstatus=stround=1 workbook=wb_pathresult=resroute=routedresume_dir=resume_dirout = table.put in=outat="resume" value=_ckpt-
_ = 1
out
step
+ `task`
+ `writeback`=True
+ `stream`=False
+ `echo`=False
+ `max_reads`=2
+ `sandbox`=False
+ `sandbox_profile`=default
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.
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=).
id = > json.get value=self key="id"
model = > json.get value=self key="model"
tools = > json.get value=self key="tools"
user_turn =
| role | content |
|---|---|
| user | task |
agent_history_append id=
iditem=user_turn
source_depth = "default" skill_depth = "default" reads_left = max_reads reply = None decision = None llm_calls = 0 tokens = 0
transport_err = None
reads_left> 0decisionreads_left = 0transport_errreads_left = 0-
selftask=tasksource_depth=source_depthskill_depth=skill_depthturn = > model_turn model=modelprompt=ctxstream=streamecho=echoterr = > json.get value=turnkey="error"terrtransport_err =terrreads_left = 0-
**reply = > json.get value=`turn` key="text"** **c = > json.get value=`turn` key="llm_calls"** **t = > json.get value=`turn` key="tokens"** **llm_calls = llm_calls + c** **tokens = tokens + t** **reply = > trim value=`reply`** **rk = > extract_plan_read reply=`reply`** 1. `rk` == source **source_depth = "deep"** **reads_left = reads_left - 1** 2. `rk` == skill **skill_depth = "deep"** **reads_left = reads_left - 1** 3. * **decision = reply** **reads_left = 0**
transport_errout=
| status | task | error | llm_calls | tokens |
|---|---|---|---|---|
| error | task |
transport_err |
llm_calls |
tokens |
writebackbody = > json.stringify value=out> wb.record value=bodykey="error"-
**_ = 1**
out 2. * _ = 1
reply = > trim value=reply
decision = reply
tool_name = > extract_tool_name reply=reply
out =
| status | task | decision |
|---|---|---|
| ok | task |
decision |
tool_nametool_out = > run_tool tools=toolsname=tool_nametool_s = > json.stringify value=tool_outdeny = > split value=tool_ssep="Tool not allowed" deny_n = > len value=denydeny_n> 1 task_s = > json.stringify value=taskfp = "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" fp = fp + task_s turn2 = > model_turn model=modelprompt=fpstream=streamecho=echoreply = > json.get value=turn2key="text" c = > json.get value=turn2key="llm_calls" t = > json.get value=turn2key="tokens" llm_calls = llm_calls + c tokens = tokens + t out = table.put in=outat="denied_tool" value=tool_nameout = table.put in=outat="result" value=reply-
**task_s = > json.stringify value=`task`**
**fp = "The user asked:"**
**fp = fp + task_s**
**fp = fp + ". Tool"**
**fp = fp + tool_name**
**fp = fp + "ran via subtask and returned:"**
**fp = fp + tool_s**
**fp = fp + ". Reply to the user briefly."**
**turn2 = > model_turn model=`model` prompt=`fp` stream=`stream` echo=`echo`**
**reply = > json.get value=`turn2` key="text"**
**c = > json.get value=`turn2` key="llm_calls"**
**t = > json.get value=`turn2` key="tokens"**
**llm_calls = llm_calls + c**
**tokens = tokens + t**
**out = table.put in=`out` at="tool" value=`tool_name`**
**out = table.put in=`out` at="tool_result" value=`tool_s`**
**out = table.put in=`out` at="result" value=`reply`**
out = table.put in=out at="result" value=reply
out = table.put in=out at="llm_calls" value=llm_calls
out = table.put in=out at="tokens" value=tokens
sandboxprof = sandbox.profile name=sandbox_profileout = table.put in=outat="sandbox_profile" value=prof-
_ = 1
as_turn =
| role | content |
|---|---|
| assistant | reply |
agent_history_append id=
iditem=as_turn
writebackbody = > json.stringify value=outst = > json.get value=outkey="status"st== "ok" > wb.record value=bodykey="ok"-
> wb.record value=`body` key="error"
_ = 1
out
preflight
+ `task`
+ `root`="."
+ `marqdo_dir`=None
+ `min_candidates`=3
+ `allow_create_after`=2
+ `reuse_threshold`=0.72
+ `adapt_threshold`=0.45
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_dirpf = > agent_eng_preflight task=taskroot=rootmarqdo_dir=marqdo_dirmin_candidates=min_candidatesallow_create_after=allow_create_afterreuse_threshold=reuse_thresholdadapt_threshold=adapt_threshold-
pf = > 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
pf
eng_reuse
+ `task`
+ `root`="."
+ `marqdo_dir`=None
Alias of preflight focused on REUSE / ADAPT / CREATE payload.
marqdo_dir> agent_eng_reuse task=taskroot=rootmarqdo_dir=marqdo_dir-
> agent_eng_reuse task=task root=root
eng_record
+ `decision`
+ `root`="."
+ `marqdo_dir`=None
+ `duplicated`=False
Record REUSE/ADAPT/CREATE into .marqdo/agent/episodes/reuse_metrics.json.
marqdo_dir> agent_eng_record decision=decisionroot=rootmarqdo_dir=marqdo_dirduplicated=duplicated-
> agent_eng_record decision=decision root=root duplicated=duplicated
plan
+ `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
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.
tools = > json.get value=self key="tools"
cache = "miss"
path = None
improve = None
explore = None
explore_attempt = None
skel_kind = skeleton
events = > table.empty_list
eng = None
eng_preflighteng = > agent_eng_preflight task=goalmarqdo_dir=marqdo_dirallow_create_after=allow_create_aftereng_status = > json.get value=engkey="status" eng_decision = > json.get value=engkey="decision" eng_allowed = > json.get value=engkey="create_allowed"eng_status== missing_knowledge _ = 1eng_decision== REUSE > agent_eng_record decision="REUSE" marqdo_dir=marqdo_dir_ = 1eng_decision== ADAPT > agent_eng_record decision="ADAPT" marqdo_dir=marqdo_dir_ = 1eng_allowed> agent_eng_record decision="CREATE" marqdo_dir=marqdo_dir_ = 1-
`out` =
| status | cache | eng | decision | preflight | events |
|--------|-------|-----|----------|-----------|--------|
| blocked | eng-block | true | BLOCKED | `eng` | `events` |
*out*
_ = 1
tf = > agent_kb_task_files kb_dir=kb_dir goal=goal tools=tools
nfiles = > json.get value=tf key="count"
-
force_ = 1 -
optimize_ = 1 -
reusehit = > agent_kb_lookup kb_dir=kb_dirgoal=goaltools=toolsnear_match=near_matchnear_threshold=near_threshold -
hitmatch_kind = > json.get value=hitkey="match" 1.match_kind== alias cache_label = "soft-hit" 2.match_kind== canonical cache_label = "soft-hit" hit_slug = > json.get value=hitkey="slug"agent_kb_add_alias kb_dir=
kb_dirslug=hit_slugalias=goal3.match_kind== near cache_label = "soft-hit" hit_slug = > json.get value=hitkey="slug" agent_kb_add_alias kb_dir=kb_dirslug=hit_slugalias=goal4.match_kind== soft cache_label = "soft-hit" 5. * cache_label = "hit" lf = > json.get value=hitkey="llm_free" 1.lfpath = > json.get value=hitkey="resource" aw = > await_workbook path=pathcode = > json.get value=awkey="code" child_val = > json.get value=awkey="value" last_obs = > json.get value=awkey="observation"code== 0
agent_kb_record_hit kb_dir=
kb_dirgoal=goaltools=toolsimprove_every=improve_everycache = cache_label hit_score = > json.get value=hitkey="score" sk = > json.get value=hitkey="skill" st = > json.get value=hitkey="status" sum = > json.parse text={"a":"OKF llm_free skill hit (","b":"); spawned resource"} suma = > json.get value=sumkey="a" sumb = > json.get value=sumkey="b" sum = suma + match_kind + sumbout=status goal workbook rounds cache match skill skill_status summary observation result ok goalpath1 cache_labelmatch_kindskstsumlast_obschild_valhit_scoreout = table.put in=outat="score" value=hit_score-
**_ = 1**events = > plan_append_decision events=
eventsdecision="REUSE" stream=streamsummary=sumevents = > plan_append_round events=eventsround=1 workbook=pathexit_code=coderesult=child_valstream=streamecho=echowritebackbody = > json.stringify value=out> wb.record value=bodykey="ok"-
**_ = 1**out = > plan_finish_stream out=
outevents=eventsstream=streamtrace=traceresult=child_valout 2. * path = None 2.nfiles<explore_nexplore = 1 cache = "explore" path = None explore_attempt = nfiles + 1explore_attempt== 2 skel_kind = "dual"-
skel_kind = skeleton 3. * path = > json.get value=
hitkey="resource" aw = > await_workbook path=pathcode = > json.get value=awkey="code" child_val = > json.get value=awkey="value" last_obs = > json.get value=awkey="observation"code== 0 rec = > agent_kb_record_hit kb_dir=kb_dirgoal=goaltools=toolsimprove_every=improve_everydue = > json.get value=reckey="improve_due"dueimprove = 1 cache = "improve"-
**cache = cache_label** **hit_score = > json.get value=`hit` key="score"** **sk = > json.get value=`hit` key="skill"** **st = > json.get value=`hit` key="status"** **sum = > json.parse text={"a":"OKF skill hit (","b":"); spawned resource"}** **suma = > json.get value=`sum` key="a"** **sumb = > json.get value=`sum` key="b"** **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` **out = table.put in=`out` at="score" value=`hit_score`** 2. * **_ = 1** **events = > plan_append_decision events=`events` decision="REUSE" stream=`stream` summary=`sum`** **events = > plan_append_round events=`events` round=1 workbook=`path` exit_code=`code` result=`child_val` stream=`stream` echo=`echo`** 1. `writeback` **body = > json.stringify value=`out`** > wb.record value=`body` key="ok" 2. * **_ = 1** **out = > plan_finish_stream out=`out` events=`events` stream=`stream` trace=`trace` result=`child_val`** *out*path = None
-
1. `soft_match`
**near = > agent_kb_near_match kb_dir=`kb_dir` goal=`goal`**
**tasks = > json.get value=`near` key="candidates"**
**tn = > len value=`tasks`**
1. `tn` < 1
**listed = > agent_kb_list_tasks kb_dir=`kb_dir`**
**tasks = > json.get value=`listed` key="tasks"**
**tn = > len value=`tasks`**
2. *
**_ = 1**
1. `tn` > 0
**soft_prompt = > build_soft_match_prompt goal=`goal` tasks=`tasks`**
**model = > json.get value=`self` key="model"**
1. `stream`
**evs = > model.stream prompt=`soft_prompt` echo=`echo`**
**soft_reply = > llm.collect events=`evs`**
**events = > plan_merge_deltas events=`events` from=`evs` stream=`stream`**
2. *
**soft_turn = > model_turn model=`model` prompt=`soft_prompt` stream=False echo=`echo`**
**soft_reply = > json.get value=`soft_turn` key="text"**
**soft_reply = > trim value=`soft_reply`**
**soft_dec = > extract_plan_decision reply=`soft_reply`**
**events = > plan_append_decision events=`events` decision=`soft_dec` stream=`stream`**
1. `soft_dec` == REUSE
**reuse_slug = > extract_soft_match_slug reply=`soft_reply`**
1. `reuse_slug`
**hit = > agent_kb_lookup kb_dir=`kb_dir` slug=`reuse_slug` goal=`goal` tools=`tools`**
1. `hit`
> agent_kb_add_alias kb_dir=`kb_dir` slug=`reuse_slug` alias=`goal`
**cache_label = "soft-hit"**
**path = > json.get value=`hit` key="resource"**
**aw = > await_workbook path=`path`**
**code = > json.get value=`aw` key="code"**
**child_val = > json.get value=`aw` key="value"**
**last_obs = > json.get value=`aw` key="observation"**
1. `code` == 0
> agent_kb_record_hit kb_dir=`kb_dir` goal=`goal` tools=`tools` improve_every=`improve_every`
**cache = "soft-hit"**
**sk = > json.get value=`hit` key="skill"**
**st = > json.get value=`hit` key="status"**
**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` |
**events = > plan_append_decision events=`events` decision="REUSE" stream=`stream` summary=`sum`**
**events = > plan_append_round events=`events` round=1 workbook=`path` exit_code=`code` result=`child_val` stream=`stream` echo=`echo`**
1. `writeback`
**body = > json.stringify value=`out`**
> wb.record value=`body` key="ok"
2. *
**_ = 1**
**out = > plan_finish_stream out=`out` events=`events` stream=`stream` trace=`trace` result=`child_val`**
*out*
2. *
**path = None**
2. *
**_ = 1**
2. *
**_ = 1**
2. *
**_ = 1**
2. *
**_ = 1**
2. *
**_ = 1**
1. `nfiles` < `explore_n`
**explore = 1**
**cache = "explore"**
**explore_attempt = nfiles + 1**
1. `explore_attempt` == 2
**skel_kind = "dual"**
2. *
**skel_kind = skeleton**
2. *
**_ = 1**
-
nfiles<explore_nexplore = 1 cache = "explore" explore_attempt = nfiles + 1-
**_ = 1**
skel = > render_workbook_skeleton goal=goal skeleton=skel_kind
workbookpath = workbook ex = > fs.exists path=pathex_ = 1-
> fs.write_text path=`path` text=`skel`
-
path_ = 1-
**slug = > agent_goal_slug goal=`goal`**
1. `workbook_dir`
> fs.make_dir path=`workbook_dir`
**ts = > time.now_ms**
**parts = > json.parse text={"a":"/workbook-","b":"-","c":".mq.md"}**
**a = > json.get value=`parts` key="a"**
**b = > json.get value=`parts` key="b"**
**c = > json.get value=`parts` key="c"**
**path = workbook_dir + a + slug + b + ts + c**
> fs.write_text path=`path` text=`skel`
2. `explore`
**parts = > json.parse text={"a":"/explore/","b":"/","c":".mq.md"}**
**a = > json.get value=`parts` key="a"**
**b = > json.get value=`parts` key="b"**
**c = > json.get value=`parts` key="c"**
**path = kb_dir + a + slug + b + explore_attempt + c**
**ex = > fs.exists path=`path`**
1. `ex`
**_ = 1**
2. *
> fs.write_text path=`path` text=`skel`
3. *
**parts = > json.parse text={"a":"/resources/","b":".mq.md"}**
**a = > json.get value=`parts` key="a"**
**b = > json.get value=`parts` key="b"**
**path = kb_dir + a + slug + b**
**ex = > fs.exists path=`path`**
1. `ex`
**_ = 1**
2. *
> fs.write_text path=`path` text=`skel`
confirmout=
| status | goal | workbook | summary | cache |
|---|---|---|---|---|
| pending | goal |
path |
workbook created; confirm to run | bypass |
writebackbody = > json.stringify value=out> wb.record value=bodykey="ok"-
**_ = 1**
out = > plan_finish_stream out=out events=events stream=stream trace=trace
out
2. *
_ = 1
model = > json.get value=self key="model"
round = 0
last_obs = None
last_reply = None
child_val = None
done = None
summary = None
status = "error"
err = "max_rounds exhausted"
skip_loop = None
plan_echo_decompose workbook=
pathstream=streamecho=echolast_obs = > inspect_workbook path=pathturn = > plan_llm_act_loop agent=selfgoal=goalpath=pathobservation=last_obsphase="decompose" explore_attempt=explore_attemptexplore_n=explore_nstream=streamecho=echoevents=eventsdec = > json.get value=turnkey="decision" last_reply = > json.get value=turnkey="reply" last_obs = > json.get value=turnkey="observation" events = > json.get value=turnkey="events"
dec== "TRANSPORT_ERROR" done = 1 status = "error" err = > json.get value=turnkey="error"- not
errerr =last_replysummary = "llm transport error" skip_loop = 1 dec== CONTINUE n = > fs.apply_patch_blocks path=pathtext=last_replysoft=Truen_ = 1-
**done = 1**
**status = "error"**
**err = "no patches applied"**
**summary = > extract_plan_summary reply=`last_reply`**
**skip_loop = 1**
dec== RUN _ = 1dec== DONE has_step = > workbook_has_worker_step path=pathhas_step_ = 1-
> plan_echo_await round=1 workbook=`path` stream=`stream` echo=`echo`
**aw = > await_workbook path=`path`**
**code = > json.get value=`aw` key="code"**
**child_val = > json.get value=`aw` key="value"**
**last_obs = > json.get value=`aw` key="observation"**
**round = 1**
**events = > plan_append_round events=`events` round=1 workbook=`path` exit_code=`code` result=`child_val` stream=`stream` echo=`echo`**
1. `code` == 0
**done = 1**
**status = "ok"**
**summary = > extract_plan_summary reply=`last_reply`**
**err = None**
**skip_loop = 1**
2. *
**_ = 1**
done = 1 status = "error" err = "unrecognized plan decision" summary = last_reply skip_loop = 1
skip_loopleft = 0improveleft = 1-
left = max_rounds
left> 0doneleft = 0-
plan_echo_await round=
roundworkbook=pathstream=streamecho=echoaw = > await_workbook path=pathcode = > json.get value=awkey="code" child_val = > json.get value=awkey="value" last_obs = > json.get value=awkey="observation" events = > plan_append_round events=eventsround=roundworkbook=pathexit_code=coderesult=child_valstream=streamecho=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`
**auto_done = None**
2. *
**auto_done = 1**
2. *
**auto_done = None**
2. *
**auto_done = None**
1. `auto_done`
> agent_workbook_solidify path=`path` observation=`last_obs`
**done = 1**
**status = "ok"**
**summary = "child returned value; solidified"**
**err = None**
**dec = "DONE"**
**events = > plan_append_decision events=`events` decision=`dec` stream=`stream` summary=`summary`**
**left = 0**
2. *
**turn = > 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`**
**dec = > json.get value=`turn` key="decision"**
**last_reply = > json.get value=`turn` key="reply"**
**last_obs = > json.get value=`turn` key="observation"**
**events = > json.get value=`turn` key="events"**
1. `dec` == DONE
> agent_workbook_solidify path=`path` observation=`last_obs`
**done = 1**
**status = "ok"**
**summary = > extract_plan_summary reply=`last_reply`**
**err = None**
**left = 0**
2. `dec` == CONTINUE
**n = > fs.apply_patch_blocks path=`path` text=`last_reply` soft=True**
1. `n`
**left = left - 1**
2. *
**done = 1**
**status = "error"**
**err = "no patches applied"**
**summary = > extract_plan_summary reply=`last_reply`**
**left = 0**
3. `dec` == RUN
**left = left - 1**
4. *
**done = 1**
**status = "error"**
**err = "unrecognized plan decision"**
**summary = last_reply**
**left = 0**
status== "ok"promoteprom = > agent_kb_promote kb_dir=kb_dirgoal=goalworkbook=pathtools=toolscache = "refreshed"-
**cache = "miss"**
_ = 1
out =
| status | goal | workbook | rounds | cache |
|---|---|---|---|---|
status |
goal |
path |
round |
cache |
summaryout = table.put in=outat="summary" value=summary-
_ = 1
errout = table.put in=outat="error" value=err-
_ = 1
last_obsout = table.put in=outat="observation" value=last_obs-
_ = 1
child_valout = table.put in=outat="result" value=child_valplan_result = child_valsummaryout = table.put in=outat="result" value=summaryplan_result = summary-
plan_result = None
writebackbody = > json.stringify value=outstatus== "ok" > wb.record value=bodykey="ok"-
> wb.record value=`body` key="error"
_ = 1
out = > plan_finish_stream out=out events=events stream=stream trace=trace result=plan_result
out
mcp_server
+ `name`=marqdo
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.
p = > plugin.native_path name="agent"
p
plugin.load path=
p
print text=ext/ai/agent: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent) sys.exit code=1
tools0 = > table.empty_list
h =
| _type | tools | name |
|---|---|---|
| mcp_server | tools0 |
name |
h
tool
+ `name`
+ `fn`
+ `description`=""
Register one tool. fn must be lib.member imported on the entry workbook.
tools = > json.get value=self key="tools"
- not
toolstools = > table.empty_listrow=
| name | fn | description |
|---|---|---|
name |
fn |
description |
tools = > table.append list=tools item=row
h = table.put in=self at="tools" value=tools
h
serve
+ `transport`=stdio
+ `host`="127.0.0.1"
+ `port`=7434
+ `path`="/mcp"
Block on MCP: stdio (line JSON-RPC) or http / streamable-http (Streamable HTTP, POST JSON-RPC + optional GET SSE). Spec 2025-03-26.
name = > json.get value=self key="name"
tools = > json.get value=self key="tools"
> agent_mcp_serve name=name tools=tools transport=transport host=host port=port path=path