@aexol/spectral 0.9.211 → 0.9.215

package/dist/server/storage.js

@@ -34,6 +34,7 @@ import { mkdirSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { getConfigDir } from "../config.js";
 import { stripJsoncComments } from "../studio-binding.js";
+import { coerceImages, parseImagesJson } from "./image-attachments.js";
 /**
  * Schema version — informational, stamped into every new database.
  *
@@ -234,35 +235,6 @@ function applyBindingFields(project, rowBinding) {
         studioTeamId: binding.teamId,
     };
 }
-/** Tables we own — used by the migration drop step. */
-/** Best-effort parse of the `images_json` column into `ImageAttachment[]`. */
-function parseImagesJson(raw) {
-    if (!raw || raw === "")
-        return undefined;
-    try {
-        const parsed = JSON.parse(raw);
-        if (!Array.isArray(parsed))
-            return undefined;
-        const out = [];
-        for (const i of parsed) {
-            if (i !== null &&
-                typeof i === "object" &&
-                typeof i.data === "string" &&
-                typeof i.mimeType === "string") {
-                out.push({
-                    data: i.data,
-                    mimeType: i.mimeType,
-                    width: typeof i.width === "number" ? i.width : undefined,
-                    height: typeof i.height === "number" ? i.height : undefined,
-                });
-            }
-        }
-        return out.length > 0 ? out : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 export class SessionStore {
     path;
     db;
@@ -1182,7 +1154,14 @@ export class SessionStore {
         const createdAt = msg.createdAt ?? Date.now();
         const eventsJsonl = msg.eventsJsonl ?? "";
         const creditsUsed = msg.creditsUsed ?? null;
-        const imagesJson = msg.images && msg.images.length > 0 ? JSON.stringify(msg.images) : "";
+        // Last line of defence: never persist an attachment that carries neither
+        // a url nor data, and never persist megabytes of inline base64 — both
+        // would bloat the DB and the history replay. Ingress paths reject these
+        // earlier; here we only guarantee the invariant.
+        const storedImages = coerceImages(msg.images, {
+            onReject: (reason) => console.warn(`[spectral] warn: not persisting image for ${sessionId}: ${reason}`),
+        });
+        const imagesJson = storedImages && storedImages.length > 0 ? JSON.stringify(storedImages) : "";
         let sequence = 0;
         const tx = this.db.transaction(() => {
             // Idempotent sequence assignment. A rewrite of the same message id must
@@ -1203,7 +1182,7 @@ export class SessionStore {
             events: eventsJsonl,
             createdAt,
             sequence,
-            ...(msg.images && msg.images.length > 0 ? { images: msg.images } : {}),
+            ...(storedImages && storedImages.length > 0 ? { images: storedImages } : {}),
             ...(creditsUsed != null ? { creditsUsed } : {}),
         };
     }

package/dist/server/ui/terminal-confirm.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Terminal-native permission confirmations for `spectral serve`.
+ *
+ * In serve mode there is no TUI, but extensions (notably desktop-control)
+ * still call `ctx.ui.confirm(...)` to gate potentially harmful actions. The
+ * user is chatting via the web UI, while `spectral serve` itself runs in a
+ * real terminal — so the confirmation is rendered there, on serve's stdout,
+ * and answered with a single keypress.
+ *
+ * Behavior:
+ *  - Non-TTY stdin: resolves `false` immediately (honest headless deny).
+ *  - The prompt is a boxed render with a key legend: Enter/y = Allow,
+ *    n/Esc/q = Deny, Ctrl+C = Deny (consumed as data in raw mode — it must
+ *    never kill the serve process).
+ *  - Stdin is put into raw mode for the duration of the prompt and always
+ *    restored afterwards.
+ *  - Title and message are sanitized before rendering: ANSI escape sequences
+ *    and control characters are stripped (newlines collapse to spaces) so a
+ *    malicious extension cannot inject terminal escapes.
+ *  - Concurrent confirmations (multiple sessions share one terminal) are
+ *    serialized through a module-level queue; queued requests print a short
+ *    "waiting" notice.
+ *  - Timeouts: `SPECTRAL_CONFIRM_TIMEOUT_MS` env (default 5 min) or the
+ *    per-dialog `opts.timeout`. On timeout the confirmation resolves `false`.
+ *  - `onOutcome` reports how the dialog ended exactly once, letting callers
+ *    (e.g. desktop-control) distinguish an explicit user denial from
+ *    auto-deny causes (timeout, non-TTY, abort) that must not lock sessions.
+ *
+ * The prompt logic is pure and takes injectable IO (`write` + `readKey`) so
+ * tests run without a TTY.
+ */
+/** Injectable terminal IO for the confirmation prompt. */
+export interface ConfirmPromptIO {
+    /** Write text to the terminal (serve's stdout). */
+    write(text: string): void;
+    /**
+     * Start listening for the next keypress and pass raw stdin data to
+     * `handler`. Returns a cancel function that must detach the listener and
+     * restore any terminal state (raw mode).
+     */
+    readKey(handler: (data: string) => void): () => void;
+}
+/** Minimal shape of a stdin stream the default IO implementation needs. */
+export interface ConfirmStdin {
+    readonly isTTY?: boolean;
+    readonly isRaw?: boolean;
+    setRawMode?(mode: boolean): unknown;
+    on(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    off(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    resume(): unknown;
+}
+export type ConfirmKeyAction = "allow" | "deny" | "ignore";
+/**
+ * How a confirmation ended. `deny` is an explicit human decision (deny key);
+ * `timeout`, `no_tty` and `cancelled` mean the dialog ended without a user
+ * answer. Same values as `ExtensionConfirmOutcome`.
+ */
+export type TerminalConfirmOutcome = "allow" | "deny" | "timeout" | "no_tty" | "cancelled";
+/** Default confirmation timeout: 5 minutes. */
+export declare const DEFAULT_CONFIRM_TIMEOUT_MS = 300000;
+/**
+ * Classify a raw keypress. Only single-byte keys are acted on; multi-byte
+ * sequences (arrow keys, pastes) are ignored so they can't accidentally
+ * answer the prompt.
+ */
+export declare function classifyConfirmKey(data: string): ConfirmKeyAction;
+/**
+ * Strip ANSI escape sequences and control characters from extension-provided
+ * text. Newlines become spaces (the box renders one wrapped block); every
+ * other C0 control character (incl. \r and tab), DEL and C1 are removed, as
+ * is any stray ESC left over from an unterminated sequence. Keeps the prompt
+ * box and result lines safe against terminal escape injection.
+ */
+export declare function sanitizeConfirmText(text: string): string;
+/**
+ * Render the confirmation prompt as a boxed block of text (with trailing
+ * newline). Pure — no IO.
+ */
+export declare function renderConfirmBox(title: string, message: string): string;
+/** Read the confirmation timeout from the environment (ms). */
+export declare function parseConfirmTimeoutMs(env?: NodeJS.ProcessEnv): number;
+export interface TerminalConfirmOptions {
+    title: string;
+    message: string;
+    io: ConfirmPromptIO;
+    /** Whether stdin is an interactive TTY. Defaults to `process.stdin.isTTY`. */
+    isTTY?: boolean;
+    /** Timeout in ms. Defaults to `parseConfirmTimeoutMs()` (env-driven). */
+    timeoutMs?: number;
+    /** AbortSignal to programmatically deny the dialog. */
+    signal?: AbortSignal;
+    /** Called when the prompt is actually rendered (not while queued). */
+    onShown?: () => void;
+    /**
+     * Called exactly once with the final outcome, before the promise settles.
+     * `deny` means an explicit human denial; `timeout`/`no_tty`/`cancelled`
+     * are auto-deny causes (no user decision was made).
+     */
+    onOutcome?: (outcome: TerminalConfirmOutcome) => void;
+}
+/**
+ * Run a single terminal confirmation. Resolves `true` (allow) or `false`
+ * (deny / timeout / abort / non-TTY). Never throws.
+ */
+export declare function runTerminalConfirm(options: TerminalConfirmOptions): Promise<boolean>;
+/**
+ * Request a terminal confirmation, serialized with all other pending
+ * confirmations in this process. Queued requests print a short notice.
+ */
+export declare function requestTerminalConfirm(options: TerminalConfirmOptions): Promise<boolean>;
+/**
+ * Default IO bound to the serve process's real terminal: writes to stdout,
+ * reads raw keypresses from stdin (entering raw mode for the duration and
+ * restoring the previous mode on cancel).
+ */
+export declare function createStdinConfirmIO(stdin?: ConfirmStdin): ConfirmPromptIO;
+/** Wire event shape emitted when a confirm prompt is actually shown. */
+export interface BridgeConfirmNotifyEvent {
+    type: "agent_notification";
+    message: string;
+    level: "info" | "warning" | "error";
+}
+/** Per-dialog options as passed by extensions (`ExtensionUIDialogOptions`). */
+export interface BridgeConfirmDialogOptions {
+    /** AbortSignal to programmatically deny the dialog. */
+    signal?: AbortSignal;
+    /** Per-dialog timeout in ms (auto-deny when it fires). */
+    timeout?: number;
+    /** Outcome side-channel, forwarded to `runTerminalConfirm.onOutcome`. */
+    onOutcome?: (outcome: TerminalConfirmOutcome) => void;
+}
+/**
+ * Build the `confirm(title, message, opts?)` implementation used by the
+ * serve-mode headless UI context: routes through `requestTerminalConfirm`
+ * (cross-session queue), maps `opts.timeout` → `timeoutMs` and
+ * `opts.signal` → `signal`, forwards `opts.onOutcome` (auto-deny vs explicit
+ * user denial side-channel), and emits an `agent_notification` (level
+ * "warning") once the prompt is rendered so web users know to look at the
+ * terminal. `io` defaults to the real stdin IO; `isTTY` overrides the TTY
+ * probe (defaults to `process.stdin.isTTY`, i.e. headless-safe).
+ */
+export declare function createBridgeConfirm(emit: (event: BridgeConfirmNotifyEvent) => void, io?: ConfirmPromptIO, opts?: {
+    isTTY?: boolean;
+}): (title: string, message: string, dialog?: BridgeConfirmDialogOptions) => Promise<boolean>;
+//# sourceMappingURL=terminal-confirm.d.ts.map

package/dist/server/ui/terminal-confirm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-confirm.d.ts","sourceRoot":"","sources":["../../../src/server/ui/terminal-confirm.ts"],"names":[],"mappings":"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"}

package/dist/server/ui/terminal-confirm.js

@@ -0,0 +1,333 @@
+/**
+ * Terminal-native permission confirmations for `spectral serve`.
+ *
+ * In serve mode there is no TUI, but extensions (notably desktop-control)
+ * still call `ctx.ui.confirm(...)` to gate potentially harmful actions. The
+ * user is chatting via the web UI, while `spectral serve` itself runs in a
+ * real terminal — so the confirmation is rendered there, on serve's stdout,
+ * and answered with a single keypress.
+ *
+ * Behavior:
+ *  - Non-TTY stdin: resolves `false` immediately (honest headless deny).
+ *  - The prompt is a boxed render with a key legend: Enter/y = Allow,
+ *    n/Esc/q = Deny, Ctrl+C = Deny (consumed as data in raw mode — it must
+ *    never kill the serve process).
+ *  - Stdin is put into raw mode for the duration of the prompt and always
+ *    restored afterwards.
+ *  - Title and message are sanitized before rendering: ANSI escape sequences
+ *    and control characters are stripped (newlines collapse to spaces) so a
+ *    malicious extension cannot inject terminal escapes.
+ *  - Concurrent confirmations (multiple sessions share one terminal) are
+ *    serialized through a module-level queue; queued requests print a short
+ *    "waiting" notice.
+ *  - Timeouts: `SPECTRAL_CONFIRM_TIMEOUT_MS` env (default 5 min) or the
+ *    per-dialog `opts.timeout`. On timeout the confirmation resolves `false`.
+ *  - `onOutcome` reports how the dialog ended exactly once, letting callers
+ *    (e.g. desktop-control) distinguish an explicit user denial from
+ *    auto-deny causes (timeout, non-TTY, abort) that must not lock sessions.
+ *
+ * The prompt logic is pure and takes injectable IO (`write` + `readKey`) so
+ * tests run without a TTY.
+ */
+/** Default confirmation timeout: 5 minutes. */
+export const DEFAULT_CONFIRM_TIMEOUT_MS = 300_000;
+/**
+ * Classify a raw keypress. Only single-byte keys are acted on; multi-byte
+ * sequences (arrow keys, pastes) are ignored so they can't accidentally
+ * answer the prompt.
+ */
+export function classifyConfirmKey(data) {
+    if (data.length !== 1)
+        return "ignore";
+    if (data === "\r" || data === "\n" || data === "y" || data === "Y") {
+        return "allow";
+    }
+    if (data === "n" ||
+        data === "N" ||
+        data === "q" ||
+        data === "Q" ||
+        data === "\x1b" /* Esc */ ||
+        data === "\x03" /* Ctrl+C */) {
+        return "deny";
+    }
+    return "ignore";
+}
+const BOX_MAX_WIDTH = 72;
+/**
+ * Complete ANSI escape sequences: CSI (…final byte), OSC (BEL- or ST-
+ * terminated) and generic two-byte ESC sequences (e.g. ESC c = reset).
+ * CSI/OSC are tried first so their full payload is consumed.
+ */
+const ANSI_ESCAPE_RE = /\x1b(?:\[[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-~])/g;
+/**
+ * Strip ANSI escape sequences and control characters from extension-provided
+ * text. Newlines become spaces (the box renders one wrapped block); every
+ * other C0 control character (incl. \r and tab), DEL and C1 are removed, as
+ * is any stray ESC left over from an unterminated sequence. Keeps the prompt
+ * box and result lines safe against terminal escape injection.
+ */
+export function sanitizeConfirmText(text) {
+    return text
+        .replace(ANSI_ESCAPE_RE, "")
+        .replace(/\x1b/g, "")
+        .replace(/\n/g, " ")
+        .replace(/[\x00-\x09\x0b-\x1f\x7f-\x9f]/g, "");
+}
+/** Greedy word-wrap for a single line, fitting `width` columns. */
+function wrapLine(line, width) {
+    if (line.length <= width)
+        return [line];
+    const words = line.split(" ");
+    const out = [];
+    let current = "";
+    for (const word of words) {
+        if (current.length === 0) {
+            current = word.slice(0, width);
+        }
+        else if (current.length + 1 + word.length <= width) {
+            current += ` ${word}`;
+        }
+        else {
+            out.push(current);
+            current = word.slice(0, width);
+        }
+    }
+    if (current.length > 0)
+        out.push(current);
+    return out.length > 0 ? out : [""];
+}
+/**
+ * Render the confirmation prompt as a boxed block of text (with trailing
+ * newline). Pure — no IO.
+ */
+export function renderConfirmBox(title, message) {
+    const cleanTitle = sanitizeConfirmText(title);
+    const cleanMessage = sanitizeConfirmText(message);
+    const legend = "Enter/y = Allow   n/Esc/q = Deny   Ctrl+C = Deny";
+    const header = `⚠ Confirmation required · ${cleanTitle}`;
+    const innerWidth = Math.min(BOX_MAX_WIDTH, Math.max(header.length, legend.length, 40));
+    const lines = [header, ""];
+    for (const raw of cleanMessage.split(/\r?\n/)) {
+        lines.push(...wrapLine(raw, innerWidth));
+    }
+    lines.push("", legend);
+    const pad = (line) => line + " ".repeat(Math.max(0, innerWidth - line.length));
+    const border = "─".repeat(innerWidth + 2);
+    const body = lines.map((line) => `│ ${pad(line)} │`).join("\n");
+    return `┌${border}┐\n${body}\n└${border}┘\n`;
+}
+/** Read the confirmation timeout from the environment (ms). */
+export function parseConfirmTimeoutMs(env = process.env) {
+    const raw = env.SPECTRAL_CONFIRM_TIMEOUT_MS;
+    if (raw === undefined || raw === "")
+        return DEFAULT_CONFIRM_TIMEOUT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return DEFAULT_CONFIRM_TIMEOUT_MS;
+    }
+    return parsed;
+}
+/**
+ * Run a single terminal confirmation. Resolves `true` (allow) or `false`
+ * (deny / timeout / abort / non-TTY). Never throws.
+ */
+export async function runTerminalConfirm(options) {
+    const { title, message, io } = options;
+    const isTTY = options.isTTY ?? process.stdin.isTTY === true;
+    if (!isTTY) {
+        options.onOutcome?.("no_tty");
+        return false;
+    }
+    if (options.signal?.aborted) {
+        options.onOutcome?.("cancelled");
+        return false;
+    }
+    // Fail-closed: a broken terminal must deny the request instead of throwing
+    // (callers and the cross-session queue rely on this resolving).
+    try {
+        io.write(renderConfirmBox(title, message));
+    }
+    catch {
+        return false;
+    }
+    try {
+        options.onShown?.();
+    }
+    catch {
+        /* onShown is a side-channel (e.g. wire emit) — never block the prompt. */
+    }
+    const safeTitle = sanitizeConfirmText(title);
+    return await new Promise((resolve) => {
+        let settled = false;
+        let cancelRead;
+        const timeoutMs = options.timeoutMs ?? parseConfirmTimeoutMs();
+        const finish = (result, notice, outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+            cancelRead?.();
+            options.onOutcome?.(outcome ?? (result ? "allow" : "deny"));
+            try {
+                if (notice)
+                    io.write(`${notice}\n`);
+                io.write(result ? `✓ Allowed: ${safeTitle}\n\n` : `✗ Denied: ${safeTitle}\n\n`);
+            }
+            catch {
+                /* terminal may be gone — the promise must still settle */
+            }
+            resolve(result);
+        };
+        const onKey = (data) => {
+            const action = classifyConfirmKey(data);
+            if (action === "allow")
+                finish(true);
+            else if (action === "deny")
+                finish(false);
+            // "ignore": keep waiting for a meaningful key.
+        };
+        const onAbort = () => finish(false, "Confirmation aborted — denied.", "cancelled");
+        const timer = setTimeout(() => {
+            finish(false, `⏰ Confirmation timed out after ${timeoutMs}ms — denied by default.`, "timeout");
+        }, timeoutMs);
+        // A pending confirmation must not keep the serve process alive on its own.
+        if (typeof timer.unref === "function") {
+            timer.unref();
+        }
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            cancelRead = io.readKey(onKey);
+        }
+        catch {
+            // Could not attach a key listener: deny now instead of hanging until
+            // the timeout with no way for the user to answer.
+            finish(false, undefined, "cancelled");
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Cross-session serialization
+//
+// All sessions in one serve process share a single terminal, so confirmations
+// are queued behind each other at the module level.
+// ---------------------------------------------------------------------------
+let queueTail = Promise.resolve();
+let pendingConfirmations = 0;
+const QUEUED_NOTICE = "⏳ Another confirmation is pending in the terminal — request queued.\n";
+/**
+ * Request a terminal confirmation, serialized with all other pending
+ * confirmations in this process. Queued requests print a short notice.
+ */
+export function requestTerminalConfirm(options) {
+    const position = pendingConfirmations;
+    pendingConfirmations++;
+    // `run` is always chained onto the queue before any side-effectful work
+    // (like the queued notice), so a throwing write can never leave the
+    // counter inflated. It never rejects: fail-closed deny.
+    const run = async () => {
+        try {
+            return await runTerminalConfirm(options);
+        }
+        catch {
+            return false;
+        }
+        finally {
+            pendingConfirmations--;
+        }
+    };
+    const result = queueTail.then(run, run);
+    queueTail = result.then(() => undefined, () => undefined);
+    if (position > 0) {
+        try {
+            options.io.write(QUEUED_NOTICE);
+        }
+        catch {
+            /* cosmetic notice — the queued confirm still runs */
+        }
+    }
+    return result;
+}
+/**
+ * Default IO bound to the serve process's real terminal: writes to stdout,
+ * reads raw keypresses from stdin (entering raw mode for the duration and
+ * restoring the previous mode on cancel).
+ */
+export function createStdinConfirmIO(stdin = process.stdin) {
+    return {
+        write: (text) => {
+            process.stdout.write(text);
+        },
+        readKey(handler) {
+            const wasRaw = stdin.isRaw === true;
+            if (stdin.isTTY && typeof stdin.setRawMode === "function") {
+                try {
+                    stdin.setRawMode(true);
+                }
+                catch {
+                    // Raw mode is what turns Ctrl+C into a plain deny key instead of
+                    // SIGINT. Without it the "Ctrl+C = Deny" legend is a lie — say so.
+                    process.stderr.write("⚠ Terminal confirm: could not enable raw mode — Ctrl+C may terminate the process instead of denying.\n");
+                }
+            }
+            const onData = (chunk) => {
+                handler(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+            };
+            const cancel = () => {
+                stdin.off("data", onData);
+                if (stdin.isTTY && typeof stdin.setRawMode === "function") {
+                    try {
+                        stdin.setRawMode(wasRaw);
+                    }
+                    catch {
+                        /* best-effort restore */
+                    }
+                }
+            };
+            try {
+                stdin.on("data", onData);
+                stdin.resume();
+            }
+            catch {
+                // Attach/resume failed (e.g. stdin closed mid-flight): detach the
+                // listener and restore raw mode right away, but still hand back the
+                // cancel function so callers can never leak.
+                cancel();
+            }
+            return cancel;
+        },
+    };
+}
+/**
+ * Build the `confirm(title, message, opts?)` implementation used by the
+ * serve-mode headless UI context: routes through `requestTerminalConfirm`
+ * (cross-session queue), maps `opts.timeout` → `timeoutMs` and
+ * `opts.signal` → `signal`, forwards `opts.onOutcome` (auto-deny vs explicit
+ * user denial side-channel), and emits an `agent_notification` (level
+ * "warning") once the prompt is rendered so web users know to look at the
+ * terminal. `io` defaults to the real stdin IO; `isTTY` overrides the TTY
+ * probe (defaults to `process.stdin.isTTY`, i.e. headless-safe).
+ */
+export function createBridgeConfirm(emit, io = createStdinConfirmIO(), opts) {
+    return (title, message, dialog) => requestTerminalConfirm({
+        title,
+        message,
+        io,
+        isTTY: opts?.isTTY,
+        timeoutMs: dialog?.timeout,
+        signal: dialog?.signal,
+        onOutcome: dialog?.onOutcome,
+        onShown: () => {
+            try {
+                emit({
+                    type: "agent_notification",
+                    message: `Approval required in terminal: ${title}`,
+                    level: "warning",
+                });
+            }
+            catch {
+                /* best-effort — the prompt must still be shown */
+            }
+        },
+    });
+}

package/dist/server/wire.d.ts

@@ -9,10 +9,35 @@
  * Naming: client → server messages are `ClientMessage`, server → client
  * frames are `ServerEvent`. JSON-encoded one-per-frame on the wire.
  */
-/** Base64-encoded image attached to a user message. */
+/**
+ * Image attached to a user message.
+ *
+ * Two carriers, in order of preference:
+ *
+ * 1. `url` — the image was uploaded to backend storage (S3) and only the
+ *    pointer travels over the relay. **Preferred**: a screenshot is worth
+ *    megabytes of base64, a url is ~40 characters.
+ * 2. `data` — inline base64 (no data URI prefix). Kept for backward
+ *    compatibility with small/legacy attachments; rejected above
+ *    `MAX_INLINE_IMAGE_BASE64_CHARS` (measured on the base64 string, i.e.
+ *    on the wire payload) so the relay never carries megabytes.
+ *
+ * At least one of `data` / `url` must be present.
+ */
 export interface ImageAttachment {
-    /** Raw base64 image data (no data URI prefix). */
-    data: string;
+    /**
+     * Raw base64 image data (no data URI prefix). Legacy/small images only —
+     * hard-capped at `MAX_INLINE_IMAGE_BASE64_CHARS` (768 KiB of base64) at
+     * the wire boundary.
+     */
+    data?: string;
+    /**
+     * Hosted image url: backend-relative (`/generated-images/<id>`) or
+     * absolute. Preferred over `data` — when both are set the url wins.
+     */
+    url?: string;
+    /** Backend image id, when the attachment came from `uploadImage()`. */
+    imageId?: string;
     /** MIME type, e.g. "image/jpeg" or "image/png". */
     mimeType: string;
     /** Compressed width in pixels (optional). */
@@ -30,7 +55,7 @@ export interface WireMessage {
     createdAt: number;
     /** Stable per-session insertion sequence used for server-authoritative ordering. */
     sequence?: number;
-    /** Base64 images attached to user messages (empty for assistant/system). */
+    /** Image attachments on user messages (hosted `url` or inline base64; empty for assistant/system). */
     images?: ImageAttachment[];
     /** Credits consumed by this message, persisted independently of the events blob (assistant only). */
     creditsUsed?: number | null;
@@ -285,7 +310,7 @@ export type ClientMessage = {
     content: string;
     /** Enable autonomous iterative loop for this message (Ralph Wiggum pattern). */
     loop?: boolean;
-    /** Optional base64-encoded images attached to the message. */
+    /** Optional image attachments (hosted `url` preferred, inline base64 legacy). */
     images?: ImageAttachment[];
     /** Optional loop max iterations (server caps at MAX_LOOP_ITERATIONS). */
     loopMaxIterations?: number;