Repository navigation
Version 4.12.30, 11/5/2026
The lock-step twin of Java 4.12.30, catching up from 4.12.27 with every common feature the Java engine shipped since. Java
4.12.28 and 4.12.29 were Java only because their headline work was the mini-scheduler, which this engine does not have, so
this port takes no number for them. The agent loop llm.run arrives in the new opt-in crate mercury-agent-loop, the
thirteenth published crate (Added 3); a graph run gains an asynchronous graph.extension (Added 2) and progress events for
a caller that watches it, with the WebSocket entry /ws/graph-run/{graph_id} (Added 4); the Playground panel takes its name
from playground.panel.name and the Playground bundle and help are redeployed (Added 5); the AI companion broker, renamed
from the Playground session broker and kept once in the starter template, can subscribe to a session a human opened first
(Added 6, Changed 4); an aborted flow whose caller cannot be told is recorded in the log (Changed 2). Upgrade notes:
CompileGraph refuses a blank progress and an input mapping to header.x-return-path, and graph.progress.*,
graph.run.socket.reply and, once an application links mercury-agent-loop, llm.run are reserved route names (Added 3
and 4). A command or a note that names scripts/playground-session-broker.mjs names scripts/ai-companion-broker.mjs, run
from templates/starter-graph (Changed 4).
Added
- The envelope golden vector
standard-trace-context(Increment 195). The Java engine added it in mercury-composable
#213 (2026-07-21) after this engine's conformance review found that no vector carriedspan_id, the field that parents a
trace across languages; this repository's copy ofvectors.jsonwas never re-synced. The file is now byte-identical with
the Java engine's and the language packs' copies, seven vectors, andenvelope_wire_formatdecodes and round-trips six
standard ones (the compact vector stays skipped). The codec passed the new vector unchanged. Upgrade note: none - a
test fixture; no shipped behaviour changes. - An asynchronous
graph.extension(Increment 197).async=truestarts the target, a deployed graph or a flow,
and continues to the next node at once, so a graph whose work runs longer than a caller waits can answer with an
advice (an HTTP 202) while the target runs. The target inherits the business correlation id and runs under its own
TTL, or the node'sttlwhen it declares one; nothing comes back, so the deployment gate refuses anoutput[]on
the node, and refusesasyncon any other skill.exception=covers only a failure to start: a target that does
not exist, or an input the target graph's rootschemarefuses, checked before the run starts. Withfor_eachthe
node starts one run per element,concurrencybounding how many are active, and checks every element's input
before any run starts. The end of each run is logged with its status. The twin of mercury-composable #609.
Upgrade note: none; a node withoutasyncruns as before. - The agent loop,
llm.run, in the new opt-in cratemercury-agent-loop(Increment 198). A graph node calls
llm.runwithgraph.task, giving it a tool catalog held on the graph, a prompt and its settings. The loop sends
each model turn tollm.chat, served by the LLM helper of mercury-python or mercury-nodejs
(extensions/llm-helper, with a transcript store configured), and calls the route each tool's name maps to. Before
the first turn it checks the whole catalog and that every route is served, so a bad catalog fails before a token is
spent. It validates each input against the row's schema (a closed JSON Schema subset), applies the node's mode to
each tool call (write, the default, holds a tool markedwrite: truefor a person;autoruns every call;
manualholds every call;unattendedrefuses a marked write), lets a row withask: trueand no route put a
question to a person, resumes from the approval block with one decision per waiting call, and stops at
max_turns, at itstimeout, at a refusal or at a cut-off turn. It answers with an envelope a decision node routes
on. When its caller names a return route inx-return-path, it sends its progress events there. Settings and their
global defaults:llm.run.max.turns(10),llm.run.result.limit(65536),llm.run.transcript.ttl(7d),
llm.run.transcript.retention(0) andllm.run.timeout(25s). The shared vector filellm-run-vectors.json(105
loop cases, 29 schema cases) is byte-identical with the Java engine's.PostOffice::send_untracedin platform-core
is now public, the send a progress event uses. The twin of mercury-composable #605 and #606. Upgrade note: none;
nothing changes until an application links the crate, andllm.runis a reserved route name once it does. - Progress events from a graph run, and the WebSocket entry
/ws/graph-run/{graph_id}(Increment 199). A caller
that watches a run gets progress events while it goes on, then one terminal event,resultorerror: on a REST
endpoint withstream: trueas server-sent events (a run that sends none still answers single-shot), on the new
WebSocket entry/ws/graph-run/{graph_id}as text frames (off by default,graph.websocket.enabled;
graph.websocket.ttl, 30m), or, for any other entry, to the route itsx-return-pathheader names when
return.path.routesdeclares it (a prefix entry ends with*; a bare*is refused at startup). A node opts in
withprogress=<text>: the engine sendsnode.start, agraph.taskfunction gets the node's relay route as
x-return-path, and a synchronous subgraph returns its events through it, sollm.run's events reach the caller.
Events carry names, routes, counts and statuses only, and are not traced. A stream the engine opens allows the
flow's TTL plus 5 seconds of idle, so the run's own terminal event always arrives first. A plain REST request is
unchanged, and an inbound HTTPx-return-pathheader has no effect.examples/kafka-demoadds
kafka.progress.publisher, a return route that publishes each event to a Kafka topic, one run per partition. The
twin of mercury-composable #611. Upgrade note: CompileGraph refuses a blankprogressand an input mapping to
header.x-return-path;graph.progress.*andgraph.run.socket.replyare reserved route names. playground.panel.namerenames the Minigraph Playground panel (Increment 200). Set it inapplication.ymlor at
launch, for example-Dplayground.panel.name='My Awesome Dev Dashboard', and the heading in the panel's top-left
corner reads that name; without it, or with a blank value, it readsMinigraph Playground.get.index.htmlwrites
the name, escaped for HTML, into the Playground page's panel-name tag in dev mode; the browser tab and the JSON-Path
playground keep their titles. The Playground bundle and help pages are redeployed from the Java repository
(index-CXcJLB42.js), so the help now coversasync=trueandprogress. The twin of mercury-composable #617.
Upgrade note: none; without the property the panel reads as before.- The AI companion broker can subscribe to a session a human opened first (Increment 201).
POST /subscribewith
{"sessionId": "ws-..."}makes the broker's own session a subscriber of that primary session, assession subscribe
typed in a browser would; the companion endpoint still refuses topology commands. The broker's session then holds a
copy of the shared draft, and when the human's session closes, the engine frees it as a primary that keeps the
work-in-progress, so the agent hands its id over and the human recovers the work by subscribing to it.GET /session
now also reportssubscribedToandsubscribers, read from the engine's own topology lines. The twin of
mercury-composable #618. Upgrade note: none; the other calls are unchanged.
Changed
- The Playground's LLM relay names the helpers' new folder (Increment 194). Both language packs moved their LLM helper
fromexamples/llm-helper/toextensions/llm-helper/(mercury-python #46, mercury-nodejs #114), so the 503 that
/api/llm/streamanswers when no helper is mapped now reads "start the LLM helper (extensions/llm-helper of
mercury-python or mercury-nodejs)". The Playground README and the commented start commands in its
event-over-http.yamlfollow. The lock-step twin of mercury-composable #601. Upgrade note: none - the route, its
status and the rest of the message are unchanged. - An aborted flow whose caller cannot be told is recorded in the log (Increment 196). A flow launched with no
callback, or whose callback route is no longer served, has nobody to tell when it aborts. The executor already
ended such a flow, but recorded nothing; it now logsFlow <id>:<instance> aborted with status <status> - <reason>,
followed by. Unable to tell <route> - <cause>when the callback route is gone. The twin of mercury-composable
#610, where the same abort had left the flow open. Upgrade note: none; one error line per such abort. - A single-shot reply that reaches a streaming HTTP response whose head is already sent is logged as such
(Increment 199). The warning reads "Single-shot reply to ... dropped - its streaming response has already
started", Java's text, where it read as an invalid stream signal; a graph run whose flow timed out after it had
streamed progress does this on every such timeout. What the client receives is unchanged. The twin of
mercury-composable #611's Changed item. Upgrade note: none. - The Playground session broker is the AI companion broker, and only the starter template carries it (Increment
201).scripts/playground-session-broker.mjsis nowscripts/ai-companion-broker.mjs, named for what it is rather
than for a word that also means a Kafka or message broker. Theminigraph-playgroundanddistributed-cache-example
examples no longer carry copies: theirscripts/README.mdruns the template's
(node ../../templates/starter-graph/scripts/ai-companion-broker.mjs --target ...), and the distributed-cache
example's points the broker at its own port, 8305, since it serves the Playground in dev mode (its README said it
did not). The twin of mercury-composable #618. Upgrade note: a command or a note that names the old file names
the new one; a project copied from the template earlier keeps its own copy, which works as before.
Documentation
- The LLM helper certification report's reproduce commands start the helpers from
extensions/llm-helper/
(Increment 194). The report's environment rows, which record the drive of 2026-10-01, keep the folder the helpers lived
in then. - How to start a human-AI collaboration (Increment 201). The AI agent guide's new Start a collaboration: the
human starts the application in a terminal to see its log, the agent starts a persistent WebSocket connection with
the AI companion broker and hands oversession subscribe {id}, and the two collaborate with the agent holding the
primary session, which never times out; a tab the browser throttles in the background is closed at the idle timeout
(websocket.idle.timeout, 60 seconds) and recovers by subscribing again. A second path covers a session the human
opened first. The session grammar and Playground and companion state what the topology does to the draft. The
configuration reference'swebsocket.idle.timeoutdrops its note that the Java engine counts minutes: both count
seconds. The twin of mercury-composable #618.