@north-light/api 0.3.580 → 0.3.588

package/dist/core/runtime/tmux-chrome.d.ts

@@ -0,0 +1,2 @@
+export { installTmuxBindings, occupiedTmuxRootGestures, type TmuxInstalledPair, type TmuxInstallDiagnostic, type TmuxInstallResult, } from './tmux-bindings.js';
+export { sendKeysEnter, displayMessage, paneCurrentPath, getPaneOption, } from './tmux-driver.js';

package/dist/core/runtime/tmux-chrome.js

@@ -0,0 +1,5 @@
+// tmux-chrome.ts — chrome seam (§2.1): stateless keybind/input verbs.
+// The only non-placement module allowed to import the bindings owner, per the
+// §5.1 lint. Re-exports the server chrome callers need.
+export { installTmuxBindings, occupiedTmuxRootGestures, } from './tmux-bindings.js';
+export { sendKeysEnter, displayMessage, paneCurrentPath, getPaneOption, } from './tmux-driver.js';

package/dist/core/runtime/tmux-driver.d.ts

@@ -0,0 +1,328 @@
+import { type AttachBindingId } from '../keybindings/index.js';
+import { shellQuote } from '../../shared/shell-quote.js';
+export { shellQuote };
+declare function tmux(args: string[]): {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+};
+export declare function inTmux(): boolean;
+/** Is any tmux SESSION currently up? `tmux list-sessions` exits 0 iff a server
+ *  is running with at least one session, non-zero otherwise (including "no
+ *  server"). This is the boot-time/bash-tooling probe — distinct from
+ *  `tmuxClientsReachable`, which asks whether a server is reachable at all
+ *  regardless of session count and is the human-surface gate. */
+export declare function tmuxSessionsReachable(): boolean;
+/** Is the tmux SERVER reachable at all? `tmux list-clients` exits 0 whenever a
+ *  server is up (even with zero attached clients), non-zero when no server is
+ *  running. This is the human-surface gate (core/spawn.ts's
+ *  `tmuxServerReachable`) — distinct from `tmuxSessionsReachable`, which
+ *  additionally requires a session to exist. */
+export declare function tmuxClientsReachable(): boolean;
+/** The pane currently displaying `nodeId`, found by the authoritative `@crtr_node`
+ *  pane tag — set by EVERY viewer (a bare `surface attach`, a focus split, a
+ *  spawned viewer) on connect. Scans all panes (`list-panes -a`); the reverse of
+ *  `nodeInPane`. Unlike the focus TABLE (which only `registerViewerFocus` writes,
+ *  so it misses attach-viewed nodes), the tag is on any pane showing the node.
+ *  Returns the pane id, or null when no pane shows it. Works headless (no $TMUX). */
+export declare function paneOfNode(nodeId: string): string | null;
+export interface TmuxLocation {
+    session: string;
+    window: string;
+    pane: string;
+}
+/** Where the caller currently is, or null if not inside tmux. */
+export declare function currentTmux(): TmuxLocation | null;
+/** True when a `tmux` binary runs on PATH. */
+export declare function tmuxAvailable(): boolean;
+/** Run tmux attached to THIS terminal (stdio inherited) — for a foreground
+ *  `new-session`/`attach-session` that hands the terminal to tmux — and return
+ *  its exit status. */
+export declare function tmuxInteractive(args: string[]): number;
+export declare function sessionExists(name: string): boolean;
+/** Create a detached session rooted at `cwd` if it doesn't exist. The session
+ *  name is a root's tmux home; every node under that root is a window in it. */
+export declare function ensureSession(name: string, cwd: string): void;
+export interface OpenWindowOpts {
+    session: string;
+    /** Window name (the node's display name). */
+    name: string;
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the window (already a shell string). */
+    command: string;
+}
+/** Open a background window for a node and run `command` in it. `-d` keeps it
+ *  detached so it doesn't steal focus or become the current window. Returns the
+ *  new window id AND the pane id it created (the durable `%pane_id`, LOCATION's
+ *  anchor) — callers that only need the window destructure `.window`.
+ *
+ *  Target is `${session}:` (trailing colon = the session, no window index) plus
+ *  `-a` (insert after the current window) so tmux allocates the next free index.
+ *  Passing a bare session name resolves to the session's *active window*, which
+ *  makes new-window try to create AT that occupied index and fail with
+ *  "create window failed: index N in use" whenever the active window is not the
+ *  last one (common when base-index is 0 but the live window sits at index 1).
+ *  `-a` also keeps node windows off index 0, which is reserved for the optional
+ *  dashboard. The explicit `-t ${session}:` target is the §2.2 HARD DRIVER
+ *  INVARIANT — never let new-window fall back to tmux's global current session. */
+export declare function openNodeWindow(opts: OpenWindowOpts): {
+    window: string;
+    pane: string;
+} | null;
+export interface SplitWindowOpts {
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the new pane (already a shell string). */
+    command: string;
+    /** Stack the new pane below instead of beside (default: beside, `-h`). */
+    vertical?: boolean;
+    /** Place the new pane BEFORE the target (left for `-h`, above for `-v`) via
+     *  `-b`, instead of after it (default: after — right/below). */
+    before?: boolean;
+    /** Fixed size of the new pane in the split axis' cells (columns for `-h`, rows
+     *  for `-v`) via `-l`. Omit ⇒ tmux's default even split. */
+    size?: number;
+}
+/** Split `targetPane`'s window, opening a NEW pane beside it running `command`,
+ *  and return the new pane id (the durable `%id`). The ONLY new-pane-beside verb
+ *  (Q3: a focus opened side-by-side). `-d` keeps the caller's pane active; `-h`
+ *  makes the split side-by-side (left/right), the default for a focus viewport.
+ *
+ *  §2.2 HARD DRIVER INVARIANT: `targetPane` is REQUIRED — a bare `split-window`
+ *  would split tmux's global current pane, which can leak a pane into an
+ *  unrelated user session (the exact bug this design kills). The explicit
+ *  `-t <targetPane>` makes the destination structurally un-leakable. Returns
+ *  null if tmux fails. */
+export declare function splitWindow(targetPane: string, opts: SplitWindowOpts): string | null;
+/** Bring a node's window forefront. Switches client across roots when needed. */
+export declare function focusWindow(session: string, window: string): boolean;
+/** Close a node's window (drop it from the UI). */
+export declare function closeWindow(window: string): boolean;
+/** Rename a window (`tmux rename-window -t <window> <name>`). Used by the
+ *  root relaunch to re-title the viewer window when its pane is re-pointed at
+ *  the freshly-minted node. Best-effort; false if tmux fails. */
+export declare function renameWindow(window: string, name: string): boolean;
+/** Break a single PANE out into a BRAND-NEW window of its own (`tmux break-pane
+ *  -d`). `-d` keeps the new window in the background (does not switch the client
+ *  to it); `-s <pane>` names the source pane — the §2.2 HARD DRIVER INVARIANT, so
+ *  the break never falls back to tmux's global current pane. The pane keeps its
+ *  durable `%id` across the move (only its window changes), so callers can keep
+ *  using the same pane handle. Returns the new `{window, pane}` location, or null
+ *  if tmux fails. Used by `surface tmux-spread` to lift the caller's viewer into a
+ *  fresh window before tiling sibling viewers beside it. */
+export declare function breakPane(pane: string): {
+    window: string;
+    pane: string;
+} | null;
+/** Close a single PANE. Its window closes automatically once this was the last
+ *  pane, but sibling panes survive — so co-located nodes (several agents sharing
+ *  one window via swap-pane focus) are torn down one at a time instead of all
+ *  at once by a window kill. Pane ids are the stable vehicle handle; windows
+ *  shift under swap-pane focus, so pane-granular teardown is the correct unit. */
+export declare function closePane(pane: string): boolean;
+/** Open a command in a tmux popup anchored to a pane. The command is a shell
+ * string because tmux executes popup payloads through the user's shell. */
+export declare function displayPopup(pane: string, cwd: string, command: string): boolean;
+/** `displayPopup` without blocking the event loop. tmux holds `display-popup -E`
+ *  open until the popup closes, so an interactive process (the attach viewer)
+ *  that opens one in-process must not wait on it synchronously. */
+export declare function displayPopupAsync(pane: string, cwd: string, command: string): Promise<boolean>;
+/** The active pane id of a window. Node windows are single-pane, so this is the
+ *  node's pane. Returns null if the window is gone or tmux fails. */
+export declare function paneOfWindow(session: string, window: string): string | null;
+/** The window a pane currently lives in. Used after a swap-pane to learn which
+ *  slot the caller's pane occupied — pane ids are stable across swaps, windows
+ *  are not, so the node→window mapping must be re-derived from the pane. Returns
+ *  null if the pane is gone or tmux fails. */
+export declare function windowOfPane(pane: string): string | null;
+/** The session + window a pane currently lives in (`display-message -p -t %id`).
+ *  The §2.4 reconciliation read-back: resolve a node's/focus's CURRENT
+ *  window/session from its durable pane id before any act, so crtr follows a
+ *  manual `move-pane`/`join-pane`/`break-pane` instead of fighting it. Null if
+ *  the pane is gone or tmux fails. */
+export declare function paneLocation(pane: string): {
+    session: string;
+    window: string;
+} | null;
+/** The index tmux shows for a window target (`#{window_index}`) — the number a
+ *  person sees in the status line and presses after the prefix. Null if the
+ *  target is gone or tmux fails. */
+export declare function windowIndex(target: string): number | null;
+/** Does this pane id still exist? A `display-message` probe on the `%id` — the
+ *  v3 PRIMARY liveness probe (§1.2/§2.2), replacing window-existence so a user
+ *  moving a pane to another window/session never reads as "gone". True iff tmux
+ *  knows the pane.
+ *
+ *  NOTE: `display-message -p -t <gone-pane>` EXITS 0 with EMPTY output (it does
+ *  not error on an unresolvable pane target) — so an `.ok` check alone would
+ *  report a dead pane as alive, defeating the whole point of pane-existence
+ *  liveness. We therefore require the echoed `#{pane_id}` to equal the requested
+ *  pane: a live pane echoes its own id, a gone/bogus one yields empty. */
+export declare function paneExists(pane: string): boolean;
+/** What a liveness probe of a pane learned. `unknown` means the probe timed out: tmux did not answer, which says nothing
+ *  about the pane. A caller that deletes state on `gone` must keep it on `unknown`. */
+export type PaneState = 'live' | 'gone' | 'unknown';
+/** {@link paneExists} that tells a timed-out probe apart from a pane that is gone. */
+export declare function paneState(pane: string): PaneState;
+/** {@link paneState} without blocking the event loop, bounded by the same timeout. */
+export declare function paneStateAsync(pane: string, timeoutMs?: number): Promise<PaneState>;
+/** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
+ *  Distinguishes a pane genuinely hosting a live process from a remain-on-exit
+ *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr surface attach`
+ *  as the pane command, so pane-running ⟹ a live viewer occupies it. */
+export declare function paneRunning(pane: string): boolean;
+/** Every live pane id on the server (`list-panes -a`), as a Set for membership
+ *  probes. Returns null when tmux is unreachable (no server / transient failure)
+ *  so callers can tell "no panes" apart from "can't tell" — a GC pass must skip,
+ *  never mass-delete, on a failed probe. One subprocess call total, so batch
+ *  liveness sweeps (e.g. the daemon's stale-focus GC) don't pay a per-pane
+ *  display-message each. */
+export declare function listLivePanes(): Set<string> | null;
+/** The same probe without blocking the event loop, for callers running inside
+ *  crtrd's detached work. The daemon runs this sweep on every supervision tick,
+ *  and a blocking fork/exec there freezes the API socket — which every CLI
+ *  command and every live broker's inbox poll shares — for its full duration.
+ *  Identical contract to `listLivePanes`: null means the probe failed (no
+ *  server, timeout), which a GC pass must treat as "can't tell" and skip. */
+export declare function listLivePanesAsync(): Promise<Set<string> | null>;
+/** The working directory of a pane (`display-message -p -t <pane>
+ *  '#{pane_current_path}'`). Null if tmux fails. */
+export declare function paneCurrentPath(pane: string): string | null;
+/** The pane's current cell dimensions, or null when tmux cannot describe it. */
+export declare function paneSize(pane: string): {
+    cols: number;
+    rows: number;
+} | null;
+/** Flash a transient status-line toast on the client showing `pane` (or the
+ *  current client when `pane` is omitted). `ms` sets the display duration. Used
+ *  by `crtr canvas issue new` to confirm a capture from inside its popup.
+ *  Best-effort; never throws. */
+/** Show a transient toast in the target client's status line.
+ *
+ *  `-C` is load-bearing, not decoration: without it tmux STOPS painting that
+ *  client's panes for the whole delay, so every crtr toast freezes a live
+ *  viewer mid-turn until the message expires or a keypress dismisses it. The
+ *  flag is newer than the tmux versions crouter still runs on, and a tmux that
+ *  rejects it prints usage and shows nothing — so a rejected call retries in
+ *  the plain form, where the toast is worth more than the paint stall. */
+export declare function displayMessage(message: string, pane?: string, ms?: number): boolean;
+/** Set a PANE-scoped tmux option (`tmux set-option -p -t <pane> <name> <value>`).
+ *  Best-effort; never throws. */
+export declare function setPaneOption(pane: string, name: string, value: string): boolean;
+/** Read a PANE-scoped tmux option value (`tmux show-options -p -t <pane> -q -v
+ *  <name>`): `-v` prints only the value, `-q` suppresses the unknown-option
+ *  error so an unset option yields an empty string. undefined if tmux fails. */
+export declare function getPaneOption(pane: string, name: string): string | undefined;
+/** Pane option recording when an attach viewer was last started or focused.
+ *  `liveViewerPanes` uses it to select the most recently used viewer. */
+export declare const VIEWER_STAMP_OPTION = "@crtr_viewer_at";
+/** Stamp a viewer pane without blocking the input path that observed focus.
+ *  Stamps are monotonically increasing and their tmux writes are serialized, so
+ *  two rapid focus events cannot leave an older pane with the newer stamp. */
+export declare function stampViewerPaneAsync(pane: string): void;
+export interface LiveViewerPane {
+    readonly pane: string;
+    readonly session: string;
+    readonly nodeId: string;
+    readonly stampMs: number;
+}
+/** List viewer panes tagged by a running local attach viewer. Pane tags can
+ *  survive a killed process, so every tag must match a viewer for the same node.
+ *  Shell-hosted viewers are recognized through their live child process. Unstamped
+ *  valid viewers remain eligible at stamp zero while an older viewer rolls forward. */
+export declare function liveViewerPanes(socket?: string): LiveViewerPane[];
+/** Deliver one private attach-control sequence literally into a viewer pane.
+ *  `-l` bypasses tmux key-table lookup, so delivery cannot re-trigger a root
+ *  binding that initiated it. */
+export declare function sendAttachControl(socket: string | undefined, pane: string, actionId: AttachBindingId): boolean;
+/** Show a tmux status-line message on a specific client when one is known.
+ *  `-C` for the same reason as `displayMessage`: the client's panes must keep
+ *  painting while the message sits in its status line. */
+export declare function displayClientMessage(socket: string | undefined, client: string | undefined, text: string): boolean;
+export interface RespawnPaneOpts {
+    /** Target pane id (e.g. `%3`) — the pane to re-exec in place. */
+    pane: string;
+    cwd: string;
+    env: Record<string, string>;
+    /** The full command to run in the pane (already a shell string). */
+    command: string;
+}
+/** Re-exec a command in an EXISTING pane, in place — SYNCHRONOUS. Runs the
+ *  `respawn-pane` to completion and reports the real exit status. Used when the
+ *  caller is NOT the pane being respawned (e.g. the daemon resuming a frozen
+ *  focus pane), so it can confirm the respawn landed. Returns true on success. */
+export declare function respawnPaneSync(opts: RespawnPaneOpts): boolean;
+/** Queue an in-place respawn through the tmux server. A program running IN the
+ * target pane must use this instead of `respawnPaneSync`: `respawn-pane -k`
+ * terminates that program, while this server-owned shell outlives the pane
+ * process long enough to run the respawn. The returned status only confirms
+ * tmux accepted the queued command. */
+export declare function respawnPaneInBackground(opts: RespawnPaneOpts): boolean;
+/** Run a shell command from the tmux server (`run-shell -b`), outside the
+ * caller's process tree, so it outlives the caller's pane or popup. The returned
+ * status only confirms tmux accepted the command. */
+export declare function runShellInBackground(command: string): boolean;
+/** The command line a pane was originally started with (`#{pane_start_command}`)
+ *  — the exact command `respawn-pane` with no argument re-runs. undefined when
+ *  tmux is unreachable or the pane is gone. */
+export declare function paneStartCommand(pane: string): string | undefined;
+/** Swap two panes' places on screen (`swap-pane -s a -t b`). The panes keep their ids and
+ *  processes; only their positions (and windows) exchange. Returns tmux's error text on
+ *  failure, null on success. */
+export declare function swapPanes(source: string, target: string): string | null;
+/** The foreground command name of a pane (`#{pane_current_command}`). */
+export declare function paneCurrentCommand(pane: string): string | undefined;
+/** The pane's root process pid (`#{pane_pid}`) — the process tmux launched in
+ *  the pane (the viewer itself, or the login shell hosting it). undefined when
+ *  tmux is unreachable or the pane is gone. */
+export declare function panePid(pane: string): number | undefined;
+/** Kill a pane's current process and re-run the SAME command line it was
+ *  started with (`respawn-pane -k` with no command reuses the pane's original
+ *  command). Used to hot-reload a viewer pane in place: the fresh process
+ *  re-resolves `crtr` and picks up the currently selected runtime generation,
+ *  while the pane id, geometry, and the node's broker are untouched. */
+export declare function respawnPaneInPlace(pane: string): boolean;
+/** Turn a pi argv array into a single shell command string.
+ *
+ *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
+ *  bundled pi CLI launched with the current Node binary. CRTR_PI_BINARY is a
+ *  TEST-ONLY substitution seam: the integration-test harness points it at a
+ *  deterministic fake-pi vehicle so a real `crtr node new` reaches the fake
+ *  instead of the LLM pi, without depending on tmux/shell PATH inheritance. An
+ *  explicit `binary` arg still overrides the env. The value may be a multi-word
+ *  launcher (e.g. `node --import tsx/esm host.ts`); only argv entries are
+ *  shell-quoted, so a multi-word binary is spliced verbatim ahead of them. */
+export declare function piCommand(argv: string[], binary?: string): string;
+/** List all window ids present in `session`. Returns [] if the session does
+ *  not exist or tmux fails for any reason. Each entry is the raw window id
+ *  string reported by tmux (e.g. `@1`, `@2`, …). */
+export declare function listWindowIds(session: string): string[];
+/** True when both `session` and `window` are present (non-null/undefined) and
+ *  the window currently exists inside the session. False whenever either arg
+ *  is absent, the session is gone, or tmux does not know the window. */
+export declare function windowAlive(session: string | null | undefined, window: string | null | undefined): boolean;
+/** Activate a window within its session (same-session navigation). Equivalent
+ *  to `tmux select-window -t <session>:<window>`. Best-effort; never throws. */
+export declare function selectWindow(session: string, window: string): boolean;
+/** Apply a named tmux layout to a window (`tmux select-layout -t <window>
+ *  <layout>`). `surface tmux-spread` calls it with `tiled` to evenly grid every
+ *  viewer pane in the spread window (and between splits, to redistribute space so
+ *  the next split has room). Best-effort; false if tmux fails. */
+export declare function selectLayout(window: string, layout: string): boolean;
+/** Make a pane the ACTIVE pane in its window (`tmux select-pane -t <pane>`). A
+ *  `split-window -d` keeps the CALLER active, so a freshly-opened viewer pane is
+ *  not focused until this runs — `focus` calls it so picking a node (e.g. from the
+ *  alt+g graph) lands the keyboard on the new viewer. Best-effort; false if tmux
+ *  fails. */
+export declare function selectPane(pane: string): boolean;
+/** Switch the tmux client to a different session (cross-session focus). Runs
+ *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
+ *  responsible for following up with selectWindow to land on the right window. */
+export declare function switchClient(session: string): boolean;
+/** Type a literal (e.g. a `/graph` slash command) into a pane and press Enter
+ *  (`tmux send-keys -t <pane> '<text>' Enter`). Requires the pane's editor be
+ *  empty, same limitation as the menu's `/promote` item. Best-effort. */
+export declare function sendKeysEnter(pane: string, text: string): boolean;
+export { tmux as runTmux };