@cjhyy/code-shell-server 0.8.0

package/dist/mobile-remote/codex-parse.d.ts

@@ -0,0 +1,34 @@
+import type { ResidentAgentEvent } from "./resident-agent.js";
+/**
+ * Parse ONE line of `codex exec --json` (JSONL) output into zero-or-more
+ * NORMALIZED ResidentAgentEvents — the exact same render-friendly union the
+ * claude room emits, so desktop + mobile UIs render a codex room with no
+ * UI-side changes. Pure + synchronous → unit-testable against recorded codex
+ * output without spawning codex.
+ *
+ * Codex event shapes (verified against codex-cli 0.142.4):
+ *   {type:"thread.started", thread_id}                       → [] (id captured by the process, not here)
+ *   {type:"turn.started"}                                    → []
+ *   {type:"item.started"|"item.updated"|"item.completed", item:{id,type,...}}
+ *       item.type "agent_message"     → text   (on completed only — dedup)
+ *       item.type "reasoning"         → []      (thinking noise)
+ *       item.type "command_execution" → tool(Bash) on start, tool_result on complete
+ *       item.type "mcp_tool_call"     → tool(server__tool) on start, tool_result on complete
+ *       item.type "web_search"        → tool(WebSearch) on start
+ *       item.type "file_change"       → tool(Edit) on start
+ *   {type:"turn.completed", usage}                           → turn_end
+ *   {type:"turn.failed", error}                              → error
+ *   {type:"error", message}                                  → error
+ *
+ * NOTE: codex never produces an approval_request — its only guardrail is the
+ * sandbox tier chosen at spawn time (read-only / workspace-write / bypass).
+ */
+export declare function parseCodexJsonLine(line: string): ResidentAgentEvent[];
+/**
+ * Pull the codex thread id out of a `thread.started` line, or undefined for any
+ * other line. Kept here (not inline in the room agent) so ALL codex JSONL
+ * knowledge lives in one file — parseCodexJsonLine deliberately drops
+ * thread.started (it's resume-control info, not a render event), so the room
+ * agent uses THIS to capture the id without a second hand-rolled JSON.parse.
+ */
+export declare function extractThreadId(line: string): string | undefined;

package/dist/mobile-remote/codex-parse.js

@@ -0,0 +1,131 @@
+/**
+ * Parse ONE line of `codex exec --json` (JSONL) output into zero-or-more
+ * NORMALIZED ResidentAgentEvents — the exact same render-friendly union the
+ * claude room emits, so desktop + mobile UIs render a codex room with no
+ * UI-side changes. Pure + synchronous → unit-testable against recorded codex
+ * output without spawning codex.
+ *
+ * Codex event shapes (verified against codex-cli 0.142.4):
+ *   {type:"thread.started", thread_id}                       → [] (id captured by the process, not here)
+ *   {type:"turn.started"}                                    → []
+ *   {type:"item.started"|"item.updated"|"item.completed", item:{id,type,...}}
+ *       item.type "agent_message"     → text   (on completed only — dedup)
+ *       item.type "reasoning"         → []      (thinking noise)
+ *       item.type "command_execution" → tool(Bash) on start, tool_result on complete
+ *       item.type "mcp_tool_call"     → tool(server__tool) on start, tool_result on complete
+ *       item.type "web_search"        → tool(WebSearch) on start
+ *       item.type "file_change"       → tool(Edit) on start
+ *   {type:"turn.completed", usage}                           → turn_end
+ *   {type:"turn.failed", error}                              → error
+ *   {type:"error", message}                                  → error
+ *
+ * NOTE: codex never produces an approval_request — its only guardrail is the
+ * sandbox tier chosen at spawn time (read-only / workspace-write / bypass).
+ */
+export function parseCodexJsonLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return [];
+    let msg;
+    try {
+        msg = JSON.parse(trimmed);
+    }
+    catch {
+        return [];
+    }
+    if (msg.type === "turn.completed")
+        return [{ type: "turn_end", reason: "completed" }];
+    if (msg.type === "turn.failed") {
+        return [{ type: "error", error: errText(msg.error) || "turn failed" }];
+    }
+    if (msg.type === "error") {
+        return [{ type: "error", error: errText(msg.message ?? msg.error) || "error" }];
+    }
+    const phase = msg.type === "item.started" ? "started" : msg.type === "item.updated" ? "updated" : msg.type === "item.completed" ? "completed" : null;
+    if (!phase)
+        return []; // thread.started / turn.started / unknown → noise
+    const item = msg.item;
+    if (!item || typeof item !== "object")
+        return [];
+    const id = typeof item.id === "string" ? item.id : undefined;
+    switch (item.type) {
+        case "agent_message":
+            // Only the final text (avoid duplicating the streaming updates).
+            return phase === "completed" && typeof item.text === "string" ? [{ type: "text", text: item.text }] : [];
+        case "reasoning":
+            return []; // thinking — not in the render union
+        case "command_execution":
+            if (phase === "completed") {
+                return [{
+                        type: "tool_result",
+                        id,
+                        summary: String(item.aggregated_output ?? "").slice(0, 400),
+                        isError: typeof item.exit_code === "number" ? item.exit_code !== 0 : false,
+                    }];
+            }
+            return phase === "started"
+                ? [{ type: "tool", id, tool: "Bash", summary: String(item.command ?? ""), input: { command: String(item.command ?? "") } }]
+                : [];
+        case "mcp_tool_call":
+            if (phase === "completed") {
+                return [{
+                        type: "tool_result",
+                        id,
+                        summary: String(item.result ?? item.output ?? "").slice(0, 400),
+                        isError: item.status === "failed" || Boolean(item.is_error),
+                    }];
+            }
+            return phase === "started"
+                ? [{
+                        type: "tool",
+                        id,
+                        tool: `${item.server ?? "mcp"}__${item.tool ?? "tool"}`,
+                        summary: "",
+                        input: { arguments: item.arguments },
+                    }]
+                : [];
+        case "web_search":
+            return phase === "started"
+                ? [{ type: "tool", id, tool: "WebSearch", summary: String(item.query ?? ""), input: { query: String(item.query ?? "") } }]
+                : [];
+        case "file_change":
+            return phase === "started"
+                ? [{
+                        type: "tool",
+                        id,
+                        tool: "Edit",
+                        summary: String(item.path ?? ""),
+                        input: item.kind !== undefined ? { path: String(item.path ?? ""), kind: item.kind } : { path: String(item.path ?? "") },
+                    }]
+                : [];
+        default:
+            return [];
+    }
+}
+/**
+ * Pull the codex thread id out of a `thread.started` line, or undefined for any
+ * other line. Kept here (not inline in the room agent) so ALL codex JSONL
+ * knowledge lives in one file — parseCodexJsonLine deliberately drops
+ * thread.started (it's resume-control info, not a render event), so the room
+ * agent uses THIS to capture the id without a second hand-rolled JSON.parse.
+ */
+export function extractThreadId(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{"))
+        return undefined;
+    let msg;
+    try {
+        msg = JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    return msg.type === "thread.started" && typeof msg.thread_id === "string" ? msg.thread_id : undefined;
+}
+function errText(e) {
+    if (typeof e === "string")
+        return e;
+    if (e && typeof e === "object" && typeof e.message === "string")
+        return e.message;
+    return "";
+}

package/dist/mobile-remote/codex-room-agent.d.ts

@@ -0,0 +1,94 @@
+import type { ResidentAgentEvent } from "./resident-agent.js";
+import type { RoomAgent } from "./room-manager.js";
+type RoomPermissionMode = "default" | "acceptEdits" | "bypassPermissions";
+/** Map a room permission mode to codex's spawn-time sandbox tier. codex has no
+ *  per-tool approval; the tier IS the guardrail. (Mirrors core's codexAdapter.) */
+export declare function sandboxForMode(mode: RoomPermissionMode): {
+    bypass: boolean;
+    sandbox?: "read-only" | "workspace-write";
+};
+/** Build `codex exec` argv for one turn. Prompt is fed over stdin (trailing `-`).
+ *  Pure → unit-testable. */
+export declare function codexArgsForTurn(opts: {
+    mode: RoomPermissionMode;
+    threadId?: string;
+}): string[];
+/**
+ * Decide whether a finished codex turn should surface a stderr-based error.
+ * Pure → unit-testable.
+ *
+ * codex `exec --json` reports most failures as `turn.failed`/`error` JSON on
+ * STDOUT (handled by parseCodexJsonLine), but some (e.g. resuming a missing
+ * thread id, arg-parse failures) print ONLY to stderr with a non-zero exit and
+ * no JSON. So we report stderr as an error *only when the process actually
+ * failed* (non-zero exit). On a clean exit, stderr is just warnings/notices and
+ * must NOT become a red error in the room. Operating on full lines (not raw
+ * chunks) avoids a chunk split mid-line being mis-judged.
+ */
+export declare function codexStderrError(stderrLines: string[], exitCode: number | null): string | null;
+/**
+ * Decide whether a finished codex turn needs a FALLBACK seal event so the room
+ * UI doesn't hang on "working". Pure → unit-testable.
+ *
+ * The room is sealed (turn_end / error) the moment a `turn.completed` or
+ * `turn.failed` JSON line arrives on stdout. But a codex process can die WITHOUT
+ * emitting either — OOM-killed, segfaulted, or non-zero exit with output only
+ * half-written — and then nothing tells the reducer the turn is over: the
+ * progress card spins forever. This function returns the event the exit handler
+ * must emit in that gap.
+ *
+ * Cases:
+ *   - already sealed (turn JSON seen)        → null (don't double-seal)
+ *   - user stopped the room                  → null (stop() tears down the UI)
+ *   - a stderr error will be emitted          → null (that error seals the run)
+ *   - otherwise (crash / silent exit)         → a turn_end so the UI settles.
+ *     reason encodes how it ended for the transcript.
+ */
+export declare function sealEventOnExit(opts: {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    turnSealed: boolean;
+    stopping: boolean;
+    hasStderrError: boolean;
+}): ResidentAgentEvent | null;
+export interface CodexRoomAgentOptions {
+    command: string;
+    cwd: string;
+    permissionMode: RoomPermissionMode;
+    /** Resume an existing codex thread (across app restarts). */
+    resumeThreadId?: string;
+    onEvent: (event: ResidentAgentEvent) => void;
+    /** Surfaced when codex mints/confirms its thread id, so the room can persist
+     *  it for resume on the next turn / after restart. */
+    onThreadId?: (threadId: string) => void;
+}
+/**
+ * A codex-backed room agent. Unlike the claude resident process (one long-lived
+ * stdin-fed process), codex `exec` runs ONE process per turn and the next turn
+ * continues the conversation via `resume <thread_id>`. So `send()` spawns a
+ * fresh `codex exec` each time, capturing the thread id from the first turn and
+ * resuming it thereafter. Implements the same RoomAgent interface so RoomManager
+ * treats it identically; it has no `respondControl` (codex has no per-tool
+ * approval — the sandbox tier is the guardrail).
+ */
+export declare class CodexRoomAgent implements RoomAgent {
+    private readonly opts;
+    private child?;
+    private threadId?;
+    private started;
+    /** True once the CURRENT turn emitted a sealing event (turn_end via
+     *  turn.completed, or an error). Reset at the start of each send(). */
+    private turnSealed;
+    /** True while stop() is tearing the room down, so the exit handler doesn't
+     *  mistake an intentional SIGTERM for a crash. */
+    private stopping;
+    constructor(opts: CodexRoomAgentOptions);
+    /** No persistent process to launch; a turn's process is spawned on send(). */
+    start(): void;
+    send(text: string): boolean;
+    /** The room is "running" once started — independent of whether a turn's
+     *  process is currently alive (turns are ephemeral). */
+    isRunning(): boolean;
+    stop(): void;
+}
+export {};

package/dist/mobile-remote/codex-room-agent.js

@@ -0,0 +1,213 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { pathWithCommonBins } from "./path-bins.js";
+import { parseCodexJsonLine, extractThreadId } from "./codex-parse.js";
+/** Map a room permission mode to codex's spawn-time sandbox tier. codex has no
+ *  per-tool approval; the tier IS the guardrail. (Mirrors core's codexAdapter.) */
+export function sandboxForMode(mode) {
+    if (mode === "bypassPermissions")
+        return { bypass: true, sandbox: undefined };
+    return { bypass: false, sandbox: mode === "acceptEdits" ? "workspace-write" : "read-only" };
+}
+/** Build `codex exec` argv for one turn. Prompt is fed over stdin (trailing `-`).
+ *  Pure → unit-testable. */
+export function codexArgsForTurn(opts) {
+    const args = ["exec", "--json", "--color", "never", "--skip-git-repo-check"];
+    const { bypass, sandbox } = sandboxForMode(opts.mode);
+    if (bypass)
+        args.push("--dangerously-bypass-approvals-and-sandbox");
+    else if (sandbox)
+        args.push("--sandbox", sandbox);
+    if (opts.threadId)
+        args.push("resume", opts.threadId, "-");
+    else
+        args.push("-");
+    return args;
+}
+/**
+ * Decide whether a finished codex turn should surface a stderr-based error.
+ * Pure → unit-testable.
+ *
+ * codex `exec --json` reports most failures as `turn.failed`/`error` JSON on
+ * STDOUT (handled by parseCodexJsonLine), but some (e.g. resuming a missing
+ * thread id, arg-parse failures) print ONLY to stderr with a non-zero exit and
+ * no JSON. So we report stderr as an error *only when the process actually
+ * failed* (non-zero exit). On a clean exit, stderr is just warnings/notices and
+ * must NOT become a red error in the room. Operating on full lines (not raw
+ * chunks) avoids a chunk split mid-line being mis-judged.
+ */
+export function codexStderrError(stderrLines, exitCode) {
+    if (exitCode === 0 || exitCode === null)
+        return null;
+    const text = stderrLines.join("\n").trim();
+    if (!text)
+        return null;
+    return text.slice(0, 800);
+}
+/**
+ * Decide whether a finished codex turn needs a FALLBACK seal event so the room
+ * UI doesn't hang on "working". Pure → unit-testable.
+ *
+ * The room is sealed (turn_end / error) the moment a `turn.completed` or
+ * `turn.failed` JSON line arrives on stdout. But a codex process can die WITHOUT
+ * emitting either — OOM-killed, segfaulted, or non-zero exit with output only
+ * half-written — and then nothing tells the reducer the turn is over: the
+ * progress card spins forever. This function returns the event the exit handler
+ * must emit in that gap.
+ *
+ * Cases:
+ *   - already sealed (turn JSON seen)        → null (don't double-seal)
+ *   - user stopped the room                  → null (stop() tears down the UI)
+ *   - a stderr error will be emitted          → null (that error seals the run)
+ *   - otherwise (crash / silent exit)         → a turn_end so the UI settles.
+ *     reason encodes how it ended for the transcript.
+ */
+export function sealEventOnExit(opts) {
+    if (opts.turnSealed || opts.stopping || opts.hasStderrError)
+        return null;
+    const reason = opts.signal != null
+        ? `killed:${opts.signal}`
+        : opts.code && opts.code !== 0
+            ? `exited:${opts.code}`
+            : "completed";
+    return { type: "turn_end", reason };
+}
+/**
+ * A codex-backed room agent. Unlike the claude resident process (one long-lived
+ * stdin-fed process), codex `exec` runs ONE process per turn and the next turn
+ * continues the conversation via `resume <thread_id>`. So `send()` spawns a
+ * fresh `codex exec` each time, capturing the thread id from the first turn and
+ * resuming it thereafter. Implements the same RoomAgent interface so RoomManager
+ * treats it identically; it has no `respondControl` (codex has no per-tool
+ * approval — the sandbox tier is the guardrail).
+ */
+export class CodexRoomAgent {
+    opts;
+    child;
+    threadId;
+    started = false;
+    /** True once the CURRENT turn emitted a sealing event (turn_end via
+     *  turn.completed, or an error). Reset at the start of each send(). */
+    turnSealed = false;
+    /** True while stop() is tearing the room down, so the exit handler doesn't
+     *  mistake an intentional SIGTERM for a crash. */
+    stopping = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.threadId = opts.resumeThreadId;
+    }
+    /** No persistent process to launch; a turn's process is spawned on send(). */
+    start() {
+        this.started = true;
+    }
+    send(text) {
+        if (!this.started)
+            return false;
+        if (this.child)
+            return false; // a turn is already running; one turn at a time
+        this.turnSealed = false; // fresh turn — not yet sealed
+        const args = codexArgsForTurn({ mode: this.opts.permissionMode, threadId: this.threadId });
+        const child = spawn(this.opts.command, args, {
+            cwd: this.opts.cwd,
+            env: { ...process.env, PATH: pathWithCommonBins() },
+            detached: true,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.child = child;
+        // Feed the user's prompt over stdin (codex exec reads it because argv ends `-`).
+        child.stdin?.end(text);
+        if (child.stdout) {
+            const rl = createInterface({ input: child.stdout });
+            rl.on("line", (line) => {
+                // Capture the thread id (parseCodexJsonLine intentionally drops
+                // thread.started — it's resume-control info, not a render event) so we
+                // can resume on the next turn and persist it across restarts.
+                const tid = extractThreadId(line);
+                if (tid) {
+                    this.threadId = tid;
+                    this.opts.onThreadId?.(tid);
+                }
+                for (const ev of parseCodexJsonLine(line)) {
+                    // turn_end / error are the reducer's sealing events — once one fires
+                    // for this turn, the exit handler need not synthesize a fallback.
+                    if (ev.type === "turn_end" || ev.type === "error")
+                        this.turnSealed = true;
+                    this.opts.onEvent(ev);
+                }
+            });
+        }
+        // Accumulate stderr by LINE; only surface it as an error if the turn exits
+        // non-zero (see codexStderrError). Per-chunk `/error/i` matching produced
+        // spurious red errors from non-fatal warnings and could misjudge a line
+        // split across chunks.
+        const stderrLines = [];
+        if (child.stderr) {
+            const errRl = createInterface({ input: child.stderr });
+            errRl.on("line", (line) => stderrLines.push(line));
+        }
+        child.on("error", (err) => {
+            const isMissing = err.code === "ENOENT";
+            this.turnSealed = true; // this error seals the run in the reducer
+            this.opts.onEvent({
+                type: "error",
+                error: isMissing
+                    ? `未找到命令 "${this.opts.command}"。请先安装 Codex CLI 并确保它在 PATH 中。`
+                    : err.message,
+            });
+            this.child = undefined;
+        });
+        child.on("exit", (code, signal) => {
+            // The turn's process is done; the room stays "running" (ready for the next
+            // turn). We do NOT emit `exit` here — that would tear the room down in the
+            // UI after every turn. turn.completed already produced a `turn_end`.
+            // A non-zero exit whose error went only to stderr (no turn.failed JSON)
+            // is surfaced now so the room shows *why* it failed.
+            const stderrErr = codexStderrError(stderrLines, code);
+            if (stderrErr) {
+                this.turnSealed = true;
+                this.opts.onEvent({ type: "error", error: stderrErr });
+            }
+            // FALLBACK SEAL (#6): if the process died without ever sealing the turn
+            // (no turn.completed / turn.failed JSON, no stderr error) and we didn't
+            // stop it ourselves, the room UI would hang on "working" forever. Emit a
+            // synthetic turn_end so the progress card settles.
+            const seal = sealEventOnExit({
+                code,
+                signal,
+                turnSealed: this.turnSealed,
+                stopping: this.stopping,
+                hasStderrError: stderrErr != null,
+            });
+            if (seal)
+                this.opts.onEvent(seal);
+            this.child = undefined;
+        });
+        return true;
+    }
+    /** The room is "running" once started — independent of whether a turn's
+     *  process is currently alive (turns are ephemeral). */
+    isRunning() {
+        return this.started;
+    }
+    stop() {
+        this.started = false;
+        this.stopping = true; // the upcoming SIGTERM exit is intentional, not a crash
+        const child = this.child;
+        this.child = undefined;
+        if (!child?.pid || child.pid <= 1) {
+            child?.kill("SIGTERM");
+            return;
+        }
+        try {
+            process.kill(-child.pid, "SIGTERM");
+        }
+        catch {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+}

package/dist/mobile-remote/mobile-attachments.d.ts

@@ -0,0 +1,21 @@
+import { type InputAttachmentMeta } from "../attachment-service.js";
+import type { MobileAttachmentSummary, MobileImageAttachment } from "./types.js";
+import type { ClaimedMobileUpload, MobileUploadService } from "./mobile-upload-service.js";
+export declare const MAX_MOBILE_ATTACHMENTS = 4;
+export declare const MAX_MOBILE_INLINE_IMAGE_BYTES: number;
+export declare const MAX_MOBILE_INLINE_TOTAL_BYTES: number;
+export declare const MAX_MOBILE_ATTACHMENT_TOTAL_BYTES: number;
+interface MaterializeInput {
+    deviceId: string;
+    cwd: string;
+    sessionId: string;
+    attachments?: MobileImageAttachment[];
+    uploads: Pick<MobileUploadService, "claim" | "release">;
+}
+/** Validate phone descriptors, resolve spools, and stage canonical attachment metadata. */
+export declare function materializeMobileAttachments(input: MaterializeInput): Promise<{
+    metas: InputAttachmentMeta[];
+    claims: ClaimedMobileUpload[];
+    summaries: MobileAttachmentSummary[];
+}>;
+export {};

package/dist/mobile-remote/mobile-attachments.js

@@ -0,0 +1,119 @@
+import { stageImageBytes } from "../attachment-service.js";
+export const MAX_MOBILE_ATTACHMENTS = 4;
+export const MAX_MOBILE_INLINE_IMAGE_BYTES = 256 * 1024;
+export const MAX_MOBILE_INLINE_TOTAL_BYTES = 512 * 1024;
+export const MAX_MOBILE_ATTACHMENT_TOTAL_BYTES = 20 * 1024 * 1024;
+const ALLOWED_MIMES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "image/gif",
+]);
+function decodeInline(descriptor) {
+    const match = /^data:([^;,]+);base64,([\s\S]*)$/.exec(descriptor.dataUrl);
+    if (!match || String(match[1]).toLowerCase() !== descriptor.mime) {
+        throw new Error("inline image MIME does not match its data URL");
+    }
+    const base64 = String(match[2] ?? "").replace(/\s+/g, "");
+    if (base64.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(base64)) {
+        throw new Error("invalid inline image base64");
+    }
+    const bytes = Buffer.from(base64, "base64");
+    if (bytes.byteLength !== descriptor.size) {
+        throw new Error("inline image size does not match its decoded bytes");
+    }
+    if (bytes.byteLength > MAX_MOBILE_INLINE_IMAGE_BYTES) {
+        throw new Error("inline image exceeds the inline size limit");
+    }
+    return bytes;
+}
+function assertBaseFields(descriptor) {
+    if (!descriptor.clientId?.trim())
+        throw new Error("attachment clientId is required");
+    if (!descriptor.name?.trim())
+        throw new Error("attachment name is required");
+    if (!ALLOWED_MIMES.has(descriptor.mime))
+        throw new Error("unsupported image MIME");
+    if (!Number.isSafeInteger(descriptor.size) || descriptor.size <= 0) {
+        throw new Error("attachment size is invalid");
+    }
+}
+/** Validate phone descriptors, resolve spools, and stage canonical attachment metadata. */
+export async function materializeMobileAttachments(input) {
+    const descriptors = input.attachments ?? [];
+    if (descriptors.length > MAX_MOBILE_ATTACHMENTS) {
+        throw new Error(`at most ${MAX_MOBILE_ATTACHMENTS} image attachments are allowed`);
+    }
+    const seen = new Set();
+    const prepared = [];
+    const claims = [];
+    let inlineTotal = 0;
+    let total = 0;
+    try {
+        for (const descriptor of descriptors) {
+            assertBaseFields(descriptor);
+            if (seen.has(descriptor.clientId))
+                throw new Error("duplicate attachment clientId");
+            seen.add(descriptor.clientId);
+            if (descriptor.transport === "inline") {
+                const bytes = decodeInline(descriptor);
+                inlineTotal += bytes.byteLength;
+                total += bytes.byteLength;
+                prepared.push({ descriptor, bytes });
+            }
+            else if (descriptor.transport === "upload") {
+                if (!descriptor.uploadId?.trim())
+                    throw new Error("uploadId is required");
+                const upload = input.uploads.claim(input.deviceId, descriptor.uploadId);
+                claims.push(upload);
+                if (upload.clientId !== descriptor.clientId ||
+                    upload.name !== descriptor.name ||
+                    upload.mime !== descriptor.mime ||
+                    upload.size !== descriptor.size) {
+                    throw new Error("uploaded image metadata does not match its descriptor");
+                }
+                total += upload.size;
+                prepared.push({ descriptor, upload });
+            }
+            else {
+                throw new Error("unsupported attachment transport");
+            }
+        }
+        if (inlineTotal > MAX_MOBILE_INLINE_TOTAL_BYTES) {
+            throw new Error("inline image total exceeds the message limit");
+        }
+        if (total > MAX_MOBILE_ATTACHMENT_TOTAL_BYTES) {
+            throw new Error("image attachment total exceeds the message limit");
+        }
+        const metas = [];
+        for (const item of prepared) {
+            const common = {
+                cwd: input.cwd,
+                sessionId: input.sessionId,
+                name: item.descriptor.name,
+                mime: item.descriptor.mime,
+                origin: "mobile",
+            };
+            if ("bytes" in item) {
+                metas.push(await stageImageBytes({ ...common, bytes: item.bytes }));
+            }
+            else {
+                metas.push(await stageImageBytes({ ...common, sourceFile: item.upload.path }));
+            }
+        }
+        return {
+            metas,
+            claims,
+            summaries: descriptors.map(({ clientId, name, mime, size }) => ({
+                clientId,
+                name,
+                mime,
+                size,
+            })),
+        };
+    }
+    catch (error) {
+        await Promise.allSettled(claims.map((claim) => input.uploads.release(input.deviceId, claim.uploadId, claim.claimId)));
+        throw error;
+    }
+}

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

@@ -0,0 +1,32 @@
+import { markAttachmentsSent, type InputAttachmentMeta } from "../attachment-service.js";
+import { type MobileRunBridge } from "./mobile-run-dispatch.js";
+import type { MobileUploadService } from "./mobile-upload-service.js";
+import type { MobileAttachmentSummary, MobileImageAttachment, PermissionMode } from "./types.js";
+type ChatTurnUploads = Pick<MobileUploadService, "claim" | "release" | "finalize">;
+export interface DispatchMobileChatTurnInput {
+    deviceId: string;
+    sessionId: string;
+    fallbackCwd: string;
+    text: string;
+    attachments?: MobileImageAttachment[];
+    clientMessageId?: string;
+    permissionMode?: PermissionMode;
+    runId: string;
+    bridge: MobileRunBridge;
+    uploads: ChatTurnUploads;
+    resolveWorkspace: (sessionId: string, fallbackCwd: string) => Promise<string>;
+    markSent?: typeof markAttachmentsSent;
+}
+export type DispatchMobileChatTurnResult = {
+    ok: true;
+    cwd: string;
+    clientMessageId: string;
+    metas: InputAttachmentMeta[];
+    summaries: MobileAttachmentSummary[];
+} | {
+    ok: false;
+    message: string;
+};
+/** Transaction boundary for mobile chat: workspace → canonical stage → worker ack → finalize. */
+export declare function dispatchMobileChatTurn(input: DispatchMobileChatTurnInput): Promise<DispatchMobileChatTurnResult>;
+export {};