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(mirror): advertise custom agents to the phone as derived binaries
reviewb21e7bb67062
diff --git a/CLAUDE.md b/CLAUDE.mdindex 91784a8d0..968a3c6a9 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -2107,7 +2107,16 @@ else, and its context links must keep classifying across restarts).`settings` block (`claudePermissionMode`/`autoSupported`/`claudeAccounts`) so the phone canlaunch agents with the desktop's permission mode + managed accounts, and SSH slices get their**per-host** settings (remote CLI caps + host-matched accounts) injected via- `remote-status-push`'s `settingsFor` dep.+ `remote-status-push`'s `settingsFor` dep. `settings.customAgents` (`[{id, label, baseAgent?,+ binaries}]`) lets the phone chat with a custom agent: built ONLY by `core/mirror-custom-agents.ts`+ (one definition for all three providers — local file, which relay `projects.list` also serves,+ SSH slices, Server Edition), `binaries` = `binariesFor` from the pane-owner predicate, published+ only when every name fits the plain alphabet `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$` (else `[]`) —+ the builder enforces it because the tokenizer can "name" a slice of a secret (`oauth2:ghp_…` out+ of a git URL, a quoted env value, a `${env:…}` template). **Never put a custom agent's raw+ `launchCmd`/`args`/`env` in the mirror** — they carry API keys and the file lands on every SSH+ host. `binariesFor` resolves a BLANK launch command with a *builtin* `baseAgent` to the base's+ binaries (what `resolveAgentConfig` actually launches).- **Hook installers** — `src/core/agents/hooks/` holds per-agent hook services + an installerregistry `MANAGED_HOOK_INSTALLERS`. `managed-script.ts` builds the POSIX hook script thatPOSTs to the server (env-gated: a no-op in the user's normal terminals, active only indiff --git a/docs/mobile-chat-view.md b/docs/mobile-chat-view.mdindex 7c25217f0..05c19cadc 100644--- a/docs/mobile-chat-view.md+++ b/docs/mobile-chat-view.md@@ -156,6 +156,36 @@ N/A (it serves no phone relay; its bridge subscription is inert).- **Answer**: Swift port of `buildPermissionDecision` (validates against the pending request file),written atomically (`umask 077`, tmp + mv) from stdin; `pendingId` regex-validated before any path.+### 3.3a Custom agents (mirror `settings.customAgents`, desktop side implemented)++A custom agent's node carries `agentId: "custom:<uuid>"`. On SSH the phone can neither know its base+harness (the chat capability follows it) nor name its binary (the pane-owner check before a send) on+its own, so the agent-status mirror's `settings` block advertises them:++```json+"settings": {+ "customAgents": [+ { "id": "custom:3f2a…", "label": "Proxy Claude", "baseAgent": "claude", "binaries": ["claude"] },+ { "id": "custom:9b1c…", "label": "My agent", "binaries": ["my-agent"] },+ { "id": "custom:77de…", "label": "Wrapped", "baseAgent": "codex", "binaries": [] }+ ]+}+```++- Present in every mirror the phone reads: the local `agent-status.json` (desktop and Server Edition;+ the relay's `projects.list` serves this same file) and each SSH project's pushed slice+ (`agent-status-<projectId>.json`, via `settingsFor`). Absent on older desktops ⇒ refuse every custom+ node, as before.+- `binaries` is the desktop predicate's `binariesFor(id, settings.customAgents)`, published only when+ every name matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$` — the BUILDER enforces this alphabet, because a+ derived "name" can be a slice of a secret (`oauth2:ghp_…` from a git URL, a quoted env value, a+ `${env:…}` template). **Empty = cannot be named honestly** (e.g. `bash -lc …`, or a name outside the+ alphabet): refuse, never guess. The phone still validates each name (`isPlainBinaryName`) and refuses otherwise.+- `baseAgent` is present only when it is a builtin id. Chat on SSH: only when it is `claude` (the only+ harness the Swift parser reads); on relay the desktop decides (`canChat(capabilityAgentId(…))`).+- Never contains the raw launch command, args or env — they routinely hold API keys and proxy URLs,+ and the slice is a file on the SSH host. `label` is display text (≤200 chars).+### 3.4 Live updates & paging (both transports)- First open: 256 KB tail; scroll near top → 512 KB older pages; merge by `key`; carried tool results;diff --git a/src/core/agent-status-mirror.ts b/src/core/agent-status-mirror.tsindex 1263872bf..cfd8fa21f 100644--- a/src/core/agent-status-mirror.ts+++ b/src/core/agent-status-mirror.ts@@ -194,6 +194,32 @@ export interface MirrorSettings {* *this* host and generalizes to neither another agent nor another machine.*/codexApprovalValues?: string[]+ /**+ * The user's custom agents (Settings → Agents), reduced to what a phone needs to chat with one:+ * which builtin harness it inherits (the chat capability follows `baseAgent`) and which binary+ * names its pane runs as (the pane-owner check before a send). Built ONLY by+ * `mirrorCustomAgents` (`core/mirror-custom-agents.ts`) — never the raw `launchCmd`/`args`/`env`,+ * which routinely carry API keys and proxy URLs. Absent on old files ⇒ a reader refuses every+ * custom node, exactly as before this field existed.+ */+ customAgents?: MirrorCustomAgent[]+}++/** One custom agent as the mirror advertises it (see MirrorSettings.customAgents). */+export interface MirrorCustomAgent {+ /** `custom:<uuid>` — the node's `agentId`. */+ id: string+ label: string+ /** The builtin harness it inherits capabilities from; absent for a baseless custom agent. */+ baseAgent?: string+ /**+ * Plain binary basenames the pane-owner predicate would accept — `binariesFor(id, customAgents)`,+ * published only when every name matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$` (enforced by the+ * builder). EMPTY when the launch command cannot be named honestly (e.g. `bash -lc …`) or the+ * derived name is outside that alphabet (a URL, credential, quoted value or `${env:…}` template);+ * a reader must then refuse, never fall back to a guess.+ */+ binaries: string[]}export interface MirrorFile {diff --git a/src/core/mirror-custom-agents.test.ts b/src/core/mirror-custom-agents.test.tsnew file mode 100644index 000000000..c705d3524--- /dev/null+++ b/src/core/mirror-custom-agents.test.ts@@ -0,0 +1,107 @@+import { describe, it, expect } from 'vitest'+import fs from 'fs'+import path from 'path'+import { mirrorCustomAgents } from './mirror-custom-agents'+import { buildFile, filterMirrorForNodes } from './agent-status-mirror'+import { binariesFor } from '@shared/agents/pane-owner-predicate'+import type { CustomAgent } from '@shared/types'++const SECRET = 'sk-ant-SECRET-123'++const agents: CustomAgent[] = [+ {+ id: 'custom:proxy',+ label: 'Proxy Claude',+ launchCmd: '',+ baseAgent: 'claude',+ env: { ANTHROPIC_AUTH_TOKEN: SECRET, ANTHROPIC_BASE_URL: 'https://proxy.example' },+ args: `--api-key ${SECRET}`+ },+ { id: 'custom:npx', label: 'NPX agent', launchCmd: `ANTHROPIC_API_KEY=${SECRET} npx -y @acme/[email protected] --token ${SECRET}` },+ { id: 'custom:shell', label: 'Shell wrapped', launchCmd: `bash -lc "TOKEN=${SECRET} run-me"`, baseAgent: 'codex' },+ { id: 'custom:bin', label: 'Plain', launchCmd: '/opt/bin/aider --model x', baseAgent: 'grok' }+]++describe('mirrorCustomAgents', () => {+ it('derives binaries with the SAME logic as the pane-owner predicate', () => {+ const out = mirrorCustomAgents(agents)+ for (const a of agents) {+ const row = out.find((r) => r.id === a.id)!+ expect(row.binaries).toEqual([...(binariesFor(a.id, agents) ?? [])])+ }+ expect(out.map((r) => [r.id, r.binaries])).toEqual([+ ['custom:proxy', ['claude']],+ ['custom:npx', ['my-agent']],+ ['custom:shell', []], // unnameable ⇒ empty ⇒ the phone refuses, never guesses+ ['custom:bin', ['aider']]+ ])+ })++ it('carries id, label and a valid baseAgent — and nothing else', () => {+ const out = mirrorCustomAgents(agents)+ expect(out[0]).toEqual({ id: 'custom:proxy', label: 'Proxy Claude', baseAgent: 'claude', binaries: ['claude'] })+ expect(out[1]).toEqual({ id: 'custom:npx', label: 'NPX agent', binaries: ['my-agent'] })+ for (const row of out) expect(Object.keys(row).sort()).toEqual(+ row.baseAgent ? ['baseAgent', 'binaries', 'id', 'label'] : ['binaries', 'id', 'label']+ )+ })++ it('never leaks a raw launch command, args or env into the mirror file', () => {+ const doc = buildFile({}, 1000, undefined, { customAgents: mirrorCustomAgents(agents) })+ const json = JSON.stringify(doc)+ expect(json).not.toContain(SECRET)+ expect(json).not.toContain('proxy.example')+ expect(json).not.toContain('launchCmd')+ expect(json).not.toContain('"env"')+ expect(json).not.toContain('"args"')+ expect(json).not.toContain('npx -y')+ expect(json).not.toContain('@acme')+ expect(json).not.toContain('/opt/bin')+ expect(doc.settings?.customAgents?.length).toBe(4)+ })++ it('publishes [] for a derived name outside the plain alphabet — a URL/credential/quote/template never ships', () => {+ const risky: CustomAgent[] = [+ { id: 'custom:uvx', label: 'a', launchCmd: 'uvx --from git+https://oauth2:[email protected] agent' },+ { id: 'custom:url', label: 'b', launchCmd: 'https://user:TOKEN@host' },+ { id: 'custom:quote', label: 'c', launchCmd: 'API_KEY="sk-ant-a sk-ant-b" my-agent' },+ { id: 'custom:tmpl', label: 'd', launchCmd: '${env:AGENT_BIN} --x' },+ { id: 'custom:long', label: 'e', launchCmd: 'x'.repeat(65) }+ ]+ const out = mirrorCustomAgents(risky)+ expect(out.map((r) => r.binaries)).toEqual([[], [], [], [], []])+ const json = JSON.stringify(buildFile({}, 1000, undefined, { customAgents: out }))+ for (const leak of ['SECRET', 'TOKEN', 'ghp_', 'oauth2', 'sk-ant', 'AGENT_BIN', '${env'])+ expect(json).not.toContain(leak)+ })++ it('drops malformed records and non-custom ids, and a baseAgent that is not a builtin', () => {+ const junk = [+ null,+ { id: 'claude', label: 'Hijack', launchCmd: 'claude' },+ { id: 42, label: 'x', launchCmd: 'y' },+ { id: 'custom:ok', label: 7, launchCmd: 'ok-agent', baseAgent: 'constructor' },+ { id: 'custom:ok2', launchCmd: 'ok2' }+ ] as unknown as CustomAgent[]+ expect(mirrorCustomAgents(junk)).toEqual([+ { id: 'custom:ok', label: 'custom:ok', binaries: ['ok-agent'] },+ { id: 'custom:ok2', label: 'custom:ok2', binaries: ['ok2'] }+ ])+ expect(mirrorCustomAgents(undefined)).toEqual([])+ })++ it('is stripped from slices by filterMirrorForNodes like every settings field (the slice gets its own)', () => {+ const doc = buildFile({}, 1000, undefined, { customAgents: mirrorCustomAgents(agents) })+ expect('settings' in filterMirrorForNodes(doc, new Set())).toBe(false)+ })++ // Every surface the phone reads the mirror from: the local file (main + Server Edition providers,+ // which is also what relay `projects.list` serves) and the per-SSH-project slice (`settingsFor`).+ it('is wired into every settings provider', () => {+ const root = path.resolve(__dirname, '..')+ const main = fs.readFileSync(path.join(root, 'main/index.ts'), 'utf8')+ const server = fs.readFileSync(path.join(root, 'server/index.ts'), 'utf8')+ expect(main.match(/customAgents: mirrorCustomAgents\(/g)?.length).toBe(2)+ expect(server.match(/customAgents: mirrorCustomAgents\(/g)?.length).toBe(1)+ })+})diff --git a/src/core/mirror-custom-agents.ts b/src/core/mirror-custom-agents.tsnew file mode 100644index 000000000..a8900a7b7--- /dev/null+++ b/src/core/mirror-custom-agents.ts@@ -0,0 +1,58 @@+// The custom-agent list the agent-status mirror advertises to the phone (MirrorSettings.customAgents).+//+// One definition consumed by every settings provider — the desktop's local file, each SSH project's+// slice (`settingsFor`), and the Server Edition — so the surfaces cannot drift. The local file is+// also what the relay's `projects.list` serves, so that surface needs no wiring of its own.+//+// SECURITY: a `CustomAgent` carries `launchCmd`, `args` and `env`, and all three routinely hold+// secrets (an `ANTHROPIC_AUTH_TOKEN`, a `--api-key`, a proxy URL). The mirror is a plain file on+// this machine AND on every SSH host a project runs on. So this builds each row field by field from+// an allowlist and publishes only DERIVED binary basenames, never the command they came from —+// and only names in a strict plain alphabet (`PLAIN_BINARY`), because a derived "name" can itself+// be a slice of a secret-bearing URL or env value.++import type { CustomAgent } from '@shared/types'+import { AGENT_CONFIG } from '@shared/agents/config'+import { binariesFor } from '@shared/agents/pane-owner-predicate'+import type { MirrorCustomAgent } from './agent-status-mirror'++/**+ * The only shape a published binary name may have. `binaryFromLaunchCmd` is a best-effort+ * tokenizer over free text, so what it names can itself be a secret: measured,+ * `uvx --from git+https://oauth2:ghp_…@github.com agent` names `oauth2:ghp_…`, a quoted env value+ * names `sk-ant-…"`, and `${env:AGENT_BIN}` names the template. A real program basename fits this+ * alphabet (no `@`, `:`, `/`, quotes, `$`); anything else publishes `[]` — "cannot be named", which+ * the phone must refuse — rather than a substring of the command.+ */+const PLAIN_BINARY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/++/** Longest label we republish — a label is display text, not a payload. */+const LABEL_MAX = 200++export function mirrorCustomAgents(customAgents: readonly CustomAgent[] | null | undefined): MirrorCustomAgent[] {+ if (!Array.isArray(customAgents)) return []+ // Settings are hand-editable JSON: never trust the static type.+ const valid = customAgents.filter(+ (c): c is CustomAgent =>+ !!c && typeof c === 'object' && typeof c.id === 'string' && c.id.startsWith('custom:')+ )+ const out: MirrorCustomAgent[] = []+ const seen = new Set<string>()+ for (const c of valid) {+ // The desktop's predicate resolves an id to its FIRST record; a duplicate must not advertise a+ // second, different binary for the same id.+ if (seen.has(c.id)) continue+ seen.add(c.id)+ const base =+ typeof c.baseAgent === 'string' && Object.prototype.hasOwnProperty.call(AGENT_CONFIG, c.baseAgent)+ ? c.baseAgent+ : undefined+ const launchCmd = typeof c.launchCmd === 'string' ? c.launchCmd : ''+ const binaries = binariesFor(c.id, [{ id: c.id, launchCmd, ...(base ? { baseAgent: base } : {}) }])+ const label = typeof c.label === 'string' && c.label.trim() ? c.label.slice(0, LABEL_MAX) : c.id+ // All-or-nothing: one unpublishable name means the derivation is not trustworthy as a whole.+ const plain = !!binaries && binaries.length > 0 && binaries.every((b) => PLAIN_BINARY.test(b))+ out.push({ id: c.id, label, ...(base ? { baseAgent: base } : {}), binaries: plain ? [...binaries] : [] })+ }+ return out+}diff --git a/src/main/index.ts b/src/main/index.tsindex d1c36260f..ef3bb454b 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -189,6 +189,7 @@ import {mirrorEntry,pendingTicketsFor} from '../core/agent-status-mirror'+import { mirrorCustomAgents } from '../core/mirror-custom-agents'import { paneOwnerProject } from '../core/agents/pane-ownership'import { createPushNotify, createLiveUpdatePush } from '../core/push-notify'import { createGrantsAccessor, type PushGrant } from '../core/push-grants'@@ -2118,7 +2119,9 @@ app.whenReady().then(async () => {: {}), // unprobed ⇒ absent ⇒ the reader uses the baseline vocabularyclaudeAccounts: (s.claudeAccounts ?? []).filter((a) => !a.host && !a.pending)- .map((a) => ({ id: a.id, dir: claudeConfigDirFor(a.id) }))+ .map((a) => ({ id: a.id, dir: claudeConfigDirFor(a.id) })),+ // Derived binary names only — never the launch command/env (see core/mirror-custom-agents.ts).+ customAgents: mirrorCustomAgents(s.customAgents)}})// Desktop → paired-phone APNs push (spec: apns-push). Feeds off the SAME actionable-event seam@@ -2326,7 +2329,10 @@ app.whenReady().then(async () => {.filter((a) => a.host === hostKey && !a.pending).map((a) => ({ id: a.id, dir: remoteAccountConfigDirAbs(home, a.id) }))}- : {}) // unresolved home ⇒ no accounts advertised (fail-open), autoSupported still ships+ : {}), // unresolved home ⇒ no accounts advertised (fail-open), autoSupported still ships+ // Settings-global, and the pane on the host runs the same launch command — so the same+ // derived binaries apply. The slice is a file ON the host: raw commands/env never go there.+ customAgents: mirrorCustomAgents(s.customAgents)}}})diff --git a/src/server/index.ts b/src/server/index.tsindex 78b77c42f..7c527bc72 100644--- a/src/server/index.ts+++ b/src/server/index.ts@@ -81,6 +81,7 @@ import {sessionNameSweepEntries,nodeSessionName} from '../core/agent-status-mirror'+import { mirrorCustomAgents } from '../core/mirror-custom-agents'import { createPushNotify, createLiveUpdatePush } from '../core/push-notify'import { createGrantsAccessor } from '../core/push-grants'import { createAckSweeper } from '../core/ack-sweep'@@ -461,7 +462,9 @@ export async function startServer(: {}), // unprobed ⇒ absent ⇒ the reader uses the baseline vocabularyclaudeAccounts: (s.claudeAccounts ?? []).filter((a) => !a.host && !a.pending)- .map((a) => ({ id: a.id, dir: claudeConfigDirFor(a.id) }))+ .map((a) => ({ id: a.id, dir: claudeConfigDirFor(a.id) })),+ // Derived binary names only — never the launch command/env (see core/mirror-custom-agents.ts).+ customAgents: mirrorCustomAgents(s.customAgents)}})// Advertise this install's version/commit/installedAt to the phone (spec: server-update). The