agent_mcp_serve gains http transport; invoke injects Bearer/X-Api-Key and maps unauthorized to 401; openai/agent field access prefers json.get over footnotes. Co-authored-by: Cursor <cursoragent@cursor.com>
96 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.\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." 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