Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import type {
ChatDraftPutResult,
ChatDraftTakeResult,
ChatInterruptResult,
ChatPromptResult, EmptyPromptResult, TextDeliveryResult } from './text-delivery'
import type { ChatScreenRead } from './agents/claude-screen'
import type { PushWebhookMinted, PushWebhookResult, PushWebhookTokenInfo } from './push-webhook'
import type { IdentitySeedEntry } from './agent-identity-seed'
import type { AgentStatusSnapshotEntry } from './agent-status-snapshot'
import type { WhiteboardFile, WhiteboardSaveResult } from './whiteboard'
import type { PrWaitHold } from './pr-wait'
import type { SessionBackend } from './session-backend'
import type { AgentIntegrationsSettings } from './agent-integrations'
import type { NodeSize, SizableNodeKind } from './default-node-size'
// Types shared across the main, preload, and renderer processes.
import { TABBAR_HEIGHT_PX } from './window-chrome-metrics'
import { DEFAULT_MARKDOWN_FONT_FAMILY, DEFAULT_MARKDOWN_FONT_SIZE } from './markdown-font'
import { DEFAULT_WORKTREE_PATH_TEMPLATE } from './worktree'
import type { CloneProgress } from './clone-url'
import type { KeybindingOverrides, TerminalShortcutPolicy } from './keybindings'
import type { NormalizedAgentEvent } from './agents/normalize'
import type { PaneOwner } from './agents/pane-owner-predicate'
import type { AnswerPermissionPayload, ChatQuestion } from './agents/permission-answer'
import type { HostChatQuery, HostChatReply } from './mobile-chat'
import type { AgentId, AgentPermissionMode, BuiltinAgentId, PromptInjectionMode } from './agents/config'
import type { ControlConfirmWaivers } from './control-confirm'
import type { AgentMessageDeliverRequest, AgentMessageReply } from './agents/agent-messaging'
import type { BoardCommentDeliverRequest } from './board-comment'
import type { ChatTranscriptPageRequest } from './chat-page'
import type { BrowserLeasePush } from './browser-indicator'
import type { GroupWorktree } from './worktree'
import type { ClientId, DinoSnapshot, PeerDiff, PeerIdentity, PeerState } from './presence'
import type { WhisperModelInfo } from './speech'
import type { ProjectKanbanGitHub } from './github-issues'
import type { KanbanPullAutoMove, KanbanPullLinks } from './kanban-pull-links'
import type { BoardDispatch } from './board-dispatch'
import type { CodexAccount } from './codex-account'
import type { ClaimResult, ProjectLimitState } from './project-limit'
import type { NotchAlign } from './notch-hud'
import type { ProjectIcon, ProjectIconPickResult } from './project-icon'
import type { AlertSoundKind, AlertSoundSaveResult, CustomAlertSounds } from './alert-sound'
import type { CanvasLayout, LayoutViewports } from './canvas-layout'
import type { ShareTeamApi } from './share-team'
import type {
ModelDiscoveryResult,
ModelGatewayCredentialStatus,
ModelGatewaySettings
} from './agents/model-gateway'
/**
* The default provider behavior for a FRESH agent spawn — the three-way successor to the old
* `vanillaLaunchDefault` boolean. Read by `pty-manager`'s spawn-site strip gate and by the
* renderer's new-node creation (`addAgentNode`):
* - `'gateway'` — inject the model gateway env; the agent uses the CLI's OWN default model
* (no `--model`). Today's behavior for a gateway node with no per-node model.
* - `'gateway-model'` — inject the gateway env AND launch with the configured default gateway
* model (`settings.modelGatewayDefaultModel`), so a new canvas session
* opens on a chosen model without a per-node "Switch model" click.
* - `'subscription'` — strip the gateway + inherited provider env so the agent runs against its
* OWN default provider (Claude's subscription, Copilot's GitHub routing).
* The former `vanillaLaunchDefault: true`. Wins even when a default model is
* set (vanilla = no gateway at all, so the gateway model is moot).
*
* `vanillaLaunchDefault` is kept for one release as a migration MIRROR (an older build still honors
* the choice); `agentLaunchMode === 'subscription'` ⇒ `vanillaLaunchDefault = true`, else `false`.
*/
export type AgentLaunchMode = 'gateway' | 'gateway-model' | 'subscription'
/** Profile-switch replacement intent. The trusted core validates and re-resolves it before teardown. */
export interface PtyRecycleTarget {
profileId: string
cwd: string
}
/**
* A shell-independent request to start or resume an agent.
*
* The renderer deliberately does not turn this into a command line: the trusted core validates
* the semantic fields, resolves the current machine-local agent configuration, and encodes the
* launch for the concrete shell that owns the live session. In particular, `auto` is not a shell
* dialect until immediately before a Windows profile is spawned.
*/
export type AgentLaunchIntent =
| {
kind: 'agent'
action: 'start'
agentId: AgentId
/** Initial prompt for a new conversation. The core rejects control-bearing values. */
prompt?: string
/** Already version/policy-gated starting mode. The core re-validates it at execution. */
permissionMode?: AgentPermissionMode
/** Optional provider id minted for this first launch; never reused as a resume id. */
newSessionId?: string
}
| {
kind: 'agent'
action: 'resume'
agentId: AgentId
/** Existing provider id. Required for resume and runtime-validated by the trusted core. */
sessionId: string
/** Starting mode for the reconstructed CLI, where the selected agent supports it. */
permissionMode?: AgentPermissionMode
}
/**
* One locally-authorized launch held behind canvas dependencies.
*
* `shell-command` is the explicit `open-terminal --cmd` compatibility path. It is opaque shell
* source, not something the app can safely parse back into argv. The whole PendingLaunch is
* machine-local and must be stripped from shared project files, exports, and inbound mutations.
*/
export type TerminalLaunchIntent =
| AgentLaunchIntent
| { kind: 'shell-command'; command: string }
export type LaunchIntentFailureReason =
| 'invalid-intent'
| 'agent-unavailable'
| 'unsupported-shell'
| 'session-unavailable'
| 'delivery-failed'
/** Opaque execution outcome. It must never contain a rendered command, executable, or argv. */
export type LaunchIntentExecutionResult =
| { ok: true }
| { ok: false; reason: LaunchIntentFailureReason; message: string }
/**
* `pty:execute-launch` request (`PtyApi.executeLaunch`). `launchId` is a fresh UUID v4 per
* delivery attempt — the session host's exactly-once ledger key. `promptFile` is the
* canvas-control `--prompt-file` path: the core reads it (the file is on the core's machine) and
* fills `intent.prompt`, so no shell ever has to expand `$(cat …)`. Only legal on a `start`
* intent that carries no `prompt` of its own.
*/
export interface LaunchIntentRequest {
launchId: string
intent: AgentLaunchIntent
promptFile?: string
}
/**
* A semantic launch held beside a terminal node's legacy typed line (`data.launchIntent`). Bound
* to the EXACT `command` it was assembled with: a writer delivering any other line (a manual Run
* now of an edited command, a resume) never uses it. Live node data only — never serialized.
*/
export interface HeldLaunchIntent {
command: string
intent: AgentLaunchIntent
promptFile?: string
}
export interface PtyCreateOptions {
shell?: string
/** Arguments for `shell` when it is run as the session program (e.g. ssh args). */
shellArgs?: string[]
cwd?: string
cols: number
rows: number
/**
* Stable key (the node id) used to derive a persistent tmux session name so the
* terminal reattaches to the same session across remounts and app restarts.
*/
persistKey?: string
/**
* The machine-local id (`IndexEntryV3.id`) of the project this node belongs to, as the renderer
* knows it at the create call. Recorded in the runtime pane-ownership ledger on a GENUINE FRESH
* spawn (`agents/pane-ownership.ts`) so agent messaging can prove which project actually spawned
* a pane rather than trusting the git-shared, forgeable `project.json`. Optional: absent ⇒ the
* pane is left unproven and messaging to it fails closed (never derived from the file id).
*/
ownerProjectId?: string
/**
* Whether the node was on screen when the renderer asked for this session. Used ONLY to order
* the per-ControlMaster remote spawn queue (`remote-ssh/pty-spawn-gate.ts`): a project switch
* mounts every node in one tick, and without it the terminals the user is looking at queued
* behind the ones they are not. `false` = queue behind on-screen spawns; absent (older clients,
* relay, headless) = on-screen, i.e. the previous plain FIFO.
*/
onScreen?: boolean
/**
* Which agent runs in this session (claude/codex/gemini/custom). Drives the hook env
* injected at spawn. Defaults to 'claude' for backward compat; the renderer passes a
* real value in a later phase.
*/
agentId?: AgentId
/** Per-node model override. Applied through the node's base harness on launch/cold restore. */
agentModel?: string
/**
* One-shot: spawn (or re-spawn after a recycle) with gateway + inherited provider env stripped
* so the agent runs against its OWN default provider (Claude's subscription, Copilot's GitHub
* routing) instead of the configured gateway/inherited override. The strip set is per-agent
* (`vanillaEnvStripPattern`); `CLAUDE_CONFIG_DIR` is deliberately kept (account isolation
* survives). Cleared after the spawn resolves so a later ordinary Restart re-applies the gateway.
*/
clearEnv?: boolean
/** Managed Claude account: inject CLAUDE_CONFIG_DIR for this account into the session env. */
accountId?: string
/**
* Which VIEW of the session this is, WITHIN one connection. A second view in the same renderer
* (the kanban card modal) passes its own id so it co-attaches as an independently-detachable
* subscriber rather than a no-op join; absent ⇒ the PRIMARY view (the canvas node) and bit-for-bit
* the pre-viewer behavior. Invisible to peers — viewers collapse to the ClientId everywhere a
* subscriber maps to a person.
*/
viewerId?: string
/** When set, this PTY runs on a remote host over the project's ssh ControlMaster, in remote tmux.
* `remoteHome` is the connection's resolved `$HOME`, used to build an ABSOLUTE remote
* `CLAUDE_CONFIG_DIR` for a managed remote account (tmux `-e` values are not shell-expanded). */
sshRemote?: { controlPath: string; conn: import('./ssh').SshConnection; remoteCwd: string; hookEndpointPath?: string; tmuxConfPath?: string; remoteHome?: string }
/**
* This node BELONGS to a remote host: never spawn it locally.
*
* `sshRemote` says "here is the master to run over"; this says "and if there isn't one, spawn
* NOTHING". Without it, a create with no `sshRemote` falls straight through to the local
* tmux/plain-shell branches — which is how an SSH project's terminal, opened while the
* ControlMaster was down (no network, laptop asleep, host unreachable), quietly became a LOCAL
* shell in the local `$HOME`: same node id, same `SSH user@host` header chip, the remote
* session's own scrollback snapshot replayed into it, and — for an agent node — a cold-restore
* `claude --resume <remote session id>` running on the WRONG MACHINE, under the local account.
* The refusal (`PtyCreateResult.unavailable`) is the honest answer: the node shows a
* "not connected" overlay and re-spawns when the master is back.
*/
requireRemote?: boolean
/**
* "If this create turns out to be a COLD start, I want the persisted scrollback back." Set by a
* caller that would otherwise replay the snapshot into its own emulator (i.e. not a node being
* opened for the first time with an `initialCommand`).
*
* It exists because the emulator is the wrong place for it on a tmux-backed session: tmux puts
* the client on the alternate screen at attach, hiding anything written before it. With this
* set, core writes the snapshot into the new PANE instead and answers
* `PtyCreateResult.scrollbackSeeded`. Ignored on a warm attach, a co-attach join, an SSH-project
* node and the non-tmux backends — there the caller's own replay still applies.
*/
restoreScrollback?: boolean
/**
* The ONE way a terminal may run on THIS machine while it sits on an SSH project's canvas: the
* local-account login node Settings → Accounts drops onto whatever canvas is active. Core refuses
* every other local spawn whose `ownerProjectId` is an SSH project (`PtyManager.setSshProjectCheck`,
* issue #1186) — the node fields that route a node remotely come from a shared file, and a node
* that lacks them must never become a local shell. Set only from an in-memory, never-persisted
* renderer mark (`renderer/lib/localOnSshCanvas.ts`), never from node data.
*/
localOnSshCanvas?: boolean
/**
* Hosted-relay VIEWERS may watch a terminal but never start one: refuse a create that would spawn
* a NEW session (`unavailable: 'join-only'`), while a co-attach join or a warm tmux reattach still
* proceeds. Set only by the relay access policy (src/core/relay/access-policy.ts).
*/
joinOnly?: boolean
/**
* The opposite of `joinOnly`: this create may only SPAWN a brand-new session. A co-attach join, a
* reattach to a live tmux / session-host / Zellij session under this node's name, and a create
* whose existence probe cannot answer are all refused (`unavailable: 'new-only'`), so the caller's
* `fresh: true` means "this create made the session". Set only by the relay scoped-guest policy
* (src/core/relay/scoped-guest-policy.ts) for a node id the guest introduced itself: naming a node
* id must never be a way to take over a session somebody else is running under it.
*/
newOnly?: boolean
/**
* `false`: this view never constrains the shared pty's size (a viewer's small window must not
* shrink everyone's terminal). It is still a subscriber and is told the authoritative size.
*/
sizeVote?: false
}
/** A tmux pane's cursor, as tmux reports it: 0-based column/row within the pane, plus whether the
* application currently wants it shown (`#{cursor_flag}`). */
export interface PaneCursor {
x: number
y: number
visible: boolean
}
/** Outcome of typing keys into a node's pane by id (`PtyApi.sendPaneKeys`). Never a rejection. */
export type PaneKeysResult =
| { ok: true }
| { ok: false; reason: 'not-connected' | 'unsupported-backend' | 'no-ssh' | 'failed' }
/**
* Result of creating a PTY session. `fresh` distinguishes a tmux session that had to be
* created anew (cold start — e.g. after a machine reboot killed the tmux server) from a
* reattach to a still-running session (warm — e.g. an app restart). The renderer uses it to
* replay the persisted scrollback and re-launch a resumable agent only on a cold start.
*/
export interface PtyCreateResult {
sessionId: string
fresh: boolean
/**
* `fresh` is FALSE, but the freshness read never completed — so "a session already exists" was a
* fold, not an answer (`RemoteSessionIndex`: only tmux's own exit 1 is evidence of absence, and
* every other outcome answers "exists" because typing `claude --resume …` into a live agent pane
* is the worse failure). SSH nodes only; a local `has-session` does not have this failure mode.
*
* Under a mount burst that overruns the host's `MaxSessions`, that fold is wrong often enough to
* matter: `tmux new-session -A` then CREATES an empty session, `fresh:false` skips cold restore,
* and the node sits at a bare shell with the user's conversation stranded on disk. MEASURED on
* the reporting host: of 107 sessions created in one switch, 66 ended at a bare shell — against
* 4 of 22 in a smaller burst minutes earlier, i.e. load-dependent, i.e. a race.
*
* The renderer re-asks ONCE after the attach has landed (tmux's own `#{session_created}` settles
* it; see `PtyApi.sessionAge`) and runs the cold-restore relaunch if the session turns out to be
* one we just made. Absent = the verdict was read, or this is not a remote node ⇒ nothing to
* re-ask.
*/
freshUnverified?: boolean
/** Set when the node's `accountId` had no config dir at spawn, so the session fell back to the
* system account. The renderer flags the account chip (folder-missing warning) when true. */
accountFallback?: boolean
/**
* WARM reattach only (local tmux): the reattached session's live working directory no longer
* exists — the folder was deleted (or deleted and re-created, which is a DIFFERENT inode, so the
* shell inside keeps printing `getcwd: cannot access parent directories`; issue #464). `tmux
* new-session -A` ignores the cwd we pass on a reattach, so this is the only moment the fact is
* knowable cheaply. The renderer shows a dismissible banner with an explicit
* recycle-and-respawn action — NOTHING is typed into the pane and nothing restarts on its own
* (the pane may be mid-work, and text into a pane is injection).
*
* Absent = fine or unknowable (fresh spawn, plain shell, SSH-remote session, probe failed, or a
* core older than this field over the relay) — the banner never shows on a guess.
*/
staleCwd?: boolean
/**
* The CURRENT SCREEN of a session this create JOINED (co-attach), captured from tmux — write it
* into the fresh xterm before the live stream starts.
*
* Only a co-attaching client ever gets it, and only when the join left the pty's grid unchanged.
* A joiner is `fresh:false`, so it skips the cold-restore scrollback replay; the only other thing
* that could paint its empty terminal is a tmux redraw, and tmux only redraws on SIGWINCH — i.e.
* when the joiner is strictly SMALLER and actually resizes the pty. Equal (the expected case: the
* node's persisted geometry and the font settings are the same on both clients) or larger resizes
* nothing, so without this the second viewer would sit on a blank-but-live terminal until the next
* byte of output. When the join DOES resize, this is deliberately absent: tmux paints it, and
* painting twice would splice two points in time.
*
* Guaranteed non-empty when present (an empty/failed capture is omitted, exactly like `pty:resync`
* — a plain-shell session has no tmux to capture and simply gets nothing).
*/
screen?: string
/**
* Where the CURSOR sits in the session that `screen` was captured from, in 0-based pane
* coordinates, with tmux's cursor-visibility flag.
*
* The THIRD thing `capture-pane` does not carry, after the mouse modes below. Its output is the
* pane's TEXT, so painting it leaves the emulator's cursor wherever the last character landed —
* the end of the last non-blank row. That was visible as: refresh a terminal running an agent
* CLI, and the block cursor sits at the end of the status line instead of in the input prompt,
* until the first keystroke makes the app repaint and place it (reported 2026-08-05).
*
* Absent when tmux could not be asked, which the renderer treats as "leave the cursor alone" —
* the pre-fix behaviour, and better than guessing a position.
*
* The coordinates are absolute in the pane, and the paint preserves that frame: the capture
* starts at pane row 0, the renderer writes it into a terminal that is at least as tall (a
* SMALLER joiner resizes the pty, and a resizing join gets no `screen` at all), and tmux trims
* trailing blank rows — so nothing scrolls and pane row N is emulator row N.
*/
cursor?: PaneCursor
/**
* This create JOINED a live TMUX-backed session (co-attach), so the fresh xterm must be told
* tmux's mouse-tracking is on. tmux emits the mouse-enable DECSET sequences (`?1000h ?1002h
* ?1006h`) to a client ONLY at its own attach — a mid-stream subscriber (the kanban card modal,
* a second window) never sees them, and neither `screen` (`capture-pane` carries no private
* modes) nor a SIGWINCH redraw re-emits them. Without them xterm treats the wheel as local
* scrollback (empty on the alternate screen), so the joiner cannot scroll tmux's history until a
* keystroke makes the app re-request mouse. The renderer writes `CO_ATTACH_MOUSE_SEQ` when this
* is set. Since our tmux is always `mouse on` (local and remote), enabling these unconditionally
* on a tmux-backed join matches tmux's own invariant client state; the enable is idempotent.
* Set on BOTH join branches (screen-painted and resized) — the resize does not deliver them.
* Absent for a plain-shell join (no tmux ⇒ no tmux mouse), for a session-host (Windows) join —
* same gate as `coAttachAltScreen`: no tmux runs `mouse on` there, and enabled tracking would
* hand the wheel and drags to the shell — and for the solo spawn path.
*/
coAttachMouse?: boolean
/**
* A TMUX-BACKED joiner must switch its fresh xterm to the ALTERNATE buffer before painting.
* tmux emits `\e[?1049h` to a client only at that client's own attach; a joiner (a renderer
* reload re-joins the same still-alive tmux client, and the kanban card modal is always a
* joiner) never sees it, so its xterm stayed on the NORMAL buffer: up to 10k lines of tmux's
* scrolled output piled up there and every output frame forced a layout (xterm's viewport
* resync) — measured 16.1% vs 7.3% total CPU for one terminal streaming 20 lines/s.
* Absent for plain-shell and session-host sessions: there the pty IS the shell and its
* normal-buffer scrollback is the only history it has. Known limitation: a REMOTE SSH session on
* a host WITHOUT tmux (`tmuxOrExplain`'s plain login-shell fallback) is still recorded tmuxBacked,
* so it gets this (and `coAttachMouse`, and `tmuxClient`) too; detecting that is a follow-up.
*/
coAttachAltScreen?: boolean
/**
* This session's client is a real TMUX client (local or remote; never a session-host session or a
* plain shell) — set on EVERY create, the solo spawn as well as a join. A `pty:resync` repaint
* (`repaintResync`) calls `term.reset()`, which drops the emulator back to the NORMAL buffer and
* clears mouse tracking; tmux does not re-send either (it emitted them once, at attach), so the
* renderer re-applies `CO_ATTACH_ALT_SCREEN_SEQ` + `CO_ATTACH_MOUSE_SEQ` after the reset when
* this is set. Same condition as `coAttachAltScreen`, asked of every session rather than only a
* joiner. Absent = unknown (an older core or relay peer) ⇒ the renderer re-applies nothing, the
* pre-field behavior.
*/
tmuxClient?: boolean
/**
* This session is TMUX-BACKED (local or remote) — it survives losing this client, so killing our
* pty client only detaches us and everything running in the session keeps going.
*
* False = the plain-shell fallback (no tmux installed, tmux switched off, or a node with no
* persistKey): the pty IS the shell, and killing it kills the shell and every process under it —
* an agent CLI mid-task included. The renderer needs the difference because several of its
* levers dispose a terminal purely as a CACHE (the park window, the park LRU cap, the
* memory-pressure drop), a call that is only cheap when tmux is underneath. See
* `renderer/terminal/park-budget.ts` (`canDisposePark`) and issue #126.
*
* Absent = unknown (a core older than this field, over the relay): the renderer must then assume
* the historical behavior (persistent), never protect on a guess.
*/
persistent?: boolean
/**
* This session is owned by the session-host backend (Windows, or POSIX with no tmux), not tmux.
* Set only on a SPAWN answer; absent everywhere else (tmux, plain shell, a join, an older core).
*
* The renderer's launch writer reads it for one decision: a FRESH session-host shell is trusted
* without a pane probe, because that backend's probe is a process-tree walk that cannot tell a
* shell from its prompt's helpers (a `git`/`starship` child reads as "not a shell") — issue
* #916. A fresh tmux pane keeps its probe: tmux's answer is exact, and it still covers the rare
* `new-session -A` race where another client created the session first.
*/
sessionHost?: boolean
/**
* REFUSED: this node's session was permanently destroyed by ANOTHER client, so nothing was
* spawned (`sessionId` is empty) — the terminal shows the "closed by <name>" state instead.
*
* This is the tombstone (PtyManager): `pty:closed` only reaches a session's SUBSCRIBERS, and a
* co-viewer whose project is inactive or closed is not one. Without this, the create it issues
* when it later opens that project would happily spawn a brand-new `nt-<id>` and resurrect a
* terminal its owner deliberately deleted. The client that DID the destroy is exempt (its ⌘Z
* must still restore the node), so the single-user delete→undo path is unchanged.
*/
closed?: { by: number | null }
/**
* REFUSED: `requireRemote` was set and no remote spawn was possible (no live ControlMaster, or
* no `ssh` executable), so nothing was spawned (`sessionId` is empty) — see
* `PtyCreateOptions.requireRemote` for what used to happen instead. The renderer shows the
* "not connected" overlay and re-spawns the node once the project's master is back.
*
* `'ssh'` is only ever set for a create that would have SPAWNED: a co-attach to a live session
* for this node id on the requested remote still joins, so a second view of a healthy remote
* terminal is unaffected.
*
* `'held-elsewhere'`: a `requireRemote` create found a live session for this node id held by this
* process, but NOT on the requested remote — it is local, or its endpoint (host, user, port)
* differs from the create's `sshRemote`. The join is refused and nothing was started; the held
* session is left untouched. A create with no `sshRemote` (master down) still joins a held
* remote session. Not a lost connection: retrying would refuse again.
*
* `'codex-account'` is the S6 fail-closed twin: a LOCAL Codex node that explicitly selected a
* managed account whose home is missing refuses rather than spawning against the system login
* (§5 property 4). Remote managed Codex accounts refuse unknown/unsafe ids or unresolved/unsafe homes.
* System SSH Codex may attach before remote home discovery. Nothing spawned on refusal.
*
* `'join-only'`: `PtyCreateOptions.joinOnly` was set (a hosted-relay viewer) and no running
* session could be confirmed to join or reattach to — either it is gone, or its existence could
* not be checked — so nothing was started. Not a lost connection.
*
* `'new-only'`: `PtyCreateOptions.newOnly` was set (a relay guest's create for a node it
* introduced) and a session already exists under this node's name, or its existence could not be
* checked. Nothing was joined or started, and the existing session was left untouched.
*/
unavailable?: 'ssh' | 'codex-account' | 'join-only' | 'held-elsewhere' | 'new-only'
/**
* Core already put the persisted scrollback (and the "session restored" separator) into the new
* tmux pane — see `PtyCreateOptions.restoreScrollback`. The caller must NOT replay the snapshot
* into its emulator: tmux paints it and owns it as history. Only ever set with `fresh: true`.
*/
scrollbackSeeded?: boolean
}
/** Payload of `pty:recycled` — see IPC.ptyRecycled and `recycleAction` in the renderer. */
export interface RecycledInfo {
/** A replacement session is registered for the node: restart onto it. False = the escape-hatch
* timeout fired with no replacement (the recycler died mid-move) → do NOT respawn. */
ready: boolean
}
// 'subagent' and 'loop' are render-only (ephemeral hook-driven viz) and never persisted.
// 'trigger' is a first-class PERSISTED kind (issue #493) — the canvas-owned schedule node; its
// spec rides `CanvasNodeState.trigger` and is sanitized on every load path (@shared/trigger).
export type NodeKind = 'terminal' | 'sticky' | 'group' | 'editor' | 'diff' | 'video' | 'web' | 'browser' | 'files' | 'subagent' | 'loop' | 'dino' | 'trigger' | 'simulator' | 'whiteboard'
/** Persisted state of a single canvas node (terminal, sticky note, group frame, or editor). */
/**
* A launch a terminal node OWES once every station in `after` has gone idle — what the
* canvas-control `--after` flag arms instead of running the command on open. This is the
* difference between a fan-out and a graph: a downstream station starts when the upstream
* ones have produced something for it to read, without an orchestrator sitting in a poll loop.
*
* Persisted, because the wait can outlive an app restart — and note that agent state is NOT
* (it is rebuilt from live hook events), so after a restart an armed node has no way to learn
* that its deps already finished. That is why the node carries a manual "run now" escape:
* a stalled station must never be a dead end.
*/
export interface PendingLaunch {
/** false proves no input attempt; true/absent require explicit recovery after reload. */
attempted?: boolean
/** An attempted/uncertain delivery requires explicit Run now; never replay on hooks. */
manualOnly?: boolean
/**
* Node ids to wait for. Only nodes running a hook-reporting agent may appear here — a plain
* terminal never reports `done`, so waiting on one would stall forever (refused at creation).
* A dep that no longer exists counts as satisfied: a deleted node can never report.
*/
after: string[]
/** Delivered to the node's shell once the wait is over (agent CLI + prompt, or a plain command). */
command: string
/**
* Which core process owns delivery. Absent is the historical renderer-owned path. Server
* Edition headless opens stamp `server`, so a connected browser can render the armed state and
* dependency edges without racing the server to type the command into the same pane. The
* desktop's headless start (#925) stamps `core` on its manualOnly write-ahead claim.
*/
executor?: 'server' | 'core'
/**
* Server-owned dependencies whose first real turn has not been observed yet. A freshly spawned
* agent can briefly report `done` while its argv prompt is still booting; that idle blip must not
* release a downstream launch. The server removes an id only after a verified `working` event,
* then requires the ordinary later `done`. Persisted so a server restart cannot forget the gate.
* Desktop-owned launches leave this absent; renderer parity is a separate follow-up.
*/
awaitWorking?: string[]
/**
* Also wait for this worktree GROUP's project setup script to finish (`waitForSetup`). Set when
* the node is opened into a frame whose checkout is still being prepared — running a command in a
* half-installed worktree is the failure this gate exists to prevent. It names a group id, never
* a command: nothing here is ever executed, it only selects a run to ask about.
*
* A group with no run on record counts as done (`launchesToFire`), so a persisted arming that
* outlives the run's event stream — an app restart — releases rather than strands the node.
*/
awaitSetupGroup?: string
/**
* Also wait on GitHub pull requests of the project's board repository (`--after-pr`, see
* @shared/pr-wait). ANDed with `after` and the setup gate. Validated at both serializer seams
* (`normalizePendingLaunch`): a malformed value becomes a hold that never fires on its own.
* A build older than this one does not know the field and releases the node on `after` alone.
*/
afterPr?: PrWaitHold
/**
* Also wait for these stations to REPORT SUCCESS (`--after-success`, see @shared/station-outcome):
* each id is in `after` too, so this adds "and it said it succeeded" to "its turn is over". ANDed
* with every other gate. Validated at both serializer seams (`normalizePendingLaunch`): a malformed
* value becomes a hold that never fires on its own. A build older than this one does not know the
* field and releases the node on the turn ending alone.
*/
afterSuccess?: import('./station-outcome').SuccessWaitHold
/**
* The file `command` reads its prompt from (`"$(cat '<path>')"`): a `--prompt-file`, or a long
* `--prompt` spilled to a file (#706). A held launch may be delivered weeks after it was armed, so
* the delivery loop checks this file still exists before it types the command, and holds the node
* for ▶ with the reason when it does not — an agent started with no brief is the failure the
* open-time existence check exists to catch. Absent for a prompt that rides the command inline.
*/
promptFile?: string
}
export interface CanvasNodeState {
id: string
kind: NodeKind
position: { x: number; y: number }
size: { width: number; height: number }
title: string
/**
* Agent nodes only: while true (the default), the node title auto-tracks the agent's own
* session name. Set false once the user renames the node by hand, so we stop overwriting it
* and instead push the user's name back to the agent via `/rename`. Persisted.
*/
titleAuto?: boolean
color: string
group: string | null
/** Labels for organizing/filtering terminals. */
tags?: string[]
/** When true the node body is hidden (header-only). */
collapsed?: boolean
/** Agent nodes only: when true, this node's subagent/loop fan-out cards are hidden. */
hideFanout?: boolean
/** Terminal nodes: the ⌘M view (chat / markdown) is open. Persisted, so leaving a project and
* coming back (or a reload) reopens the node the way the user left it instead of on the raw
* terminal. Absent = closed. */
mdMode?: boolean
/**
* A user-chosen icon shown wherever this node is listed (canvas header, kanban card, sessions
* sidebar): one emoji/character, or an image file. Absent = the node draws exactly as it did
* before the feature. Validate with `normalizeNodeIcon` at the point of use — this value comes
* from a git-shared, hand-editable project file. See @shared/node-icon.
*/
icon?: import('./node-icon').NodeIcon
/** Parent group node id, if this node belongs to a group frame. */
parentId?: string
// terminal-only
/** This terminal's own font size (issue #915), set with ⌘+ / ⌘− when
* `settings.terminalFontZoomKeys` is on; absent = follow the global `fontSize`. Hand-editable,
* so every reader goes through `normalizeTerminalFontSize` (renderer/terminal/terminal-font-zoom). */
terminalFontSize?: number
shell?: string
cwd?: string
/** Which agent runs in this terminal node (claude/codex/gemini/custom). */
agentId?: AgentId
/** Model selected for this agent node through the shared model gateway. */
agentModel?: string
/**
* Agent nodes started on a GitHub issue ("Start with agent" on an issue card, or
* `open-agent --issue`): WHICH issue this session works on. It drives the binding chips (the
* issue card's run chips, the node header's `#N`) and the issue card's run history — never a
* launch line: the launch prompt was composed once, at creation, from a validated reference.
* Git-shared, so hostile input: `normalizeIssueRef` runs at both serializer seams. See
* @shared/github-issue-ref.
*/
issueRef?: import('./github-issue-ref').IssueRef
/**
* The node id of the agent that OPENED this node through a canvas-control open verb
* (`open-agent`/`open-claude`/`open-terminal`, `spawn-team`, `verify`) — recorded where that verb
* draws its lineage rope. It is what lets the app tell the right agent when this station stops
* (@shared/station-notice): a rope alone cannot, because an `--after` station is roped to the
* stations it waited on as well, with the same id shape. Git-shared, so hostile input: validated
* with `isSafeNodeId` at both serializer seams, and honoured only while the opener's rope to this
* node still exists and the opener is a canvas-capable agent node in the same project.
*/
openedBy?: string
/**
* One-shot "Restart on subscription" flag: when set, the next `transport.create` strips gateway +
* inherited provider env (per `vanillaEnvStripPattern`) so the agent resumes against its own
* default provider. Set by the clear-env recycle action, cleared after the spawn resolves so an
* ordinary Restart re-applies the gateway. See `PtyCreateOptions.clearEnv`.
*/
clearEnv?: boolean
/** Set while this node is armed but not yet launched — see PendingLaunch. */
pendingLaunch?: PendingLaunch
/**
* Claude-only: managed account this node runs on (CLAUDE_CONFIG_DIR injection).
* Resolved once at node creation (explicit pick → project default → system default)
* and immutable for the node's lifetime. Undefined = system default (~/.claude).
*/
accountId?: string
/**
* Agents in `SESSION_ID_CAPABLE` (claude): the session id nodeterm minted and launched this
* node's CLI with (`--session-id`). Persisted so a cold restore can resume even when no hook
* ever delivered an id — the SSH reverse tunnel is the only path that carries one, and a node
* whose tunnel was down came back as a blank conversation with its transcript intact on disk.
* The hook-fed id still wins when known: `/clear` and `--fork-session` mint a new one in-CLI.
*/
agentSessionId?: string
/** When set, the terminal runs `ssh` to this host on the local PTY; persisted (auto-reconnects). */
ssh?: import('./ssh').SshConnection
/** When true (SSH-project terminals), the node runs in REMOTE tmux on `ssh` rather than `ssh`-on-local-PTY. */
sshRemoteTmux?: boolean
/** editor-only: when true (SSH-project editors), reads/writes go to the project's remote fs via `sshFs`. */
sshFs?: boolean
/**
* Run nodes only (a terminal node that runs a `.vscode/launch.json` configuration): folder,
* configuration, device, reload-on-save. Git-shared and hand-editable — read through
* `normalizeRunConfig` (@shared/run-config) on every load AND save.
*/
runConfig?: import('./run-config').RunNodeConfig
/** Run nodes: a simulator shown inside the node. Read through `normalizeInlineSimulatorConfig`. */
runSimulator?: import('./simulator').InlineSimulatorConfig
/** simulator-only: which iOS simulator the node shows. Read through `normalizeSimulatorConfig`. */
simulator?: import('./simulator').SimulatorNodeConfig
// sticky-only
text?: string
/**
* sticky-only: last canvas-control `sticky` write — when, and the title of the agent node that
* wrote it. The stamp means "an agent synced this", not "last touched": a hand edit clears both,
* so a stale stamp can never vouch for text the user has since rewritten.
*/
textUpdatedAt?: number
textUpdatedBy?: string
/**
* whiteboard-only: the board this node shows until it saves its own — set on a duplicate or a
* reopen (which get a NEW id) so the copy needs no file copy and no board file is ever deleted.
* A node id, never a path: the core resolves it inside this project (core/whiteboards.ts).
*/
whiteboardSource?: string
/** whiteboard-only: epoch ms of the last editing session that changed the board. Written once
* per session (never per stroke) — what a linked agent's "the board changed" keys on. */
boardRev?: number
// dino-only: best score reached in the T-Rex Runner game.
highScore?: number
// editor / diff
filePath?: string
/**
* editor/diff-only: true once `filePath` was confirmed gone (e.g. its worktree was removed —
* see `displacedByWorktree` in `./worktree.ts`). There is nothing to re-point the node at, so
* it shows a persistent notice instead of silently opening blank / failing a `git show`.
*/
fileMissing?: boolean
/** web-only: when set, the web node loads this live URL (else it loads `filePath` as local html). */
url?: string
/**
* browser-only: the Electron session partition for an AGENT-opened browser node
* (`persist:nt-agent-browser-<projectId>`), set once at creation and never mutated. Absent for a
* USER-opened node (default session, no migration). Persisted so the jar survives reopen; carried
* through untouched on Server Edition / mobile, where a browser node renders with no <webview>.
*/
partition?: string
/** browser-only: popped out of a run node's browser panel — that run node's id. */
dockTo?: string
/** Run nodes: the browser panel inside the node. Read through `normalizeRunBrowserConfig`. */
runBrowser?: import('./run-preview').RunBrowserConfig
/** diff-only: true = staged diff (HEAD vs index), false = unstaged (index vs working). */
diffStaged?: boolean
/** diff-only: when set, the diff shows parent (<oid>^) vs commit (<oid>) for a file from history. */
commitOid?: string
/** group-only: when bound, the git worktree this group works in. */
worktree?: GroupWorktree
/**
* trigger-only: the schedule + payload + target this node represents (issue #493). Git-shared
* CONTENT — deliberately, the team shares the definition — which is exactly why it is treated
* as hostile on every load path (`sanitizeNodeTriggers` in core/workspace-files) and why the
* definition alone never fires: execution additionally requires this machine's arm record
* (`core/trigger-arm-store.ts`), bound to the spec's exact content. See @shared/trigger.
*/
trigger?: import('./trigger').TriggerSpec
/**
* Set while the node is maximized to fill the viewport (issue #399): the rect to give back on
* the toggle's second click — the node's ROOT-space (absolute canvas) position plus its size.
* Absent = not maximized. Persisted so the restore survives a reload. Root-space on purpose:
* maximizing a grouped node re-fits (and thereby moves) its frame, so a parent-relative rect
* would restore a few px off — and root-space also survives the frame being ungrouped meanwhile.
*/
premaxRect?: { x: number; y: number; width: number; height: number }
}
/**
* One entry in `Project.closedSessions` — everything needed to recreate a fresh node in the same
* spot a deleted one used to occupy. `node` is the exact shape a live node is already persisted
* as (`CanvasNodeState`); `absolutePosition` is captured at delete time because `node.position`
* is relative-to-parent when `node.parentId` is set, and that parent group may not exist by the
* time this entry is reopened.
*/
export interface ClosedSessionEntry {
id: string
closedAt: number
node: CanvasNodeState
absolutePosition: { x: number; y: number }
/**
* The agent session this node was running when it was closed — a POINTER to the transcript the
* agent CLI already owns, never a copy of its text (issue #531). It is the one fact that dies
* with the node and cannot be recovered afterwards: the live id is held only in the transient
* `agentStatus` store, whose entry is dropped on delete, while the transcript `.jsonl` itself
* stays on disk under the agent's own root. Without it a closed station's work cannot be read
* back at all, which is what made "close the node once its branch is merged" quietly destructive.
*
* Captured at close from the hook-fed live id, falling back to `node.agentSessionId` (the id
* nodeterm minted at creation) — the two agree whenever both exist, and each covers a case the
* other misses (a RESUMED session has no minted id; a node that never emitted a hook event has
* no live one).
*
* MACHINE-LOCAL by construction: `closedSessions` rides `IndexEntryV3`, never the git-shared
* `.nodeterm/project.json` (see `Project.closedSessions`), so a session id — a `$HOME`-anchored
* fact about one person's machine — is never shipped to everyone who clones the repo.
*/
sessionId?: string
}
/**
* How many closed-session entries one project keeps (newest-first; the rest are dropped).
*
* ONE definition, because the cap must hold at every point an entry list is produced OR admitted:
* the store mutator that records a delete (`recordClosedSessions`), and every load path that
* admits `IndexEntryV3.closedSessions` (a ref'd project's machine-local history) or an inline
* project's embedded one. Enforcing it only where WE append is not enforcement at all —
* workspace.json is hand-editable input too, so an inflated list can arrive from outside (a
* pre-cap build's file, a hand edit) and would render unbounded rows and be written back in full.
*/
export const CLOSED_SESSIONS_CAP = 20
/**
* A snapshot of one canvas's nodes in the form sent over the remote mirror wire.
* Reuses the persisted node shape (`CanvasNodeState`) so host and client agree on layout.
*/
export interface CanvasState {
nodes: CanvasNodeState[]
}
/**
* A minimal change to a canvas: replace-or-append a node by id, or drop one by id — and, on the team
* canvas-sync path, the same for one persisted edge (`edge-*`) or one board item (`kb-*`, see
* `KanbanOp` below and @shared/kanban-ops).
* Used for the client's optimistic edits and host-side diffing (see `applyMutation`/`diffToMutations`).
*
* `src` and `seq` exist ONLY on the team canvas-sync path (`canvas:mut`), and they are what makes
* two people editing one node CONVERGE instead of splitting brain (see src/shared/canvas-order.ts):
* - `src` is stamped by the sending client's publisher — a random per-Canvas tag, so a client can
* recognize its OWN mutation coming back (the reflector echoes to everyone, sender included:
* that echo is the ACK that tells the sender where its edit landed in the total order).
* - `seq` is stamped by the reflector (src/core/canvas-sync.ts) and is the TOTAL ORDER. It is
* server-authoritative: a client-supplied `seq` is overwritten at ingest, never trusted.
* - `seen` is the sender's CAUSAL stamp: the highest `seq` it had applied at the moment it cast.
* It answers the one question `seq` alone cannot — "did this client already know about the
* delete?" — which is what lets a delete beat a concurrent drag frame instead of being
* resurrected by it (canvas-order's rule 4). Client-supplied; the reflector clamps it below the
* order it is being given, which is hygiene and changes no verdict (see `stampMutation`). A
* mutation without it is judged exactly as before, so an unstamped peer degrades rather than
* breaks.
* - `origin: 'core'` is ALSO reflector-authoritative: a client-supplied one is deleted at ingest.
* The core adds it only on a copy that came from an OWNER client (or the core itself) and goes to
* an owner client, and it is the ONE thing that lets a receiver take the node's machine-local
* `pendingLaunch` as sent (@shared/node-exec `mutationTrustsLaunch`). It means something only on
* a node `upsert`; every other op may carry it (the reflector vouches per recipient, not per op)
* and ignores it.
* The legacy relay host's canvas mirror (`canvas:state` / `canvas:mutate`: src/main/remote/
* host-service.ts and canvas-sync.ts, which stayed there when the relay transport moved to
* src/core/relay) uses the same vocabulary and simply omits these stamps.
*/
export type CanvasMutation =
| { op: 'upsert'; node: CanvasNodeState; src?: string; seq?: number; seen?: number; origin?: 'core' }
| { op: 'remove'; id: string; src?: string; seq?: number; seen?: number; origin?: 'core' }
| {
op: 'edge-upsert'
kind: CanvasEdgeKind
edge: BridgeLink
src?: string
seq?: number
seen?: number
origin?: 'core'
}
| {
op: 'edge-remove'
kind: CanvasEdgeKind
id: string
src?: string
seq?: number
seen?: number
origin?: 'core'
}
| (KanbanOp & MutationStamp)
/** The node and edge half of `CanvasMutation` — all a canvas SCENE diff (`diffToMutations`) ever
* produces. Their order keys are project-independent (node and edge ids are globally unique), so
* the ordering API accepts them without a project id; any value that MAY be a board op must name
* its project (see `mutationKey`). */
export type SceneMutation = Exclude<CanvasMutation, { op: `kb-${string}` }>
/** Stamp fields every canvas mutation may carry (see canvas-order): the sender tag, the reflector's
* total order, the sender's causal position, and the core's per-recipient vouching (`origin`).
* Documented on `CanvasMutation` above. */
export interface MutationStamp {
src?: string
seq?: number
seen?: number
origin?: 'core'
}
/**
* The board half of the `canvas:mut` vocabulary (@shared/kanban-ops): one op per board ITEM, so two
* people editing one board converge item by item instead of last-writer-wins on the whole `kanban`
* block. Keys live in one `k:` space (`kanbanOpKey`); only a column / label / view REMOVAL is a
* rule-4 deletion — `kb-card-remove` and `kb-meta-remove` set a card's placement / metadata to
* "none", an ordinary last-writer-wins value (`isKanbanDeletion`). `github` and `pullLinks` are
* outside the vocabulary and never cast.
*/
export type KanbanOp =
| { op: 'kb-column'; column: KanbanColumn }
| { op: 'kb-column-remove'; id: string }
| { op: 'kb-column-order'; ids: string[] }
| { op: 'kb-card'; assignment: KanbanAssignment }
| { op: 'kb-card-remove'; nodeId: string }
| { op: 'kb-meta'; meta: KanbanCardMeta }
| { op: 'kb-meta-remove'; nodeId: string }
| { op: 'kb-label'; label: KanbanLabel }
| { op: 'kb-label-remove'; id: string }
| { op: 'kb-label-order'; ids: string[] }
| { op: 'kb-view'; view: KanbanSavedView }
| { op: 'kb-view-remove'; id: string }
/**
* Which persisted edge list a mutation addresses — `bridges` (context links, which an agent can
* actually READ through) or `ropes` (display-only "spawned by" lineage). They are two arrays on
* the project with two different meanings, so the kind travels with the mutation; the ORDER,
* however, is keyed on the edge id alone (canvas-order's `e:<id>`), because one id is one edge and
* two clients must never end up holding it as both a bridge and a rope. The apply agrees
* (`applyEdgeMutationToScene`: an upsert takes the id out of the other list, a remove drops it from
* both), and so does the diff (an id that moved lists casts its upsert and no remove).
*/
export type CanvasEdgeKind = 'bridge' | 'rope'
/** Canvas pan/zoom state. */
export interface Viewport {
x: number
y: number
zoom: number
}
/** A persistent "bridge" link between two Claude nodes (lets their sessions message each other). */
export interface BridgeLink {
id: string
source: string
target: string
/**
* Context links only (issue #852): the ONE endpoint allowed to read the other. Absent = both
* read each other, which is every link persisted before the field existed. A value naming
* neither endpoint authorizes nobody (fail closed) — see `linkReadPairs` in canvas-link.ts.
*/
reader?: string
}
/** Where a column sits in a card's lifecycle (see @shared/kanban-category). A closed set; an
* unknown value read from a hand-edited or newer file reads as ABSENT (`columnCategory`), and is
* left in the file untouched so a newer build's value survives an older build's save. */
export type KanbanColumnCategory = 'unstarted' | 'started' | 'done' | 'closed'
/** One kanban board column. Column order = array order in ProjectKanban.columns. */
export interface KanbanColumn {
id: string
title: string
color: string
/** Optional lifecycle category. Absent = uncategorized (the pre-category board, and any column
* the user never categorized). Read it through `columnCategory`, never directly. */
category?: KanbanColumnCategory
}
/** Assignment of one session node to a board column. A session with no assignment sits
* in the virtual Ungrouped column (never persisted). Order within a column = `rank` (a
* fractional-index string, @shared/kanban-rank), and for an entry without a valid one, its
* position in ProjectKanban.assignments (@shared/kanban-order `columnOrder`). Every write keeps
* the ARRAY in rank order too, so a build that ignores `rank` shows the same column. */
export interface KanbanAssignment {
nodeId: string
columnId: string
/** Optional position key within the column. Absent / invalid ⇒ derived from array order. */
rank?: string
}
/** Per-project kanban board (docs/superpowers/specs/2026-07-18-kanban-view-design.md).
* Absent = never edited: the renderer shows a default 3-column board and writes
* nothing until the first change. Cards are the project's session nodes — the board
* stores only their column assignments. */
/** Trello-style per-card metadata. Lives beside the assignments (not on the node) so it rides
* the same git/mirror machinery; absent entries mean "no metadata". Assignee identity is the
* presence identity — the same {name, color} the board log attributes comments to. */
export type KanbanPriority = 'low' | 'medium' | 'high' | 'urgent'
export interface KanbanCardMeta {
nodeId: string
assignees?: BoardLogAuthor[]
/** Due timestamp (ms). Absent = no due date. */
dueAt?: number
/** Absent = no priority. */
priority?: KanbanPriority
/** Ids of the board labels applied to this card (see ProjectKanban.labels). Absent/empty = none;
* ids that no longer resolve to a label are dropped by readers (dangling-safe). */
labels?: string[]
}
/** The Notion label palette. A closed set so the chip colors and the picker can't desync; an
* unknown value read from a hand-edited file falls back to 'default'. */
export type KanbanLabelColor =
| 'default'
| 'gray'
| 'brown'
| 'orange'
| 'yellow'
| 'green'
| 'blue'
| 'purple'
| 'pink'
| 'red'
/** A board-level label (Notion-style): defined once per board, applied to any number of cards by
* id (KanbanCardMeta.labels). Order in ProjectKanban.labels is the palette's display order. */
export interface KanbanLabel {
id: string
name: string
color: KanbanLabelColor
}
/** A saved board view's filters (@shared/kanban-views). SHARED content: a view is how a team
* looks at its board. Deliberately NOT here: the live-state status chips (never persisted
* anywhere) and display preferences like showing closed columns (per user, localStorage). */
export interface KanbanViewQuery {
/** The source filter; absent = all. */
source?: 'all' | 'github' | 'pulls' | 'sessions'
/** Label filter keys (`local:<labelId>` | `github:<folded name>`); OR within the list. */
labels?: string[]
/** Assignee names (the presence identity's name); a card needs one of them. */
assignees?: string[]
/** Column ids to SHOW (`ungrouped` names the virtual column); absent/empty = every column. */
columns?: string[]
}
export interface KanbanSavedView {
id: string
name: string
query: KanbanViewQuery
}
export interface ProjectKanban {
columns: KanbanColumn[]
assignments: KanbanAssignment[]
/** Saved views — named filter sets shared with everyone on the board. Tolerated as absent or
* malformed (sanitizeViews); the ACTIVE view is per user (localStorage), never here. */
views?: KanbanSavedView[]
/** Optional card metadata; tolerated as absent/malformed by every reader (lib normalizes). */
meta?: KanbanCardMeta[]
/** Board-level label palette (Notion-style). Cards reference these by id in `meta[].labels`;
* tolerated as absent/malformed by every reader. */
labels?: KanbanLabel[]
/** Shared, non-secret GitHub issue label mapping. Local approval and credentials live elsewhere. */
github?: ProjectKanbanGitHub
/** Card ↔ pull request link tombstones and per-card auto-move opt-outs (@shared/kanban-pull-links).
* Hostile input: read only through `readPullLinks`. */
pullLinks?: KanbanPullLinks
}
/** Who produced a board-log entry (a teammate on a shared board, or this user). */
export interface BoardLogAuthor {
name: string
color: string
}
/** A structural board change worth recording. `type` is closed; the optional fields carry
* the human-readable names resolved at event time (the virtual column is named 'Ungrouped'). */
export interface BoardLogEvent {
type:
| 'card-created'
| 'card-moved'
| 'column-added'
| 'column-renamed'
| 'column-deleted'
| 'member-assigned'
| 'member-unassigned'
| 'due-set'
| 'due-cleared'
| 'priority-set'
| 'priority-cleared'
/** An agent-to-agent message delivery. `from`/`to` are NODE IDS (not column names) and `title`
* is the delivery's outcome kind — a trace that cannot answer "did it land?" answers the only
* question anyone asks it with silence. Written by `agent-message-trace.recordDelivery`. */
| 'agent-message'
/** An agent read a site's cookies through `browser --cookies` — a data-exfiltration surface the
* owner allowed but that MUST be loudly traced (PR 9 Task 9.2/9.3). `from` = the owner agent
* node's title, `to` = the domain read, `title` = the browser node's title; `nodeId` = the owner
* agent node so it files under that agent's card. Written BEFORE the read (fail-closed): a cookie
* read that happened but was not recorded is the one outcome this trace exists to prevent. */
| 'agent-read-cookies'
/** An agent session was started on a GitHub issue. Filed under the issue CARD's board-log
* identity (`issueLogId`), not the node's, so the issue keeps its run history after the
* session's node is gone. `run` names the session; `title` is the node title at the time. */
| 'run-started'
/** That session's node was closed. `run.end` is the last agent state observed at that
* moment — a turn ending (`done`) is NOT a run ending, which is why this is written only when
* the node goes. */
| 'run-ended'
/** A station an agent opened stopped, and that agent was told (src/core/agents/
* station-notice.ts). Filed under the RECIPIENT's card — the orchestrator's — because that is
* who has to act on it. `from` = the station's node id, `to` = the reason (a
* `StationFailureReason`, @shared/station-notice), `title` = the station's title as the notice
* carried it (one line, capped). Never any station output. */
| 'station-failed'
/** A station reported its TASK outcome (`report-outcome`, @shared/station-outcome). Filed under
* the STATION's own card. `from` = the station's node id, `to` = the outcome (`succeeded` /
* `failed`), `title` = its note (one line, capped). Written by the app, never a gate: the
* outcome a `--after-success` wait reads lives in core's transient store, not in this file. */
| 'station-reported'
from?: string
to?: string
/** Column title for column-added/deleted; card title for card-created; outcome for agent-message;
* for card-moved, the reason when the board moved the card itself ("PR #12 merged"). */
title?: string
/** agent-message only: the `notPermitted` reason when that is the outcome. From a shared file like
* every field here, so a reader treats it as an untrusted string. */
reason?: string
/** run-started / run-ended only. No cost or token figure: nodeterm has no cumulative number for
* a session, and a context-window reading is not one. */
run?: {
nodeId: string
agentId?: string
sessionId?: string
end?: 'done' | 'working' | 'waiting' | 'blocked' | 'errored' | 'dropped' | 'unknown'
}
}
/** One line of the append-only board history (`.nodeterm/board-log.jsonl`). A `comment`
* carries `text`; an `event` carries `event`. Serialized one-per-line as JSON. */
export interface BoardLogEntry {
id: string
ts: number
author: BoardLogAuthor
nodeId?: string
kind: 'comment' | 'event'
text?: string
event?: BoardLogEvent
}
/** Max chars kept for a comment's `text`. On an SSH project the whole JSON line becomes one
* shell arg (`printf '%s\n' '<line>'` over the ControlMaster); an unbounded paste blows past
* ARG_MAX → the append fails → the optimistic entry silently vanishes on reload. Locally it
* just bloats the append-only file. Shared so core (disk) and the renderer (optimistic UI)
* clamp identically. */
export const BOARD_LOG_TEXT_MAX = 16_384
/** Read options for the board log: cap the newest N entries (default 500 in the store) or `all`. */
export interface BoardLogReadOpts {
cap?: number
all?: boolean
}
/** Result of a board-log read. `unsupported` is set (with `entries: []`) when the project has no
* reachable log — an inline/no-cwd canvas, a disconnected SSH project, or an SSH project on the
* Server Edition (v1 has no remote board log there). */
export interface BoardLogReadResult {
entries: BoardLogEntry[]
unsupported?: boolean
}
/** The board-log surface on `window.nodeTerminal`. Project-routed: the main/server side resolves
* the project to a local cwd, a desktop SSH connection, or unsupported. `append` is
* fire-and-forget-safe (resolves `false` on any failure, never throws). */
/** One captured debug-log line (issue #78). `seq` is monotonic across the process lifetime so
* subscribers can dedupe batches against the snapshot they filled from. */
export interface LogRecord {
seq: number
/** Epoch ms. */
ts: number
level: 'debug' | 'info' | 'warn' | 'error'
/** The `[subsystem]` prefix convention the codebase logs with; '' when absent. */
tag: string
msg: string
}
export interface LogApi {
/** The whole ring, oldest-first — the panel's initial fill. */
snapshot(): Promise<LogRecord[]>
/** Empty the ring (the panel's Clear button). */
clear(): void
/** Subscribe to batched pushes; returns an unsubscribe. Batches may overlap the snapshot
* around the subscribe edge — dedupe by `seq`. */
onBatch(cb: (batch: LogRecord[]) => void): () => void
}
export interface BoardLogApi {
/** Append one entry. Resolves `false` on any failure (unsupported project, fs/exec error). */
append(projectId: string, entry: BoardLogEntry): Promise<boolean>
/** Read the log newest-first (see BoardLogReadResult). */
read(projectId: string, opts?: BoardLogReadOpts): Promise<BoardLogReadResult>
/** Subscribe to change pushes for one project; returns an unsubscribe. */
onChanged(projectId: string, cb: () => void): () => void
}
/** One recorded "deliberate landing" on a node — the breadcrumb trail's unit. Frozen at record
* time (nodeId only, no live pointer): a deleted node is filtered at render, a renamed one shows
* its current title (read live), but the `note` stays a snapshot of what was happening then. */
export interface NavStop {
nodeId: string
at: number
note: string
}
/** MACHINE-LOCAL: this SSH project was handed over to a hosted team on its host ("Share with
* team"). From that moment the server core is the only writer of its project.json, so this
* desktop never mirrors, reconciles or polls it again. `hostId` absent = the handover started
* and did not finish (the same guard applies until the user reopens it). */
export interface HandedOffTo { hostId?: string; projectId?: string; at: number }
/** A project is one canvas/page: its own nodes, viewport, and default working dir. */
export interface Project {
id: string
name: string
color: string
/** Optional icon shown beside `name` (tab, start screen). Git-shared like `name`/`color` — see
* `sanitizeProjectIcon` (@shared/project-icon) for the hostile-input rules a stored value must
* pass on load. */
icon?: ProjectIcon
/** Default working directory for new terminals created in this project. */
cwd?: string
/**
* MACHINE-LOCAL: this folder project's canvas lives in app data (`userData/inline-projects/<id>.json`),
* not in `<cwd>/.nodeterm/project.json`, and nothing is written into the folder (issue #1145).
* Only meaningful beside a local `cwd`; never written to any shared file. See the
* folder-data-ref kind in core/workspace-files.ts (`IndexEntryV3.dataFile`).
*/
storeInAppData?: boolean
/** When set, this is an SSH project: its terminals run on `server` in `remoteCwd` (remote tmux). */
ssh?: { server: import('./ssh').SshConnection; remoteCwd: string }
viewport: Viewport
nodes: CanvasNodeState[]
/** Default managed Claude account for new Claude/chat nodes in this project. */
defaultAccountId?: string
/** Permission mode for new Claude TERMINAL (CLI) sessions in this project. SDK chat nodes are
* not covered — the chat driver still runs in `default`. Unset = use the global setting. */
defaultPermissionMode?: AgentPermissionMode
/**
* Per-project capability switch: agents may drive browser nodes THEY opened in this project.
* GIT-SHARED (rides .nodeterm/project.json) and therefore hostile input — the raw bit is read
* ONLY through `projectCapabilityFlagInFile` (@shared/project-capabilities, strict `=== true`,
* own-property), and it is NEVER a grant by itself: grants go through
* `projectCapabilityGrantedFor` (@shared/project-capability-consent), which also requires this
* machine's recorded 'kept' answer below.
*/
agentBrowserControl?: boolean
/** Per-project capability switch: agents may message other agent nodes in this project. Same
* rules as `agentBrowserControl` above — git-shared hostile input, strict `=== true` read,
* never a grant without this machine's recorded 'kept' (`projectCapabilityGrantedFor`). */
agentMessaging?: boolean
/** Per-project capability switch: agents may file a GitHub issue in THIS project's repository
* when they hit a nodeterm gap. Same rules as the two above — git-shared hostile input, strict
* `=== true` read, never a grant without this machine's recorded 'kept'
* (`projectCapabilityGrantedFor`). Unlike them, what it grants is PUBLICATION: the text leaves
* the machine, so the copy in `PROJECT_CAPABILITY_COPY` says so in as many words. */
agentIssueReporting?: boolean
/**
* MACHINE-LOCAL record of what this machine's user ANSWERED for each capability switch —
* 'kept' or 'declined', not a bare bit, because a declined switch whose hostile `true`
* re-arrives via git must be refused and re-noticed, never silently granted (PR #213 C1).
* Persisted on `IndexEntryV3.capabilityAck`, NEVER written into the shared project file
* (workspace-files.test.ts / capability-notice tests pin that the file bytes are unchanged).
*/
capabilityAck?: import('./project-capability-consent').CapabilityAckMap
/** Best dino-game score in this project — new dino nodes seed from it, so the record survives closing the node. */
dinoHighScore?: number
/** Kanban task board — shared via .nodeterm/project.json like nodes. */
kanban?: ProjectKanban
/** Bridge links between Claude nodes (optional; absent in pre-bridge files). */
bridges?: BridgeLink[]
/**
* Visual "spawned by" ropes (control-capable agent → node it opened via the `nodeterm` CLI,
* or browser popup → its opener). Display-only — never context links — but persisted so the
* lineage survives restarts; deletable like any selected edge.
*/
ropes?: BridgeLink[]
/** Camera navigation history — deliberate node landings, newest last. MACHINE-LOCAL: rides
* `IndexEntryV3.breadcrumbs`, never emitted into the shared project file (a repo must not carry
* one person's wandering camera history). */
breadcrumbs?: NavStop[]
/**
* Named geometry snapshots for this canvas - see @shared/canvas-layout for what a layout may
* carry and why it may carry nothing else.
*
* CONTENT, git-shared via `.nodeterm/project.json` like `kanban`: node geometry is already
* shared content in that file and a restore writes exactly those fields, so the snapshot belongs
* beside them. The camera precedent (`viewport`, `breadcrumbs`) deliberately does NOT reach
* here - those are camera facts, and nobody else's canvas moves when I pan.
*/
layouts?: CanvasLayout[]
/** This machine's camera per layout, keyed by layout id. MACHINE-LOCAL: rides
* `IndexEntryV3.layoutViewports`, never the shared file - same rule as `breadcrumbs`. */
layoutViewports?: LayoutViewports
/**
* Closed projects are hidden from the tab bar but kept on disk with all their nodes (and their
* tmux sessions left running) so they can be reopened from the start screen's "Recently closed"
* list. Absent/false = an open tab. A closed project never becomes `activeProjectId`.
*/
closed?: boolean
/** Set alongside `closed: true` — when this project was closed, for sorting "recently closed"
* history newest-first. Machine-local (see `IndexEntryV3.closedAt`) — never written into the
* shared project file, same rule as `closed` itself. Absent on a project closed before this
* field existed; such entries sort last. */
closedAt?: number
/** See `HandedOffTo`. Index-only; never written to the shared project.json. */
handedOffTo?: HandedOffTo
/**
* Sessions (terminal/agent/sticky/…) deleted from this project, most-recent-first, capped at
* 20. MACHINE-LOCAL, same rule as `closedAt`/`breadcrumbs` — see `IndexEntryV3.closedSessions`,
* never written into the shared project file (a delete's full node-state blob — title, cwd,
* position — would otherwise churn a committed, teammate-visible document on every one). Whose
* trash can holds what is a per-machine fact, not shared content. A fresh id per entry;
* recreating a node from one always mints a new node id/session, never reuses the original
* (see `recreateNodeFromSnapshot`).
*/
closedSessions?: ClosedSessionEntry[]
/**
* Set at load time when the project's .nodeterm/project.json could not be read
* (folder missing, server unreachable, corrupt file). Runtime-only — never persisted.
* Unavailable projects show a greyed tab and cannot be activated.
*/
unavailable?: boolean
/**
* This tab is a LIVE relay connection to another machine's project — not a workspace on
* THIS disk. Runtime-only, never persisted: set by `openRelayTab` (see relay-tab.ts) and
* excluded from both `toWorkspace()` and the on-disk index (see the `splitWorkspace` skip in
* core/workspace-files.ts). A relay tab is a connection bookmark, never a workspace on the
* peer's disk, so it must never land in this client's workspace.json.
*/
remote?: boolean
/**
* Relay tabs only: the host's SSH endpoint as DISPLAY strings (the tab's `SSH user@host` chip).
* A relay tab never carries `ssh` — it would make this machine dial the host's server with this
* machine's credentials (see renderer/session/relay-ssh.ts). Runtime-only like `remote`.
*/
relaySsh?: { user: string; host: string; remoteCwd: string }
}
/** The full workspace written to / read from disk. */
export interface Workspace {
version: 2
activeProjectId: string
projects: Project[]
}
/** Old single-canvas format (v1), kept only for migration on load. */
export interface WorkspaceV1 {
version: 1
viewport: Viewport
nodes: CanvasNodeState[]
}
export const DEFAULT_PROJECT_ID = 'project-1'
// No projects on a fresh start → the renderer shows the welcome / start screen.
export const EMPTY_WORKSPACE: Workspace = {
version: 2,
activeProjectId: '',
projects: []
}
// ---- Contract for the API exposed to the renderer via preload ----
/** Local core backend discovery, not a runtime health check or a promise about existing sessions. */
export interface TmuxStatus {
/** tmux discovery only; retained for older callers and install polling. */
available: boolean
/** Absent on older peers; null when discovery could not be read. */
persistence?: {
enabled: boolean
backend: 'tmux' | 'zellij' | 'session-host' | null
} | null
/**
* The optional Zellij backend (@shared/session-backend): whether a `zellij` binary was found and
* whether this machine's setting selects it for NEW local terminals. Absent on older peers and on
* Windows (no Zellij backend there). `selected && !available` means new terminals fall back to
* tmux — the Settings row says so rather than letting the choice look applied.
*/
zellij?: { available: boolean; selected: boolean; socketTooLong?: boolean }
/** One-shot install command for a terminal node; null = no known installer (text-only banner). */
installCommand: string | null
/** Button caption for installCommand (e.g. "Install Homebrew + tmux" when brew must come first). */
installLabel: string | null
/** `process.platform` of the core that owns the sessions/filesystem. `null` means the read
* failed; callers must not substitute the browser's platform for a server or relay core. */
platform: string | null
}
/**
* How close THIS MACHINE is to `kern.tty.ptmx_max`, the system-wide pty-device ceiling that took
* the whole app down in the 2026-08-11 field report (every spawn failing with a bare
* `posix_spawnp failed.`). See core/pty-pressure.ts for the bands.
*/
export type PtyPressureLevel = 'none' | 'elevated' | 'critical'
/** A pty-pressure reading, as broadcast on `IPC.ptyPressure`. `null` = could not be measured. */
export interface PtyPressure {
level: PtyPressureLevel
/** `/dev/ttys*` entries in existence right now. */
usage: number | null
/** `kern.tty.ptmx_max`. */
ceiling: number | null
}
/** Outcome of the banner's "Fix automatically…" button (macOS only) — see main/ptmx-limit.ts. */
export type PtyLimitFixResult =
| { ok: true; ceiling: number }
/** `canceled` = the user dismissed macOS's own admin-password dialog. Not an error to retry.
* `busy` = a password dialog from another window/reload is already up. Both are SILENT for the
* renderer: nothing failed, so neither may raise an error toast. */
| { ok: false; error: string; canceled?: boolean; busy?: boolean }
export interface PtyApi {
/** Starts a new PTY session; returns its sessionId and whether the session was freshly
* created (cold start) vs reattached to a still-running tmux session (warm). */
create(options: PtyCreateOptions): Promise<PtyCreateResult>
/** Sends user input to the PTY. */
write(sessionId: string, data: string): void
/** Updates the PTY when the terminal is resized. The pty runs at the SMALLEST subscriber's grid,
* so this is a REPORT, not a command — the effective size comes back over `onSize`.
* `cols`/`rows` null means "subscribed, but not viewing" (a parked terminal): the client leaves
* the size set entirely, so a parked small window can't shrink everyone else's terminal.
* `viewerId` (optional, trailing) scopes the size vote to one VIEW within the connection (the
* kanban card modal); absent ⇒ the PRIMARY view. */
resize(sessionId: string, cols: number | null, rows: number | null, viewerId?: string): void
/** Flow control: pause (false) or resume (true) reading the PTY when xterm is backed up.
* `viewerId` (optional, trailing) scopes the pause to one VIEW (a client's second xterm is
* edge-latched independently); absent ⇒ the PRIMARY view. */
setFlow(sessionId: string, resume: boolean, viewerId?: string): void
/** Detaches/terminates ONE view of the PTY (the underlying tmux session survives). `viewerId`
* (optional, trailing) names the view to detach — closing the kanban modal leaves the canvas
* node attached; absent ⇒ the PRIMARY view. */
kill(sessionId: string, viewerId?: string): void
/** Permanently ends the persistent session for a node (kills its tmux session) because the node
* is being DELETED. Co-viewers get `onClosed` and must not respawn it.
*
* `everySocket` (optional, trailing) widens a kill for a session we hold NOTHING for to every
* local tmux socket the name could be on. Opt-in for one caller — the session-memory panel's
* speculative kill of a row it swept off either socket. An ordinary node-× must not set it: it
* takes the same unheld branch after an app restart, and the legacy `nodeterm-rmt` holds sessions
* a pre-unification build on another machine SSHed in to spawn. */
destroy(persistKey: string, opts?: { everySocket?: boolean }): void
/** Ends a node's persistent session so the SAME node id respawns in a new cwd ("move into
* worktree"). Same tmux kill as `destroy`, opposite intent: the node stays on the canvas, so
* co-viewers get `onRecycled` (restart + re-attach), never the permanent closed state. */
recycle(persistKey: string): void
/** Suggest a terminal title from its recent output via the configured AI agent. `accountId` is
* the node's managed Claude account (trailing + optional: absent = system `~/.claude`), so the
* naming request runs under the same login the node itself does. */
generateName(persistKey: string, cwd: string, accountId?: string): Promise<GitResult>
/** Suggest a group title from its member terminals' recent output via the configured AI agent. */
generateGroupName(memberKeys: string[], cwd: string): Promise<GitResult>
/** Capture a terminal session's output as text. `full` grabs the entire scrollback. */
capture(persistKey: string, full?: boolean): Promise<string>
/**
* Seconds since this node's tmux session was created, measured on the machine that holds it, or
* `null` when that cannot be told (no session, no tmux, an unreadable host, a garbled answer).
*
* The late cold-start check behind `PtyCreateResult.freshUnverified`: `#{session_created}`
* survives a `new-session -A` attach, so a session created within seconds of our own attach is
* one we just made — i.e. the node was cold after all. `null` is never an age; the caller acts
* only on a small number.
*/
sessionAge(persistKey: string): Promise<number | null>
/**
* Has the host behind `sshRemote.controlPath` POSITIVELY listed this node's remote tmux session?
*
* The early-attach gate: a remote terminal may run over a ControlMaster whose connect-time setup
* has not finished only when its session already exists (`new-session -A` then merely attaches,
* and the remote tmux `-f` config and the `-e` hook/account env are read at session CREATION
* only). Absent AND unreadable both answer `false` — the node then waits for the full connect,
* because creating a session without that env silently costs it its agent-status badges.
*
* Desktop-only, like SSH projects; the Server Edition bridge answers `false` (never attach
* early), which is the pre-feature behavior.
*/
remoteSessionConfirmed(
persistKey: string,
sshRemote: { controlPath: string; conn: import('./ssh').SshConnection }
): Promise<boolean>
/** Read the persisted scrollback snapshot for a node (for cold-restart replay). '' if none. */
readScrollback(persistKey: string): Promise<string>
/** Send literal text into a session, by default followed by Enter (e.g. a slash command).
* `opts.enter: false` writes the text without submitting it (dictation's Insert). Returns
* false if unavailable; `pasted-not-submitted` means input was accepted but Enter was not
* confirmed written. Surface it without automatically resending. True is not an app receipt. */
sendText(persistKey: string, text: string, opts?: { enter?: boolean }): Promise<TextDeliveryResult>
/** Submit a prompt from the ⌘M chat view. For an agent whose screen can be read
* (`readsScreenDialogs`), refused BEFORE anything is written when the agent's own dialog owns the
* keyboard (`ChatPromptBlocked`) — such dialogs fire no hook. Otherwise the `sendText` contract. */
sendChatPrompt(persistKey: string, text: string, agentId: string): Promise<ChatPromptResult>
/** Type `text` + Enter ONLY into an empty composer of an agent whose composer can be read
* (issue #1144 — the app's own link notes). Refused, with the reason, before anything is written
* when the composer holds a draft, a dialog owns the keyboard, or emptiness cannot be proven. */
sendToEmptyPrompt(persistKey: string, text: string, agentId: string): Promise<EmptyPromptResult>
/** One read of an agent's screen for the ⌘M chat view's poll: who owns the keyboard, and the
* prompt the agent suggests next (claude: `readClaudeSuggestion`). An agent with no measured
* reader, or a pane that could not be read, answers `{ screen: { kind: 'unknown' }, suggestion: null }`. */
readChatScreen(persistKey: string, agentId: string): Promise<ChatScreenRead>
/** Esc from the ⌘M chat view: interrupt a running turn, for an agent whose interrupt is measured
* (claude). Refused before writing when the agent's own dialog owns the keyboard. `sentText` (the
* chat view's last send) lets core take it back out of the agent's input box when the Esc landed
* before the reply started; it comes back as `restored`. Never rejects on the desktop. */
interruptChat(persistKey: string, agentId: string, sentText?: string): Promise<ChatInterruptResult>
/** ⌘M chat → terminal: type the chat draft into the agent's EMPTY input box, unsent. Never
* rejects on the desktop. */
putChatDraft(persistKey: string, agentId: string, text: string): Promise<ChatDraftPutResult>
/** Terminal → ⌘M chat: take a draft that can be read back exactly out of the agent's input box
* (it is cleared there). Never rejects on the desktop. */
takeChatDraft(persistKey: string, agentId: string): Promise<ChatDraftTakeResult>
/** Is tmux available on this host (else the silent plain-shell fallback), plus a suggested
* install command for the "tmux not found" banner. */
tmuxStatus(): Promise<TmuxStatus>
/** The command currently in the foreground of a node's tmux pane (e.g. 'claude', 'zsh'), by
* node persistKey. null when it is unknown — no session, no tmux, or the query failed — which
* callers must read as "not observed", never as evidence of a particular command. */
paneCommand(persistKey: string, opts?: { resolveUnmounted?: boolean }): Promise<string | null>
/** The live working directory of a node's pane (`#{pane_current_path}`). null when unknown —
* no session, no tmux, the session-host backend, a failed query, or a surface that does not
* serve it (relay tabs) — and never a rejection. Used as the second cwd for file links. */
paneCwd(persistKey: string): Promise<string | null>
/** Type raw keys into a node's tmux pane by node id; no mounted terminal needed. Never rejects. */
sendPaneKeys(nodeId: string, data: string): Promise<PaneKeysResult>
/**
* Desktop only (#925). Spawn-or-attach a node's session with no viewer and deliver `command`
* through the echo-verified writer, then release the synthetic client (the tmux session keeps
* running). Refused as `not-persistent` without tmux or the session-host. The Server Edition
* starts nodes through its own factory, so the browser build rejects with E_UNSUPPORTED.
*/
launchHeadless(req: {
ptyOptions: PtyCreateOptions
command: string
}): Promise<import('./headless-launch').HeadlessLaunchResult>
/** Kernel truth about a node's pane — its root pid, tty, tmux pane id and the full argv of its
* foreground process group — so a caller can ask WHO owns the pane rather than what tmux calls
* it. `null` is "could not read", never evidence that the pane is free (see `isAgentPane`'s
* three-valued verdict, which is what consumers should decide on). */
paneOwner(persistKey: string, opts?: { resolveUnmounted?: boolean }): Promise<PaneOwner | null>
/**
* Execute a semantic agent launch in a node's live LOCAL Windows session-host pane: the core
* encodes it for the pane's own shell (pwsh / Windows PowerShell / cmd) and the host types it
* exactly once. Every other session (tmux, SSH, Zellij, plain shell, POSIX core, Git Bash/WSL)
* answers `unsupported-shell`, and the caller keeps its legacy typed line. Optional: surfaces
* that cannot serve it (relay tabs, test fakes) simply omit it — the caller's answer is the same.
*/
executeLaunch?(persistKey: string, request: LaunchIntentRequest): Promise<LaunchIntentExecutionResult>
/** Terminate the foreground process group in a node's pane. Returns false when the pane/process
* cannot be safely identified; it never kills the pane's login shell. When `expectedAgentId` is
* given, the kill happens only if that harness actually owns the foreground group (argv-verified)
* — so a stale menu can never SIGTERM vim or a build the user started in the pane. On Windows
* (session host / direct ConPTY) the identity gate is mandatory and the kill is the proven agent's
* process tree, never the shell; `'unsupported'` = the running session host predates that verb. */
terminateForeground(persistKey: string, expectedAgentId?: string): Promise<boolean | 'unsupported'>
/** The agent session's display name (`/rename` name, else auto name) read from the agent's own
* session store, resolved strictly by sessionId; null if unknown. Keeps a node title in sync with
* the `/resume` name (e.g. after resume) without cross-contaminating same-folder sessions.
* `accountId` scopes the lookup to a managed Claude account's transcript root (default `~/.claude`).
* `agentId` picks the reader — grok's name lives in its session metadata, not a claude transcript;
* omitted (every pre-grok caller) means the claude transcript reader. */
readSessionName(sessionId: string, accountId?: string, agentId?: string): Promise<string | null>
/** Listens for PTY output. Returns an unsubscribe function. */
onData(sessionId: string, listener: (data: string) => void): () => void
/** Fires when the PTY process exits. Returns an unsubscribe function. */
onExit(sessionId: string, listener: (exitCode: number) => void): () => void
/** The authoritative size of a co-attached session: min(cols) × min(rows) over all subscribers
* ("smallest subscriber wins"). Broadcast whenever the subscriber set or any reported size
* changes; the terminal renders at this size instead of its own fit. Returns an unsubscribe. */
onSize(sessionId: string, listener: (size: { cols: number; rows: number }) => void): () => void
/** Another client permanently destroyed this node while we were co-viewing it: the session is
* gone for good (do not respawn — show a "closed by <peer>" state). `by` is the destroying
* client's ClientId, or null when the destroy was not attributed to a client (a local desktop
* destroy); resolve it to a name via the presence store. Returns an unsubscribe. */
onClosed(sessionId: string, listener: (info: { by: ClientId | null }) => void): () => void
/** Another client RECYCLED this node (moved it into a worktree): this session id is dead. With
* `ready:true` a replacement is already live under the same node id — restart the terminal (the
* re-create co-attaches to it) instead of showing the closed state: nothing was deleted. With
* `ready:false` no replacement ever came (the recycler died mid-move): do NOT respawn — the
* terminal ends and offers a manual reopen. Returns an unsubscribe. */
onRecycled(sessionId: string, listener: (info: RecycledInfo) => void): () => void
/** We fell too far behind and the server dropped our queued output; this is the session's
* CURRENT screen captured from tmux. Reset the emulator and repaint from it.
* CONTRACT: the payload is guaranteed NON-EMPTY (a failed capture is retried, never sent). The
* listener must STILL ignore an empty/falsy payload — never reset on one: a wrongly cleared
* screen is unrecoverable, a skipped repaint is not. Returns an unsubscribe. */
onResync(sessionId: string, listener: (screen: string) => void): () => void
}
export type WorkspaceMigrationKind = 'v2' | 'exec'
export interface WorkspaceSaveOptions {
localOnly?: boolean
}
export interface WorkspaceApi {
load(): Promise<Workspace>
/** `localOnly`: return once this machine's disk holds the save, WITHOUT the SSH mirror
* round trips (the mirror is owed and rides the next ordinary save). For a write-ahead barrier
* that must be durable here but must not wait on a remote host — see WorkspaceStore.save. */
save(workspace: Workspace, opts?: WorkspaceSaveOptions): Promise<void>
/**
* Ask the core to claim one held launch (node id + command) before any viewer types it
* (issue #1173): `claimed` = this viewer delivers it, `elsewhere` = another viewer of the same
* project already claimed it, type nothing. A manual Run now is never refused. Optional: a
* client without it (an older core, a test double) keeps the per-viewer barrier alone.
*/
claimLaunch?(nodeId: string, command: string, manual: boolean): Promise<'claimed' | 'elsewhere'>
/** Reads <folder>/.nodeterm/project.json and returns the assembled Project (cwd resolved), or null. */
probeFolder(folder: string): Promise<Project | null>
/** Whether <folder>/.nodeterm/project.json is `present`, definitely `absent`, or `unreadable`
* (any non-ENOENT error). Never guesses absence from a failed read — see issue #385. */
projectFileState(folder: string): Promise<'present' | 'absent' | 'unreadable'>
/** "Store in app data", second half (issue #1145): once the move's save has landed, carry the
* folder's settings into app data and remove its `.nodeterm` files (git-tracked ones only with
* `removeTracked`). See `WorkspaceStore.releaseFolderFiles`. */
releaseFolderFiles(projectId: string, removeTracked: boolean): Promise<import('./project-storage').ReleaseFolderFilesResult>
/** "Store in folder", first half (issue #1145): refuse a folder that already holds a canvas or
* settings, else carry this project's settings in. See `WorkspaceStore.prepareFolderStorage`. */
prepareFolderStorage(projectId: string): Promise<import('./project-storage').PrepareFolderStorageResult>
/** Where the store has this project's canvas right now (issue #1145): asked after a move's save,
* which can land while the folder write in it did not. See `WorkspaceStore.projectStorage`. */
projectStorage(projectId: string): Promise<import('./project-storage').ProjectStorageKind>
/** Fired once after an on-disk migration: `v2` = a v2→v3 migration wrote .nodeterm/ dirs into the
* project folders; `exec` = the custom shell / advanced ssh args of already-open projects moved
* out of the shared project file into this machine's own workspace index (@shared/node-exec). */
onMigrated(cb: (kind: WorkspaceMigrationKind) => void): () => void
/** Fired once per run when a load found the workspace index unreadable and preserved it as
* `workspace.json.corrupt-<ts>` (the payload). The projects themselves are untouched — their
* canvases live in each <cwd>/.nodeterm/project.json — so the note tells the user to re-add them. */
onCorruptRecovered(cb: (backupFile: string) => void): () => void
/** Fired when a project file changed on disk outside the app (git pull, sync, teammate). */
onExternalChange(cb: (project: Project) => void): () => void
/** Fired when THIS core wrote the project itself (Server Edition headless canvas control: an agent
* opened, renamed, moved, closed…). Not an outside edit — the renderer merges it, never asks. */
onServerChange(cb: (project: Project) => void): () => void
/**
* Main asks for pending canvas edits to be written NOW — before a quit or a restart-to-update
* (`src/main/renderer-flush.ts`). The callback's settling is the answer; main waits at most ~1 s
* either way. Desktop only: the Server Edition has no main process to quit, so its bridge never
* fires it. Returns unsubscribe.
*/
onFlushRequest(cb: () => Promise<unknown> | void): () => void
}
export interface ProjectSettingsApi {
/** `{shared, local, conflict?}` for a known project id, or null for an unknown one. */
read(projectId: string): Promise<import('./project-settings').ProjectSettingsSnapshot | null>
/** Whole-document write of the git-shared `.nodeterm/settings.json`. See
* `WorkspaceStore.writeProjectSettings` for the false-vs-true contract. */
writeShared(projectId: string, doc: import('./project-settings').ProjectSettingsDoc): Promise<boolean>
/** This machine's own overlay; `local: undefined` clears it. */
updateLocal(
projectId: string,
local: import('./project-settings').ProjectLocalSettings | undefined
): Promise<boolean>
/** Resolved settings + per-family trust verdict for one project — `null` for an unknown id. The
* renderer cache (`renderer/state/projectLaunchInfo.ts`) warms this on activate and never awaits
* it inline; a caller wanting the raw handshake calls this directly instead. */
launchInfo(projectId: string): Promise<import('./project-settings').ProjectLaunchInfo | null>
/** main → renderer: a family's trust verdict changed for `projectId` (a consent dialog answered,
* an approval revoked). Nobody broadcasts this yet — Task 2 records approvals and emits it. */
onTrustChanged(cb: (p: { projectId: string }) => void): () => void
}
export interface ProjectSetupApi {
/** Launch a project's setup/archive script behind the trust gate (`project-setup-service.ts`).
* `worktreePath`, when given, is the ONLY path-shaped hint this call carries — main derives
* `rootPath`/`ssh` from its own workspace index by `projectId` and independently validates
* `worktreePath` against that project's actual git worktrees; nothing path-shaped sent here is
* trusted as-is (Task 1 review finding). */
run(
projectId: string,
kind: import('./project-settings').ProjectSetupKind,
worktreePath?: string
): Promise<import('./project-settings').ProjectSetupRunResult>
/** Aborts a live run, or one still waiting at its consent dialog. `false` = nothing by that
* runKey exists (already finished, or never did). */
cancel(runKey: string): Promise<boolean>
/** Renderer's answer to a `onConsentRequest` prompt. A stale/unknown requestId is a silent no-op. */
consent(requestId: string, answer: import('./project-settings').ProjectSetupConsentAnswer): Promise<void>
/**
* Ask for this project's `agents`/`shell` family to be trusted, prompting the human if it is not
* yet — the call a launcher makes before consuming a shared-sourced `launchCmd`/`env`/`shell`.
* `true` only when the family is trusted at that project's location (nothing shared to gate, an
* existing grant, or a fresh approval); skip, expiry, an unknown project and a refused (relay
* guest) call are all `false`. Concurrent asks for one location share ONE dialog. On approval,
* `projectSettings.onTrustChanged` fires for the project, so a cached launch-info verdict is
* re-read rather than trusted from before the answer.
*/
requestTrust(projectId: string, family: 'agents' | 'shell'): Promise<boolean>
/** main → renderer: raise the trust dialog before a shared-sourced script runs, or before a
* shared-sourced launch setting is consumed — tagged by family (`ProjectConsentRequest`). */
onConsentRequest(cb: (req: import('./project-settings').ProjectConsentRequest) => void): () => void
/** main → renderer: close a prompt nobody answered before the renderer did. */
onConsentDismiss(cb: (p: { requestId: string }) => void): () => void
/** Per-project run progress (`ProjectSetupEvent`), mirroring `boardLog.onChanged`'s ref-counted
* subscribe/unsubscribe shape. */
onEvent(projectId: string, cb: (ev: import('./project-settings').ProjectSetupEvent) => void): () => void
}
export interface WorktreeApi {
/**
* Symlink a project's configured `sharedPaths` (git-ignored dirs like `node_modules`) from its
* repo root into a freshly-created git worktree, so a setup `npm install` there sees the links.
*
* The renderer passes ONLY `(projectId, worktreePath)` — never the path list: main reads the list
* itself out of the project's settings by `projectId`, derives the repo root from its own
* workspace index, and validates `worktreePath` is that project's rootPath or one of its actual
* git worktrees. An unknown project, an unvalidated path, or an SSH project (local-only this PR)
* all resolve `[]`. Never rejects — a per-entry `SharedPathResult[]` reports what happened.
*/
materializeShared(
projectId: string,
worktreePath: string
): Promise<import('./worktree').SharedPathResult[]>
}
export interface DialogApi {
/** Opens a native folder picker; returns the chosen path or null if cancelled. */
selectFolder(): Promise<string | null>
/** Opens a native file picker; returns the chosen path or null if cancelled. */
selectFile(): Promise<string | null>
}
export interface ClipboardWriteOptions {
/**
* Never raise a failure toast. For writes the user did not explicitly ask for as a copy — today
* only copy-on-select (issue #759), which writes on every completed drag, where a toast per drag
* would be unusable. The write still tries every route; only the banner is withheld. The desktop
* preload's write is fire-and-forget IPC with no failure surface at all, so it ignores this.
*/
quiet?: boolean
}
export interface ClipboardApi {
writeText(text: string, opts?: ClipboardWriteOptions): void
/** Copy local files so Finder and other file-aware macOS apps can paste them. */
writeFiles(paths: string[]): Promise<boolean>
}
export interface ShellApi {
/** Reveal a path in the OS file manager (Finder). */
reveal(path: string): void
/** Open a path with the OS default application. */
openPath(path: string): void
/** Open an http(s) URL in the OS default browser. */
openExternal(url: string): void
/** Open a file dialog for a project-icon image; main re-encodes the pick to a bounded PNG data
* URL (or an error), or returns null when cancelled. See `pickProjectIcon` (main). */
pickProjectIcon(): Promise<ProjectIconPickResult>
}
export interface DirEntry {
name: string
dir: boolean
/** True when the entry is matched by .gitignore (shown dimmed). */
ignored?: boolean
}
export interface FsApi {
/** List a directory (folders first, then files; alphabetical). */
list(dirPath: string): Promise<DirEntry[]>
/** Read a file's text contents (empty string on error). */
read(filePath: string): Promise<string>
/** Read a file as base64 (for images and other binary previews; '' on error). */
readBinary(filePath: string): Promise<string>
/** Write text to a file; resolves true on success. */
write(filePath: string, content: string): Promise<boolean>
/** Create a directory (recursive). Resolves true on success. */
mkdir(dirPath: string): Promise<boolean>
/** True when the path exists (file or directory). */
exists(path: string): Promise<boolean>
}
export interface FilesApi {
/** Fuzzy-open file index for a project root: root-relative `/`-paths ([] on failure). */
quickOpen(cwd: string): Promise<string[]>
/**
* Mint a one-shot, short-TTL ticket for downloading `path` over HTTP, and resolve the URL to
* navigate to. Resolves **null** where the shell has no HTTP surface to redeem it on (Electron
* desktop, relay) — callers treat null as "downloading is not offered here" and hide the
* affordance rather than erroring.
*/
downloadTicket(path: string): Promise<DownloadTicket | null>
/**
* Persist raw bytes (base64) as a file on the machine the terminals run on, and resolve its
* ABSOLUTE path — what a clipboard paste of an image has instead of a path, and what a browser
* client's dropped file has instead of a usable one. Resolves null when it could not be written
* (too large, unwritable); callers drop that file the way a failed drop does.
*/
saveUpload(name: string, dataBase64: string): Promise<string | null>
/**
* Persist raw bytes (base64) as a CANVAS image and resolve its ABSOLUTE path. Unlike
* `saveUpload` the file is durable: a canvas image node is persisted in `project.json`, so its
* file cannot live in a staging area that is swept after a week. The directory is derived from
* `projectId` on the receiving side — the caller never names a path — and is the project's own
* git-shared `.nodeterm/images/` when it has a local cwd, else a durable app-local folder.
* Resolves null when it could not be written; callers drop that file like a failed drop.
*/
saveCanvasImage(projectId: string, name: string, dataBase64: string): Promise<string | null>
/**
* Save a whiteboard node's scene (Excalidraw JSON) and the picture it shows at rest. The core
* derives the file from (projectId, nodeId) — beside project.json, or its own data dir. Resolves
* `{ok: true, path, rev}`, a conflict when the board on disk is no longer `expectedRev` (nothing
* written), or null when it could not be written. A core on an older build answers the bare path
* string and ignores `expectedRev`. See core/whiteboards.ts.
*/
saveWhiteboard(
projectId: string,
nodeId: string,
scene: string,
thumbnailBase64?: string,
expectedRev?: string | null
): Promise<WhiteboardSaveResult | string | null>
/** Read a whiteboard back; `sourceId` is the board a copied node falls back to until it saves.
* `withScene: false` reads only the picture and revision (a board at rest). */
readWhiteboard(projectId: string, nodeId: string, sourceId?: string, withScene?: boolean): Promise<WhiteboardFile | null>
/**
* Store a custom sound for an agent alert (issue #289). The core validates kind, extension,
* size and magic bytes, then writes a FIXED per-kind file under its own data dir — the picked
* file's path is never sent, only its bytes and base name. Resolves `{ ok: false, error }` for a
* refusal; never rejects on a bad file.
*/
saveAlertSound(kind: AlertSoundKind, name: string, dataBase64: string): Promise<AlertSoundSaveResult>
/** The stored custom sound for `kind` as base64, or null when there is none (or it is unreadable). */
readAlertSound(kind: AlertSoundKind): Promise<string | null>
/** Delete the custom sound for `kind` (Reset to default). */
clearAlertSound(kind: AlertSoundKind): Promise<boolean>
}
export interface MediaApi {
/** Allow an absolute local path to be served, and return its nt-media:// URL. */
allow(absPath: string): Promise<string>
/**
* Allow a file that lives on an SSH project's HOST: main pulls it into a local cache over the
* project's ControlMaster (skipped when the cached copy's size still matches the remote), then
* allowlists the cached copy. Resolves the playable nt-media:// URL, or a reason it couldn't
* (not connected, transfer failed). Desktop only — the browser bridge rejects it.
*/
allowSsh(projectId: string, remotePath: string): Promise<{ ok: true; url: string } | { ok: false; error: string }>
/** Persist raw HTML to <userData>/agent-web/<id>.html, allowlist it, return its absolute path. */
writeHtml(html: string): Promise<string>
}
export interface BrowserApi {
/** Map a browser node's <webview> guest to its node id (for new-window capture). */
register(webContentsId: number, nodeId: string): void
unregister(webContentsId: number): void
/** Fires when a browser guest requested a new window; the renderer opens another browser node. */
onBrowserNewWindow(listener: (e: { url: string; sourceNodeId: string }) => void): () => void
/** Push: the current set of browser nodes an agent is driving (chip / rope / kill row). `stopped`
* ids drop from the chip immediately, skipping the anti-flicker linger. */
onLeaseChanged(listener: (push: BrowserLeasePush) => void): () => void
/** Stop agent control of ONE browser node — the chip button and the node context menu. Detaches
* the debugger + drops the lease in main; a later drive from that owner is refused by name. */
stop(nodeId: string): void
/** Stop agent control of EVERY driven node — the Settings kill row's Stop-all. */
stopAll(): void
/** Stop agent control of every node in a project — the project's browser-control switch going off. */
stopProject(projectId: string): void
}
/** A user-defined agent (BYO CLI). With no `baseAgent` it is in no capability list, so it gets
* only spawn + terminal-title + process status (no hooks/branch/loop/bridge). With a `baseAgent`
* it inherits that builtin harness's capabilities (hooks, resume, permission modes, canvas
* control) and prompt convention — the use case being a harness-compatible CLI pointed at your
* own inference proxy, where you want to KEEP nodeterm's integration while redirecting the calls. */
export interface CustomAgent {
/** Stable id of the form 'custom:<uuid>'. Used as the node's agentId. */
id: string
label: string
/** Base launch command. Blank when `baseAgent` is set means "use the base harness's command"
* (so a claude-compatible proxy needs zero launch config). */
launchCmd: string
/** Prompt convention. Optional: inherited from `baseAgent` when set, else defaults to 'argv'. */
promptInjectionMode?: PromptInjectionMode
/** Optional builtin harness to inherit capabilities + prompt convention from. */
baseAgent?: BuiltinAgentId
/** Env vars injected at spawn, merged LAST so they win over hook/account env (required for the
* proxy case — your ANTHROPIC_AUTH_TOKEN must beat any account env). Values support
* `${env:VAR}` / `${env:VAR:fallback}` expansion at spawn time against the live OS env. */
env?: Record<string, string>
/** Extra argv inserted after `launchCmd`, before the prompt/flags. Free-text, shell-split.
* Supports `${env:…}` expansion. Blank = none. */
args?: string
/** Node color. Falls back to `baseAgent`'s color (or the default grey). */
color?: string
}
/**
* A managed Claude account. Its credentials/config live in a private config dir
* ({userData}/claude-accounts/<id>, or `~/.nodeterm/claude-accounts/<id>` on `host` for
* remote accounts) injected as CLAUDE_CONFIG_DIR at spawn. The claude CLI owns login,
* credential storage, and token refresh inside that dir — we never write credentials.
*/
export interface ClaudeAccount {
id: string
/** Display label; defaults to the captured email. */
label: string
email?: string
/** Set only for remote (SSH) accounts: the ssh host this account's config dir lives on. */
host?: string
/** True until `claude /login` completes in the account dir and the email is captured. */
pending?: boolean
/** Optional default node color for nodes opened under this account (Settings → Accounts);
* unset = the agent's own brand color. Read through `accountNodeColor`, which re-validates it
* as a string — this file is hand-editable and nothing checks it field-by-field on load. */
color?: string
/**
* LINKED account: an ABSOLUTE local path to a pre-existing Claude config dir the user already
* owns (e.g. `~/.claude-2` driven by their own `CLAUDE_CONFIG_DIR` shell setup). Set only by
* `claudeAccounts.link`; never combined with `host`. A linked account has no managed dir under
* `{userData}/claude-accounts/` — `claudeConfigDirFor` resolves it to this path — and REMOVING
* it only forgets the record: the directory is the user's and is never deleted. Hand-editable
* (settings.json), so it is re-validated at every point of use (absolute, normalized).
*/
configDir?: string
/**
* Share the machine's system skills (`~/.claude/skills`) with this account (issue #643).
* OFF/absent = the isolation Claude Code's own `join(CLAUDE_CONFIG_DIR, 'skills')` gives, which
* is the default and often the point. ON = each system skill is LINKED into the account's own
* `skills/` individually — the account's directory stays real, nodeterm's own skills keep their
* names, and turning it off removes only the links (`core/claude-skill-share.ts`).
* Reconciled at launch and whenever the switch is flipped; LOCAL accounts only — a remote (SSH)
* account's skills live on its host and are out of scope for v1.
*/
shareSystemSkills?: boolean
createdAt: number
}
/**
* Which Claude account a RUNNING session was observed to use — derived by the hook server from
* the `transcript_path` its hooks report (`<configDir>/projects/<slug>/<session>.jsonl`), never
* from anything the node was created with. A LABEL, exactly like `NormalizedAgentEvent.verified`:
* it tells the UI which identity a pane is on (a hand-launched `claude` in a plain terminal, an
* account switched by the user's own shell), it never grants anything.
* - `accountId === null` ⇒ the system default (`<home>/.claude`).
* - `accountId` set + `known` ⇒ a managed or linked `ClaudeAccount` from settings.
* - `known === false` ⇒ a config dir nodeterm has no record of (`accountId` is null); the UI
* labels it by its path and offers to link it. No filesystem read is ever made for such a dir.
*/
export interface ObservedClaudeAccount {
/** The config dir as the hook reported it (normalized string; may be a REMOTE path for SSH nodes). */
configDir: string
accountId: string | null
known: boolean
/**
* The observation came from a session whose FILESYSTEM IS ON ANOTHER MACHINE (an SSH-project
* pane), so every LOCAL affordance — offering the dir for linking, matching it against a local
* account's `configDir` — must refuse it. `~/.claude-2` on a host and `~/.claude-2` here are
* different directories that spell the same string, and the same username on both machines is
* the common case, not the exotic one.
*
* It is NOT set by the classifier: `classifyClaudeConfigDir` is deliberately host-agnostic (its
* managed-remote and basename-`.claude` rules exist precisely to name a REMOTE dir) and core
* holds only the payload, which says nothing about which machine posted it. The RENDERER is the
* only layer that knows a node's project and `data.ssh`, so the flag is attached there, once, at
* the point the label enters the store.
*
* Optional and trailing: an observation without it is a local one, which is what every
* observation was before the field existed.
*/
remote?: boolean
}
export interface SpeechSettings {
engine: 'whisper' | 'cloud'
/** WhisperModelInfo id — meaningful while engine === 'whisper'. */
model: string
/** BCP-47-ish hint or 'auto'. */
language: string
/** Press-to-talk / hold-to-talk shortcut, canonical form e.g. "Cmd+Alt+D" (keyed = toggle) or
* "Cmd+Alt" (v3, modifier-only = hold-to-talk — the new DEFAULT); see `shared/shortcut.ts`
* (`isHoldChord` derives the mode from the string, not a separate setting). "Cmd" is
* platform-abstracted: metaKey on mac, ctrlKey elsewhere. Drives the Canvas listener, the
* Dock mic tooltip, and the ShortcutsPanel row. */
shortcut: string
}
/** xterm cursor shapes, mirrored here so `Settings` doesn't depend on the xterm typings (which
* are renderer-only — `src/shared` is imported by main and the server shell too). */
export type TerminalCursorStyle = 'block' | 'bar' | 'underline'
export type TerminalCursorInactiveStyle = TerminalCursorStyle | 'outline' | 'none'
/** The primary modifiers of a forwarded desktop ⌘/Ctrl+0 (issue #915): the renderer applies the
* per-platform terminal-font-reset predicate to them. Optional on the listener because the Server
* Edition stub never fires and an absent value must read as "not a font reset". */
export interface ZoomActualSizeModifiers {
meta: boolean
control: boolean
}
/** `settings.runInBackgroundOnClose` — see the field's doc. */
export type BackgroundOnCloseSetting = 'auto' | 'on' | 'off'
/** User-configurable application settings (settings.json). */
export interface Settings {
fontSize: number
fontFamily: string
/** Characters that end a word during xterm double-click selection. */
terminalWordSeparator: string
cursorBlink: boolean
/** Appearance of the APP chrome (tab bar, panels, node headers, menus). `auto` (the default)
* takes it from the terminal colour theme, so picking a light terminal theme doesn't leave a
* black window framing it; `dark`/`light` pin it. `liquid-glass` follows the terminal theme like
* `auto` AND turns the Liquid Glass appearance on: every canvas node and the app chrome go
* translucent + blurred over the wallpaper, and terminal windows drop their per-node accent
* colour; tint opacities keep the primary text at WCAG 4.5:1 over any backdrop
* (renderer/lib/glassContrast.ts). See renderer/lib/appTheme.ts. */
appTheme: 'auto' | 'dark' | 'light' | 'liquid-glass'
/** Scale factor for the whole application UI (1 = 100%; issue #299, 4K readability). Applied as
* PAGE ZOOM (`webFrame.setZoomFactor`) on desktop, so menus, node headers, dialogs — and
* terminal glyphs — all scale together: the terminal font-size setting stays in CSS px, so its
* effective size is fontSize × uiScale (the Settings row says so). Hand-editable; every reader
* resolves it through `resolveUiScale` (shared/ui-scale.ts), which clamps to [0.5, 2] and maps
* garbage to 1. Server Edition: intentionally inert — the browser owns page zoom (Cmd/Ctrl+±). */
uiScale: number
/** Reflect the active session in the NATIVE window title ("<node> — <project> — node-terminal"),
* so window-title-based time trackers (ActivityWatch et al.) can tell sessions apart — the same
* thing iTerm2 / Windows Terminal do per tab (issue #414). Opt-in and OFF by default: the title
* is OS-visible surface area (window switchers, screen sharing), so an update must not start
* broadcasting session names for users who never asked. Renderer-only (`document.title` —
* Electron mirrors page-title changes onto the BrowserWindow, and the Server Edition gets the
* browser tab title through the identical write), so there is no bridge member to stub. */
windowTitleActiveSession: boolean
/** Terminal colour scheme — an id from `renderer/terminal/themes.ts`. Resolution is tolerant
* (settings.json is hand-editable): an unknown id falls back to the default theme, whose
* colours reproduce the pre-feature hardcoded `#1e1e1e`/`#e6e6e6` exactly. */
terminalTheme: string
/** Desktop wallpaper behind the canvas (Liquid Glass appearance). Opt-in; `none` draws the
* canvas exactly as before. Hand-editable: read through `normalizeWallpaper` (shared/wallpaper). */
desktopWallpaper: import('./wallpaper').DesktopWallpaper
/** The most recent imported wallpaper image's cache path, kept after switching to a preset so the
* "Your image" tile stays and the cache prune keeps its file (`recentWallpaperImage`). */
recentWallpaperImage: string | null
/** Weight for normal text. xterm's own default is `normal` (400). */
fontWeight: number
/** Weight for BOLD text. xterm's own default is `bold` (700). Lowering it is how you keep bold
* legible in a thin font that renders 700 as a smear. */
fontWeightBold: number
/** Render bold text in the palette's BRIGHT colours (xterm's default, and the historical
* terminal convention). Off keeps bold purely a weight, so colour still means what the program
* said it meant. */
drawBoldTextInBrightColors: boolean
/** Minimum foreground/background contrast ratio, 1–21. 1 (xterm's default) disables the
* adjustment entirely; 4.5 is WCAG AA, 7 is AAA, 21 forces black or white. Costs per-cell work
* in the renderer, so it stays off unless asked for. */
terminalMinContrast: number
/** Cursor shape. */
cursorStyle: TerminalCursorStyle
/** Cursor shape while the terminal does NOT have focus. `outline` (xterm's own default) is what
* tells you at a glance which of a canvas full of terminals is taking your keystrokes. */
cursorInactiveStyle: TerminalCursorInactiveStyle
/** Line height as a multiple of the font size (1 = xterm's default, i.e. no extra leading). */
terminalLineHeight: number
/** Extra horizontal space between cells, in CSS pixels (0 = xterm's default). */
terminalLetterSpacing: number
/** Empty string = use the system default shell. */
defaultShell: string
gridSize: number
/** Drag-time snap: while ON, dragging a node rounds its position to the grid. A live editor in
* BehaviorSection; the canvas reads it for the React Flow `snapToGrid` prop. Distinct from
* `autoAlignGrid` (a one-shot arrange-all), which is a mode, not a drag constraint. */
snapToGrid: boolean
/** Snap-to-grid MODE (like a desktop "Auto arrange"): while ON, every node is snapped to the
* grid at the moment the mode is turned on (the existing one-shot `alignToGrid` run over all
* node ids). Toggled from the native View menu (with a checkmark) and Settings → Behavior.
* Distinct from `snapToGrid` (drag-time snap) — turning this on arranges once; it does not
* constrain future drags. v1: arrange-all-on-enable only. */
autoAlignGrid: boolean
/** Height of the top project tab bar in CSS px (Settings → Appearance). Hand-editable; every
* reader — the renderer's `--tabbar-h` and main's traffic-light `y` — goes through
* `resolveTabBarHeight` (`@shared/window-chrome-metrics`), which clamps to 28–64 and answers
* the default for anything that is not a finite number. Machine-local: it is one person's
* chrome, not a canvas fact. */
tabBarHeight: number
/** How solid sticky notes / group frames are behind their colour tint, 0–100 (Settings →
* Appearance, issue #1113). 0 = see-through, the original look. Hand-editable; read through
* `resolveCanvasBacking` (@shared/canvas-backing). Machine-local. */
stickyNoteBacking: number
groupFrameBacking: number
/** Font of the rendered-Markdown reading views — the ⌘M output and chat views and the editor's
* Markdown preview (Settings → Appearance). A CSS font stack. Hand-editable; read through
* `resolveMarkdownFontFamily` (@shared/markdown-font). Code inside Markdown follows the
* terminal `fontFamily` instead. Machine-local, like the terminal font. */
markdownFontFamily: string
/** Body size (CSS px) of the same views; headings scale from it, code is 0.92 of it. Read
* through `resolveMarkdownFontSize`, which clamps to 8–28 and answers 13 for garbage. */
markdownFontSize: number
/** Default size (px) for NEW terminal/agent nodes on the canvas. Existing nodes keep
* whatever size they were saved with; other node kinds keep their own defaults. */
defaultNodeWidth: number
defaultNodeHeight: number
/** Default size (px) for NEW nodes of every other kind the add menus create, keyed by kind; a
* kind with no entry opens at its built-in size. Read through `defaultNodeSize` (renderer) /
* `resolveDefaultNodeSize` (@shared/default-node-size), which clamp hand edits. Machine-local. */
defaultNodeSizes: Partial<Record<SizableNodeKind, NodeSize>>
/** Sessions sidebar: the DEFAULT for a project row the user never toggled — on (historical)
* keeps the active project expanded and collapses the others, off leaves everything expanded.
* Explicit toggles live in `sidebarCollapsedItems` and always win. */
sidebarAutoCollapse: boolean
/** Persisted disclosure choices for the sessions tree, keyed `project:<id>` and
* `project:<id>:group:<groupId>` (true = collapsed). Pruned on every write against the live
* tree, so a deleted frame or project cannot grow settings.json forever. */
sidebarCollapsedItems: Record<string, boolean>
/** Sessions sidebar top-level grouping. 'project' (the default, the historical behavior) groups
* sessions under their project; 'status' flattens across projects and regroups by live agent
* status so sessions needing attention float to the top. Remote/relay sessions have no live
* status in the sidebar and show as idle in either mode. */
sidebarGrouping: 'project' | 'status'
/** Fallback view for projects the user hasn't explicitly toggled (canvas or the kanban board).
* Personal machine-local preference; per-project explicit choices override it. */
defaultProjectView: 'canvas' | 'kanban'
/** Global swimlane kanban overview (Omni-Kanban): when enabled, the kanban board shows all
* open projects as stacked swimlanes instead of per-project tabs. Toggle in Settings →
* Behavior. Default OFF — no silent behavior change for existing users; `globalKanban`
* (the view flag) is only honored when this is true. */
omniKanbanEnabled: boolean
/** When enabled, Cmd+Shift+B (view.kanbanToggle) opens the global Omni board instead of the
* per-project board. The dedicated global shortcut (view.globalKanbanToggle) always opens
* Omni regardless of this setting. Opt-in, per user — default OFF. */
omniKanbanAsDefault: boolean
/** New-worktree path template, resolved relative to the repository root. Supports `$repoName`
* (`$reponame` and `$defaultFolderName` aliases) plus `$branch`; both `$x` and `${x}` forms.
* A missing branch token is appended automatically. */
worktreePathTemplate: string
/** Issue #1145. Where a folder project created from now on keeps its canvas: `'folder'` (the
* default — `<cwd>/.nodeterm/project.json`, git-shareable) or `'appData'` (nothing written into
* the folder; see `Project.storeInAppData`). A folder that already has a project.json is adopted
* as it is, in its folder, whatever this says. Existing projects move from the tab menu. */
newProjectStorage: import('./project-storage').NewProjectStorage
/** ms to dwell over a terminal before it takes pointer focus (pan-across guard). */
panHoverDelay: number
/** Issue #757. Whether a terminal node's keyboard focus follows the POINTER (the long-standing
* behaviour and the default): a `panHoverDelay` dwell takes it and leaving the node gives it
* back. Off = click to focus (the Mac model): the pointer decides nothing, a click or a "go to
* node" takes the keyboard, and the terminal keeps it until focus really moves elsewhere
* (another node, the empty canvas, a field). Machine-local, Settings → Behavior. Decisions live
* in `renderer/lib/terminalFocusMode.ts`. */
terminalFocusFollowsPointer: boolean
doubleClickFocus: boolean
/** "Go to node" (sessions sidebar, notification click, ⌘K jump, breadcrumb steps, presence
* travel) fits the node in view. Off: the camera keeps the CURRENT zoom and only pans, which is
* what a user who has settled on a zoom level wants — a jump that also rescales the whole canvas
* costs them the sense of where they were. Either way the node is centred and kept clear of the
* floating chrome (renderer/lib/nodeFocus). */
focusZoomToNode: boolean
/** Closing the LAST session (terminal/agent) node of a project with its × offers to close the
* project too (issue #848). Opt-in — default OFF, because not everyone closes their last
* session when they are done with a project. Only the user's × click asks; a restart, an exit,
* a hibernated agent (still a node) or a bulk/programmatic close never does
* (renderer/lib/lastSessionClose). Declining keeps the project open. */
offerCloseProjectOnLastSession: boolean
/** Whether the bottom-left canvas lock survives a restart. OFF by default, and deliberately so:
* the lock was transient by design, because a canvas that will not pan on the next launch reads
* as "the app is frozen" to whoever opens it, and the lit button is a small thing to spot. Users
* who lock on purpose and want it to stay locked opt in here; everyone else opens unlocked
* exactly as before. The lock itself is persisted in localStorage (renderer/lib/canvasLock),
* never in settings.json or the git-shared project.json: this flag says whether to remember,
* the lock is one person's view state. Machine-local on Desktop; in the Server Edition this
* setting is the server's while the lock is per browser profile. */
rememberCanvasLock: boolean
/** Whether `nodeterm://` links from other apps are handled (docs/superpowers/specs/
* 2026-10-13-open-link-design.md). OFF by default: a link can come from any web page, script
* or app, so taking them is something a person turns on. On, a `nodeterm://open` link shows a
* confirm sheet and opens ONE agent or terminal node only after a click; `nodeterm://pair` and
* `nodeterm://join` pre-fill the code prompt. Off, a link opens nothing and a notice says where
* to turn it on. Machine-local (settings.json); read by main on every link. */
allowOpenLinks: boolean
/** Open Markdown files (.md, .markdown, …) in rendered preview instead of the code editor.
* Only picks the view an editor node OPENS in — the node's Preview/Edit toggle (and the
* markdown-toggle chord) still switches either way. Default ON since the release after
* v0.3.3 (maintainer decision on issue #495; a preview is one ⌘M from the editor, so the
* rendered view is the better first sight for docs). A one-shot load migration keyed on
* `openMarkdownPreviewMigrated` (see mergeSettings) forces this ON once for every existing
* file — including one saved by v0.3.3, the one release that defaulted off and whose
* full-snapshot saves materialized `false` for users who never touched the toggle. After
* the migration the user's own opt-out is permanent. */
openMarkdownPreview: boolean
/** One-shot marker for the openMarkdownPreview default flip (#495). Absent = the file
* predates the flip → the load migration sets `openMarkdownPreview: true` and stamps this
* true; present = the migration already ran (or the install was born after it) and the
* stored `openMarkdownPreview` value is the user's own, never touched again. */
openMarkdownPreviewMigrated: boolean
/**
* Let a MIDDLE CLICK inside a terminal paste (Linux in practice — macOS and Windows have no
* PRIMARY selection and no tmux middle-click habit, so the guard changes nothing visible there).
*
* OFF by default, and OFF means the middle button is fully INERT inside a terminal — tmux's own
* middle-click paste included. That is a consequence of the real mechanism (issue #84, measured
* on the reporting machine): the paste never happens in the browser. xterm forwards a mouse
* report for the middle button and something DOWNSTREAM of the pty consumes it — tmux's root
* `MouseDown2Pane` binding pastes tmux's buffer at a shell prompt, and an agent TUI reads the X
* PRIMARY selection itself. There is no browser default action to cancel, so the guard swallows
* the event before xterm can forward it (`guardMiddleClickPaste`), and tmux's paste necessarily
* goes with it. The default stays off because the paste fires hardest inside agent TUIs: a stray
* click drops whatever was last selected anywhere on the machine into a live agent prompt.
*/
terminalMiddleClickPaste: boolean
/**
* Copy a completed MOUSE selection that the terminal emulator (xterm) owns to the system
* clipboard (issue #759). OFF by default: it preserves the explicit-copy behaviour, and silently
* changing what is on the clipboard is a surprise worth opting into.
*
* Scope, stated honestly: it covers only selections xterm makes itself — a drag, double/triple
* click, or a FORCED selection (Option-drag on macOS, Shift-drag elsewhere) inside an app that
* tracks the mouse. It cannot copy a selection an app draws itself, and OSC 52 copies (tmux
* copy-mode, vim `"+y`) reach the clipboard whether this is on or off. Programmatic selections
* (find-bar hits) never copy. Read live, so a toggle applies to the next drag on every open
* terminal. Logic: `renderer/terminal/copy-on-select.ts`.
*/
copyOnSelect: boolean
/** ⌘+ / ⌘− / ⌘0 (Ctrl off-mac) change the FOCUSED terminal's own font size instead of doing
* nothing / zooming the canvas (issue #915). The size is stored per node
* (`CanvasNodeState.terminalFontSize`); ⌘0 clears it back to `fontSize`. OFF by default: off-mac
* the chord is Ctrl+−, which a focused terminal passes to the shell today (readline undo). With
* it off, and whenever no terminal has focus, the keys behave exactly as before. See
* renderer/terminal/terminal-font-zoom.ts. */
terminalFontZoomKeys: boolean
/**
* Windows SSH projects: after a key is unlocked with its passphrase, also load it into the
* Windows OpenSSH agent service, so later connections (and the user's own `ssh`) do not prompt
* again. OFF by default because that agent STORES the key — DPAPI-encrypted in
* `HKCU\Software\OpenSSH\Agent\Keys`, surviving service restarts — until it is removed
* (`ssh-add -d` / `-D`), and it refuses a lifetime constraint (measured on windows-latest,
* OpenSSH_for_Windows_9.5p2), so there is no "for this session only". A host whose own
* `~/.ssh/config` says `AddKeysToAgent yes` gets the add without this switch: that user already
* asked OpenSSH for exactly this. Logic: `core/remote-ssh/native/agent-add.ts`.
*/
windowsSshAgentAddKeys: boolean
/** Plain mouse wheel zooms the canvas (no Cmd/Ctrl needed). On macOS a two-finger trackpad
* scroll keeps panning independently (see canvas/wheel-gesture.ts), so mouse and trackpad
* coexist; elsewhere this still trades away scroll-to-pan, so it stays opt-in. */
wheelZoom: boolean
/** How far one plain wheel click zooms, as a multiplier on the canvas zoom step (0.2–2,
* default 1 = historical feel). Applies only to the `wheelZoom` path — Cmd/Ctrl+wheel and
* pinch keep the fixed step, so tuning a chunky mouse down never slows the trackpad.
* Validated at point of use (canvas/wheel-zoom.ts `clampWheelZoomSpeed`). */
wheelZoomSpeed: number
/** macOS only: a two-finger trackpad scroll pans the canvas, independently of `wheelZoom`
* (see canvas/wheel-gesture.ts). Off restores the pre-router behavior — `wheelZoom` alone
* decides. On the desktop the device is identified from the main process's raw input stream
* (main/trackpad-gesture.ts), so mouse zoom and trackpad pan coexist; the off-switch is the
* remaining recourse for the Server Edition's browser tab, where detection is heuristic and a
* precise-pixel MOUSE still reads as a trackpad. */
trackpadPan: boolean
/** What a left-drag on EMPTY canvas does. 'select' (default) rubber-band selects, like
* Figma's move tool — pan stays on middle-drag / two-finger scroll. 'pan' drags the map
* directly (grab cursor), for mouse users who pan constantly; box-select then moves to
* Shift+drag (React Flow's selectionKeyCode). */
canvasDragMode: 'select' | 'pan'
/**
* Browser memory saver: release a browser/web node's page after it has been hidden for
* `BROWSER_DISCARD_MS` (5 min), reloading it from its URL when it is shown again. Each
* `<webview>` is a whole Chromium renderer process and the canvas caps nothing, so an
* afternoon of opened pages is otherwise permanently resident. On by default — the cost is a
* reload (and the lost back/forward stack, which a webview cannot serialize), not lost work.
*/
browserMemorySaver: boolean
accent: string
tmuxEnabled: boolean
/**
* Which multiplexer creates a NEW local terminal's persistent session on POSIX: `tmux` (default)
* or `zellij`. Hand-editable, so every reader goes through `normalizeSessionBackend`
* (@shared/session-backend) — anything unknown reads as tmux. A node whose session already
* lives in one backend keeps reattaching there; Windows and SSH projects ignore it.
*/
sessionBackend: SessionBackend
/**
* Reach a released tmux session with a control-mode (`tmux -C`) client instead of respawning its
* terminal — the shadow clients in pty-manager.ts (`shadowAttach`) and the shared background-write
* client behind `backgroundWrite`. A control client holds ZERO pty devices, which is the whole
* point: the machine-wide `kern.tty.ptmx_max` ceiling is what a canvas of idle terminals runs into
* first (see pty-devices.ts).
*
* ON by default, and read at those two entry points only: switching it off means this process
* spawns no `tmux -C` child at all, and a released session is simply unreachable again — exactly
* the behavior of the release before it. It is a kill switch for one soak release, not a feature
* toggle: nothing user-visible depends on it (the mechanism has no production caller yet), so it
* has no settings row and is flipped in settings.json.
*/
ptyShadowClients: boolean
/** GPU (WebGL) terminal rendering. 'off' routes every terminal to xterm's DOM renderer.
* 'auto' (default) = one WebGL context PER TERMINAL everywhere except macOS, where it is
* 'shared'. Repeated macOS field reports (whole-window flicker; terminals compositing black
* after renderer swaps, with zero JS-visible errors) point at the OS compositor mishandling
* many live WebGL canvases — which is why per-terminal WebGL stays a deliberate opt-in ('on')
* there, and why the ONE-context renderer is what macOS defaults to instead. Legacy boolean
* values are migrated on load: `false` (an explicit escape-hatch choice) → 'off'; `true`
* (indistinguishable from the old merged-in default) → 'auto'.
*
* 'shared' is the glyphgrid renderer: instead of one WebGL context per terminal (which is what
* the ~16-context cap and the whole budget coordinator exist to ration), every terminal on the
* canvas paints into ONE canvas-wide context. Promoted out of experimental on 2026-08-05 after
* the device checklist + soak; any failure still drops the session back to xterm's DOM
* renderer. See `resolveTerminalRenderer` (shared/webgl.ts) for the full history. */
terminalGpuRendering: 'auto' | 'on' | 'off' | 'shared'
tmuxScrollback: number
/** OPT-IN lead-pane width for Claude Code agent teams (issue #119). 0 = off (default): the
* generated tmux confs stay byte-identical to their pre-feature output — no `set-hook` at all.
* 40–90 = emit guarded after-resize-pane / after-split-window hooks (shared/tmux-lead-pane.ts)
* that keep the lead pane at this % of the node width when CC's team backend re-applies its
* hardcoded 70/30 split. Hand-editable; re-validated at the conf-generation site
* (`sanitizeLeadPaneWidth`). Honest side effect while on: a manual 50/50 split in a plain
* terminal node is nudged to the target too. */
tmuxLeadPaneWidth: number
/** Minutes a terminal may sit fully offscreen before its xterm+PTY client is torn down in
* place (tmux keeps the session; re-approach reattaches and redraws). 0 = never. */
offscreenTerminalMinutes: number
/** Minutes a terminal stays PARKED after its project is switched away — xterm + PTY client kept
* alive off-DOM so switching back is instant and exact (no reattach). 0 = until the app quits.
* Default 10. Hand-editable; re-validated at the use site (`parkWindowMs`). Issue #886. */
terminalParkMinutes: number
/** Max parked terminals across all projects before the oldest (local first, then remote) are
* released early. Default 20. Re-validated at the use site (`parkCap`). Issue #886. */
terminalParkMax: number
/** AI commit message agent: a local coding-agent CLI run read-only. */
commitAgent: 'claude' | 'codex' | 'custom'
/** For commitAgent='custom': command template; {prompt} placeholder optional (else stdin). */
commitAgentCommand: string
/** Extra instructions appended to the commit prompt (e.g. Conventional Commits). */
commitExtraPrompt: string
/** Whether the shortcuts overlay has been shown on first launch. */
seenShortcuts: boolean
/** Whether the first-run setup tour (onboarding) has been completed or skipped. Existing
* installs (seenShortcuts already true) are migrated to true silently — the tour is for
* fresh installs; rerunnable via the ⌘K "Setup tour" command. */
seenOnboarding: boolean
/** Notify (OS notification) when a Claude Code turn finishes while the app is in the background. */
notifyOnClaudeDone: boolean
/** Periodically `git fetch` while the Source Control panel is open, so ahead/behind stays
* accurate (remote/SSH projects fetch on the remote). */
gitAutoFetch: boolean
/** Whether the one-time notification consent prompt has been shown. */
notifyConsentAsked: boolean
/** Play a retro sound effect when a turn finishes / a session needs you (renderer/lib/sfx.ts).
* Unlike OS notifications this fires whether or not the window is focused — the point is to
* catch a finish while you're looking at ANOTHER node. Throttled per node. */
soundEffects: boolean
/** Sound-effect volume, 0..1. */
soundVolume: number
/** User-picked replacements for the built-in chimes, per alert kind (issue #289). Holds only a
* display name + a stamp — the FILE lives in the core's data dir (`<userData>/sounds/`), never
* at the user's original path. Read through `customAlertSoundFor` (hand-editable JSON); an
* absent/malformed entry, or a file that is gone or will not decode, plays the built-in chime. */
customAlertSounds: CustomAlertSounds
/** User-defined agents (BYO CLI) appended to the Add menus. */
customAgents: CustomAgent[]
/** One gateway root + non-secret credential reference used by model-switch-capable harnesses. */
modelGateway: ModelGatewaySettings
/** The default gateway model id (from discovery) applied to a fresh canvas agent spawn when
* `agentLaunchMode === 'gateway-model'`. A separate field from `modelGateway` (it is NOT a
* credential). Absent/empty = no default ⇒ `'gateway-model'` behaves like `'gateway'`. */
modelGatewayDefaultModel?: string
/** Per-builtin-agent launch command overrides (Settings → Agents → Launch commands). The value
* replaces the bare CLI name everywhere a launch line is built — new sessions, cold-restore
* relaunches and in-place restarts, with the usual flags (`--resume`, `--permission-mode`, the
* prompt) appended after it — so a wrapper script that picks an account or sets env vars runs
* wherever the agent would. Empty/absent = the builtin default, byte-identical to before this
* setting existed. Keyed by builtin id only: custom agents already own their `launchCmd`. */
agentLaunchCommands: Partial<Record<BuiltinAgentId, string>>
/** Managed Claude accounts (config-dir isolated). See ClaudeAccount. */
claudeAccounts: ClaudeAccount[]
/** Managed Codex accounts (CODEX_HOME isolated, machine-scoped by `host`). See CodexAccount.
* Renderer-owned in settings.json exactly like `claudeAccounts`; main owns only fs lifecycle. */
codexAccounts: CodexAccount[]
/** Custom display label for the SYSTEM Claude account (~/.claude) in pickers/settings.
* Empty = unset → fall back to the detected login email, else "System account". */
systemAccountLabel: string
/** Agent ids hidden from the Add menus. */
disabledAgents: AgentId[]
/** Usage providers hidden from the pill + popover (Settings → Usage toggles). Hiding is a
* DISPLAY choice — credentials and fetchers are untouched, so re-enabling is instant. */
hiddenUsageProviders: string[]
/** Ids of node right-click menu rows the user has hidden; empty = everything visible. Only ids
* in HIDEABLE_MENU_ITEMS (renderer/lib/ui-visibility.ts) can hide — Delete and the other
* recovery actions stay put whatever this array says. */
hiddenNodeMenuItems: string[]
/** Ids of terminal node header buttons the user has hidden; empty = everything visible. Gated by
* HIDEABLE_HEADER_BUTTONS the same way. */
hiddenHeaderButtons: string[]
/** Whether project activation offers the "Resume where you left off" card (breadcrumb trail's
* once-per-app-run popup). OFF by default — it interrupts every project switch, so it is
* opt-in. Cmd+[ / Cmd+] and the Dock buttons walk the trail regardless of this. */
showResumeCard: boolean
/** Draw the canvas dot grid (Settings → Appearance). Display only — snapping and align-to-grid
* are unchanged. Default ON in every appearance; read through `showCanvasDots`. */
canvasDots: boolean
/** Pulse the RUNNING chip on board cards (Settings → Appearance). Off = the same chip, held still.
* The node header's mascot is not affected. Default ON; read through `pulseBoardRunning`, so only
* a literal false stops it. */
boardRunningPulse: boolean
/** The Liquid Glass slider (Settings → Appearance), 0 = Clear … 1 = Tinted. null = the Readable
* tick, where text keeps 4.5:1 (renderer/lib/glassContrast.ts `resolveGlassSlider`). */
glassTint: number | null
/** Liquid Glass: keep the node blur and refraction live while the canvas pans or zooms (Apple's
* behaviour, more GPU). Off = the blur pauses during a camera move and the tint alone stays.
* Default ON; only a literal false turns it off (`keepGlassBlurWhileMoving`). */
glassBlurWhileMoving: boolean
/** Whether usage percentages render as consumed ("32% used"), remaining ("68% left"), or raw
* token counts ("48k/200k tokens" — context-window surfaces only; provider quota surfaces
* have no token counts and fall back to 'used' display). 'remaining' is the historical
* default; users coming from other tools expect 'used'. */
usagePercentMode: 'used' | 'remaining' | 'tokens'
/** Which agent the ⌘⇧C shortcut / quick-add launches. Always a launchable builtin. */
defaultAgent: AgentId
/** The permission mode Claude TERMINAL (CLI) sessions START in — passed as `--permission-mode`
* at launch; Shift+Tab still cycles modes at runtime. SDK chat nodes are NOT covered (the chat
* driver runs in `default`). Overridable per project via Project.defaultPermissionMode.
* `auto` is version-gated: CLIs below 2.1.71 reject the value, so it degrades to no flag. */
claudePermissionMode: AgentPermissionMode
/**
* When on, EVERY fresh agent launch spawns with gateway + inherited provider env stripped, so the
* agent runs against its OWN default provider (Claude's subscription, Copilot's GitHub routing)
* instead of a configured gateway/inherited override. The per-node one-shot `data.clearEnv`
* (cleared after its single recycle) is the per-node action; this is its global counterpart.
* Default OFF — opt-in, because it changes which provider every agent node uses. Does NOT strip
* `CLAUDE_CONFIG_DIR` (account isolation survives). See `vanillaEnvStripPattern`.
*/
vanillaLaunchDefault: boolean
/** The default provider behavior for a fresh agent spawn (the three-way successor to
* `vanillaLaunchDefault`). See `AgentLaunchMode`. Default `'gateway'` = today's behavior. */
agentLaunchMode: AgentLaunchMode
/** "Eco": exit the agent CLI of a session that has been idle AND offscreen for
* `agentHibernationIdleMinutes`, reclaiming its RAM; the conversation is resumed automatically
* when the node is viewed again. Default OFF — opt-in, because it stops a real process.
* Scheduled/loop agents and sessions with live subagents are never touched
* (renderer/terminal/hibernation-policy.ts explains why). */
agentHibernationEnabled: boolean
/**
* Agent messaging for a project whose `.nodeterm/project.json` carries NO `agentMessaging` value
* (@shared/project-capabilities, CAPABILITY_MACHINE_DEFAULTS). MACHINE-LOCAL on purpose: it is
* this machine's user deciding for their own unconfigured projects, which is why it may answer
* without a clone notice — while an explicit `true` in a cloned file still needs one, and an
* explicit `false` still wins. Read strictly (`=== true`). Never settable from the canvas CLI
* (@shared/settings-verb forbids it): it is a grant over every project at once.
*/
agentMessagingDefault: boolean
/** How long a session must be idle + offscreen before "Eco" hibernates it (minutes). */
agentHibernationIdleMinutes: number
/** When Eco hibernates a session, also mark it PAUSED (see `AgentNodeStatus.paused`) so it does
* NOT auto-resume the next time the project or app reopens — only an explicit Resume brings it
* back. Off by default: ordinary Eco already resumes automatically on the next reveal, and this
* opts a hibernated session OUT of that for good, trading convenience for a colder, smaller
* footprint across restarts. Independent of manual "Pause session", which always persists this
* way regardless of this setting. */
agentHibernationPersistAcrossRestart: boolean
/** Send anonymous usage data: the version/OS telemetry ping, and the open-project count on the
* /v1/check call (`openProjects`, a number only — never names, paths or hosts). Opt-OUT
* (default on): nothing personal, client IP never stored. Turn it off in Settings → Privacy
* (or hard-disable with DO_NOT_TRACK / NODETERM_TELEMETRY_DISABLED). Note: a lighter anonymous
* install count also rides the /v1/check call and is NOT gated on this toggle — see core/check.ts. */
telemetryEnabled: boolean
/** The user's consent to license and free-project-allowance calls to api.nodeterm.dev while
* DO_NOT_TRACK / NODETERM_TELEMETRY_DISABLED is set. Default off: under DNT nothing
* license-related leaves the machine until the user says so. Covers ONLY the calls behind
* `licenseNetworkGate()` (core/license.ts) — never telemetry or the check feed, which stay off
* under DNT whatever this says. Read as `=== true` (main installs it via
* `setLicenseNetworkConsent`), so a hand-edited non-boolean is no consent. Shown and revocable in
* Settings → Privacy only while DNT is set. Never settable by an agent (SETTINGS_VERB_FORBIDDEN). */
licenseNetworkConsent: boolean
/** Debug log panel (issue #78): captures the app's own console into an in-memory, redacted
* ring and unlocks the log viewer. Default off — a debugging tool, not a daily surface.
* Toggle in Settings → Application → Debug. */
debugLogPanel: boolean
/** Keep a standing relay host connection so a paired phone can reach this Mac from anywhere
* (end-to-end encrypted). Default on — the host only admits SAS-approved, pinned devices, so
* an un-paired install just keeps an idle listener. Toggle in Settings → Phone. */
phoneAccessEnabled: boolean
/** Send APNs push notifications to relay-paired phones when an agent needs approval, asks a
* question, or finishes a turn (spec: apns-push). Default on — it only fires for users who
* have paired a phone. Toggle in Settings → Notifications. */
mobilePushEnabled: boolean
/** Push when an agent needs you: approval requests + questions. Default on. Sub-gate under
* `mobilePushEnabled` (the master switch). Toggle in Settings → Notifications. */
mobilePushNeedsYou: boolean
/** Push when an agent finishes a turn (the `done` kind). Default on. Sub-gate under
* `mobilePushEnabled` (the master switch). Toggle in Settings → Notifications. */
mobilePushDone: boolean
/** Stream live status updates to paired phones as a session's state + activity + context%
* change — an iOS Live Activity (Lock Screen / Dynamic Island) or an Android ongoing
* notification (spec: interactive-push-live-activities). Default on. The KEY keeps its
* iOS-era name because it is persisted in settings.json; the UI calls it "Live updates on
* phone". Sub-gate under `mobilePushEnabled` (the master switch). Toggle in Settings →
* Notifications. */
mobileLiveActivities: boolean
/** Hold phone ALERTS while you're actively at this computer, releasing them when you go idle or
* lock the screen (spec: presence-aware-push). Default on. Desktop-only (the Server Edition is
* headless, so it always sends); the live-update stream is never held. Sub-gate under
* `mobilePushEnabled`. Off ⇒ alerts always send immediately (legacy). Toggle in Settings →
* Notifications. */
mobilePushPresenceAware: boolean
/** Deterministic hook-reply approvals (spec: docs/hook-reply-approvals.md). When on (default),
* Claude terminal sessions launch with `NODETERM_PERM_WAIT_SECS` set: the managed permission
* hook holds briefly for a phone/canvas Approve/Deny before falling through to the normal
* interactive prompt. Off ⇒ the env var is absent ⇒ exact legacy behavior. Claude-only. */
hookReplyApprovals: boolean
/** Remove a subagent's ephemeral canvas card the moment that subagent REPORTS finished, instead
* of keeping it until the parent agent's next turn clears it. Default off ⇒ exact legacy
* behavior. A card whose subagent is still running is never removed by this, and neither is one
* the stale decay marked done because its end never arrived. Settings → Agents. */
autoHideFinishedSubagentCards: boolean
/** Hold an idle-sleep power assertion while a LOCAL agent node is working, so long runs
* survive an unattended laptop. Released when the last one stops (or goes stale). Cannot
* hold through a closed lid. Asked in the setup tour; Settings → Behavior. */
keepAwakeWhileAgentsWork: boolean
/** Ask before the app actually quits (⌘/Ctrl+Q, menu Quit, or the Windows/Linux title-bar ×).
* The auto-update "Restart to update" flow never asks — that decision was already made.
* Settings → Behavior. */
confirmBeforeQuit: boolean
/** Windows/Linux "background mode": closing the window hides it to the notification-area tray
* instead of quitting, so the phone relay host, hook server, notifications and updater keep
* running — the analogue of macOS keeping the app in the Dock. `'auto'` (default) = on for
* Windows, off for Linux (whose tray support depends on the desktop environment). Resolved by
* `resolveBackgroundOnClose` (src/main/background-mode.ts); ignored on macOS (always hides) and
* on the Server Edition (no window). Hand-editable: an unknown value reads as `'auto'`.
* Settings → Behavior (Windows/Linux only). */
runInBackgroundOnClose: BackgroundOnCloseSetting
/** macOS Notch HUD (docs/notch-hud.md): a transparent always-on-top strip by the notch showing
* walking agent mascots while agents work, expanding into a mini session panel. Default on;
* macOS + desktop only (ignored on other platforms / Server Edition). */
notchHud: boolean
/** Assumed physical notch width in px. macOS exposes no API for it (Electron has no
* `auxiliaryTopLeftArea`), so the capsule has to assume one — this is the knob that makes it sit
* flush on YOUR Mac. Bigger = the capsule sits further left. */
notchWidth: number
/** Which side of the primary display the capsule sits on. `center` (default) hugs the physical
* notch; `left` / `right` draw a floating pill at that edge. Re-validated at use
* (`sanitizeNotchAlign`, shared/notch-hud.ts): an unknown string means `center`. */
notchAlign: NotchAlign
/** Vertical offset of the capsule from its resting place, px, positive = DOWN. Up is bounded by
* the display's top edge (the fused notch capsule is already there, so it only moves down —
* and moving it detaches it into a pill). Clamped to NOTCH_OFFSET_MIN/MAX; non-finite → 0. */
notchOffsetY: number
/** Expand the notch panel on hover (after a short dwell). Off = click the capsule to expand. */
notchHoverExpand: boolean
/** Dictation (desktop/server). Written as a whole object by the renderer. */
speech: SpeechSettings
/** Keyboard-shortcut overrides by command id (see shared/keybindings.ts). Absent id = the
* command's default bindings; `[]` = disabled. Hand-editable; invalid or conflicting
* entries are dropped with a console warning at read time (sanitizeKeybindingOverrides).
* Optional and deliberately not in DEFAULT_SETTINGS: absent simply means "no overrides". */
keybindings?: KeybindingOverrides
/** Who wins while a terminal has keyboard focus: 'app-first' (default) lets allowInTerminal
* app commands fire over an xterm; 'terminal-first' reserves every chord but the terminal's
* own (find, copy) for the shell/TUI — including ⌘W/⌘M and the zoom/project-jump gestures. */
terminalShortcutPolicy: TerminalShortcutPolicy
/** Command ids whose "this chord was captured from your terminal" notice has been shown
* (app-first only, once per command). Optional and absent from DEFAULT_SETTINGS: absent
* means none seen. Lives in settings, not localStorage, so Server Edition shares it. */
seenShortcutCaptureNotices?: string[]
/** Per-node hook identity enforcement (src/core/agents/node-identity-policy.ts).
*
* One of the three optional keys in this interface, and deliberately so: it is a TRI-state, and the two
* non-default states are opposite escape hatches. Absent (the default — it is not in
* DEFAULT_SETTINGS) follows `NODE_IDENTITY_STRICT_AFTER`, so the rollout has one schedule for
* everybody. `true` opts in to strict enforcement before that date. `false` keeps the warning
* window open past it and releases the trust-on-first-proof latch, so a user whose upgrade
* strands a live session gets their canvas back without downgrading the app. Neither value ever
* admits a forged token. */
hookIdentityStrict?: boolean
/** Agent-integration consent (issue #744, `@shared/agent-integrations`): which agents nodeterm
* may integrate with by writing into their user-owned global config (status hooks, skills),
* here and per SSH host. Optional and absent from DEFAULT_SETTINGS: absent = a new install that
* has not been asked, which writes NOTHING. Hand-editable, so every reader sanitizes. */
agentIntegrations?: AgentIntegrationsSettings
/** Machine-local waivers for the canvas-control destructive confirm dialog
* (@shared/control-confirm). Absent — and absent from DEFAULT_SETTINGS — means "always ask",
* which is the pre-feature behavior bit for bit.
*
* MACHINE-LOCAL BY CONSTRUCTION, and the reason is the trap this closed: a permission mode
* rides `.nodeterm/project.json` and is git-shared, so anything keyed on the mode alone could
* be turned off for a user by a repository they cloned. A waiver is a statement about this
* machine's trust in its own agents, so it lives here and NEVER in a project file. */
controlConfirmWaivers?: ControlConfirmWaivers
/** Machine-local: move a session card to a column once every pull request linked to it has
* merged (@shared/kanban-pull-links — why this is here and never in the project file). Absent —
* and absent from DEFAULT_SETTINGS — means off everywhere. Read through
* `sanitizeKanbanPullAutoMove`: settings.json is hand-editable. */
kanbanPullAutoMove?: KanbanPullAutoMove
/** Machine-local board dispatch: which projects start an agent run when this person moves a
* GitHub issue card into a chosen column, with which agent and how many at once, plus the kill
* switch (@shared/board-dispatch — why this is here and never in the project file). Absent —
* and absent from DEFAULT_SETTINGS — means off everywhere. Read through
* `sanitizeBoardDispatch`: settings.json is hand-editable. */
boardDispatch?: BoardDispatch
}
export const DEFAULT_SETTINGS: Settings = {
fontSize: 13,
fontFamily: 'Menlo, Monaco, "Courier New", monospace',
// Keep hyphens, underscores, slashes and dots inside words so identifiers and paths select whole.
terminalWordSeparator: " ()[]{}',\"",
cursorBlink: true,
// Every appearance default below reproduces the pre-feature look bit-for-bit: the default theme
// carries the old hardcoded background/foreground, and block/outline/1/0 are xterm's own
// defaults. Picking a theme is opt-in — an update must not repaint anybody's terminals.
// Follows the terminal theme, whose own default is dark — so an install that never touches
// either setting keeps the dark chrome it has always had.
appTheme: 'auto',
uiScale: 1,
windowTitleActiveSession: false,
terminalTheme: 'nodeterm-dark',
desktopWallpaper: { kind: 'none' },
recentWallpaperImage: null,
fontWeight: 400,
fontWeightBold: 700,
drawBoldTextInBrightColors: true,
terminalMinContrast: 1,
cursorStyle: 'block',
cursorInactiveStyle: 'outline',
terminalLineHeight: 1,
terminalLetterSpacing: 0,
defaultShell: '',
gridSize: 24,
snapToGrid: false,
autoAlignGrid: false,
tabBarHeight: TABBAR_HEIGHT_PX,
stickyNoteBacking: 0,
groupFrameBacking: 0,
markdownFontFamily: DEFAULT_MARKDOWN_FONT_FAMILY,
markdownFontSize: DEFAULT_MARKDOWN_FONT_SIZE,
defaultNodeWidth: 640,
defaultNodeHeight: 440,
defaultNodeSizes: {},
sidebarAutoCollapse: true,
sidebarCollapsedItems: {},
sidebarGrouping: 'project',
defaultProjectView: 'canvas',
omniKanbanEnabled: false,
omniKanbanAsDefault: false,
worktreePathTemplate: DEFAULT_WORKTREE_PATH_TEMPLATE,
newProjectStorage: 'folder',
panHoverDelay: 600,
terminalFocusFollowsPointer: true,
doubleClickFocus: true,
focusZoomToNode: true,
offerCloseProjectOnLastSession: false,
rememberCanvasLock: false,
allowOpenLinks: false,
openMarkdownPreview: true,
openMarkdownPreviewMigrated: true,
terminalMiddleClickPaste: false,
copyOnSelect: false,
terminalFontZoomKeys: false,
windowsSshAgentAddKeys: false,
wheelZoom: false,
wheelZoomSpeed: 1,
trackpadPan: true,
canvasDragMode: 'select',
browserMemorySaver: true,
accent: '#0a84ff',
tmuxEnabled: true,
sessionBackend: 'tmux',
ptyShadowClients: true,
terminalGpuRendering: 'auto',
tmuxScrollback: 50000,
tmuxLeadPaneWidth: 0,
offscreenTerminalMinutes: 10,
terminalParkMinutes: 10,
terminalParkMax: 20,
commitAgent: 'claude',
commitAgentCommand: '',
commitExtraPrompt: '',
// 'app-first' reproduces today's dispatch bit-for-bit: allowInTerminal app commands keep
// firing over a focused xterm. Opting into 'terminal-first' is the user's call, never ours.
terminalShortcutPolicy: 'app-first',
seenShortcuts: false,
seenOnboarding: false,
notifyOnClaudeDone: true,
gitAutoFetch: true,
notifyConsentAsked: false,
soundEffects: true,
soundVolume: 0.5,
customAlertSounds: {},
customAgents: [],
modelGateway: { baseUrl: '', apiKey: '' },
// No default gateway model until the user picks one in Settings → Model gateway. Absent ⇒
// `'gateway-model'` behaves like `'gateway'` (no --model on a fresh spawn).
modelGatewayDefaultModel: undefined,
agentLaunchCommands: {},
claudeAccounts: [],
codexAccounts: [],
systemAccountLabel: '',
// All three builtin agents (Claude/Codex/Gemini) show in the Add menus out of the box.
// Existing users keep whatever they've saved (their persisted disabledAgents overrides this).
disabledAgents: [],
hiddenUsageProviders: [],
// Nothing hidden out of the box, so existing users see the menu and header they already know.
hiddenNodeMenuItems: [],
hiddenHeaderButtons: [],
// Opt-in: the resume card pops over the canvas on every qualifying project activation, which
// reads as noise to users who navigate by the trail chords/Dock buttons instead.
showResumeCard: false,
canvasDots: true,
boardRunningPulse: true,
glassTint: null,
glassBlurWhileMoving: true,
usagePercentMode: 'remaining',
defaultAgent: 'claude',
// Sessions start in auto mode out of the box. Existing users pick this up on hydrate
// (settings hydrate merges over DEFAULT_SETTINGS) — a deliberate behavior change.
claudePermissionMode: 'auto',
// Opt-in: strips the gateway/inherited provider env on every fresh launch so agents run against
// their own default provider. Off by default — changes which provider every agent node uses.
vanillaLaunchDefault: false,
// The three-way successor to the boolean above. `'gateway'` = inject gateway env, CLI default
// model (today's behavior). `vanillaLaunchDefault` is now its migration mirror.
agentLaunchMode: 'gateway',
// Opt-in: hibernation exits a live CLI, so nobody gets it without asking. The 30-minute floor
// is deliberately long — shorter windows exit sessions the user is between turns on.
agentHibernationEnabled: false,
// OFF until the cross-restart pane-ownership proof lands: messaging refuses every pane that
// survived an app restart (core/agents/pane-ownership.ts), so "on by default" would be false
// after every restart and every update. Flipping this is a separate, deliberate change.
agentMessagingDefault: false,
agentHibernationIdleMinutes: 30,
agentHibernationPersistAcrossRestart: false,
// Opt-out (default on). Existing users pick this up on hydrate ONLY if their settings.json has
// no telemetryEnabled key yet; anyone who already saved settings keeps their stored value.
telemetryEnabled: true,
// Off: under DO_NOT_TRACK no license call runs until the user consents in Settings → Privacy.
licenseNetworkConsent: false,
debugLogPanel: false,
phoneAccessEnabled: true,
mobilePushEnabled: true,
mobilePushNeedsYou: true,
mobilePushDone: true,
mobileLiveActivities: true,
mobilePushPresenceAware: true,
// Deterministic hook-reply approvals default ON (existing users pick it up on hydrate). Only
// affects Claude terminal sessions; off reproduces the pre-feature launch bit-for-bit.
hookReplyApprovals: true,
autoHideFinishedSubagentCards: false,
// Keep-awake-while-agents-work default ON (existing users pick it up on hydrate — deliberate,
// same note style as hookReplyApprovals). Held only while a local agent is actually working.
keepAwakeWhileAgentsWork: true,
// Confirm-before-quit default ON: sessions survive a quit anyway, but an accidental ⌘Q
// tears down every window at once; the toggle is one switch away for who finds it noisy.
confirmBeforeQuit: true,
// Background mode 'auto' = on for Windows (the tray is always there), off for Linux.
runInBackgroundOnClose: 'auto',
// macOS Notch HUD default ON (guarded to darwin at runtime; a no-op elsewhere).
notchHud: true,
notchWidth: 168,
notchAlign: 'center',
notchOffsetY: 0,
notchHoverExpand: true,
// model: '' = the explicit "no dictation" state (SPEECH_MODEL_NONE, issue #143). Dictation is
// opt-in: nothing is selected — and so nothing downloads and no shortcut records — until the
// user picks a model in onboarding or Settings → Speech. Existing installs keep whatever their
// settings.json already says (the merge only fills ABSENT keys), so nobody's working dictation
// is switched off by an upgrade.
speech: { engine: 'whisper', model: '', language: 'auto', shortcut: 'Cmd+Alt' },
}
export interface SettingsApi {
load(): Promise<Settings>
save(settings: Settings): Promise<void>
}
/** Agent-integration consent status (issue #744). The CHOICE rides `settings.agentIntegrations`;
* this only reports what the host's last reconcile did. */
export interface IntegrationsApi {
status(): Promise<import('./agent-integrations').AgentIntegrationsStatus>
}
/** A downloadable whisper model plus its on-disk status, as returned by `speech.models()`. */
export interface SpeechModelInfo extends WhisperModelInfo {
downloaded: boolean
/** Actual on-disk size in MB, present only when `downloaded`. */
sizeMB?: number
}
export interface SpeechApi {
/** Transcribe a chunk of mono PCM audio (16kHz Float32 samples) to text.
* `language` is a BCP-47-ish hint or 'auto'; defaults to the user's speech settings. */
transcribe(pcm: Float32Array, language?: string): Promise<{ text: string }>
/** List the known whisper models with their download/pro status. */
models(): Promise<SpeechModelInfo[]>
/** Download a whisper model to disk (progress via `onProgress`). */
downloadModel(id: string): Promise<void>
/** Delete a downloaded whisper model. */
deleteModel(id: string): Promise<void>
/** Subscribe to model-download progress (`pct` 0-100). Returns unsubscribe. */
onProgress(cb: (p: { id: string; pct: number }) => void): () => void
/** Ask for microphone permission. Electron: OS-level (macOS TCC prompt); browser: always
* resolves true — the browser's own getUserMedia prompt is not ours to gate. */
micConsent(): Promise<boolean>
/** Open the OS microphone-privacy page (Windows `ms-settings:privacy-microphone`, macOS System
* Settings). Desktop only — ABSENT in the browser bridge (a browser's mic permission lives in
* its own site settings), and the overlay hides its button when absent. Resolves false where
* the OS has no such page. */
openMicSettings?(): Promise<boolean>
}
export interface SshApi {
list(): Promise<import('./ssh').SshServer[]>
save(server: import('./ssh').SshServer): Promise<import('./ssh').SshServer[]>
remove(id: string): Promise<import('./ssh').SshServer[]>
/** Parse `~/.ssh/config` into importable hosts (empty if none). */
importCandidates(): Promise<import('./ssh').ParsedSshHost[]>
}
export type SshProjectStatus = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'error'
/**
* A live SSH project's status, pushed from main. `claudeAutoPermissionMode` rides a `connected`
* event: the remote `claude --version` probe runs AFTER connect (its login shell is slow and must
* not delay the project's terminals), so the answer arrives on its own event once it lands.
* Absent = not probed / nothing new ⇒ the renderer keeps omitting the `auto` flag (fail-open).
*/
export interface SshProjectStatusEvent {
/** Hook-only health update; it does not imply an SSH reconnect or terminal restart. */
hookTunnelVerified?: boolean
projectId: string
status: SshProjectStatus
error?: string
/**
* The ControlMaster socket path, published the MOMENT `ssh -O check` answers — i.e. while the
* status is still `connecting`, before the connect's remote setup chain (hook tunnel + per-agent
* hook installs, `$HOME`, the remote tmux.conf write, the Codex runtime staging) has run.
*
* ADDITIVE, and deliberately not a new status value: `connected` keeps its exact meaning (the
* whole chain finished), and everything hanging off it — git routing, the remote claude probe,
* the tunnel resync, the connection banner — is untouched. This field only lets a terminal whose
* remote tmux session ALREADY EXISTS stop waiting: `new-session -A` then merely attaches, and
* the remote `-f` config and the tmux `-e` pairs are read at session CREATION only. A node whose
* session does not exist (or could not be read) must still wait for `connected`, or it would
* create a session with no hook env and lose its agent-status badges — see
* `PtyApi.remoteSessionConfirmed`.
*
* Never emitted for an ADOPTED live-orphan master: that one can still be torn down and rebuilt
* inside the same connect (the stale reverse-forward cure), which would kill a terminal that had
* already attached over it.
*/
masterControlPath?: string
claudeAutoPermissionMode?: boolean
/** The remote `claude --version` output the probe read, riding the same `connected` event as
* `claudeAutoPermissionMode`. `null` = the probe ran but found no claude (distinguishable from
* "old CLI" in the tab-menu hint); absent = nothing new. */
remoteClaudeVersion?: string | null
/** Does THIS HOST's `codex` accept `--no-daemon` (probed after connect, `codex --help` through
* the login shell)? Keyed by `sshHostKey` because it is a fact about the host's binary, not the
* project. Only `supported: true` puts the flag on a remote Codex launch — see
* shared/agents/codex-daemon.ts. Absent = nothing new. */
remoteCodexNoDaemon?: RemoteCodexNoDaemon
}
/** A host's answer to "does its `codex` accept `--no-daemon`?" — see `SshProjectStatusEvent`. */
export interface RemoteCodexNoDaemon {
hostKey: string
supported: boolean
}
/** main → renderer: this SSH identity file needs its passphrase (the ssh-agent doesn't hold the
* key, or the last answer was wrong). `retry` distinguishes "that passphrase didn't work" from
* a first ask. */
export interface SshPassphraseRequest {
requestId: string
identityFile: string
retry: boolean
/** `user@host` the unlock is for, when main could attribute the prompt to a connection. One key
* can serve several servers, and the prompt can fire from the watchdog long after any connect
* dialog closed. Absent when the asking master could not be identified (adopted orphan). */
target?: string
}
export interface SshProjectApi {
/** Open (or reuse) the ControlMaster for an SSH project; resolves once connected. */
connect(
projectId: string,
server: import('./ssh').SshConnection,
remoteCwd?: string
): Promise<{
controlPath: string
hookEndpointPath?: string
tmuxConfPath?: string
remoteHome?: string
/** Whether the REMOTE host's claude CLI accepts `--permission-mode auto` (probed on connect). */
claudeAutoPermissionMode?: boolean
/** The probed remote `claude --version` output (`null` = probe failed; only on reused conns). */
remoteClaudeVersion?: string | null
/** The host's `--no-daemon` answer, when a probe already ran on this connection (reused conns). */
remoteCodexNoDaemon?: RemoteCodexNoDaemon
}>
/** Tear down the master (remote tmux is unaffected). */
disconnect(projectId: string): Promise<void>
/**
* End the given terminal nodes' REMOTE tmux sessions over the project's live master.
* Authoritative teardown on project delete: works regardless of whether the nodes are
* mounted, and must be awaited BEFORE disconnect (which kills the master). `nodeIds` are
* raw node ids; main maps them to `nt-<id>` session names.
*
* `everySocket` widens the kill to every tmux socket on the host rather than the `node-terminal`
* one an SSH project spawns on (shared with a nodeterm running ON the host). Opt-in for ONE
* caller — the session-memory panel, whose rows are swept off both sockets. Project deletion
* stays narrow: the legacy `nodeterm-rmt` holds only what an older build left behind.
*/
killSessions(
projectId: string,
nodeIds: string[],
opts?: { everySocket?: boolean }
): Promise<void>
/** List remote sub-directories of `path` (default ~). */
listDir(projectId: string, path: string): Promise<{ path: string; dirs: string[] }>
/** Create a remote directory (mkdir -p). Resolves false when not connected or the mkdir fails. */
mkdir(projectId: string, path: string): Promise<boolean>
/**
* Upload a local file to the remote over the project's ControlMaster, into
* `<remoteHome>/.nodeterm/uploads/<token>/<fileName>`. Resolves the ABSOLUTE remote path on
* success, or null on any failure (not connected, unresolved remote home, mkdir/scp failure).
*/
uploadFile(projectId: string, localPath: string, fileName: string): Promise<string | null>
/**
* Pull a remote file (or, with a directory, the whole tree) down to this machine over the
* project's ControlMaster, into the OS Downloads folder unless `destDir` names another one.
* The DESTINATION is built in main (`app.getPath('downloads')` + the remote basename, collision-
* resolved) — the renderer only ever names the remote side, so no renderer string reaches the
* local write path. Never throws: a failure resolves `{ ok: false, error }`.
*/
downloadFile(projectId: string, remotePath: string, destDir?: string): Promise<DownloadResult>
onStatus(cb: (e: SshProjectStatusEvent) => void): () => void
/** The user's answer to a passphrase prompt (null on cancel). */
submitPassphrase(requestId: string, value: string | null): Promise<void>
onPassphraseRequest(cb: (e: SshPassphraseRequest) => void): () => void
/** Main expired a pending passphrase request; close its dialog if it is still showing. */
onPassphraseDismiss(cb: (e: { requestId: string }) => void): () => void
}
/** Outcome of a file download (SSH pull). `localPath` is the absolute path actually written —
* collision resolution may have renamed it (`notes.md` → `notes (2).md`). */
export type DownloadResult =
| { ok: true; localPath: string; dir: boolean }
| { ok: false; error: string }
/** A one-shot HTTP download ticket (Server Edition). `url` is same-origin and carries the token;
* the browser does the transfer natively, so nothing streams through the WS bridge. */
export interface DownloadTicket {
url: string
/** Filename the download will land under (a directory becomes `<name>.tar.gz`). */
name: string
}
/**
* SSH-project Explorer/Editor filesystem API: the same `FsApi` contract scoped to a project,
* proxied over the project's ControlMaster (renderer → `sshFs:*` IPC → main `SshFs`). The renderer
* `sshFs(projectId)` helper closes over `projectId` to expose a plain `FsApi`. Fails open
* ([]/''/false) when the project is not connected.
*/
export interface SshFsApi {
list(projectId: string, path: string): Promise<DirEntry[]>
read(projectId: string, path: string): Promise<string>
readBinary(projectId: string, path: string): Promise<string>
write(projectId: string, path: string, content: string): Promise<boolean>
mkdir(projectId: string, path: string): Promise<boolean>
exists(projectId: string, path: string): Promise<boolean>
/** ⌘K Quick Open index of the project's remoteCwd: root-relative `/`-paths ([] on failure). */
quickOpen(projectId: string, cwd: string): Promise<string[]>
}
export interface GitFileChange {
path: string
/** Single-letter status: M (modified), A (added), D (deleted), R (renamed), U (untracked). */
status: string
added: number
deleted: number
}
export interface GitStatus {
hasRepo: boolean
/** "owner/repo" from the origin remote, else the folder name. */
repoName: string
branch: string
/** Local branch names (for the branch switcher). */
branches: string[]
/** Remote-tracking branch names as `<remote>/<branch>` (HEAD pointers excluded), so the
* switcher can offer branches that exist only on a remote — a plain `git switch <branch>`
* then DWIMs a local tracking branch. Absent in stale caches: read with `?? []`. */
remoteBranches?: string[]
ahead: number
behind: number
/** The repo has at least one remote — which may well not be named `origin` (a fork can have only
* `upstream`). Never read this to decide whether a `git push origin …` can work: use `hasOrigin`. */
hasRemote: boolean
/** A remote literally named `origin` exists — i.e. a hardcoded `push origin <ref>` has a target. */
hasOrigin: boolean
/** The current branch has an upstream tracking ref (i.e. it has been published). */
hasUpstream: boolean
ghAvailable: boolean
ghAuthed: boolean
staged: GitFileChange[]
changes: GitFileChange[]
}
export interface GitResult {
ok: boolean
message: string
/** worktreeRemove() only: the worktree is no longer on disk (registration pruned, or never
* registered), so the caller must clear its binding even when `ok` is false. */
worktreeGone?: boolean
/** Set by publish() when no usable GitHub credential was found, so the UI can
* fall back to an interactive `gh auth login` instead of just showing an error. */
needsAuth?: boolean
}
export interface GitApi {
status(cwd: string): Promise<GitStatus>
init(cwd: string): Promise<GitResult>
/** Clone a repo into parentDir; returns the cloned folder path in message on success. */
clone(parentDir: string, url: string): Promise<GitResult>
/** Abort the in-flight clone, if any (its clone() promise resolves message:'aborted'). */
cloneAbort(): Promise<void>
/** Suggested parent dir for clones: ~/projects if it exists, else the home dir. */
cloneDefaultParent(): Promise<string>
/** Subscribe to live clone progress; returns unsubscribe. */
onCloneProgress(listener: (p: CloneProgress) => void): () => void
/** Commits the staged changes (no implicit add). */
commit(cwd: string, message: string): Promise<GitResult>
push(cwd: string): Promise<GitResult>
pull(cwd: string): Promise<GitResult>
/** Pull then push. */
sync(cwd: string): Promise<GitResult>
publish(cwd: string, name: string, isPrivate: boolean): Promise<GitResult>
stage(cwd: string, paths: string[]): Promise<GitResult>
unstage(cwd: string, paths: string[]): Promise<GitResult>
stageAll(cwd: string): Promise<GitResult>
unstageAll(cwd: string): Promise<GitResult>
/** Unified diff for a file. `staged` selects index vs worktree; untracked shows full file. */
diff(cwd: string, path: string, staged: boolean, untracked: boolean): Promise<string>
/** Discard a file's changes (or delete it if untracked). */
discard(cwd: string, path: string, untracked: boolean): Promise<GitResult>
switchBranch(cwd: string, name: string): Promise<GitResult>
createBranch(cwd: string, name: string): Promise<GitResult>
/** File contents at a git ref ('HEAD', or '' for the index/staged blob). */
showFile(cwd: string, ref: string, path: string): Promise<string>
/** Generate a commit message from the staged diff via a local AI agent CLI. */
generateMessage(cwd: string): Promise<GitResult>
/** Commit history graph for the repo. */
history(
cwd: string,
options?: { limit?: number; baseRef?: string | null }
): Promise<import('./git-history').GitHistoryResult>
/** File-level changes introduced by a commit (oid). */
commitFiles(cwd: string, oid: string): Promise<GitFileChange[]>
/** Remote web URL for a commit sha, or null if it can't be derived. */
remoteCommitUrl(cwd: string, sha: string): Promise<string | null>
/** Merge a branch into the current branch. */
merge(cwd: string, ref: string): Promise<GitResult>
/** Rebase the current branch onto another. */
rebase(cwd: string, onto: string): Promise<GitResult>
/** Delete a branch (force = -D, for unmerged). */
deleteBranch(cwd: string, name: string, force: boolean): Promise<GitResult>
/** Rename the current branch. */
renameBranch(cwd: string, newName: string): Promise<GitResult>
/** Fetch all remotes and prune. */
fetch(cwd: string): Promise<GitResult>
/** Push with --force-with-lease. */
forcePush(cwd: string): Promise<GitResult>
/** Stash uncommitted changes (incl. untracked). */
stashPush(cwd: string): Promise<GitResult>
/** Pop the latest stash. */
stashPop(cwd: string): Promise<GitResult>
/** Revert a commit (--no-edit). */
revert(cwd: string, oid: string): Promise<GitResult>
/** Create + switch to a new branch at a commit. */
branchAt(cwd: string, name: string, oid: string): Promise<GitResult>
/** Checkout a commit (detached HEAD). */
checkoutCommit(cwd: string, oid: string): Promise<GitResult>
repoRoot(cwd: string): Promise<string | null>
/** `{ ok: false, entries: [] }` when git itself could not be read — which is NOT the same fact as
* "this repo has no worktrees", and no caller may treat it as one (see worktree-ops). */
worktreeList(repoPath: string): Promise<import('./worktree').WorktreeListResult>
worktreeAdd(repoPath: string, wtPath: string, branch: string, baseRef: string, isNew: boolean): Promise<GitResult>
/** `push`: also publish `baseRef` to origin after a successful merge (only if a remote exists).
* Opt-in — a merge must never publish to a shared remote the user was not told about. */
worktreeMerge(repoPath: string, branch: string, baseRef: string, push?: boolean): Promise<GitResult>
/** `pruneOnly`: clean up git's registration only — never delete a directory. Used to prune a
* stale binding whose worktree was already deleted outside the app. */
worktreeRemove(repoPath: string, wtPath: string, deleteBranch: boolean, pruneOnly?: boolean): Promise<GitResult>
/** Scope remote git routing to the active project: pass its id to route git over that SSH
* project's master, or null for a local project so all git ops run locally. */
setActiveRemote(projectId: string | null): Promise<void>
}
export interface UpdateInfo {
version: string
notes?: string
/**
* The update cannot self-install and must be downloaded manually (Linux .deb/.rpm: no
* APPIMAGE env, so electron-updater's quitAndInstall would throw). The card shows a
* download link instead of the download-progress/restart flow. Absent/false = self-installs.
*/
manual?: boolean
}
export interface UpdatePolicy {
/** Minimum supported version for the device's channel (or null when no policy). */
minSupported: string | null
/** True when the running version is below the minimum supported version. */
mandatory: boolean
/** Optional release highlights (markdown) the feed carries for `latestVersion`. */
notes?: string
/** The version `notes` describe. Notes are shown only on a card for this exact version. */
latestVersion?: string
}
/** Restart-to-update was accepted: `preparing` = waiting for the OS updater to stage it (macOS),
* `restarting` = the install is starting now. */
export interface UpdateInstalling {
phase: 'preparing' | 'restarting'
version: string | null
}
export interface UpdateProgress {
/** 0–100. */
percent: number
transferred: number
total: number
bytesPerSecond: number
}
export interface UpdateApi {
/** A newer version was found and is downloading. Returns unsubscribe. */
onAvailable(listener: (info: UpdateInfo) => void): () => void
/** The update finished downloading and is ready to install. Returns unsubscribe. */
onDownloaded(listener: (info: UpdateInfo) => void): () => void
/** Download progress ticks while an update downloads. Returns unsubscribe. */
onProgress(listener: (p: UpdateProgress) => void): () => void
/** An updater error occurred (drives the card's error state). Returns unsubscribe. */
onError(listener: (message: string) => void): () => void
/** No newer version is available (also the dev no-op reply to check()). Returns unsubscribe. */
onNotAvailable(listener: () => void): () => void
/**
* This build has no update channel and can never learn whether a newer version exists
* (issue #814). Deliberately separate from `onNotAvailable`: "we looked and you are current"
* and "we cannot look" are different facts with different remedies. Returns unsubscribe.
*/
onNoChannel(listener: () => void): () => void
/** Restart-to-update was accepted and is preparing / restarting. Returns unsubscribe. */
onInstalling(listener: (s: UpdateInstalling) => void): () => void
/**
* The update main already staged this run (announced once), or null. A renderer that loads after
* that one-time `onDownloaded` — ⌘R, a window recreated after a crash — asks on mount.
*/
getStaged(): Promise<{ version: string; notes: string } | null>
/** Trigger a manual update check. */
check(): void
/** The running app version. */
getVersion(): Promise<string>
/** The channel's mandatory-update policy for the running version (from /v1/check). */
getPolicy(): Promise<UpdatePolicy>
/** Quit and install the staged update. */
restart(): void
/** Prepare-for-update (Windows session host, issue #829): what the running host holds. Never
* launches a host. Answers `unsupported` off Windows and in the Server Edition. */
prepareInspect(): Promise<import('./update-prep').UpdatePrepInspection>
/** Prepare-for-update: ask the host to end every session and exit, and confirm it did. */
prepareShutdownHost(): Promise<import('./update-prep').UpdatePrepShutdown>
/** Prepare-for-update: quit the app (no quit confirmation) once the host is gone. */
prepareQuit(): void
}
/** A single news/announcement item, fetched from the remote announcements feed. */
export interface Announcement {
/** Stable unique id; used to remember which items the user has dismissed. */
id: string
title: string
body?: string
/** Optional "Learn more" link (opened in the system browser). */
url?: string
/** Visual emphasis; defaults to 'info'. */
level?: 'info' | 'success' | 'warning'
}
/** A one-time popup from the same feed (`popups` in the check reply): shown once per install. */
export interface PopupAnnouncement extends Announcement {
/** The button's label; absent = "Learn more" for a link, "Upgrade to Pro" for the checkout. */
ctaLabel?: string
/** 'upgrade' = the button starts the app's own Pro checkout instead of opening `url`. */
action?: 'upgrade'
/** The SHA-256 naming its picture, fetched with `AnnouncementsApi.popupImage`. */
image?: string
}
export interface AnnouncementsApi {
/** Fetch the announcements feed from the website (returns [] on any failure). */
fetch(): Promise<Announcement[]>
/** The feed's one-time popups ([] on any failure, and on the Server Edition, which does not read
* the feed). Which of them were already shown is the renderer's record, not the feed's. */
popups(): Promise<PopupAnnouncement[]>
/** A popup's picture as a `data:` URL, or null when it cannot be had. */
popupImage(sha256: string): Promise<string | null>
}
export interface NotifyPayload {
title: string
body: string
/** Node to focus/center when the notification is clicked. */
nodeId: string
/** Show even when the window is focused (used to trigger the macOS permission prompt). */
force?: boolean
}
/** A chunk of a subagent's live transcript, streamed while it works. */
export interface SubagentActivity {
toolUseId: string
chunk: string
}
/** One linked node, as the context-link CLI sees it. */
export interface ContextLinkInfo {
id: string
title: string
/** The linked node's working dir — lets the CLI resolve a transcript when the path isn't known yet. */
cwd?: string
/** Set when the linked node is a sticky note: its current text. Note entries have no transcript/terminal. */
note?: string
/** The linked node's agent CLI ('claude' | 'codex' | 'gemini') — selects the CLI transcript parser. */
agentId?: string
/** Latest known provider session id — lets main resolve the transcript via the per-agent locators. */
sessionId?: string
/** Managed Claude account of the linked node — scopes the claude locator fallback. */
accountId?: string
}
/** Map of node id → the nodes it is context-linked to. Sent to main so it can write link files. */
export type ContextLinkMap = Record<string, ContextLinkInfo[]>
export interface ContextLinkApi {
/** Push the current link map to main; main rewrites the per-node link files. */
setLinks(map: ContextLinkMap): Promise<void>
/** Static facts the renderer needs to compose link messages: the CLI shim's absolute path, and
* the `process.platform` of the core that wrote it (absent from an older core ⇒ treat as POSIX).
* On `win32` a non-claude agent is told to run the `.cmd` launcher beside the shim. */
info(): Promise<{ shimPath: string; platform?: string }>
}
/** One usage window (5h session or 7d weekly) as shown in the indicator. */
export interface ClaudeUsageWindow {
/** 0–100; remaining quota. Drives the bar fill (shows "remaining"). */
leftPercent: number
/** Unix ms when this window resets, or null if unknown. */
resetsAt: number | null
}
/**
* One usage window, normalized across providers. Claude's endpoint hands these over directly
* as its open-ended `limits[]` array — a per-model quota (Fable's weekly cap, say) is an
* ordinary entry whose model name rides in `scopeLabel`, so a new model needs no new field.
* Other providers (Codex's primary/secondary windows, …) are mapped into the same shape.
*
* Percentages are portions USED, which is the providers' own convention; the UI inverts for
* display where it shows "left".
*/
export interface UsageLimit {
/** Provider-assigned kind: 'session' | 'weekly_all' | 'weekly_scoped' | future values. */
kind: string
/** Coarse grouping ('session' | 'weekly'), or null when the provider omits it. */
group: string | null
/** 0–100, portion consumed. */
usedPercent: number
/**
* The provider's own severity call ('normal' | 'warning' | 'critical' | …), or **null when
* the provider does not report one** — which is the common case (only Claude does today).
* Null means "derive from the percentage locally"; it must NOT be defaulted to 'normal',
* or every provider without severity would paint a permanently green bar.
*/
severity: string | null
resetsAt: number | null
/**
* The bucket's real duration in minutes, when the provider reports it (Codex sends
* `limit_window_seconds`), else null. Providers can and do vary this per plan, so labelling
* a window "5h" from its `kind` alone can be a lie.
*/
windowMinutes: number | null
/** Model display name for a scoped limit (e.g. 'Fable'), else null. */
scopeLabel: string | null
/** The provider says this window is the one currently gating the account. */
isActive: boolean
}
/**
* One provider's usage snapshot. `ClaudeUsage` below is the Claude-shaped superset kept for the
* existing pill; new providers use this leaner shape (they have no per-account story yet).
*/
/** Safe billing diagnostics: never include URLs, response bodies, or exception messages. */
export type UsageDiagnostic = {
view: 'credits' | 'default'
} & ({ reason: 'http'; httpStatus: number } | {
reason: 'timeout' | 'network' | 'invalid-response'
})
export interface ProviderUsage {
/** Agent id the limits belong to: 'claude' | 'codex' | … */
provider: string
/** Failed billing views, including failures recovered by a successful fallback. */
diagnostics?: UsageDiagnostic[]
limits: UsageLimit[]
/** Signed-in identity, when the provider exposes one cheaply (email / account label). */
account: string | null
/**
* The managed account this row's numbers belong to, when the provider is account-scoped (Codex
* manages N homes on one machine). `undefined` is the un-owned system row — an account that
* cannot be proven un-owned is never labelled un-owned. Rows are keyed by this so one account's
* usage can never collapse into or be attributed to another (S6 §4.3, no mixing / fail-closed).
*/
accountId?: string
updatedAt: number
/**
* 'unavailable' = not signed in / no subscription to report → hide this provider entirely.
* 'fetching' = request in flight. 'ok' = limits present. 'error' = the fetch failed — and when
* `limits` is non-empty alongside it, those are the LAST GOOD numbers the service kept
* (`holdLastGoodProvider`), still stamped with their own `updatedAt`.
*/
status: 'unavailable' | 'fetching' | 'ok' | 'error'
/** The latest read was refused with HTTP 429 (Codex today, issue #1168). Absent = not rate
* limited, or not known to be. */
rateLimited?: boolean
}
/** Host memory snapshot in MB. `null` from any reader means "could not read" — never "zero".
* Shared because it crosses the wire for the system-resource pill; core reads it, the renderer
* renders it. */
export interface MemInfo {
availableMb: number
totalMb: number
/**
* Swap, and the kernel's own stall accounting. **Optional on purpose, and their absence is the
* darwin contract.**
*
* `availableMb` alone cannot see a host that has already spent its overflow reserve: a machine
* with 10.5 GB "available" and 84% of its swap consumed reads as healthy under a 10%-of-RAM
* watermark, which is exactly the state the 2026-08-03 swap-thrash lockup was in. These fields
* carry the two host-wide facts that DO see it.
*
* Only the Linux reader populates them (`/proc/meminfo` for swap, `/proc/pressure/memory` for
* PSI — both world-readable, measured on a `hidepid=invisible` host where a non-root uid can read
* neither another user's processes nor their tmux socket). `parseVmStat` leaves every one of them
* undefined, so no macOS reading can ever satisfy a swap or PSI term: darwin cannot start firing
* on a signal that was never measured there.
*
* A consumer must treat `undefined` as NO SIGNAL, never as zero — a zero here reads as
* "swap totally exhausted" / "no stall", and both are claims the reader has not earned.
*/
/** Total swap in MB; `0` legitimately means "this host has no swap configured". */
swapTotalMb?: number
/** Free swap in MB. */
swapFreeMb?: number
/** `/proc/pressure/memory` `some avg60` — % of the last minute at least one task stalled on memory. */
psiSomeAvg60?: number
/** `/proc/pressure/memory` `full avg60` — % of the last minute EVERY task was stalled. Thrash. */
psiFullAvg60?: number
/**
* What the RAM pill SHOWS beyond used/total. **Display only: never an input to the reaper, the
* memory-pressure monitor or a reclaim lever**. It is a separate object,
* rather than more top-level fields, so that rule is structural: `hostUnderMemoryPressure` reads
* `swapTotalMb`/`swapFreeMb`, and filling THOSE on darwin would fire the reaper's swap term all
* day on a Mac that can keep most of its swap in use for hours (16% swap free on the measured
* one). Absent field = not measured, never zero.
*/
display?: MemDisplay
}
/** See `MemInfo.display`. Every field is optional and independent: one failed read omits one fact. */
export interface MemDisplay {
/** Swap in use, MB. darwin: `sysctl vm.swapusage`; Linux: `SwapTotal - SwapFree`. */
swapUsedMb?: number
/** Swap currently provisioned, MB. On darwin this GROWS on demand (dynamic swap files), so it is
* a size, not a ceiling. */
swapTotalMb?: number
/** The kernel's own verdict (`kern.memorystatus_vm_pressure_level`: 1/2/4), darwin only — the
* colour Activity Monitor's pressure graph shows. Linux has no equivalent level and PSI has no
* measured threshold here, so it is never invented there. */
pressureLevel?: 'normal' | 'warn' | 'critical'
}
/** One nt- session's memory, as the panel renders it. */
export interface SessionMemoryRow {
/** tmux session name, `nt-<nodeId>`. */
session: string
/** The canvas node id — the session name minus the `nt-` prefix. */
nodeId: string
panePid: number
/** The pane's own process. */
selfMb: number
/** Everything below it (MCP servers, headless browsers, …). */
childrenMb: number
childCount: number
/** The whole tree: the pane's own process plus everything below it. */
totalMb: number
/** The biggest single process in the tree, pane process included. Part of `totalMb`. */
largestMb: number
/** Its name, cleaned for display (`processLabel`). Absent when the table carried no name. */
largestName?: string
/** `#{pane_current_command}` — the agent/shell label. */
command: string
}
/**
* What a sweep's numbers are, because the three measures answer differently for the same process:
* on a Mac an idle MCP server measured 242 MB of footprint and 4 MB of rss (most of it compressed).
* - `footprint`: macOS phys_footprint, Activity Monitor's "Memory" column;
* - `rss`: resident memory: Linux, and every SSH host, which is read with `ps` whatever it runs;
* - `working-set`: Windows, Task Manager's "Working set" column.
*/
export type SessionMemoryMetric = 'footprint' | 'rss' | 'working-set'
/**
* `ok: false` means the sweep could not run (no tmux binary, unreadable process table). It is NOT
* the same as an empty `rows` with `ok: true`, which means "we looked and there are no sessions".
* Collapsing the two would make the panel report "nothing is using memory" at exactly the moment
* it failed to measure.
*/
export interface SessionMemoryReport {
ok: boolean
rows: SessionMemoryRow[]
mem: MemInfo | null
/** The measure `rows` are in. Absent when the sweep read no process table. */
metric?: SessionMemoryMetric
/**
* Live nodeterm sessions on this machine that the sweep could NOT measure — today, Zellij-backed
* ones (the sweep reads tmux). Absent/0 = none. `null` = could not tell. Local scope only. The
* panel must never say "no sessions are running" while this is non-zero or unknown.
*/
unmeasured?: number | null
/** Which backend the `unmeasured` sessions belong to, for the panel's sentence. Absent = Zellij
* (the original and, off Windows, only case); `'session-host'` = a running session host older
* than this app, which names its sessions but cannot describe their processes. */
unmeasuredBackend?: 'session-host'
/**
* The Windows session host's OWN cost, which belongs to no session row (CLAUDE.md, Session
* memory): its process (every session's headless emulator, node-pty's per-session conout worker
* thread) and its non-shell children (one conhost/OpenConsole per ConPTY — they are the host's
* children, siblings of the shell, so no row's tree reaches them). Absent = no session host, or it
* could not be measured: never a fake zero. The tmux leg never sets it.
*/
host?: SessionHostOverhead
/**
* nodeterm's OWN processes (main, renderer(s), GPU, helpers) — the "nodeterm itself" group.
* Display only, LOCAL scope only. Absent = this shell cannot enumerate its processes (Server
* Edition, a relay stub, every SSH scope): not available. `ok:false` = it tried and could not
* measure. Never part of the session total — see AppSelfMemory.
*/
app?: AppSelfMemory
}
/** Which of nodeterm's own processes a group is (Electron `ProcessMetric.type`, folded). */
export type AppProcessKind = 'main' | 'renderer' | 'gpu' | 'helper'
/** One kind of nodeterm process, summed over every pid of that kind (the HUD is a 2nd renderer). */
export interface AppSelfGroup {
kind: AppProcessKind
count: number
/** Summed memory in MB, in the SAME accounting as the session rows (darwin: phys_footprint from
* the panel's own `top` read; Linux: VmRSS; Windows: working set). Absent when any pid of the
* group was missing from the table: a partial sum would understate, which is a wrong number. */
mb?: number
/** Summed CPU time since each process started, seconds (Electron `cumulativeCPUUsage`). Absent =
* not reported. A lifetime total, deliberately not a percentage. */
cpuSeconds?: number
}
/**
* The GPU helper's real footprint (1557-1845 MB live, mostly IOSurfaces)
* was invisible because `ps` RSS says 96-153 MB and nothing attributed it. `ok:false` (no groups)
* when the process list or the table could not be read, or no pid of ours was in it.
*/
export interface AppSelfMemory {
ok: boolean
groups: AppSelfGroup[]
/** Sum of every group, only when every group was measured. */
totalMb?: number
}
/** See `SessionMemoryReport.host`. All MB figures are MEASURED working sets, not estimates. */
export interface SessionHostOverhead {
pid: number
/** The session-host process itself. */
selfMb: number
/** Its non-shell children (conhost / OpenConsole, plus anything under them — including the
* pane-probe PowerShell worker while it is warm, which is the host's child and its cost). */
consoleMb: number
/** Direct children recognised as a console host — "N consoles" in the panel. */
consoleCount: number
totalMb: number
}
/**
* What the renderer asks for: the machine a project runs ON, never "this machine" implicitly.
* `remote: true` is the renderer saying it already knows (from `usageScope`) that the active
* project is an SSH one; the shell's own `isRemoteProject` is a second, independent confirmation,
* so a project the shell has not (yet) registered as connected still cannot be answered with the
* local machine's sessions.
*/
export interface SessionMemoryQuery {
projectId?: string
remote?: boolean
}
/**
* Per-session memory for the machine the ACTIVE PROJECT runs on — the same scoping rule the usage
* indicator follows (`usageScope`), for the same reason: a number is meaningless without the
* machine it describes.
*
* Both members are on-demand only, never polled: a remote answer costs an ssh exec plus a `ps` of
* somebody else's whole process table. Pass the query through verbatim — `remote` is one of the two
* independent sources the service uses to decide which host answers.
*/
export interface SessionMemoryApi {
/** Per-session breakdown for the scoped machine. `ok:false` = the sweep could not run, which is
* NOT an empty `rows` with `ok:true` ("we looked, there are none"). */
read(q?: SessionMemoryQuery): Promise<SessionMemoryReport>
/** The scoped machine's RAM. `null` = could not read (never "zero"). */
host(q?: SessionMemoryQuery): Promise<MemInfo | null>
}
/** Best-effort active organization from this account's Claude identity file. */
export interface ClaudeUsageOrganization {
name: string
uuid?: string
type?: string
rateLimitTier?: string
}
/** Claude Code subscription usage snapshot for the bottom-left indicator. */
export interface ClaudeUsage {
/**
* Every limit the plan exposes, including per-model scoped ones. Prefer this over the
* `session`/`weekly` fields below, which are kept only so older callers keep compiling.
*/
limits: UsageLimit[]
session: ClaudeUsageWindow | null
weekly: ClaudeUsageWindow | null
/** Signed-in account email, read-only and best-effort (null if unknown). */
email: string | null
/** Active organization, absent when its metadata is unavailable. */
organization?: ClaudeUsageOrganization
/** Unix ms when this snapshot was produced. */
updatedAt: number
/**
* 'unavailable' = no OAuth subscription token (API-key billing / logged out) → hide pill.
* 'fetching' = request in flight. 'ok' = windows present. 'error' = fetch failed — and when
* `limits` is non-empty alongside it, those are the LAST GOOD numbers the service kept
* (`holdLastGood`), still stamped with their own `updatedAt`.
*/
status: 'unavailable' | 'fetching' | 'ok' | 'error'
/**
* The latest read was refused with HTTP 429. The usage endpoint's request budget is also
* spent by every Claude CLI using the same login (the CLI reads this endpoint itself), so a
* host running dozens of sessions can exhaust it without us. Absent = not rate limited (or
* not known to be).
*/
rateLimited?: boolean
}
/**
* One REMOTE (SSH host) Claude or Codex identity's usage, read on that host over the project's
* ControlMaster. Separate from the local per-account rows because the identity is only
* meaningful together with the host it lives on — the same email can be logged in on two
* machines with two different quotas in flight.
*/
interface RemoteAccountUsageBase {
/** `user@host` of the connection the numbers came from. */
hostKey: string
/** Managed remote account id, or null for that provider's system identity on the host. */
accountId: string | null
/** Display label: the managed account's label, else the host key. */
label: string
}
export type RemoteAccountUsage = RemoteAccountUsageBase & (
| { provider?: 'claude'; usage: ClaudeUsage }
| { provider: 'codex'; usage: ProviderUsage }
)
/** What the usage indicator wants from the remote hosts right now. */
export interface RemoteUsageQuery {
/** Read only this `user@host` — the machine the active project runs on. Omitted = every
* connected host, which no scoped UI asks for but keeps the channel general. */
hostKey?: string
/** Bypass the cache debounce (the ⟳ button). */
force?: boolean
}
export interface UsageApi {
/** Returns the latest snapshot (cached if fresh, else a fresh fetch). Optional account id
* targets a managed account; omitted = the system account (also the pushed one). */
fetch(accountId?: string): Promise<ClaudeUsage>
/** Forces a fresh fetch, bypassing the focus debounce. Optional account id as `fetch`. */
refresh(accountId?: string): Promise<ClaudeUsage>
/** Snapshots for every non-Claude provider (codex, …). Fetched on demand, not polled — pass
* `force` to bypass the cache debounce. Providers that aren't signed in come back
* 'unavailable' rather than being omitted, so the caller can tell "off" from "broken". */
providers(force?: boolean): Promise<ProviderUsage[]>
/** Usage for the Claude identities on connected SSH hosts, read on those hosts (the credential
* never crosses back). On-demand like `providers`, not polled — each row costs an ssh
* round-trip, which is also why the caller should name the ONE host it is showing. Empty when
* nothing is connected, or on a shell with no SSH projects (Server Edition), so callers need
* no capability check. */
remote(query?: RemoteUsageQuery): Promise<RemoteAccountUsage[]>
/** Store (or, with an empty string, clear) a provider's browser cookie. Resolves to whether one
* is now stored. Write-only by design — nothing reads the value back across this boundary. */
setProviderCookie(provider: string, cookie: string): Promise<boolean>
/** Which cookie-based providers have one stored, so the UI shows state without the secret. */
cookieProviders(): Promise<Record<string, boolean>>
/** Fires whenever main pushes a new snapshot (poll/refresh). Returns unsubscribe. */
onUpdate(listener: (usage: ClaudeUsage) => void): () => void
}
/** A Claude session's context-window fill, pushed per sessionId from the transcript tailer. */
export interface ContextWindowUsage {
/** Remote Codex observations are node-scoped; equal thread ids on different hosts never mix. */
nodeId?: string
/** Invalidates this node/session observation after its remote scope changes or disappears. */
cleared?: true
/** Missing on older hosts; only session-env is an observed Claude configuration. */
windowSource?: 'session-env' | 'transcript' | 'estimate'
sessionId: string
/** input + cache_read + cache_creation tokens of the latest assistant message. */
usedTokens: number
/** Model context window (200k default, 1M for 1m-context models). */
windowTokens: number
/** 0–100 fullness. */
usedPercent: number
/** Model id from the transcript, or null if not seen yet. */
model: string | null
/**
* Reasoning effort of the latest request, as Claude Code records it on the transcript's assistant
* record (`low`/`medium`/`high`/`xhigh`/`max` on 2.1.283). Absent = not recorded: another agent,
* an older host or CLI, or a model that takes no effort. Shown by the ⌘M composer's toolbar.
*/
effort?: string
updatedAt: number
}
export interface ContextApi {
/** Fires whenever a session's context fill changes. Returns unsubscribe. */
onUpdate(listener: (usage: ContextWindowUsage) => void): () => void
/**
* Fires when a Claude session's transcript records Remote Control (`/remote-control`) connecting
* or disconnecting. Fed by the same transcript tails as `onUpdate`. Returns unsubscribe.
*/
onRemoteControl(listener: (update: { nodeId: string; sessionId: string; on: boolean }) => void): () => void
/**
* Ask the core to start (or refresh) tracking a session's transcript so the meter populates
* without waiting for a live hook event — e.g. on node mount after an app restart, when
* the continuing session is idle. `cwd` is a transcript-path fallback only.
* `accountId` scopes resolution to a managed Claude account's transcript root (default `~/.claude`).
*
* `nodeId` and `agentId` are what make this work for anything but a LOCAL CLAUDE node, and both
* are load-bearing rather than informational (see `core/context-ensure.ts`):
* - `nodeId` is the only way to learn that this session runs on an SSH project's HOST, whose
* transcript no local resolver can see. Without it a remote node's meter stayed blank until
* its next turn, every app restart.
* - `agentId` routes the resolve to THAT agent's own locator and tail. Claude's resolver falls
* back to the newest claude transcript for the cwd, so resolving a codex/gemini session through
* it would meter a stranger's conversation. Both omitted ⇒ the legacy local-claude behaviour.
*/
ensure(
sessionId: string,
cwd?: string,
accountId?: string,
nodeId?: string,
agentId?: string
): void
}
/**
* Canvas sync: node mutations travel between the attached clients (an Electron renderer, a
* Server-Edition browser tab) so they converge on one node set — instead of each holding its own
* canvas until someone's whole-file `workspace.save` overwrites the other's edits.
*/
export interface CanvasApi {
/**
* Publish one local node mutation for `projectId` (a project IS a canvas — a mutation is only
* ever applied to the canvas it was made on). Fire-and-forget; the reflector fans it out to every
* OTHER attached client and never echoes it back to the sender.
*/
mutate(projectId: string, mutation: CanvasMutation): void
/** Fires with each PEER's mutation (project id + mutation). Returns unsubscribe. */
onMutation(listener: (projectId: string, mutation: CanvasMutation) => void): () => void
}
/**
* Which of this core's projects a canvas authority governs (the Server Edition hosting a team,
* docs/hosted-team-relay.md). The authority writes a governed project's content only from the ops it
* hears, so a client must publish its canvas ops for such a project even when nobody else is
* attached — the solo gate is overridden for it. The desktop runs no authority and governs nothing.
*/
export interface CanvasAuthorityApi {
/** true = this core may govern projects, and which ones is known only once `governed()` answers:
* until then a client publishes for EVERY project on it (the Server Edition). false = known in
* advance, so nothing is assumed (the desktop and a Team Access tab govern nothing; a hosted
* relay tab answers from its own bindings). */
readonly assumeAllUntilAnswered: boolean
/** The governed project ids right now. Never rejects: "unknown" is the empty list. */
governed(): Promise<string[]>
/** Fires with the NEW governed set whenever it changes (a share or unshare). Returns unsubscribe. */
onChanged(listener: (ids: string[]) => void): () => void
}
/** One searchable line extracted from a Claude session transcript. */
export interface TranscriptLine {
role: 'user' | 'assistant' | 'tool'
text: string
}
/** One ordered piece of a chat message: prose, or a tool call with an optional result.
* `summary` (present only on live-turn tools folded into history) carries the diff-preview
* metadata so committed tool cards keep the same summary/diff-click treatment as live ones. */
export type ChatPart =
| { kind: 'text'; text: string }
| {
kind: 'thinking'
text: string
/**
* How long the model thought, in ms — this record's timestamp minus that of the newest `user`
* record before it (the prompt, tool_result or meta line the request answered). Present only on
* the opt-in `thinking` read, only when both stamps exist and the gap is ≥ 0. Measured 2026-11-02
* on CLI 2.1.275–2.1.316: a thinking record is written when the thinking ENDS, and the record
* after it is a tool call whose write time scales with its input, so the gap to the NEXT record
* is not thinking time; nor is the gap to the record right BEFORE it, which is an empty
* encrypted thinking record of the same message written ~10 ms earlier (1,018 of 1,037).
* A paged read sees only its own window, so a thinking record with no `user` record before it
* in that window (the start of an older page) carries no `ms`.
*/
ms?: number
}
| {
/**
* An image the user attached to a prompt (a pasted screenshot): `data` is the base64 payload,
* drawn as `data:<mediaType>;base64,<data>`. Present only on the opt-in `rich` read
* (`ChatParseOptions.rich`), and only for a base64 source whose `mediaType` is in
* `CHAT_IMAGE_TYPES` (core/transcript-reader.ts) — never `image/svg+xml`. An image a tool
* returned (inside a `tool_result`) is tool output and never becomes one.
*/
kind: 'image'
mediaType: string
data: string
}
| {
/**
* A message from an agent team's teammate (core/chat-teammate.ts): Claude Code records it in the
* lead's transcript as a user record, but nobody typed it. Present only on the opt-in `rich`
* read; without it the record is one `Agent message` tool part. `text` = a plain message's
* markdown body; `idle` = the teammate reporting that its turn ended (then `text` is absent).
* `color` is the teammate's TUI color name, as recorded (untrusted: map it, never use it as CSS).
*/
kind: 'teammate'
from: string
color?: string
summary?: string
unverified?: boolean
text?: string
idle?: ChatTeammateIdle
}
| {
/**
* The user interrupted the turn here (Esc, or Ctrl+C once): one of Claude Code's fixed marker
* records (`CLAUDE_INTERRUPT_MARKERS`), which it saves as a USER record but which the user did
* not type. Present only on the opt-in `rich` read; without it the marker stays a user text
* part, as before. The renderer draws Claude's own TUI line for it.
*/
kind: 'interrupt'
}
| {
kind: 'tool'
name: string
arg: string
result?: string
summary?: ChatToolSummary
/** Markdown worth reading in full (an `ExitPlanMode` plan, an `AskUserQuestion` question and
* its options, and on the opt-in `rich` read a `TodoWrite` checklist — `core/chat-tool-body.ts`).
* Present = the renderer shows an expanded card instead of the collapsed chip (a superseded
* todo list excepted: `lib/chatTodo.ts`). Capped at 64K characters. */
body?: string
/** `AskUserQuestion` only: the questions read for the answer controls (`readQuestions`) —
* the SAME reader the held request's texts come from, so a surface can match the card to the
* held ticket. Absent = unreadable input = the card stays read-only. */
questions?: ChatQuestion[]
/** `Edit` / `Write` only, on the opt-in `rich` read (`ChatParseOptions.rich`): the change the
* call asked for, read from its INPUT — never from the result — so the renderer can draw it as
* a diff. Absent = any other tool, an unreadable input, or a read without `rich`. */
diff?: ChatToolDiff
/** The transcript's `tool_use` id. Set only by a PAGED read (`ChatTranscriptResult.olderCursor`
* present): a result carried across a page boundary (`unmatchedResults`) is attached by it. */
id?: string
}
/** An `idle_notification` from a teammate (`ChatPart` teammate `idle`). Every field is optional:
* the notification names only what the teammate reported. */
export interface ChatTeammateIdle {
reason?: 'available' | 'interrupted' | 'failed'
/** The teammate's last direct message, one line. */
summary?: string
failureReason?: string
taskId?: string
/** The teammate's report, markdown, capped. */
result?: string
}
/**
* The change an `Edit` / `Write` tool call asked for (`ChatPart` tool `diff`). Edit's
* `{file_path, old_string, new_string}` maps to `{filePath, oldText, newText}`; Write's
* `{file_path, content}` to `{filePath, oldText: '', newText: content}`. An empty `newText` on an
* Edit is a deletion. Each text is capped at a tool body's length (`capText`, core/chat-tool-body.ts:
* 64K characters, then `TOOL_BODY_TRUNCATED`, with no markdown fence repair — it is file content).
*/
export interface ChatToolDiff {
filePath: string
oldText: string
newText: string
}
/** A structured chat message reconstructed from a Claude session transcript. */
export interface ChatMessage {
role: 'user' | 'assistant'
parts: ChatPart[]
/**
* Stable identity for list rendering: the absolute byte offset of the transcript line this
* message came from. Set only by a PAGED claude read — an absolute offset does not change when
* an older page is prepended or the file grows, so a prepend does not re-key the list. Absent on
* the legacy read and on grok (whose reader does not page).
*/
key?: number
/**
* When the transcript line was written (epoch ms, from claude's ISO `timestamp`). Set on BOTH
* read paths; absent when the line states none (grok, older records). The ⌘M thread shows it as a
* relative time under an assistant turn and a clock time under a user message, and starts a day
* divider at each local day's first stamped message.
*/
at?: number
}
/** A `tool_result` whose `tool_use` was not in the same page (it lives in an OLDER one). */
export interface ChatCarriedToolResult {
/** The `tool_use_id` — matches `ChatPart.id` of a tool part in an older page. */
id: string
result: string
}
/** Edit/Write tool summary for diff-preview cards. */
export interface ChatToolSummary {
filePath?: string
added?: number
removed?: number
}
/**
* Result of a chat transcript read. `found` is the whole point of the wrapper: an empty
* `messages` means two very different things — the session exists and nobody has said anything
* yet (`found: true`), or no transcript could be resolved at all (`found: false`, e.g. Claude's
* 30-day cleanup removed it, or the id belongs to another machine). The ⌘M panel rendered both
* as "No conversation yet.", which is what made a resolution failure look like an empty session.
*/
export interface ChatTranscriptResult {
messages: ChatMessage[]
found: boolean
/**
* PAGED reads only (absent on the legacy unpaged read, which is unchanged byte for byte). The
* byte offset where this window's first complete line starts — pass it back as `page.before` to
* read the next OLDER window. `null` = this window reached the start of the file, or the reader
* does not page (grok).
*
* `found: false` on a read WITH `page.before` set is a FAILED OLDER-PAGE load (the host blipped,
* the file became unreadable), NOT a missing transcript: the caller keeps what it rendered and
* offers a retry. Only the first (tail) read's `found: false` means "no transcript".
*/
olderCursor?: number | null
/**
* PAGED reads only. Tool results in this window whose `tool_use` is NOT in it: the newer page is
* read first, so its results precede their tools. Hold them and attach each to the tool part with
* the same `id` when an older page arrives. Always `[]` from a reader that does not page.
*/
unmatchedResults?: ChatCarriedToolResult[]
/**
* PAGED reads only: the newest assistant record's model in the returned window — claude's
* `message.model` (`<synthetic>` error lines skipped), grok's `model_id`. Absent when the window
* has none, and on the legacy read.
*/
model?: string
/** PAGED reads only: that same record's effort — claude's top-level `effort`, grok's
* `reasoning_effort`. Never carried forward from an older record. */
effort?: string
/** PAGED reads only, with `found: false`: the transcript could not be READ (a remote host that did
* not answer, a growth re-read that failed, a remote node with no reachable master) — as opposed
* to "no transcript exists". Absent on every other result. */
unreadable?: true
}
/**
* Three answers to "is there a transcript for this session id?", because two are not enough.
*
* `absent` is a POSITIVE finding — we read the place it would be and it is not there. `unknown`
* is "we could not look": an unreadable root, a downed ControlMaster, a surface with no reader,
* an id we would not put on a command line anyway. The only consumer that acts on a negative is
* cold restore (it launches the agent bare instead of resuming a dead id), and for it the two
* must never collapse: dropping a resume on `unknown` would throw away a live conversation
* because an ssh call blipped.
*/
export type TranscriptPresence = 'present' | 'absent' | 'unknown'
export interface ChatApi {
/**
* Reads an agent session transcript as structured chat messages.
* Resolves the transcript like `ClaudeApi.readTranscript` (sessionId → cwd), then
* reconstructs ordered bubbles + tool calls. `nodeId` lets an SSH-project node be resolved
* on its HOST even when no hook event has registered its transcript in this app run.
*
* `agentId` picks the reader. Omitted (or `claude`) keeps the historical claude path exactly as
* it was. It is NOT optional in spirit: without it a grok node falls into claude's resolver, whose
* cwd fallback returns the newest CLAUDE transcript for that directory — someone else's
* conversation. `CHAT_CAPABLE` decides who may ask; this decides who answers.
*
* `page` (optional, trailing) asks for ONE window instead of the whole 5 MB tail — see
* `shared/chat-page.ts`. Absent = the legacy read, byte for byte. Present = a result carrying
* `olderCursor`, per-message `key`s, tool-part `id`s and `unmatchedResults`. An invalid
* `before` rejects.
*/
readTranscript(
sessionId: string | undefined,
cwd: string | undefined,
accountId?: string,
nodeId?: string,
agentId?: string,
page?: ChatTranscriptPageRequest
): Promise<ChatTranscriptResult>
/**
* Is the transcript this session id names still on disk?
*
* Resolved STRICTLY by `sessionId` — no cwd fallback, which would answer `present` from another
* session's newest file. `nodeId` lets an SSH-project node be asked on its HOST. Never rejects:
* anything it cannot judge is `unknown`.
*
* Claude-shaped transcripts only (`readsClaudeTranscript` is the caller-side gate) — every other
* agent's id misses this resolver by construction, and reporting that as `absent` would drop a
* perfectly good resume.
*/
transcriptExists(
sessionId: string,
accountId?: string,
nodeId?: string
): Promise<TranscriptPresence>
/**
* The ⌘M composer's `/` catalog for a node: its agent's measured built-in slash commands, custom
* command files and skills (core/chat-catalog.ts). An SSH-project node's files are read on its
* HOST (`nodeId` — remoteness is the shell's own record, never this call's). A relay tab REJECTS
* (E_UNSUPPORTED — the peer's files are not this machine's to read, and the relay does not carry
* the channel); the composer then offers the shared built-in table alone, and every caller must
* treat any rejection the same way.
*/
catalog(nodeId: string, agentId: string, accountId?: string, cwd?: string): Promise<import('./chat-catalog').ChatCatalog>
}
/** Optional SSH context for account ops. When `projectId` names a connected SSH project, the
* account lives on that host (config dir + login + removal happen over ssh). Omit it for local. */
export interface AccountSshCtx {
projectId?: string
}
export interface ClaudeAccountsApi {
/** Mint a new managed account: create its config dir, install the hook, check the CLI version.
* With an SSH `ctx` the dir + hook are created on the remote host instead of locally. */
add(ctx?: AccountSshCtx): Promise<{ id: string; configDir: string; versionSupported: boolean }>
/** Poll the account's `.claude.json` for a completed login; null on timeout/cancel. With an SSH
* `ctx` the poll reads the remote host's copy over ssh. */
waitLogin(id: string, ctx?: AccountSshCtx): Promise<{ email: string } | null>
/** Cancel an in-flight `waitLogin` for this account. */
cancelWaitLogin(id: string): Promise<void>
/** Delete a managed account's config dir (recursive). With an SSH `ctx`, `rm -rf` on the host.
* For a LINKED account (`configDir` set) this only forgets the record — the dir is untouched. */
remove(id: string, ctx?: AccountSshCtx): Promise<void>
/**
* Link a PRE-EXISTING local Claude config dir as an account (see `ClaudeAccount.configDir`).
* Validates the path (absolute, exists, is a directory, not the system `~/.claude`, not a managed
* dir, not already linked), reads its `.claude.json` for the signed-in email (null when not logged
* in yet), and installs the managed status hook into it. Local only — no SSH ctx.
*/
link(configDir: string): Promise<{ id: string; configDir: string; email: string | null }>
/**
* Turn `~/.claude/skills` sharing on or off for one LOCAL account (issue #643) and reconcile the
* filesystem now. Idempotent in both directions; the renderer owns the settings flag and calls
* this for the effect. Never throws — the result reports what happened, including `refused`
* (the account's `skills/` resolves to the system one) and `failed` (an EPERM, a vanished skill).
*/
setSkillSharing(id: string, enabled: boolean): Promise<ClaudeSkillShareResult>
/**
* Copy a conversation's transcript from one LOCAL account's config dir into another's (`undefined`
* = the system `~/.claude`), so a node switched onto the target account resumes the SAME
* conversation there with no `/login`. With an SSH `ctx` the same copy runs on that project's host,
* between REMOTE accounts pinned to it. Called only after the CLI has exited. Never overwrites a
* diverged copy (`diverged`); never throws — every refusal is a reason.
*/
copySession(
sessionId: string,
sourceAccountId: string | undefined,
targetAccountId: string | undefined,
/** An SSH project's node: the copy runs ON THAT HOST, between its remote account dirs. */
ctx?: AccountSshCtx
): Promise<ClaudeSessionCopyResult>
}
/** What `claudeAccounts.copySession` did. `copied: false` = the target already held this exact copy. */
export type ClaudeSessionCopyResult =
| { ok: true; copied: boolean }
| {
ok: false
reason: 'bad-request' | 'unknown-account' | 'no-transcript' | 'diverged' | 'failed'
}
/** What one `setSkillSharing` / launch reconcile did. Counts, never an exception. */
export interface ClaudeSkillShareResult {
linked: number
unlinked: number
/** Links of ours present after the call — what the Settings row reports. */
shared: number
/** System skills not shared because the account has its own entry by that name. */
occupied: number
failed: number
/**
* Why nothing was done. `same-directory`: the account's `skills/` resolves to the system one
* (a hand-made whole-directory link, or a linked account pointed at `~/.claude`) — linking into
* it would plant links in the user's own folder and let the off-switch delete them from there.
* `remote-account`: an SSH account, whose skills live on its host (out of scope for v1).
*/
refused?: 'same-directory' | 'remote-account'
}
/**
* Machine-scoped managed Codex accounts (S6). LOCAL accounts on this Mac are reachable through
* PR 5; SSH remote accounts land in PR 6. The account LIST is renderer-owned in `settings.json`
* (`codexAccounts`), exactly like `claudeAccounts`; main owns only the fs + daemon lifecycle and
* the switch protocol.
*/
export interface CodexAccountsApi {
/** Mint a new managed account: create its private CODEX_HOME (0700) and symlink the shared,
* non-secret runtime assets in. Returns the new id + its home. With an SSH `ctx` the home is
* created ON that connected host (no credential ever travels); throws when it cannot be. */
add(ctx?: AccountSshCtx): Promise<{ id: string; home: string }>
/** Poll the account's `auth.json` (a real file, never a symlink) every 2s up to 5min for a
* completed device login, then read its email; null on timeout/cancel. With an SSH `ctx` the poll
* runs on the host, and a login whose email cannot be read there resolves `{ email: null }`. */
waitLogin(id: string, ctx?: AccountSshCtx): Promise<{ email: string | null } | null>
/** Cancel an in-flight `waitLogin` for this account. */
cancelWaitLogin(id: string): Promise<void>
/** Read a managed account's already-logged-in identity (email), or null if not logged in. With an
* SSH `ctx`, asked of the account's home on that host. */
identity(id: string, ctx?: AccountSshCtx): Promise<{ email: string | null } | null>
/** Read a machine's system (`~/.codex`) account identity. No arg ⇒ this Mac. `{ projectId }` ⇒
* the connected SSH host behind that project; a host whose system identity cannot be resolved
* resolves `null` (fail-closed — a remote machine panel never borrows this Mac's login). */
systemIdentity(ctx?: { projectId?: string }): Promise<{ email: string | null } | null>
/** Remove a managed account: stop its daemon and delete its home. Refused while a switch
* reservation holds it or a concurrent removal is in flight (Property 10). With an SSH `ctx`,
* the home is deleted on that host; throws when it could not be. */
remove(id: string, ctx?: AccountSshCtx): Promise<void>
/** Phase 1 of the owner-authorized same-machine switch: plan + reserve the rollout exposure of a
* conversation from one account to another under a `rollbackToken` (TTL 60s, owner = caller). */
switchThread(
threadId: string,
cwd: string,
sourceAccountId?: string,
targetAccountId?: string
): Promise<{ threadId: string; rollbackToken?: string }>
/** Phase 2: commit the reserved exposure (atomic hardlink into the target account). */
commitSwitch(rollbackToken: string): Promise<void>
/** Phase 3a: finish a committed switch, releasing the reservation. */
finishSwitch(rollbackToken: string): Promise<void>
/** Phase 3b: roll back a reservation (releases it; a committed link is left for cleanup). */
rollbackSwitch(rollbackToken: string): Promise<void>
/**
* The SSH leg of a running node's account switch: expose the conversation to `targetAccountId`
* ON the connected host behind `ctx.projectId` (hardlink the rollout into the target home, verify
* the target discovers it). `hostAccountIds` = every managed account on that host (the catalogs
* the thread is resolved across). Resolves once the target can resume it; throws otherwise.
*/
switchThreadRemote(
threadId: string,
targetAccountId: string | undefined,
hostAccountIds: string[],
ctx: AccountSshCtx
): Promise<void>
/** Source-side leg of moving an idle LOCAL conversation to an SSH account: validate strict source
* containment then hand the upload to the remote import path (PR 6). Local rollout untouched. */
transferThreadToSsh(
threadId: string,
cwd: string,
projectId: string,
targetAccountId?: string,
sourceAccountId?: string
): Promise<{ threadId: string; imported: boolean }>
}
/** One ranked search hit across all on-disk Claude session transcripts. */
export interface TranscriptHit {
sessionId: string
title: string
snippet: string
cwd: string
projectLabel: string
mtime: number
/** The managed/linked Claude account whose root holds this transcript; absent = system. */
accountId?: string
}
export interface TranscriptsApi {
/** Search all on-disk Claude session transcripts by content. */
search(query: string): Promise<TranscriptHit[]>
}
/** What the Claude CLI on THIS machine can do. Fed by the `claude --version` probe in
* core/claude-cli.ts; every field fails open to the conservative answer when the version
* is unknown (missing CLI, timeout, unreadable output). */
export interface ClaudeCliCaps {
version: string | null
/** `--permission-mode auto` is only accepted by Claude Code >= 2.1.71. */
autoPermissionMode: boolean
/** `"tui": "fullscreen"` in settings.json is only understood by Claude Code >= 2.1.89. Gates
* whether nodeterm writes that key (write-if-absent) so sessions render fullscreen in tmux. */
fullscreenTui: boolean
/**
* Whether this CLI accepts `--session-id <uuid>`, which lets nodeterm MINT a node's session id
* instead of waiting to learn it from a hook. Detected by reading `claude --help`, not by
* comparing versions: the version this flag first shipped in is not documented anywhere we can
* check, and a guessed floor is the one mistake that would be fatal here — an unknown flag makes
* the CLI exit, so a wrong guess kills every claude launch rather than degrading.
*/
sessionIdFlag: boolean
}
export interface GrokCliCaps {
/**
* Whether the local grok CLI accepts `--session-id <uuid>`, so nodeterm can MINT a node's session
* id instead of waiting to learn it from a hook.
*
* Probed from `grok --help` by `core/grok-cli.ts` — grok's OWN probe, never claude's. The two
* CLIs are installed and upgraded independently, so claude's answer is not even correlated with
* grok's, and an unknown flag makes grok exit rather than degrade.
*
* grok's grammar differs from claude's in three measured ways (1.0.13): the UUID must not already
* exist under the target session directory, so minting one twice is a LAUNCH ERROR and never a
* resume; `--session-id` combines with `--resume`/`--continue` only alongside `--fork-session`;
* and `--resume` accepts a TITLE as well as an id, failing as ambiguous on duplicates.
*/
sessionIdFlag: boolean
/**
* Model ids this CLI lists, from `grok models` — the CLI's own catalogue, so there is no allowlist
* to maintain and a model shipped tomorrow appears without a code change.
*
* Empty when the subcommand fails, is unparseable, or grok is not installed: the UI then offers no
* model switching, which is the pre-feature behaviour. Never a partial list.
*/
models: string[]
}
/** Unprobed grok ⇒ omit the flag, offer no models ⇒ today's command line, byte-identical. */
export const UNKNOWN_GROK_CLI_CAPS: GrokCliCaps = { sessionIdFlag: false, models: [] }
export interface CursorCliCaps {
/** `cursor-agent models`: id + label, the account's own catalogue. [] when it cannot be read. */
models: { id: string; name?: string }[]
}
/** Unprobed cursor ⇒ no models ⇒ no model switching (the pre-feature behaviour). */
export const UNKNOWN_CURSOR_CLI_CAPS: CursorCliCaps = { models: [] }
export interface CursorApi {
/** Never rejects; an unprobed or offline CLI resolves to the empty catalogue. */
cliCaps(): Promise<CursorCliCaps>
}
export interface GrokApi {
/** Capabilities of the local grok CLI (memoized in the shell; safe to call repeatedly).
* Never rejects — an unprobed CLI resolves to the fail-open caps. */
cliCaps(): Promise<GrokCliCaps>
/**
* The session ids grok already has under this cwd.
*
* Needed because grok REFUSES a `--session-id` that already exists under the target session
* directory — that is a launch error, not a resume, so a node handed a taken id never starts. An
* array rather than a Set: a Set does not survive the IPC/WS-RPC boundary and would arrive empty,
* which is the one wrong answer this call can give.
*/
takenSessionIds(cwd: string): Promise<string[]>
}
/** The answer whenever the CLI version can't be determined: no `auto` flag → bare command, and no
* fullscreen-tui write (an unknown settings key can warn on old CLIs — silence is safer). */
export const UNKNOWN_CLAUDE_CLI_CAPS: ClaudeCliCaps = {
version: null,
autoPermissionMode: false,
fullscreenTui: false,
sessionIdFlag: false
}
/**
* What the LOCAL `codex` binary can do, read from its own `--help` — see `core/codex-cli.ts`.
*
* Separate from `CodexIdentityCaps` on purpose, because the two have OPPOSITE Server Edition
* answers: shared identity is declined there deliberately (a constant `false`), while the
* approval vocabulary must be probed for real — the server's own machine is the one that runs its
* Codex sessions. Folding them into one bag would have made the honest answer to one question the
* silent absence of the other.
*/
export interface CodexCliCaps {
/** The values this `codex` advertises for `--ask-for-approval`. `null` = not probed, no codex on
* PATH, or a help page we could not read — all of which mean "use the baseline vocabulary", not
* "this CLI accepts nothing". Measured: 0.146.0–0.148.0 list `untrusted, on-request, never`;
* 0.149.0+ list `on-request, never`. */
approvalValues: string[] | null
/** Does this `codex` accept `--no-daemon`? `null` = unknown (not probed, no codex). Every
* nodeterm-launched plain Codex TUI carries the flag when this is `true`: from 0.157.0 a plain
* TUI otherwise runs inside ONE shared background app-server per CODEX_HOME that keeps the FIRST
* pane's `NODETERM_*` environment, attributing every later node's hooks and tool shells to that
* first node (see `codexNoDaemonFrom`). Optional so an older core's answer still type-checks. */
noDaemon?: boolean | null
}
/** The answer before the probe has run, and for any surface that cannot speak for the CLI that will
* actually run the session (a relay tab, an SSH host). */
export const UNKNOWN_CODEX_CLI_CAPS: CodexCliCaps = { approvalValues: null, noDaemon: null }
/** Whether a Codex node launched on this machine right now would get a managed shared identity.
* Fed by core/codex-identity-caps.ts; the unknown answer is `false`, i.e. plain `codex`. */
export interface CodexIdentityCaps {
shared: boolean
/** Absolute path of the installed launcher, or null when it could not be written. */
launcherPath: string | null
/** Does the installed `codex` accept `--remote`? Feature-detected from its own `--help`. The one
* precondition that cannot be recovered from at runtime: the launcher execs, and a CLI without
* the flag dies on a usage error where no fallback is left. Unknown ⇒ false ⇒ plain codex, and
* "not probed" counts as unknown: when `appServer` is false the help spawns are skipped, so this
* reads false whatever the CLI's help page would have said. */
remoteFlag: boolean
/** Can this INSTALL run a shared app-server at all? `codex app-server daemon start` needs the
* standalone runtime the Codex installer manages; an npm (or snap) install has the `--remote`
* flag in its help and no such runtime, so it can never serve a shared identity. Unknown ⇒
* false ⇒ plain codex. */
appServer: boolean
/** Why shared identity is off by DESIGN rather than by probe, when it is. `unsupported-platform`
* = a Windows core (phase 1: not wired there yet; every node runs its own codex). Absent on
* every other answer — an older core never sends it. */
unavailableReason?: 'unsupported-platform'
}
/** The answer before the probe has run, and the one the Server Edition gives on purpose. */
export const UNKNOWN_CODEX_IDENTITY_CAPS: CodexIdentityCaps = {
shared: false,
launcherPath: null,
remoteFlag: false,
appServer: false
}
/** A Codex node's identity mode, as reported by the node's own launcher at spawn time.
* `plain` carries the machine-readable reason the managed identity was unavailable. */
export interface CodexIdentityEvent {
nodeId: string
mode: 'shared' | 'plain'
reason?: string
}
/** The Codex-specific surface. Small on purpose: everything else a Codex node needs already goes
* through the shared agent/pty APIs. */
export interface CodexApi {
/** Would a Codex node launched right now get a managed shared identity on this machine?
* Never rejects — the unknown answer is `{ shared: false }`, i.e. plain `codex`. */
identityCaps(): Promise<CodexIdentityCaps>
/** What the local Codex CLI accepts, so a launch line only carries flag values this binary
* actually has. Never rejects — the unknown answer is `UNKNOWN_CODEX_CLI_CAPS`. */
cliCaps(): Promise<CodexCliCaps>
/** Fires when a Codex node's launcher reports its identity mode. `plain` is the fallback, and
* this event is what stops that fallback being silent. Returns unsubscribe. */
onIdentity(listener: (e: CodexIdentityEvent) => void): () => void
}
export interface ClaudeApi {
/** Capabilities of the local Claude CLI (memoized in the shell; safe to call repeatedly).
* Never rejects — an unknown version resolves to the fail-open caps. */
cliCaps(): Promise<ClaudeCliCaps>
/**
* Reads a Claude session's full transcript as flat searchable lines ([] if unavailable).
* Resolves by `sessionId` when known (exact); otherwise falls back to `cwd` (durable —
* the newest transcript under that project dir, no live hook event required).
* `accountId` scopes resolution to a managed Claude account's transcript root (default `~/.claude`).
* `nodeId` (optional) lets an SSH-project node's transcript be located on its HOST when no hook
* event has registered it in this app run — without it the search silently reads nothing there.
*/
readTranscript(
sessionId: string | undefined,
cwd: string | undefined,
accountId?: string,
nodeId?: string
): Promise<TranscriptLine[]>
}
export type HandoffResult = { filePath: string } | { error: string }
/** Agent launch/gateway IPC. The renderer has no `process.env`; `${env:VAR}` expansion runs
* renderer-side against the `envSnapshot()` cache (src/renderer/lib/agentEnv.ts), so the
* Settings preview and the typed launch command share one assembler AND one environment — they
* cannot drift by construction. */
export interface AgentApi {
/** A string-only snapshot of the main process environment (undefined entries omitted), for
* expanding `${env:VAR}` tokens in launch commands and the Settings preview. Desktop-window
* only: the browser/relay bridges resolve `{}` (a host env dump must never cross to a peer —
* the PR #195 leak class), and expansion there degrades to the missing-env refusal. */
envSnapshot(): Promise<Record<string, string>>
/** Query the configured gateway's OpenAI-compatible `/v1/models` endpoint. Never rejects. */
discoverModels(settings: ModelGatewaySettings): Promise<ModelDiscoveryResult>
/** Literal gateway credentials are write-only in the renderer. */
gatewayCredentialStatus(): Promise<ModelGatewayCredentialStatus>
saveGatewayCredential(apiKey: string): Promise<ModelGatewayCredentialStatus>
clearGatewayCredential(): Promise<ModelGatewayCredentialStatus>
}
export interface HandoffApi {
/**
* Render the source agent's full conversation transcript (located by `sessionId`)
* to a portable Markdown file under `<cwd>/.nodeterm/` and return its absolute path.
* No summarization — the entire transcript including tool calls and outputs.
*/
build(
sessionId: string,
agentId: string,
sourceNodeId: string,
cwd: string | undefined,
accountId?: string
): Promise<HandoffResult>
}
export interface LicenseStatus {
/** 'pro' when entitled, else null. */
tier: string | null
active: boolean
/** Unix seconds when the entitlement TOKEN expires, or null — the offline grace window (the server
* mints 7-day tokens and the app re-mints every 6 h, so this rolls forward forever). It is NOT
* when the subscription ends and must never be shown as that; see `termEndsAt` (issue #800). */
expiresAt: number | null
/** Unix seconds when the current subscription term ends, as the server stated it beside the token,
* or null. Null is a first-class answer — a lifetime entitlement, a license with no expiry, or a
* server that does not send the field yet — and renders as no date at all. Display only. */
termEndsAt: number | null
/** Seat cap for the relay host (Team Access): premium → the token's seats (absent → 1), free/inactive → 0. */
seats: number
/** Last activation/refresh error reason code, or null. */
error: string | null
}
/**
* Where the entitlement behind this install came from. A verified entitlement's licenseId is NOT
* always a keygen license id: a store purchase on a paired phone bridges Pro to the desktop and
* mints `apple:<txn>` (App Store) or `google:<orderId>` (Google Play), and `free:` exists too. For
* those the server makes zero keygen calls and answers `key: null, used: 0, seats: 0` — genuinely
* "device counting does not apply here", which is a different fact from a failed read and from a
* keygen license with no devices yet.
*/
export type LicenseSource = 'keygen' | 'apple' | 'google' | 'free'
/** What Settings → License shows: the key to copy and how much of the device cap is in use.
* A failed read is an ERROR, never "0 devices" — the two are different facts. */
export interface LicenseDetail {
/** The license key to copy. `null` on a 200 is legitimate (a keygen policy that hides keys, a
* license predating the column, a non-keygen source) — it is NOT an error. */
key: string | null
/** Devices currently activated. May EXCEED `seats` if a cap was lowered after activation. */
used: number
seats: number
/** The source the server stated, or null when it stated none — every error reply, and the
* release route's 200, which answers with counts only. Never inferred locally. */
source: LicenseSource | null
/** Null on success; a stable reason code otherwise ('unauthorized' | 'inactive' | 'offline' |
* 'disabled' | 'too_soon' | 'not_applicable' | 'network'). A failed read is an error, never
* "0 devices". */
error: string | null
/** Days until another release is allowed — only set with error === 'too_soon'. */
retryAfterDays?: number
}
export interface LicenseApi {
/** Open Stripe checkout bound to this device and poll for the entitlement (no key paste).
* `target` picks the link: 'seats' = the add-seats (quantity) link, else base Pro (default).
* Returns the current status immediately; the active status arrives via onChange. */
upgrade(target?: 'pro' | 'seats'): Promise<LicenseStatus>
/** Activate a license key on this device. Returns the resulting status. */
activate(key: string): Promise<LicenseStatus>
/** Release this device's seat and clear the local license. */
deactivate(): Promise<LicenseStatus>
/** Current cached status (verifies the stored token offline). */
getStatus(): Promise<LicenseStatus>
/** Fires when the license status changes. Returns unsubscribe. */
onChange(listener: (s: LicenseStatus) => void): () => void
/** The license key + device usage for this machine's license. Authorized by the stored
* entitlement token — never by deviceId. */
detail(): Promise<LicenseDetail>
/** Deactivate every device on this license except this one. Throttled server-side to once
* per 30 days (error 'too_soon' + retryAfterDays). Answers with COUNTS only: no key and no
* source ride a successful release, so callers must merge rather than replace. */
releaseOthers(): Promise<LicenseDetail>
}
/** The free-tier open-project limit (src/shared/project-limit.ts; core computes the state). Desktop
* only: the Server Edition's stub answers `INACTIVE_PROJECT_LIMIT` and claims `disabled`,
* and a relay tab keeps the local preload — the allowance is this machine's, never the host's. */
export interface ProjectLimitApi {
/** The current state. Cheap and offline: it never waits on the network. */
state(): Promise<ProjectLimitState>
/** Claim this device's allowance from the server (lazily, at the limit moment). Never rejects
* for a network or server failure — that is `ok: false` with the state as it stands. */
claim(): Promise<ClaimResult>
/** Fires with the new state whenever it changes. Main sends it to this machine's windows only
* (never broadcast to relay peers). Returns unsubscribe. */
onChange(listener: (s: ProjectLimitState) => void): () => void
}
export type PhoneApprovalResult = {
status: 'persisted' | 'approved' | 'saved-disconnected' | 'stale' | 'persistence-failed'
}
export interface RemoteHostApi {
/**
* Enter host mode: mint a pairing token, connect to the relay as the host, and return the
* pairing offer string (`nodeterm://pair?code=…`) to hand to a client. Rejects if the device
* is not entitled to Pro (or in a dev build without NODETERM_RELAY_URL).
*/
start(): Promise<{ offer: string }>
/** Leave host mode: close the relay connection (ends served PTYs, drops client access). */
stop(): Promise<void>
/**
* Push the host's current active-project canvas snapshot to main. Main keeps the latest
* and (re)broadcasts it to a connected client (debounced). Safe to call when not hosting.
*/
sendCanvasState(state: CanvasState): void
/**
* Listen for a client's mutation command that the host renderer must apply to its React
* Flow (the single writer). Returns an unsubscribe function.
*/
onApplyMutation(listener: (mutation: CanvasMutation) => void): () => void
/**
* Fires when a client finishes the E2EE handshake and is awaiting approval. The host must call
* `approve()` before any of the client's pty/fs RPCs are served; `sas` is the channel
* verification code to display. Returns an unsubscribe function.
*/
onPeerPending(
listener: (info: { sas: string | null; id: string; pub?: string | null; standing?: boolean }) => void
): () => void
/** The pending prompt expired host-side (120 s) — the dialog must drop or re-arm, else its
* Approve is a silent no-op against a dead id (issue #372). */
onPeerPendingCleared(
listener: (info: { id: string | null; pub?: string | null }) => void
): () => void
/** Standing phone consent: persist the displayed handshake identity before granting access.
* Both fields must match a bounded pending request. Desktop-only; Server rejects explicitly. */
approvePhone(id: string, pub: string): Promise<PhoneApprovalResult>
/** Legacy interactive (single-use offer) approval; does not persist a device pin. */
approve(id: string, pub?: string): void
/** Reject the pending client → the connection is dropped. Same id/pub matching as approve. */
reject(id: string, pub?: string): void
/**
* Start/stop the standing (phone) relay host so a paired phone can reach this Mac from anywhere.
* Mirrors `settings.phoneAccessEnabled`.
*/
setPhoneAccess(enabled: boolean): void
}
/**
* Payload of `relayHost.onPeerPending`: a client has finished the E2EE handshake over the new
* relay tunnel and is awaiting the host human's approval. `id` addresses this pending peer for
* `confirm(id)`; `sas` is the channel verification code both humans compare (null before the key is
* derived); `peerKeyB64` is the peer's stable box public key to pin on approval.
*/
export interface RelayPeerPending {
id: string
sas: string | null
peerKeyB64: string
/** Team Access: the invitee email this seat was invited with, if any. DISPLAY label only (never
* trust/identity — the SAS is the gate); used to tag the row in the connected-devices list. */
email?: string
}
/**
* HOST side of the new E2EE relay tunnel (Stage 4) — the successor to `RemoteHostApi`. A connected
* peer becomes a first-class CorePlatform client (it exchanges raw rpc frames), so this surface is
* only the mutual-approval gate plus enter/leave, not a per-verb API. Desktop-only (Electron);
* the Server Edition browser build degrades every member to `E_UNSUPPORTED`/no-op.
*/
export interface RelayHostApi {
/**
* Enter host mode over the relay: connect and return a pairing offer string to hand to a client.
* Rejects if the device is not entitled (or a dev build without the relay URL). `projectId` is the
* single project this hosting session shares with the peer; omit for the legacy whole-workspace view.
*/
start(projectId?: string): Promise<{ offer: string; id: string }>
/**
* Team Access: ADD a seat — mint a fresh pairing offer for one more device (no supersede), tagged
* with the optional invitee `email` (display label only). Rejects `E_SEATS_FULL` when the licensed
* seat cap is reached, and with the Pro / dev-build errors `start` uses. `projectId` scopes the
* shared project as in `start`. Resolves with the offer AND the seat's `id` — the settings UI uses
* it to show the pending row immediately and to `revoke` a seat whose peer never connects.
*/
invite(opts?: { projectId?: string; email?: string }): Promise<{ offer: string; id: string }>
/** Leave host mode: close every bridged peer in the pool. */
stop(): Promise<void>
/**
* Which of these projects may NOT be shared, with the reason (a folder that is the disk root, the
* home directory or an ancestor of either — every file under it would be readable). The invite
* UI disables those projects; `start`/`invite` refuse them host-side too. Projects absent from the
* answer may be shared.
*/
scopeProblems(projectIds: string[]): Promise<Record<string, string>>
/**
* Team Access: per-peer revoke — cut ONE bridged peer's live session immediately (by its id) and
* free its seat. Distinct from `stop()` (which drops all).
*/
revoke(id: string): void
/**
* Fires when a client finishes the handshake and is awaiting approval. The host must `confirm()`
* before the peer is admitted as a client. Returns an unsubscribe function.
*/
onPeerPending(listener: (info: RelayPeerPending) => void): () => void
/** Approve the pending peer (by its pending id) after comparing the SAS → it joins as a client. */
confirm(id: string): void
/** Fires when a bridged peer becomes a live client (both humans confirmed). Returns unsubscribe.
* `email` is the seat's invite label, if any (Team Access). */
onOpen(listener: (info: { id: string; email?: string }) => void): () => void
/** Fires when a bridged peer's connection drops. Returns an unsubscribe function. */
onClosed(listener: (info: { id: string }) => void): () => void
}
/**
* CLIENT side of the new E2EE relay tunnel (Stage 4) — the successor to the deleted legacy relay
* client dialect. The client exchanges raw rpc.ts frames (JSON strings) with the host over the encrypted tunnel rather
* than a per-verb channel set. Desktop-only (Electron); the Server Edition browser build degrades
* every member to `E_UNSUPPORTED`/no-op.
*/
export interface RelayClientApi {
/**
* Connect to a host by its pairing offer string. Gates on entitlement (rejects otherwise, and in
* dev builds without the relay URL). Resolves with a `connectionId` to address the methods below.
*/
connect(offer: string): Promise<string>
/**
* Listen for the channel SAS once the handshake completes, so the client human can compare it
* with the code shown on the host before approving. Returns an unsubscribe function.
*/
onSas(connectionId: string, listener: (sas: string | null) => void): () => void
/** Confirm the SAS on this side (the client half of the mutual-approval gate). */
confirm(connectionId: string): void
/** Fires once the host approves this connection → the client may begin exchanging frames. */
onApproved(connectionId: string, listener: () => void): () => void
/** Cast an outbound rpc frame (a JSON string) at the host over the tunnel. */
send(connectionId: string, frame: string): void
/** Listen for an inbound rpc frame (a JSON string) from the host. Returns an unsubscribe. */
onFrame(connectionId: string, listener: (frame: string) => void): () => void
/** Fires when the connection's relay socket drops (host/relay gone). `reason` is set only when
* the host refused this device over the tunnel first (a hosted team: an owner declined, removed
* it, or nobody answered in time). Returns unsubscribe. */
onClosed(connectionId: string, listener: (reason?: RelayClosedReason) => void): () => void
/** Close a connection: end the relay socket and drop access to the host. */
disconnect(connectionId: string): void
}
/** Why a host refused a relay client before closing it (the core relay's `TrustDeniedReason`). */
export type RelayClosedReason = 'denied' | 'removed' | 'expired'
/**
* The hosted teams this desktop has joined by `nodeterm://join` code. A join code is passed to
* `relayClient.connect` like a pairing offer; these are the bookmarks that connect leaves behind.
* Desktop-only: a browser cannot join a relay host, so the Server Edition answers an empty list.
*/
export interface RelayHostedApi {
/** The bookmarks, never their device tokens. `approved` = both humans approved this device on
* that host, so a reconnect needs no SAS comparison on this side. */
bookmarks(): Promise<Array<{ hostId: string; label: string; approved: boolean; code: string }>>
/** Forget a bookmark (its device token and its approval). Rejects while a join for that team is
* still minting or joining: that join would write the bookmark straight back. */
removeBookmark(hostId: string): Promise<void>
}
/** A hosted team member's role (the core team store's `TeamRole`). */
export type HostedRole = 'owner' | 'editor' | 'commenter' | 'viewer'
/** A device waiting for an owner to approve it (core hosted-service's `HostedPending`). */
export interface HostedPending {
pendingId: string
/** The code both people compare out of band. */
sas: string
peerKeyB64: string
/** Host wall-clock ms the request arrived. */
since: number
}
/** Why a pending request stopped being pending. `approved` / `denied` may be ANOTHER owner's answer;
* `replaced` = the same device asked again (its newer request arrives on its own). */
export type HostedPendingClosedReason = 'approved' | 'denied' | 'expired' | 'replaced' | 'gone'
/** What `relay:hosted:self` answers: this device's role, its label on the team, the host's label. */
export interface HostedSelf {
role: HostedRole
label: string
hostLabel: string
}
/**
* The hosted team verbs of ONE relay session. Only a relay tab joined by a `nodeterm://join` code has
* it (`NodeTerminalApi.hosted`); a local session, a Server Edition browser and a Team Access relay
* tab (desktop to desktop) never do. The host answers every one of these itself and judges the
* caller's role: `self` is open to any member, the rest are owner-only.
*/
export interface HostedSessionApi {
self(): Promise<HostedSelf>
/** The requests still waiting (owner-only). Pulled once on open; the events below are deltas. */
pending(): Promise<HostedPending[]>
/** The team's join code, or null when the host has none to hand out. */
inviteCode(): Promise<string | null>
/** Admit a waiting device with `role`. False when it is gone or another owner answered first. */
approve(pendingId: string, role: HostedRole): Promise<boolean>
/** Refuse a waiting device. False when it is already gone. */
deny(pendingId: string): Promise<boolean>
onPeerPending(listener: (p: HostedPending) => void): () => void
onPendingClosed(listener: (p: { pendingId: string; reason: HostedPendingClosedReason }) => void): () => void
/** The team's shared projects changed (share or unshare on the host): their whole set. */
onSharedChanged(listener: (p: { projectIds: string[] }) => void): () => void
}
/** A paired device as exposed to the renderer — the bearer token is never included. */
export interface PairedDevice {
id: string
name: string
/** epoch-ms the device was paired. */
pairedAt: number
/** epoch-ms the host agent last saw this device (0 = never). */
lastSeenAt: number
/**
* The phone's OWN device id — what the relay backend keys its device row on, as opposed to
* `id`, which is ours. Absent for devices paired before this field existed; that is NOT "there
* is no server row we can name", because a revoke then falls back to `id`, which is the value
* the mint sent as the row's key whenever the phone supplied no id of its own (see
* `revokeDevice` in main/pairing-service.ts, including the residual case it cannot name). An id,
* not a secret, which is why it may cross to the renderer.
*/
relayDeviceId?: string
}
/**
* The server leg of a device revoke — three states, because two cannot tell the truth apart.
* 'ok' = the backend confirmed; 'failed' = we asked and were refused or could not reach it;
* 'skipped' = we did not ask and that is fine (no entitlement to sign with — a free-tier desktop
* has no Pro of ours on that phone to reclaim — or no such device to name). Only 'failed' is a
* warning: reporting 'skipped' as a failure would tell a free user their phone's Pro is stuck.
*
* 'ok' is the backend's 204, which is idempotent and reveals nothing about WHICH row it applied
* to — see the residual-leak note on `revokeDevice` in main/pairing-service.ts before treating it
* as proof that a particular phone lost Pro.
*/
export type DeviceRevokeServerOutcome = 'ok' | 'failed' | 'skipped'
/**
* Both legs of a device revoke, reported independently so a half-finished removal can never render
* as a clean one (the same discipline as remote/revocation.ts's persisted/killed).
*/
export interface DeviceRevokeResult {
/** The phone's relay trust (every phone relay pin + live relay session), its authorized_keys line
* and its agent.json entry were all removed from this machine. */
local: boolean
/** Whether the phone's Pro entitlement was taken back on the relay backend. */
server: DeviceRevokeServerOutcome
}
/** Phone-pairing (nodeterm iOS "scan a QR" flow) bridge. */
export interface PairingApi {
/** Start the one-shot LAN listener; resolves with the QR payload + an SSH-reachable hint. */
start(): Promise<{
payload: string
sshOpen: boolean
relayPlan?: 'ok' | 'dev' | 'off'
/** false = relay-only host (Windows): no SSH key is installed and the QR waits for the relay,
* not sshd (`pairingGate`). Absent from an older main process ⇒ treat as true. */
sshKey?: boolean
/** Windows only, explanation only: which authorized_keys file sshd reads for this account. */
windowsKeyFile?: 'administrators' | 'profile' | 'unknown'
}>
/** Cancel an in-flight pairing (e.g. when the settings section unmounts). */
stop(): Promise<void>
/** Fires once when pairing finishes (ok=true paired, ok=false timeout / relay-only mint failure).
* Returns unsubscribe. */
onDone(
cb: (result: {
ok: boolean
relay?: 'ok' | 'off' | 'failed' | 'dev'
reason?: 'timeout' | 'relay-failed'
reached?: boolean
}) => void
): () => void
/** Live re-probe of 127.0.0.1:22, so the "SSH server is off" warning can clear the moment the
* user turns it on (polled by the UI only while the warning is showing). */
probeSsh(): Promise<boolean>
/** Open this OS's settings page for its SSH server — Sharing → Remote Login on macOS, Optional
* features on Windows (`sshServerCopy().settingsUrl`, the same table the warning's copy comes
* from). The deep link is a main-side constant: neither scheme passes shellOpenExternal's
* http(s) allowlist. A no-op where that table offers no URL, and the UI shows no button there. */
openRemoteLoginSettings(): Promise<void>
/** List paired devices from ~/.nodeterm/agent.json (never includes the token). */
listDevices(): Promise<PairedDevice[]>
/**
* Revoke a device: remove its registry entry, delete its authorized_keys line, and take its Pro
* entitlement back on the relay backend. Never rejects for a leg that failed — read the result.
*/
revokeDevice(id: string): Promise<DeviceRevokeResult>
/** Push webhook (shared/push-webhook.ts): what token is live for this machine — never its value. */
webhookStatus(): Promise<PushWebhookResult<PushWebhookTokenInfo | null>>
/** Mint (or rotate) the token. The value in the result is the only copy that will ever exist
* outside the user's own storage: the backend keeps only its hash, and this app keeps nothing. */
webhookMint(): Promise<PushWebhookResult<PushWebhookMinted>>
webhookRevoke(): Promise<PushWebhookResult<true>>
/** The API base the examples should name (NODETERM_API_BASE or production). */
webhookEndpoint(): Promise<string>
}
/** Team presence (docs/team-presence.md). All of it is transient — nothing here is persisted. */
export interface PresenceApi {
/** Announce {name, color}. Resolves with THIS client's own id (so it never draws its own
* cursor) plus the current peer table. */
hello(identity: PeerIdentity): Promise<{ clientId: ClientId; peers: PeerState[] }>
/** Publish the local cursor in FLOW coordinates (null when it leaves the canvas). */
cursor(cursor: { x: number; y: number } | null): void
/** Publish the node the local user is working in (null = none). */
focus(nodeId: string | null): void
/** Publish live cursor-chat text (null closes the bubble). */
chat(text: string | null): void
/** Publish the live dino game we are the authority for (null = stopped/idle). Spectators read
* the matching peer's `dino` and render `snap` instead of running their own sim. */
dino(payload: { nodeId: string; snap: DinoSnapshot } | null): void
/** Publish the project (canvas) we are looking at — peers on other projects are never drawn
* on our canvas, and we are never drawn on theirs (null = no project open). */
project(projectId: string | null): void
/** Full peer-table snapshot (on join). Returns unsubscribe.
* Exactly one subscriber (the presence store, src/renderer/state/presence.ts): the browser
* bridge drains its early-event buffer into the FIRST subscriber, so a second one gets nothing.
* Components read the store; they never subscribe here. */
onSync(listener: (peers: PeerState[]) => void): () => void
/** Single-peer diff (join / update / leave). Returns unsubscribe.
* Exactly one subscriber (the presence store) — same reason as onSync. */
onPeer(listener: (diff: PeerDiff) => void): () => void
}
/** Keyboard-shortcut plumbing the RENDERER cannot do for itself. */
export interface ShortcutsApi {
/** Tell the shell that a shortcut recorder is armed (`true`) or released (`false`), so the
* desktop's `before-input-event` intercepts stand down and the chord being recorded — ⌘W and
* ⌘M among them — reaches the recorder instead of closing the user's selected nodes. A claimed
* chord never reaches the page, so the recorder's own preventDefault cannot substitute for
* this. Fire-and-forget. **The `false` leg is not optional**: the bit is global, so a recorder
* that arms and never releases leaves those chords dead app-wide. Server Edition: a documented
* no-op (a browser tab has no application menu to steal a chord back from, so nothing
* intercepts). */
setRecording(active: boolean): void
/** Mirror whether an xterm currently holds keyboard focus, so the desktop's intercepts can stand
* down under the `terminal-first` shortcut policy — `before-input-event` fires before any
* renderer handler could answer, so main needs the answer in advance. Sent on CHANGE only.
* Fire-and-forget, and **not optional**: the mirror is the only thing that makes the policy
* reach the three main-intercepted chords. Read fail-safe on the far side (a missing or stale
* mirror = not focused = intercepts on), so the failure mode of never sending is the app
* behaving as it did before the policy existed. Server Edition: a documented no-op, like
* `setRecording` — a browser tab has no application menu to steal a chord back from. */
setTerminalFocused(focused: boolean): void
}
/**
* Trigger nodes (issue #493): the card's IPC surface. `arm` binds this machine's consent to the
* exact spec the user was shown (content-bound — see @shared/trigger); `runNow` chooses only WHEN,
* never WHAT (the payload is resolved core-side from the node's persisted content). Real on
* desktop and the Server Edition; the relay stub refuses (another machine's arm store is not ours
* to write).
*/
export interface TriggersApi {
arm(projectId: string, nodeId: string, spec: import('./trigger').TriggerSpec): Promise<boolean>
disarm(projectId: string, nodeId: string): Promise<void>
status(projectId: string, nodeId: string): Promise<import('./trigger').TriggerNodeStatus>
runNow(
projectId: string,
nodeId: string
): Promise<{ outcome: 'fired' | 'missed' | 'failed' | 'queued'; detail?: string }>
}
/** `nodeterm://` links (see main/open-link.ts, @shared/open-link). */
export interface OpenLinkApi {
/** The renderer is listening: main delivers any link that arrived before (a cold start). */
ready(): void
/** An `open` link for the confirm sheet. */
onRequest(listener: (req: import('./open-link').OpenLinkPrompt) => void): () => void
/** A `pair` / `join` link: route to the existing pairing / join flow, never auto-accept. */
onPair(listener: (link: { kind: 'pair' | 'join'; url: string }) => void): () => void
/** A refused or dropped link, as one sentence for a toast. */
onNotice(listener: (n: { text: string }) => void): () => void
/** The human's choice; main re-checks it and answers with the final open. */
accept(id: string, choice: import('./open-link').OpenLinkChoice): Promise<import('./open-link').OpenLinkAcceptResult>
/** The sheet was dismissed (or replaced): forget the request. */
cancel(id: string): void
}
export interface NodeTerminalApi {
pty: PtyApi
workspace: WorkspaceApi
projectSettings: ProjectSettingsApi
projectSetup: ProjectSetupApi
worktree: WorktreeApi
dialog: DialogApi
settings: SettingsApi
integrations: IntegrationsApi
speech: SpeechApi
ssh: SshApi
sshProject: SshProjectApi
sshFs: SshFsApi
git: GitApi
clipboard: ClipboardApi
shell: ShellApi
fs: FsApi
media: MediaApi
browser: BrowserApi
files: FilesApi
updates: UpdateApi
announcements: AnnouncementsApi
license: LicenseApi
projectLimit: ProjectLimitApi
contextLink: ContextLinkApi
boardLog: BoardLogApi
logs: LogApi
githubIssues: import('./github-issues').GitHubIssuesApi
githubControl: import('./github-issues').GitHubControlApi
usage: UsageApi
sessionMemory: SessionMemoryApi
devPorts: import('./dev-ports').DevPortsApi
/** "Open recent" — the newest agent conversations in this machine's CLI histories. */
recentConversations: import('./recent-conversations').RecentConversationsApi
wallpaper: import('./wallpaper').WallpaperApi
/** Run node host side (launch.json, devices, launcher, status, stop, signals, reload on save). */
runConfig: import('./run-config').RunConfigApi
/** Simulator node host side (macOS desktop): live iOS simulator screen + input. */
simulator: import('./simulator').SimulatorApi
triggers: TriggersApi
context: ContextApi
canvas: CanvasApi
/** Which projects publish their canvas ops even when alone (see CanvasAuthorityApi). */
canvasAuthority: CanvasAuthorityApi
codex: CodexApi
claude: ClaudeApi
grok: GrokApi
cursor: CursorApi
/** Custom-agent launch/preview (env-var expansion + command assembly). */
agent: AgentApi
chat: ChatApi
claudeAccounts: ClaudeAccountsApi
codexAccounts: CodexAccountsApi
transcripts: TranscriptsApi
remoteHost: RemoteHostApi
relayHost: RelayHostApi
relayClient: RelayClientApi
relayHosted: RelayHostedApi
/** "Share with team" for an SSH project. Desktop only (the Server Edition and relay tabs answer
* `E_UNSUPPORTED`). */
shareTeam: ShareTeamApi
/** The hosted team verbs of THIS session's host — present only on a relay tab joined by a hosted
* team's join code; absent everywhere else (local, Server Edition, Team Access relay tabs). */
hosted?: HostedSessionApi
handoff: HandoffApi
pairing: PairingApi
presence: PresenceApi
shortcuts: ShortcutsApi
/** `nodeterm://` links clicked outside the app. Desktop only (the Server Edition has no URL
* scheme: its stub never fires and refuses accept). */
openLink: OpenLinkApi
/** Fires when the user presses Cmd/Ctrl+M (toggle markdown view). Returns unsubscribe. */
onMarkdownToggle(listener: () => void): () => void
/** Fires when the user presses Cmd/Ctrl+W (close selected node). Returns unsubscribe. */
onCloseNode(listener: () => void): () => void
/** Fires when the user presses Cmd/Ctrl+0 (zoom the canvas back to 100%). Desktop only: the
* key is intercepted in main because Electron's default View menu owns the accelerator. In the
* Server Edition the renderer's own keydown handler sees the key and this is a no-op stub. */
onZoomActualSize(listener: (mods?: ZoomActualSizeModifiers) => void): () => void
/** Native View menu → Snap to Grid toggle. Returns unsubscribe. */
onToggleAutoAlign(listener: () => void): () => void
/** Native View menu → Fit View. Returns unsubscribe. */
onFitView(listener: () => void): () => void
/** Native View menu → Toggle Kanban / Canvas view. Returns unsubscribe. */
onToggleKanban(listener: () => void): () => void
/** Fires when the native app menu's "Settings…" item (⌘,) is clicked. Returns unsubscribe. */
onOpenSettings(listener: () => void): () => void
/** Close the application window (Cmd/Ctrl+W fallback when no node is selected). */
closeWindow(): void
/** Bring the app window to the foreground (show + OS focus). Called after a file is DROPPED
* into a terminal: on macOS a drag-drop from another app (Finder/browser) does not activate
* the destination app, so the drag-source keeps keyboard focus and the user's next keystrokes
* land in the WRONG application — `term.focus()` (DOM-only) can't fix that. Desktop raises the
* BrowserWindow; the browser bridge does a best-effort `window.focus()`. */
focusWindow(): void
/** Set the macOS Dock badge to the unread-message count (0 clears it). */
setBadgeCount(count: number): void
/** Apply the UI-scale setting as page zoom for THIS window (desktop: `webFrame.setZoomFactor`).
* The preload re-clamps through `resolveUiScale` — the value originates in hand-editable
* settings.json, and the boundary must not trust the caller to have done it. Server Edition:
* documented no-op — a browser page cannot set its own page zoom, and the browser already owns
* the identical mechanism (Cmd/Ctrl+±). */
setUiZoomFactor(factor: number): void
/** Absolute filesystem path for a dropped/picked File (for drag-into-terminal). */
getPathForFile(file: File): string
/** Absolute writable base dir (Electron userData) for app-managed files like default worktrees. */
userDataDir(): Promise<string>
/** Show an OS notification (main suppresses it if the window is focused). 'failed' =
* the OS rejected it (e.g. macOS permission denied) — surface it, don't ignore it. */
notify(payload: NotifyPayload): Promise<'shown' | 'failed' | 'skipped'>
/** Open the OS notification settings pane (macOS; no-op elsewhere) to re-grant permission. */
openNotificationSettings(): Promise<void>
/** Fires when a notification is clicked, asking the renderer to focus a node. Returns unsubscribe. */
onFocusNode(listener: (nodeId: string) => void): () => void
/** Fires when the shell's memory-pressure monitor (core/memory-pressure.ts) sees the host — or
* this process's own RSS — cross a watermark: the renderer answers by running its reclaim
* levers (hidden WebGL contexts, parked terminals). At most one fire a minute, so the levers
* need only be idempotent, not cheap. Returns unsubscribe. Server Edition: never fires (the
* pressure levers run host-side there; a browser tab's memory belongs to the browser). */
onMemoryPressure(listener: (severity: 'warning' | 'critical') => void): () => void
/** Fires when the main window is put away (`'hidden'`: close-to-tray, macOS hide-on-close,
* minimize) or brought back (`'shown'`). The renderer answers by treating every terminal as
* offscreen while hidden (renderer/terminal/window-backgrounded.ts). Returns unsubscribe.
* Server Edition: never fires — a browser tab being hidden is a routine tab switch, not the app
* being put away, so the levers stay on their viewport-only behaviour there. */
onWindowVisibility(listener: (state: 'hidden' | 'shown') => void): () => void
/** Fires when THIS MACHINE's pty-device pressure band changes (core/pty-pressure.ts): the
* renderer raises/lowers the banner that warns before `kern.tty.ptmx_max` stops every new
* terminal from opening. Band changes only, re-sent for a held band at most once every five
* minutes; `level: 'none'` means the banner should come down. Returns unsubscribe.
* Server Edition: never fires — the reaper leg runs host-side only (see src/server/index.ts). */
onPtyPressure(listener: (reading: PtyPressure) => void): () => void
/** Fires when a macOS trackpad gesture (two-finger scroll or pinch) opens or closes on the
* main window — edge transitions from the main process's raw input stream
* (main/trackpad-gesture.ts), a handful per physical gesture. The canvas wheel router uses
* this as ground-truth device identity so a precise-pixel mouse (MX Master) can zoom while the
* trackpad pans. Returns unsubscribe. Server Edition: never fires — a browser tab has no raw
* input stream, and the router keeps its delta-shape heuristics there. */
onCanvasTrackpadGesture(listener: (active: boolean) => void): () => void
/** Raise this Mac's pty-device ceiling (`kern.tty.ptmx_max`) now AND across reboots, behind
* macOS's own administrator-password dialog. Called ONLY from the banner's explicit
* "Fix automatically…" click — never on the app's initiative. macOS only; a dismissed password
* dialog resolves `{ ok: false, canceled: true }`, which is not an error to report or retry. */
raisePtyDeviceLimit(): Promise<PtyLimitFixResult>
/** Answer a Claude permission request via the deterministic hook-reply channel (spec:
* docs/hook-reply-approvals.md). Writes the one-line answer file the held hook is polling
* (`~/.nodeterm/pending/<pendingId>.answer`) on the host the agent runs on — the LOCAL fs for a
* local project, or the remote host over the project's ControlMaster for an SSH project. Resolves
* `true` when the file was written, `false` on any failure (invalid pendingId, unknown node,
* unsupported project, fs/exec error).
*
* `decision` is the original contract and still works alone. An optional structured `answer`
* (`PermissionAnswer`: approve a plan with a follow-on mode, send plan feedback, answer an
* AskUserQuestion) wins over it; core validates it against the held request file on the agent's
* host and refuses (`false`) when that request is gone or the answer does not fit it. A plain
* `allow` on a held AskUserQuestion is refused too — Claude would drop it. */
answerPermission(payload: AnswerPermissionPayload): Promise<boolean>
/** Notify the core that the user READ a finished (done) session on this surface (the unread-clear
* funnel calls it when the node's latest state is `done`). The core marks the node's done inbox
* event(s) resolved (phone Inbox archives the card) and re-sends an 'end' live-update so the
* paired phone dismisses its lingering DONE Live Activity. Fire-and-forget; no-op if the node has
* no unresolved done event. */
ackDone(nodeId: string): void
/** Fires when the host swept a phone read-ack (`~/.nodeterm/acks/<nodeId>.seen`) for a finished
* session: the renderer should drop the node's unread flag WITHOUT re-acking (call
* `clearUnread(id, { external: true })`, so it does not loop back into `ackDone`). Arg is the
* node id. Returns unsubscribe. See core/ack-sweep.ts. */
onUnreadClear(listener: (nodeId: string) => void): () => void
/** Fires on each normalized agent hook event (working/done/waiting/subagent/…). Returns unsubscribe. */
onAgentStatus(listener: (e: NormalizedAgentEvent) => void): () => void
/** The core's per-node agent states as they stand now, read off its agent-status mirror (newest
* `AGENT_STATUS_SNAPSHOT_MAX`; no `state` for an identity-only or restored entry). A relay tab asks
* right after subscribing to `onAgentStatus`, so it does not start blank; a non-editor peer gets
* the shared nodes only. Rejects on a core that predates the channel. */
agentStatusSnapshot(): Promise<AgentStatusSnapshotEntry[]>
/** Report a node's Eco hibernation flag to the core (the renderer owns the flag; the core only
* mirrors it into the agent-status file so the phone can render SLEEPING). Fire-and-forget;
* called on every `setHibernated` change and replayed for the persisted set at boot. */
reportHibernated(nodeId: string, on: boolean): void
/** Seed the core's agent-status mirror with node identities from this renderer's persisted
* agentStatus store (see `@shared/agent-identity-seed`). Fire-and-forget and add-only: the core
* fills only nodes it has no session for, and validates every field. A relay tab's api is a
* deliberate no-op — its nodes belong to another core, whose own renderer seeds it. */
seedAgentIdentity(entries: IdentitySeedEntry[]): void
/** Fires when the core asks this renderer to WAKE a hibernated node NOW (a phone viewer just
* attached to its session over the relay). A nudge with `wakeHibernatedNode`'s exact contract:
* re-read the flag, no-op when not hibernated or not mounted. Returns unsubscribe.
* Desktop-only signal (the relay host lives in the desktop main process); the ws-bridge
* subscribes to nothing and returns a no-op unsubscribe. */
onAgentWake(listener: (nodeId: string) => void): () => void
/** Fires with the CURRENT set of node ids that have a live relay (phone) viewer attached — the
* full set each change, never a delta. Feeds `isNodeWatched` so Eco cannot hibernate a session
* someone is watching from a phone. Desktop-only signal, like `onAgentWake`. */
onRemoteViewers(listener: (nodeIds: string[]) => void): () => void
/** Fires when the core asks this renderer to reload a terminal node's view in place (bump its
* `respawnNonce` — fresh attach to the SAME tmux session) — the phone relay host's
* `node.refresh` verb. A nudge with the `onAgentWake` contract: no-op for an unknown,
* non-terminal or unmounted node. Desktop-only signal (the relay host lives in the desktop
* main process); the ws-bridge subscribes to nothing and returns a no-op unsubscribe. */
onAgentRefreshNode(listener: (nodeId: string) => void): () => void
/** Fires when the core asks this renderer to rename a node on a phone's behalf (the relay
* host's `node.rename` verb, title already sanitized host-side). The renderer routes it
* through the same `renameSession` funnel as the node header. Desktop-only signal, like
* `onAgentRefreshNode`. */
onAgentRenameNode(listener: (payload: { nodeId: string; title: string }) => void): () => void
/** Fires with live subagent transcript chunks while a subagent runs. Returns unsubscribe. */
onSubagentActivity(listener: (e: SubagentActivity) => void): () => void
/** Fires when an agent's `nodeterm` CLI requests a canvas action. Returns unsubscribe. */
onAgentControl(
listener: (cmd: {
requestId: string
sourceNodeId: string
verb: string
args: Record<string, string>
}) => void
): () => void
/** Reply to an agent control request (resolves the awaiting CLI call in main). */
sendAgentControlResult(payload: {
requestId: string
ok: boolean
message?: string
result?: unknown
error?: string
}): void
/** The `browser` verb resolve round-trip (S8 PR 7): main asks the renderer to resolve a source
* node's owning project, control-capability and the LIVE per-project capability value. The
* renderer answers over `sendBrowserControlResolveResult` and NEVER runs a CDP command. */
onBrowserControlResolve(
listener: (req: { requestId: string; sourceNodeId: string; browserNodeId?: string }) => void
): () => void
/** Answer a browser-control resolve. `ok:false` carries a named refusal; `ok:true` carries the
* facts main turns into its own (owner + capability + CDP-gate) decision. `sourceTitle`/
* `browserTitle` are for the cookie-read trace only (PR 9) — never a security input. */
sendBrowserControlResolveResult(payload: {
requestId: string
ok: boolean
refusal?: string
projectId?: string
projectCwd?: string
sourceControlCapable?: boolean
capabilityOn?: boolean
sourceTitle?: string
browserTitle?: string
}): void
/** The phone Chat verbs' round-trip (main/remote/host-chat.ts): main asks this renderer for a
* node's chat status, or to send a phone message through the ⌘M composer's own gate. Desktop
* only — the phone relay host lives in the Electron main process; the browser and relay bridges
* subscribe to nothing. */
onHostChatQuery(listener: (q: HostChatQuery) => void): () => void
/** Answer a `onHostChatQuery` request. */
sendHostChatReply(reply: HostChatReply): void
/** Agent messaging (the `send`/`reply` control verbs): run one delivery in main, where the
* scope check, the per-project switch, flow control and the pane probes all live. The reply is
* already rendered as a control reply — Canvas forwards it verbatim. */
agentMessage: {
deliver(req: AgentMessageDeliverRequest): Promise<AgentMessageReply>
/** Deliver one mentioned session's copy of a board comment the local user just posted, through
* the same gates. `result` carries the typed outcome the comment row renders. Desktop only: the
* browser and relay bridges answer `notPermitted: unsupported-edition`. */
deliverBoardComment(req: BoardCommentDeliverRequest): Promise<AgentMessageReply>
}
/** Board dispatch (#1051): the renderer REPORTS its in-memory dispatch map to core, replaced
* whole on each change, so the read-only `issues` control verb can show it beside an issue
* (@shared/board-dispatch-report). Display only. Desktop and Server Edition are real; a relay
* tab's board is the host's, so there it is inert. */
boardDispatch: {
report(entries: import('./board-dispatch-report').BoardDispatchReportEntry[]): void
}
/** Station-failure notices (@shared/station-notice, src/core/agents/station-notice.ts): the
* chips on an orchestrator whose stations stopped, and the renderer's DROPPED verdicts, which
* are the one trigger fact core cannot measure. Desktop and Server Edition are real; a relay
* tab's stations belong to the host's core, so there it is inert. */
stationNotice: {
list(): Promise<import('./station-notice').StationNoticeView[]>
onChanged(cb: (views: import('./station-notice').StationNoticeView[]) => void): () => void
reportDropped(nodeId: string, dropped: boolean): void
}
/** Station task outcomes (`report-outcome`, src/core/station-outcome-store.ts): what each station
* reported about its own task (durable across a restart) — what a `--after-success` wait reads. Desktop and
* Server Edition are real; a relay tab's stations belong to the host's core, so there it is inert
* (and its launch delivery is refused anyway). */
stationOutcome: {
list(): Promise<import('./station-outcome').StationOutcomeRecord[]>
onChanged(cb: (records: import('./station-outcome').StationOutcomeRecord[]) => void): () => void
}
/** Stations with unfinished HANDED-OVER work (src/core/station-handover.ts) — what plain
* `--after` reads so it never releases on a `done` from before that work arrived. Desktop and
* Server Edition are real; a relay tab's stations belong to the host's core, so there it is
* inert (and its launch delivery is refused anyway). */
stationHandover: {
list(): Promise<import('./station-handover').StationHandoverRecord[]>
onChanged(cb: (records: import('./station-handover').StationHandoverRecord[]) => void): () => void
}
}