@bivy/bivy 0.5.1-staging.75 → 0.5.1-staging.77

package/dist/auth.js

@@ -164,8 +164,13 @@ export function isAuthorized(ctx) {
  * local/private hostnames and reject a public Host (rebinding) or public Origin
  * (cross-site). Escape hatches: BIVY_ALLOWED_HOSTS (comma-separated extra
  * hostnames, e.g. a reverse-proxy domain) and BIVY_ALLOW_ANY_ORIGIN=1.
+ *
+ * Exported: also reused as the private/local-address check for the inline
+ * markdown-image SSRF guard (src/session/inline-image-fetch.ts) — same
+ * "must not be a private/loopback/link-local address" question, just asked
+ * about an *outbound* fetch target instead of an *inbound* request's Host.
  */
-function hostnameIsLocal(hostname) {
+export function hostnameIsLocal(hostname) {
     const h = hostname.toLowerCase().replace(/^\[/, "").replace(/\]$/, "").replace(/^::ffff:/, "");
     if (h === "localhost" || h === "127.0.0.1" || h === "::1" || h === "0.0.0.0")
         return true;

package/dist/runtime/anthropic-preflight.js

@@ -15,6 +15,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { isModelAuthError } from "./auth-errors.js";
 /** Candidate paths for the `claude` CLI's own stored login (`.credentials.json`). */
 export function claudeCredentialFiles(deps = {}) {
     const home = deps.home ?? os.homedir();
@@ -68,7 +69,7 @@ export function anthropicCredentialPreflight(env, deps = {}) {
 }
 /** True when a raw error string looks like an Anthropic auth failure (401 etc.). */
 export function isAnthropicAuthError(raw) {
-    return /\b401\b|unauthorized|authentication|invalid x-api-key|(missing|invalid).*(bearer|api[\s_-]?key|token)/i.test(raw);
+    return isModelAuthError(raw);
 }
 /**
  * Phrase an SDK error for the user: an auth failure gets the sign-in guidance

package/dist/runtime/auth-errors.js

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Classify model auth failures and map a failing session to the provider the
+// user needs to (re)authenticate.
+//
+// When a runtime has no usable model credential — or a present-but-expired one —
+// its first upstream request fails with a 401. Codex surfaces this as
+// `failed to connect to websocket: HTTP error: 401 Unauthorized, url:
+// wss://api.openai.com/v1/responses`; Anthropic as `401 Unauthorized`; others
+// similarly. Rather than let that stream past as a raw error, the daemon runs
+// `isModelAuthError` over surfaced errors and, when one matches, broadcasts a
+// `session.auth_required` targeted at `authProviderForSession(...)` so the client
+// can pop the "Sign in to your model" sheet for the right provider.
+import { MODEL_OAUTH_PROVIDERS } from "./oauth/model-oauth-providers.js";
+/**
+ * True when a raw error string looks like a model auth failure (401 / missing
+ * bearer / invalid key). Covers both the generic SDK phrasing and Codex's
+ * websocket-connect form.
+ */
+export function isModelAuthError(raw) {
+    const text = String(raw || "");
+    // Generic: an explicit 401, "unauthorized"/"authentication", or a
+    // missing/invalid bearer/api-key/token phrase.
+    if (/\b401\b|unauthorized|authentication|invalid x-api-key|(missing|invalid)[\s\S]*(bearer|api[\s_-]?key|token)/i.test(text))
+        return true;
+    // Codex app-server: websocket connect rejected with an HTTP 401/403.
+    if (/failed to connect to websocket[\s\S]*http error:\s*40[13]/i.test(text))
+        return true;
+    return false;
+}
+// Provider ids the app knows how to authenticate (OAuth subscription providers
+// plus any provider that has a conventional API-key env var). Used to validate
+// a model provider before signalling the client to sign in for it.
+const KNOWN_KEY_PROVIDERS = new Set([
+    "anthropic",
+    "openai",
+    "openrouter",
+    "google",
+    "gemini",
+    "groq",
+    "mistral",
+    "deepseek",
+    "xai",
+    "together",
+    "fireworks",
+    "cohere",
+    "perplexity",
+]);
+/**
+ * Resolve which credential provider the user should sign in for, given the
+ * failing runtime id and (optionally) its active model provider. Returns
+ * undefined when we can't confidently name a provider — in that case the caller
+ * should not raise the sign-in sheet.
+ *
+ * Codex runtimes (`codex`, `codex-approvals`) are served by the ChatGPT
+ * subscription, whose vault/provider id is `openai-codex`; that's the id the
+ * "Sign in with OpenAI" OAuth button targets.
+ */
+export function authProviderForSession(runtimeId, modelProvider) {
+    const id = String(runtimeId || "").trim().toLowerCase();
+    if (id.startsWith("codex"))
+        return "openai-codex";
+    const provider = String(modelProvider || "").trim().toLowerCase();
+    if (!provider)
+        return undefined;
+    if (Object.prototype.hasOwnProperty.call(MODEL_OAUTH_PROVIDERS, provider))
+        return provider;
+    if (KNOWN_KEY_PROVIDERS.has(provider))
+        return provider;
+    return undefined;
+}

package/dist/runtime/claude-code.js

@@ -66,14 +66,23 @@ const FALLBACK_MODELS = [
  * it can't (it looks for a tool, finds none). BIVY_SESSION_ID is injected into the
  * subprocess env (see spawnQuery), so the bare command resolves the session. Keep
  * this short: it rides on every turn's system prompt.
+ *
+ * The chat still has no route to a LOCAL/workspace file path, so that half of the
+ * guidance (use `bivy attach`, not markdown, for those) stands. A REMOTE
+ * `https://` image URL is different: the node now fetches it server-side and
+ * serves it back to the chat (see src/session/inline-image-fetch.ts, issue #293),
+ * so plain markdown is the right tool there — `bivy attach` only works on files
+ * already inside the workspace, which a URL by definition isn't.
  */
 export const BIVY_ATTACH_SYSTEM_PROMPT = "Sending files and images to the user: the person you're talking to is in a chat UI. They cannot see files you only " +
-    "write to disk, and the chat cannot load remote image URLs or workspace file paths. " +
-    "To show them a file or image — a report, screenshot, chart, or a file they asked for — run " +
+    "write to disk, and the chat has no route to a workspace file path. " +
+    "To show them a LOCAL file or image — a report, screenshot, chart, or a file they asked for — run " +
     '`bivy attach <path> [--caption "short note"]` in your shell. ' +
     "An image renders inline in the chat; any other file shows as a downloadable chip. The path must be inside the session " +
-    "workspace. Do NOT use markdown image syntax like ![](path) to show a local file or a URL — it will not render; always " +
-    "use `bivy attach`. Prefer this over pasting large file contents or describing where a file lives on disk.";
+    "workspace. Do NOT use markdown image syntax like ![](path) for a local file or workspace path — it will not render; " +
+    "always use `bivy attach` for those. A REMOTE image you already have a URL for is different: plain markdown " +
+    "`![alt](https://...)` renders it inline, no attach needed. Prefer `bivy attach` / markdown links over pasting large " +
+    "file contents or describing where a file lives on disk.";
 /** Name of the in-process MCP server the native attach tool is registered
  *  under (see buildAttachMcpServer) — the SDK namespaces the tool the agent
  *  sees as `mcp__<server>__<tool>`. */

package/dist/runtime/index.js

@@ -1071,6 +1071,16 @@ function codexAppServerRuntime(credsDir, tier) {
         args: [shim],
         ...(policy ? { env: { BIVY_CODEX_SANDBOX: policy.sandbox, BIVY_CODEX_APPROVAL_POLICY: policy.approvalPolicy } } : {}),
         credentials: createCredentialStore(credsDir),
+        // Mint ~/.codex/auth.json from the vault before the app-server spawns, then
+        // preflight — mirroring the `codex` exec path (see below). Without this the
+        // shim would launch uncredentialed and 401 on its first /responses call with
+        // no actionable message. `prepare` runs pre-spawn (the shim reads auth.json at
+        // launch); `preflight` backstops the genuinely uncredentialed case.
+        prepare: async () => {
+            const home = await ensureCodexAuth(credsDir);
+            return home ? { CODEX_HOME: home } : {};
+        },
+        preflight: (env) => codexCredentialPreflight(env),
         // Session-less catalog contribution: Codex runs OpenAI models under a ChatGPT
         // subscription (provider id "openai-codex"). The authoritative per-session
         // list comes from the app-server; this is the picker preview.

package/dist/runtime/oauth/model-oauth-providers.js

@@ -43,7 +43,9 @@ export const MODEL_OAUTH_PROVIDERS = {
             codex_cli_simplified_flow: "true",
             originator: "pi",
         },
-        refreshSkewMs: 0,
+        // Refresh a little early (like Anthropic/xAI) so Codex never bakes an
+        // already-expired access token into ~/.codex/auth.json and 401s mid-turn.
+        refreshSkewMs: 5 * 60 * 1000,
         refreshRotates: true,
         accountIdClaim: { path: "https://api.openai.com/auth", field: "chatgpt_account_id" },
     },

package/dist/runtime/protocol.js

@@ -212,6 +212,9 @@ class ProtocolSession {
     currentModelId;
     /** Provider of the selected model — scopes custom base-URL env injection. */
     currentModelProvider;
+    /** Env patch from the last `prepare` run (e.g. Codex's minted CODEX_HOME),
+     *  applied to the spawned child and reused by the per-turn preflight. */
+    prepareEnv = {};
     getModels() { return this.models; }
     getCurrentModel() {
         if (!this.currentModelId)
@@ -257,12 +260,19 @@ class ProtocolSession {
         const credentialEnv = this.runtimeOptions.credentials
             ? await buildAgentCredentialEnv(this.runtimeOptions.credentials, undefined, this.currentModelProvider).catch(() => ({}))
             : {};
+        // Optional prepare step, run before the child spawns because a shim reads its
+        // credential at launch (e.g. Codex mints ~/.codex/auth.json from the vault and
+        // pins CODEX_HOME). Stored so the per-turn preflight sees the same env. Best-
+        // effort: a throw is swallowed and treated as no patch.
+        this.prepareEnv = this.runtimeOptions.prepare
+            ? (await Promise.resolve(this.runtimeOptions.prepare({ ...process.env, ...this.runtimeOptions.env, ...credentialEnv })).catch(() => undefined)) ?? {}
+            : {};
         const child = spawn(this.runtimeOptions.command, this.runtimeOptions.args ?? [], {
             cwd: this.cwd,
             // bivySessionEnv() lets the agent's own shell resolve its session for
             // `bivy attach <path>` (see session-env.ts); spread last so it can never
             // be shadowed by an operator-configured env var of the same name.
-            env: { ...process.env, ...this.runtimeOptions.env, ...credentialEnv, ...bivySessionEnv(this.id) },
+            env: { ...process.env, ...this.runtimeOptions.env, ...credentialEnv, ...this.prepareEnv, ...bivySessionEnv(this.id) },
             stdio: "pipe",
         });
         this.child = child;
@@ -503,6 +513,38 @@ class ProtocolSession {
     async prompt(text, options) {
         const wasStarted = this.started;
         await this.open();
+        // Per-turn prepare + credential preflight, mirroring ProcessRuntime. Unlike a
+        // fresh-process runtime, the protocol child is long-lived, so a credential
+        // connected AFTER it spawned (a mid-session sign-in from the "Sign in to your
+        // model" sheet) would never be materialized by start()'s one-shot prepare.
+        // Re-run prepare here so e.g. Codex mints ~/.codex/auth.json from the just-
+        // completed sign-in before this turn — the app-server reads the default auth
+        // file, so it recovers on the next prompt instead of staying stuck on the
+        // initial 401. Then preflight backstops the genuinely uncredentialed case with
+        // an actionable error instead of an opaque upstream 401. ensureCodexAuth is
+        // idempotent (it no-ops once auth.json exists), so the repeat is cheap.
+        if (this.runtimeOptions.prepare || this.runtimeOptions.preflight) {
+            const credentialEnv = this.runtimeOptions.credentials
+                ? await buildAgentCredentialEnv(this.runtimeOptions.credentials, undefined, this.currentModelProvider).catch(() => ({}))
+                : {};
+            if (this.runtimeOptions.prepare) {
+                this.prepareEnv =
+                    (await Promise.resolve(this.runtimeOptions.prepare({ ...process.env, ...this.runtimeOptions.env, ...credentialEnv })).catch(() => undefined)) ??
+                        this.prepareEnv;
+            }
+            const preflightError = this.runtimeOptions.preflight?.({ ...process.env, ...this.runtimeOptions.env, ...credentialEnv, ...this.prepareEnv }, { provider: this.currentModelProvider });
+            if (preflightError) {
+                this.streaming = false;
+                const message = { role: "assistant", content: "", errorMessage: preflightError };
+                this.messages.push(message);
+                this.emit({ type: "message_start", message: { role: "assistant", content: "" } });
+                this.emit({ type: "session.error", error: preflightError });
+                this.emit({ type: "message_end", message });
+                this.emit({ type: "turn_end" });
+                this.emit({ type: "agent_end", code: 1, signal: null });
+                return;
+            }
+        }
         if (!wasStarted)
             this.emit({ type: "agent_start" });
         const prompt = text.trim();

package/dist/server.js

@@ -22,6 +22,7 @@ import { InMemoryLocationRegistry } from "./runtime/location-registry.js";
 import { ControlPlaneSessionLocationRegistry, LayeredSessionLocationRegistry } from "./runtime/control-plane-location.js";
 import { attachAdoptedSessions, classifyAttachFailure } from "./runtime/adoption.js";
 import { createCredentialStore } from "./runtime/credentials.js";
+import { isModelAuthError, authProviderForSession } from "./runtime/auth-errors.js";
 import { createCredentialVault, migrateVaultDir } from "./runtime/credential-store.js";
 import { provisionAgentRun } from "./runtime/credential-provisioning.js";
 import { ingestAgentCredentials } from "./runtime/credential-ingest.js";
@@ -74,6 +75,7 @@ import { buildNativeImportSeedPrompt } from "./session/native-import.js";
 import { EventLog } from "./session/event-log.js";
 import { AttachmentStore, isValidAttachmentHash } from "./session/attachment-store.js";
 import { planAttachment, isAttachPlanError, MAX_AGENT_ATTACHMENT_BYTES } from "./session/attach-to-chat.js";
+import { extractInlineImageUrls, assistantTextForImageScan, fetchInlineImage, isFetchImageError, inlineImageDisplayName, } from "./session/inline-image-fetch.js";
 import { ReplicationService } from "./session/replication-service.js";
 import { createSessionNewDedupe } from "./session/session-new-dedupe.js";
 import { evaluateForkPrereqs, blockingForkPrereqs, missingForkPrereqs } from "./session/fork-prereqs.js";
@@ -2322,6 +2324,70 @@ function persistTranscriptSnapshot(record) {
         return;
     eventLog.appendBaseSnapshot(record.id, base);
 }
+// In-flight dedupe so two sessions (or two turns) referencing the same remote
+// image URL only ever trigger one outbound fetch. Process-lifetime only — a
+// restart just means the first re-encounter fetches again, which is fine.
+const inlineImageFetchInFlight = new Map();
+// A URL that failed (bad host, timeout, not-an-image, …) is not retried for a
+// cooldown window, so a persistently broken URL in a long-lived session can't
+// turn every subsequent message_end into a wasted fetch attempt.
+const inlineImageFailedAt = new Map();
+const INLINE_IMAGE_RETRY_COOLDOWN_MS = 10 * 60 * 1000;
+/**
+ * Scan a session's just-finalized assistant messages for remote markdown images
+ * (`![alt](https://…)`) and, for any URL not already resolved or in flight,
+ * fetch it (SSRF-guarded, size-capped — see inline-image-fetch.ts), store the
+ * bytes in the content-addressed AttachmentStore, persist the durable url→ref
+ * mapping, and broadcast it live so an already-open chat hydrates the image
+ * without waiting for a reload. Fire-and-forget: called from the session event
+ * listener, which must not block on a network fetch.
+ */
+function resolveInlineImages(record) {
+    const messages = record.session.getMessages();
+    const urls = new Set();
+    for (const m of messages) {
+        if (m.role !== "assistant")
+            continue;
+        for (const url of extractInlineImageUrls(assistantTextForImageScan(m.content)))
+            urls.add(url);
+    }
+    if (!urls.size)
+        return;
+    const alreadyResolved = new Set(eventLog.readInlineImages(record.id).map(([url]) => url));
+    for (const url of urls) {
+        if (alreadyResolved.has(url) || inlineImageFetchInFlight.has(url))
+            continue;
+        const failedAt = inlineImageFailedAt.get(url);
+        if (failedAt !== undefined && Date.now() - failedAt < INLINE_IMAGE_RETRY_COOLDOWN_MS)
+            continue;
+        const task = (async () => {
+            try {
+                const result = await fetchInlineImage(url);
+                if (isFetchImageError(result)) {
+                    console.warn(`[inline-image] ${url}: ${result.error}`);
+                    inlineImageFailedAt.set(url, Date.now());
+                    return;
+                }
+                const ref = attachmentStore.put(result.bytes, {
+                    name: inlineImageDisplayName(url, result.mimeType),
+                    mimeType: result.mimeType,
+                    kind: "image",
+                });
+                eventLog.appendInlineImage(record.id, { url, ref });
+                eventLog.flush(record.id);
+                broadcast({ type: "session.event", sessionId: record.id, event: { type: "inlineImage", url, ref } });
+            }
+            catch (error) {
+                console.warn(`[inline-image] ${url}:`, error instanceof Error ? error.message : String(error));
+                inlineImageFailedAt.set(url, Date.now());
+            }
+            finally {
+                inlineImageFetchInFlight.delete(url);
+            }
+        })();
+        inlineImageFetchInFlight.set(url, task);
+    }
+}
 // Append the tool-activity entry to the log. The id-merge and last-500 cap the old
 // store applied are now applied by `foldTool` on replay.
 function upsertToolActivityMessage(sessionId, entry) {
@@ -2445,6 +2511,11 @@ function buildHistoryEvent(opts) {
         // Durable attachment references (text→refs), so a client that never sent the
         // attachment (a reload, or a different device) rehydrates thumbnails by hash.
         attachmentRefs: opts.sessionId ? eventLog.readAttachments(opts.sessionId) : [],
+        // Durable url→ref map for remote markdown images the node has already
+        // fetched (see resolveInlineImages) — lets a reload resolve a
+        // `data-remote-src` placeholder straight to its attachment hash instead of
+        // waiting on a fresh (redundant) fetch.
+        inlineImageRefs: opts.sessionId ? eventLog.readInlineImages(opts.sessionId) : [],
     };
 }
 // Idempotency for `session.new` keyed by requestId: a client's post-reconnect
@@ -6724,6 +6795,24 @@ function terminalTurnError(event) {
     }
     return undefined;
 }
+/**
+ * When a surfaced error looks like a model auth failure (no credential, or an
+ * expired/invalid one that 401'd upstream), tell the client which provider to
+ * (re)authenticate so it can pop the "Sign in to your model" sheet instead of
+ * leaving a bare error bubble. Fires at most once per turn (reset on turn_start)
+ * so a retry storm — e.g. Codex's repeated websocket 401s — raises the sheet once.
+ */
+function maybeSignalAuthRequired(record, errorText) {
+    if (record.authRequiredSignaled)
+        return;
+    if (!isModelAuthError(errorText))
+        return;
+    const provider = authProviderForSession(record.runtimeId, record.session.getCurrentModel()?.provider);
+    if (!provider)
+        return;
+    record.authRequiredSignaled = true;
+    broadcast({ type: "session.auth_required", sessionId: record.id, provider, reason: errorText.slice(0, 400) });
+}
 function attachSessionListeners(record) {
     record.unsubscribe?.();
     // In-session model reroute controller (inert unless BIVY_SESSION_MODEL_FALLBACK
@@ -6773,6 +6862,10 @@ function attachSessionListeners(record) {
         ].includes(event.type)) {
             markSessionWorking(record, event);
         }
+        // A fresh turn re-arms the once-per-turn auth-required signal, so a credential
+        // that was fixed (or newly broke) is re-evaluated on the next prompt.
+        if (event.type === "turn_start")
+            record.authRequiredSignaled = false;
         if (event.type === "message_update" && event.message && (event.message?.role === "assistant")) {
             persistIntermediateFromEvent(record, event, false);
         }
@@ -6786,6 +6879,15 @@ function attachSessionListeners(record) {
         if (event.type === "turn_start" || event.type === "message_end" || event.type === "turn_end") {
             persistTranscriptSnapshot(record);
         }
+        // A finalized assistant message may reference a remote image via markdown
+        // (`![alt](https://…)`) — fetch and store it now so the chat can render it
+        // (see resolveInlineImages). Checked on both events: message_end is the
+        // precise "this assistant message is done" signal most runtimes emit, but
+        // turn_end is a safety net for one that only surfaces the final text there.
+        // Fire-and-forget and internally deduped, so checking on both costs nothing.
+        if (event.type === "message_end" || event.type === "turn_end") {
+            resolveInlineImages(record);
+        }
         // Durably persist the throttled sidecars at the turn boundary so a crash
         // loses at most the in-flight turn's UI detail, not the whole turn.
         if (event.type === "turn_end")
@@ -6803,6 +6905,12 @@ function attachSessionListeners(record) {
             const e = event;
             broadcast({ type: "session.notice", sessionId: record.id, level: e.level ?? "info", message: String(e.message ?? ""), ...(e.action ? { action: e.action } : {}) });
         }
+        if (event.type === "session.error") {
+            // A runtime-emitted auth failure (Codex's app-server websocket 401, or a
+            // ProcessRuntime/ProtocolRuntime credential preflight) — raise the sign-in
+            // sheet for the right provider alongside the inline error bubble.
+            maybeSignalAuthRequired(record, String(event.error ?? ""));
+        }
         if (event.type === "runtime.commands") {
             // The agent learned its own slash commands mid-session (e.g. Claude Code's
             // system/init reports slash_commands only after the first turn starts).
@@ -6851,6 +6959,9 @@ function attachSessionListeners(record) {
                 metadata.touchSession(record.id, "failed");
                 scheduleAdvertise();
                 broadcast({ type: "session.error", sessionId: record.id, error: turnError });
+                // If the terminal error is an auth failure (expired key/token → 4xx),
+                // also raise the sign-in sheet for the failing provider.
+                maybeSignalAuthRequired(record, turnError);
                 void sendNotificationHint({
                     kind: "session_error",
                     sessionId: record.id,

package/dist/session/event-log.js

@@ -61,8 +61,18 @@ function isOutboundAttachment(value) {
         typeof record.ref === "object" &&
         typeof record.ref.hash === "string");
 }
+function isInlineImage(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (record.bivyKind === "inline-image" &&
+        typeof record.url === "string" &&
+        !!record.ref &&
+        typeof record.ref === "object" &&
+        typeof record.ref.hash === "string");
+}
 function isRecord(value) {
-    return isOverlay(value) || isBase(value) || isAttachment(value) || isOutboundAttachment(value);
+    return isOverlay(value) || isBase(value) || isAttachment(value) || isOutboundAttachment(value) || isInlineImage(value);
 }
 /**
  * Fold attachment records into a text→refs list: last write wins per text (a
@@ -85,6 +95,24 @@ export function replayAttachments(entries) {
     }
     return [...byText.entries()];
 }
+/**
+ * Fold inline-image records into a url→ref list: last write wins per URL
+ * (a re-resolved URL — e.g. after a retry — re-keys onto the newest ref),
+ * preserving first-seen order. Mirrors replayAttachments' shape exactly, one
+ * level simpler (a single ref instead of an array) since one URL is one image.
+ */
+export function replayInlineImages(entries) {
+    const byUrl = new Map();
+    for (const entry of entries) {
+        if (entry.bivyKind !== "inline-image")
+            continue;
+        if (!entry.url)
+            continue;
+        byUrl.delete(entry.url);
+        byUrl.set(entry.url, entry.ref);
+    }
+    return [...byUrl.entries()];
+}
 /**
  * Fold the intermediate-reasoning entries exactly as the legacy incremental
  * upsert did (`upsertIntermediateMessage` in server.ts): last write wins per id;
@@ -343,6 +371,22 @@ export class EventLog {
         };
         this.enqueue(id, `oa:${entry.id}`, record);
     }
+    /**
+     * Record the durable ref for a fetched inline (remote markdown) image,
+     * keyed by its source URL. Coalesces on the URL so a re-resolve (retry after
+     * a transient failure) updates in place rather than appending a duplicate line.
+     */
+    appendInlineImage(id, entry) {
+        if (!entry.url)
+            return;
+        this.load(id);
+        const record = { bivyKind: "inline-image", createdAt: Date.now(), url: entry.url, ref: { ...entry.ref } };
+        this.enqueue(id, `ii:${entry.url}`, record);
+    }
+    /** Replay the inline-image records (disk + pending) into a url→ref list. */
+    readInlineImages(id) {
+        return replayInlineImages(this.entries(id));
+    }
     /** Replay the overlay entries (disk + pending) into the flat `extras` list. */
     read(id) {
         return replayExtras(this.entries(id));

package/dist/session/inline-image-fetch.js

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Fetch + validate a remote image an agent referenced with markdown image syntax
+// (`![alt](https://…)`), so the node — not the viewer's browser — makes the
+// request. See docs/issue #293: the deployed web app's CSP (`img-src 'self'
+// data: blob:`) blocks a literal `<img src="https://…">` outright, so without
+// this the syntax rendered nothing. Fetching server-side also closes the
+// SSRF/privacy hole a client-side fetch would otherwise open (an agent could
+// otherwise get the *viewer's* browser/IP to hit an arbitrary URL by embedding
+// it in a reply).
+//
+// This is the PURE-ish, testable half — URL extraction, host/SSRF validation,
+// and the guarded fetch itself — all dependency-injectable so tests never hit
+// the real network or DNS. The server half (src/server.ts) owns the AttachmentStore
+// write, the durable event-log ref, and the live broadcast; see resolveInlineImages.
+import dns from "node:dns/promises";
+import { hostnameIsLocal } from "../auth.js";
+import { sanitizeAttachmentName, sniffMime } from "./attach-to-chat.js";
+/**
+ * The image-markdown pattern, `![alt](https://…)` — MUST match the image regex
+ * in `inline()` in packages/core/src/markdown.ts exactly. Not a shared import: the
+ * node (src/) intentionally does not depend on @bivy/core (a browser/client
+ * package — see packages/core's own description). Kept in lock-step by comment
+ * instead, the same convention EPHEMERAL_ALLOWED_HOSTS uses in
+ * src/ephemeral-exec.ts for its cross-copy host allowlist. If you change one,
+ * change the other.
+ */
+const INLINE_IMAGE_MD_RE = /!\[[^\]]*\]\((https:\/\/[^)\s]+)\)/g;
+/** Bound how many distinct remote images a single message can trigger a fetch
+ *  for — a pathological/malicious message can't fan out into an unbounded
+ *  number of outbound requests. */
+export const MAX_INLINE_IMAGES_PER_MESSAGE = 6;
+/** Ceiling for a single fetched inline image. Smaller than
+ *  MAX_AGENT_ATTACHMENT_BYTES (attach-to-chat.ts) because these bytes come from
+ *  an arbitrary, untrusted remote origin rather than the local workspace —
+ *  still comfortably under the relay's 32 MiB reassembly limit (see
+ *  packages/core/src/wire-format.ts). */
+export const MAX_INLINE_IMAGE_BYTES = 8 * 1024 * 1024;
+const FETCH_TIMEOUT_MS = 10_000;
+/** Hard cap on redirect hops, mirroring execEphemeralRequest's guard. */
+const MAX_REDIRECTS = 5;
+/** Extract the distinct `https://` URLs a message's raw markdown references via
+ *  `![alt](url)`, in first-seen order, capped at MAX_INLINE_IMAGES_PER_MESSAGE. */
+export function extractInlineImageUrls(text) {
+    if (!text)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const match of text.matchAll(INLINE_IMAGE_MD_RE)) {
+        const url = match[1];
+        if (!url || seen.has(url))
+            continue;
+        seen.add(url);
+        out.push(url);
+        if (out.length >= MAX_INLINE_IMAGES_PER_MESSAGE)
+            break;
+    }
+    return out;
+}
+/** Best-effort plain text for an assistant RuntimeMessage's `content`, which is
+ *  either a plain string or an array of typed blocks (`{type:"text", text}`
+ *  among others, e.g. tool_use/thinking). Only the text parts matter for
+ *  finding markdown image references. */
+export function assistantTextForImageScan(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((part) => !!part && typeof part === "object" && String(part.type || "").toLowerCase() === "text")
+        .map((part) => String(part.text ?? ""))
+        .join("\n");
+}
+/** Env-configurable extra allowlist, comma-separated hostnames — same shape/
+ *  naming convention as BIVY_ALLOWED_HOSTS (src/auth.ts). When set and
+ *  non-empty, ONLY these hosts may be fetched (a stricter opt-in for locked-down
+ *  deployments); unset means "any public host is fine" (the private/local-address
+ *  block below still applies either way). */
+function explicitAllowlist() {
+    return new Set((process.env.BIVY_INLINE_IMAGE_ALLOWED_HOSTS ?? "")
+        .split(",")
+        .map((h) => h.trim().toLowerCase())
+        .filter(Boolean));
+}
+export function isFetchImageError(value) {
+    return typeof value.error === "string";
+}
+async function defaultResolveHost(hostname) {
+    const results = await dns.lookup(hostname, { all: true });
+    return results.map((r) => r.address);
+}
+/**
+ * Reject anything but a public https host before it's ever requested: the
+ * literal hostname (an IP-literal `https://169.254.169.254/…` cloud-metadata
+ * URL, or an internal domain), AND every address it resolves to (a public-
+ * looking hostname an attacker points at an internal IP — classic DNS-rebinding
+ * SSRF). This runs again on every redirect hop in fetchInlineImage, exactly like
+ * execEphemeralRequest's per-hop host re-check.
+ *
+ * Known limitation: `fetch()` below does its own DNS resolution, which could in
+ * principle differ from what we just checked (a narrow TOCTOU window) — pinning
+ * the connection to the resolved address would need a custom dispatcher/Agent,
+ * which isn't worth the complexity here; this closes the overwhelming majority
+ * of real SSRF attempts (metadata endpoints, LAN scanning, loopback) the same
+ * way the rest of this codebase's SSRF guards do.
+ */
+async function assertHostAllowed(url, resolveHost) {
+    if (url.protocol !== "https:")
+        throw new Error(`Refusing to fetch a non-https image URL (${url.protocol})`);
+    const hostname = url.hostname;
+    if (hostnameIsLocal(hostname))
+        throw new Error(`Refusing to fetch an image from a local/private host: ${hostname}`);
+    const allowlist = explicitAllowlist();
+    if (allowlist.size > 0 && !allowlist.has(hostname.toLowerCase())) {
+        throw new Error(`Host not in BIVY_INLINE_IMAGE_ALLOWED_HOSTS: ${hostname}`);
+    }
+    let addresses;
+    try {
+        addresses = await resolveHost(hostname);
+    }
+    catch (error) {
+        throw new Error(`Could not resolve host ${hostname}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!addresses.length)
+        throw new Error(`Host ${hostname} did not resolve to any address`);
+    for (const address of addresses) {
+        if (hostnameIsLocal(address))
+            throw new Error(`Refusing to fetch an image — ${hostname} resolves to a private/local address`);
+    }
+}
+/**
+ * Fetch a single remote image, guarded against SSRF (private/local hosts,
+ * DNS-rebinding, unvalidated redirects), unbounded size, and non-image
+ * responses. Returns the bytes + a validated mime type, or a human-readable
+ * error — never throws (a bad/malicious URL must not crash the caller).
+ */
+export async function fetchInlineImage(rawUrl, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const resolveHost = opts.resolveHost ?? defaultResolveHost;
+    const maxBytes = opts.maxBytes ?? MAX_INLINE_IMAGE_BYTES;
+    const timeoutMs = opts.timeoutMs ?? FETCH_TIMEOUT_MS;
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return { error: `Invalid image URL: ${rawUrl}` };
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        for (let hop = 0;; hop++) {
+            try {
+                await assertHostAllowed(url, resolveHost);
+            }
+            catch (error) {
+                return { error: error instanceof Error ? error.message : String(error) };
+            }
+            let res;
+            try {
+                res = await fetchImpl(url.toString(), { signal: controller.signal, redirect: "manual", headers: { accept: "image/*" } });
+            }
+            catch (error) {
+                return { error: `Fetching image failed: ${error instanceof Error ? error.message : String(error)}` };
+            }
+            if (res.status >= 300 && res.status < 400 && res.status !== 304) {
+                if (hop >= MAX_REDIRECTS)
+                    return { error: `Too many redirects fetching image: ${rawUrl}` };
+                const location = res.headers.get("location");
+                if (!location)
+                    return { error: `Redirect (${res.status}) had no Location header` };
+                try {
+                    url = new URL(location, url);
+                }
+                catch {
+                    return { error: `Redirect target was not a valid URL: ${location}` };
+                }
+                continue; // next hop re-validates the new host before requesting it
+            }
+            if (!res.ok)
+                return { error: `Image fetch failed: HTTP ${res.status}` };
+            const contentLength = Number(res.headers.get("content-length") || "0");
+            if (contentLength > 0 && contentLength > maxBytes) {
+                return { error: `Image too large (${contentLength} bytes; limit ${maxBytes})` };
+            }
+            if (!res.body)
+                return { error: "Image response had no body" };
+            const contentType = (res.headers.get("content-type") || "").split(";")[0].trim().toLowerCase();
+            const reader = res.body.getReader();
+            const chunks = [];
+            let total = 0;
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (!value)
+                    continue;
+                total += value.byteLength;
+                if (total > maxBytes) {
+                    try {
+                        await reader.cancel();
+                    }
+                    catch {
+                        // best-effort — we're already erroring out
+                    }
+                    return { error: `Image exceeded the ${maxBytes}-byte limit` };
+                }
+                chunks.push(value);
+            }
+            const bytes = Buffer.concat(chunks.map((c) => Buffer.from(c)));
+            if (!bytes.length)
+                return { error: "Image response was empty" };
+            // Trust magic bytes over the (spoofable) Content-Type header when they
+            // disagree; fall back to the header only when sniffing is inconclusive
+            // (e.g. an SVG, which sniffMime doesn't recognize).
+            const sniffed = sniffMime(bytes);
+            const mimeType = sniffed || (contentType.startsWith("image/") ? contentType : "");
+            if (!mimeType)
+                return { error: "Response does not look like an image" };
+            return { bytes, mimeType };
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/** A display name for a fetched inline image's AttachmentStore entry: the URL's
+ *  last path segment when it looks like a filename, else a generic name derived
+ *  from the resolved mime type. */
+export function inlineImageDisplayName(url, mimeType) {
+    try {
+        const pathname = new URL(url).pathname;
+        const base = pathname.split("/").filter(Boolean).pop();
+        if (base)
+            return sanitizeAttachmentName(decodeURIComponent(base));
+    }
+    catch {
+        // fall through to the generic name below
+    }
+    const ext = mimeType.split("/")[1]?.split("+")[0] || "png";
+    return `inline-image.${ext}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.5.1-staging.75",
+  "version": "0.5.1-staging.77",
   "type": "module",
   "license": "FSL-1.1-ALv2",
   "description": "Run coding agents on machines you own. Source-available, self-hostable agent workspace.",