@termfleet/core 0.1.0

package/dist/agent-launch.d.ts

@@ -0,0 +1,78 @@
+export type AgentKind = "claude" | "codex" | "gemini";
+export type AgentWindowCreateOptions = {
+    agent: AgentKind;
+    agentCwd?: string;
+    createTimeoutMs?: number;
+    cwd?: string;
+    model?: string;
+    name?: string;
+    prompt?: string;
+    agentSessionId?: string;
+    resume?: boolean;
+    setupCommand?: string;
+};
+export type AgentWindowCreateResult = {
+    agent: AgentKind;
+    agentSessionId?: string;
+    command: string;
+    cwd?: string;
+    result: unknown;
+    terminalId?: string;
+};
+export type AgentLaunchResponder = {
+    input: string;
+    matches(content: string): boolean;
+};
+export type AgentLaunchStage = "agent-start" | "preflight" | "session-capture" | "window-create";
+export type AgentLaunchErrorDetail = {
+    capture?: string;
+    launchTraceFile?: string;
+    path?: string;
+    session?: string;
+    windowId?: number;
+};
+export type AgentLaunchErrorPayload = AgentLaunchErrorDetail & {
+    code: string;
+    message: string;
+    stage: AgentLaunchStage;
+};
+export declare class AgentLaunchError extends Error {
+    readonly code: string;
+    readonly detail: AgentLaunchErrorDetail;
+    readonly stage: AgentLaunchStage;
+    constructor({ code, detail, message, stage }: {
+        code: string;
+        detail?: AgentLaunchErrorDetail;
+        message: string;
+        stage: AgentLaunchStage;
+    });
+    toJSON(): AgentLaunchErrorPayload;
+}
+export declare function parseAgentLaunchErrorPayload(value: unknown): AgentLaunchError | undefined;
+export declare function isAgentLaunchStage(value: unknown): value is AgentLaunchStage;
+export declare function buildAgentStartupCommand(options: AgentWindowCreateOptions & {
+    openedAtCwd?: boolean;
+    promptFile?: string;
+}): {
+    agentSessionId?: string;
+    command: string;
+};
+export declare function defaultAgentCommand(agent: AgentKind, sessionId?: string, options?: {
+    model?: string;
+    resume?: boolean;
+    trustedCwd?: string;
+}): string;
+export declare function buildStartupCommand(command: string, options: {
+    agentCwd?: string;
+    cwd?: string;
+    openedAtCwd?: boolean;
+    prompt?: string;
+    promptFile?: string;
+    setupCommand?: string;
+}): string;
+export declare function isShellPromptReady(content: string): boolean;
+export declare function agentLaunchResponders(agent: AgentKind): AgentLaunchResponder[];
+export declare function isAgentLaunchReady(content: string, agent: AgentKind): boolean;
+export declare function detectAgentLaunchFailure(content: string, agent: AgentKind): string | undefined;
+export declare function shellQuote(value: string): string;
+export declare function isUuid(value: string): boolean;

package/dist/agent-launch.js

@@ -0,0 +1,247 @@
+// Structured launch failure. Agent launches fail at distinct stages (preflight
+// cwd checks, window creation, agent boot, terminal-session capture) and callers
+// need to branch on a machine-readable stage/code instead of string-matching
+// prose. Crosses the provider control socket as a payload via toJSON and is
+// rebuilt by parseAgentLaunchErrorPayload on the client. The startup-hang case
+// (no transcript after the first-write deadline) is the retryable agent-start
+// failure — see isRetryableAgentLaunchError in the provider engine.
+export class AgentLaunchError extends Error {
+    code;
+    detail;
+    stage;
+    constructor({ code, detail = {}, message, stage }) {
+        super(message);
+        this.name = "AgentLaunchError";
+        this.code = code;
+        this.detail = detail;
+        this.stage = stage;
+    }
+    toJSON() {
+        return {
+            code: this.code,
+            ...this.detail,
+            message: this.message,
+            stage: this.stage
+        };
+    }
+}
+export function parseAgentLaunchErrorPayload(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const { capture, code, launchTraceFile, message, path, session, stage, windowId } = value;
+    if (typeof code !== "string" || typeof message !== "string" || !isAgentLaunchStage(stage)) {
+        return undefined;
+    }
+    return new AgentLaunchError({
+        code,
+        detail: {
+            ...(typeof capture === "string" ? { capture } : {}),
+            ...(typeof launchTraceFile === "string" ? { launchTraceFile } : {}),
+            ...(typeof path === "string" ? { path } : {}),
+            ...(typeof session === "string" ? { session } : {}),
+            ...(typeof windowId === "number" && Number.isInteger(windowId) ? { windowId } : {})
+        },
+        message,
+        stage
+    });
+}
+export function isAgentLaunchStage(value) {
+    return value === "agent-start" || value === "preflight" || value === "session-capture" || value === "window-create";
+}
+export function buildAgentStartupCommand(options) {
+    if (options.agent === "codex" && options.agentSessionId) {
+        throw new Error("Codex launches do not support explicit session ids yet.");
+    }
+    if (options.resume && !options.agentSessionId) {
+        throw new Error("Resuming an agent session requires an explicit session id.");
+    }
+    // Claude and Gemini both take an explicit UUID session id (claude --session-id,
+    // gemini --session-id); codex does not.
+    const bareAgentSessionId = options.agent === "claude" || options.agent === "gemini"
+        ? normalizeAgentSessionId(options.agent, options.agentSessionId ?? createUuid())
+        : undefined;
+    if (bareAgentSessionId && !isUuid(bareAgentSessionId)) {
+        throw new Error(`${options.agent} requires a UUID session id.`);
+    }
+    const command = buildStartupCommand(defaultAgentCommand(options.agent, bareAgentSessionId, {
+        model: options.model,
+        resume: Boolean(options.resume),
+        trustedCwd: options.agentCwd ?? options.cwd
+    }), {
+        agentCwd: options.agentCwd,
+        cwd: options.cwd,
+        openedAtCwd: options.openedAtCwd,
+        prompt: options.promptFile ? undefined : options.prompt,
+        promptFile: options.promptFile,
+        setupCommand: options.setupCommand
+    });
+    const agentSessionId = bareAgentSessionId ? `${options.agent}:${bareAgentSessionId}` : undefined;
+    return {
+        ...(agentSessionId ? { agentSessionId } : {}),
+        command
+    };
+}
+function normalizeAgentSessionId(agent, sessionId) {
+    return sessionId.startsWith(`${agent}:`) ? sessionId.slice(agent.length + 1) : sessionId;
+}
+export function defaultAgentCommand(agent, sessionId, options) {
+    const modelFlag = options?.model ? `--model ${shellQuote(options.model)}` : undefined;
+    if (agent === "claude") {
+        // --resume <id> reattaches to an existing conversation; --session-id <id>
+        // creates a new one with that id (and fails if it already exists).
+        const sessionFlag = sessionId
+            ? options?.resume
+                ? `--resume ${shellQuote(sessionId)}`
+                : `--session-id ${shellQuote(sessionId)}`
+            : undefined;
+        return [
+            "CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1",
+            "claude",
+            "--dangerously-skip-permissions",
+            modelFlag,
+            sessionFlag
+        ].filter((part) => Boolean(part)).join(" ");
+    }
+    if (agent === "gemini") {
+        // --skip-trust avoids the workspace-trust prompt; --session-id seeds a new
+        // session with our UUID (resume-by-uuid isn't supported — gemini resumes by
+        // index/latest, handled separately). The prompt is appended positionally by
+        // buildStartupCommand (gemini's `query` arg runs interactive by default).
+        const sessionFlag = sessionId && !options?.resume ? `--session-id ${shellQuote(sessionId)}` : undefined;
+        return [
+            "gemini",
+            "--skip-trust",
+            sessionFlag,
+            modelFlag
+        ].filter((part) => Boolean(part)).join(" ");
+    }
+    return [
+        "codex",
+        "--dangerously-bypass-approvals-and-sandbox",
+        "--dangerously-bypass-hook-trust",
+        options?.trustedCwd ? `-c ${shellQuote(`projects.${JSON.stringify(options.trustedCwd)}.trust_level="trusted"`)} ` : undefined,
+        modelFlag
+    ].filter((part) => Boolean(part)).join(" ");
+}
+export function buildStartupCommand(command, options) {
+    const cwdPrefix = options.openedAtCwd || !options.cwd ? undefined : `cd ${shellQuote(options.cwd)}`;
+    // The prompt file is a short-lived launch artifact (written 0600). Read it into
+    // a shell var and delete it BEFORE the agent runs, so it never lingers in /tmp
+    // even for a long-running session. Argv exposure is identical to inlining
+    // "$(cat …)" — both expand into the launched process's arguments.
+    const quotedPromptFile = options.promptFile ? shellQuote(options.promptFile) : undefined;
+    const agentCommand = quotedPromptFile
+        ? `__tf_prompt="$(cat ${quotedPromptFile})" && rm -f ${quotedPromptFile} && ${command} "$__tf_prompt"`
+        : options.prompt ? `${command} ${shellQuote(options.prompt)}` : command;
+    return [
+        cwdPrefix,
+        options.setupCommand,
+        options.agentCwd ? `cd ${shellQuote(options.agentCwd)}` : undefined,
+        agentCommand
+    ].filter((part) => Boolean(part)).join(" && ");
+}
+// Conservative heuristic for "the pane's shell is at a prompt and reading
+// input": the last visible line ends with a common prompt terminator. Used
+// before typing a launch command into a freshly created pane, where typing
+// during shell startup races the line editor.
+export function isShellPromptReady(content) {
+    const lines = content.split("\n").map((line) => line.trimEnd()).filter((line) => line.length > 0);
+    const lastLine = lines.at(-1);
+    return lastLine !== undefined && /[$%#>❯]$/.test(lastLine);
+}
+export function agentLaunchResponders(agent) {
+    if (agent === "claude")
+        return claudeLaunchResponders;
+    if (agent === "gemini")
+        return geminiLaunchResponders;
+    return codexLaunchResponders;
+}
+export function isAgentLaunchReady(content, agent) {
+    if (agent === "claude") {
+        return /Claude Code/i.test(content)
+            && !content.includes("WARNING: Claude Code running in Bypass Permissions mode")
+            && /[❯>]\s*$/.test(content.trimEnd());
+    }
+    if (agent === "gemini") {
+        return /gemini/i.test(content) && /[❯>]\s*$/.test(content.trimEnd());
+    }
+    return /codex/i.test(content) && /[❯>]\s*$/.test(content.trimEnd());
+}
+export function detectAgentLaunchFailure(content, agent) {
+    if (agent === "claude") {
+        if (/Select login method:/i.test(content)) {
+            return "Claude Code is not logged in for this Docker session.";
+        }
+        if (/Claude configuration file not found at:/i.test(content)) {
+            return "Claude Code configuration is missing for this Docker session.";
+        }
+        if (/A backup file exists at:/i.test(content) && /You can manually restore it by running:/i.test(content)) {
+            return "Claude Code configuration is missing for this Docker session, but a backup exists.";
+        }
+        if (/Please run\s+\/login/i.test(content) && /API Error:\s*401 Invalid authentication credentials/i.test(content)) {
+            return "Claude Code credentials are invalid for this Docker session. Run /login in the session or remount a valid Claude home.";
+        }
+        if (/EROFS:\s*read-only file system/i.test(content) && /\.claude/i.test(content)) {
+            return "Claude Code cannot write to its mounted .claude directory. Mount Claude credentials read-write for Docker workers.";
+        }
+    }
+    if (agent === "gemini") {
+        // Verified against gemini-cli 0.47 run with no credentials: it prints exactly
+        // "Please set an Auth method in your …/.gemini/settings.json or specify one of
+        // the following environment variables …: GEMINI_API_KEY, …". High-precision and
+        // unambiguous — a healthy launch never prints it.
+        if (/Please set an Auth method/i.test(content)) {
+            return "Gemini is not authenticated. Set GEMINI_API_KEY (or configure an auth method in .gemini/settings.json) for this session.";
+        }
+    }
+    return undefined;
+}
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+export function isUuid(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function createUuid() {
+    const randomUUID = globalThis.crypto?.randomUUID;
+    if (randomUUID) {
+        return randomUUID.call(globalThis.crypto);
+    }
+    return "10000000-1000-4000-8000-100000000000".replace(/[018]/g, (character) => {
+        const value = Number(character);
+        return (value ^ Math.random() * 16 >> value / 4).toString(16);
+    });
+}
+const claudeLaunchResponders = [
+    {
+        input: "\n",
+        matches: (content) => /Is this a project you created or one you trust\?/i.test(content)
+            && /Yes, I trust this folder/i.test(content)
+    },
+    {
+        input: "\n",
+        matches: (content) => /Choose the text style that looks best with your terminal/i.test(content)
+    },
+    {
+        input: "\x1b[B\n",
+        matches: (content) => /Try the new fullscreen renderer\?/i.test(content)
+            && /Not now/i.test(content)
+    },
+    {
+        input: "2\n",
+        matches: (content) => content.includes("WARNING: Claude Code running in Bypass Permissions mode")
+            && content.includes("Yes, I accept")
+    }
+];
+const codexLaunchResponders = [
+    {
+        input: "y\n",
+        matches: (content) => /trust|continue|confirm|approve|permission/i.test(content)
+            && /codex/i.test(content)
+    }
+];
+// --skip-trust suppresses the workspace-trust prompt and Gemini is already
+// authed, so no launch responders are needed in the common case. (bootstrapAgentLaunch
+// gives up gracefully if the ready check never matches — the agent still launched.)
+const geminiLaunchResponders = [];

package/dist/agent-session-id.d.ts

@@ -0,0 +1,10 @@
+import type { AgentProvider } from "./agent-session-index.js";
+export declare const agentProviders: readonly ["claude", "codex", "gemini"];
+export declare function isAgentProvider(value: string): value is AgentProvider;
+export declare function formatAgentSessionId(agent: AgentProvider, bareId: string): string;
+export declare function parseAgentSessionId(agentSessionId: string): {
+    agent: AgentProvider;
+    bareId: string;
+} | undefined;
+export declare function bareAgentSessionId(agentSessionId: string): string;
+export declare function isLiveAgentSessionId(sessionId: string | null | undefined): boolean;

package/dist/agent-session-id.js

@@ -0,0 +1,36 @@
+// The agentSessionId is the identity of the primary abstraction: an agent prefix
+// (claude:/codex:/gemini:) plus the agent's own bare session id. This is the ONE
+// owner of that grammar — every surface (CLI, SDK, MCP, the provider socket gates,
+// the session→window descent) parses/formats it here and shares one valid-prefix
+// set, so adding a fourth agent is a single edit and the gates can't drift apart
+// (they did: a live Gemini terminal used to be refused session-keyed input).
+export const agentProviders = ["claude", "codex", "gemini"];
+// A forked Claude sub-session runs under its own prefix; it hosts a live agent
+// terminal (eligible for session-keyed input) but is not a top-level provider.
+const liveAgentPrefixes = [...agentProviders.map((agent) => `${agent}:`), "claude-subagent:"];
+export function isAgentProvider(value) {
+    return agentProviders.includes(value);
+}
+export function formatAgentSessionId(agent, bareId) {
+    return `${agent}:${bareId}`;
+}
+// Split a prefixed id into { agent, bareId }; undefined for an unprefixed or
+// unknown-prefix id (the caller decides whether that is an error).
+export function parseAgentSessionId(agentSessionId) {
+    const separator = agentSessionId.indexOf(":");
+    if (separator < 0) {
+        return undefined;
+    }
+    const prefix = agentSessionId.slice(0, separator);
+    return isAgentProvider(prefix) ? { agent: prefix, bareId: agentSessionId.slice(separator + 1) } : undefined;
+}
+// The agent's bare service id: drops a known agent prefix, leaves an unprefixed
+// id untouched.
+export function bareAgentSessionId(agentSessionId) {
+    return parseAgentSessionId(agentSessionId)?.bareId ?? agentSessionId;
+}
+// True when this session id names a live agent terminal (claude/codex/gemini, or a
+// claude subagent) — the eligibility gate for session-keyed / break-glass input.
+export function isLiveAgentSessionId(sessionId) {
+    return !!sessionId && liveAgentPrefixes.some((prefix) => sessionId.startsWith(prefix));
+}

package/dist/agent-session-index-client.d.ts

@@ -0,0 +1,7 @@
+import type { AgentSessionIndexPage } from "./agent-session-index.js";
+export declare function listAgentSessionsInWorker(options?: {
+    cursor?: string | null;
+    limit?: number;
+    query?: string;
+}): Promise<AgentSessionIndexPage>;
+export declare function warmAgentSessionIndexInWorker(): Promise<void>;

package/dist/agent-session-index-client.js

@@ -0,0 +1,86 @@
+import { Worker } from "node:worker_threads";
+let worker;
+let nextId = 0;
+const pending = new Map();
+// A request is bounded work (paginated, 64KB head/tail reads, candidate cache).
+// A worker wedged in a synchronous fs call emits neither "error" nor "exit", so
+// without this the promise would hang forever and `pending` would grow per call.
+const requestTimeoutMs = 30_000;
+function ensureWorker() {
+    if (worker)
+        return worker;
+    // Dev runs from .ts via tsx; the built output is .js. In dev, a worker does
+    // not inherit tsx's loader, so spawn a plain-JS bootstrap that registers it
+    // and then imports the TS worker. In the built output, run the .js directly.
+    const isTypeScript = import.meta.url.endsWith(".ts");
+    const workerUrl = isTypeScript
+        ? new URL("./agent-session-index-worker-boot.mjs", import.meta.url)
+        : new URL("./agent-session-index-worker.js", import.meta.url);
+    const next = new Worker(workerUrl);
+    next.on("message", (message) => {
+        const entry = pending.get(message.id);
+        if (!entry)
+            return;
+        pending.delete(message.id);
+        if (message.error)
+            entry.reject(new Error(message.error));
+        else if (message.page)
+            entry.resolve(message.page);
+        else
+            entry.reject(new Error("Agent session index worker returned no page."));
+    });
+    next.on("error", (error) => {
+        const failure = error instanceof Error ? error : new Error(String(error));
+        for (const entry of pending.values())
+            entry.reject(failure);
+        pending.clear();
+        // Terminate the dead worker so its thread/isolate and listeners are released;
+        // a bare `worker = undefined` would leak the isolate on repeated errors.
+        void next.terminate();
+        worker = undefined;
+    });
+    next.on("exit", (code) => {
+        // A worker can die WITHOUT first emitting "error" (OOM kill, terminate, a
+        // throw the runtime turns into a clean exit). Reject any in-flight requests
+        // so the chat list surfaces an error instead of hanging forever.
+        if (pending.size > 0) {
+            const failure = new Error(`Agent session index worker exited (code ${code}).`);
+            for (const entry of pending.values())
+                entry.reject(failure);
+            pending.clear();
+        }
+        worker = undefined;
+    });
+    // Don't keep the process alive on the worker alone (matters for the CLI/tests).
+    next.unref();
+    worker = next;
+    return next;
+}
+export function listAgentSessionsInWorker(options = {}) {
+    const target = ensureWorker();
+    const id = ++nextId;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            if (!pending.has(id))
+                return;
+            pending.delete(id);
+            reject(new Error(`Agent session index timed out after ${requestTimeoutMs}ms.`));
+            // A wedged worker won't recover; terminate it so the next call respawns a
+            // fresh one (the "exit" handler rejects any other in-flight requests).
+            if (worker === target) {
+                void target.terminate();
+                worker = undefined;
+            }
+        }, requestTimeoutMs);
+        timer.unref();
+        pending.set(id, {
+            reject: (error) => { clearTimeout(timer); reject(error); },
+            resolve: (page) => { clearTimeout(timer); resolve(page); }
+        });
+        target.postMessage({ id, ...options });
+    });
+}
+// Prime the worker's caches off the request path (e.g. at provider startup).
+export async function warmAgentSessionIndexInWorker() {
+    await listAgentSessionsInWorker({ limit: 1 });
+}

package/dist/agent-session-index-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agent-session-index-worker.js

@@ -0,0 +1,20 @@
+import { parentPort } from "node:worker_threads";
+import { buildAgentSessionIndex } from "./agent-session-index.js";
+const port = parentPort;
+if (!port) {
+    throw new Error("agent-session-index-worker must be run as a worker thread.");
+}
+port.on("message", async (request) => {
+    try {
+        const page = await buildAgentSessionIndex({
+            ...(request.home ? { home: request.home } : {}),
+            ...(request.limit !== undefined ? { limit: request.limit } : {}),
+            ...(request.cursor !== undefined ? { cursor: request.cursor } : {}),
+            ...(request.query ? { query: request.query } : {})
+        });
+        port.postMessage({ id: request.id, page });
+    }
+    catch (error) {
+        port.postMessage({ error: error instanceof Error ? error.message : String(error), id: request.id });
+    }
+});

package/dist/agent-session-index.d.ts

@@ -0,0 +1,34 @@
+export type MessageKind = "command" | "context" | "message";
+export type SubagentSummary = {
+    count: number;
+};
+export type AgentProvider = "claude" | "codex" | "gemini";
+export type AgentSessionIndexRow = {
+    aiTitle?: string;
+    cwd?: string;
+    preview: string;
+    previewKind: MessageKind;
+    previewRole: "assistant" | "user";
+    provider: AgentProvider;
+    sessionId: string;
+    subagents?: SubagentSummary;
+    title: string;
+    titleKind: MessageKind;
+    transcriptPath: string;
+    updatedAt: string;
+};
+export type AgentSessionIndexPage = {
+    nextCursor: string | null;
+    rows: AgentSessionIndexRow[];
+    total: number;
+};
+export declare function buildAgentSessionIndex(options?: {
+    cursor?: string | null;
+    home?: string;
+    limit?: number;
+    nowMs?: number;
+    query?: string;
+}): Promise<AgentSessionIndexPage>;
+export declare function warmAgentSessionIndex(options?: {
+    home?: string;
+}): Promise<void>;