@volter/supercode-terminal 0.2.30

package/substrate/internal/exec.js

@@ -0,0 +1,192 @@
+import { spawn, spawnSync } from "node:child_process";
+function runEnvironment(options) {
+    if (options.inheritEnv === false) {
+        return options.env ?? {};
+    }
+    return options.env ? { ...process.env, ...options.env } : process.env;
+}
+// Memoized by command name: PATH is finalized once at process startup
+// (ensureSystemToolsOnPath, called before any subprocess runs) and never changes
+// for the rest of the process's life in this codebase's usage, so re-spawning
+// `command -v <name>` on every call is pure repeated cost. This matters because
+// requireCommand/assertTmux-style guards run on hot per-request paths (e.g.
+// captureTerminal calling assertTmux on every capture) — a synchronous spawnSync
+// there would otherwise reintroduce a small blocking cost on every single call,
+// undermining the whole point of an async capture path (see CLAUDE.md's
+// event-loop invariant).
+const commandExistsCache = new Map();
+export function commandExists(command) {
+    const cached = commandExistsCache.get(command);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const result = spawnSync("command", ["-v", command], {
+        encoding: "utf8",
+        shell: true
+    });
+    const exists = result.status === 0;
+    commandExistsCache.set(command, exists);
+    return exists;
+}
+export function requireCommand(command, installHint) {
+    if (!commandExists(command)) {
+        const hint = installHint ? ` ${installHint}` : "";
+        throw new Error(`${command} is required but was not found on PATH.${hint}`);
+    }
+}
+// The standard system tool directories. Appended (never reordered) to PATH at
+// process startup so `run`/`execFile` of ps, tmux, and coreutils resolve even when
+// the process was launched from a stripped-PATH context — cron, launchd, a GUI
+// app, or a nested agent shell whose PATH was degraded. A provider booted that way
+// otherwise silently loses its lifecycle observation (`spawn ps ENOENT`) while
+// healthz still answers. Non-existent dirs (e.g. /opt/homebrew on Intel/Linux) are
+// harmless — the OS skips them during lookup.
+const systemToolDirs = ["/usr/bin", "/bin", "/usr/sbin", "/sbin", "/usr/local/bin", "/opt/homebrew/bin"];
+// Guarantee the system tool dirs are on PATH without disturbing the caller's own
+// order or entries: only the missing ones are appended. Call once at entrypoint
+// startup, before any subprocess runs. Idempotent.
+export function ensureSystemToolsOnPath() {
+    const current = (process.env.PATH ?? "").split(":").filter(Boolean);
+    const have = new Set(current);
+    const missing = systemToolDirs.filter((dir) => !have.has(dir));
+    if (missing.length > 0) {
+        process.env.PATH = [...current, ...missing].join(":");
+    }
+}
+export function run(command, args, options = {}) {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd,
+        encoding: "utf8",
+        env: runEnvironment(options),
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: options.timeoutMs
+    });
+    if (result.error) {
+        const message = result.error.name === "Error" && "code" in result.error && result.error.code === "ETIMEDOUT"
+            ? `${command} ${args.join(" ")} timed out after ${options.timeoutMs}ms.`
+            : result.error.message;
+        const detail = runOutputDetail(result.stdout, result.stderr);
+        if (detail) {
+            throw new Error(`${message}\n${detail}`);
+        }
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        const output = runOutputDetail(result.stdout, result.stderr);
+        const detail = output ? `\n${output}` : "";
+        throw new Error(`${command} ${args.join(" ")} failed with exit ${result.status}.${detail}`);
+    }
+    return result.stdout;
+}
+function runOutputDetail(stdout, stderr) {
+    const stderrText = outputText(stderr);
+    const stdoutText = outputText(stdout);
+    if (stderrText && stdoutText) {
+        return `stderr:\n${stderrText}\nstdout:\n${stdoutText}`;
+    }
+    if (stderrText) {
+        return `stderr:\n${stderrText}`;
+    }
+    if (stdoutText) {
+        return `stdout:\n${stdoutText}`;
+    }
+    return "";
+}
+function outputText(value) {
+    if (Buffer.isBuffer(value)) {
+        return value.toString("utf8").trim();
+    }
+    return String(value ?? "").trim();
+}
+export function runBuffer(command, args, options = {}) {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd,
+        env: runEnvironment(options),
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        const stderr = Buffer.isBuffer(result.stderr) ? result.stderr.toString("utf8").trim() : String(result.stderr ?? "").trim();
+        const detail = stderr ? `\n${stderr}` : "";
+        throw new Error(`${command} ${args.join(" ")} failed with exit ${result.status}.${detail}`);
+    }
+    return Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(result.stdout ?? "");
+}
+export function runWithInput(command, args, input, options = {}) {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd,
+        env: runEnvironment(options),
+        input,
+        stdio: ["pipe", "pipe", "pipe"]
+    });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        const stderr = Buffer.isBuffer(result.stderr) ? result.stderr.toString("utf8").trim() : String(result.stderr ?? "").trim();
+        const detail = stderr ? `\n${stderr}` : "";
+        throw new Error(`${command} ${args.join(" ")} failed with exit ${result.status}.${detail}`);
+    }
+    return Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(result.stdout ?? "");
+}
+export async function runAsync(command, args, options = {}) {
+    return await spawnAsync(command, args, options);
+}
+export async function runWithInputAsync(command, args, input, options = {}) {
+    return await spawnAsync(command, args, options, input);
+}
+async function spawnAsync(command, args, options, input) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: runEnvironment(options),
+            stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"]
+        });
+        const stdout = [];
+        const stderr = [];
+        // Honor timeoutMs without blocking the loop (the sync `run` relied on
+        // spawnSync's timeout): SIGKILL the child and reject if it overruns.
+        const timer = options.timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                child.kill("SIGKILL");
+                reject(new Error(`${command} ${args.join(" ")} timed out after ${options.timeoutMs}ms.`));
+            }, options.timeoutMs);
+        timer?.unref?.();
+        const clear = () => {
+            if (timer)
+                clearTimeout(timer);
+        };
+        child.stdout?.on("data", (chunk) => stdout.push(chunk));
+        child.stderr?.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", (error) => {
+            clear();
+            reject(error);
+        });
+        child.on("close", (code) => {
+            clear();
+            if (code !== 0) {
+                const detail = Buffer.concat(stderr).toString("utf8").trim();
+                reject(new Error(`${command} ${args.join(" ")} failed with exit ${code}.${detail ? `\n${detail}` : ""}`));
+                return;
+            }
+            resolve(Buffer.concat(stdout).toString("utf8"));
+        });
+        if (input !== undefined && child.stdin) {
+            child.stdin.on("error", reject);
+            child.stdin.end(input);
+        }
+    });
+}
+export function spawnInherited(command, args) {
+    const child = spawn(command, args, { stdio: "inherit" });
+    child.on("exit", (code, signal) => {
+        if (signal) {
+            process.kill(process.pid, signal);
+            return;
+        }
+        process.exit(code ?? 1);
+    });
+}

package/substrate/internal/process-tree.d.ts

@@ -0,0 +1 @@
+export declare function snapshotDescendantPids(rootPids: number[]): number[];

package/substrate/internal/process-tree.js

@@ -0,0 +1,41 @@
+import { execFileSync } from "node:child_process";
+const PROCESS_SNAPSHOT_MAX_BUFFER = 16 * 1024 * 1024;
+// Return only each requested root and its descendants. This is the safe input
+// to the tmux session cleanup sweep: the tmux server is a parent and therefore
+// can never be selected, while helpers detached below a pane remain reachable.
+export function snapshotDescendantPids(rootPids) {
+    if (rootPids.length === 0)
+        return [];
+    const stdout = execFileSync("ps", ["-axo", "pid=,ppid="], {
+        encoding: "utf8",
+        maxBuffer: PROCESS_SNAPSHOT_MAX_BUFFER,
+        timeout: 5000
+    });
+    const children = new Map();
+    const processIds = new Set();
+    for (const line of stdout.split("\n")) {
+        const match = line.trim().match(/^(\d+)\s+(\d+)$/);
+        if (!match)
+            continue;
+        const pid = Number(match[1]);
+        const parent = Number(match[2]);
+        if (!Number.isInteger(pid) || pid < 1 || !Number.isInteger(parent) || parent < 0)
+            continue;
+        processIds.add(pid);
+        const siblings = children.get(parent) ?? [];
+        siblings.push(pid);
+        children.set(parent, siblings);
+    }
+    const result = [];
+    const pending = [...new Set(rootPids.filter((pid) => processIds.has(pid)))];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const pid = pending.pop();
+        if (pid === undefined || seen.has(pid))
+            continue;
+        seen.add(pid);
+        result.push(pid);
+        pending.push(...(children.get(pid) ?? []));
+    }
+    return result.sort((a, b) => a - b);
+}

package/substrate/local-terminal.d.ts

@@ -0,0 +1,13 @@
+export interface LocalTerminalCommand {
+    program: string;
+    arguments?: readonly string[];
+    cwd?: string;
+    env?: Readonly<Record<string, string>>;
+}
+export type LocalTerminalRunner = (program: string, arguments_: readonly string[]) => Promise<void>;
+export interface OpenLocalTerminalOptions {
+    platform?: NodeJS.Platform;
+    runner?: LocalTerminalRunner;
+}
+export declare function terminalShellCommand(command: LocalTerminalCommand): string;
+export declare function openLocalTerminal(command: LocalTerminalCommand, options?: OpenLocalTerminalOptions): Promise<void>;

package/substrate/local-terminal.js

@@ -0,0 +1,41 @@
+import { runAsync } from "./internal/exec.js";
+const APPLE_SCRIPT = [
+    "on run argv",
+    "ignoring application responses",
+    'tell application "Terminal"',
+    "activate",
+    "do script (item 1 of argv)",
+    "end tell",
+    "end ignoring",
+    "end run",
+].join("\n");
+export function terminalShellCommand(command) {
+    if (!command.program)
+        throw new Error("A terminal command program is required.");
+    const environment = Object.entries(command.env ?? {}).map(([name, value]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+            throw new Error(`Invalid terminal environment variable name: ${JSON.stringify(name)}.`);
+        }
+        return `${name}=${value}`;
+    });
+    const launch = [
+        ...(environment.length ? ["env", ...environment] : []),
+        command.program,
+        ...(command.arguments ?? []),
+    ].map(shellQuote).join(" ");
+    return command.cwd ? `cd ${shellQuote(command.cwd)} && exec ${launch}` : `exec ${launch}`;
+}
+export async function openLocalTerminal(command, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== "darwin") {
+        throw new Error(`Opening a local terminal is not supported on ${platform}.`);
+    }
+    const runner = options.runner ?? defaultRunner;
+    await runner("osascript", ["-e", APPLE_SCRIPT, terminalShellCommand(command)]);
+}
+async function defaultRunner(program, arguments_) {
+    await runAsync(program, [...arguments_], { timeoutMs: 5_000 });
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}

package/substrate/native-host.d.ts

@@ -0,0 +1,57 @@
+import { type LocalTerminalCommand } from "./local-terminal.js";
+import { type SessionLifecycleState } from "./session-lifecycle.js";
+export type NativeTerminalBackend = "iterm" | "native-terminal-app";
+export type NativeTerminalSession = Readonly<{
+    agentSessionId: string;
+    backend: NativeTerminalBackend;
+    state: SessionLifecycleState;
+}>;
+export type NativeSessionIdleProof = Readonly<{
+    observedAtMs: number;
+    source: string;
+    turn: "idle";
+}>;
+export type NativeSessionResolution = Readonly<{
+    proof: NativeSessionIdleProof;
+    session: NativeTerminalSession;
+}>;
+export type NativeTerminalApplication = "iterm" | "terminal";
+/**
+ * Host-only local terminal capability for embedders.
+ *
+ * The public surface contains durable agent session ids and semantic state only.
+ * Native window ids, tty paths, process ids, AppleScript references, and tmux
+ * handles remain private to this process.
+ */
+export declare class NativeTerminalSessionHost {
+    private readonly lifecycleStore;
+    private readonly rollTracker;
+    private observationPending;
+    private readonly claudeConfigDir;
+    private readonly resolvedSessionIds;
+    private sessions;
+    constructor(options?: {
+        home?: string;
+        claudeConfigDir?: string;
+    });
+    listSessions(): Promise<NativeTerminalSession[]>;
+    private observeSessions;
+    captureSession(agentSessionId: string, options?: {
+        lines?: number;
+    }): Promise<string>;
+    openSession(command: LocalTerminalCommand, options: {
+        application: NativeTerminalApplication;
+    }): Promise<void>;
+    hasSessionCandidate(agentSessionId: string, options: {
+        cwd: string;
+    }): boolean;
+    resolveSession(agentSessionId: string, options: {
+        cwd: string;
+    }): Promise<NativeSessionResolution | null>;
+    relinquishSession(agentSessionId: string, proof: NativeSessionIdleProof): Promise<{
+        agentSessionId: string;
+        released: true;
+    }>;
+    private requireSession;
+    private observeSurfaces;
+}