@cjhyy/code-shell-server 0.8.0

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

@@ -0,0 +1,286 @@
+import type { ResidentAgentEvent } from "./resident-agent.js";
+import type { InputAttachmentMeta } from "../attachment-service.js";
+export declare function isValidRoomId(id: unknown): id is string;
+export type RoomPermissionMode = "default" | "acceptEdits" | "bypassPermissions";
+/**
+ * Build the `updatedInput` that answers an AskUserQuestion `can_use_tool`
+ * request. Empirically (claude CLI, verified against the live control protocol
+ * + the Agent SDK docs), the answer must go in an `answers` RECORD keyed by each
+ * question's `question` text, with STRING values (arrays/objects fail schema
+ * validation). For multiSelect the caller joins chosen labels with ", ". The
+ * original `questions` array is passed through (claude validates against it).
+ * `answersByQuestion` maps question text → answer string.
+ */
+export declare function buildAskUserUpdatedInput(input: unknown, answersByQuestion: Record<string, string>): Record<string, unknown>;
+/**
+ * Parse an AskUserQuestion input into the first question's prompt/header/options
+ * so the UI can render a choice card. The room UI answers one question at a time
+ * (the first); returns undefined for a non-AskUser / malformed input (no
+ * questions), which the caller treats as "fall back to auto-allow".
+ */
+export declare function askUserPrompt(input: unknown): {
+    question: string;
+    header?: string;
+    options: string[];
+    multiSelect: boolean;
+} | undefined;
+/** Which external CLI backs the room. "claude-code" drives `claude` (long-lived
+ *  stdin process with per-tool approval); "codex" drives `codex exec` (one
+ *  process per turn, resumed by thread id, no per-tool approval — the sandbox
+ *  tier chosen at open is the only guardrail). */
+export type RoomKind = "claude-code" | "codex";
+/** Exact external-session identity proved by the host's transcript locator.
+ * RoomManager deliberately does not know CLI-specific transcript paths; the
+ * host resolves those paths and returns the identity read from disk. */
+export interface LinkedSessionTarget {
+    externalSessionId: string;
+    cwd: string;
+    kind: RoomKind;
+}
+export interface RoomMeta {
+    id: string;
+    name: string;
+    cwd: string;
+    kind: RoomKind;
+    permissionMode: RoomPermissionMode;
+    createdAt: number;
+    lastActiveAt: number;
+    /** Session/thread id to resume: claude's session_id OR codex's thread_id.
+     *  (Named claudeSessionId for back-compat with persisted room.json files.) */
+    claudeSessionId?: string;
+    /** Persisted capability boundary for a room bound from an external CLI
+     * transcript. While set, ordinary open/send calls cannot start an agent;
+     * only takeOverLinkedSession may clear it after revalidating the tuple. */
+    linkedSessionMode?: "observe-only";
+}
+export type RoomOpenStatus = "running" | "missing" | "observing";
+export interface RoomMessage {
+    seq: number;
+    ts: number;
+    from: "user" | "agent" | "system";
+    type: string;
+    text?: string;
+    tool?: string;
+    summary?: string;
+    reason?: string;
+    isError?: boolean;
+    /** claude's tool_use block id — present on `tool` (the start) and
+     *  `tool_result` (the matching result) so the UI can pair them by id rather
+     *  than guessing "the last open tool". Absent on legacy messages. */
+    toolId?: string;
+    /** Full structured tool_use input (e.g. a sub-agent's `prompt`) on `tool`
+     *  messages. `summary` is a lossy one-field preview; `args` is what the tool
+     *  card expands to so the real parameters are visible. Absent on legacy
+     *  messages that predate args persistence. */
+    args?: Record<string, unknown>;
+    attachments?: Array<{
+        name: string;
+        mime?: string;
+        size: number;
+        path: string;
+    }>;
+}
+export declare function roomTurnText(text: string, attachments: InputAttachmentMeta[]): string;
+export declare function stripRoomAttachmentBlock(text: string): string;
+/**
+ * Minimal interface a resident agent must satisfy, so RoomManager can be unit
+ * tested with a fake (no real claude process).
+ */
+export interface RoomAgent {
+    start(): void;
+    send(text: string): boolean;
+    isRunning(): boolean;
+    stop(): void;
+    respondControl?(requestId: string, decision: {
+        behavior: "allow";
+        updatedInput?: unknown;
+    } | {
+        behavior: "deny";
+        message: string;
+    }): void;
+}
+export interface RoomAgentFactory {
+    (room: RoomMeta, onEvent: (event: ResidentAgentEvent) => void): RoomAgent;
+}
+export interface RoomManagerOptions {
+    rootDir: string;
+    createAgent: RoomAgentFactory;
+    /** Locate an already-running external CLI transcript without starting a CLI.
+     * Returning null means the transcript is absent. The returned identity is
+     * checked again here so a stale or mismatched locator fails closed. */
+    resolveLinkedSession?: (target: Readonly<LinkedSessionTarget>) => LinkedSessionTarget | null | undefined;
+    /** 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
+     *  AskUserQuestion, `askUser` carries the parsed prompt + options so the UI
+     *  renders a choice card; the user's pick is routed back via respondApproval's
+     *  `answer` field and baked into updatedInput.answers here in main. */
+    onApprovalRequest?: (roomId: string, req: {
+        requestId: string;
+        toolName: string;
+        displayName?: string;
+        input: unknown;
+        description?: string;
+        askUser?: {
+            question: string;
+            header?: string;
+            options: string[];
+            multiSelect: boolean;
+        };
+    }) => void;
+    /** Called after a room's resident process exits or the room is explicitly
+     * closed. Live transcript followers use it as their natural terminal hook. */
+    onRoomEnded?: (roomId: string) => void;
+    now?: () => number;
+}
+/**
+ * Owns room lifecycle and the on-disk message log (the authoritative source).
+ * A room's resident agent is started on open() and its normalized events are
+ * appended to messages.jsonl and mirrored via onMessage. seq is monotonic per
+ * room so the phone can sync incrementally.
+ */
+export declare class RoomManager {
+    private readonly opts;
+    private agents;
+    /** Rooms whose visible output is currently sourced from the external CLI's
+     * transcript tail. While present, the resident agent's stdout mirror is
+     * suppressed so the same CLI output is not pushed twice. */
+    private transcriptFollowedRooms;
+    /** Pending AskUserQuestion control requests, keyed by `${roomId}:${requestId}`.
+     *  Holds the raw tool input so respondApproval can bake the user's answer into
+     *  the `answers` record the CLI expects. Cleared on response. */
+    private pendingAskUser;
+    /** User turns are echoed immediately for responsive room UX. When a
+     * transcript follower later sees the same CLI-written user line, this queue
+     * suppresses that duplicate. */
+    private pendingTranscriptUserEchoes;
+    /**
+     * Rooms whose agent events must be buffered instead of handled immediately.
+     *
+     * Only set for the duration of `agent.send()` inside `send()`: acceptance has
+     * to be known before the user turn is persisted, but the user turn must still
+     * come FIRST in the history. An agent that emits synchronously from send()
+     * would otherwise have its reply appended ahead of the prompt it answers.
+     */
+    private deferredEmitRooms;
+    private deferredEmits;
+    /**
+     * Last assigned message seq per room, so appends do not re-read the whole
+     * JSONL. Seeded lazily from disk on the first append after startup; dropped
+     * when the room's messages are deleted so the next append re-derives it.
+     */
+    private lastSeqByRoom;
+    /** Throttled lastActiveAt bookkeeping — see touchLastActive. */
+    private pendingLastActive;
+    private lastActiveWrittenAt;
+    private now;
+    /** 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
+     *  5-min timeout. Keys are `${roomId}:${requestId}`. */
+    private clearPendingAskUser;
+    constructor(opts: RoomManagerOptions);
+    private roomDir;
+    private metaPath;
+    private msgPath;
+    createRoom(input: {
+        name?: string;
+        cwd: string;
+        kind?: RoomKind;
+        permissionMode?: RoomPermissionMode;
+        claudeSessionId?: string;
+        linkedSessionMode?: "observe-only";
+    }): RoomMeta;
+    listRooms(): RoomMeta[];
+    getRoom(id: string): RoomMeta | undefined;
+    private nextSeq;
+    private append;
+    /**
+     * Refresh the room's `lastActiveAt`, throttled.
+     *
+     * This re-read and rewrote the whole room.json on EVERY appended message. The
+     * field only feeds idle-based pruning (measured in hours), so second-level
+     * precision is worthless while the write cost is paid per message — together
+     * with the old full-history seq scan it made a busy room progressively slower.
+     *
+     * Writes at most once per THROTTLE window per room; `flushLastActive` forces
+     * one out at close/prune time so a room that goes quiet still records its real
+     * last activity.
+     */
+    private touchLastActive;
+    /** Persist a pending lastActiveAt immediately, if there is one. */
+    private flushLastActive;
+    /** Persist the room's resume id (claude session_id / codex thread_id) so the
+     *  next open() can continue the same conversation. No-op if unchanged. */
+    setRoomSessionId(id: string, sessionId: string): void;
+    getMessages(id: string, sinceSeq?: number): RoomMessage[];
+    latestSeq(id: string): number;
+    beginTranscriptFollow(id: string): void;
+    endTranscriptFollow(id: string): void;
+    /** 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;
+    /**
+     * 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.
+     */
+    openForSession(claudeSessionId: string, cwd: string, mode: RoomPermissionMode, kind?: RoomKind): {
+        roomId: string;
+        status: RoomOpenStatus;
+    };
+    /** Bind an external CLI transcript to a room for observation only.
+     *
+     * This method never creates or starts a resident agent. The host must first
+     * prove that an on-disk transcript exists for the exact kind + session id +
+     * cwd tuple. A missing locator, missing transcript, or mismatched identity
+     * fails closed before a room is created.
+     */
+    openLinkedSession(externalSessionId: string, cwd: string, kind: RoomKind): {
+        roomId: string;
+        status: "observing" | "running";
+        mode: RoomPermissionMode;
+        cwd: string;
+    };
+    /** Explicitly take control of a previously observed external CLI room.
+     * 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): {
+        roomId: string;
+        status: "running";
+        mode: RoomPermissionMode;
+        cwd: string;
+    };
+    private requireLinkedSessionTarget;
+    /**
+     * Forward a phone-side approval decision to the room's resident agent.
+     * Returns false if the room has no live agent (or it can't take control
+     * responses).
+     */
+    respondApproval(roomId: string, requestId: string, decision: {
+        behavior: "allow";
+        updatedInput?: unknown;
+        answer?: string;
+    } | {
+        behavior: "deny";
+        message: string;
+    }): boolean;
+    /** Open a room: start its resident agent if not already running. Observe-only
+     * linked rooms fail closed until takeOverLinkedSession clears the boundary. */
+    open(id: string): {
+        status: RoomOpenStatus;
+    };
+    private onAgentEvent;
+    /** Post a user message: persist it, ensure agent running, feed it. */
+    send(id: string, text: string, attachments?: InputAttachmentMeta[]): boolean;
+    close(id: string): void;
+    closeAll(): void;
+    isOpen(id: string): boolean;
+    /**
+     * Delete rooms whose last activity is older than maxAgeMs (idle-based GC,
+     * replacing the removed one-shot /cc path's lack of cleanup). A room with a
+     * currently running resident agent is NEVER reaped, regardless of age — only
+     * truly dormant rooms (whole directory) are removed. Returns the ids deleted.
+     */
+    pruneStaleRooms(maxAgeMs: number): string[];
+}