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
/**
* The canvas-control `settings` verb: which settings an agent may read and ask to change, and what
* it may never touch.
*
* AN AGENT THAT CAN WRITE SETTINGS CAN GRANT ITSELF POWERS. Several settings exist precisely so a
* HUMAN decides them — the permission mode, the per-node identity escape hatch, browser control,
* the confirm waivers — and a CLI that could flip them would make every one of those decisions
* decorative. So this file is built on three rules, each pinned by `settings-verb.test.ts`:
*
* 1. AN ALLOWLIST, NOT A DENYLIST (`SETTINGS_VERB_KEYS`). A key that is not in the table is
* refused BY NAME, whatever it is. Adding a key is a deliberate one-line change beside a test,
* and the entry must say why it is safe for an agent to hold (`why`).
* 2. A FORBIDDEN SET THAT OUTRANKS THE LIST (`SETTINGS_VERB_FORBIDDEN`). The test walks the
* allowlist against it, and against a name pattern, so a future entry that names a permission,
* an account, a credential, telemetry, a keybinding or a confirm waiver goes red even when
* somebody adds it to the table on purpose. The forbidden names are typed against `Settings` /
* `Project`, so a rename cannot leave a phantom entry that forbids nothing.
* 3. EVERY CHANGE ASKS THE HUMAN. This file only PLANS a change (`planSettingsSet`); the desktop
* dispatch raises the confirm dialog, and `settings` is deliberately outside
* `CONFIRM_WAIVABLE_VERBS` (@shared/control-confirm), so no standing waiver — app-run, project,
* always or bypass — can answer for the user. The Server Edition has no human to ask, so it
* refuses `--set` by name (src/server/control-unsupported.ts).
*
* THE CLI SHAPE uses flags only — `settings`, `settings --get <key>`, `settings --set <key> --value
* <v> [--project <id>]` — never a positional sub-action. The sh shim maps a bare positional only for
* the verbs it names, and an SSH host can still be running an older shim (it is brought up to
* date on connect, but not through a dead tunnel, and not over another desktop's older copy), so
* `settings get` could reach the server with the `get` silently dropped. Every flag carries a value, which both the old and the new shim loop
* read identically.
*
* In `src/shared` because both edges need it: the desktop renderer (dispatch + dialog) and the
* Server Edition's headless handler (`get`, plus the named `--set` refusal).
*/
import { PROJECT_CAPABILITY_COPY, type ProjectCapability } from './project-capabilities'
import {
capabilityAnswerOf,
projectCapabilityEffective,
type CapabilityAckMap
} from './project-capability-consent'
import type { Project, Settings } from './types'
import { NODE_SIZE_MAX, TERMINAL_NODE_SIZE_MIN } from './default-node-size'
/** Where a setting lives. `project` = a per-project capability (the project's file + this
* machine's answer); `machine` = settings.json on this machine, every project. */
export type SettingsVerbScope = 'project' | 'machine'
type SettingsVerbType = { kind: 'boolean' } | { kind: 'integer'; min: number; max: number }
export interface SettingsVerbKeySpec {
scope: SettingsVerbScope
type: SettingsVerbType
/** What the user reads in the confirm dialog. */
label: string
/** Why an agent may hold this. Required: an entry nobody could justify does not belong here. */
why: string
}
/** The machine-wide keys, typed against `Settings` so the table cannot name a field that is not
* there (a typo would otherwise be an allowlisted key that silently writes nothing). */
type MachineKey = keyof Pick<
Settings,
'snapToGrid' | 'gridSize' | 'defaultNodeWidth' | 'defaultNodeHeight'
>
type ProjectKey = Extract<ProjectCapability, 'agentMessaging'>
export type SettingsVerbKey = MachineKey | ProjectKey
/** What a reader needs from settings.json: the machine keys, plus the machine default a project
* capability falls back to when its file says nothing. */
export type SettingsVerbSettings = Pick<Settings, MachineKey> &
Partial<Pick<Settings, 'agentMessagingDefault'>>
/**
* THE ALLOWLIST. Order = the order `settings` lists them in.
*
* Deliberately tiny. The machine keys are canvas layout only — what an orchestrator that is already
* allowed to open and arrange nodes would reasonably want to tune, and nothing that hides, silences
* or loosens anything. The bounds mirror the Settings UI (`BehaviorSection` for the grid,
* `terminalNodeSize` for node size), so the CLI can never persist a value the UI would not.
*/
export const SETTINGS_VERB_KEYS: Readonly<Record<SettingsVerbKey, SettingsVerbKeySpec>> = {
agentMessaging: {
scope: 'project',
type: { kind: 'boolean' },
label: PROJECT_CAPABILITY_COPY.agentMessaging.label,
why:
'The owner asked for agents to be able to turn on agent-to-agent messaging. It is a capability ' +
'grant, so it lands through the same setter as the Settings switch and every other messaging ' +
'gate (verified-only, same project, idle panes, rate limit, trace) stays in force.'
},
snapToGrid: {
scope: 'machine',
type: { kind: 'boolean' },
label: 'Snap nodes to the grid while dragging',
why: 'Canvas layout only; an agent that arranges nodes may want them to land on the grid.'
},
gridSize: {
scope: 'machine',
type: { kind: 'integer', min: 8, max: 96 },
label: 'Grid size (px)',
why: 'Canvas layout only. Bounds are the Settings field’s own (BehaviorSection).'
},
defaultNodeWidth: {
scope: 'machine',
type: { kind: 'integer', min: TERMINAL_NODE_SIZE_MIN.width, max: NODE_SIZE_MAX.width },
label: 'Default width of new terminal and agent nodes (px)',
why: 'Canvas layout only. Bounds are terminalNodeSize’s clamp, so nothing out of range persists.'
},
defaultNodeHeight: {
scope: 'machine',
type: { kind: 'integer', min: TERMINAL_NODE_SIZE_MIN.height, max: NODE_SIZE_MAX.height },
label: 'Default height of new terminal and agent nodes (px)',
why: 'Canvas layout only. Bounds are terminalNodeSize’s clamp, so nothing out of range persists.'
}
}
export const SETTINGS_VERB_KEY_LIST = Object.keys(SETTINGS_VERB_KEYS) as SettingsVerbKey[]
/**
* NEVER settable from the CLI, whatever the allowlist says — these exist so a human decides them.
* `settings-verb.test.ts` walks the allowlist against this set AND against
* `SETTINGS_VERB_FORBIDDEN_PATTERN`, so the list below is the named core, not the whole fence.
*/
export const SETTINGS_VERB_FORBIDDEN = new Set<keyof Settings | keyof Project>([
// Permission mode — global and per project (bypassPermissions travels with a clone).
'claudePermissionMode',
'defaultPermissionMode',
'vanillaLaunchDefault',
// Per-node identity escape hatch.
'hookIdentityStrict',
// Browser control — a capability that acts as the user on the web.
'agentBrowserControl',
// Issue reporting — the only capability whose effect LEAVES THE MACHINE. An agent that could
// switch on its own auto-reporting is a self-granting loop aimed at a public tracker, so this is
// never settable from the CLI whatever the allowlist says. The name pattern below does NOT catch
// it (none of "report", "issue" or "github" is a forbidden name class, and adding one would be
// guessing at words rather than at capabilities), so this entry is the key's ONLY fence — which
// is why it is also named in settings-verb.test.ts's escapees tripwire.
'agentIssueReporting',
// Board dispatch — starting agent runs by itself. An agent that could switch it on (or lift its
// kill switch, or raise its cap) would grant itself more agents; its consent is the person's own.
// The name pattern does not catch it, so this entry is its only fence.
'boardDispatch',
// This machine's consent record for capabilities; writable only by the human's answer.
'capabilityAck',
// Accounts, credentials, model gateway, and anything that decides WHAT COMMAND runs.
'claudeAccounts',
'codexAccounts',
'defaultAccountId',
'modelGateway',
'modelGatewayDefaultModel',
'agentLaunchCommands',
'customAgents',
'commitAgentCommand',
'defaultShell',
// The machine default for messaging: a grant over EVERY project on this machine at once, cloned
// ones included. The per-project switch is the narrower, confirmable thing an agent may ask for.
'agentMessagingDefault',
// Telemetry.
'telemetryEnabled',
// Consent to license and allowance calls while DO_NOT_TRACK is set. A privacy decision:
// an agent that could grant it would turn the user's DO_NOT_TRACK into a suggestion. The `consent`
// name class below catches it too; it is named here so the snapshot test pins it either way.
'licenseNetworkConsent',
// Keybindings and the terminal-first shortcut policy.
'keybindings',
'terminalShortcutPolicy',
// Confirm waivers / "don't ask again" and one-click approvals: a CLI that could set these would
// make every confirm decorative (see @shared/control-confirm).
'controlConfirmWaivers',
'confirmBeforeQuit',
'hookReplyApprovals',
// Remote reach into this machine.
'phoneAccessEnabled'
])
/** Name classes that are forbidden even for a key nobody has thought of yet. The allowlist walk
* in the test fails on any entry matching this. */
export const SETTINGS_VERB_FORBIDDEN_PATTERN =
/permission|identity|browser|account|credential|token|secret|password|apikey|gateway|telemetry|keybinding|shortcut|waiver|confirm|approval|consent|ack$|launch|command|shell|phone|push/i
/** Is this string a key on the allowlist? Own-property lookup: `constructor` / `__proto__` are
* not keys, whatever the prototype chain says. */
export function isSettingsVerbKey(key: string): key is SettingsVerbKey {
return Object.prototype.hasOwnProperty.call(SETTINGS_VERB_KEYS, key)
}
/** A key is agent-supplied text that ends up in a reply; echo it only when it looks like a key. */
function shownKey(key: string): string {
return /^[A-Za-z][A-Za-z0-9._-]{0,63}$/.test(key) ? `"${key}"` : 'that key'
}
/** The refusal for a key off the list — named, and distinct for the forbidden set so an agent
* learns this is a human's decision rather than a missing feature. */
export function settingsKeyRefusal(key: string): string {
if ((SETTINGS_VERB_FORBIDDEN as ReadonlySet<string>).has(key)) {
return (
`settings-key-forbidden: ${shownKey(key)} can never be read or changed from the canvas CLI — ` +
'it is a decision the user makes in Settings. Do not retry; ask the user if it needs changing.'
)
}
return (
`settings-key-not-allowed: ${shownKey(key)} is not on the canvas CLI settings allowlist ` +
`(${SETTINGS_VERB_KEY_LIST.join(', ')}). Do not retry.`
)
}
export type SettingsRequest =
| { action: 'list'; project?: string }
| { action: 'get'; key: SettingsVerbKey; project?: string }
| { action: 'set'; key: SettingsVerbKey; value: boolean | number; project?: string }
const KNOWN_FLAGS = new Set(['get', 'set', 'value', 'project'])
/** Parse `settings` arguments (the `arg.*` fields the shim sends). Pure; every refusal names what
* was wrong. */
export function parseSettingsRequest(
args: Record<string, string | undefined>
): SettingsRequest | { error: string } {
const unknown = Object.keys(args).filter((k) => !KNOWN_FLAGS.has(k))
if (unknown.length) {
return {
error:
`settings: unknown flag ${unknown.map((k) => shownKey(k)).join(', ')} — use ` +
'`settings`, `settings --get <key>` or `settings --set <key> --value <value> [--project <id>]`'
}
}
const project = args.project?.trim() || undefined
if (args.project !== undefined && !project) return { error: 'settings: --project needs a project id' }
const hasGet = args.get !== undefined
const hasSet = args.set !== undefined
if (hasGet && hasSet) return { error: 'settings: pass either --get or --set, not both' }
if (!hasSet && args.value !== undefined) {
return { error: 'settings: --value only goes with --set <key>' }
}
const scopeError = (key: SettingsVerbKey): string | null =>
project && SETTINGS_VERB_KEYS[key].scope === 'machine'
? `settings: ${key} is a machine-wide setting — --project does not apply to it`
: null
if (!hasSet) {
const key = (args.get ?? '').trim()
if (!key) return { action: 'list', ...(project ? { project } : {}) }
if (!isSettingsVerbKey(key)) return { error: settingsKeyRefusal(key) }
const bad = scopeError(key)
if (bad) return { error: bad }
return { action: 'get', key, ...(project ? { project } : {}) }
}
const key = (args.set ?? '').trim()
if (!key) return { error: 'settings: --set needs a key' }
if (!isSettingsVerbKey(key)) return { error: settingsKeyRefusal(key) }
const bad = scopeError(key)
if (bad) return { error: bad }
if (args.value === undefined || args.value.trim() === '') {
return { error: `settings: --set ${key} needs --value` }
}
const value = parseSettingsValue(key, args.value)
if ('error' in value) return value
return { action: 'set', key, value: value.value, ...(project ? { project } : {}) }
}
/** Strict value parsing: `true`/`false` for a boolean, a whole number inside the key's bounds for
* an integer. Anything else is refused — never coerced to the nearest legal value. */
export function parseSettingsValue(
key: SettingsVerbKey,
raw: string
): { value: boolean | number } | { error: string } {
const t = SETTINGS_VERB_KEYS[key].type
const v = raw.trim()
if (t.kind === 'boolean') {
if (v === 'true') return { value: true }
if (v === 'false') return { value: false }
return { error: `settings: ${key} takes true or false` }
}
if (!/^-?\d+$/.test(v)) return { error: `settings: ${key} takes a whole number` }
const n = Number(v)
if (n < t.min || n > t.max) {
return { error: `settings: ${key} must be between ${t.min} and ${t.max}` }
}
return { value: n }
}
/** The project half a reader needs: its id and name, the capability flag the file carries, and this
* machine's recorded answer. `Project` satisfies it; so does the server's capability view. */
export interface SettingsProjectView {
id: string
name: string
agentMessaging?: unknown
capabilityAck?: CapabilityAckMap
}
export interface SettingsValue {
key: SettingsVerbKey
scope: SettingsVerbScope
/** The EFFECTIVE value — for a capability, whether it is granted right now, not the file bit. */
value: boolean | number
/** One human line: the value plus where it came from. */
display: string
}
/**
* Read one key. A capability reads as its GRANT (`projectCapabilityGrantedFor`), never the raw
* file bit: a project file that says `true` while this machine has not confirmed it is OFF, and
* saying "on" there would invite an agent to rely on a delivery that will be refused.
*/
export function readSettingsValue(
key: SettingsVerbKey,
settings: SettingsVerbSettings,
project: SettingsProjectView | undefined
): SettingsValue | { error: string } {
const spec = SETTINGS_VERB_KEYS[key]
if (spec.scope === 'machine') {
const value = settings[key as MachineKey]
return { key, scope: 'machine', value, display: `${value} (this machine)` }
}
if (!project) {
return { error: `settings: ${key} belongs to a project, and this node is not in a saved project yet` }
}
const cap = key as ProjectCapability
const effective = projectCapabilityEffective(project, cap, {
agentMessagingDefault: settings.agentMessagingDefault
})
let display: string
if (effective.pendingNotice) {
display =
capabilityAnswerOf(project, cap) === 'declined'
? 'off (the project file turns it on, but the user declined it on this machine)'
: 'off (the project file turns it on, but the user has not confirmed it on this machine yet)'
} else {
const why = effective.source === 'default' ? "this machine's default" : 'this project'
display = `${effective.on ? 'on' : 'off'} (${why})`
}
return { key, scope: 'project', value: effective.on, display }
}
/** The text/plain + structured reply for `settings` / `settings --get <key>`. */
export function renderSettingsGet(input: {
keys: readonly SettingsVerbKey[]
settings: SettingsVerbSettings
project: SettingsProjectView | undefined
}): { ok: true; message: string; result: unknown } | { ok: false; error: string } {
const values: SettingsValue[] = []
for (const key of input.keys) {
const v = readSettingsValue(key, input.settings, input.project)
// A single-key read of a project key with no project is an error; in the full listing the
// project keys are simply skipped with a note, so the machine keys still answer.
if ('error' in v) {
if (input.keys.length === 1) return { ok: false, error: v.error }
continue
}
values.push(v)
}
const width = Math.max(...values.map((v) => v.key.length), 0)
const lines = [
input.project
? `Settings the canvas CLI can read and change (project "${input.project.name}", id ${input.project.id}):`
: 'Settings the canvas CLI can read and change (this node is not in a saved project yet):',
...values.map(
(v) => ` ${v.key.padEnd(width)} ${v.display} [${v.scope}] ${SETTINGS_VERB_KEYS[v.key].label}`
)
]
if (input.keys.length > 1) {
lines.push(
'Change one with `settings --set <key> --value <value>` (add `--project <id>` for a project ' +
'key in another project). Every change asks the user to confirm; a denial is final.'
)
}
return {
ok: true,
message: lines.join('\n'),
result: {
...(input.project ? { projectId: input.project.id } : {}),
settings: values
}
}
}
/** What the desktop applies once the user confirms — exactly one store write. */
export type SettingsChange =
| { scope: 'project'; projectId: string; capability: ProjectCapability; on: boolean }
| { scope: 'machine'; patch: Partial<Pick<Settings, MachineKey>> }
export type SettingsSetPlan =
| { kind: 'unchanged'; message: string }
| {
kind: 'confirm'
change: SettingsChange
message: string
confirmLabel: string
/** Granting a capability is the one change drawn as a danger action. */
danger: boolean
/** The reply once applied. */
done: string
}
| { kind: 'error'; error: string }
function showValue(key: SettingsVerbKey, v: boolean | number): string {
return SETTINGS_VERB_KEYS[key].scope === 'project' ? (v ? 'on' : 'off') : String(v)
}
/**
* Plan a `--set`: the old value, the new one, the dialog wording, and the single write. A value
* that is already in effect is answered without a dialog — there is nothing to consent to — which
* for a capability means already GRANTED: a file `true` the user has not confirmed is off, and
* `--set agentMessaging --value true` there raises the dialog, whose confirm IS that consent.
*/
export function planSettingsSet(input: {
request: Extract<SettingsRequest, { action: 'set' }>
settings: SettingsVerbSettings
project: SettingsProjectView | undefined
requestedBy: string
}): SettingsSetPlan {
const { request, project, requestedBy } = input
const current = readSettingsValue(request.key, input.settings, project)
if ('error' in current) return { kind: 'error', error: current.error }
const spec = SETTINGS_VERB_KEYS[request.key]
const from = showValue(request.key, current.value)
const to = showValue(request.key, request.value)
if (current.value === request.value) {
return {
kind: 'unchanged',
message:
`${request.key} is already ${current.display}` +
`${spec.scope === 'project' && project ? ` in project "${project.name}"` : ''} — nothing changed`
}
}
const where =
spec.scope === 'project' && project
? `Project: ${project.name}`
: 'Applies to: this machine (every project)'
const lines = [
`Agent "${requestedBy}" wants to change a setting.`,
'',
`Setting: ${spec.label} (${request.key})`,
where,
`Change: ${from} → ${to}`
]
let change: SettingsChange
let danger = false
if (spec.scope === 'project' && project) {
const cap = request.key as ProjectCapability
const on = request.value === true
change = { scope: 'project', projectId: project.id, capability: cap, on }
if (on) {
danger = true
const copy = PROJECT_CAPABILITY_COPY[cap]
lines.push('', `${copy.description} ${copy.cloneWarning}`)
}
} else {
change = { scope: 'machine', patch: { [request.key]: request.value } as Partial<Pick<Settings, MachineKey>> }
}
return {
kind: 'confirm',
change,
message: lines.join('\n'),
confirmLabel: 'Change setting',
danger,
done:
`changed ${request.key}: ${from} → ${to}` +
(spec.scope === 'project' && project ? ` in project "${project.name}"` : ' on this machine')
}
}