diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 8b3c110ff2..a14305135e 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -122,6 +122,7 @@ jobs:
packages/ui/components/DiagramBlock.askAI.test.tsx
packages/ui/components/Viewer.askAISelectionLine.test.tsx
packages/ui/components/ImageLightbox.test.tsx
+ packages/inbox/images.test.tsx
packages/ui/components/blocks/QuestionBlock.test.tsx
packages/ui/components/blocks/QuestionBlock.host.test.tsx
packages/ui/components/blocks/QuestionBlock.decisionToggle.test.tsx
diff --git a/AGENTS.md b/AGENTS.md
index 65faf674c4..8a9153a049 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1975,6 +1975,12 @@ Sorting and the rest:
- Comments take no images.
- Delete thread rewrites the project's files without the thread's lines. Delete project removes its folder. Both then remove every blob that no remaining record uses.
+**Images in a message** (#1813; `packages/shared/inbox/message-images.ts`, `packages/server/inbox-message-images.ts`, `packages/inbox/images.ts`).
+- A message body's (an agent's or the person's own) `` and ``. The window draws each body with `imageBaseDir` = `inbox-message:` and installs `inboxImageSrcResolver`, which maps that marker to the route. There is no route that takes a bare path.
+- The rules, in order: the path must appear in THAT message's body as an image reference (`inboxMessageImageRefs`: the markdown target as written, the ``: an image the message's body shows, read from its project (see "Images in a message"); sniffed `Content-Type`, nosniff, sandbox CSP, same-origin CORP, `X-Image-Width`/`-Height`. `403 image_not_referenced` / `outside_project` / `cross_origin`, `404 message_not_found` / `image_missing`, `405`, `409 image_changed`, `413 image_too_large`, `415 not_an_image` |
| `/api/inbox/attachments/:id/view` | GET | `{ attachment, version, text, html }`: one version's text (`version` is `current` or the sent sha256, the annotations' key); for HTML, `html` is the page with its `/` | GET | Annotate's asset route (`resolveHtmlAssetRoute`) for the folder of an attached HTML page |
| `/api/inbox/annotations` | POST | `{ serverSession?, attachment_id, version, annotation }`: save a new annotation or edit one still waiting (`409 annotation_closed` once sent or removed) |
diff --git a/apps/marketing/src/content/docs/reference/inbox.md b/apps/marketing/src/content/docs/reference/inbox.md
index 6799f0a2bd..a76a292ae2 100644
--- a/apps/marketing/src/content/docs/reference/inbox.md
+++ b/apps/marketing/src/content/docs/reference/inbox.md
@@ -38,6 +38,7 @@ You never need to keep the Inbox running yourself. When an agent calls it and it
- **A thread.** It reads like email. Questions render as cards, and a click saves your pick at once. **Send** carries your picks, your words and your annotations as one reply. **Mod+Enter** sends. After a Send the reply reads "Saved for " until the agent reads it, then "Delivered to , ".
- **New message.** Next to Reply, **New message** writes to an agent session that is running now in the thread's project (Claude Code, Pi or OpenCode 2 with the inbox tool; Pi and OpenCode 2 sessions are listed once they have written in that project). With one session running, the message goes to it; with several, you pick one. The session takes it as its next turn. The message belongs only to the session you picked: another agent session reading the thread does not take it. When no session is running, the button says so and offers Reply instead.
- **Files.** Files an agent attached open beside the thread: markdown, text, HTML, Mermaid and Graphviz. Annotate them as in Plannotator, and the annotations ride your next Send. If the agent changes a file after it sent it, the Inbox says so and can still show the version it sent.
+- **Images.** An image in a message, `` or `/image with the src as written', async () => {
+ setImageSrcResolver(inboxImageSrcResolver);
+ const body = [
+ 'The page after the fix:',
+ '',
+ '',
+ '',
+ '
',
+ '',
+ '',
+ ].join('\n');
+ host = document.createElement('div');
+ document.body.appendChild(host);
+ await act(async () => {
+ root = createRoot(host!);
+ root.render(
+ {}}
+ onSelectAnnotation={() => {}}
+ selectedAnnotationId={null}
+ mode="selection"
+ taterMode={false}
+ maxWidth={null}
+ stickyActions={false}
+ disableCodePathValidation
+ imageBaseDir={inboxMessageImageBase(ID)}
+ answerOnly
+ readOnly
+ />,
+ );
+ });
+ const src = (alt: string) => host!.querySelector(`img[alt="${alt}"]`)?.getAttribute('src');
+ expect(src('after')).toBe(`/api/inbox/messages/${ID}/image?path=${encodeURIComponent('.walkthrough/shots/after.png')}`);
+ expect(src('before')).toBe(`/api/inbox/messages/${ID}/image?path=${encodeURIComponent('/abs/shots/before.png')}`);
+ // Remote images keep their URL (the window's CSP does not load them).
+ expect(src('remote')).toBe('https://example.com/x.png');
+});
+
+test('the resolver routes only a message marker; anything else keeps the default URL', () => {
+ expect(inboxImageSrcResolver('a.png', inboxMessageImageBase(ID))).toBe(`/api/inbox/messages/${ID}/image?path=a.png`);
+ expect(inboxImageSrcResolver('a.png', 'inbox-message:../../evil')).toBe('/api/image?path=a.png&base=inbox-message%3A..%2F..%2Fevil');
+ expect(inboxImageSrcResolver('a.png')).toBe('/api/image?path=a.png');
+});
diff --git a/packages/inbox/images.ts b/packages/inbox/images.ts
new file mode 100644
index 0000000000..496e47c9bb
--- /dev/null
+++ b/packages/inbox/images.ts
@@ -0,0 +1,43 @@
+/**
+ * Images in a message (#1813). A message body is drawn by ui's
+ * Viewer with `imageBaseDir` set to `inboxMessageImageBase(message.id)`, and
+ * the window installs `inboxImageSrcResolver` (configurePlannotatorUI), which
+ * turns that marker plus the src as written into the Inbox's own route:
+ * `/api/inbox/messages//image?path=`. The server reads the image
+ * from the message's project only when the message's body shows it
+ * (packages/shared/inbox/message-images.ts). There is no route that takes a
+ * bare path.
+ *
+ * Remote `http(s)` images are left as written: the window's CSP (`img-src
+ * 'self' data: blob:`) does not load them.
+ */
+import type { ImageSrcResolver } from '@plannotator/ui/configure';
+
+const MESSAGE_BASE_PREFIX = 'inbox-message:';
+const MESSAGE_ID_RE = /^msg_[0-9A-Za-z]+$/;
+
+/** The `imageBaseDir` a message body is drawn with. */
+export function inboxMessageImageBase(messageId: string): string {
+ return `${MESSAGE_BASE_PREFIX}${messageId}`;
+}
+
+/** The URL an image in a message loads from. */
+export function inboxMessageImageUrl(messageId: string, src: string): string {
+ return `/api/inbox/messages/${encodeURIComponent(messageId)}/image?path=${encodeURIComponent(src)}`;
+}
+
+/**
+ * The window's image resolver. Outside a message body there is no image
+ * route in the Inbox, so any other local path keeps ui's default URL, which
+ * the Inbox answers with a 404 as it always has.
+ */
+export const inboxImageSrcResolver: ImageSrcResolver = (path, base) => {
+ if (/^https?:\/\//i.test(path)) return path;
+ if (base?.startsWith(MESSAGE_BASE_PREFIX)) {
+ const id = base.slice(MESSAGE_BASE_PREFIX.length);
+ if (MESSAGE_ID_RE.test(id)) return inboxMessageImageUrl(id, path);
+ }
+ let url = `/api/image?path=${encodeURIComponent(path)}`;
+ if (base && !path.startsWith('/')) url += `&base=${encodeURIComponent(base)}`;
+ return url;
+};
diff --git a/packages/server/inbox-mcp.ts b/packages/server/inbox-mcp.ts
index e0887ff404..2106b5eb1c 100644
--- a/packages/server/inbox-mcp.ts
+++ b/packages/server/inbox-mcp.ts
@@ -10,7 +10,8 @@
* question, approves or sends on the person's behalf.
*/
-import { isAbsolute } from "node:path";
+import { realpathSync } from "node:fs";
+import { isAbsolute, sep } from "node:path";
import { McpServer } from "@modelcontextprotocol/server";
import * as z from "zod";
import { QUESTION_AUTHORING_GUIDE } from "@plannotator/core/question-block";
@@ -227,6 +228,22 @@ export async function sendProject(context: InboxMcpContext, input: { reply_to?:
return context.resolveProject(input.project_path);
}
+/**
+ * The folder inside `project` an agent sent from, when it is not the root
+ * (`InboxMessage.base_path`): relative image paths in its body start there.
+ */
+function sendBasePath(projectPath: string | undefined, project: InboxProject): string | null {
+ if (!projectPath || !isAbsolute(projectPath)) return null;
+ let real: string;
+ try {
+ real = realpathSync(projectPath);
+ } catch {
+ return null;
+ }
+ const root = project.root.endsWith(sep) ? project.root : `${project.root}${sep}`;
+ return real !== project.root && real.startsWith(root) ? real : null;
+}
+
/** An agent's message into `project`, routed by the store (send_message, submit_guide). */
export function sendAgentMessage(
context: InboxMcpContext,
@@ -256,6 +273,7 @@ export function sendAgentMessage(
thread: input.thread ?? null,
attachments,
guide: guide ?? null,
+ base_path: sendBasePath(input.project_path, project),
});
const message = result.message;
const landed = store.project(message.project_id)!;
diff --git a/packages/server/inbox-message-images.test.ts b/packages/server/inbox-message-images.test.ts
new file mode 100644
index 0000000000..a6103f3230
--- /dev/null
+++ b/packages/server/inbox-message-images.test.ts
@@ -0,0 +1,288 @@
+/**
+ * Images in a message (#1813), proved against a real Inbox on
+ * loopback under a temp data dir, a temp git project, the MCP SDK client for
+ * the agent and real `fetch` for the window.
+ */
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, truncateSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { inboxMessageImageRefs, readInboxMessageImage } from "@plannotator/shared/inbox/message-images";
+import { MAX_REVIEW_IMAGE_PREVIEW_BYTES } from "@plannotator/shared/diff-paths";
+import { startInboxServer, type InboxServer } from "./inbox";
+
+const roots: string[] = [];
+const servers: InboxServer[] = [];
+const clients: Client[] = [];
+let previousDataDir: string | undefined;
+
+beforeEach(() => {
+ previousDataDir = process.env.PLANNOTATOR_DATA_DIR;
+});
+
+afterEach(async () => {
+ for (const client of clients.splice(0)) await client.close().catch(() => {});
+ for (const server of servers.splice(0)) server.stop();
+ for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+ if (previousDataDir === undefined) delete process.env.PLANNOTATOR_DATA_DIR;
+ else process.env.PLANNOTATOR_DATA_DIR = previousDataDir;
+});
+
+/** A PNG's signature and IHDR (2 x 3 px): enough for the sniffer and the dimension read. */
+function png(): Uint8Array {
+ const bytes = new Uint8Array(33);
+ bytes.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 13, 0x49, 0x48, 0x44, 0x52, 0, 0, 0, 2, 0, 0, 0, 3, 8, 6, 0, 0, 0]);
+ return bytes;
+}
+
+function gif(): Uint8Array {
+ return new Uint8Array([0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 1, 0, 1, 0, 0, 0, 0]);
+}
+
+function world() {
+ const root = realpathSync(mkdtempSync(join(tmpdir(), "plannotator-inbox-img-")));
+ roots.push(root);
+ const project = join(root, "api");
+ mkdirSync(join(project, ".walkthrough", "shots"), { recursive: true });
+ mkdirSync(join(project, "packages", "web", "shots"), { recursive: true });
+ Bun.spawnSync(["git", "init", "-q"], { cwd: project, env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" } });
+ writeFileSync(join(project, ".walkthrough", "shots", "after.png"), png());
+ // A GIF named .png: the type comes from the bytes.
+ writeFileSync(join(project, ".walkthrough", "shots", "really-a-gif.png"), gif());
+ writeFileSync(join(project, ".walkthrough", "shots", "fake.png"), "not an image at all");
+ writeFileSync(join(project, ".walkthrough", "notes.txt"), "plain text");
+ writeFileSync(join(project, "packages", "web", "shots", "home.png"), png());
+ // Outside the project.
+ writeFileSync(join(root, "secret.png"), png());
+ symlinkSync(join(root, "secret.png"), join(project, ".walkthrough", "shots", "escape.png"));
+ const dataDir = join(root, "data");
+ process.env.PLANNOTATOR_DATA_DIR = dataDir;
+ return { root, project, dataDir };
+}
+
+async function start(dataDir: string): Promise {
+ const server = await startInboxServer({ dataDir, phones: false });
+ servers.push(server);
+ return server;
+}
+
+async function agent(server: InboxServer): Promise {
+ const client = new Client({ name: "inbox-message-images-test", version: "1.0.0" });
+ await client.connect(new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${server.port}/mcp`)));
+ clients.push(client);
+ return client;
+}
+
+async function send(client: Client, args: Record): Promise> {
+ const result = (await client.callTool({ name: "send_message", arguments: args })) as { isError?: boolean; content: { text: string }[]; structuredContent: Record };
+ if (result.isError) throw new Error(result.content[0]!.text);
+ return result.structuredContent;
+}
+
+function image(server: InboxServer, messageId: string, path: string, headers: Record = {}): Promise {
+ return fetch(`http://127.0.0.1:${server.port}/api/inbox/messages/${messageId}/image?path=${encodeURIComponent(path)}`, { headers });
+}
+
+function expectGuardHeaders(response: Response): void {
+ expect(response.headers.get("x-content-type-options")).toBe("nosniff");
+ expect(response.headers.get("content-security-policy")).toBe("sandbox; default-src 'none'; style-src 'unsafe-inline'");
+ expect(response.headers.get("cross-origin-resource-policy")).toBe("same-origin");
+ expect(response.headers.get("access-control-allow-origin")).toBeNull();
+}
+
+const BODY = [
+ "The page after the fix:",
+ "",
+ "",
+ "",
+ "  ",
+ "",
+ "  ",
+ "",
+ '/image?path=`, the
+ * images a message shows (#1813). Mounted in the Inbox server's
+ * route table (packages/server/inbox.ts), behind its Host allowlist; it sets
+ * no CORS headers.
+ *
+ * Every decision is in packages/shared/inbox/message-images.ts: the path
+ * must be an image the message's own body references, inside the message's
+ * project (realpath, so `../` and symlink escapes are refused), an image by
+ * extension and by its magic bytes, at most 10 MB. This file adds the
+ * transport: a cross-site request is refused before anything is read, and
+ * every answer carries nosniff, a sandbox CSP and a same-origin CORP, so
+ * another site can neither embed nor read an image, and an SVG opened
+ * directly never runs.
+ */
+
+import { isInboxId } from "@plannotator/core/inbox-types";
+import { INBOX_MESSAGE_IMAGE_CSP, readInboxMessageImage } from "@plannotator/shared/inbox/message-images";
+import type { InboxStore } from "@plannotator/shared/inbox/store";
+
+export const INBOX_MESSAGE_IMAGE_ROUTE = /^\/api\/inbox\/messages\/([A-Za-z0-9_]+)\/image$/;
+
+const GUARD_HEADERS = {
+ "X-Content-Type-Options": "nosniff",
+ "Content-Security-Policy": INBOX_MESSAGE_IMAGE_CSP,
+ "Cross-Origin-Resource-Policy": "same-origin",
+};
+
+function refuse(status: number, code: string, error: string): Response {
+ return new Response(JSON.stringify({ error, code }), {
+ status,
+ headers: { ...GUARD_HEADERS, "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" },
+ });
+}
+
+/** Answers the image route, or null when the path is not it. */
+export function inboxMessageImageRoute(req: Request, url: URL, store: InboxStore): Response | null {
+ const match = INBOX_MESSAGE_IMAGE_ROUTE.exec(url.pathname);
+ if (!match) return null;
+ if (req.method !== "GET" && req.method !== "HEAD") return refuse(405, "method_not_allowed", "Use GET.");
+ // The window's own /image?path=`
+ * (packages/server/inbox-message-images.ts), and this module decides every
+ * answer. The rules, in order:
+ *
+ * 1. The path must appear in THAT message's body as an image reference
+ * (`inboxMessageImageRefs`), compared as written. So the route reads
+ * only what the message shows, never a file a caller names.
+ * 2. It must name an image by extension (png jpg jpeg gif webp svg avif bmp
+ * ico apng, `isReviewImagePath`), before anything is read.
+ * 3. A relative path resolves against the folder the agent sent from
+ * (`base_path`, kept on the message when it is a subfolder of the
+ * project), else the project root; an absolute one is taken as it is.
+ * Its realpath must sit inside the project root (a realpath itself), so
+ * `../` and a symlink that leaves the project are refused alike, while
+ * an absolute path spelled through a symlinked prefix (macOS `/tmp`,
+ * really `/private/tmp`) is judged by where it really leads. A path
+ * that is not on disk and lexically leaves the project is refused too.
+ * 4. The realpath is opened once, `O_RDONLY | O_NOFOLLOW | O_NONBLOCK`, and
+ * everything after that reads the descriptor: `fstat` must say a regular
+ * file of at most MAX_REVIEW_IMAGE_PREVIEW_BYTES, at most cap + 1 bytes
+ * are read, and the path must still lead to that same file afterwards.
+ * A swap to a symlink, a FIFO (a blocking open or read would hang the
+ * Inbox's event loop on it) or a device is refused, never read. Then
+ * MAX_REVIEW_IMAGE_PREVIEW_PIXELS, and the content type is sniffed from
+ * the magic bytes (code review's sniffer), never taken from the name.
+ */
+
+import { closeSync, constants, fstatSync, openSync, readSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, resolve, sep } from "node:path";
+import { MAX_REVIEW_IMAGE_PREVIEW_BYTES, MAX_REVIEW_IMAGE_PREVIEW_PIXELS, isReviewImagePath } from "../diff-paths";
+import { isLfsPointer, readImageDimensions, sniffImageContentType } from "../review-image";
+
+/** The longest `path` the route takes. */
+export const INBOX_MESSAGE_IMAGE_PATH_MAX = 2048;
+
+/** The image answer's policy: an SVG opened directly never runs a script. */
+export const INBOX_MESSAGE_IMAGE_CSP = "sandbox; default-src 'none'; style-src 'unsafe-inline'";
+
+/** The markdown image grammar the window renders (InlineMarkdown): the src is everything up to the first `)`. */
+const MARKDOWN_IMAGE_RE = /!\[[^\]]*\]\(([^)]+)\)/g;
+/** An `]*?\ssrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/gi;
+
+const NAMED_ENTITIES: Record = { amp: "&", quot: '"', apos: "'", lt: "<", gt: ">", nbsp: " " };
+
+/** The attribute value as the browser reads it (getAttribute decodes character references). */
+function decodeAttribute(value: string): string {
+ return value.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (whole, ref: string) => {
+ if (ref[0] === "#") {
+ const code = ref[1] === "x" || ref[1] === "X" ? parseInt(ref.slice(2), 16) : parseInt(ref.slice(1), 10);
+ return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+ }
+ return NAMED_ENTITIES[ref.toLowerCase()] ?? whole;
+ });
+}
+
+/**
+ * Every image source the body names, as the window sends it: the markdown
+ * `` target as written and each ` {
+ const refs = new Set();
+ const add = (src: string | undefined) => {
+ if (!src) return;
+ if (/^(https?:|data:|blob:)/i.test(src)) return;
+ refs.add(src);
+ };
+ for (const match of body.matchAll(MARKDOWN_IMAGE_RE)) add(match[1]);
+ for (const match of body.matchAll(HTML_IMG_SRC_RE)) add(decodeAttribute(match[1] ?? match[2] ?? match[3] ?? ""));
+ return refs;
+}
+
+export type InboxMessageImageResult =
+ | { ok: true; bytes: Buffer; contentType: string; width?: number; height?: number }
+ | { ok: false; status: number; code: string; error: string };
+
+function refuse(status: number, code: string, error: string): InboxMessageImageResult {
+ return { ok: false, status, code, error };
+}
+
+function isInside(path: string, root: string): boolean {
+ return path === root || path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+}
+
+/**
+ * The filesystem paths a src may mean, in order: as written, without a
+ * `?query` / `#fragment`, and percent-decoded (`my%20shot.png`).
+ */
+function pathCandidates(src: string): string[] {
+ const out = [src];
+ const stripped = src.replace(/[?#].*$/s, "");
+ if (stripped && stripped !== src) out.push(stripped);
+ if (stripped.includes("%")) {
+ try {
+ const decoded = decodeURIComponent(stripped);
+ if (decoded !== stripped) out.push(decoded);
+ } catch {
+ // Not percent-encoded after all.
+ }
+ }
+ return out;
+}
+
+/** A URL scheme the route never reads (`file:`, `javascript:`); a Windows drive letter is a path. */
+function hasScheme(src: string): boolean {
+ return /^[a-z][a-z0-9+.-]*:/i.test(src) && !/^[a-z]:[\\/]/i.test(src);
+}
+
+/**
+ * Read one image a message shows. `root` is the project's root (a realpath);
+ * `base` the folder relative paths start from (the message's `base_path`, or
+ * the root). Never throws.
+ */
+export function readInboxMessageImage(input: { body: string; root: string; base?: string | null; path: string | null }): InboxMessageImageResult {
+ const src = input.path;
+ if (typeof src !== "string" || src === "") return refuse(400, "validation_error", "path: required.");
+ if (src.length > INBOX_MESSAGE_IMAGE_PATH_MAX || /[\u0000-\u001f\u007f]/.test(src)) {
+ return refuse(400, "validation_error", "path: not a usable image path.");
+ }
+ if (!inboxMessageImageRefs(input.body).has(src)) {
+ return refuse(403, "image_not_referenced", "This message does not show that image.");
+ }
+ if (hasScheme(src)) return refuse(400, "validation_error", "path: not a file path.");
+
+ let root: string;
+ try {
+ root = realpathSync(input.root);
+ } catch {
+ return refuse(404, "image_missing", "The message's project is no longer on disk.");
+ }
+ let base = root;
+ if (input.base) {
+ try {
+ const real = realpathSync(input.base);
+ if (isInside(real, root)) base = real;
+ } catch {
+ // The folder the agent sent from is gone: paths start at the root.
+ }
+ }
+
+ const candidates = pathCandidates(src).filter((candidate) => isReviewImagePath(candidate));
+ if (candidates.length === 0) return refuse(415, "not_an_image", "Only png, jpg, gif, webp, svg, avif, bmp and ico images are shown.");
+
+ for (const candidate of candidates) {
+ const named = isAbsolute(candidate) ? resolve(candidate) : resolve(base, candidate);
+ let real: string;
+ try {
+ real = realpathSync(named);
+ } catch {
+ // Not on disk under this spelling: one that leaves the project is
+ // refused as such; otherwise the next spelling is tried.
+ if (!isInside(named, root)) return refuse(403, "outside_project", "That image is outside the message's project.");
+ continue;
+ }
+ // Judged by where the path really leads, never by its spelling.
+ if (!isInside(real, root)) return refuse(403, "outside_project", "That image leads outside the message's project.");
+ const read = readImageFile(real);
+ if (!read.ok) return read;
+ const bytes = read.bytes;
+ if (isLfsPointer(bytes)) return refuse(415, "not_an_image", "That image is stored in Git LFS.");
+ const contentType = sniffImageContentType(bytes);
+ if (!contentType) return refuse(415, "not_an_image", "That file is not a recognized image.");
+ const dims = readImageDimensions(bytes, contentType);
+ if (dims && dims.width * dims.height > MAX_REVIEW_IMAGE_PREVIEW_PIXELS) {
+ return refuse(413, "image_too_large", "That image has too many pixels to show.");
+ }
+ return { ok: true, bytes, contentType, ...(dims ? { width: dims.width, height: dims.height } : {}) };
+ }
+ return refuse(404, "image_missing", "That image is not on disk.");
+}
+
+const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+const TOO_LARGE = "That image is larger than 10 MB.";
+const CHANGED = "That image changed while it was read.";
+
+/**
+ * Read a realpath through one descriptor: never follows a final symlink,
+ * never blocks on a FIFO, never buffers more than the cap + 1 bytes, and
+ * refuses when the path no longer leads to the file that was read.
+ */
+function readImageFile(real: string): { ok: true; bytes: Buffer } | Extract {
+ const fail = (status: number, code: string, error: string) => ({ ok: false as const, status, code, error });
+ let fd: number;
+ try {
+ fd = openSync(real, OPEN_FLAGS);
+ } catch (error) {
+ // ELOOP: the last component became a symlink after it was resolved.
+ if ((error as NodeJS.ErrnoException).code === "ELOOP") return fail(409, "image_changed", CHANGED);
+ return fail(404, "image_missing", "That image could not be opened.");
+ }
+ try {
+ const stat = fstatSync(fd);
+ if (!stat.isFile()) return fail(404, "image_missing", "That image is not a file.");
+ if (stat.size > MAX_REVIEW_IMAGE_PREVIEW_BYTES) return fail(413, "image_too_large", TOO_LARGE);
+ // One byte past what fstat said, so a file that grew meanwhile is seen.
+ const buffer = Buffer.alloc(Math.min(stat.size, MAX_REVIEW_IMAGE_PREVIEW_BYTES) + 1);
+ let total = 0;
+ while (total < buffer.length) {
+ const n = readSync(fd, buffer, total, buffer.length - total, null);
+ if (n === 0) break;
+ total += n;
+ }
+ if (total > MAX_REVIEW_IMAGE_PREVIEW_BYTES) return fail(413, "image_too_large", TOO_LARGE);
+ if (total === buffer.length) return fail(409, "image_changed", CHANGED);
+ // The path must still lead to the file this descriptor read, so a parent
+ // folder swapped for a symlink in between is caught.
+ let again: ReturnType | null = null;
+ try {
+ if (realpathSync(real) === real) again = statSync(real);
+ } catch {
+ again = null;
+ }
+ if (!again || again.dev !== stat.dev || again.ino !== stat.ino) return fail(409, "image_changed", CHANGED);
+ return { ok: true, bytes: buffer.subarray(0, total) };
+ } catch {
+ return fail(404, "image_missing", "That image could not be read.");
+ } finally {
+ closeSync(fd);
+ }
+}
diff --git a/packages/shared/inbox/store.ts b/packages/shared/inbox/store.ts
index 819c2b5f91..2257c1ec23 100644
--- a/packages/shared/inbox/store.ts
+++ b/packages/shared/inbox/store.ts
@@ -103,6 +103,8 @@ export interface InboxSendInput {
attachments?: InboxAttachment[];
/** A guided review the message carries (submit_guide); its blob is written once the message lands. */
guide?: InboxGuideRef | null;
+ /** The folder inside the project the agent sent from, when not its root (`InboxMessage.base_path`). */
+ base_path?: string | null;
}
export interface InboxSendResult {
@@ -808,6 +810,7 @@ export class InboxStore {
? { attachments: input.attachments.map((attachment) => ({ ...attachment, sent_at: at })) }
: {}),
...(input.guide ? { guide: input.guide } : {}),
+ ...(input.base_path ? { base_path: input.base_path } : {}),
};
this.appendMessage(message, at);
for (const question of parsed) {
diff --git a/packages/shared/package.json b/packages/shared/package.json
index 3c5c53ff1d..3dc7021eb8 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -113,6 +113,7 @@
"./inbox/registry": "./inbox/registry.ts",
"./inbox/devices": "./inbox/devices.ts",
"./inbox/attachments": "./inbox/attachments.ts",
+ "./inbox/message-images": "./inbox/message-images.ts",
"./inbox/connection": "./inbox/connection.ts",
"./inbox/agent-link": "./inbox/agent-link.ts"
},
diff --git a/tests/e2e/inbox-message-images.spec.ts b/tests/e2e/inbox-message-images.spec.ts
new file mode 100644
index 0000000000..563a33faae
--- /dev/null
+++ b/tests/e2e/inbox-message-images.spec.ts
@@ -0,0 +1,80 @@
+/**
+ * Images in a message (#1813), proved in a real browser against the
+ * compiled binary. Nothing is mocked: `plannotator inbox --background` runs
+ * under a temp PLANNOTATOR_DATA_DIR and HOME, an agent writes through
+ * `plannotator inbox mcp` (scripts/inbox-sim.ts) with a markdown image and an
+ * HTML
',
+ '',
+ '',
+ ].join('\n'),
+ });
+ const id = sent.message_id as string;
+ const page = await context.newPage();
+ await page.goto(`${url}#thread=${sent.thread_id}`);
+ const body = page.locator(`[data-message-id="${id}"]`);
+
+ const route = `/api/inbox/messages/${id}/image?path=${encodeURIComponent('.walkthrough/shots/after.png')}`;
+ for (const alt of ['after the fix', 'html image']) {
+ const img = body.getByRole('img', { name: alt });
+ await expect(img).toHaveAttribute('src', route);
+ await expect.poll(() => img.evaluate((el: HTMLImageElement) => el.complete && el.naturalWidth)).toBe(1);
+ }
+
+ const outside = body.getByRole('img', { name: 'outside' });
+ await expect(outside).toHaveAttribute('src', `/api/inbox/messages/${id}/image?path=${encodeURIComponent('../outside.png')}`);
+ await expect.poll(() => outside.evaluate((el: HTMLImageElement) => el.complete)).toBe(true);
+ expect(await outside.evaluate((el: HTMLImageElement) => el.naturalWidth)).toBe(0);
+ } finally {
+ await agent.close().catch(() => {});
+ await context.close();
+ try {
+ process.kill(JSON.parse(readFileSync(join(dataDir, 'inbox', 'inbox.json'), 'utf8')).pid, 'SIGTERM');
+ } catch {
+ // Already gone.
+ }
+ rmSync(root, { recursive: true, force: true });
+ }
+});
diff --git a/tests/e2e/playwright.config.ts b/tests/e2e/playwright.config.ts
index cb9a13ff22..bfa6f4438c 100644
--- a/tests/e2e/playwright.config.ts
+++ b/tests/e2e/playwright.config.ts
@@ -3,7 +3,7 @@
* binary (`plannotator inbox`), under a temp PLANNOTATOR_DATA_DIR: the window
* (inbox.spec.ts), notifications, decisions (inbox-decisions.spec.ts) and
* guided reviews (inbox-guides.spec.ts), New message
- * (inbox-new-message.spec.ts), the order inside a section (inbox-order.spec.ts), phones (inbox-phones.spec.ts), the sidebar (inbox-sidebar.spec.ts), and the
+ * (inbox-new-message.spec.ts), the order inside a section (inbox-order.spec.ts), phones (inbox-phones.spec.ts), the sidebar (inbox-sidebar.spec.ts), images in messages (inbox-message-images.spec.ts), and the
* surface a phone hosts, in WebKit (surface.spec.ts). Build the binary
* first (see inbox.spec.ts), then `bun run test:e2e:inbox`.
*/
@@ -11,7 +11,7 @@ import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: '.',
- testMatch: ['inbox.spec.ts', 'notifications.spec.ts', 'inbox-decisions.spec.ts', 'inbox-attachments.spec.ts', 'inbox-guides.spec.ts', 'inbox-new-message.spec.ts', 'inbox-order.spec.ts', 'inbox-phones.spec.ts', 'inbox-sidebar.spec.ts', 'surface.spec.ts'],
+ testMatch: ['inbox.spec.ts', 'notifications.spec.ts', 'inbox-decisions.spec.ts', 'inbox-attachments.spec.ts', 'inbox-guides.spec.ts', 'inbox-new-message.spec.ts', 'inbox-order.spec.ts', 'inbox-phones.spec.ts', 'inbox-sidebar.spec.ts', 'inbox-message-images.spec.ts', 'surface.spec.ts'],
outputDir: '../../.local/test-results',
fullyParallel: false,
workers: 1,