Op vocabulary

The agents the config offers to launch, and the ones goofi has running.

returns {instances: [{id, harness, state, exit_code}], agents: [{name, command}], config_error: string | null}

Launch a config-listed agent on a PTY with the patch workspace as its cwd, under a login shell — a command that cannot launch fails on the PTY itself. Read its terminal at /term/<instance_id>. An unknown name is refused with the config's list.

• name string required positional

returns {instance_id: string}

Stop a running agent (SIGTERM, then SIGKILL), or dismiss one that already exited. The shell's undo stack dies with it; the exit code arrives on harness_changed.

• instance string required positional

returns {ok: true}

Every control panel and the group it draws, and every group holding a widget: each element with its value, its widget (`control`), its lock and what it follows (`source`).

returns {panels: [{panel, group}], groups: {group: {lock, elements: [{name, element, type, value, control, lock, source?}]}}}

Bear a widget in a control panel's group: a global of the kind's own type, carrying the widget. `kind` is knob/slider/number/field/toggle/dropdown. `element` is minted `knob0`, `knob1`, … when not given, and the cell is the first free one when `x`/`y` are not. Works on a config-locked group and leaves it locked — a control panel owns its group — as ONE undo step.

• group string required positional
• kind string required positional
• element string
• x float
• y float
• w float
• h float
• value any
• min float
• max float
• step float
• options json

returns {name, control} — the global's full name and the widget as stored

Change a widget: `name` renames the element (every expression reading it follows), and the rest re-shape the widget, its range, its options or its cell. Through the lock, as `control add` is.

• group string required positional
• element string required positional
• name string
• kind string
• min float
• max float
• step float
• options json
• x float
• y float
• w float
• h float

returns {name} — the element's full name after the edit

Delete a widget and the global under it. Through the lock, as `control add` is.

• group string required positional
• element string required positional

returns {removed: true}

Make a widget FOLLOW one producer output, `node.slot`, with `index` picking one number out of a wide frame — a MIDI controller's `cc` is 128 of them — so a knob on a controller drives the widget. An empty reference clears it. Through the lock, as `control add` is.

• group string required positional
• element string required positional
• reference string required
• index int

returns {source: {reference, index} | null}

List a directory on the goofi host — the save/load browser's read.

• path string positional

returns {path, parent, entries: [{name, dir}], roots}

Every patch global — what an expression can read and the global writes can set — each with the lock that holds it (its own and its group's together), and every group that carries a lock. The `system` group is goofi's own: config-locked for life, and `system.goofi_home` is the machine's value, never saved into a patch.

returns {globals: [{name, type, value, lock: {config, value}, control?, source?}], groups: {group: {lock}}}

The arrangement as a tree: every tab, split and panel with its id, order and share of its parent. How a caller discovers the ids every layout op addresses. `tab` narrows it to one tab; no arg = all of them.

• tab string positional

returns {text: string}

Move a layout entry — a panel, a whole split's subtree, or a tab; one op per drag gesture, so a drop is one undo step. With `--beside` (and `--side`, `--ratio`) it lands beside that panel. With `--in` it lands inside that split, at `--index` among its children. Bare, a TAB moves to `--index` in the strip, and anything else wraps onto a tab of its own, labelled `--name`. Taking a tab's last panel takes the tab with it.

• entry string required positional
• beside string
• side string
• ratio float
• in string
• index int
• name string

returns {id, tab, text} — what was moved, the tab it is on, and the arrangement as `layout inspect` draws it

Close a layout entry: a panel, a whole split's subtree, or a tab and every panel on it. Its space goes to its siblings; a tab keeps its last panel, and the last tab stays.

• entry string required positional

returns {text} — the resulting arrangement, as `layout inspect` draws it

The node library: every registered type with its slots, params, docs and availability — what `node add` can build.

returns {types: [{type, engine, tags, doc, input_slots, output_slots, params, available}]}

ONE library entry in full: the palette fields plus where the type came from and its source text. Copy a node into the patch workspace to modify one.

• type string required positional

returns the `library list` entry plus {language, tier, provenance, path, source}

Re-read the shipped and patch node directories; live instances of a changed type restart onto the new code. Call after writing a node file.

returns {added: [type], changed: [type], removed: [type]}

Wire `from` (an output, as `uid/slot`) to `to` (an input). Refuses a dtype mismatch, naming both ends; refuses an end that names no node — so a reply means the wire is really there. A link never crosses a sub-patch boundary, and the two acts that look like it are ordinary links in different scopes. From the OUTSIDE you wire a node to the sub-patch's facade, naming a port's uid as the slot; the wire is stored against the PORT, whether or not anything is behind it yet. From the INSIDE you wire a port to a member, both of them in that sub-patch. A port carries one slot, `value`, on both of its sides.

• from endpoint required positional
• to endpoint required positional

returns {from, to, dtype} — the wire as made, with a facade endpoint resolved to the PORT it named.

Remove one wire, addressed by both of its endpoints — a boundary port's inner wire included. Idempotent, like `node remove`.

• from endpoint required positional
• to endpoint required positional

returns {removed: bool} — false when there was no such wire

Read one node: its params (values, ranges, expression bindings), each output slot's name and kind and whether the node is emitting on it, and its error. `slot` narrows to one output; `--no-params` and `--no-error` drop a section. The FRAMES are not here: `node snapshot` reads one raw, and `/data/<node>/<slot>` streams them exactly as a viewer sees them.

• node uid required positional
• slot string
• params bool
• error bool

returns {text: string}

The output's latest frame, RAW and once — the analysis read, addressed `uid/slot`. A facade or a boundary port resolves to the stream behind it, exactly as a viewer's does. It reads the cache the slot's reducer already keeps, so it never wakes the node and never touches the viewers' shared stream. ARRAY answers base64 NPY; STRING and TABLE answer plain JSON, a table's ARRAY members as NPY again. A slot asked about before anything was cached answers `{frame: null}` with the reason — asking is also what opens the slot's feed, so ask again after the node's next emit.

• output endpoint required positional

returns {meta, npy_b64} for ARRAY; {meta, value} for STRING/TABLE; {frame: null, reason} before the first cached frame

Create a node of `type`. `inst_id` births it inside that sub-patch; absent = root. `name` is a letter then letters or digits and not a Python keyword — one that is taken or illegal is refused, never silently swapped — and an omitted one is minted. Each `--param` is one birth param, self-addressed: `{"name": "group/param", …}` carrying `node param edit`'s fields — inside a JSON flag under bash, spell nested strings with ESCAPED double quotes (`"nd(\"other\").out.sfreq"`); a single-quoted `nd('x')` inside a single-quoted shell token loses its quotes silently. `member_uid` asks for a CHOSEN uid, so a caller rebuilding a graph it already knows — or wiring a batch it is still building — keeps its uid-keyed bindings; naming one the patch already holds answers with that node rather than a second one. The boundary types (InArray/InString/InTable/InAudio/OutArray/OutString/OutTable/OutAudio) create a PORT of the sub-patch named by `inst_id`, which is required for them. A port is a node in every way an op can see — it is named, moved, wired and removed by the same ops — but it never runs, so it takes no params. To COPY a node rather than build one, read it with `nodes copy` and put it back with `nodes paste`.

• type string required positional
• pos float2
• name string
• inst_id uid
• member_uid uid
• param json[]

returns {uid, name, input_slots, output_slots, params} — the node as born, so it can be wired and tuned without a follow-up read. `name` is what nd() addresses it by.

Edit a node's own record: rename it, move it, set viewers — any of them, in one step and one undo. An omitted field is left alone. Params are `node param edit`'s. A sub-patch boundary port takes every field: its name is in the one namespace nd() reads, so a collision is refused exactly as a leaf's is, and its `value` slot takes a viewer exactly as a leaf's output does. A `name` is a letter then letters or digits, and not a Python keyword, for every kind of node. An expression reads a name as an ATTRIBUTE — a sub-patch's slot in `nd('chain').out.drain` — and a reference spells `name.slot`, so one that cannot be read there breaks every source naming it, and the rewrite that follows the NEXT rename can no longer find what it broke. Each `--viewer` is one slot's inline view, `{"slot": "out", "kind": …, "settings": …}`, merged slot by slot so only the slots named move; `{"slot": "out", "clear": true}` removes that slot's stored view. `kind` is one of: line (a time plot: one series (1-D) or one per channel (C, N)); image (a bitmap: (H, W), or (H, W, C) for 1–4 channels); trajectory (a phase portrait over pairs of rows of a (D, N) frame); topomap (a scalp map of one scalar per channel); string (the text of a STRING slot); table (the rows of a TABLE slot).

• node uid required positional
• name string
• pos float2
• viewer json[]

returns {ok: true}

Delete whatever the uid names — a leaf, a boundary port or a whole sub-patch. A sub-patch takes everything inside it, to any depth: nested sub-patches, their members and their ports. A port of an enclosing sub-patch that exposed the deleted node STAYS, unwired — a port is a node, and it outlives what was behind it exactly as an unconnected node outlives the cable it lost. Idempotent: a uid naming no node succeeds having deleted nothing, and says so.

• node uid required positional

returns {removed: bool} — false when the uid named nothing

Respawn a node in place, keeping its uid, name, params, links and scope. Recovery, not an edit — `setup()` runs again.

• node uid required positional

returns {ok: true}

Open a node's own editor window — a plugin's GUI — on the machine goofi runs on, never in the page; `--no-show` closes it. Only a type whose palette row says `editor: true` has one, and a machine with no display has none.

• node uid required positional
• show bool

returns {changed: bool} — false when the editor was already open, or already closed

Read one scope as a mermaid flowchart — nodes, sub-patches, boundary ports and wires. No arg = the root scope. Scope-wide and nothing more: what is broken is the whole patch's business, so `session status` answers that.

• scope uid positional

returns {text: string}

Read `nodes` and everything they hold — a sub-patch's members, their ports and the nested sub-patches below them, to any depth — as a self-contained fragment. A link rides only when BOTH its ends are in the fragment. The shape is the `.gfi`'s own, so a fragment is a patch's worth of nodes in the format a patch is written in, and `nodes paste` is what puts one back.

• nodes uid[] required positional

returns {doc: {nodes, links}} — the fragment, keyed by the uids it was read from

Add a `nodes copy` fragment on FRESH uids and fresh names, so it lands beside whatever it was copied from rather than colliding with it. `pos` shifts the whole fragment by that offset; `inst_id` puts its roots inside that sub-patch, absent = root. A record naming a scope that is IN the fragment keeps the shape it was copied with. One command, so it is one undo step.

• doc json required
• pos float2
• inst_id uid

returns {rename: {old_uid: new_uid}} — every record's uid in the fragment mapped to the one it was created at

Collapse nodes into a new sub-patch, returning its instance uid. `nodes` must share one scope, and one of them may itself be a sub-patch. Every wire that ends up CROSSING the new boundary mints a port to carry it, so nothing is disconnected and nothing stops running; a wire buried in a nested member mints a port there too, so it can reach the new boundary.

• nodes uid[] required positional
• pos float2

returns {inst_id: uid}

Dissolve a sub-patch, returning its members to the parent scope. Its ports go with it and every wire they carried stands, because a port keeps its wire against the node behind it. A port of an ENCLOSING sub-patch that exposed one of these follows down onto what it exposed.

• subpatch uid required positional

returns {ok: true}

Every op this server speaks: its name, its arguments (`!` marks a required one), what it does, what it answers, and its kind — a `write` is undoable and may ride in a batch, an `effect` runs alone.

returns {ops: [{op, args, positional, kind, doc, result}]}

What can come NEXT on a partial command line — the shell completion read. Each candidate is a word with a one-line doc: a group or op word mid-phrase, a flag once the op is named, or a value for a flag with a known vocabulary (a panel type, a live node's uid). The line's last word, when partial, filters the candidates.

• line string positional

returns {text: string} — one candidate per line, `word<TAB>doc`

The session's identity AND its health: which instance this is, where the patch lives, whether it differs from disk, and every standing error with how long it has stood. One read for `is my patch healthy, and have I saved it`.

returns {instance_id, save_path: string | null, workspace, dirty: bool, errors: [{node, path, error, standing}]}

The whole replicated document, exact and ATOMIC: nodes, links, globals and arrangement in one read — what every client mirrors, read without the sync protocol that carries it. ONE `nodes` map carries leaves, sub-patch facades and boundary ports alike, each naming its scope, and a port's inner wire is in `links` like any other cable. Narrowing is the caller's: pipe it through `jq`.

returns {nodes, links, globals, arrangement} — nodes and globals keyed by id, links a list.

The open patch as YAML — the manifest a `.gfi` holds, diffable and versionable.

returns {yaml: string}

Pack the patch and its workspace to a `.gfi`. With no `path` it saves to the patch's home — refused when the patch has never been saved — and a given `path` becomes the new home.

• path string positional

returns {path: string}

Replace the open patch, losing unsaved work. `path` names a `.gfi` and brings its workspace with it; `--content` is an inline YAML manifest and carries no workspace. Exactly ONE of the two — the empty patch is `session new`. `adopt` (default true) decides whether a loaded FILE becomes the patch's home, which is what a later silent save overwrites; `/patch.gfi` passes false, because the file a browser upload came from lives on the user's machine and the staged copy this reads is deleted immediately.

• path string positional
• content string
• adopt bool

returns {ok: true, layout_warning: string | null}

Replace the open patch with the empty one, losing unsaved work. The undo history is cleared, so this cannot be taken back.

returns {ok: true, layout_warning: string | null}

Undo this actor's last graph command. Each actor — a browser tab, a shell, the MCP — has its own stack.

returns {changed: bool, can_undo: bool, can_redo: bool}

Redo this actor's last undone graph command.

returns {changed: bool, can_undo: bool, can_redo: bool}

Run several steps in order as ONE undo step and one settled decision: viewers see no intermediate document, and the unsaved dot moves once. `ops` is a list of `{op, payload}`; a step is a read or an undoable write, and an effect is refused — it runs as its own call. A refused step takes back the ones that already landed, so the call either happens whole or not at all. A read step sees the earlier steps' writes on the GRAPH — but the document settles only when the batch does, so `session state` and `session status` inside a batch answer the document the batch found. Read them after it, not inside it.

• ops json required

returns the steps' own replies, as a bare JSON list in order