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
import {
resolveProjectSettings,
type ProjectSettingsDoc,
type ProjectSettingsSnapshot,
type ResolvedProjectSetting
} from '../shared/project-settings'
import type { ProjectConsumerFamily } from './project-setup-service'
import type { ProjectSetupTargetInfo } from './project-setup-runner-local'
import type { ProjectTrustStore } from './project-trust-store'
import { projectFamilyTrusted, projectTrustKeyFor } from './project-trust-verdict'
/**
* What a project contributes to a session it owns: environment variables and the terminal program.
* `PtyManager` consumes exactly this and nothing else (`setProjectSpawnOverrides`).
*
* Absent fields mean "the project has no opinion" — never "clear what was there". A spawn with no
* overrides at all answers `null`, so the whole feature costs one skipped branch on every path that
* has no project settings.
*/
export interface ProjectSpawnOverrides {
/** LITERAL values only. `${env:VAR}` is NOT expanded here — that is a custom-agent feature
* (custom-agent-env.ts) and inheriting it would turn a git-shared settings.json into a read of
* this machine's process environment, laundered past a dialog that rendered the literal. The
* keys/values are already bounded and identifier-shaped by the Task 1 sanitizer. */
env?: Record<string, string>
/** Still validated at the spawn (`safeSessionProgram`) — see `PtyManager.spawnSession`. */
shell?: string
}
export type ProjectSpawnOverridesReader = (
projectId: string
) => Promise<ProjectSpawnOverrides | null>
export interface ProjectSpawnOverridesDeps {
/** This shell's own settings resolution (e.g. `WorkspaceStore.readProjectSettings`). */
readSettings(projectId: string): Promise<ProjectSettingsSnapshot | null>
/**
* The project's LOCATION, from this process's own workspace index (e.g.
* `WorkspaceStore.projectTargetInfo`) — never from the renderer, and never derived from the
* git-shared `project.json`. Required because trust is keyed by location, not project id.
*/
targetInfo(projectId: string): ProjectSetupTargetInfo | null
trust: Pick<ProjectTrustStore, 'isTrusted'>
/**
* Raise the consent dialog for a family whose SHARED value was just refused
* (`ProjectSetupService.ensureFamilyTrusted`, single-flight per family+location). FIRE AND
* FORGET: this spawn has already decided to go without the value — waiting on a human would
* block a terminal for up to five minutes, and the answer arrives in time for the NEXT launch.
* Optional so a shell with no consent surface still gets the local-value half.
*/
requestTrust?(projectId: string, family: ProjectConsumerFamily): unknown
}
/** Shared-sourced values are the gated ones; a local value is this machine's own typing. */
function isShared<T>(r: ResolvedProjectSetting<T> | undefined): boolean {
return r?.source === 'shared'
}
/**
* The ONE reader both shells inject into `PtyManager` (main/index.ts + server/index.ts).
*
* Rules, in the order they matter:
* 1. A LOCAL value is always consumed, with no trust question and no prompt — the user typed it
* into this machine's own overlay, which is the same reason `ProjectSetupService.run` never
* gates a local script.
* 2. A SHARED value (git, or a remote host's disk) is consumed only while its family's
* shared-content hash is trusted at this LOCATION — the verdict computed by
* `projectFamilyTrusted`, the same helper `project-settings:launch-info` reports from.
* 3. An untrusted shared value is OMITTED and the family's consent dialog is requested
* fire-and-forget. The spawn is never delayed by it.
* 4. Everything else fails OPEN: no settings, an unreadable document, a throwing trust store, a
* throwing `requestTrust` — all answer "no overrides", never an exception into the spawn path.
*/
export function makeProjectSpawnOverrides(
deps: ProjectSpawnOverridesDeps
): ProjectSpawnOverridesReader {
return async (projectId: string): Promise<ProjectSpawnOverrides | null> => {
let snap: ProjectSettingsSnapshot | null
try {
snap = await deps.readSettings(projectId)
} catch {
return null
}
if (!snap) return null
const resolved = resolveProjectSettings(snap.local, snap.shared ?? undefined)
const envSetting = resolved.agents.env
const shellSetting = resolved.terminal.shell
if (!envSetting && !shellSetting) return null
const sharedDoc: ProjectSettingsDoc = snap.shared ?? {}
const key = projectTrustKeyFor(deps.targetInfo(projectId))
/** Ask once per family, and never wait on the human. */
const admit = async (family: ProjectConsumerFamily): Promise<boolean> => {
if (await projectFamilyTrusted(deps.trust, key, family, sharedDoc)) return true
try {
// Deliberately not awaited (and not returned): `ensureFamilyTrusted` resolves only when a
// human answers — or in five minutes, when the prompt expires.
void deps.requestTrust?.(projectId, family)
} catch {
/* a shell with no window to prompt in is still a shell that spawns terminals */
}
return false
}
const out: ProjectSpawnOverrides = {}
if (envSetting && (!isShared(envSetting) || (await admit('agents')))) {
out.env = { ...envSetting.value }
}
if (shellSetting && (!isShared(shellSetting) || (await admit('shell')))) {
out.shell = shellSetting.value
}
return out.env || out.shell ? out : null
}
}