letagents 0.12.9 → 0.12.11

package/dist/mcp/codex-session/runtime-summary.js

@@ -0,0 +1,220 @@
+const CODEX_RUNTIME_STREAM_SOURCE = "codex_app_server";
+const codexReasoningStreams = new Map();
+export function isCodexAgentSessionMarker(session) {
+    const runtime = String(session.runtime ?? "").trim().toLowerCase();
+    const ideLabel = String(session.ide_label ?? "").trim().toLowerCase();
+    const livenessCapability = String(session.liveness_capability ?? "").trim().toLowerCase();
+    const toolBridgeId = String(session.tool_bridge_id ?? "").trim().toLowerCase();
+    return runtime === "codex" ||
+        ideLabel === "codex" ||
+        livenessCapability.includes("codex") ||
+        /(^|:)codex(:|$)/.test(toolBridgeId);
+}
+function statusForCodexRuntimeMethod(method) {
+    if (/blocked|error|failed/i.test(method))
+        return "blocked";
+    if (/completed|finished|done|stopped|interrupted/i.test(method))
+        return "idle";
+    return "working";
+}
+function compactRuntimeParam(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    const item = typeof record.item === "object" && record.item
+        ? record.item
+        : record;
+    const type = typeof item.type === "string" ? item.type : null;
+    const name = typeof item.name === "string"
+        ? item.name
+        : typeof item.command === "string"
+            ? item.command
+            : null;
+    if (type && name)
+        return `${type}: ${name}`;
+    return type || name;
+}
+function notificationRecord(notification) {
+    return notification.params && typeof notification.params === "object"
+        ? notification.params
+        : {};
+}
+function reasoningStreamKey(record) {
+    const threadId = typeof record.threadId === "string" ? record.threadId : "";
+    const turnId = typeof record.turnId === "string" ? record.turnId : "";
+    const itemId = typeof record.itemId === "string"
+        ? record.itemId
+        : typeof record.item?.id === "string"
+            ? String(record.item.id)
+            : "";
+    return threadId && turnId && itemId ? `${threadId}:${turnId}:${itemId}` : null;
+}
+function ensureReasoningStream(key) {
+    const existing = codexReasoningStreams.get(key);
+    if (existing)
+        return existing;
+    const next = new Map();
+    codexReasoningStreams.set(key, next);
+    return next;
+}
+function coerceReasoningSummaryParts(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((part) => {
+        if (typeof part === "string")
+            return part;
+        if (part && typeof part === "object" && "text" in part) {
+            return String(part.text ?? "");
+        }
+        return "";
+    }).map((part) => part.trim()).filter(Boolean);
+}
+function reasoningSummaryFromStream(stream) {
+    return [...stream.entries()]
+        .sort(([left], [right]) => left - right)
+        .map(([, value]) => value.trim())
+        .filter(Boolean)
+        .join("\n\n")
+        .trim();
+}
+export function summarizeCodexReasoningNotificationForTest(notification) {
+    const method = notification.method.trim();
+    if (!method.startsWith("item/reasoning/") && method !== "item/started" && method !== "item/completed") {
+        return null;
+    }
+    const record = notificationRecord(notification);
+    const item = record.item && typeof record.item === "object"
+        ? record.item
+        : null;
+    const itemType = typeof item?.type === "string" ? item.type : "";
+    if ((method === "item/started" || method === "item/completed") && itemType !== "reasoning") {
+        return null;
+    }
+    const key = reasoningStreamKey(record);
+    if (!key) {
+        return null;
+    }
+    if (method === "item/reasoning/summaryTextDelta") {
+        const summaryIndex = typeof record.summaryIndex === "number" ? record.summaryIndex : 0;
+        const delta = typeof record.delta === "string" ? record.delta : "";
+        const stream = ensureReasoningStream(key);
+        stream.set(summaryIndex, `${stream.get(summaryIndex) ?? ""}${delta}`);
+        const summary = reasoningSummaryFromStream(stream);
+        return {
+            summary: summary || "Codex reasoning summary is streaming.",
+            status: "working",
+            checking: `${CODEX_RUNTIME_STREAM_SOURCE}: readable reasoning summary`,
+            next_action: "Continue streaming the Codex reasoning summary.",
+        };
+    }
+    if (method === "item/reasoning/summaryPartAdded") {
+        const summaryIndex = typeof record.summaryIndex === "number" ? record.summaryIndex : 0;
+        const stream = ensureReasoningStream(key);
+        stream.set(summaryIndex, stream.get(summaryIndex) ?? "");
+        return {
+            summary: reasoningSummaryFromStream(stream) || "Codex started a new reasoning summary section.",
+            status: "working",
+            checking: `${CODEX_RUNTIME_STREAM_SOURCE}: reasoning summary section ${summaryIndex + 1}`,
+            next_action: "Continue streaming the Codex reasoning summary.",
+        };
+    }
+    if (method === "item/reasoning/textDelta") {
+        return {
+            summary: "Codex raw reasoning text is streaming.",
+            status: "working",
+            checking: "Raw reasoning text is available from Codex app-server but hidden by LetAgents by default.",
+            next_action: "Wait for readable reasoning summary deltas or other runtime progress.",
+        };
+    }
+    const stream = ensureReasoningStream(key);
+    const summaryParts = coerceReasoningSummaryParts(item?.summary);
+    if (summaryParts.length) {
+        summaryParts.forEach((part, index) => stream.set(index, part));
+    }
+    const summary = reasoningSummaryFromStream(stream);
+    const completed = method === "item/completed";
+    if (completed) {
+        codexReasoningStreams.delete(key);
+    }
+    return {
+        summary: summary || (completed ? "Codex reasoning summary completed." : "Codex reasoning summary started."),
+        status: completed ? "idle" : "working",
+        checking: `${CODEX_RUNTIME_STREAM_SOURCE}: readable reasoning item`,
+        next_action: completed ? "Waiting for the next Codex runtime event." : "Streaming readable Codex reasoning.",
+    };
+}
+export function summarizeCodexRuntimeNotificationForTest(notification) {
+    const reasoningSummary = summarizeCodexReasoningNotificationForTest(notification);
+    if (reasoningSummary) {
+        return reasoningSummary;
+    }
+    const method = notification.method.trim();
+    const detail = compactRuntimeParam(notification.params);
+    const readableMethod = method.replaceAll("/", " ");
+    const status = statusForCodexRuntimeMethod(method);
+    const suffix = detail ? ` (${detail})` : "";
+    if (/^thread\//i.test(method)) {
+        return {
+            summary: `Codex ${readableMethod}${suffix}`,
+            status,
+            checking: `${CODEX_RUNTIME_STREAM_SOURCE}: ${method}`,
+            next_action: status === "idle" ? "Waiting for the next room event." : "Continuing the Codex worker turn.",
+        };
+    }
+    if (/^turn\//i.test(method)) {
+        return {
+            summary: `Codex ${readableMethod}${suffix}`,
+            status,
+            checking: `${CODEX_RUNTIME_STREAM_SOURCE}: ${method}`,
+            next_action: status === "idle" ? "Turn finished; waiting for room activity." : "Streaming turn progress.",
+        };
+    }
+    if (/^item\//i.test(method)) {
+        return {
+            summary: `Codex ${readableMethod}${suffix}`,
+            status,
+            checking: detail ? `Handling ${detail}.` : `${CODEX_RUNTIME_STREAM_SOURCE}: ${method}`,
+            next_action: status === "idle" ? "Waiting for the next runtime item." : "Continuing runtime work.",
+        };
+    }
+    return {
+        summary: `Codex runtime event: ${readableMethod}${suffix}`,
+        status,
+        checking: `${CODEX_RUNTIME_STREAM_SOURCE}: ${method}`,
+        next_action: status === "idle" ? "Waiting for the next runtime event." : "Continuing runtime work.",
+    };
+}
+export function summarizeCodexRuntimeSnapshotForTest(input) {
+    const recentItems = input.recentItems ?? [];
+    const latestItem = [...recentItems].reverse().find((item) => {
+        const type = String(item.type ?? "");
+        return type === "agentMessage" || type === "userMessage";
+    });
+    const latestText = typeof latestItem?.text === "string" ? latestItem.text.trim() : "";
+    const latestType = String(latestItem?.type ?? "");
+    const turnStatus = typeof input.turnStatus === "string" ? input.turnStatus : "";
+    const threadStatus = typeof input.threadStatus === "string" ? input.threadStatus : "";
+    const status = statusForCodexRuntimeMethod(`${threadStatus} ${turnStatus} ${latestType}`);
+    if (latestText) {
+        return {
+            summary: latestType === "agentMessage" ? latestText : "Codex worker received room input.",
+            status,
+            checking: latestType === "agentMessage"
+                ? "Latest Codex worker message from app-server snapshot."
+                : latestText,
+            next_action: status === "idle" ? "Waiting for the next room event." : "Continuing the Codex worker turn.",
+        };
+    }
+    if (turnStatus || threadStatus) {
+        const statusText = [threadStatus && `thread ${threadStatus}`, turnStatus && `turn ${turnStatus}`]
+            .filter(Boolean)
+            .join(", ");
+        return {
+            summary: `Codex worker ${statusText}.`,
+            status,
+            checking: `${CODEX_RUNTIME_STREAM_SOURCE}: snapshot`,
+            next_action: status === "idle" ? "Waiting for the next room event." : "Monitoring Codex worker progress.",
+        };
+    }
+    return null;
+}

package/dist/mcp/codex-session/session-inspection.js

@@ -0,0 +1,100 @@
+import { getCurrentCodexLiveSession, getStoredCodexLiveSession, updateCodexLiveSession, } from "../local-state.js";
+import { isServerReady } from "./app-server.js";
+import { RpcClient } from "./rpc-client.js";
+import { summarizeCodexRuntimeSnapshotForTest } from "./runtime-summary.js";
+import { deriveCodexLiveSessionStatus, extractThreadStatus, extractTurnStatus, isLikelyMaterializingError, isTerminalCodexSessionStatus, summarizeItems, } from "./session-status.js";
+import { clearSessionMonitor, killOwnedAppServer, postCodexRuntimeReasoningSummary, } from "./session-supervisor.js";
+export async function inspectLocalCodexSession(sessionId, roomId) {
+    const session = sessionId
+        ? getStoredCodexLiveSession(sessionId)
+        : getCurrentCodexLiveSession(roomId ?? undefined);
+    if (!session) {
+        return null;
+    }
+    const serverReachable = await isServerReady(session.server_url);
+    if (!serverReachable) {
+        const updated = updateCodexLiveSession(session.session_id, (current) => ({
+            ...current,
+            status: deriveCodexLiveSessionStatus(current, false, null, null),
+            updated_at: new Date().toISOString(),
+        })) ?? session;
+        if (updated.launched_server) {
+            killOwnedAppServer(updated);
+            clearSessionMonitor(updated.session_id);
+        }
+        return {
+            session: updated,
+            server_reachable: false,
+            thread_status: null,
+            turn_status: null,
+            recent_items: [],
+        };
+    }
+    const client = new RpcClient(session.server_url);
+    try {
+        await client.connect();
+        let read = null;
+        try {
+            read = await client.request("thread/read", {
+                threadId: session.thread_id,
+                includeTurns: true,
+            });
+        }
+        catch (error) {
+            if (!isLikelyMaterializingError(error)) {
+                throw error;
+            }
+        }
+        const turns = read?.thread?.turns ?? [];
+        const turn = turns.find((candidate) => candidate.id === session.turn_id) ?? turns[turns.length - 1];
+        const threadStatus = extractThreadStatus(read?.thread);
+        const turnStatus = extractTurnStatus(turn);
+        const recentItems = summarizeItems(turn?.items ?? turn?.output);
+        const updated = updateCodexLiveSession(session.session_id, (current) => ({
+            ...current,
+            status: deriveCodexLiveSessionStatus(current, true, threadStatus, turnStatus),
+            last_error: null,
+            updated_at: new Date().toISOString(),
+        })) ?? session;
+        if (isTerminalCodexSessionStatus(updated.status)) {
+            killOwnedAppServer(updated);
+            clearSessionMonitor(updated.session_id);
+        }
+        void postCodexRuntimeReasoningSummary(updated, summarizeCodexRuntimeSnapshotForTest({
+            threadStatus,
+            turnStatus,
+            recentItems,
+        })).catch(() => {
+            // Snapshot-derived reasoning should never break session inspection.
+        });
+        return {
+            session: updated,
+            server_reachable: true,
+            thread_status: read?.thread?.status ?? null,
+            turn_status: turn?.status ?? null,
+            recent_items: recentItems,
+        };
+    }
+    catch (error) {
+        const updated = updateCodexLiveSession(session.session_id, (current) => ({
+            ...current,
+            status: "unknown",
+            last_error: error instanceof Error ? error.message : String(error),
+            updated_at: new Date().toISOString(),
+        })) ?? session;
+        if (updated.launched_server) {
+            killOwnedAppServer(updated);
+            clearSessionMonitor(updated.session_id);
+        }
+        return {
+            session: updated,
+            server_reachable: true,
+            thread_status: null,
+            turn_status: null,
+            recent_items: [],
+        };
+    }
+    finally {
+        client.close();
+    }
+}

package/dist/mcp/codex-session/session-mapper.js

@@ -0,0 +1,51 @@
+export function toSessionState(input) {
+    const now = new Date().toISOString();
+    return {
+        session_id: input.session_id,
+        room_id: input.room_id,
+        room_identifier: input.room_identifier,
+        room_code: input.room_code ?? null,
+        room_display_name: input.room_display_name ?? null,
+        joined_via: input.joined_via,
+        cwd: input.cwd,
+        repo_branch: input.repo_branch ?? null,
+        stop_phrase: input.stop_phrase,
+        max_minutes: input.max_minutes,
+        deadline_utc: input.deadline_utc,
+        token: input.token,
+        thread_id: input.thread_id,
+        turn_id: input.turn_id,
+        server_url: input.server_url,
+        server_pid: input.server_pid,
+        launched_server: input.launched_server,
+        codex_bin: input.codex_bin,
+        status: "running",
+        last_error: null,
+        started_at: now,
+        updated_at: now,
+    };
+}
+export function toPublicCodexLiveSession(session) {
+    return {
+        session_id: session.session_id,
+        room_id: session.room_id,
+        room_code: session.room_code ?? null,
+        room_display_name: session.room_display_name ?? null,
+        joined_via: session.joined_via,
+        cwd: session.cwd,
+        repo_branch: session.repo_branch ?? null,
+        stop_phrase: session.stop_phrase,
+        max_minutes: session.max_minutes,
+        deadline_utc: session.deadline_utc ?? null,
+        thread_id: session.thread_id,
+        turn_id: session.turn_id,
+        server_url: session.server_url,
+        server_pid: session.server_pid ?? null,
+        launched_server: session.launched_server,
+        agent_session_id: session.agent_session_id ?? null,
+        status: session.status,
+        last_error: session.last_error ?? null,
+        started_at: session.started_at,
+        updated_at: session.updated_at,
+    };
+}

package/dist/mcp/codex-session/session-start.js

@@ -0,0 +1,182 @@
+import { randomUUID } from "crypto";
+import { resolve } from "path";
+import { getCurrentCodexLiveSession, getStoredCodexLiveSession, saveCodexLiveSession, updateCodexLiveSession, } from "../local-state.js";
+import { getGitCurrentBranch } from "../git-remote.js";
+import { isServerReady, launchAppServer, resolveCodexServerUrl, terminateSpawnedProcess, waitForServer, } from "./app-server.js";
+import { RpcClient, } from "./rpc-client.js";
+import { summarizeCodexRuntimeNotificationForTest } from "./runtime-summary.js";
+import { isTerminalCodexSessionStatus, parseStartupObservationMs, sleep, STARTUP_POLL_INTERVAL_MS, } from "./session-status.js";
+import { buildStartPrompt, DEFAULT_STOP_PHRASE, formatDeadline, makeToken } from "./start-prompt.js";
+import { inspectLocalCodexSession } from "./session-inspection.js";
+import { toSessionState } from "./session-mapper.js";
+import { forgetLaunchedAppServer, killOwnedAppServer, maybeStartCodexRuntimeBridge, postCodexRuntimeReasoningSummary, registerLaunchedAppServer, scheduleOwnedSessionMonitor, startCodexRuntimeBridge, } from "./session-supervisor.js";
+async function waitForWorkerStartup(session) {
+    const observationMs = parseStartupObservationMs();
+    const deadline = Date.now() + observationMs;
+    let latest = session;
+    while (Date.now() < deadline) {
+        await sleep(Math.min(STARTUP_POLL_INTERVAL_MS, Math.max(deadline - Date.now(), 0)));
+        const inspected = await inspectLocalCodexSession(session.session_id);
+        if (!inspected) {
+            continue;
+        }
+        latest = inspected.session;
+        if (!inspected.server_reachable || latest.status === "unknown") {
+            const reason = !inspected.server_reachable
+                ? "app-server became unreachable during startup"
+                : "worker status became unknown during startup";
+            const failed = updateCodexLiveSession(session.session_id, (current) => ({
+                ...current,
+                status: "failed",
+                last_error: reason,
+                updated_at: new Date().toISOString(),
+            })) ?? latest;
+            throw new Error(`Codex worker exited during startup: ${failed.last_error ?? reason}`);
+        }
+        if (isTerminalCodexSessionStatus(latest.status)) {
+            const reason = latest.status === "completed"
+                ? "turn completed before entering the room polling loop"
+                : `turn entered ${latest.status}`;
+            const failed = updateCodexLiveSession(session.session_id, (current) => ({
+                ...current,
+                status: "failed",
+                last_error: reason,
+                updated_at: new Date().toISOString(),
+            })) ?? latest;
+            throw new Error(`Codex worker exited during startup: ${failed.last_error ?? reason}`);
+        }
+    }
+    return latest;
+}
+export function canReuseCodexLiveSessionForStart(input) {
+    const { session } = input;
+    if (!session) {
+        return false;
+    }
+    return (session.room_id === input.roomId &&
+        resolve(session.cwd) === resolve(input.cwd) &&
+        (session.repo_branch ?? null) === input.repoBranch);
+}
+export async function startLocalCodexSession(input) {
+    const cwd = resolve(input.cwd || process.cwd());
+    const repoBranch = getGitCurrentBranch(cwd);
+    const currentSession = getCurrentCodexLiveSession(input.room_id);
+    if (currentSession &&
+        canReuseCodexLiveSessionForStart({
+            session: currentSession,
+            roomId: input.room_id,
+            cwd,
+            repoBranch,
+        })) {
+        const inspected = await inspectLocalCodexSession(currentSession.session_id);
+        if (inspected &&
+            (inspected.session.status === "running" || inspected.session.status === "starting")) {
+            scheduleOwnedSessionMonitor(inspected.session);
+            await maybeStartCodexRuntimeBridge(inspected.session);
+            return { session: inspected.session, reused: true };
+        }
+    }
+    const serverUrl = await resolveCodexServerUrl(input.server_url);
+    const stopPhrase = input.stop_phrase || DEFAULT_STOP_PHRASE;
+    const maxMinutes = Number.isFinite(input.max_minutes) ? Math.max(0, input.max_minutes ?? 0) : 0;
+    const codexBin = input.codex_bin || process.env.LETAGENTS_CODEX_BIN || "codex";
+    const token = makeToken();
+    const deadline = formatDeadline(maxMinutes);
+    const launchedServer = !(await isServerReady(serverUrl));
+    let serverPid = null;
+    let client = null;
+    let notificationSession = null;
+    let startupSucceeded = false;
+    try {
+        if (launchedServer) {
+            serverPid = launchAppServer(serverUrl, codexBin);
+            if (serverPid) {
+                registerLaunchedAppServer(serverPid);
+            }
+            const ready = await waitForServer(serverUrl);
+            if (!ready) {
+                throw new Error(`Timed out waiting for codex app-server at ${serverUrl}`);
+            }
+        }
+        client = new RpcClient(serverUrl, (notification) => {
+            const session = notificationSession
+                ? getStoredCodexLiveSession(notificationSession.session_id) ?? notificationSession
+                : null;
+            if (!session)
+                return;
+            void postCodexRuntimeReasoningSummary(session, summarizeCodexRuntimeNotificationForTest(notification)).catch(() => {
+                // Runtime notifications should never break the worker turn.
+            });
+        });
+        await client.connect();
+        const threadStart = await client.request("thread/start", {});
+        const threadId = threadStart.thread?.id;
+        if (!threadId) {
+            throw new Error("Codex app-server did not return a thread id.");
+        }
+        const prompt = buildStartPrompt({
+            room_identifier: input.room_identifier,
+            joined_via: input.joined_via,
+            cwd,
+            repo_branch: repoBranch,
+            stop_phrase: stopPhrase,
+            token,
+            deadline_utc: deadline.utc,
+            max_minutes: maxMinutes,
+        });
+        const turnStart = await client.request("turn/start", {
+            threadId,
+            cwd,
+            approvalPolicy: "never",
+            sandboxPolicy: { type: "dangerFullAccess" },
+            input: [{ type: "text", text: prompt, text_elements: [] }],
+        });
+        const turnId = turnStart.turn?.id;
+        if (!turnId) {
+            throw new Error("Codex app-server did not return a turn id.");
+        }
+        const session = saveCodexLiveSession(toSessionState({
+            session_id: randomUUID(),
+            room_id: input.room_id,
+            room_identifier: input.room_identifier,
+            room_code: input.room_code ?? null,
+            room_display_name: input.room_display_name ?? null,
+            joined_via: input.joined_via,
+            cwd,
+            repo_branch: repoBranch,
+            stop_phrase: stopPhrase,
+            max_minutes: maxMinutes,
+            deadline_utc: deadline.utc,
+            token,
+            thread_id: threadId,
+            turn_id: turnId,
+            server_url: serverUrl,
+            server_pid: serverPid,
+            launched_server: launchedServer,
+            codex_bin: codexBin,
+        }));
+        notificationSession = session;
+        try {
+            const verifiedSession = await waitForWorkerStartup(session);
+            scheduleOwnedSessionMonitor(verifiedSession);
+            startCodexRuntimeBridge(verifiedSession, client);
+            client = null;
+            startupSucceeded = true;
+            return { session: verifiedSession, reused: false };
+        }
+        catch (error) {
+            killOwnedAppServer(session);
+            throw error;
+        }
+    }
+    catch (error) {
+        if (!startupSucceeded && launchedServer && serverPid) {
+            terminateSpawnedProcess(serverPid);
+            forgetLaunchedAppServer(serverPid);
+        }
+        throw error;
+    }
+    finally {
+        client?.close();
+    }
+}

package/dist/mcp/codex-session/session-status.js

@@ -0,0 +1,77 @@
+const DEFAULT_STARTUP_OBSERVATION_MS = 8_000;
+export const STARTUP_POLL_INTERVAL_MS = 500;
+export function extractTurnStatus(turn) {
+    if (!turn) {
+        return null;
+    }
+    if (typeof turn.status === "string") {
+        return turn.status;
+    }
+    if (turn.status && typeof turn.status === "object" && "status" in turn.status) {
+        return typeof turn.status.status === "string" ? turn.status.status : null;
+    }
+    return null;
+}
+export function extractThreadStatus(thread) {
+    if (!thread?.status) {
+        return null;
+    }
+    if (typeof thread.status === "string") {
+        return thread.status;
+    }
+    return typeof thread.status.type === "string" ? thread.status.type : null;
+}
+export function summarizeItems(items) {
+    return (items ?? []).slice(-6).map((item) => {
+        if (item.type === "agentMessage") {
+            return { type: item.type, phase: item.phase, text: item.text ?? null };
+        }
+        if (item.type === "userMessage") {
+            return {
+                type: item.type,
+                text: (item.content ?? []).map((part) => part.text ?? "").join("\n"),
+            };
+        }
+        return { type: item.type ?? "unknown" };
+    });
+}
+export function deriveCodexLiveSessionStatus(session, serverReachable, threadStatus, turnStatus) {
+    if (threadStatus === "systemError" || threadStatus === "error" || turnStatus === "failed") {
+        return "failed";
+    }
+    if (turnStatus === "completed") {
+        return "completed";
+    }
+    if (turnStatus === "interrupted") {
+        return "interrupted";
+    }
+    if (turnStatus === "inProgress" || threadStatus === "active") {
+        return "running";
+    }
+    if (!serverReachable) {
+        return session.status === "completed" || session.status === "interrupted"
+            ? session.status
+            : "unknown";
+    }
+    if (session.status === "starting") {
+        return "starting";
+    }
+    return session.status;
+}
+export function isTerminalCodexSessionStatus(status) {
+    return status === "completed" || status === "interrupted" || status === "failed";
+}
+export function parseStartupObservationMs() {
+    const parsed = Number.parseInt(process.env.LETAGENTS_CODEX_STARTUP_OBSERVATION_MS ?? "", 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return DEFAULT_STARTUP_OBSERVATION_MS;
+    }
+    return parsed;
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function isLikelyMaterializingError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("not materialized yet");
+}

package/dist/mcp/codex-session/session-stop.js

@@ -0,0 +1,43 @@
+import { getCurrentCodexLiveSession, getStoredCodexLiveSession, updateCodexLiveSession, } from "../local-state.js";
+import { isServerReady } from "./app-server.js";
+import { RpcClient } from "./rpc-client.js";
+import { clearSessionMonitor, killOwnedAppServer, } from "./session-supervisor.js";
+export async function stopLocalCodexSession(options) {
+    const session = options?.session_id
+        ? getStoredCodexLiveSession(options.session_id)
+        : getCurrentCodexLiveSession(options?.room_id ?? undefined);
+    if (!session) {
+        return null;
+    }
+    // Attempt to interrupt the turn via RPC, but gracefully handle a dead server.
+    const serverReachable = await isServerReady(session.server_url);
+    if (serverReachable) {
+        try {
+            const client = new RpcClient(session.server_url);
+            await client.connect();
+            try {
+                await client.request("turn/interrupt", {
+                    threadId: session.thread_id,
+                    turnId: session.turn_id,
+                });
+            }
+            finally {
+                client.close();
+            }
+        }
+        catch {
+            // Server may have died between the readiness check and the RPC call.
+        }
+    }
+    const updated = updateCodexLiveSession(session.session_id, (current) => ({
+        ...current,
+        status: "interrupted",
+        last_error: serverReachable ? null : "server unreachable at stop time",
+        updated_at: new Date().toISOString(),
+    })) ?? session;
+    if (options?.shutdown_server || updated.launched_server) {
+        killOwnedAppServer(updated);
+    }
+    clearSessionMonitor(updated.session_id);
+    return updated;
+}