Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import * as pty from 'node-pty';
import os from 'os';
import { basename } from 'path';
import { v4 as uuidv4 } from '../lib/uuid.js';
import { withSpawnCwdEnv } from '../lib/spawnCwd.js';
import { scheduleSubmitEnters, SUBMIT_KEY } from '../lib/tuiHandshake.js';
import { buildCdCommand } from '../lib/shellCd.js';
import { resolveInteractiveShell } from '../lib/interactiveShellResolver.js';
import { buildRunThenExitCommand } from '../lib/shellExit.js';
import { buildReadinessProbe } from '../lib/shellReadinessProbe.js';
import { prepareCliSpawn } from '../lib/bufferedSpawn.js';
import { createReplayBuffer } from '../lib/terminalReplay.js';
import { findCommandOnPath } from '../lib/processEnv.js';
import { MAX_TOTAL_SESSIONS } from '../lib/shellLimits.js';
// Store active shell sessions (persist across socket reconnects)
const shellSessions = new Map();
// Re-exported so a session caller reaches the Enter byte without importing the
// TUI-handshake module directly. See lib/tuiHandshake.js for why it is CR.
export { SUBMIT_KEY };
// PTY event handlers run outside the Express middleware chain — uncaught throws here
// crash the Node process instead of bubbling to res.next. try/catch is therefore
// justified in this one spot despite the project-wide "no try/catch" convention.
// Async hooks are serialized per-session via hookQueue so interleaved awaits (e.g.
// agentTuiSpawning's handleData mutating module-level buffers) don't race.
function runHook(label, session, fn, arg) {
if (!fn) return;
session.hookQueue = session.hookQueue.then(() => {
try {
return Promise.resolve(fn(arg));
} catch (err) {
console.error(`🐚 ${label} sync error in ${session._id}: ${err.message}`);
}
}).catch(err => console.error(`🐚 ${label} async error in ${session._id}: ${err.message}`));
}
// Allowlist of safe environment variable prefixes to pass to PTY sessions
// Prevents leaking secrets (API keys, tokens) to the shell
const SAFE_ENV_PREFIXES = [
'HOME', 'USER', 'LOGNAME', 'SHELL', 'PATH', 'LANG', 'LC_', 'TERM',
'COLORTERM', 'EDITOR', 'VISUAL', 'HOSTNAME', 'PWD', 'OLDPWD', 'TMPDIR',
'XDG_', 'SSH_AUTH_SOCK', 'DISPLAY', 'HOMEBREW_', 'NVM_', 'FNM_', 'NODE_',
'NPM_', 'VOLTA_', 'GOPATH', 'GOROOT', 'CARGO_', 'RUSTUP_', 'PYENV_',
'VIRTUAL_ENV', 'CONDA_', 'JAVA_HOME', 'ANDROID_', 'DOCKER_', 'COMPOSE_',
'KUBECONFIG', 'LESS', 'PAGER', 'MANPATH', 'INFOPATH', 'ZDOTDIR', 'STARSHIP_'
];
// Windows-only additions, matched as EXACT names rather than prefixes. The list
// above is POSIX-shaped: on Windows it drops variables the OS itself needs to
// create a working process, so a PTY session started from it launches into a
// crippled shell (no DLL search root, no temp dir, no per-user app data — which
// is where `claude`/`codex` keep their credentials and config).
//
// Exact-match is load-bearing, not a style choice: these are individual OS
// variables, not grouped families like `NPM_`/`XDG_`, so prefix-matching them
// would admit anything merely STARTING with one — `APPDATA_TOKEN`,
// `TEMP_SECRET`, and (worst, since it is two characters) `OS_API_KEY` would all
// be handed to an attachable agent shell by a filter whose entire job is
// withholding credentials.
//
// PATHEXT / USERPROFILE / HOMEDRIVE / HOMEPATH are deliberately absent: the
// POSIX PATH / USER / HOME prefixes already cover them.
const SAFE_ENV_NAMES_WIN32 = new Set([
'SYSTEMROOT', 'SYSTEMDRIVE', 'WINDIR', 'COMSPEC',
'APPDATA', 'LOCALAPPDATA',
'PROGRAMFILES', 'PROGRAMFILES(X86)', 'PROGRAMW6432',
'PROGRAMDATA', 'COMMONPROGRAMFILES', 'COMMONPROGRAMFILES(X86)', 'COMMONPROGRAMW6432',
'TEMP', 'TMP',
'NUMBER_OF_PROCESSORS', 'PROCESSOR_ARCHITECTURE', 'OS', 'PSMODULEPATH',
// Windows spellings of variables the POSIX prefixes above cover only on
// POSIX. They are listed here — rather than case-folding the POSIX prefix
// list on Windows — because folding a PREFIX list widens it: `NPM_` would
// then match npm's lower-case `npm_config__authToken` (a registry credential)
// and hand it to an attachable agent shell. An exact-name Set can be matched
// case-insensitively with no such reach.
'PATH', 'PATHEXT',
'USERPROFILE', 'USERNAME', 'USERDOMAIN', 'USERDOMAIN_ROAMINGPROFILE',
'HOMEDRIVE', 'HOMEPATH'
]);
/**
* Filter `process.env` down to the allowlist above.
*
* Two matching rules, deliberately different:
*
* - `SAFE_ENV_PREFIXES` is matched **case-sensitively on both platforms**.
* These are grouped families, and folding case widens a prefix rather than
* preserving it: upper-casing keys would push npm's lower-case
* `npm_config_*` / `npm_package_*` vars — `npm_config__authToken` among
* them — through the `NPM_` prefix into an attachable shell. PortOS starts
* under `npm run`, so those variables are always present.
* - `SAFE_ENV_NAMES_WIN32` is matched **case-insensitively, on Windows only,
* as exact names**. Windows env names are case-insensitive and arrive in
* mixed case (the real variable is `Path`, not `PATH`), and an exact-name
* Set can be folded safely because it has no prefix reach.
*
* Before this split, `Path` was dropped entirely on Windows by the
* case-sensitive `startsWith('PATH')` — the agent shell then couldn't resolve
* any CLI provider — while the coincidentally-upper-case `PATHEXT` survived.
*
* Exported for tests; `platform` is injectable so the Windows branch is
* testable from any host.
*
* @param {NodeJS.ProcessEnv} [env] - source environment; defaults to `process.env`
* @param {string} [platform] - `process.platform` value; defaults to the real one
* @returns {Record<string, string>} filtered environment
*/
export function buildSafeEnv(env = process.env, platform = process.platform) {
const isWin32 = platform === 'win32';
const safeEnv = {};
for (const [key, value] of Object.entries(env)) {
const allowed = SAFE_ENV_PREFIXES.some(prefix => key.startsWith(prefix))
|| (isWin32 && SAFE_ENV_NAMES_WIN32.has(key.toUpperCase()));
if (allowed) safeEnv[key] = value;
}
return safeEnv;
}
/**
* The shell a session runs when the caller doesn't name one.
*/
function getDefaultShell() {
return resolveInteractiveShell();
}
/**
* True — and warns — when the service already holds its ceiling of PTYs it
* spawned itself. Only ever called in the refusal position, so the log lives
* here rather than being spelled out at each spawn entry point.
*
* Only sessions this service spawned count. External views (one-shot TUI runs
* registered via registerExternalSession) are governed by their own runner and
* must not consume a slot.
*/
function refusedForSessionCap() {
let owned = 0;
for (const session of shellSessions.values()) {
if (!session.external) owned += 1;
}
if (owned < MAX_TOTAL_SESSIONS) return false;
console.log(`🐚 Max total sessions reached (${MAX_TOTAL_SESSIONS})`);
return true;
}
// Every PTY this service opens is a 256-color terminal.
const TERM_ENV = { TERM: 'xterm-256color', COLORTERM: 'truecolor' };
/**
* The non-env half of the `pty.spawn` options both entry points use, so the
* terminal name and the geometry defaults are stated once.
*
* `env` is deliberately NOT assembled here. Each caller wraps its own env in
* `withSpawnCwdEnv` at its own `pty.spawn` call, which keeps the #3193 PWD pin
* visible at every spawn site — and keeps `lib/spawnCwd.test.js` counting pins
* one-for-one against spawns, instead of one shared pin covering both.
*/
function ptyTerminalOptions({ cwd, cols, rows }) {
return {
name: 'xterm-256color',
cols: cols || 80,
rows: rows || 24,
cwd
};
}
/**
* Put a PTY in the session registry and wire its output (and, for a PTY this
* service owns, its exit) — so every attachable session, however it was
* started, has the same record shape and the same 50KB re-attach ring buffer.
*
* Three callers, differing only in the process behind the PTY:
* - `createShellSession` — an interactive login shell
* - `spawnCommandSession` — the launched command itself
* - `registerExternalSession` — a PTY spawned elsewhere (`external: true`)
*
* `shell` is the hosting shell binary, or `null` when the PTY *is* the launched
* command. Everything that injects a command line into a session reads it (see
* `changeSessionDirectory`), so a null value is the load-bearing signal that
* there is no shell to type at.
*
* `external` sessions skip the exit wiring: their lifecycle belongs to whoever
* spawned them, which ends the session through `unregisterExternalSession`.
*/
function adoptPtySession(sessionId, ptyProcess, options = {}) {
// Recent output, replayed to a client that attaches later. The buffer owns
// its own window, eviction, query-stripping and mode tracking — see
// lib/terminalReplay.js.
const replay = createReplayBuffer();
// Store session info
shellSessions.set(sessionId, {
_id: sessionId.slice(0, 8),
hookQueue: Promise.resolve(),
pty: ptyProcess,
socket: options.socket || null,
cwd: options.cwd || null,
// The spawned shell binary — kept so cd-style commands injected later can be
// written in the dialect this session actually speaks (see changeSessionDirectory).
// Null for a direct command session: there is no shell reading those lines.
shell: options.shell || null,
createdAt: Date.now(),
label: options.label || null,
kind: options.kind || 'shell',
agentId: options.agentId || null,
command: options.command || null,
onData: options.onData || null,
onExit: options.onExit || null,
// Keeps the session out of the interactive cap count and out of Shell's
// auto-attach — you opt into watching a run by clicking its tab.
...(options.external ? { external: true } : {}),
replay
});
// Handle pty output
ptyProcess.onData((data) => {
replay.push(data);
const session = shellSessions.get(sessionId);
session?.socket?.emit('shell:output', { sessionId, data });
if (session) runHook('onData', session, session.onData, data);
});
// An external PTY's lifecycle belongs to whoever spawned it — it ends the
// session through unregisterExternalSession — so registering an exit listener
// here would delete the record out from under that owner.
if (options.external) return;
// Handle pty exit
//
// `signal` is forwarded, not discarded: on POSIX a shell killed by a signal
// reports the wait-status exit code (0 for a plain SIGTERM/SIGHUP) with the
// signal number in the separate `signal` field. Dropping it made a
// pm2-treekilled agent shell indistinguishable from one that exited cleanly —
// which is how an agent whose PTY was torn down got recorded as a successful
// run (#3202). Consumers that care (the TUI spawner's onExit) MUST treat a
// non-null `signal` as an abnormal end regardless of `exitCode`.
ptyProcess.onExit(({ exitCode, signal }) => {
console.log(`🐚 Shell session ${sessionId.slice(0, 8)} exited (code: ${exitCode}${signal ? `, signal: ${signal}` : ''})`);
const session = shellSessions.get(sessionId);
shellSessions.delete(sessionId);
session?.socket?.emit('shell:exit', { sessionId, code: exitCode });
if (session) runHook('onExit', session, session.onExit, { exitCode, signal: signal ?? null });
broadcastSessionList();
});
}
/**
* Create a new shell session
*/
export function createShellSession(socket, options = {}) {
if (refusedForSessionCap()) {
socket?.emit?.('shell:error', { error: `Max ${MAX_TOTAL_SESSIONS} shell sessions. Kill an existing session first.` });
return null;
}
const sessionId = uuidv4();
const shell = options.shell || getDefaultShell();
const cwd = options.cwd || os.homedir();
console.log(`🐚 Creating shell session ${sessionId.slice(0, 8)} (${shell})`);
let ptyProcess;
try {
ptyProcess = pty.spawn(shell, [], {
...ptyTerminalOptions({ cwd, cols: options.cols, rows: options.rows }),
// Pin PWD to the spawn cwd — see withSpawnCwdEnv (#3193). An interactive
// login shell rewrites PWD itself at startup, but a non-login shell may
// not, and an agent-TUI session injects its CLI command into this shell.
env: withSpawnCwdEnv({
// `options.env` is a DELTA here — this base is always unioned underneath
// it. A caller that has already narrowed its environment to a strict
// allowlist must use `spawnCommandSession` instead, which unions nothing
// (and gets no rc file either — see its docstring).
...buildSafeEnv(), // filters process.env to prevent leaking inherited secrets (e.g. shell-inherited API keys)
// options.env is the caller's explicit opt-in env (e.g. TUI provider API keys for codex/claude).
// Callers are responsible for not passing vars they don't want visible inside attachable shells.
// Single-user/single-instance deployment (Tailscale-only) makes this acceptable.
...(options.env || {}),
...TERM_ENV
}, cwd)
});
} catch (err) {
console.error(`❌ Failed to spawn PTY: ${err.message}`);
socket?.emit?.('shell:error', { error: `Failed to spawn shell: ${err.message}` });
return null;
}
adoptPtySession(sessionId, ptyProcess, { ...options, socket, cwd, shell });
// Starting a fresh shell means the user moved on from whatever they were
// viewing — release any TUI-run views they held so those runs resume normal
// completion instead of staying paused for a tab they've left.
releaseExternalViews(socket, sessionId);
broadcastSessionList();
if (options.initialCommand) {
// `exitWithCommand` wraps the command so the shell dies with it, carrying its
// status out (an agent-TUI shell exists only to host one CLI). Rendered HERE
// rather than by the caller because only this function knows which shell the
// session actually got, and the wrapper is dialect-specific — see
// lib/shellExit.js. Same reason changeSessionDirectory renders its own `cd`.
const initialCommand = options.exitWithCommand
? buildRunThenExitCommand(options.initialCommand, shell)
: options.initialCommand;
// onInitialCommandSent fires at the exact moment the command is injected,
// regardless of which branch sent it. The agent-TUI spawner uses this to
// start observing claude's input-readiness ONLY after the real command is
// in flight — so the readiness probe's own shell activity (below) can't
// prematurely satisfy its bracketed-paste gate.
//
// For the waitForPromptReady path, `sendInitial` runs from the probe's
// `ptyProcess.onData` listener (below), registered AFTER the main output
// listener above that dispatches `session.onData` via `runHook`/
// `session.hookQueue`. node-pty invokes same-event listeners in
// registration order, but `runHook` only QUEUES the caller's onData
// handler as a microtask — it doesn't run it inline. So calling
// `options.onInitialCommandSent?.()` synchronously here would fire it
// BEFORE the caller's onData handler has actually processed the very
// chunk that proved the probe round-tripped, even though that handler was
// enqueued first. A consumer gating output on "has the command been
// injected yet" (see agentTuiSpawning.js's commandInjected) would then
// misread the probe's own echoed marker as post-injection output. Routing
// this callback through the SAME `session.hookQueue` guarantees it runs
// only after that chunk's onData handler has finished — while the actual
// PTY write below stays synchronous/immediate, unaffected.
const sendInitial = () => {
const session = shellSessions.get(sessionId);
if (session && options.onInitialCommandSent) {
runHook('onInitialCommandSent', session, options.onInitialCommandSent);
} else {
options.onInitialCommandSent?.();
}
submitToSession(sessionId, initialCommand);
};
if (options.waitForPromptReady) {
// Inject the command only once the shell can ACTUALLY run commands. A fixed
// delay races a heavy interactive shell; a prompt-marker / settle-on-quiet
// watch is fooled by powerlevel10k's *instant prompt*, which renders (and
// enables bracketed-paste mode) BEFORE `.zshrc`/plugins/nvm finish — and a
// slow mid-load quiet gap (nvm/plugins) trips a settle timer just as
// easily, sending the command into a half-loaded shell where it's swallowed
// when the real prompt redraws (the command sits echoed but unexecuted —
// exactly the wedged `claude …` at a bare prompt users hit). Instead, PROVE
// the shell is executing commands with a round-trip probe: print a unique
// nonce and wait until we SEE it in the OUTPUT. The nonce is split in the
// probe source (see buildReadinessProbe) so the command ECHO never contains
// the assembled string — only the executed output matches, so a single
// sighting is unambiguous. Instant-prompt keystroke buffering replays the
// probe into the real shell, so this is theme-agnostic. A bounded fallback
// still injects the command if the probe never round-trips (or the dialect
// has none — cmd.exe, see buildReadinessProbe).
let sent = false;
let sub = null;
let exitSub = null;
const nonce = uuidv4().replace(/-/g, '').slice(0, 12);
const marker = `PORTOSRDY${nonce}`;
const probe = buildReadinessProbe(nonce, shell);
let seen = '';
// Tear down every pending timer + listener. Called both on success
// (fire) and when the PTY exits before the probe round-trips, so no
// timer survives to fire into a dead session.
const stop = () => {
clearTimeout(probeTimer);
clearTimeout(fallback);
sub?.dispose?.();
exitSub?.dispose?.();
};
const fire = () => {
if (sent) return;
sent = true;
stop();
sendInitial();
};
// No probe for this dialect (cmd.exe, probe === null) — the guard inside
// each callback below is a no-op and the fallback timer alone injects the
// command, same as a probe that never round-trips.
sub = ptyProcess.onData((chunk) => {
if (!probe) return;
seen += chunk;
if (seen.length > 8192) seen = seen.slice(-8192);
if (seen.includes(marker)) fire();
});
// If the shell dies before the probe round-trips, cancel the pending
// writes/timers — sent stays true so the fallback can't resurrect a
// send into the gone session.
exitSub = ptyProcess.onExit(() => { sent = true; stop(); });
// Give the freshly-spawned PTY a tick to come up, then send the probe.
// Writing earlier is harmless (zsh's line editor / p10k instant-prompt
// buffer holds it until the prompt is live and replays it), but a small
// delay avoids racing node-pty's own spawn handshake.
const probeTimer = setTimeout(() => { if (probe && !sent) submitToSession(sessionId, probe); }, 50);
const fallback = setTimeout(fire, options.initialCommandDelayMs ?? 8000);
} else {
setTimeout(sendInitial, options.initialCommandDelayMs ?? 200);
}
}
return sessionId;
}
/**
* Spawn `command` AS the PTY — no hosting shell — and register it as an
* ordinary attachable session.
*
* Why this exists next to `createShellSession`: that function's PTY is an
* interactive login shell into which a command is later typed, so the
* operator's own rc file (`.zshrc`, `.bash_profile`, …) runs BEFORE the command
* and can re-export anything it likes. For a public-content review stage whose
* whole posture is a strict environment allowlist, that rc file is a hole no
* allowlist can close (#6159). Here the launched binary is the PTY's own
* process, so `env` is exactly what the child gets.
*
* `env` is the COMPLETE environment, not a delta: nothing is unioned underneath
* it (`buildSafeEnv` is deliberately not consulted), because the callers that
* need this have already narrowed the environment themselves.
*
* Ordinary agent TUI sessions keep the login shell — the operator's rc file is
* a feature there, not a leak — so this is not a drop-in replacement for
* `createShellSession`.
*
* Unlike `createShellSession`, every failure here THROWS rather than returning
* null. The caller is a spawner that records a cause on the agent record, and a
* bare null would make "the binary isn't installed" and "the session cap is
* full" indistinguishable — both then get filed as a generic host problem.
*
* @param {string} command - the binary to run (bare name or path)
* @param {string[]} [args]
* @param {object} [options] - { cwd, env, cols, rows, label, kind, agentId, command, onData, onExit }
* @returns {string} sessionId
* @throws when the session cap is reached, the command is not on the child's
* PATH, or the PTY will not open
*/
export function spawnCommandSession(command, args = [], options = {}) {
if (refusedForSessionCap()) {
throw new Error(`Max ${MAX_TOTAL_SESSIONS} shell sessions are already open; kill one before starting another`);
}
const sessionId = uuidv4();
const cwd = options.cwd || os.homedir();
// No buildSafeEnv union — see the docstring. The caller owns this env whole.
// PWD is still pinned to the spawn cwd (#3193): a directly-launched CLI reads
// it (OpenCode resolves its project root from it) and no shell will fix it up.
const childEnv = withSpawnCwdEnv({ ...(options.env || {}), ...TERM_ENV }, cwd);
// Resolve the executable BEFORE spawning. A PTY has no shell to print
// "command not found": on POSIX node-pty forks and `execvp` fails in the
// child, which exits 1 with an EMPTY screen, so an output-driven probe can
// never see it and the run finalizes as a bare exit-1 with no cause. Resolve
// against the CHILD's PATH — a caller's env may replace PATH with only the
// provider's own bin dir. Same pre-flight `tuiPromptRunner` and the CoS
// runner's `/spawn-tui` do; `basename` keeps the resolved path, which can
// embed the local account name, out of the message.
const executable = findCommandOnPath(command, { env: childEnv, cwd });
if (!executable) {
throw new Error(`Command executable unavailable: ${basename(command)} is not on the PATH for this session. Install it or update the configured command.`);
}
// Launch the path the pre-flight actually RESOLVED, not the bare name — the
// CoS runner's /spawn-tui does the same, and for the same reason. The two
// resolvers do not agree on Windows: `findCommandOnPath` unquotes a PATH
// entry, maps an empty one to cwd, resolves relative entries, and searches
// all of PATHEXT, while `prepareCliSpawn`'s own lookup does none of that. Re-
// resolving the bare name could therefore fall through to a bare
// extensionless `claude`, which ConPTY cannot launch — a blank PTY and a bare
// exit-1, the exact failure this pre-flight exists to prevent.
//
// prepareCliSpawn still runs: a resolved `.cmd`/`.bat` shim must launch
// through cmd.exe (never the user's shell — that wrapper runs no profile),
// and it owns the shared argument-escaping contract. On POSIX it is a no-op
// and the binary is spawned directly.
const { command: ptyCommand, args: ptyArgs } = prepareCliSpawn(executable, args, childEnv);
console.log(`🐚 Creating command session ${sessionId.slice(0, 8)} (${basename(command)})`);
const ptyProcess = pty.spawn(ptyCommand, ptyArgs, {
...ptyTerminalOptions({ cwd, cols: options.cols, rows: options.rows }),
env: childEnv
});
adoptPtySession(sessionId, ptyProcess, { ...options, cwd, shell: null });
broadcastSessionList();
return sessionId;
}
/**
* A socket can stay bound to multiple sessions (the registry allows it), but a
* user views one at a time. `isExternalSessionAttached` keys off socket binding,
* so without this a TUI run stays "watched" (and its completion stays paused)
* after the user switches to another tab. When a socket starts viewing a
* different session, drop its binding to any OTHER external (TUI-run) view so
* that run resumes normal completion handling. Interactive shells keep their
* lingering binding (the registry's one-socket-many-shells model is unchanged).
*/
function releaseExternalViews(socket, exceptId = null) {
if (!socket) return;
for (const [id, session] of shellSessions.entries()) {
if (session.external && session.socket === socket && id !== exceptId) {
session.socket = null;
}
}
}
/**
* Register a PTY spawned OUTSIDE this service (one-shot TUI runs in
* `lib/tuiPromptRunner.js`) as an attachable session so it shows up in the Shell
* UI where the user can watch its live output AND interact with it — type
* corrections, answer questions the model is waiting on, or interrupt it.
*
* Why this exists separately from createShellSession:
* - The TUI runner deliberately spawns its own PTY (it bypasses the session
* cap and the login-shell wrapper — see tuiPromptRunner.js's header). This
* helper only *surfaces* that already-running PTY; it does not spawn one.
* - `external: true` keeps it out of the interactive-session cap count and out
* of Shell's auto-attach (you opt into watching a run by clicking its tab).
*
* Input and resize are NOT blocked — these views are fully interactive. To keep
* a run from being killed out from under an engaged human, the runner pauses its
* idle-completion and hard-timeout while a viewer is attached (see
* `isExternalSessionAttached` + tuiPromptRunner's completion watch).
*
* node-pty fans `onData` out to every registered listener, so the listener we
* add here streams to the Shell viewer without disturbing the runner's own
* output capture. Lifecycle is owned by the runner: it calls
* unregisterExternalSession from its single finish() funnel when the run ends.
*
* @param {string} sessionId — typically the runId, so the Shell view correlates
* with the /runs record.
* @param {object} ptyProcess — the live node-pty IPty.
* @param {object} [options] — { label, command, cwd, kind, agentId }.
* @returns {string} sessionId (idempotent — returns the id if already registered).
*/
export function registerExternalSession(sessionId, ptyProcess, options = {}) {
if (shellSessions.has(sessionId)) return sessionId;
// Same record and same 50KB re-attach ring buffer every other session gets, so
// a viewer who opens the run mid-stream sees the recent screen state — the
// only differences are `external` and that the exit wiring stays with the
// owner (see adoptPtySession).
adoptPtySession(sessionId, ptyProcess, {
...options,
kind: options.kind || 'tui-run',
external: true,
// The PTY is not ours to type a command line into, and its hooks belong to
// the process that spawned it.
shell: null,
onData: null,
onExit: null
});
console.log(`🐚 Registered external TUI session ${sessionId.slice(0, 8)} (${options.label || options.command || 'tui'})`);
broadcastSessionList();
return sessionId;
}
/**
* Remove an external session from the registry and notify any attached viewer
* that the run finished. Idempotent and external-only — a no-op if the id is
* unknown or belongs to an interactive shell (those clean up via PTY onExit).
*/
export function unregisterExternalSession(sessionId, { exitCode = 0 } = {}) {
const session = shellSessions.get(sessionId);
if (!session || !session.external) return false;
shellSessions.delete(sessionId);
session.socket?.emit('shell:exit', { sessionId, code: exitCode });
broadcastSessionList();
return true;
}
/**
* True when an external (TUI-run) session exists and a Shell viewer is currently
* attached to it. The runner consults this to pause auto-completion/timeout while
* a human is watching, so the run isn't killed mid-interaction.
*/
export function isExternalSessionAttached(sessionId) {
const session = shellSessions.get(sessionId);
return !!(session && session.external && session.socket);
}
/**
* Public "stopped viewing" signal — the client emits this when it leaves the
* Shell page (the SocketProvider socket persists across navigations, so a plain
* disconnect doesn't fire). Releases every external (TUI-run) view bound to this
* socket so those runs resume normal idle completion instead of staying paused
* for a page the user has navigated away from. Tab-switching already releases via
* attach/create; this covers navigating away from /shell entirely.
*/
export function releaseExternalViewsForSocket(socket) {
if (!socket) return;
const held = [...shellSessions.values()].some(s => s.external && s.socket === socket);
releaseExternalViews(socket);
if (held) broadcastSessionList();
}
/**
* Attach an existing session to a new socket
*
* A shell session has a single attached socket — PTY output is fanned to that one
* socket only (see ptyProcess.onData). When a deep link is opened in a second tab,
* the new socket takes over and the previous tab would otherwise sit "Connected"
* with no output. Emit shell:detached on the prior socket so it can clear its
* local state instead of silently losing the stream.
*
* `claim` — when true, the attach refuses to displace a different socket. Used by
* client-side auto-pick paths so concurrent broadcasts to two idle tabs don't
* end up with both tabs racing to attach the same survivor (and one tab's win
* displacing the other via shell:detached). User-initiated attaches default to
* claim=false (takeover semantics — explicit intent wins).
*/
export function attachSession(sessionId, socket, { claim = false } = {}) {
const session = shellSessions.get(sessionId);
if (!session) return null;
const prevSocket = session.socket;
if (claim && prevSocket && prevSocket !== socket) {
// Auto-pick lost the race to a different socket. Caller can fall back to
// another survivor or give up and stay at /shell.
return { claimRejected: true };
}
if (prevSocket && prevSocket !== socket) {
prevSocket.emit('shell:detached', { sessionId, reason: 'attached-elsewhere' });
}
session.socket = socket;
// Switching view releases any TUI-run this socket was watching, so that run
// resumes normal completion rather than staying paused for a tab left behind.
releaseExternalViews(socket, sessionId);
console.log(`🐚 Attached session ${sessionId.slice(0, 8)} to socket ${socket.id}`);
// Broadcast so other clients pick up the new `attached: true` state and skip
// this session in their auto-pick flow.
broadcastSessionList();
return {
sessionId,
bufferedOutput: session.replay.render()
};
}
// Subscribers for session list broadcasts
const sessionListSubscribers = new Set();
export function subscribeSessionList(socket) {
sessionListSubscribers.add(socket);
}
export function unsubscribeSessionList(socket) {
sessionListSubscribers.delete(socket);
}
function broadcastSessionList() {
// Each subscriber gets a recipient-relative list so `attached` reflects "attached
// to a different tab" from that subscriber's POV. See listAllSessions().
for (const sock of sessionListSubscribers) {
sock.emit('shell:sessions', listAllSessions(sock));
}
}
/**
* List all active sessions with metadata
*
* When `forSocket` is provided, `attached` is recipient-relative: TRUE only if the
* session is bound to a DIFFERENT socket than the recipient. Sessions bound to the
* recipient's own socket — or unbound — report `attached: false`. This lets clients
* use `attached` as a "don't auto-pick this, it belongs to someone else" signal
* without accidentally filtering out their own live sessions when they return to
* the page (the SocketProvider singleton keeps the socket alive across navigations,
* so sessions opened earlier in this tab stay bound to it).
*
* Omitting `forSocket` returns the globally-attached view (used only by callers
* that don't have a recipient context — currently none in PortOS).
*/
export function listAllSessions(forSocket = null) {
const sessions = [];
for (const [sessionId, session] of shellSessions.entries()) {
sessions.push({
sessionId,
cwd: session.cwd,
createdAt: session.createdAt,
label: session.label,
kind: session.kind,
agentId: session.agentId,
command: session.command,
external: !!session.external,
attached: forSocket
? (!!session.socket && session.socket !== forSocket)
: !!session.socket
});
}
return sessions;
}
export function getSession(sessionId) {
return shellSessions.get(sessionId) || null;
}
export function getSessionProcess(sessionId) {
return shellSessions.get(sessionId)?.pty || null;
}
// Automatic xterm replies to the TUI's own queries/focus tracking: focus
// in/out, CPR, DA1/DA2, DSR, and OSC color answers. An attached viewer emits
// these unprompted, so they are not a person typing over a pasted prompt.
// eslint-disable-next-line no-control-regex
const TERMINAL_REPLY_RE = /^(?:\x1b\[[IO]|\x1b\[[?>]?[\d;]*[Rcn]|\x1b\][\s\S]*?(?:\x07|\x1b\\))+$/;
/**
* Write input to a shell session
*/
export function writeToSession(sessionId, data, options) {
const session = shellSessions.get(sessionId);
if (session) {
session.lastInputAt = Date.now();
// pasteToSession cancels its Enter retries when this moves; a terminal
// protocol reply must not, or an attached viewer silently strands the
// pasted prompt unsubmitted.
if (!TERMINAL_REPLY_RE.test(data)) session.inputRevision = (session.inputRevision || 0) + 1;
// Runner proxies carry submission evidence alongside the Enter. Native
// node-pty sessions retain their ordinary one-argument write contract.
if (session.external && options?.promptSubmission) session.pty.write(data, options);
else session.pty.write(data);
return true;
}
return false;
}
/**
* Type a command line into a session and press Enter.
*
* Every "inject a command the user didn't type" path goes through here so the
* terminator is decided once — see SUBMIT_KEY for why it isn't a newline.
*
* @param {string} sessionId
* @param {string} line - command line, WITHOUT a trailing terminator
* @returns {boolean} false when the session is unknown
*/
export function submitToSession(sessionId, line) {
return writeToSession(sessionId, `${line}${SUBMIT_KEY}`);
}
/**
* Change a session's working directory.
*
* Goes through the service rather than the client emitting its own `cd` string,
* because only the server knows which shell this PTY is running — and the command
* differs per shell. See lib/shellCd.js for why.
*
* Updates `session.cwd` on success — see the body for why that is optimistic.
*
* @param {string} sessionId
* @param {string} dirPath
* @returns {boolean} false when the session is unknown, or has no hosting shell
*/
export function changeSessionDirectory(sessionId, dirPath) {
const session = shellSessions.get(sessionId);
if (!session) return false;
// A session with no hosting shell — an external (TUI-run) view, or a direct
// `spawnCommandSession` PTY — has nothing reading that line: the bytes land in
// the agent as typed text and the trailing Enter posts them as a message. Refuse
// rather than type into someone else's run — socket.js turns this into an error the
// Shell page shows. Its `cwd` also stays pinned to the repo the RUN was spawned in,
// which is what workspaceContext groups runs by.
if (session.external || !session.shell) return false;
if (!submitToSession(sessionId, buildCdCommand(dirPath, session.shell))) return false;
// Track the cd optimistically so the Shell tab label and the Workspace Contexts
// widget follow the session instead of staying pinned to its spawn directory.
// `cwd` is display-only after spawn — nothing functional reads it — and the paths
// come from the managed-apps list, so they exist. Asking the PTY for its REAL cwd
// would need a per-platform probe plus a round-trip, which is not worth it for a
// label; a rejected path just leaves the label wrong until the next cd.
session.cwd = dirPath;
broadcastSessionList();
return true;
}
/**
* Deliver `text` to a session as a SINGLE bracketed-paste event, then submit it.
*
* This is how you hand a message to a live agent TUI rather than to a shell:
* Claude Code reads `ESC[200~…ESC[201~` as one paste, so a multi-line message
* lands as one input event instead of N submits.
*
* The returned interval handle lets lifecycle-aware callers cancel pending
* submission retries. The helper self-cancels when the session disappears,
* newer input arrives, or its attempt budget is spent.
*
* @param {string} sessionId
* @param {string} text - paste payload (no trailing newline; the Enter submits it)
* @param {object} [opts]
* @param {string} [opts.label='paste'] - log label for the submit-Enter failure path
* @returns {ReturnType<typeof setInterval>|false} false when the session is unknown
*/
export function pasteToSession(sessionId, text, { label = 'paste' } = {}) {
if (!writeToSession(sessionId, `\x1b[200~${text}\x1b[201~`)) return false;
const session = shellSessions.get(sessionId);
let expectedInputRevision = session.inputRevision;
const writeEnter = () => {
try {
writeToSession(sessionId, SUBMIT_KEY);
expectedInputRevision = session.inputRevision;
} catch (err) {
// Timer callbacks run outside the request lifecycle, and a write to a
// live-but-broken PTY can throw.
console.error(`🐚 ${label} submit Enter failed for ${sessionId.slice(0, 8)}: ${err.message}`);
}
};
return scheduleSubmitEnters(
writeEnter,
() => !shellSessions.has(sessionId) || session.inputRevision !== expectedInputRevision,
);
}
/**
* When input was last written to this session (human paste/keystrokes via
* `shell:input`, or an internal writer like the CoS agent's auto-paste) — or
* `null` if none yet. Unlike a socket-attached check, this recency naturally
* expires once nobody is actually interacting, so it can't get stuck forever
* the way "is a socket bound" can for a regular (non-external) session whose
* viewer navigated away without disconnecting.
*/
export function getLastInputAt(sessionId) {
return shellSessions.get(sessionId)?.lastInputAt || null;
}
/**
* Resize a shell session
*/
export function resizeSession(sessionId, cols, rows) {
const session = shellSessions.get(sessionId);
if (session) {
try {
session.pty.resize(cols, rows);
return true;
} catch (err) {
console.warn(`🐚 Failed to resize shell session ${sessionId}: ${err.message}`);
return false;
}
}
return false;
}
/**
* Kill a shell session
*/
export function killSession(sessionId) {
const session = shellSessions.get(sessionId);
if (session) {
console.log(`🐚 Killing shell session ${sessionId}`);
session.pty.kill();
shellSessions.delete(sessionId);
runHook('onExit', session, session.onExit, { exitCode: null, killed: true });
broadcastSessionList();
return true;
}
return false;
}
/**
* Detach all sessions from a socket (on disconnect) — sessions stay alive
*/
export function detachSocketSessions(socket) {
let count = 0;
for (const [, session] of shellSessions.entries()) {
if (session.socket === socket) {
session.socket = null;
count++;
}
}
unsubscribeSessionList(socket);
// Broadcast so other tabs see the freed `attached: false` state and can adopt
// these orphaned sessions in their auto-pick flow.
if (count > 0) broadcastSessionList();
return count;
}
/**
* Get session count
*/
export function getSessionCount() {
return shellSessions.size;
}