Driving Jonquil from an agent (MCP)

jonquil_eval, jonquil_run and jonquil_run_selection take timeout_ms (default 30000). A program that stops to read stdin makes the call return early with what it printed; type into the console or call jonquil_stop.

The window serves its launch project. Run on another project's tab is refused, though jonquil_run_selection still moves the visible selection.

When the client disconnects (EOF on stdin) the window closes and unsaved edits are discarded, so have the agent jonquil_save first. jolt mcp:smoke --window exercises all of this end to end.

The trust boundary is the headless server's, plus the files the window can reach: the agent can open, edit and save any file you can.

jonquil_plugin_propose never runs the agent's code in Jonquil. It is checked first in a separate jolt process (isolation, not a sandbox; see Plugins), then waits as a pending proposal that you decide in Review Plugin Proposals. No tool can accept or reject one; the agent reads your decision, and your reject note, with jonquil_plugin_status.

A proposal is refused before any check when its id isn't a plugin id, its reason is blank or over 4000 characters, its source is over 262144, or the window runs with --no-plugins (the reading tools still answer). A propose can take most of a minute (30 s check, busy window); if it doesn't finish, the answer is status: unknown and jonquil_plugin_status says whether it was recorded. If a newer proposal replaces the one you're reading, the next Accept is refused; press it again after reading the new one.

jonquil_change_set_propose takes a name and forms, each form a path (absolute, or relative to the window's folder) and the text of one top-level form that replaces the form with the same first two elements in that file (a later entry of the same two elements replaces the file's next such form). Each path is resolved to its real path and must name an existing, readable Clojure file (.clj, .cljc, .cljs, .cljd or .bb) inside the window's folder, or the call is refused with the reason. The set is saved beside the settings file, marked with the client's own name (control characters dropped, at most 60 characters), and the window shows it as "a client calling itself" that name. A line goes to the console and the status bar. The call applies nothing and edits no file or tab: Change Sets in the palette lists it, the panel shows each form as a diff of the file's current form against the proposed text, and only you press Apply to REPL or Delete. There is no Revert for a proposed set. A name that is already taken is refused, and the file is created only if the name is free, so a proposal never replaces one of your sets, even when two windows race. It is also refused when forms is empty or holds more than 200 entries, an entry isn't exactly one balanced form, or the texts together pass 262144 characters.

A plugin gives agents tools in :mcp-tools:

:mcp-tools [{:name "twice" :doc "The text twice."
             :args {"text" {:type "string" :doc "The text." :required? true}}
             :run (fn [ctx args] (str (get args "text") (get args "text")))}]

A window serving MCP (--mcp --window, or one you attach to) serves each live plugin's tools as plugin_<id>_<name> after its twenty: plugin_smoke-t_twice for plugin smoke-t above.

• Argument types: string, integer, number, boolean. A missing or wrong-typed required argument is refused before :run.
• :run returns a string or {:text "..." :error? true}. It runs with only the plugin's declared effects, gets 30 s, and runs one call at a time per tool (a call still going at 30 s keeps the tool busy).
• Tool :name: lower-case letters, digits, _, starting with a letter; the served name is at most 50 characters. Argument names: 1 to 64 characters of letters, digits, _, ., -.

Jonquil sends notifications/tools/list_changed when a plugin's tools change; a client that ignores it sees them on its next list or after reconnecting. Accept refuses a plugin whose tools differ from what its check reported.

A window registers the folder it opened on; Open Folder re-roots both.

Detaching leaves the window running with its tabs and unsaved edits, unlike --window, where EOF closes it. If the relay loses its connection it writes a line to stderr and exits. A crashed window's leftover entry is recognized by its dead pid and skipped. jolt mcp:smoke --attach exercises all of this end to end.