eve-hub 0.14.3 → 0.14.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # eve-hub
 
+## 0.14.4
+
+### Patch Changes
+
+- `post_message` carries a post's images (`images`: sandbox paths, or `screenshot` on a local hub) and uploads the documents its markdown links point at (a sandbox path becomes `hub://upload/<id>` on a hosted hub, `file://` on a local one). Its text is capped at 700 characters, link targets excluded, and `![]()` is refused. `show` refuses images. `attach_image` is removed. Docs are written in markdown, which the app renders in Vercel's report design; HTML only for a bespoke layout.
+  
+  Upgrade boundary: the hub no longer collects images uploaded by `attach_image`. A bot still on eve-hub 0.14.3 or older keeps a working `attach_image` (the upload succeeds), but its image never reaches a post. Redeploy every bot on 0.14.4 together with the hub that carries this release.
+
 ## 0.14.3
 
 ### Patch Changes

package/README.md

@@ -4,7 +4,7 @@ The bot-side code every hub agent shares (milestone M3 in [`docs/architecture`](
 
 | Module | What it is | Bots use it as |
 |---|---|---|
-| `tools/update_thread.ts`, `list_threads.ts`, `read_thread.ts`, `react.ts`, `show.ts`, `attach_image.ts`, `browser.ts` | Registry and workspace tools (`defineTool`) | `agent/tools/<same name>.ts` |
+| `tools/update_thread.ts`, `list_threads.ts`, `read_thread.ts`, `react.ts`, `show.ts`, `browser.ts` | Registry and workspace tools (`defineTool`) | `agent/tools/<same name>.ts` |
 | `tools/create_thread.ts`, `post_message.ts`, `archive_thread.ts`, `unarchive_thread.ts`, `list_agents.ts`, `create_agent.ts`, `remove_agent.ts`, `restart_agent.ts`, `tag_threads.ts`, `apply_tags.ts` | The orchestrator's tools | `main`'s `agent/tools/<same name>.ts` |
 | `hooks/sandbox.ts` | Migrates legacy Docker sessions to the host sandbox (`defineHook`) | `agent/hooks/sandbox.ts` |
 | `instructions/main.ts`, `main-instructions.mjs` | main's instructions (`defineInstructions`), rendered at build time from the kit's `templates/main-instructions.md` (identity, role) between the shared templates, each in its own tag, so no workspace carries a copy | `main`'s `agent/instructions.ts`; workspace-only additions in `agent/role/*.md` (inside `<role>`) |

package/host-browser.js

@@ -132,8 +132,8 @@ class SandboxBrowser {
     onClose;
     // One action at a time per browser. Tool calls in one model step run in
     // parallel, and Chromium drops a Page.captureScreenshot that's in flight
-    // when a navigation commits: it never answers. So `open` + `attach_image
-    // {screenshot}` side by side hung the turn. Serialized, the screenshot
+    // when a navigation commits: it never answers. So `open` + a
+    // screenshot side by side hung the turn. Serialized, the screenshot
     // waits for the page to load and then captures it.
     chain = Promise.resolve();
     exclusive(fn) {

package/hub-upload.d.ts

@@ -0,0 +1,20 @@
+export type SandboxFiles = {
+    readBinaryFile(input: {
+        path: string;
+    }): PromiseLike<Uint8Array | null | undefined>;
+    resolvePath(path: string): string;
+};
+export type Uploaded = {
+    id: string;
+    name: string;
+    size: number;
+};
+export declare const hostedHub: () => boolean;
+export declare const IMAGE_FILE: RegExp;
+/** A markdown link target that names a sandbox file: an absolute path, or one under the home directory. */
+export declare const isSandboxPath: (target: string) => boolean;
+export declare function readSandboxFile(sandbox: SandboxFiles, path: string): Promise<Uint8Array>;
+export declare function uploadBytes(bytes: Uint8Array, name: string, what: string): Promise<Uploaded>;
+export declare const uploadFile: (sandbox: SandboxFiles, path: string, what: string) => Promise<Uploaded>;
+/** Where the human's app opens a sandbox document from: hub://upload/<id> on a hosted hub, file:// on a local one. */
+export declare function documentUrl(sandbox: SandboxFiles, path: string, what: string): Promise<string>;

package/hub-upload.js

@@ -0,0 +1,42 @@
+// A bot's sandbox files on the hub: the upload path `show` and `post_message` share. An image
+// is uploaded on both hubs (it rides a message, store/attachments). A document goes as
+// file:// on a local hub (the bot's files are the human's) and, on a hosted one (a deployed
+// bot, or HUB_TOKEN set), as a snapshot uploaded to the hub (hub://upload/<sha>.<ext>),
+// since the human's Mac can't read the sandbox.
+import { basename } from "node:path";
+import { pathToFileURL } from "node:url";
+import { registryFetch } from "./registry-fetch.mjs";
+export const hostedHub = () => Boolean(process.env.VERCEL || process.env.HUB_TOKEN);
+export const IMAGE_FILE = /\.(png|jpe?g|gif|webp|heic)$/i;
+/** A markdown link target that names a sandbox file: an absolute path, or one under the home directory. */
+export const isSandboxPath = (target) => /^(\/|\$HOME\/|~\/)/.test(target);
+// The sandbox resolves `~/`; `$HOME/` is the same place spelled as the shell does.
+const sandboxPath = (path) => path.replace(/^\$HOME\//, "~/");
+export async function readSandboxFile(sandbox, path) {
+    const bytes = await sandbox.readBinaryFile({ path: sandboxPath(path) });
+    if (!bytes)
+        throw new Error(`no file at ${path}`);
+    return bytes;
+}
+export async function uploadBytes(bytes, name, what) {
+    const res = await registryFetch(`/api/uploads`, {
+        method: "POST",
+        headers: { "content-type": "application/octet-stream", "x-filename": encodeURIComponent(name) },
+        body: new Uint8Array(bytes),
+        signal: AbortSignal.timeout(30_000),
+    }).catch((error) => {
+        throw new Error(`${what} failed: the upload didn't finish (${error.message})`);
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || typeof body.id !== "string")
+        throw new Error(`${what} failed: the upload was refused (${body.error ?? res.status})`);
+    return { id: body.id, name: body.name ?? name, size: body.size ?? bytes.length };
+}
+export const uploadFile = async (sandbox, path, what) => uploadBytes(await readSandboxFile(sandbox, path), basename(path), what);
+/** Where the human's app opens a sandbox document from: hub://upload/<id> on a hosted hub, file:// on a local one. */
+export async function documentUrl(sandbox, path, what) {
+    if (hostedHub())
+        return `hub://upload/${(await uploadFile(sandbox, path, what)).id}`;
+    await readSandboxFile(sandbox, path);
+    return pathToFileURL(sandbox.resolvePath(sandboxPath(path))).href;
+}

package/kit-modules.json

@@ -17,7 +17,6 @@
   "skills/onboarding-profile",
   "tools/apply_tags",
   "tools/archive_thread",
-  "tools/attach_image",
   "tools/bash",
   "tools/browser",
   "tools/create_agent",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "license": "Apache-2.0",
   "description": "Bot-side code shared by every hub agent: registry tools, the roster hook, the eve channel, the host sandbox and browser, and model helpers.",
   "type": "module",

package/stubs.mjs

@@ -10,7 +10,6 @@ export const KIT_FILES = {
   "tools/react.ts": ["React to a message with an emoji."],
   "tools/show.ts": ["Move the human's screen to a thread, DM, or message, or open a page or file beside the thread."],
   "tools/browser.ts": ["Its own headless browser, watched live in the Computer view."],
-  "tools/attach_image.ts": ["Puts an image (a sandbox file or a browser screenshot) on this turn's reply."],
   "tools/view_image.ts": ["Shows the bot an image (a sandbox file or a browser screenshot) so it can see it."],
   "tools/update_thread.ts": ["Update a thread this bot is in: title, track, domain and summary."],
   "tools/list_threads.ts": ["Every workspace thread, from any session."],
@@ -50,7 +49,7 @@ export const MAIN_KIT_FILES = {
 // hub's machine: the sandbox hook (it migrates host sessions, and deletes any
 // sandbox that resolves /workspace as itself, which a Vercel Sandbox does),
 // the kit's bash (HostSandbox's root, the daemon's env; eve's own bash runs
-// instead), the browser and the screenshot paths of attach_image/view_image,
+// instead), the browser and the screenshot path of view_image,
 // restart_hub (the hub's own code), memory (the workspace's files), and main's prune schedule (it cleans the hub machine's disk).
 // main's dash schedule stays: off the hub's machine it has no PR data (its lookup runs `gh`).
 export const DEPLOYED_KIT_FILES = new Set([

package/templates/writing.md

@@ -7,10 +7,11 @@
   - How: a `flow`, `sequence`, `chart` or `ask` form sent with `post_message`; load the `forms` skill for the shapes, tables and syntax.
   - Never draw with characters: no arrows, boxes, numbered timelines or tables in a code fence.
 - **Disclose one step at a time**
-  - First bubble: the point or the question, in at most two sentences. The inbox and notifications show only its first line.
-  - After a `---` line (blank lines around it): what the reader needs to act, and nothing more.
-  - A linked file, PR or message: the full evidence, one click away, never pasted.
-  - Be ready to go deep when asked: that is the next step, not this one.
+  - A post is at most 2 sentences (the point or the question; the inbox shows only its first line), then at most 3 bullets or one small table: what the reader needs to act, and nothing more. `post_message` refuses more than 700 characters.
+  - Depth (evidence, analysis, options, a long table) goes in a doc: write a markdown file in your sandbox and link it in the post, `[the analysis](/workspace/notes/analysis.md)`; `post_message` uploads it and the link opens it beside the thread, already styled. Never paste it. Write HTML only for a layout markdown can't hold, following the `vercel-design` skill when you have it.
+  - Images go in `post_message`'s `images` (sandbox paths), never in the text.
+  - A file reaches the human only as a markdown link in a post or through `show`, which upload it. A raw sandbox path in text is a file they can't open.
+  - Once you have posted into the thread, your turn's closing text is not posted: say nothing after a post.
   - Why: the first line is often all that's read; depth one click away costs nothing until it's wanted.
 - **Say only what's new**
   - Post only what changes what the reader does next; react when nothing is new.

package/tools/post_message.d.ts

@@ -1,7 +1,15 @@
+export declare const MAX_CHARS = 700;
+/** The characters the cap counts: the text without its links' targets. */
+export declare const postLength: (text: string) => number;
+/** The error for a text the thread shouldn't carry, or null. */
+export declare function textError(text: string): string | null;
+/** The text with each sandbox-path link target replaced by where the human's app opens it. */
+export declare function rewriteDocLinks(text: string, open: (path: string) => Promise<string>): Promise<string>;
 declare const _default: import("eve/tools").ToolDefinition<{
     threadId?: string | undefined;
     agent?: string | undefined;
     text: string;
+    images?: string[] | undefined;
     policy?: "abort" | "queue" | "steer" | undefined;
     status?: "done" | "planning" | "reviewing" | "working" | undefined;
     metadata?: {
@@ -27,6 +35,7 @@ declare const _default: import("eve/tools").ToolDefinition<{
         threadId?: string | undefined;
         agent?: string | undefined;
         text: string;
+        images?: string[] | undefined;
         policy?: "abort" | "queue" | "steer" | undefined;
         status?: "done" | "planning" | "reviewing" | "working" | undefined;
         metadata?: {

package/tools/post_message.js

@@ -1,14 +1,19 @@
 import { defineTool } from "eve/tools";
 import { z } from "zod";
+import { documentUrl, hostedHub, isSandboxPath, uploadBytes, uploadFile } from "../hub-upload.js";
 import { registryFetch } from "../registry-fetch.mjs";
 // Posts as you into a thread or DM, from whichever session you're in. With no
-// target it posts into the thread you're in, as part of the running turn: it
-// carries the turn's id and the images collected so far,
-// and if it's your turn's last act (alone or with reactions), your end-of-turn text isn't posted. Into
-// another thread, mentions wake bots exactly as your replies do; posting into
-// a bot's DM wakes that bot; archived threads refuse it. Your session in the
-// target thread, if any, isn't woken; it sees the message as yours the next
-// time it's addressed.
+// target it posts into the thread you're in, as part of the running turn: once
+// a turn has posted there, its end-of-turn text isn't posted. Into another
+// thread, mentions wake bots exactly as your replies do; posting into a bot's
+// DM wakes that bot; archived threads refuse it. Your session in the target
+// thread, if any, isn't woken; it sees the message as yours the next time it's
+// addressed.
+//
+// The text is capped (MAX_CHARS, link targets excluded): depth goes in a
+// document the post links by its sandbox path, which is uploaded and the link
+// rewritten to where the hub serves it (hub-upload.ts). Images go in `images`
+// and ride the post.
 //
 // `policy` is how a post reaches the one bot it @-mentions: queue (default)
 // waits for that bot's turn to end, steer folds into its running turn, abort
@@ -17,12 +22,48 @@ import { registryFetch } from "../registry-fetch.mjs";
 // A status post: `status` is the thread's phase after it (the hub checks the
 // move), the text is its summary, `metadata` its PR and sha. The hub keeps the
 // latest one per bot and thread for the workspace state and the Dash.
+export const MAX_CHARS = 700;
+const LINK = /\[([^\]]*)\]\(([^)\s]+)\)/g;
+const IMAGE_SYNTAX = /!\[[^\]]*\]\([^)]*\)/;
+const SCREENSHOT = "screenshot";
+/** The characters the cap counts: the text without its links' targets. */
+export const postLength = (text) => text.replace(LINK, (_, label) => `[${label}]()`).length;
+/** The error for a text the thread shouldn't carry, or null. */
+export function textError(text) {
+    if (IMAGE_SYNTAX.test(text))
+        return "Images don't go in the text: pass the file's sandbox path in `images` and it shows inline";
+    if (postLength(text) > MAX_CHARS)
+        return "Too long: move the detail into a doc and link it";
+    return null;
+}
+/** The text with each sandbox-path link target replaced by where the human's app opens it. */
+export async function rewriteDocLinks(text, open) {
+    const links = [...text.matchAll(LINK)].filter((m) => isSandboxPath(m[2]));
+    const urls = await Promise.all(links.map((m) => open(m[2])));
+    let out = "", at = 0;
+    links.forEach((m, i) => {
+        const start = m.index + m[0].length - m[2].length - 1;
+        out += text.slice(at, start) + urls[i];
+        at = start + m[2].length;
+    });
+    return out + text.slice(at);
+}
+async function screenshot(sessionId) {
+    if (hostedHub())
+        throw new Error("a browser screenshot needs the hub's machine: on a hosted hub save the image to a sandbox file and pass its path in `images`");
+    const { browserFor } = await import("../host-browser.js");
+    const browser = await browserFor(sessionId);
+    if (browser.url === "about:blank")
+        throw new Error("your browser has no page open; open one with the browser tool first");
+    return browser.screenshot();
+}
 export default defineTool({
-    description: "Post a message as you. Leave out threadId and agent to post into the thread you're in, while you work: posting doesn't end your turn, and once your turn has posted into this thread, its end-of-turn text isn't posted, so put your result in a post. Or post into another workspace thread or a bot's DM. @-mentions wake bots the same way your replies do (at most one, never yourself); `@all` wakes every participant; each bot's gate decides whether it replies. Posting into a bot's DM wakes that bot. Archived threads are refused. `policy` says how a post reaches the one bot it @-mentions: queue (default) runs as its next turn, or starts one now if it is idle; steer lands in its RUNNING turn at the next step boundary and the bot folds it in without a restart, to correct course mid-turn; abort stops its turn in that thread (running commands are killed, the process keeps running) and the text starts its fresh turn, \"stop, do this instead\". Steer and abort need exactly one @-mention, not `@all`, and cut into work already under way: use them only to change what a running turn is doing. A status post sets the thread's phase: planning, working, reviewing or done; allowed moves are start → planning or working, planning → working, working → reviewing, reviewing → working (fix first), planning (rethink) or done. Any other move is refused with the allowed next phases. The text is a phase marker, not a report: at most 8 plain words on what is happening now (\"Building the input-count fix\"), with no bot or role names, no restating the phase, no parentheticals. Test results, branch names and caveats go in a separate message. The PR URL and sha go in metadata, never in the text.",
+    description: "Post a message as you. Leave out threadId and agent to post into the thread you're in, while you work: posting doesn't end your turn, and once your turn has posted into this thread, its end-of-turn text isn't posted, so put your result in a post. Or post into another workspace thread or a bot's DM. The text is at most 700 characters (link targets don't count): the point in 2 sentences, then at most 3 bullets or one small table. Depth goes in a document: write it to a file and link it in the text by its sandbox path, `[the plan](/workspace/plan.md)`; the file is uploaded and the link opens it beside the thread. Images go in `images` (sandbox paths; `screenshot` for your browser's page on a local hub) and show inline; never write `![]()`. @-mentions wake bots the same way your replies do (at most one, never yourself); `@all` wakes every participant; each bot's gate decides whether it replies. Posting into a bot's DM wakes that bot. Archived threads are refused. `policy` says how a post reaches the one bot it @-mentions: queue (default) runs as its next turn, or starts one now if it is idle; steer lands in its RUNNING turn at the next step boundary and the bot folds it in without a restart, to correct course mid-turn; abort stops its turn in that thread (running commands are killed, the process keeps running) and the text starts its fresh turn, \"stop, do this instead\". Steer and abort need exactly one @-mention, not `@all`, and cut into work already under way: use them only to change what a running turn is doing. A status post sets the thread's phase: planning, working, reviewing or done; allowed moves are start → planning or working, planning → working, working → reviewing, reviewing → working (fix first), planning (rethink) or done. Any other move is refused with the allowed next phases. The text is a phase marker, not a report: at most 8 plain words on what is happening now (\"Building the input-count fix\"), with no bot or role names, no restating the phase, no parentheticals. Test results, branch names and caveats go in a separate message. The PR URL and sha go in metadata, never in the text.",
     inputSchema: z.object({
         threadId: z.string().optional().describe("Another thread's id, e.g. thr_0002, or a DM id, dm-<bot>. Omit it to post into the thread you're in."),
         agent: z.string().optional().describe("Post into this bot's DM instead of a thread."),
-        text: z.string().describe("The message. @-mention the one bot who should act. On a status post: at most 8 plain words on what is happening now."),
+        text: z.string().describe("The message, at most 700 characters (link targets don't count). A markdown link to a sandbox path uploads that document. @-mention the one bot who should act. On a status post: at most 8 plain words on what is happening now."),
+        images: z.array(z.string()).optional().describe("Images to show inline on this post: sandbox paths (PNG, JPEG, GIF or WebP, up to 3 MB each), or `screenshot` for your browser's current page (local hub only)."),
         policy: z.enum(["queue", "steer", "abort"]).optional().describe("How the post reaches the one bot it @-mentions: queue (default), steer into its running turn, or abort its turn and start a fresh one on this text."),
         status: z.enum(["planning", "working", "reviewing", "done"]).optional().describe("The thread's phase after this post. Makes it a status post."),
         metadata: z
@@ -39,12 +80,19 @@ export default defineTool({
             .describe("With a verdict: what the human has to pick. [] when nothing; required with ship."),
         tested: z.string().optional().describe("With a verdict: what you ran to check it, in a sentence (shown on the Dash row)."),
     }),
-    async execute({ threadId, agent, text, policy, status, metadata, verdict, decisions, tested }, ctx) {
+    async execute({ threadId, agent, text, images, policy, status, metadata, verdict, decisions, tested }, ctx) {
+        const bad = textError(text);
+        if (bad)
+            throw new Error(bad);
         const target = threadId ?? (agent ? `dm-${agent.replace(/^@/, "")}` : "here");
+        let sandbox;
+        const files = async () => (sandbox ??= await ctx.getSandbox());
+        const posted = await rewriteDocLinks(text, async (path) => documentUrl(await files(), path, "post_message"));
+        const attachments = await Promise.all((images ?? []).map(async (image) => image === SCREENSHOT ? uploadBytes(await screenshot(ctx.session.id), "screenshot.png", "post_message") : uploadFile(await files(), image, "post_message")));
         const res = await registryFetch(`/api/threads/${encodeURIComponent(target)}/messages`, {
             method: "POST",
             headers: { "content-type": "application/json" },
-            body: JSON.stringify({ text, sessionId: ctx.session.id, ...(policy ? { policy } : {}), ...(status ? { status } : {}), ...(metadata ? { metadata } : {}), ...(verdict ? { verdict } : {}), ...(decisions ? { decisions } : {}), ...(tested ? { tested } : {}) }),
+            body: JSON.stringify({ text: posted, sessionId: ctx.session.id, ...(attachments.length ? { attachments: attachments.map(({ id, name }) => ({ id, name })) } : {}), ...(policy ? { policy } : {}), ...(status ? { status } : {}), ...(metadata ? { metadata } : {}), ...(verdict ? { verdict } : {}), ...(decisions ? { decisions } : {}), ...(tested ? { tested } : {}) }),
         });
         if (!res.ok)
             throw new Error(`post_message failed: ${res.status} ${await res.text()}`);

package/tools/show.js

@@ -1,23 +1,22 @@
 import { basename } from "node:path";
-import { pathToFileURL } from "node:url";
 import { defineTool } from "eve/tools";
 import { z } from "zod";
+import { documentUrl, IMAGE_FILE } from "../hub-upload.js";
 import { registryFetch } from "../registry-fetch.mjs";
 // Moves the human's workspace UI, e.g. to a thread you just opened or a
 // message they need to look at, or opens a page or file in the pane beside
 // the thread. They see a note saying you did it and why.
 //
-// A file goes as file:// on a local hub (the bot's files are the human's) and,
-// on a hosted hub (a deployed bot, or HUB_TOKEN set), as a snapshot uploaded to the hub
-// (hub://upload/<sha>.<ext>), since the human's Mac can't read the sandbox.
+// A file opens from where the hub can serve it (hub-upload.ts). An image is
+// refused: it belongs on a post, where the thread shows it inline.
 export default defineTool({
-    description: "Move the human's screen to a place in the workspace: a thread (threadId), a bot's DM (agent), optionally scrolled to and highlighting one message (messageId). Or open a web page (uri) or a file from your sandbox (path: markdown, text or code, an image, a PDF; line for text) in a tab beside this thread, without moving them. Use when you want them to look at something now. Rarely move their screen: only when they must look now.",
+    description: "Move the human's screen to a place in the workspace: a thread (threadId), a bot's DM (agent), optionally scrolled to and highlighting one message (messageId). Or open a web page (uri) or a document from your sandbox (path: markdown, html, text or code, a PDF; line for text) in a tab beside this thread, without moving them. Not for images: those go in post_message's `images`. A document the human should keep is better linked from a post (post_message uploads a sandbox path in a markdown link); show only when they must look now. Rarely move their screen.",
     inputSchema: z.object({
         threadId: z.string().optional().describe("Thread id, e.g. thr_0002."),
         agent: z.string().optional().describe("Open this bot's DM instead of a thread."),
         messageId: z.string().optional().describe("Also scroll to and highlight this message, like opening a link to it."),
         uri: z.string().optional().describe("An http(s) page to open beside the thread."),
-        path: z.string().optional().describe("A file in your sandbox to open beside the thread, e.g. /workspace/repo/PLAN.md."),
+        path: z.string().optional().describe("A document in your sandbox to open beside the thread, e.g. /workspace/repo/PLAN.md. Not an image."),
         line: z.number().int().positive().optional().describe("With path: the line a text or code file opens at."),
         reason: z.string().describe("One short line shown to the human, e.g. 'the plan is ready for review'."),
     }),
@@ -26,28 +25,12 @@ export default defineTool({
             throw new Error("pass path or uri, not both");
         if (line && !path)
             throw new Error("line goes with path");
+        if (path && IMAGE_FILE.test(path))
+            throw new Error(`${basename(path)} is an image: post it with post_message's images instead, so it shows in the thread`);
         let open = uri, title;
         if (path) {
             title = basename(path);
-            const sandbox = await ctx.getSandbox();
-            if (process.env.VERCEL || process.env.HUB_TOKEN) {
-                const bytes = await sandbox.readBinaryFile({ path });
-                if (!bytes)
-                    throw new Error(`no file at ${path}`);
-                const res = await registryFetch(`/api/uploads`, {
-                    method: "POST",
-                    headers: { "content-type": "application/octet-stream", "x-filename": encodeURIComponent(basename(path)) },
-                    body: new Uint8Array(bytes),
-                    signal: AbortSignal.timeout(30_000),
-                });
-                const body = await res.json().catch(() => ({}));
-                if (!res.ok)
-                    throw new Error(`show failed: the upload was refused (${body.error ?? res.status})`);
-                open = `hub://upload/${body.id}`;
-            }
-            else {
-                open = pathToFileURL(sandbox.resolvePath(path)).href;
-            }
+            open = await documentUrl(await ctx.getSandbox(), path, "show");
         }
         const res = await registryFetch(`/api/ui`, {
             method: "POST",

package/tools/view_image.js

@@ -1,6 +1,7 @@
 // The `view_image` tool: shows the bot an image so it can actually see it.
-// `read_file` only reads text and `attach_image` posts an image without the
-// bot seeing it, so without this a bot can take a screenshot but not check it.
+// `read_file` only reads text and post_message's `images` posts an image
+// without the bot seeing it, so without this a bot can take a screenshot but
+// not check it.
 // The bytes come from the bot's sandbox (a file path) or its browser (a
 // screenshot) and reach the model as an image part of the tool result.
 //
@@ -101,7 +102,7 @@ export function toModelOutput(output) {
     ]);
 }
 export default defineTool({
-    description: "Look at an image yourself: a PNG, JPEG, GIF, or WebP file from your sandbox (path), or a screenshot of your browser's current page (screenshot: true). The image comes back to you so you can see it and describe it. Use it to check screenshots and captures before you attach or report them; `read_file` can't read images and `attach_image` only posts them. Large images are scaled to 1568px on the long edge.",
+    description: "Look at an image yourself: a PNG, JPEG, GIF, or WebP file from your sandbox (path), or a screenshot of your browser's current page (screenshot: true). The image comes back to you so you can see it and describe it. Use it to check screenshots and captures before you post them (post_message `images`); `read_file` can't read images. Large images are scaled to 1568px on the long edge.",
     inputSchema: z.object({
         path: z.string().optional().describe("Image file in your sandbox, e.g. /tmp/shot.png."),
         screenshot: z.boolean().optional().describe("View a screenshot of your browser instead of a file."),

package/tools/attach_image.d.ts

@@ -1,16 +0,0 @@
-declare const _default: import("eve/tools").ToolDefinition<{
-    path?: string | undefined;
-    screenshot?: boolean | undefined;
-}, {
-    attachment: any;
-    note: string;
-}> & {
-    execute(input: {
-        path?: string | undefined;
-        screenshot?: boolean | undefined;
-    }, ctx: import("eve/tools").ToolContext): Promise<{
-        attachment: any;
-        note: string;
-    }>;
-};
-export default _default;

package/tools/attach_image.js

@@ -1,51 +0,0 @@
-// The `attach_image` tool: puts an image on the bot's reply. The bytes come
-// from the bot's own sandbox (a file path) or its browser (a screenshot) and
-// go to the registry's upload store; the registry posts them with the turn's
-// final message.
-import { basename } from "node:path";
-import { defineTool } from "eve/tools";
-import { z } from "zod";
-import { browserFor } from "../host-browser.js";
-import { registryFetch } from "../registry-fetch.mjs";
-export default defineTool({
-    description: "Attach an image to your reply in this thread: a PNG, JPEG, GIF, or WebP file from your sandbox (path), or a screenshot of your browser's current page (screenshot: true). Up to 3 MB each. It is posted with your final message for this turn, so mention what it shows there. Never write `![]()` for it.",
-    inputSchema: z.object({
-        path: z.string().optional().describe("Image file in your sandbox, e.g. /workspace/out/chart.png."),
-        screenshot: z.boolean().optional().describe("Attach a screenshot of your browser instead of a file."),
-    }),
-    async execute({ path, screenshot }, ctx) {
-        if (Boolean(path) === Boolean(screenshot))
-            throw new Error("pass exactly one of path or screenshot");
-        let bytes;
-        let name;
-        if (screenshot) {
-            const browser = await browserFor(ctx.session.id);
-            if (browser.url === "about:blank")
-                throw new Error("your browser has no page open; open one with the browser tool first");
-            bytes = await browser.screenshot();
-            name = "screenshot.png";
-        }
-        else {
-            const sandbox = await ctx.getSandbox();
-            const file = await sandbox.readBinaryFile({ path: path });
-            if (!file)
-                throw new Error(`no file at ${path}`);
-            bytes = file;
-            name = basename(path);
-        }
-        const res = await registryFetch(`/api/uploads`, {
-            method: "POST",
-            headers: { "content-type": "application/octet-stream", "x-filename": encodeURIComponent(name) },
-            body: new Uint8Array(bytes),
-            signal: AbortSignal.timeout(30_000),
-        }).catch((error) => {
-            throw new Error(`attach failed: the upload didn't finish (${error.message})`);
-        });
-        const body = await res.json().catch(() => ({}));
-        if (!res.ok)
-            throw new Error(`attach failed: ${body.error ?? res.status}`);
-        // The action.result stream event carries this reference on the exact turn
-        // that owns the call. Uploading bytes does not mutate session lifecycle.
-        return { attachment: body, note: "posts with your final message" };
-    },
-});