Skip to content

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.

feat(core): one local-spawn option builder for headless starts

reviewc4e8ba6a92b4
diff --git a/src/server/headless-node-factory.ts b/src/server/headless-node-factory.ts
index c9b16c9e3..1e121cd27 100644
--- a/src/server/headless-node-factory.ts
+++ b/src/server/headless-node-factory.ts
@@ -18,6 +18,7 @@ import {
type NodeColor
} from '../shared/node-colors'
import { applyStickyWrite, parseStickyArgs, resolveStickyRef } from '../shared/sticky-write'
+import { localNodePtyOptions } from '../shared/node-pty-options'
import type { WorkspaceStore } from '../core/workspace-store'
import {
AGENT_CONFIG,
@@ -481,16 +482,7 @@ function ungroupPersistedNodes(
}
function ptyOptions(project: Project, node: CanvasNodeState): PtyCreateOptions {
- return {
- cwd: node.cwd || project.cwd,
- cols: TERMINAL_COLS,
- rows: TERMINAL_ROWS,
- persistKey: node.id,
- ownerProjectId: project.id,
- ...(node.agentId ? { agentId: node.agentId } : {}),
- ...(node.agentModel ? { agentModel: node.agentModel } : {}),
- ...(node.accountId ? { accountId: node.accountId } : {})
- }
+ return localNodePtyOptions(project, node, { cols: TERMINAL_COLS, rows: TERMINAL_ROWS })
}
/**
diff --git a/src/shared/node-pty-options.test.ts b/src/shared/node-pty-options.test.ts
new file mode 100644
index 000000000..dd616c711
--- /dev/null
+++ b/src/shared/node-pty-options.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+import { HEADLESS_COLS, HEADLESS_ROWS, localNodePtyOptions } from './node-pty-options'
+
+const project = { id: 'p1', cwd: '/repo' }
+
+describe('localNodePtyOptions', () => {
+ it('builds the local spawn a node gets, falling back to the project cwd', () => {
+ expect(localNodePtyOptions(project, { id: 'n1' }, { cols: 80, rows: 24 })).toEqual({
+ cwd: '/repo',
+ cols: 80,
+ rows: 24,
+ persistKey: 'n1',
+ ownerProjectId: 'p1'
+ })
+ })
+
+ it('carries shell, agent, model and account only when set, and prefers the node cwd', () => {
+ expect(
+ localNodePtyOptions(
+ project,
+ { id: 'n2', cwd: '/repo/sub', shell: '/bin/zsh', agentId: 'claude', agentModel: 'm', accountId: 'a1' },
+ { cols: HEADLESS_COLS, rows: HEADLESS_ROWS }
+ )
+ ).toEqual({
+ cwd: '/repo/sub',
+ cols: 120,
+ rows: 36,
+ persistKey: 'n2',
+ ownerProjectId: 'p1',
+ shell: '/bin/zsh',
+ agentId: 'claude',
+ agentModel: 'm',
+ accountId: 'a1'
+ })
+ })
+
+ // The key set IS the contract with TerminalNode's local create (see the module comment): a key
+ // added there and forgotten here makes a headless-started session differ from a mounted one.
+ it('never emits keys beyond the local-spawn set', () => {
+ const keys = Object.keys(
+ localNodePtyOptions(
+ project,
+ { id: 'n3', cwd: '/x', shell: 's', agentId: 'codex', agentModel: 'm', accountId: 'a' },
+ { cols: 1, rows: 1 }
+ )
+ ).sort()
+ expect(keys).toEqual(
+ ['accountId', 'agentId', 'agentModel', 'cols', 'cwd', 'ownerProjectId', 'persistKey', 'rows', 'shell'].sort()
+ )
+ })
+})
diff --git a/src/shared/node-pty-options.ts b/src/shared/node-pty-options.ts
new file mode 100644
index 000000000..b4c190139
--- /dev/null
+++ b/src/shared/node-pty-options.ts
@@ -0,0 +1,40 @@
+import type { CanvasNodeState, Project, PtyCreateOptions } from './types'
+
+/** Size of a headless spawn until a real viewer attaches and resizes it (tmux redraws then). */
+export const HEADLESS_COLS = 120
+export const HEADLESS_ROWS = 36
+
+type NodeSpawnFields = Pick<CanvasNodeState, 'id' | 'cwd' | 'shell' | 'agentId' | 'agentModel' | 'accountId'>
+
+/**
+ * The PtyCreateOptions a LOCAL spawn of `node` uses when no viewer initiates it: the desktop
+ * headless launcher (#925) and the Server Edition's canvas factory.
+ *
+ * It mirrors the local fields of TerminalNode's own `transport.create`: `shell`, `cwd`,
+ * `persistKey`, `ownerProjectId`, `agentId`, `agentModel` and `accountId`. The session a viewer later
+ * warm-attaches to therefore carries the env it would have had if the viewer had spawned it. Two
+ * deliberate differences:
+ * - `cwd` falls back to the project root. A headless spawn has no mounted node to inherit a
+ * working directory from, and the Server Edition always did this.
+ * - No `sshRemote` / `requireRemote` / `clearEnv`. Headless starts are local-only in v1, and
+ * clearEnv is a one-shot restart flag.
+ * TerminalNode itself is NOT moved onto this builder: its create also serves warm and SSH attaches,
+ * and a cwd-less node there spawns in $HOME today.
+ */
+export function localNodePtyOptions(
+ project: Pick<Project, 'id' | 'cwd'>,
+ node: NodeSpawnFields,
+ size: { cols: number; rows: number }
+): PtyCreateOptions {
+ return {
+ cwd: node.cwd || project.cwd,
+ cols: size.cols,
+ rows: size.rows,
+ persistKey: node.id,
+ ownerProjectId: project.id,
+ ...(node.shell ? { shell: node.shell } : {}),
+ ...(node.agentId ? { agentId: node.agentId } : {}),
+ ...(node.agentModel ? { agentModel: node.agentModel } : {}),
+ ...(node.accountId ? { accountId: node.accountId } : {})
+ }
+}