CLI and ops

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

{
  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.

{
  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.

{
  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`).

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

Bear a widget in a control panel's group: a variable of the kind's own type, carrying the widget. `kind` is knob/slider/number/text/toggle/dropdown/paint. `element` is minted `knob0`, `knob1`, … when not given, and the cell is the first free one when `x`/`y` are not. A config-locked group refuses it, as it refuses every other edit to what it holds.

{
  name,
  control
}

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. ONE undo step, and refused by a config lock.

{
  name
}

Delete a widget and the variable under it. Refused by a config lock.

{
  removed: true
}

Draw on a `paint` widget with turtle steps — another hand on the pad, not a second painter: the op parses the script and the WIDGET makes the strokes, by the code a mouse reaches. So a pad nobody has open draws nothing, and the reply says how many clients heard it. `steps` is one step per line and the whole block is one submission; `//` to end of line is a comment, and `#` cannot be one because it opens every colour. Coordinates span a 1000 square whatever pixel size the pad is, the origin is the TOP-left with y running down, heading 0 faces +x and `right` turns clockwise. The steps: `forward <d>`, `back <d>`, `left <deg>`, `right <deg>`, `heading <deg>`, `goto <x> <y>`, `home` (the middle, facing +x), `up`, `down`, `curve <c1x> <c1y> <c2x> <c2y> <x> <y>` — a cubic bezier in the turtle's OWN frame, +x along the heading and +y to its right, which it leaves along the curve's exit tangent — `pen <#rgb|#rrggbb|#rrggbbaa|erase>`, `width <w>`, `soft <s>` and `clear`. `pen`, `width` and `soft` are the widget's own colour, size and softness, so a script says what a hand would set.

{
  steps,
  marks,
  clients
}

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. Refused by a config lock.

{
  source: {
    reference,
    index
  } | null
}

Resolve a host path and report whether it names a file, a directory, or nothing.

{
  path,
  kind: file | dir | missing
}

List a directory on the goofi host — the save/load browser's read. Without a path it opens the folder of the last patch loaded or saved, else the working directory; `roots` lists Home, the working directory and the five folders patches were last loaded from or saved to (`recent`). Dot-names are left out; `--hidden` includes them. Directories come first; `--sort` is name (the default), modified or size, and `--reverse` turns the order.

{
  path,
  parent,
  entries: [
    {
      name,
      kind,
      is_gfi,
      modified,
      size
    }
  ],
  roots: [
    {
      label,
      path,
      recent
    }
  ]
}

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.

{
  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.

{
  id,
  tab,
  text
}

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.

{
  text
}

The node library as an INDEX: every registered type, and the first line of its doc. Everything else about the one type you then pick — where it came from, its slots, its params, the rest of its doc — is `library get`'s, so choosing from this list costs a catalog and not a manual. `--full` answers the palette a client draws the add-menu from instead.

{
  types: [
    {
      type,
      doc
    }
  ]
}

ONE library entry in full: the palette fields — slots, params, availability — plus where the type came from. `--source` reads the file itself too, under `text`. Copy a node into the patch workspace to modify one.

Save a patch or custom node in the private library. An existing file requires --overwrite. Use --name to save under another file name with the same extension; this keeps the source for existing instances. Without a new name, a patch file moves into the library and future patch saves bundle it from there.

{
  type,
  path
}

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.

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

Wire `from` (an output, as `node/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,
  to,
  dtype
}

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

{
  removed: bool
}

Read the retained log groups, ordered by their last occurrence.

{
  cursor,
  oldest,
  reset,
  groups
}

Write an application message. Level is info, warning or error.

{
  logged: true
}

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.

{
  text: string
}

The output's latest frame, once — the analysis read, addressed `node/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. An ARRAY answers its shape and its range, which is what tells silence from signal; `--raw` answers the numbers themselves as base64 NPY. STRING and TABLE answer plain JSON, a table's ARRAY members reading the same way. 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.

{
  meta,
  shape,
  range: {
    min,
    max,
    mean
  }
}

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/InTexture/OutArray/OutString/OutTable/OutAudio/OutTexture) 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`.

{
  name,
  uid,
  input_slots,
  output_slots,
  params
}

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); or, as a setting, the trajectory over pairs of rows); image (a bitmap: (H, W), or (H, W, C) for 1–4 channels); brain (a scalp map of one scalar per channel (1-D), or the connectivity between channels (C, C) as a ring or in 3-D); string (the text of a STRING slot); table (the rows of a TABLE slot).

{
  ok: true
}

Delete whatever `node` 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.

{
  removed: bool
}

Take the touched filter's zero point to be what this node holds NOW — what the inspector's Clear button does. A param reads as touched when its value, its expression or its reference differs from that zero, and with no zero recorded the zero is the type's own declared default. A plugin's declared default is its FACTORY default, so loading a preset moves hundreds of params at once and the filter that exists to show the few in play fills with everything the preset moved; this is how that is reset to the few that follow. It edits no param and breaks no binding: an expression or a reference keeps driving exactly as it did, and the Expression and Reference filters still find it. Undoable.

{
  ok: true,
  cleared: int
}

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

{
  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.

{
  changed: bool
}

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

{
  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.

{
  doc: {
    nodes,
    links
  }
}

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.

{
  rename: {
    old_uid: new_uid
  }
}

Collapse nodes into a new sub-patch, returning it. `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.

{
  name,
  inst_id
}

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.

{
  ok: true
}

Every op this server speaks: its name, its arguments (`!` marks a required one) and its kind — a `write` is undoable and may ride in a batch, an `effect` runs alone. Every argument is reachable as `--name value`, which is all a caller needs to write one. What an op DOES is `<op> --help`; `--doc` answers the whole vocabulary explained, which is the manual and costs like one.

{
  ops: [
    {
      op,
      args,
      kind
    }
  ]
}

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 name). The line's last word, when partial, filters the candidates.

{
  text: string
}

List installed plugins and their status.

{
  plugins
}

Whether a recording runs, where it writes, and every armed stream's health: frames written, frames dropped, and how full its buffer is. The one read a panel, an agent and a test all use.

{
  running: bool,
  folder: string | null,
  elapsed: number | null,
  streams: [
    {
      node,
      slot,
      engine,
      file,
      frames,
      dropped,
      fill
    }
  ],
  error: null
}

Capture this output slot, addressed `node/slot`. Arming rides the node's own record, so it is undone, saved and copied with the node, and a re-wire elsewhere cannot disarm it. Arming while a recording runs opens a new file for that stream at once. `changed` is false when the slot was already armed, which records no command.

{
  ok: true,
  changed: bool
}

Set an armed video output's quality: small, high (default), or very_high. Saved with the patch and undoable. During recording, a change starts a new video file.

{
  ok: true,
  changed: bool
}

Stop capturing this output slot. A file open for it is closed and named in the manifest. `changed` is false when the slot was not armed, which records no command.

{
  ok: true,
  changed: bool
}

Begin a recording. `name` names the folder, which otherwise carries the UTC of this moment; `root` overrides the recordings folder for this one recording. Either one absent is read from `variables.record.name` and `variables.record.root`. Refused when nothing is armed, and refused when one already runs.

{
  folder: string
}

End the recording: every file is closed and the manifest is finalized.

{
  folder: string
}

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`.

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

The whole replicated document, exact and ATOMIC: nodes, links, variables 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`.

{
  nodes,
  links,
  variables,
  arrangement
}

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

{
  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. Set `overwrite` to false to refuse an existing file; normal Save replaces the current file.

{
  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.

{
  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.

{
  ok: true,
  layout_warning: string | null
}

Every autosave a goofi that did not shut down cleanly left behind: unsaved work, kept beside the crashed session's workspace. `workspace` is what `session recover` and `session discard` take; `home` is the `.gfi` the patch was saved as, null for one never saved; `at` is when the autosave was taken, in seconds since the epoch.

{
  recoveries: [
    {
      workspace,
      home: string | null,
      at: float | null
    }
  ]
}

Replace the open patch with a crash's autosave, losing unsaved work. The recovered patch is UNSAVED work with its old home: a plain Save writes it where the lost session would have. The autosave is removed once it is open.

{
  ok: true,
  layout_warning: string | null
}

Remove a crash's autosave without opening it. Refused for a workspace a running goofi owns.

{
  ok: true
}

Every patch variable — what an expression can read and the variable 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 its EPHEMERAL members — `system.goofi_home` and the `system.audio_*` facts the audio engine publishes — are goofi's own value, never saved into a patch.

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

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

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

Redo this actor's last undone graph command.

{
  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.