Mercury CLI
Documentation

Code

Workshop

Workshop runs code in cells whose state survives across calls. The model writes a cell, reads the result, and the next cell continues from the same live state.

Languages

  • js: Runs JavaScript in a state-holding VM context with top-level await.
  • ts: Runs TypeScript in the same kind of context, transpiled with the workspace's own TypeScript. A workspace that cannot transpile is refused with the reason.
  • py: Runs Python in a persistent python3 kernel. A machine with no usable interpreter is reported as such.

Runtime ownership

A runtime is owner-scoped: one per conversation owner, per language. Cells of that owner and language share state across calls. Closing the owning conversation reaps its workers.

A timeout or cancellation kills the worker, and the result reports the state loss. The result carries the runtime generation, which advances on every kill or reset, so a cell cannot silently continue from a state that is gone.

Python cancellation is interrupt-first. State is retained when the interpreter can be interrupted, and only an unresponsive kernel is killed, after a bounded escalation.

Run a cell

To run a cell, follow these steps:

  1. Call Workshop with the cell's code and its language, js, ts or py.

The runtime executes the cell and returns its completion value, captured output and display items.

Reset cell state

To reset cell state, follow these steps:

  1. Call Workshop with reset: true.

The runtime starts fresh and the result reports a new generation.

Results

  • Completion value: A bounded preview of the cell's final value.
  • Captured output: A bounded tail of the output. The full stream spills to an artifact when it overflows.
  • mercury.display(): Items the cell emits into the result: text, JSON, Markdown, tables or refs.

Failed cells

A failed cell's result names the error first and then only the cell's own lines.

  • Thrown error: The error's name and message, followed by the frames inside the cell and inside any local module it required, never the runtime's own plumbing.
  • Failed bridge call: The call's ordinal within the cell and the tool, that tool's own words, a statement that the cell stopped at that call, and the cell line that made it. A cell that catches the rejection continues.
  • Syntax error: The line and column, an excerpt of the source around that position with a caret under it, never an echo of the whole cell.

Every error text is bounded, with the message kept ahead of the bound.

Mercury bridge

  • mercury.inspect, mercury.tool and mercury.agent: Reach Mercury through the tool transaction and permission path. A cell that asks to edit a file meets the same consent an Edit would.
  • mercury.sample({ name, title?, html }): Keeps a page you asked to see as a sample: a versioned page under the session that opens in the browser and takes your marks back into the session. The same name publishes the next version. Present only when samples are on.

Parallel and pipelined bridge calls work within a cell. A cell that invokes Workshop recursively is refused.

Feature switches

  • MERCURY_WORKSHOP: On by default. 0 removes the tool, and no runtime spawns.
  • MERCURY_SAMPLES: Off by default. 1, or the Boot Menu's Samples row, turns on mercury.sample, the loopback listener and the /samples command for new sessions.

With samples off, there is no mercury.sample, no listener and no /samples, and the tool's prompt has no line about samples.

Samples, Edits and change transactions, Agents and teams