Skip to content

v4.12.30

Latest

Choose a tag to compare

@acn-ericlaw acn-ericlaw released this 05 Nov 23:38
· 31 commits to main since this release
Immutable release. Only release title and notes can be modified.
852c297

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

  1. 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 carried span_id, the field that parents a
    trace across languages; this repository's copy of vectors.json was never re-synced. The file is now byte-identical with
    the Java engine's and the language packs' copies, seven vectors, and envelope_wire_format decodes 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.
  2. An asynchronous graph.extension (Increment 197). async=true starts 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's ttl when it declares one; nothing comes back, so the deployment gate refuses an output[] on
    the node, and refuses async on any other skill. exception= covers only a failure to start: a target that does
    not exist, or an input the target graph's root schema refuses, checked before the run starts. With for_each the
    node starts one run per element, concurrency bounding 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 without async runs as before.
  3. The agent loop, llm.run, in the new opt-in crate mercury-agent-loop (Increment 198). A graph node calls
    llm.run with graph.task, giving it a tool catalog held on the graph, a prompt and its settings. The loop sends
    each model turn to llm.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 marked write: true for a person; auto runs every call;
    manual holds every call; unattended refuses a marked write), lets a row with ask: true and 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 its timeout, 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 in x-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) and llm.run.timeout (25s). The shared vector file llm-run-vectors.json (105
    loop cases, 29 schema cases) is byte-identical with the Java engine's. PostOffice::send_untraced in 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, and llm.run is a reserved route name once it does.
  4. 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, result or error: on a REST
    endpoint with stream: true as 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 its x-return-path header names when
    return.path.routes declares it (a prefix entry ends with *; a bare * is refused at startup). A node opts in
    with progress=<text>: the engine sends node.start, a graph.task function gets the node's relay route as
    x-return-path, and a synchronous subgraph returns its events through it, so llm.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 HTTP x-return-path header has no effect. examples/kafka-demo adds
    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 blank progress and an input mapping to
    header.x-return-path; graph.progress.* and graph.run.socket.reply are reserved route names.
  5. playground.panel.name renames the Minigraph Playground panel (Increment 200). Set it in application.yml or 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 reads Minigraph Playground. get.index.html writes
    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 covers async=true and progress. The twin of mercury-composable #617.
    Upgrade note: none; without the property the panel reads as before.
  6. The AI companion broker can subscribe to a session a human opened first (Increment 201). POST /subscribe with
    {"sessionId": "ws-..."} makes the broker's own session a subscriber of that primary session, as session 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 reports subscribedTo and subscribers, read from the engine's own topology lines. The twin of
    mercury-composable #618. Upgrade note: none; the other calls are unchanged.

Changed

  1. The Playground's LLM relay names the helpers' new folder (Increment 194). Both language packs moved their LLM helper
    from examples/llm-helper/ to extensions/llm-helper/ (mercury-python #46, mercury-nodejs #114), so the 503 that
    /api/llm/stream answers 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.yaml follow. The lock-step twin of mercury-composable #601. Upgrade note: none - the route, its
    status and the rest of the message are unchanged.
  2. 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 logs Flow <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.
  3. 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.
  4. The Playground session broker is the AI companion broker, and only the starter template carries it (Increment
    201).
    scripts/playground-session-broker.mjs is now scripts/ai-companion-broker.mjs, named for what it is rather
    than for a word that also means a Kafka or message broker. The minigraph-playground and distributed-cache-example
    examples no longer carry copies: their scripts/README.md runs 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

  1. 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.
  2. 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 over session 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's websocket.idle.timeout drops its note that the Java engine counts minutes: both count
    seconds. The twin of mercury-composable #618.