Close GAP-01–05 with ext/web streaming reverse proxy and HTTP→## invoke, transitive object method lookup, corpus_search plugin ensure, and agent MCP server stdio so downstream apps can drop Python side relays. Co-authored-by: Cursor <cursoragent@cursor.com>
71 KiB
title: ext/ai/agent description: Document-driven agent — step / plan; tools via lib/subtask; runtime via ABI v2 agent plugin. 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
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
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 = > json.parse text={}
out = > json.set map=out key="prompt" value=prompt
out = > json.set map=out key="call_site" value=site
out = > json.set map=out key="prompt_chars" value=chars
out = > json.set map=out key="truncated" value=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 = > json.parse text=[] \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=True \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=True \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=True \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 = > json.parse text={"path":""}
obs = > json.set map=obs key="path" value=path
obs = > json.set map=obs key="source" value=source
obs = > json.set map=obs key="slots" value=slots
obs = > json.set map=obs key="exit_code" value=exit_code
valueobs = > json.set map=obskey="value" value=value-
_ = 1
stdoutobs = > json.set map=obskey="stdout" value=stdout-
_ = 1
stderrobs = > json.set map=obskey="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 = > json.set map=obskey="last_ok" value=last_ok-
_ = 1
last_errorobs = > json.set map=obskey="last_error" value=last_error-
_ = 1
obs
await_workbook
+ `path`
Spawn a workbook file (quiet by default), wait for {code,value,stdout?,stderr?}, and inspect.
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 = > json.parse text={"code":0}
out = > json.set map=out key="code" value=code
out = > json.set map=out key="value" value=value
out = > json.set map=out key="observation" 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 = > json.parse text=[]
chars = 0
count = 0
linecount<max_linesln = > len value=linenext = chars + lnnext>max_charscount = max_lines-
*acc = > json.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 = > json.parse text=[] i = 0 chars = 0
linei>=startln = > len value=linenext = chars + lnnext>max_charsi = n-
*acc = > json.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 = > json.parse text=[]
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 = > json.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 = > json.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
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 = > json.parse text={}
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 = > json.parse text={}
ev = > json.set map=ev key="type" value=type
ev = > json.set map=ev key="name" value=name
ev = > json.set map=ev key="kind" value=kind
resultev = > json.set map=evkey="result" value=result-
_ = 1
events = > json.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 = > json.parse text={"ok":True} out = > json.set map=outkey="path" value=pathout
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 = > json.parse text={"kind":"call"} out = > json.set map=outkey="name" value=toolout-
_ = 1
rk = > extract_plan_read reply=reply
rkout = > json.parse text={"kind":"read"} out = > json.set map=outkey="name" value=rkout-
_ = 1
dec = > extract_plan_decision reply=reply
decout = > json.parse text={"kind":"decision"} out = > json.set map=outkey="name" value=decout-
out = > json.parse text={"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 = > json.parse text=[]
in_body = None
linein_bodyt = > trim value=linet==closein_body = None-
*body_lines = > json.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 = > json.parse text={}
out = > json.set map=out key="name" value=name
out = > json.set map=out key="text" value=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 = > json.set map=obskey="source_excerpt" value=exobs = > json.set map=obskey="read_source" value=Truekind== stderr err = > json.get value=obskey="stderr" tail = > text_tail_lines text=errmax_lines=80 max_chars=6000 obs = > json.set map=obskey="stderr_tail" value=tailobs = > json.set map=obskey="read_stderr" value=Truekind== stdout out = > json.get value=obskey="stdout" tail = > text_tail_lines text=outmax_lines=80 max_chars=6000 obs = > json.set map=obskey="stdout_tail" value=tailobs = > json.set map=obskey="read_stdout" value=Truekind== slots slots = > json.get value=obskey="slots" obs = > json.set map=obskey="slots_detail" value=slotsobs = > json.set map=obskey="read_slots" value=Truekind== skill brief = > skill_brief depth="deep" obs = > json.set map=obskey="skill_brief" value=briefobs = > json.set map=obskey="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 = > json.parse text={"note":"Plan-and-Move: CALL/READ then DECISION. Success (exit 0 + has_value) → DONE. solidify_on_done. No long prose."}
compact = > json.set map=compact key="path" value=obs_path
compact = > json.set map=compact key="exit_code" value=obs_code
compact = > json.set map=compact key="source_len" value=src_len
compact = > json.set map=compact key="has_worker_step" value=has_step
compact = > json.set map=compact key="solidify_on_done" value=True
obs_srcex = > json.get value=observationkey="source_excerpt"excompact = > json.set map=compactkey="source_excerpt" value=ex-
*ex = > workbook_source_excerpt source=`obs_src`*
*compact = > json.set map=`compact` key="source_excerpt" value=`ex`*
_ = 1
obs_stderrtail = > json.get value=observationkey="stderr_tail"tailcompact = > json.set map=compactkey="stderr_tail" value=tail-
*tail = > text_tail_lines text=`obs_stderr`*
*compact = > json.set map=`compact` key="stderr_tail" value=`tail`*
_ = 1
obs_stdouttail = > json.get value=observationkey="stdout_tail"tailcompact = > json.set map=compactkey="stdout_tail" value=tail-
*tail = > text_tail_lines text=`obs_stdout`*
*compact = > json.set map=`compact` key="stdout_tail" value=`tail`*
_ = 1
val_txt = > str value=obs_val
val_len = > len value=val_txt
obs_valcompact = > json.set map=compactkey="has_value" value=True compact = > json.set map=compactkey="value_len" value=val_lenval_len> 200 preview = > text_head_lines text=val_txtmax_lines=4 max_chars=200 compact = > json.set map=compactkey="value_preview" value=preview-
*compact = > json.set map=`compact` key="value" value=`obs_val`*
compact = > json.set map=compact key="has_value" value=False
slots_brief = > json.parse text=[]
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 = > json.parse text={"key":""} brief = > json.set map=briefkey="key" value=skbrief = > json.set map=briefkey="line" value=slbrief = > json.set map=briefkey="body_len" value=sb_lensk== error prev = > text_head_lines text=sb_txtmax_lines=8 max_chars=400 brief = > json.set map=briefkey="body_preview" value=prev-
slots_briefitem=brief
_ = 1
compact = > json.set map=compact key="slots" value=slots_brief
detail = > json.get value=observation key="slots_detail"
detailcompact = > json.set map=compactkey="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 = > json.set map=compactkey="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 = > json.set map=compactkey="last_error_preview" value=prevcompact = > json.set map=compactkey="last_error_len" value=err_len-
*compact = > json.set map=`compact` key="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 = > json.parse text=[]
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}.
model = > json.get value=agent key="model"
last_obs = observation
left = max_acts
decision = None
last_reply = None
evs_all = events
left> 0decisionleft = 0-
agentgoal=goalobservation=last_obsexplore_attempt=explore_attemptexplore_n=explore_nphase=phasestreamevs = > model.complete prompt=ctxstream=True echo=echolast_reply = > llm.stream_result events=evsevs_all = > plan_merge_deltas events=evs_allfrom=evsstream=stream-
last_reply = > trim value=*last_reply = > model.complete prompt=`ctx`*last_replyact = > extract_plan_act reply=last_replykind = > json.get value=actkey="kind" name = > json.get value=actkey="name"kind== call evs_all = > plan_append_tool events=evs_alltype="tool_start" name=namekind="call" stream=streamtool_out = > run_parent_tool name=namepath=pathobservation=last_obsreply=last_replybrief = > tool_result_brief value=tool_outevs_all = > plan_append_tool events=evs_alltype="tool_end" name=namekind="call" result=briefstream=streamlast_obs = > json.set map=last_obskey="tool_result" value=tool_outleft = left - 1kind== read evs_all = > plan_append_tool events=evs_alltype="tool_start" name=namekind="read" stream=streamlast_obs = > plan_read_deepen observation=last_obskind=namepath=pathbrief = > tool_result_brief value=last_obsevs_all = > plan_append_tool events=evs_alltype="tool_end" name=namekind="read" result=briefstream=streamleft = left - 1kind== decision decision = name evs_all = > plan_append_decision events=evs_alldecision=decisionstream=streamleft = 0-
*decision = "unknown"* *left = 0*
out = > json.parse text={}
out = > json.set map=out key="decision" value=decision
out = > json.set map=out key="reply" value=last_reply
out = > json.set map=out key="observation" value=last_obs
out = > json.set map=out key="events" value=evs_all
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 = > json.parse text={"type":"decompose"} ev = > json.set map=evkey="workbook" value=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 = > json.parse text={"type":"await"} ev = > json.set map=evkey="round" value=roundev = > json.set map=evkey="workbook" value=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 = > json.parse text={"type":"round"}
ev = > json.set map=ev key="round" value=round
ev = > json.set map=ev key="workbook" value=workbook
ev = > json.set map=ev key="exit_code" value=exit_code
resultev = > json.set map=evkey="result" value=result-
_ = 1
events = > json.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 = > json.parse text={"type":"decision"}
ev = > json.set map=ev key="decision" value=decision
summaryev = > json.set map=evkey="summary" value=summary-
_ = 1
events = > json.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 = > json.append list=eventsitem=evt== reasoning events = > json.append list=eventsitem=evt== error events = > json.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 = > json.parse text={"type":"done"}
resultev = > json.set map=evkey="result" value=result-
_ = 1
events = > json.append list=events item=ev
stream
sys.stream_publish event=
ev
_ = 1
out = > json.set map=out key="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 = > json.parse text={"_type":"agent"}
h = > json.set map=h key="id" value=id
h = > json.set map=h key="model" value=model
h = > json.set map=h key="tools" value=tools
standingh = > json.set map=hkey="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
step
+ `task`
+ `writeback`=True
+ `stream`=False
+ `echo`=False
+ `max_reads`=2
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.
id = > json.get value=self key="id"
model = > json.get value=self key="model"
tools = > json.get value=self key="tools"
user_turn = > json.parse text={"role":"user"}
user_turn = > json.set map=user_turn key="content" value=task
agent_history_append id=
iditem=user_turn
source_depth = "default" skill_depth = "default" reads_left = max_reads reply = None decision = None
reads_left> 0decisionreads_left = 0-
selftask=tasksource_depth=source_depthskill_depth=skill_depthstreamevs = > model.complete prompt=ctxstream=True echo=echoreply = > llm.stream_result events=evs-
reply = > trim value=*reply = > model.complete prompt=`ctx`*replyrk = > extract_plan_read reply=replyrk== source source_depth = "deep" reads_left = reads_left - 1rk== skill skill_depth = "deep" reads_left = reads_left - 1-
*decision = reply* *reads_left = 0*
reply = > trim value=reply
decision = reply
tool_name = > extract_tool_name reply=reply
out = > json.parse text={"status":"ok"}
out = > json.set map=out key="task" value=task
out = > json.set map=out key="decision" value=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 1.streamevs_retry = > model.complete prompt=fpstream=True echo=echoreply = > llm.stream_result events=evs_retry2. * reply = > model.complete prompt=fpout = > json.set map=outkey="status" value="ok" out = > json.set map=outkey="decision" value=decisionout = > json.set map=outkey="denied_tool" value=tool_nameout = > json.set map=outkey="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."*
1. `stream`
*evs2 = > model.complete prompt=`fp` stream=True echo=`echo`*
*reply = > llm.stream_result events=`evs2`*
2. *
*reply = > model.complete prompt=`fp`*
*out = > json.set map=`out` key="tool" value=`tool_name`*
*out = > json.set map=`out` key="tool_result" value=`tool_s`*
*out = > json.set map=`out` key="result" value=`reply`*
out = > json.set map=out key="result" value=reply
as_turn = > json.parse text={"role":"assistant"}
as_turn = > json.set map=as_turn key="content" value=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
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
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.
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 = > json.parse text=[]
tf = > agent_kb_task_files kb_dir=kb_dir goal=goal tools=tools
nfiles = > json.get value=tf key="count"
force_ = 1optimize_ = 1reusehit = > agent_kb_lookup kb_dir=kb_dirgoal=goaltools=toolsnear_match=near_matchnear_threshold=near_thresholdhitmatch_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 out = > json.parse text={"status":"ok"} out = > json.set map=outkey="status" value="ok" out = > json.set map=outkey="goal" value=goalout = > json.set map=outkey="workbook" value=pathout = > json.set map=outkey="rounds" value=1 out = > json.set map=outkey="cache" value=cache_labelout = > json.set map=outkey="match" value=match_kindhit_score = > json.get value=hitkey="score"hit_scoreout = > json.set map=outkey="score" value=hit_score-
sk = > json.get value=*_ = 1*hitkey="skill" out = > json.set map=outkey="skill" value=skst = > json.get value=hitkey="status" out = > json.set map=outkey="skill_status" value=stsum = > 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 + sumb out = > json.set map=outkey="summary" value=sumout = > json.set map=outkey="observation" value=last_obsout = > json.set map=outkey="result" value=child_valevents = > 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"-
out = > plan_finish_stream out=*_ = 1*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"-
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* *out = > json.parse text={"status":"ok"}* *out = > json.set map=`out` key="status" value="ok"* *out = > json.set map=`out` key="goal" value=`goal`* *out = > json.set map=`out` key="workbook" value=`path`* *out = > json.set map=`out` key="rounds" value=1* *out = > json.set map=`out` key="cache" value=`cache_label`* *out = > json.set map=`out` key="match" value=`match_kind`* *hit_score = > json.get value=`hit` key="score"* 1. `hit_score` *out = > json.set map=`out` key="score" value=`hit_score`* 2. * *_ = 1* *sk = > json.get value=`hit` key="skill"* *out = > json.set map=`out` key="skill" value=`sk`* *st = > json.get value=`hit` key="status"* *out = > json.set map=`out` key="skill_status" value=`st`* *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 = > json.set map=`out` key="summary" value=`sum`* *out = > json.set map=`out` key="observation" value=`last_obs`* *out = > json.set map=`out` key="result" value=`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**-
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.complete prompt=`soft_prompt` stream=True echo=`echo`*
*soft_reply = > llm.stream_result events=`evs`*
*events = > plan_merge_deltas events=`events` from=`evs` stream=`stream`*
2. *
*soft_reply = > model.complete prompt=`soft_prompt`*
*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"*
*out = > json.parse text={"status":"ok"}*
*out = > json.set map=`out` key="status" value="ok"*
*out = > json.set map=`out` key="goal" value=`goal`*
*out = > json.set map=`out` key="workbook" value=`path`*
*out = > json.set map=`out` key="rounds" value=1*
*out = > json.set map=`out` key="cache" value="soft-hit"*
*out = > json.set map=`out` key="match" value="soft"*
*sk = > json.get value=`hit` key="skill"*
*out = > json.set map=`out` key="skill" value=`sk`*
*st = > json.get value=`hit` key="status"*
*out = > json.set map=`out` key="skill_status" value=`st`*
*sum = "OKF soft_match REUSE; spawned resource"*
*out = > json.set map=`out` key="summary" value=`sum`*
*out = > json.set map=`out` key="observation" value=`last_obs`*
*out = > json.set map=`out` key="result" value=`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*
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*
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*
> fs.write_text path=`path` text=`skel`
confirmout = > json.parse text={"status":"pending"} out = > json.set map=outkey="goal" value=goalout = > json.set map=outkey="workbook" value=pathout = > json.set map=outkey="summary" value="workbook created; confirm to run" out = > json.set map=outkey="cache" value="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== 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 = > json.parse text={"status":"ok"}
out = > json.set map=out key="status" value=status
out = > json.set map=out key="goal" value=goal
out = > json.set map=out key="workbook" value=path
out = > json.set map=out key="rounds" value=round
out = > json.set map=out key="cache" value=cache
summaryout = > json.set map=outkey="summary" value=summary-
_ = 1
errout = > json.set map=outkey="error" value=err-
_ = 1
last_obsout = > json.set map=outkey="observation" value=last_obs-
_ = 1
child_valout = > json.set map=outkey="result" value=child_valplan_result = child_valsummaryout = > json.set map=outkey="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). 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
h = > json.parse text={"_type":"mcp_server","tools":[]}
h = > json.set map=h key="name" value=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"
row = > json.parse text={"name":"","fn":"","description":""}
row = > json.set map=row key="name" value=name
row = > json.set map=row key="fn" value=fn
row = > json.set map=row key="description" value=description
tools = > json.append list=tools item=row
h = > json.set map=self key="tools" value=tools
h
serve
+ `transport`=stdio
Block on stdio MCP (initialize / tools/list / tools/call). HTTP transport is H4b.
name = > json.get value=self key="name"
tools = > json.get value=self key="tools"
> agent_mcp_serve name=name tools=tools transport=transport