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
feat(server): run verb and --run-now on the Server Edition (#925)
review7e97614b4fa5
diff --git a/src/server/canvas-control.ts b/src/server/canvas-control.tsindex 918d45132..91e336758 100644--- a/src/server/canvas-control.ts+++ b/src/server/canvas-control.ts@@ -229,6 +229,7 @@ export async function initServerCanvasControl(rename: (sourceNodeId, args) => factory.rename(sourceNodeId, args),color: (sourceNodeId, args) => factory.color(sourceNodeId, args),sticky: (sourceNodeId, args) => factory.sticky(sourceNodeId, args),+ run: (sourceNodeId, args, verified) => factory.run(sourceNodeId, args, verified),settings: async (sourceNodeId, args) =>serverSettingsControl({diff --git a/src/server/control-unsupported.test.ts b/src/server/control-unsupported.test.tsindex 0a55c664b..511deace9 100644--- a/src/server/control-unsupported.test.ts+++ b/src/server/control-unsupported.test.ts@@ -183,9 +183,22 @@ describe('the enabled Server Edition handler parses and dispatches the v1 surfaccolor: vi.fn(async () => ({ ok: true as const, result: { colored: ['term-target'] } })),sticky: vi.fn(async () => ({ ok: true as const, result: { id: 'sticky-new' } })),settings: vi.fn(async () => ({ ok: true as const, message: 'settings' })),+ run: vi.fn(async () => ({ ok: true as const })),deliver: vi.fn(async () => ({ ok: true as const, message: 'queued' }))})+ it('routes run to the factory (#925)', async () => {+ const a = actions()+ const handler = createServerEditionControlHandler(a)+ await handler({ verb: 'run', nodeId: 'src', args: { node: 'n1' }, verified: true })+ expect(a.run).toHaveBeenCalledWith('src', { node: 'n1' }, true)+ // The shared parser still requires --node before the action is reached.+ await expect(+ handler({ verb: 'run', nodeId: 'src', args: {}, verified: true })+ ).resolves.toEqual({ ok: false, error: 'run requires --node <id>' })+ expect(a.run).toHaveBeenCalledTimes(1)+ })+it('routes settings to its action, after the shared allowlist parse', async () => {const a = actions()const handler = createServerEditionControlHandler(a)diff --git a/src/server/control-unsupported.ts b/src/server/control-unsupported.tsindex 84dab76af..73d655ccf 100644--- a/src/server/control-unsupported.ts+++ b/src/server/control-unsupported.ts@@ -95,6 +95,8 @@ export interface ServerEditionControlActions {sticky(sourceNodeId: string, args: Record<string, string>): Promise<ServerControlReply>/** Reads only; `--set` is refused by name (src/server/settings-control.ts). */settings(sourceNodeId: string, args: Record<string, string>): Promise<ServerControlReply>+ /** `run --node <id>` (#925): deliver a retained launch for the node's creator. */+ run(sourceNodeId: string, args: Record<string, string>, verified: boolean): Promise<ServerControlReply>deliver(input: {verb: 'send' | 'reply' | 'notify'sourceNodeId: string@@ -116,7 +118,8 @@ const SERVER_V1_VERBS: ReadonlySet<string> = new Set(['reply','notify','sticky',- 'settings'+ 'settings',+ 'run'])/** A permanent, verb-specific refusal used only while canvas control itself is enabled. */@@ -181,6 +184,8 @@ export function createServerEditionControlHandler(actions: ServerEditionControlAreturn actions.sticky(nodeId, command.args)case 'settings':return actions.settings(nodeId, command.args)+ case 'run':+ return actions.run(nodeId, command.args, verified)case 'send':case 'reply':case 'notify':diff --git a/src/server/headless-node-factory.test.ts b/src/server/headless-node-factory.test.tsindex 3d18d4e35..6ed5cb0fb 100644--- a/src/server/headless-node-factory.test.ts+++ b/src/server/headless-node-factory.test.ts@@ -1311,4 +1311,123 @@ describe('HeadlessNodeFactory', () => {const node = (await store.load({ sideline: false })).projects[0].nodes.find((n) => n.id === id)expect(node?.pendingLaunch).toMatchObject({ command: 'printf hello', manualOnly: true })})++ it('accepts --run-now on open verbs as a no-op: server opens are already immediate (#925)', async () => {+ const reply = await factory.openTerminal('term-source', { cwd: projectDir, cmd: 'printf hi', 'run-now': '' }, true)+ expect(reply.ok).toBe(true)+ const id = (reply.result as { id: string }).id+ expect(pty.sends).toEqual([{ nodeId: id, text: 'printf hi' }])+ })++ it('accepts --run-now on open-agent as the same no-op (#925)', async () => {+ const reply = await factory.openAgent('term-source', { agent: 'claude', prompt: 'brief', 'run-now': '' }, true)+ expect(reply.ok).toBe(true)+ const id = (reply.result as { id: string }).id+ expect(pty.sends).toEqual([{ nodeId: id, text: "claude 'brief'" }])+ })++ it('run delivers a retained launch for the node owner (#925)', async () => {+ const spy = vi.spyOn(pty, 'writeHeadless').mockReturnValue(false)+ const opened = await factory.openTerminal('term-source', { cwd: projectDir, cmd: 'printf hi' }, true)+ const id = (opened.result as { id: string }).id+ spy.mockRestore()+ pty.sends.length = 0+ const reply = await factory.run('term-source', { node: id }, true)+ expect(reply).toMatchObject({ ok: true, result: { started: true, startedIds: [id] } })+ expect(pty.sends).toEqual([{ nodeId: id, text: 'printf hi' }])+ const node = (await store.load({ sideline: false })).projects[0].nodes.find((n) => n.id === id)+ expect(node?.pendingLaunch).toBeUndefined()+ })++ it('run saves its claim before typing; a failed delivery stays queued and names the reason (#925)', async () => {+ // An --after arm is the one held launch that has never been attempted, so the claim below is+ // run's own write-ahead and not one left behind by the open.+ states['term-upstream'] = 'working'+ const opened = await factory.openTerminal(+ 'term-source',+ { cwd: projectDir, cmd: 'printf hi', after: 'term-upstream' },+ true+ )+ const id = (opened.result as { id: string }).id+ expect((await store.load({ sideline: false })).projects[0].nodes.find((n) => n.id === id)?.pendingLaunch)+ .toMatchObject({ attempted: false })+ expect(pty.sends).toEqual([])+ let durableAtFirstWrite: ReturnType<WorkspaceStore['load']> | undefined+ const refuse = vi.spyOn(pty, 'writeHeadless').mockImplementation(() => {+ durableAtFirstWrite ??= store.load({ sideline: false })+ return false+ })+ const reply = await factory.run('term-source', { node: id }, true)+ refuse.mockRestore()+ expect(reply).toMatchObject({+ ok: true,+ result: { started: false, startedIds: [], queued: true, queuedIds: [id], reason: 'cancelled' }+ })+ const claimed = (await durableAtFirstWrite!).projects[0].nodes.find((n) => n.id === id)+ expect(claimed?.pendingLaunch).toMatchObject({ command: 'printf hi', attempted: true, manualOnly: true })+ expect(pty.sends).toEqual([])+ const node = (await store.load({ sideline: false })).projects[0].nodes.find((n) => n.id === id)+ expect(node?.pendingLaunch).toMatchObject({ command: 'printf hi', attempted: true, manualOnly: true })+ // manualOnly: the dependency finishing never replays it.+ await factory.refreshArmed({ nodeId: 'term-upstream', state: 'done' })+ expect(pty.sends).toEqual([])+ })++ it('run refuses a non-owner, an unknown node and a node with nothing queued (#925)', async () => {+ const opened = await factory.openTerminal('term-source', { cwd: projectDir, cmd: 'printf hi' }, true)+ const id = (opened.result as { id: string }).id+ expect((await factory.run('someone-else', { node: id }, true)).error).toMatch(/^run-not-owner:/)+ expect((await factory.run('term-source', { node: id }, true)).error).toMatch(/^run-nothing-queued:/)+ expect((await factory.run('term-source', { node: id, cmd: 'x' }, true)).error).toMatch(/not supported/)+ expect((await factory.run('term-source', { node: id }, false)).error).toMatch(/^run-identity-refused:/)+ // Owned by this caller but gone from the canvas: the desktop's own wording.+ ownership.record('term-vanished', { sourceNodeId: 'term-source', projectId: 'project-1' })+ expect((await factory.run('term-source', { node: 'term-vanished' }, true)).error)+ .toBe('run: no node with id term-vanished')+ })++ it('run marks an agent it freshly spawned as awaiting its first working turn, as open does (#925)', async () => {+ // The open's spawn fails, so the node has no session and was never marked; run spawns it fresh.+ const spawn = vi.spyOn(pty, 'createHeadless').mockResolvedValueOnce({ sessionId: '', fresh: true })+ const opened = await factory.openAgent('term-source', { agent: 'claude', prompt: 'brief' }, true)+ spawn.mockRestore()+ expect(opened.ok).toBe(false)+ const agentNode = (opened.result as { id: string }).id+ expect(await factory.run('term-source', { node: agentNode }, true))+ .toMatchObject({ ok: true, result: { started: true } })+ // A dependent armed now must not be released by the fresh CLI's boot `done` blip.+ const dependent = await factory.openTerminal(+ 'term-source',+ { cwd: projectDir, cmd: 'printf after', after: agentNode },+ true+ )+ const depId = (dependent.result as { id: string }).id+ pty.sends.length = 0+ await factory.refreshArmed({ nodeId: agentNode, state: 'done' })+ expect(pty.sends).toEqual([])+ await factory.refreshArmed({ nodeId: agentNode, state: 'working' })+ await factory.refreshArmed({ nodeId: agentNode, state: 'done' })+ expect(pty.sends).toEqual([{ nodeId: depId, text: 'printf after' }])+ })++ it('run refuses an SSH node before any claim (#925)', async () => {+ const held = { after: [], command: 'printf hi', executor: 'server' as const, attempted: false }+ const workspace = await store.load({ sideline: false })+ workspace.projects[0].nodes.push({+ ...terminal('term-remote', 'Remote'),+ sshRemoteTmux: true,+ pendingLaunch: held+ })+ await store.save(workspace)+ ownership.record('term-remote', { sourceNodeId: 'term-source', projectId: 'project-1' })+ const reply = await factory.run('term-source', { node: 'term-remote' }, true)+ expect(reply).toEqual({+ ok: false,+ error: 'run-remote-unsupported: term-remote is an SSH node; the Server Edition cannot start it'+ })+ expect(pty.creates).toEqual([])+ expect(pty.sends).toEqual([])+ const node = (await store.load({ sideline: false })).projects[0].nodes.find((n) => n.id === 'term-remote')+ expect(node?.pendingLaunch).toEqual(held)+ })})diff --git a/src/server/headless-node-factory.ts b/src/server/headless-node-factory.tsindex ee71a13c4..ba470c2de 100644--- a/src/server/headless-node-factory.ts+++ b/src/server/headless-node-factory.ts@@ -36,6 +36,7 @@ import {import { assembleLaunchCommand } from '../shared/agents/launch'import type { AgentState, NormalizedAgentEvent } from '../shared/agents/normalize'import { oneLine } from '../shared/one-line'+import { isRemoteSessionNode } from '../shared/worktree'import { UNKNOWN_CODEX_CLI_CAPS } from '../shared/types'import type {BridgeLink,@@ -1041,6 +1042,55 @@ export class HeadlessNodeFactory {})}+ /** `run --node <id>` (#925): deliver a node's retained launch now. Server v1 ownership applies:+ * only nodes the caller spawned during this server run. */+ run(sourceNodeId: string, args: Record<string, string>, verified: boolean): Promise<ServerControlReply> {+ return this.runExclusive(async () => {+ if (!verified) {+ return { ok: false, error: 'run-identity-refused: Server Edition canvas control requires verified node identity' }+ }+ const flagError = unsupportedFlags(args, new Set(['node', 'project']))+ if (flagError) return { ok: false, error: `run: ${flagError}` }+ const id = (args.node ?? '').trim()+ if (!this.ownsSpawn(sourceNodeId, id)) return this.ownershipRefusal('run', sourceNodeId, id)+ const workspace = await this.deps.workspaceStore.load({ sideline: false })+ const project = workspace.projects.find((p) => p.nodes.some((n) => n.id === id))+ const node = project?.nodes.find((n) => n.id === id)+ if (!project || !node) return { ok: false, error: `run: no node with id ${id}` }+ const held = node.pendingLaunch+ if (!held?.command) return { ok: false, error: `run-nothing-queued: ${id} has no queued launch` }+ // A remote node is NEVER spawned locally, and this launcher only spawns locally. Refuse+ // before the claim, leaving the held launch untouched (the desktop's startHeadless guard).+ if (isRemoteSessionNode(node)) {+ return {+ ok: false,+ error: `run-remote-unsupported: ${id} is an SSH node; the Server Edition cannot start it`+ }+ }+ // Write-ahead, exactly as open() does before its own delivery.+ node.pendingLaunch = { ...held, attempted: true, manualOnly: true }+ await this.deps.workspaceStore.save(workspace)+ const launched = await this.launch(project, node, held.command)+ // As open() does: an agent this spawned fresh has not had its first real turn yet, so a+ // later `--after` on it must not be released by the CLI's boot `done` blip.+ if (node.agentId && launched.fresh) this.awaitingFirstWorking.add(id)+ if (launched.outcome === 'delivered') node.pendingLaunch = undefined+ await this.deps.workspaceStore.save(workspace)+ this.publish(project, [node])+ return launched.outcome === 'delivered'+ ? {+ ok: true,+ message: `started ${id}; agent startup is not confirmed`,+ result: { ids: [id], id, started: true, startedIds: [id], queued: false, queuedIds: [] }+ }+ : {+ ok: true,+ message: `${id} stays queued (${launched.reason}); launch retained for Run now`,+ result: { ids: [id], id, started: false, startedIds: [], queued: true, queuedIds: [id], reason: launched.reason }+ }+ })+ }+color(sourceNodeId: string, args: Record<string, string>): Promise<ServerControlReply> {return this.runExclusive(async () => {const flagError = unsupportedFlags(args, new Set(['node', 'color']))@@ -1088,9 +1138,10 @@ export class HeadlessNodeFactory {return this.runExclusive(async () => {const flagError = unsupportedFlags(args,+ // `run-now` (#925) is accepted and ignored: a server open already delivers immediately.verb === 'open-terminal'- ? new Set(['count', 'cwd', 'cmd', 'after', 'project'])- : new Set(['agent', 'count', 'cwd', 'prompt', 'after', 'project', 'model'])+ ? new Set(['count', 'cwd', 'cmd', 'after', 'project', 'run-now'])+ : new Set(['agent', 'count', 'cwd', 'prompt', 'after', 'project', 'model', 'run-now']))if (flagError) return { ok: false, error: `${verb}: ${flagError}` }if (!verified) {