omp-mobile 0.2.0 → 0.3.0

package/NOTICE

@@ -4,3 +4,7 @@ Copyright (c) 2026 Rinai
 Licensed under the Apache License, Version 2.0. See the LICENSE file.
 
 OMP Mobile is not affiliated with oh-my-pi or Tailscale.
+
+The app bundles the Geist typeface (Copyright 2023 Vercel, in collaboration with basement.studio) and the
+JetBrains Mono typeface (Copyright 2020 The JetBrains Mono Project Authors), both under the SIL Open Font
+License 1.1; see app/assets/fonts.

package/README.md

@@ -13,13 +13,15 @@
 
 OMP Mobile is a native phone app for [oh-my-pi](https://github.com/can1357/oh-my-pi) (OMP), with a small daemon on each computer. Start, follow and steer OMP sessions from the phone: transcript, tool calls, approvals, and the sessions you started in a terminal.
 
-- **Native app:** The app draws the transcript, tool cards, thinking, Markdown and composer itself. No WebView, no web page.
+- **Native app:** The app draws the transcript, tool cards, thinking, Markdown and composer itself, in OMP's own look (Geist, JetBrains Mono, the π mark). No WebView, no web page.
+- **A transcript you can follow:** each stretch of tool calls folds into one card that shows the step running now and sums itself up when done ("Edited 2 files, ran 3"); tap a step for its command, diff and output. The view stays on the newest message while you are at the bottom and stays put while you read back.
 - **The whole transcript:** images the user sent and images tools produce (screenshots, opened files), edit diffs with their intent, tool results, Markdown tables, OMP's todo list, context usage and queued messages.
 - **Model switching:** tap the model in the composer to pick from OMP's catalog — grouped by provider and searchable — and set its thinking level. The model chip follows the session when it changes.
+- **Photos to the agent:** attach photos from the library or the camera; they are downscaled on the phone and sent with your message.
 - **Approvals on the phone:** OMP's own tool approvals and questions arrive as a sheet, and the turn waits for your answer.
 - **Terminal sessions:** Sessions you started in a terminal on the computer are listed too and continue on the phone. One still open in a terminal waits until that terminal exits.
 - **Notifications:** Android notifications for approvals, questions, and finished turns while the app is in the background.
-- **All your machines:** Pair each computer by QR code, switch between them from the session list. A reopened chat shows at once, also offline.
+- **All your machines:** Pair each computer by QR code and give it a name on the phone. Tap a chat's title for every session on every computer — searchable, with what needs you first. The app opens on the computer you used last; a reopened chat shows at once, also offline.
 - **Tailscale only:** The daemon listens on the computer's Tailscale address and admits only your own devices. No relay or cloud service of its own.
 - **An OMP plugin:** `/mobile` in OMP starts the daemon in the background and shows the pairing code. The daemon keeps running after the terminal closes.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-mobile",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The computer side of OMP Mobile: runs oh-my-pi sessions and serves them to the phone app over Tailscale.",
   "keywords": [
     "mobile",

package/src/rpc-frame.mjs

@@ -0,0 +1,135 @@
+/**
+ * OMP's RPC framing, the parts the daemon needs to read protocol v2.
+ *
+ * Protocol v1 caps every JSON line at 1 MiB; a response above that arrives as
+ * `{success: false, error: "RPC response exceeded the transport limit"}`. After
+ * `negotiate_protocol` v2, OMP splits a larger frame into `rpc_chunk` lines
+ * (base64 slices of the frame's UTF-8 bytes) that reassemble up to 64 MiB.
+ * The limits and checks mirror OMP's `rpc-frame.ts` so a frame OMP accepts
+ * is one this decoder accepts.
+ */
+
+/** Maximum UTF-8 size of one newline-delimited RPC frame, including the newline. */
+export const MAX_RPC_FRAME_BYTES = 1024 * 1024;
+/** Maximum UTF-8 size of one logical frame reassembled by protocol v2. */
+export const MAX_RPC_REASSEMBLED_BYTES = 64 * 1024 * 1024;
+/** Bytes of the original frame carried by one chunk. */
+export const RPC_CHUNK_PAYLOAD_BYTES = 256 * 1024;
+
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+/**
+ * Whether OMP's `ready` frame offers protocol v2 with the limits this decoder implements.
+ * @param {unknown} ready
+ */
+export function supportsProtocolV2(ready) {
+  if (ready === null || typeof ready !== "object") return false;
+  const value = /** @type {Record<string, unknown>} */ (ready);
+  return (
+    value.type === "ready" &&
+    Array.isArray(value.supportedProtocolVersions) &&
+    value.supportedProtocolVersions.includes(2) &&
+    value.maxFrameBytes === MAX_RPC_FRAME_BYTES &&
+    value.maxReassembledFrameBytes === MAX_RPC_REASSEMBLED_BYTES
+  );
+}
+
+/** @param {unknown} data */
+function decodeBase64(data) {
+  if (typeof data !== "string" || data.length === 0 || !BASE64.test(data)) throw new Error("invalid rpc chunk data");
+  const bytes = Buffer.from(data, "base64");
+  if (bytes.toString("base64") !== data) throw new Error("invalid rpc chunk data");
+  return bytes;
+}
+
+/**
+ * Reassembles `rpc_chunk` sequences. Feed it every parsed line in order: a
+ * plain frame comes straight back, a chunk returns undefined until its
+ * sequence completes, then the reassembled frame. Any violation throws, and
+ * the decoder is left empty for the next frame.
+ */
+export class RpcFrameDecoder {
+  /** @type {{chunkId: string, count: number, byteLength: number, nextIndex: number, chunks: Buffer[], receivedBytes: number} | undefined} */
+  #pending = undefined;
+
+  /**
+   * @param {unknown} value
+   * @returns {object | undefined}
+   */
+  push(value) {
+    try {
+      return this.#push(value);
+    } catch (error) {
+      this.#pending = undefined;
+      throw error;
+    }
+  }
+
+  /** @param {unknown} value */
+  #push(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("rpc frame must be an object");
+    const frame = /** @type {Record<string, unknown>} */ (value);
+    if (frame.type !== "rpc_chunk") {
+      if (this.#pending !== undefined) throw new Error("rpc chunk sequence interrupted");
+      return frame;
+    }
+    const { chunkId, index, count, byteLength } = frame;
+    if (
+      typeof chunkId !== "string" ||
+      chunkId.length === 0 ||
+      chunkId.length > 128 ||
+      !Number.isSafeInteger(index) ||
+      !Number.isSafeInteger(count) ||
+      !Number.isSafeInteger(byteLength) ||
+      /** @type {number} */ (index) < 0 ||
+      /** @type {number} */ (count) < 2 ||
+      /** @type {number} */ (count) > Math.ceil(MAX_RPC_REASSEMBLED_BYTES / RPC_CHUNK_PAYLOAD_BYTES) ||
+      /** @type {number} */ (index) >= /** @type {number} */ (count) ||
+      /** @type {number} */ (byteLength) < MAX_RPC_FRAME_BYTES ||
+      /** @type {number} */ (byteLength) > MAX_RPC_REASSEMBLED_BYTES
+    ) {
+      throw new Error("invalid rpc chunk metadata");
+    }
+    const bytes = decodeBase64(frame.data);
+    if (bytes.byteLength > RPC_CHUNK_PAYLOAD_BYTES) throw new Error("rpc chunk payload exceeds the transport limit");
+    if (this.#pending === undefined) {
+      if (index !== 0) throw new Error("rpc chunk sequence must start at index 0");
+      this.#pending = { chunkId, count: /** @type {number} */ (count), byteLength: /** @type {number} */ (byteLength), nextIndex: 0, chunks: [], receivedBytes: 0 };
+    }
+    const pending = this.#pending;
+    if (pending.chunkId !== chunkId || pending.count !== count || pending.byteLength !== byteLength || pending.nextIndex !== index) {
+      throw new Error("rpc chunk sequence mismatch");
+    }
+    pending.chunks.push(bytes);
+    pending.receivedBytes += bytes.byteLength;
+    pending.nextIndex += 1;
+    if (pending.receivedBytes > pending.byteLength) throw new Error("rpc chunk sequence exceeds its byte length");
+    if (pending.nextIndex < pending.count) return undefined;
+    this.#pending = undefined;
+    if (pending.receivedBytes !== pending.byteLength) throw new Error("rpc chunk sequence ended short of its byte length");
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(pending.chunks, pending.receivedBytes));
+    const reassembled = JSON.parse(text);
+    if (reassembled === null || typeof reassembled !== "object" || Array.isArray(reassembled)) {
+      throw new Error("reassembled rpc frame must be an object");
+    }
+    if (reassembled.type === "rpc_chunk") throw new Error("reassembled rpc frame must not be a chunk");
+    return reassembled;
+  }
+}
+
+/**
+ * Split one frame into the `rpc_chunk` lines OMP v2 writes for it (used by tests and fakes).
+ * @param {object} frame
+ * @param {string} chunkId
+ * @returns {string[]}
+ */
+export function chunkFrame(frame, chunkId) {
+  const bytes = Buffer.from(JSON.stringify(frame), "utf8");
+  const count = Math.ceil(bytes.byteLength / RPC_CHUNK_PAYLOAD_BYTES);
+  const lines = [];
+  for (let index = 0; index < count; index += 1) {
+    const data = bytes.subarray(index * RPC_CHUNK_PAYLOAD_BYTES, (index + 1) * RPC_CHUNK_PAYLOAD_BYTES).toString("base64");
+    lines.push(JSON.stringify({ type: "rpc_chunk", chunkId, index, count, byteLength: bytes.byteLength, data }));
+  }
+  return lines;
+}

package/src/rpc-session.mjs

@@ -9,6 +9,7 @@ import { spawn } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { randomUUID } from "node:crypto";
 import { createInterface } from "node:readline";
+import { RpcFrameDecoder, supportsProtocolV2 } from "./rpc-frame.mjs";
 
 const START_TIMEOUT_MS = 45_000;
 
@@ -21,6 +22,38 @@ function withoutBunFlag(env) {
   return rest;
 }
 const REQUEST_TIMEOUT_MS = 60_000;
+/** Messages per `get_messages_page` request: OMP's maximum; a page also stays under 768 KiB. */
+const MESSAGE_PAGE_LIMIT = 256;
+/** OMP's `get_messages_page` codes that mean "page later or read it whole", as OMP's own client treats them. */
+const PAGE_FALLBACK_CODES = new Set(["session_busy", "stale_cursor"]);
+const PAGE_FALLBACK_MESSAGES = new Set([
+  "Cannot page messages while the session is changing",
+  "RPC message cursor is stale",
+]);
+
+/**
+ * A failed RPC command: OMP's error text, and its machine-readable `code` when it sent one.
+ */
+export class RpcCommandError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} command
+   * @param {string | undefined} code
+   */
+  constructor(message, command, code) {
+    super(message);
+    this.name = "RpcCommandError";
+    this.command = command;
+    this.code = code;
+  }
+}
+
+/** Whether a paging failure should fall back to one whole `get_messages`. */
+function pageFallback(error) {
+  if (!(error instanceof Error)) return false;
+  if (error instanceof RpcCommandError && error.code !== undefined && PAGE_FALLBACK_CODES.has(error.code)) return true;
+  return PAGE_FALLBACK_MESSAGES.has(error.message);
+}
 
 /** Events that carry no useful state to the phone. */
 const IGNORED_UI = new Set(["setStatus", "setWidget", "setTitle", "set_editor_text"]);
@@ -88,6 +121,9 @@ export class RpcSession extends EventEmitter {
     this.lastState = null;
     this.lastError = null;
     this.stderr = "";
+    /** 1 until OMP accepts `negotiate_protocol` v2; then frames above 1 MiB arrive as chunks. */
+    this.protocolVersion = 1;
+    this.frames = new RpcFrameDecoder();
   }
 
   /** Start the process and resolve once it printed `ready`. */
@@ -132,7 +168,14 @@ export class RpcSession extends EventEmitter {
       });
     });
     lines.on("line", (line) => this.#onLine(line));
-    await ready;
+    const hello = await ready;
+    // v1 caps every frame at 1 MiB: a long session's messages or a large tool
+    // result would come back as a transport-limit error. v2 chunks them instead.
+    if (supportsProtocolV2(hello)) {
+      const response = await this.request("negotiate_protocol", { protocolVersion: 2 });
+      if (response.data?.protocolVersion !== 2) throw new Error("omp RPC protocol v2 negotiation failed");
+      this.protocolVersion = 2;
+    }
     this.started = true;
     return this;
   }
@@ -141,11 +184,13 @@ export class RpcSession extends EventEmitter {
   #onLine(line) {
     let message;
     try {
-      message = JSON.parse(line);
+      message = this.frames.push(JSON.parse(line));
     } catch {
       this.emit("protocol-error", { line: line.slice(0, 500) });
       return;
     }
+    // A chunk of a larger frame: the frame is handled once its last chunk arrives.
+    if (message === undefined) return;
     this.updatedAt = Date.now();
     if (message.type === "ready") {
       this.emit("ready", message);
@@ -155,7 +200,9 @@ export class RpcSession extends EventEmitter {
       const pending = message.id ? this.pending.get(message.id) : undefined;
       if (pending !== undefined && message.id) {
         this.pending.delete(message.id);
-        if (message.success === false) pending.reject(new Error(message.error || `RPC ${message.command} failed`));
+        if (message.success === false) {
+          pending.reject(new RpcCommandError(message.error || `RPC ${message.command} failed`, message.command, message.code));
+        }
         else pending.resolve(message);
         return;
       }
@@ -252,12 +299,50 @@ export class RpcSession extends EventEmitter {
     return data;
   }
 
-  /** @returns {Promise<{messages: object[]}>} */
+  /**
+   * The session's messages. Under protocol v2 they are read in pages, as OMP's
+   * own RPC client does: one `get_messages` answer is a single frame, which a
+   * long uncompacted session outgrows. A page that cannot be read now (the
+   * session is changing, or the cursor went stale) falls back to the whole list
+   * in one response, which v2 may chunk.
+   * @returns {Promise<{messages: object[]}>}
+   */
   async getMessages() {
+    // As OMP's own client: pages only once v2 is negotiated (an OMP that offers v2 pages).
+    if (this.protocolVersion === 2) {
+      try {
+        return { messages: await this.#drainPages() };
+      } catch (error) {
+        if (!pageFallback(error)) throw error;
+      }
+    }
     const response = await this.request("get_messages");
     return response.data ?? { messages: [] };
   }
 
+  async #drainPages() {
+    const messages = [];
+    const seen = new Set();
+    /** @type {number | undefined} */
+    let total;
+    /** @type {string | undefined} */
+    let cursor;
+    do {
+      const response = await this.request("get_messages_page", cursor === undefined ? { limit: MESSAGE_PAGE_LIMIT } : { cursor, limit: MESSAGE_PAGE_LIMIT });
+      const page = response.data ?? {};
+      if (!Number.isSafeInteger(page.totalMessages) || page.totalMessages < 0 || (total !== undefined && page.totalMessages !== total)) {
+        throw new Error("omp message pages returned an inconsistent total");
+      }
+      total = page.totalMessages;
+      if (Array.isArray(page.messages)) messages.push(...page.messages);
+      cursor = typeof page.nextCursor === "string" && page.nextCursor !== "" ? page.nextCursor : undefined;
+      if (cursor !== undefined && seen.has(cursor)) throw new Error("omp message pages repeated a cursor");
+      if (cursor !== undefined) seen.add(cursor);
+    } while (cursor !== undefined);
+    if (messages.length !== total) throw new Error("omp message pages ended before the advertised total");
+    return messages;
+  }
+
   /**
    * The models this session can switch to, compacted for a phone list.
    * OMP waits out background discovery first, so this can take a few seconds.
@@ -293,9 +378,12 @@ export class RpcSession extends EventEmitter {
     return this.getState();
   }
 
-  /** @param {string} text */
-  async prompt(text) {
-    return this.request("prompt", { message: text });
+  /**
+   * @param {string} text
+   * @param {{type: "image", data: string, mimeType: string}[]} [images] OMP `ImageContent` parts sent with the text.
+   */
+  async prompt(text, images = []) {
+    return this.request("prompt", images.length > 0 ? { message: text, images } : { message: text });
   }
 
   async abort() {
@@ -327,4 +415,4 @@ export class RpcSession extends EventEmitter {
   }
 }
 
-export { REQUEST_TIMEOUT_MS, START_TIMEOUT_MS };
+export { REQUEST_TIMEOUT_MS, START_TIMEOUT_MS, MESSAGE_PAGE_LIMIT };

package/src/server.mjs

@@ -42,10 +42,46 @@ const STATE_EVENTS = new Set([
   "todo_auto_clear",
   "goal_updated",
 ]);
+/** Image types a phone may attach to a prompt: what the camera and the photo picker produce. */
+const PROMPT_IMAGE_TYPES = new Set(["image/jpeg", "image/png", "image/webp", "image/gif"]);
+/** At most this many images per prompt, each at most this many decoded bytes. */
+const MAX_PROMPT_IMAGES = 8;
+const MAX_PROMPT_IMAGE_BYTES = 10 * 1024 * 1024;
+
+/**
+ * The images of a `prompt` frame as OMP's `ImageContent`, checked: base64 that
+ * round-trips, a known image type, bounded count and size. Anything else is
+ * refused whole rather than sent half.
+ * @param {unknown} value
+ * @returns {{type: "image", data: string, mimeType: string}[]}
+ */
+export function promptImages(value) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new Error("images must be a list");
+  if (value.length > MAX_PROMPT_IMAGES) throw new Error(`at most ${MAX_PROMPT_IMAGES} images per message`);
+  return value.map((image, index) => {
+    const data = image?.data;
+    const mimeType = image?.mimeType;
+    if (typeof mimeType !== "string" || !PROMPT_IMAGE_TYPES.has(mimeType)) throw new Error(`image ${index + 1}: unsupported type`);
+    if (typeof data !== "string" || data === "") throw new Error(`image ${index + 1}: no data`);
+    const bytes = Buffer.from(data, "base64");
+    if (bytes.byteLength === 0 || bytes.toString("base64") !== data) throw new Error(`image ${index + 1}: data is not base64`);
+    if (bytes.byteLength > MAX_PROMPT_IMAGE_BYTES) throw new Error(`image ${index + 1}: larger than ${MAX_PROMPT_IMAGE_BYTES / 1024 / 1024} MB`);
+    return { type: "image", data, mimeType };
+  });
+}
+
+/**
+ * What this daemon supports beyond protocol 1, for an app to offer only what
+ * the computer it talks to can do. `prompt-images`: `prompt` frames carry `images`.
+ */
+const FEATURES = ["prompt-images"];
+/** Close code after an `open_failed` frame: the session socket opened only to say why the session could not. */
+const OPEN_FAILED_CLOSE_CODE = 4000;
 /** OMP's content-addressed image store under `<omp home>/agent/blobs`. */
 const BLOB_NAME = /^[0-9a-f]{64}$/;
 
-/** @typedef {{id: string, title: string, cwd: string, status: string, model?: string, createdAt: number, updatedAt: number, sessionFile?: string, origin: "daemon" | "omp", openElsewhere?: boolean}} SessionSummary */
+/** @typedef {{id: string, title: string, cwd: string, status: string, model?: string, createdAt: number, updatedAt: number, sessionFile?: string, origin: "daemon" | "omp", openElsewhere?: boolean, waiting?: number}} SessionSummary */
 
 /** An error with the HTTP status it answers. */
 function httpError(status, message) {
@@ -364,6 +400,8 @@ class SessionEntry {
       updatedAt: this.updatedAt,
       sessionFile: this.state?.sessionFile,
       origin: "daemon",
+      // OMP questions and tool approvals still waiting for an answer: the session needs the user.
+      waiting: this.openRequests().length,
     };
   }
 
@@ -451,6 +489,11 @@ class Daemon {
   constructor(options, token, identity = {}) {
     this.options = options;
     this.token = token;
+    /**
+     * Where failures nothing else reports go: the daemon's output is `~/.omp-mobile/daemon.log`.
+     * @type {(error: unknown) => void}
+     */
+    this.log = options.log ?? ((error) => console.error(`${new Date().toISOString()} ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`));
     this.admission = identity.admission;
     this.user = identity.user ?? "";
     this.startedAt = Date.now();
@@ -530,6 +573,7 @@ class Daemon {
         sessionCount: this.sessions.size,
         cwd: this.options.cwd,
         user: this.user || null,
+        features: FEATURES,
       });
       return;
     }
@@ -601,9 +645,10 @@ class Daemon {
       }
       sendJson(res, 404, { error: "not found" });
     } catch (error) {
-      sendJson(res, typeof error?.status === "number" ? error.status : 500, {
-        error: error instanceof Error ? error.message : String(error),
-      });
+      const status = typeof error?.status === "number" ? error.status : 500;
+      // A refusal the API defines (404, 409, 410) is an answer; anything else is a failure worth keeping.
+      if (status >= 500) this.log(error);
+      sendJson(res, status, { error: error instanceof Error ? error.message : String(error) });
     }
   }
 
@@ -657,7 +702,9 @@ class Daemon {
    */
   ensureLive(id) {
     const live = this.sessions.get(id);
-    if (live !== undefined) return Promise.resolve(live);
+    if (live !== undefined && !live.closed) return Promise.resolve(live);
+    // Its OMP process exited: resume it afresh instead of serving a dead session.
+    if (live !== undefined) this.sessions.delete(id);
     let starting = this.starting.get(id);
     if (starting === undefined) {
       starting = this.resume(id).finally(() => this.starting.delete(id));
@@ -683,16 +730,24 @@ class Daemon {
       autoApprove: this.options.autoApprove,
       extraArgs: this.options.approvalMode ? ["--approval-mode", this.options.approvalMode] : [],
     });
-    await rpc.start();
-    const entry = new SessionEntry(stored.cwd, rpc);
-    await entry.hydrate();
-    entry.id = id;
-    entry.onChange = (changed) => this.remember(changed);
-    entry.onBroadcast = (source, payload) => this.attention.observe(source, payload);
-    entry.bind();
-    this.sessions.set(id, entry);
-    this.remember(entry);
-    return entry;
+    // Until the session is registered the process is ours alone to close: left
+    // running it would hold the session's owner lock, so every later open would
+    // be refused as "open in another omp process" naming this very child.
+    try {
+      await rpc.start();
+      const entry = new SessionEntry(stored.cwd, rpc);
+      await entry.hydrate();
+      entry.id = id;
+      entry.onChange = (changed) => this.remember(changed);
+      entry.onBroadcast = (source, payload) => this.attention.observe(source, payload);
+      entry.bind();
+      this.sessions.set(id, entry);
+      this.remember(entry);
+      return entry;
+    } catch (error) {
+      rpc.close();
+      throw error;
+    }
   }
 
   async createSession(cwd) {
@@ -703,19 +758,21 @@ class Daemon {
       autoApprove: this.options.autoApprove,
       extraArgs: this.options.approvalMode ? ["--approval-mode", this.options.approvalMode] : [],
     });
-    await rpc.start();
-    const entry = new SessionEntry(cwd, rpc);
-    await entry.hydrate();
-    if (entry.id === "") {
+    try {
+      await rpc.start();
+      const entry = new SessionEntry(cwd, rpc);
+      await entry.hydrate();
+      if (entry.id === "") throw new Error("omp returned no session id");
+      entry.onChange = (changed) => this.remember(changed);
+      entry.onBroadcast = (source, payload) => this.attention.observe(source, payload);
+      entry.bind();
+      this.sessions.set(entry.id, entry);
+      this.remember(entry);
+      return entry;
+    } catch (error) {
       rpc.close();
-      throw new Error("omp returned no session id");
+      throw error;
     }
-    entry.onChange = (changed) => this.remember(changed);
-    entry.onBroadcast = (source, payload) => this.attention.observe(source, payload);
-    entry.bind();
-    this.sessions.set(entry.id, entry);
-    this.remember(entry);
-    return entry;
   }
 
   handleUpgrade(req, socket, head) {
@@ -745,10 +802,15 @@ class Daemon {
         });
       })
       .catch((error) => {
-        const status = typeof error?.status === "number" ? error.status : 404;
-        socket.write(`HTTP/1.1 ${status} ${STATUS_CODES[status] ?? "Error"}\r\n\r\n`);
-        socket.destroy();
-        this.log?.(error);
+        const status = typeof error?.status === "number" ? error.status : 500;
+        if (status >= 500) this.log(error);
+        // A browser-style client only sees that the upgrade failed, never why. Finish
+        // the handshake instead, say why the session cannot open, and close: the app
+        // shows the reason and stops retrying what a retry cannot fix.
+        this.wsServer.handleUpgrade(req, socket, head, (ws) => {
+          ws.send(JSON.stringify({ type: "open_failed", status, error: error instanceof Error ? error.message : String(error) }));
+          ws.close(OPEN_FAILED_CLOSE_CODE, "session did not open");
+        });
       });
   }
 
@@ -763,8 +825,10 @@ class Daemon {
     try {
       switch (message.type) {
         case "prompt": {
-          if (typeof message.text !== "string" || message.text.trim() === "") throw new Error("empty prompt");
-          await entry.rpc.prompt(message.text);
+          const images = promptImages(message.images);
+          const text = typeof message.text === "string" ? message.text : "";
+          if (text.trim() === "" && images.length === 0) throw new Error("empty prompt");
+          await entry.rpc.prompt(text, images);
           ws.send(JSON.stringify({ type: "accepted", command: "prompt" }));
           return;
         }
@@ -822,7 +886,14 @@ class Daemon {
           throw new Error(`unknown command ${String(message.type)}`);
       }
     } catch (error) {
-      ws.send(JSON.stringify({ type: "error", error: error instanceof Error ? error.message : String(error) }));
+      // `command` names the frame that failed, so the app can tell a refused prompt from any other error.
+      ws.send(
+        JSON.stringify({
+          type: "error",
+          command: typeof message?.type === "string" ? message.type : undefined,
+          error: error instanceof Error ? error.message : String(error),
+        }),
+      );
     }
   }