@cjhyy/code-shell-server 0.9.51 → 0.10.1

package/dist/mobile-remote/resident-agent.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { releaseStdioAfterExit, stopRoomProcess } from "./room-process-stop.js";
+import { releaseStdioAfterExit, stopRoomProcess, stopRoomProcessAndWait, waitForRoomProcessSpawn, } from "./room-process-stop.js";
 import { createInterface } from "node:readline";
 import { pathWithCommonBins } from "./path-bins.js";
 /**
@@ -119,12 +119,15 @@ export function parseStreamJsonLine(line) {
 export class ResidentAgentProcess {
     opts;
     child;
+    /** The most recently spawned process, kept after stop() so a caller can
+     * wait for it to actually exit before starting a replacement. */
+    lastChild;
+    spawned;
     constructor(opts) {
         this.opts = opts;
     }
-    start() {
-        if (this.child)
-            return;
+    /** Exact argv for one resident process. Pure → unit-testable. */
+    static argsFor(opts) {
         const args = [
             "--print",
             "--verbose",
@@ -135,13 +138,17 @@ export class ResidentAgentProcess {
             "--permission-prompt-tool",
             "stdio",
         ];
-        if (this.opts.appendSystemPrompt) {
-            args.push("--append-system-prompt", this.opts.appendSystemPrompt);
-        }
-        if (this.opts.resumeSessionId) {
-            args.push("--resume", this.opts.resumeSessionId);
-        }
-        args.push("--permission-mode", this.opts.permissionMode);
+        if (opts.appendSystemPrompt)
+            args.push("--append-system-prompt", opts.appendSystemPrompt);
+        if (opts.resumeSessionId)
+            args.push("--resume", opts.resumeSessionId);
+        args.push("--permission-mode", opts.permissionMode);
+        return args;
+    }
+    start() {
+        if (this.child)
+            return;
+        const args = ResidentAgentProcess.argsFor(this.opts);
         const child = spawn(this.opts.command, args, {
             cwd: this.opts.cwd,
             env: { ...process.env, PATH: pathWithCommonBins() },
@@ -149,6 +156,10 @@ export class ResidentAgentProcess {
             stdio: ["pipe", "pipe", "pipe"],
         });
         this.child = child;
+        this.lastChild = child;
+        this.spawned = waitForRoomProcessSpawn(child);
+        // Observed by whenStarted(); an unobserved failed spawn is reported via onEvent.
+        this.spawned.catch(() => undefined);
         // Settle on `close` so trailing output is read, without waiting on grandchildren.
         releaseStdioAfterExit(child);
         if (child.stdout) {
@@ -231,4 +242,20 @@ export class ResidentAgentProcess {
         if (child)
             stopRoomProcess(child);
     }
+    /** Resolves once the spawned process exists; rejects when the spawn failed. */
+    whenStarted() {
+        return this.spawned ?? Promise.resolve();
+    }
+    /**
+     * Stop, then resolve true only after the last spawned process has exited.
+     * A process already retired by a pipe error is still waited for: it may be
+     * alive for up to the SIGKILL grace period.
+     */
+    stopAndWait(timeoutMs) {
+        const child = this.child ?? this.lastChild;
+        this.child = undefined;
+        if (!child)
+            return Promise.resolve(true);
+        return stopRoomProcessAndWait(child, timeoutMs);
+    }
 }

package/dist/mobile-remote/room-history.d.ts

@@ -14,6 +14,13 @@ export interface RoomHistoryRequest {
 export declare function scanRoomHistory<T extends {
     seq: number;
 }>(file: string, parse: (value: unknown) => T | undefined, visit?: (message: T) => void): number;
+/** Same strict snapshot proof as scanRoomHistory, yielding between bounded reads. */
+export declare function scanRoomHistoryAsync<T extends {
+    seq: number;
+}>(file: string, parse: (value: unknown) => T | undefined, visit?: (message: T) => void): Promise<{
+    sequence: number;
+    stamp: string;
+}>;
 /** Durable immutable copies keep a frozen page boundary valid across Host restarts. */
 export declare function readRoomHistoryPage<T extends {
     seq: number;

package/dist/mobile-remote/room-history.js

@@ -1,12 +1,15 @@
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, writeFileSync, writeSync, } from "node:fs";
 import { join } from "node:path";
+import { lstat, open } from "node:fs/promises";
 const MAX_BYTES = 256 * 1024 * 1024;
 const MAX_LINE = 4 * 1024 * 1024;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const decoder = new TextDecoder("utf-8", { fatal: true });
 function regular(path) {
-    const stat = lstatSync(path);
+    return assertRegular(lstatSync(path));
+}
+function assertRegular(stat) {
     if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
         throw new Error("room history must be a private regular file");
     }
@@ -99,6 +102,58 @@ export function scanRoomHistory(file, parse, visit) {
         closeSync(fd);
     }
 }
+/** Same strict snapshot proof as scanRoomHistory, yielding between bounded reads. */
+export async function scanRoomHistoryAsync(file, parse, visit) {
+    const initial = assertRegular(await lstat(file));
+    const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const before = assertRegular(await handle.stat());
+        if (stamp(initial) !== stamp(before))
+            throw new Error("room history changed while opening");
+        if (before.size > MAX_BYTES)
+            throw new Error("room history exceeds 256 MiB; archive it before continuing");
+        let offset = 0, seq = 0, partialBytes = 0;
+        let parts = [];
+        while (offset < before.size) {
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, before.size - offset));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, offset);
+            if (!bytesRead)
+                throw new Error("room history was truncated while reading");
+            offset += bytesRead;
+            let from = 0;
+            while (from < bytesRead) {
+                const next = chunk.indexOf(0x0a, from);
+                const newline = next >= 0 && next < bytesRead ? next : -1;
+                const end = newline < 0 ? bytesRead : newline;
+                const piece = chunk.subarray(from, end);
+                partialBytes += piece.length;
+                if (partialBytes > MAX_LINE)
+                    throw new Error("room history record exceeds size limit");
+                parts.push(piece);
+                if (newline < 0)
+                    break;
+                const bytes = parts.length === 1 ? parts[0] : Buffer.concat(parts, partialBytes);
+                const message = parse(JSON.parse(decoder.decode(bytes)));
+                if (!message || message.seq !== seq + 1)
+                    throw new Error(`room history is corrupt at sequence ${seq + 1}`);
+                seq = message.seq;
+                visit?.(message);
+                parts = [];
+                partialBytes = 0;
+                from = newline + 1;
+            }
+        }
+        if (partialBytes)
+            throw new Error("room history has an incomplete final record");
+        if (stamp(before) !== stamp(await handle.stat()) ||
+            stamp(before) !== stamp(assertRegular(await lstat(file))))
+            throw new Error("room history changed while scanning");
+        return { sequence: seq, stamp: stamp(before) };
+    }
+    finally {
+        await handle.close();
+    }
+}
 function validateManifest(value, roomId, snapshotId) {
     if (!value ||
         value.version !== 1 ||

package/dist/mobile-remote/room-manager.d.ts

@@ -57,6 +57,54 @@ export interface RoomMeta {
     linkedSessionMode?: "observe-only";
 }
 export type RoomOpenStatus = "running" | "missing" | "observing";
+/** Why a room cannot change its spawn-time permission mode right now. */
+export type RoomBusyReason = "switching" | "retiring" | "turn" | "approval" | "queued";
+export declare class RoomBusyError extends Error {
+    readonly reason: RoomBusyReason;
+    constructor(reason: RoomBusyReason);
+}
+/** Stable code of RoomInputAcceptedError; callers branch on it, never on text. */
+export declare const ROOM_INPUT_ACCEPTED = "ROOM_INPUT_ACCEPTED";
+/**
+ * The CLI accepted the input, but recording it (history, trace, echo) failed.
+ * The turn may be running: it must never be retried as if it were rejected.
+ */
+export declare class RoomInputAcceptedError extends Error {
+    readonly code = "ROOM_INPUT_ACCEPTED";
+    constructor(cause: unknown);
+}
+/** The room or its process changed between planning and applying a mode change. */
+export declare class RoomStateChangedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Read-only plan for opening an external CLI session under a mode. A Host may
+ * ask for authorization between plan and apply; apply re-validates every field.
+ */
+export interface RoomSessionOpenPlan {
+    /** Existing room id, or an id reserved for the room apply() will create. */
+    roomId: string;
+    created: boolean;
+    sessionId: string;
+    /** Canonical directory the CLI process will run in. */
+    cwd: string;
+    kind: RoomKind;
+    /** Live process mode, else persisted mode; undefined for a new room. */
+    fromMode?: RoomPermissionMode;
+    toMode: RoomPermissionMode;
+    /** False when metadata and any live process already run in toMode. */
+    change: boolean;
+    /** True when a process is live now (an unchanged open will reuse it). */
+    live: boolean;
+    observing: boolean;
+    revision: number;
+}
+export interface RoomSessionOpenResult {
+    roomId: string;
+    status: RoomOpenStatus;
+    mode: RoomPermissionMode;
+    changed: boolean;
+}
 export interface RoomMessage {
     seq: number;
     ts: number;
@@ -84,6 +132,15 @@ export interface RoomMessage {
         size: number;
         path: string;
     }>;
+    /** Exact mobile intent receipt, durable alongside its accepted user turn. */
+    clientMessageId?: string;
+    clientDeviceId?: string;
+    clientIntentHash?: string;
+}
+export interface RoomInputReceipt {
+    clientMessageId: string;
+    clientDeviceId: string;
+    clientIntentHash: string;
 }
 export declare function roomTurnText(text: string, attachments: InputAttachmentMeta[]): string;
 export declare function stripRoomAttachmentBlock(text: string): string;
@@ -96,6 +153,15 @@ export interface RoomAgent {
     send(text: string): boolean;
     isRunning(): boolean;
     stop(): void;
+    /** Stop, then resolve true only after the process has really exited. A
+     * replacement for the same external session must not start before that. */
+    stopAndWait?(timeoutMs: number): Promise<boolean>;
+    /** True while a turn process is alive. Codex spawns one child per turn and
+     * that child can outlive the parsed turn_end. Agents without this hook are
+     * tracked by accepted-input / turn_end accounting. */
+    isBusy?(): boolean;
+    /** Resolves once the spawned process exists; rejects for a failed spawn. */
+    whenStarted?(): Promise<void>;
     respondControl?(requestId: string, decision: {
         behavior: "allow";
         updatedInput?: unknown;
@@ -123,6 +189,19 @@ export interface RoomManagerOptions {
      * external session. Checked before any resident agent can start on it, so
      * desktop and phone entry points share one ownership gate. */
     assertExternalSessionAvailable?: (externalSessionId: string, kind: RoomKind) => void;
+    /** Host start policy, checked before ANY resident agent is created (open,
+     * send's implicit open, session open, takeover). Throwing refuses the start.
+     * Persisted metadata alone is never an authorization: the Host decides. */
+    authorizeStart?: (room: Readonly<RoomMeta>) => void;
+    /** Bound on waiting for a retired process during a mode handoff. */
+    processExitTimeoutMs?: number;
+    /** Called after an explicit close() (not after a process exit). */
+    onRoomClosed?: (roomId: string) => void;
+    /** Called when a room's process state changed without a caller to report
+     * it: a failed mode handoff after the old process exited, a failed first
+     * start, or a retired process finally proven gone. Hosts republish the
+     * room's authoritative state to every view. */
+    onRoomStateChanged?: (roomId: string) => void;
     /** Called whenever a room gains a new persisted message (push to phone). */
     onMessage: (roomId: string, msg: RoomMessage) => void;
     /** Called when a room's resident agent requests tool-use approval. For
@@ -156,6 +235,21 @@ export declare class RoomManager {
     /** Permission mode each live agent was spawned with. The mode is a spawn-time
      * CLI argument, so room metadata alone cannot prove what a process runs. */
     private agentModes;
+    /** Accepted inputs minus turn_end per room, for agents without isBusy(). A
+     * Claude resident process queues several inputs; each ends with a result. */
+    private turnCounts;
+    /** In-flight mode handoff per room. close() deletes it, so a handoff that is
+     * waiting for the old process can never reopen a room the user closed. */
+    private transitions;
+    /** Detached processes not yet proven exited. This is a process-safety fence,
+     * independent of any operation: close() and cancellation leave it in place,
+     * and no agent may start for the room until the process has really exited,
+     * so one external session never has two writers. */
+    private retiring;
+    private retiringProbes;
+    /** Bumped on every change to a room's process or mode, so a Host approval
+     * granted for one state cannot be applied to another. */
+    private revisions;
     private modelTraces;
     /** Rooms whose visible output is currently sourced from the external CLI's
      * transcript tail. While present, the resident agent's stdout mirror is
@@ -198,6 +292,9 @@ export declare class RoomManager {
     private readonly rootRealPath;
     private readonly rootIdentity;
     private readonly failedWrites;
+    private readonly preparingInputReceipts;
+    private readonly inputReceipts;
+    private hostTurnHooks;
     /** Drop all pending AskUser entries for a room. Called when its agent goes
      *  away (exit/close) so a request that can no longer be answered doesn't leak
      *  in the map (small memory leak) and its approval card doesn't hang until the
@@ -219,6 +316,8 @@ export declare class RoomManager {
         claudeSessionId?: string;
         linkedSessionMode?: "observe-only";
     }): RoomMeta;
+    private mintRoomId;
+    private createRoomWithId;
     listRooms(): RoomMeta[];
     getRoom(id: string): RoomMeta | undefined;
     private nextSeq;
@@ -250,14 +349,114 @@ export declare class RoomManager {
     /** Persist normalized transcript-tail messages through the same seq/history/
      * broadcast path as resident-agent output. */
     ingestTranscriptMessages(id: string, messages: Omit<RoomMessage, "seq" | "ts">[]): void;
+    /** Monotonic per-room state revision; see `revisions`. */
+    roomRevision(id: string): number;
+    private bumpRevision;
+    /** The room bound to an external session. Reuse must match BOTH id and kind:
+     * a codex thread id and a claude session id share the `claudeSessionId`
+     * field, so a bare id match could hand back the other CLI's room. */
+    findSessionRoom(sessionId: string, kind: RoomKind): RoomMeta | undefined;
+    /** Spawn-time mode of the room's live process, if one is running. */
+    liveMode(id: string): RoomPermissionMode | undefined;
+    /**
+     * Why the room cannot change its process now. A mode change stops the
+     * process, so it must not interrupt queued/active turns, a pending tool
+     * approval or AskUserQuestion, or a decision that already left the approval
+     * bridge but has not been consumed here yet (its entry stays in the pending
+     * maps until respondApproval consumes it).
+     */
+    roomBusyReason(id: string): RoomBusyReason | undefined;
+    /**
+     * The room's own execution state, independent of any Host-held pending
+     * turns: an active or queued CLI input (Codex: a live turn child), a mode
+     * handoff, or an unanswered approval. A Host scheduler waits on this.
+     */
+    private executionBusyReason;
+    /**
+     * True while a new input must not be handed to the room: it is executing
+     * or awaiting an approval, switching modes, or a retired process may still
+     * write. Host pending turns are deliberately not counted here.
+     */
+    isExecutionBusy(id: string): boolean;
+    /** Mode a new input would run under: the live process mode, else the stored one. */
+    effectiveMode(id: string): RoomPermissionMode | undefined;
     /**
-     * Open (or create) the room bound to a claude session id, deduping by that id
-     * so a given claude session maps to exactly one room. Returns the room id.
+     * Host pending-turn integration, installed once by the Host composition.
+     * `hasPendingTurns` blocks every mode change; `beforeClose` runs before an
+     * explicit close signals the process, so pending turns pause first.
      */
-    openForSession(claudeSessionId: string, cwd: string, mode: RoomPermissionMode, kind?: RoomKind): {
+    setHostTurnHooks(hooks: {
+        hasPendingTurns?: (roomId: string) => boolean;
+        beforeClose?: (roomId: string) => void;
+    }): void;
+    /**
+     * Plan opening an external session's room under `mode` without changing
+     * anything. Throws for a cwd that differs from the room's bound directory,
+     * an occupied external session, or a busy room whose mode would change.
+     */
+    planSessionOpen(input: {
+        sessionId: string;
+        cwd: string;
+        kind: RoomKind;
+        mode: RoomPermissionMode;
+    }): RoomSessionOpenPlan;
+    /**
+     * Apply a plan from planSessionOpen. `authorize` runs before anything is
+     * changed and again right before the replacement process is created; a
+     * throw leaves metadata untouched (or restores it) and never starts a CLI.
+     * `revalidate` re-checks asynchronous Host facts after every wait for a
+     * retired process, before that final `authorize`, while the room's handoff
+     * is still owned by this call.
+     */
+    applySessionOpen(plan: RoomSessionOpenPlan, options?: {
+        authorize?: () => void;
+        revalidate?: () => Promise<void>;
+    }): Promise<RoomSessionOpenResult>;
+    /**
+     * Open (or create) the room bound to an external session id, deduping by
+     * that id so a given session maps to exactly one room. A different mode is
+     * applied by a guarded process handoff. Hosts that must authorize a mode
+     * use planSessionOpen/applySessionOpen directly.
+     */
+    openForSession(claudeSessionId: string, cwd: string, mode: RoomPermissionMode, kind?: RoomKind): Promise<{
         roomId: string;
         status: RoomOpenStatus;
-    };
+        mode: RoomPermissionMode;
+    }>;
+    /**
+     * Re-probe a retired process of the session's room (see `retiring`), so a
+     * plan made right afterwards is refused only while that process is really
+     * still alive. Never starts anything.
+     */
+    settleSessionRoom(sessionId: string, kind: RoomKind): Promise<void>;
+    /** Resolves true once no retired process of the room can still be alive. */
+    private settleRetiring;
+    private probeRetired;
+    /** Synchronous entry points cannot wait: refuse, and re-probe in the
+     * background so the next attempt succeeds once the process is gone. */
+    private assertNotRetiring;
+    /** Request an exit probe; the shared probe publishes a proven exit once.
+     * A handoff that still owns the room reports its own outcome. */
+    private watchRetired;
+    private notifyRoomState;
+    /**
+     * Replace a room's process with one in `toMode`. permissionMode is a
+     * spawn-time CLI argument (`--permission-mode` / codex sandbox flags), so a
+     * live process cannot change it. Order matters:
+     *  1. refuse a busy room, before touching anything;
+     *  2. detach the old process, so its late output/exit belongs to nobody, and
+     *     wait (bounded) until it has really exited — never two writers;
+     *  3. re-authorize, then persist the mode and start the replacement;
+     *  4. on any failure restore the previous mode. The old process is already
+     *     gone at that point, so the room reports not running instead of
+     *     pretending the old state came back, and every view is told so.
+     * The detached process stays in `retiring` until its exit is proven: a
+     * timeout, close() or cancellation ends this operation but not the fence.
+     * Transcript followers are not ended: the external session continues.
+     */
+    private transitionRoom;
+    /** Start (or reuse) the room's agent and wait until a spawned process exists. */
+    private startAgent;
     /** Bind an external CLI transcript to a room for observation only.
      *
      * This method never creates or starts a resident agent. The host must first
@@ -275,12 +474,12 @@ export declare class RoomManager {
      * This is the linked-session operation that may create/start an agent. The
      * external identity is revalidated at takeover time so stale links cannot
      * silently start a different session. */
-    takeOverLinkedSession(roomId: string, externalSessionId: string, cwd: string, kind: RoomKind): {
+    takeOverLinkedSession(roomId: string, externalSessionId: string, cwd: string, kind: RoomKind): Promise<{
         roomId: string;
         status: "running";
         mode: RoomPermissionMode;
         cwd: string;
-    };
+    }>;
     private requireLinkedSessionTarget;
     /**
      * Forward a phone-side approval decision to the room's resident agent.
@@ -301,13 +500,21 @@ export declare class RoomManager {
     open(id: string): {
         status: RoomOpenStatus;
     };
-    /** Stop a live agent whose spawn-time permission mode differs from `mode`. */
-    private retireAgentUnlessMode;
+    private openAgent;
     private onAgentEvent;
+    /** Prepare cold receipts outside the synchronous send path; concurrent intents share one scan. */
+    prepareInputReceipts(id: string): Promise<void>;
+    private buildInputReceipts;
+    private currentInputReceipts;
+    /** A replay never opens a new CLI, reclaims an attachment, or reuses a changed intent. */
+    hasAcceptedInput(id: string, receipt: RoomInputReceipt): boolean;
     /** Post a user message: persist it, ensure agent running, feed it. */
-    send(id: string, text: string, attachments?: InputAttachmentMeta[]): boolean;
+    send(id: string, text: string, attachments?: InputAttachmentMeta[], receipt?: RoomInputReceipt): boolean;
+    private recordAcceptedInput;
     close(id: string): void;
     closeAll(): void;
+    /** True while the room's process runs, or a retired one is not yet proven
+     * gone (a view must not be told the room stopped while it may still write). */
     isOpen(id: string): boolean;
     /**
      * Delete rooms whose last activity is older than maxAgeMs (idle-based GC,