@cjhyy/code-shell-server 0.9.51 → 0.10.1

package/dist/mobile-remote/room-process-stop.d.ts

@@ -1,6 +1,21 @@
 import type { ChildProcess } from "node:child_process";
 /** Retire an unusable room transport without leaving an unresponsive CLI alive. */
 export declare function stopRoomProcess(child: ChildProcess): void;
+/**
+ * Resolve true once `child` has exited (or never started a process), false
+ * when it is still alive after `timeoutMs`. A replacement CLI for the same
+ * external session may only start after this resolves true; otherwise two
+ * processes could append to one transcript.
+ */
+export declare function waitForRoomProcessExit(child: ChildProcess, timeoutMs: number): Promise<boolean>;
+/** Signal the process group, then wait (bounded) for the child to exit. */
+export declare function stopRoomProcessAndWait(child: ChildProcess, timeoutMs: number): Promise<boolean>;
+/**
+ * Resolve once a just-spawned child exists. Node assigns `pid` synchronously
+ * for a successful spawn; a failed spawn (missing command/cwd) has no pid and
+ * reports the failure through `error` on a later tick.
+ */
+export declare function waitForRoomProcessSpawn(child: ChildProcess): Promise<void>;
 /**
  * `close` waits for every holder of the child's stdout/stderr. A grandchild the
  * CLI backgrounded with inherited stdio (a dev server, say) keeps them open

package/dist/mobile-remote/room-process-stop.js

@@ -26,6 +26,47 @@ export function stopRoomProcess(child) {
     timer.unref();
     child.once("exit", () => clearTimeout(timer));
 }
+/**
+ * Resolve true once `child` has exited (or never started a process), false
+ * when it is still alive after `timeoutMs`. A replacement CLI for the same
+ * external session may only start after this resolves true; otherwise two
+ * processes could append to one transcript.
+ */
+export function waitForRoomProcessExit(child, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null || child.pid === undefined)
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        const onExit = () => {
+            clearTimeout(timer);
+            resolve(true);
+        };
+        const timer = setTimeout(() => {
+            child.off("exit", onExit);
+            resolve(false);
+        }, timeoutMs);
+        timer.unref?.();
+        child.once("exit", onExit);
+    });
+}
+/** Signal the process group, then wait (bounded) for the child to exit. */
+export function stopRoomProcessAndWait(child, timeoutMs) {
+    const exited = waitForRoomProcessExit(child, timeoutMs);
+    stopRoomProcess(child);
+    return exited;
+}
+/**
+ * Resolve once a just-spawned child exists. Node assigns `pid` synchronously
+ * for a successful spawn; a failed spawn (missing command/cwd) has no pid and
+ * reports the failure through `error` on a later tick.
+ */
+export function waitForRoomProcessSpawn(child) {
+    if (child.pid !== undefined)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        child.once("spawn", () => resolve());
+        child.once("error", (error) => reject(error));
+    });
+}
 /**
  * `close` waits for every holder of the child's stdout/stderr. A grandchild the
  * CLI backgrounded with inherited stdio (a dev server, say) keeps them open

package/dist/mobile-remote/trusted-device-store.d.ts

@@ -1,7 +1,19 @@
 import type { TrustedDevicePublic } from "./types.js";
 export declare class TrustedDeviceStore {
     private readonly filePath;
+    /** Account handoffs never create durable pairing credentials, even after a crash. */
+    private readonly ephemeral;
     constructor(filePath: string);
+    addEphemeralDevice(input: {
+        name: string;
+        secretHash: string;
+        expiresAt: number;
+    }): TrustedDevicePublic;
+    private pruneEphemeral;
+    /** Account identities require their matching entrance grant on every transport. */
+    isEphemeralDevice(id: string): boolean;
+    /** Retiring an account grant must never acquire or mutate the durable pairing store. */
+    removeEphemeralDevice(id: string): boolean;
     addDevice(input: {
         name: string;
         secretHash: string;

package/dist/mobile-remote/trusted-device-store.js

@@ -24,9 +24,46 @@ function secretHashEquals(a, b) {
 }
 export class TrustedDeviceStore {
     filePath;
+    /** Account handoffs never create durable pairing credentials, even after a crash. */
+    ephemeral = new Map();
     constructor(filePath) {
         this.filePath = filePath;
     }
+    addEphemeralDevice(input) {
+        const name = normalizeDeviceName(input.name);
+        if (!name ||
+            !isBoundedOpaqueString(input.secretHash, MAX_DEVICE_SECRET_LENGTH) ||
+            !isTimestamp(input.expiresAt) ||
+            input.expiresAt <= Date.now() ||
+            input.expiresAt > Date.now() + 10 * 60_000)
+            throw new Error("Invalid short-lived device grant");
+        this.pruneEphemeral();
+        if (this.ephemeral.size >= 128)
+            throw new Error("Short-lived device limit reached");
+        const device = {
+            id: randomUUID(),
+            name,
+            secretHash: input.secretHash,
+            createdAt: Date.now(),
+        };
+        this.ephemeral.set(device.id, { device, expiresAt: input.expiresAt });
+        return this.toPublic(device);
+    }
+    pruneEphemeral() {
+        const now = Date.now();
+        for (const [id, grant] of this.ephemeral)
+            if (grant.expiresAt <= now)
+                this.ephemeral.delete(id);
+    }
+    /** Account identities require their matching entrance grant on every transport. */
+    isEphemeralDevice(id) {
+        this.pruneEphemeral();
+        return this.ephemeral.has(id);
+    }
+    /** Retiring an account grant must never acquire or mutate the durable pairing store. */
+    removeEphemeralDevice(id) {
+        return this.ephemeral.delete(id);
+    }
     addDevice(input) {
         const name = normalizeDeviceName(input.name);
         if (!name)
@@ -34,6 +71,9 @@ export class TrustedDeviceStore {
         if (!isBoundedOpaqueString(input.secretHash, MAX_DEVICE_SECRET_LENGTH)) {
             throw new Error("Invalid trusted device secret");
         }
+        this.pruneEphemeral();
+        if ([...this.ephemeral.values()].some(({ device }) => secretHashEquals(device.secretHash, input.secretHash)))
+            throw new Error("Account device credentials cannot be paired permanently");
         return this.mutate((devices) => {
             // Get-or-create by secretHash. A phone's secret is stable per browser
             // (persisted in localStorage as cs.deviceSecret), so re-scanning the QR
@@ -61,13 +101,22 @@ export class TrustedDeviceStore {
         });
     }
     listDevices() {
-        return this.readAll().map((device) => this.toPublic(device));
+        this.pruneEphemeral();
+        return [...this.readAll(), ...[...this.ephemeral.values()].map((grant) => grant.device)].map((device) => this.toPublic(device));
     }
     authenticate(id, secretHash) {
         if (!isBoundedOpaqueString(id, MAX_DEVICE_ID_LENGTH) ||
             !isBoundedOpaqueString(secretHash, MAX_DEVICE_SECRET_LENGTH)) {
             return undefined;
         }
+        this.pruneEphemeral();
+        const temporary = this.ephemeral.get(id)?.device;
+        if (temporary) {
+            if (temporary.revokedAt || !secretHashEquals(temporary.secretHash, secretHash))
+                return;
+            temporary.lastSeenAt = Date.now();
+            return this.toPublic(temporary);
+        }
         return this.mutate((devices) => {
             const device = devices.find((item) => item.id === id && !item.revokedAt && secretHashEquals(item.secretHash, secretHash));
             if (!device)
@@ -79,6 +128,8 @@ export class TrustedDeviceStore {
     revoke(id) {
         if (!isBoundedOpaqueString(id, MAX_DEVICE_ID_LENGTH))
             return false;
+        if (this.ephemeral.has(id))
+            return this.ephemeral.delete(id);
         return this.mutate((devices) => {
             const device = devices.find((item) => item.id === id && !item.revokedAt);
             if (!device)
@@ -91,6 +142,8 @@ export class TrustedDeviceStore {
     remove(id) {
         if (!isBoundedOpaqueString(id, MAX_DEVICE_ID_LENGTH))
             return false;
+        if (this.ephemeral.has(id))
+            return this.ephemeral.delete(id);
         return this.mutate((devices) => {
             const index = devices.findIndex((item) => item.id === id);
             if (index < 0)

package/dist/mobile-remote/turn-queue.d.ts

@@ -0,0 +1,183 @@
+import type { MobileAttachmentSummary, MobileTurnQueueEntryStatus, MobileTurnQueueState, MobileTurnQueueTarget, PermissionMode } from "./types.js";
+/**
+ * Host-owned FIFO of turns submitted while their conversation is busy.
+ *
+ * The queue never runs anything itself: an entry is handed to the caller's
+ * ORIGINAL submit path (same validation, approvals and workspace checks) only
+ * when the exact target is idle, so it cannot bypass or duplicate an existing
+ * Core/CLI queue. Entries are bound to the conversation they were submitted
+ * for, never to a viewer's later selection.
+ */
+export declare const MAX_TURN_QUEUE_ENTRIES_PER_TARGET = 20;
+export declare const MAX_TURN_QUEUE_ENTRIES_PER_DEVICE = 50;
+export declare const MAX_TURN_QUEUE_ENTRIES = 200;
+export type TurnQueueDispatchResult = {
+    ok: true;
+}
+/**
+ * requeue: a Stop of the target fenced the turn off before anything was
+ * submitted; it returns to the (stopped) queue unchanged, never failed.
+ */
+ | {
+    ok: false;
+    message: string;
+    uncertain?: boolean;
+    requeue?: boolean;
+};
+export type TurnQueueActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export type TurnQueueGate = {
+    ok: true;
+    viewerId?: string;
+} | {
+    ok: false;
+    message: string;
+};
+export interface TurnQueueSubmission<P> {
+    target: MobileTurnQueueTarget;
+    clientMessageId: string;
+    deviceId: string;
+    viewerId?: string;
+    text: string;
+    attachments: MobileAttachmentSummary[];
+    uploadIds: string[];
+    permissionMode?: PermissionMode;
+    modelKey?: string;
+    nativeConnectionId?: string;
+    /** The original validated client event, replayed through its own submit path. */
+    payload: P;
+    /**
+     * Input identity (text + attachment descriptors). A replay of the same intent
+     * id with different content is refused rather than mistaken for the same turn.
+     */
+    fingerprint?: string;
+    /**
+     * The submitter still awaits a direct acknowledgement (an immediate run on
+     * an idle target). Hidden from snapshots and dropped on rejection, so the
+     * original submit path's error keeps its legacy meaning. Cleared by reveal().
+     */
+    transient?: boolean;
+}
+export interface TurnQueueEntry<P> extends TurnQueueSubmission<P> {
+    id: string;
+    createdAt: number;
+    status: MobileTurnQueueEntryStatus;
+    message?: string;
+}
+export interface MobileTurnQueueDeps<P> {
+    /** True while the exact target has an active turn (including its approvals). */
+    isBusy(target: MobileTurnQueueTarget): boolean;
+    /** Re-check the submitting device's authority immediately before running. */
+    canDispatch(entry: Readonly<TurnQueueEntry<P>>): TurnQueueGate;
+    dispatch(entry: Readonly<TurnQueueEntry<P>>): Promise<TurnQueueDispatchResult>;
+    /** Called after every visible change of one target's queue. */
+    publish(target: MobileTurnQueueTarget): void;
+    /** Release resources (uploads) of an entry that will never run. */
+    discard?(entry: Readonly<TurnQueueEntry<P>>): void;
+    now?: () => number;
+    /** Poll interval for idle detection; 0 disables the internal timer (tests). */
+    intervalMs?: number;
+    /** Minimum gap after an accepted dispatch before the next head may run. */
+    settleMs?: number;
+}
+/** A replay's existing outcome, decided before any resource is retained for it. */
+export type TurnQueueLookup<P> = {
+    kind: "duplicate";
+    entry: TurnQueueEntry<P>;
+    position: number;
+} | {
+    kind: "settled";
+    outcome: "dispatched" | "cancelled";
+} | {
+    kind: "conflict";
+    message: string;
+};
+export type TurnQueueEnqueueResult<P> = {
+    kind: "queued";
+    entry: TurnQueueEntry<P>;
+    position: number;
+} | {
+    kind: "duplicate";
+    entry: TurnQueueEntry<P>;
+    position: number;
+} | {
+    kind: "settled";
+    outcome: "dispatched" | "cancelled";
+} | {
+    kind: "rejected";
+    message: string;
+};
+export declare function turnQueueTargetKey(target: MobileTurnQueueTarget): string;
+export declare function sameTurnQueueTarget(left: MobileTurnQueueTarget | undefined, right: MobileTurnQueueTarget | undefined): boolean;
+export declare class MobileTurnQueue<P> {
+    private readonly deps;
+    readonly epoch: `${string}-${string}-${string}-${string}-${string}`;
+    private readonly queues;
+    private readonly settled;
+    private readonly pumping;
+    private readonly stopGenerations;
+    private readonly now;
+    private timer?;
+    private disposed;
+    /** Monotonic across targets so a recreated queue never reuses a revision. */
+    private revision;
+    constructor(deps: MobileTurnQueueDeps<P>);
+    /**
+     * The live or settled outcome of one device's intent on one target. Callers
+     * check this BEFORE retaining resources: a replay of an admitted turn must be
+     * answered from its receipt, not re-validated against consumed uploads.
+     */
+    lookup(target: MobileTurnQueueTarget, deviceId: string, clientMessageId: string, fingerprint?: string): TurnQueueLookup<P> | undefined;
+    /** Admit one submission, or return its existing/settled outcome for a replay. */
+    enqueue(submission: TurnQueueSubmission<P>): TurnQueueEnqueueResult<P>;
+    /** Remove one entry that has not been handed to its submit path. */
+    cancel(target: MobileTurnQueueTarget, entryId: string): TurnQueueActionResult;
+    /** Remove every entry that is not already being submitted. */
+    clear(target: MobileTurnQueueTarget): number;
+    /**
+     * Stop scheduling after the current turn; nothing is discarded. An explicit
+     * Stop outranks a failure/uncertain pause: removing or retrying the entry
+     * that caused that pause must not restart the rest. Every Stop advances the
+     * target's stop generation, which fences an in-flight dispatch off before it
+     * physically submits (see stopGeneration).
+     */
+    pause(target: MobileTurnQueueTarget, reason: "stopped"): void;
+    /** Monotonic count of Stops of this target during this Host lifetime. */
+    stopGeneration(target: MobileTurnQueueTarget): number;
+    /**
+     * Continue after Stop or a rejected entry. An entry whose execution cannot
+     * be ruled out must be removed first; it is never resubmitted from here.
+     */
+    resume(target: MobileTurnQueueTarget): TurnQueueActionResult;
+    /** Retry a rejected entry with the same clientMessageId. */
+    retry(target: MobileTurnQueueTarget, entryId: string): TurnQueueActionResult;
+    private releaseFailurePause;
+    /** Publish an entry whose submitter was told it is queued rather than running. */
+    reveal(target: MobileTurnQueueTarget, entryId: string): void;
+    has(target: MobileTurnQueueTarget): boolean;
+    entries(target: MobileTurnQueueTarget): readonly Readonly<TurnQueueEntry<P>>[];
+    targets(): MobileTurnQueueTarget[];
+    /** Public state as seen by one recipient device. */
+    snapshot(target: MobileTurnQueueTarget, recipientDeviceId?: string): MobileTurnQueueState;
+    /** Re-evaluate every queue; used by the idle timer and Host lifecycle signals. */
+    pumpAll(): Promise<void>;
+    /**
+     * Hand the next runnable entry to its submit path when the exact target is
+     * idle. At most one entry per target is in flight. Entries of one device
+     * keep their order; a device that cannot run now (e.g. its tab is away)
+     * does not hold back other devices' turns. A rejected or uncertain entry
+     * pauses the whole target so nothing runs past an unresolved outcome.
+     */
+    pump(target: MobileTurnQueueTarget): Promise<void>;
+    dispose(): void;
+    private identity;
+    private retire;
+    private remember;
+    private changed;
+    private ensureTimer;
+    private stopTimerIfIdle;
+}