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(mirror): advertise custom agents to the phone as derived binaries

reviewb21e7bb67062
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 can
launch 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 installer
registry `MANAGED_HOOK_INSTALLERS`. `managed-script.ts` builds the POSIX hook script that
POSTs to the server (env-gated: a no-op in the user's normal terminals, active only in
diff --git a/docs/mobile-chat-view.md b/docs/mobile-chat-view.md
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 vocabulary
claudeAccounts: (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.ts
index 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 vocabulary
claudeAccounts: (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