@bivy/bivy 0.5.1-staging.59 → 0.5.1-staging.61

package/bin/bivy.mjs

@@ -145,6 +145,7 @@ const attachEntry = path.join(repoRoot, packaged ? "dist/attach.js" : "src/attac
 const relayAttachEntry = path.join(repoRoot, packaged ? "dist/relay-attach.js" : "src/relay-attach.ts");
 const execEntry = path.join(repoRoot, packaged ? "dist/exec.js" : "src/exec.ts");
 const mcpProxyEntry = path.join(repoRoot, packaged ? "dist/harness/mcp-proxy-cli.js" : "src/harness/mcp-proxy-cli.ts");
+const mcpServeEntry = path.join(repoRoot, packaged ? "dist/harness/mcp-serve-cli.js" : "src/harness/mcp-serve-cli.ts");
 const qrEntry = path.join(repoRoot, "public", "qr.js");
 const tsxCli = packaged ? "" : path.join(repoRoot, "node_modules", "tsx", "dist", "cli.mjs");
 const nodeBin = process.execPath;
@@ -4360,6 +4361,13 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
       // agent's cwd so relative server commands resolve.
       await run(nodeBin, [...nodeScriptArgs(mcpProxyEntry), ...args], { cwd: process.cwd(), env: process.env });
       break;
+    case "mcp-serve":
+      // Bivy-owned MCP server (exposes attach_to_chat and future chat tools).
+      // Injected into a non-SDK agent's MCP config so the agent discovers the
+      // tool; like mcp-proxy its stdin/stdout ARE the JSON-RPC stream, so emit
+      // nothing else here and inherit stdio verbatim.
+      await run(nodeBin, [...nodeScriptArgs(mcpServeEntry), ...args], { cwd: process.cwd(), env: process.env });
+      break;
     case "help":
     case "-h":
     case "--help":

package/dist/harness/mcp-config-formats.js

@@ -15,6 +15,33 @@
 // exact original bytes on session end regardless. Pure string→string, unit-tested
 // in test/harness-mcp-formats.test.ts.
 import { PROXY_MARKER } from "./mcp-config.js";
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** True when a TOML config already declares `[mcp_servers.<name>]`. */
+export function hasTomlServer(content, name) {
+    return new RegExp(`^\\s*\\[mcp_servers\\.${escapeRegExp(name)}\\]\\s*$`, "m").test(content);
+}
+/**
+ * Append a `[mcp_servers.<name>]` table to a Codex TOML config (the reverse of
+ * routeThroughProxy's rewrite — this ADDS Bivy's own server rather than wrapping
+ * the agent's). Idempotent: returns `inserted: false` untouched when a table of
+ * that name already exists. Env is written as an inline table; string values are
+ * TOML-escaped via JSON.stringify (safe for the ASCII paths/ids we stamp).
+ */
+export function insertTomlServer(content, name, spec) {
+    if (hasTomlServer(content, name))
+        return { content, inserted: false };
+    const block = [`[mcp_servers.${name}]`, `command = ${JSON.stringify(spec.command)}`, `args = ${tomlStringArray(spec.args ?? [])}`];
+    if (spec.env && Object.keys(spec.env).length) {
+        const pairs = Object.entries(spec.env).map(([k, v]) => `${k} = ${JSON.stringify(v)}`);
+        block.push(`env = { ${pairs.join(", ")} }`);
+    }
+    // Separate from prior content with a blank line; keep a trailing newline.
+    const base = content.length === 0 || content.endsWith("\n") ? content : `${content}\n`;
+    const sep = base.length > 0 && !base.endsWith("\n\n") ? "\n" : "";
+    return { content: `${base}${sep}${block.join("\n")}\n`, inserted: true };
+}
 function proxyArgs(launcher, server, command, origArgs) {
     return [...(launcher.argsPrefix ?? []), PROXY_MARKER, "--server", server, "--", command, ...origArgs];
 }

package/dist/harness/mcp-config.js

@@ -85,6 +85,30 @@ export function parseProxiedArgs(args) {
     const tail = args.slice(sep + 1);
     return { server, command: tail[0], args: tail.slice(1) };
 }
+// ---------------------------------------------------------------------------
+// Bivy-owned tools server — the mirror of the proxy above. routeThroughProxy
+// wraps the agent's OWN servers; this ADDS a `bivy` server (run via `bivy
+// mcp-serve`) so the agent discovers Bivy's chat tools (attach_to_chat, …) in
+// its own tool list. Session id + node URL ride in its env so the tool can post
+// back to the right session.
+/** The server spec that launches `bivy mcp-serve` for a session. */
+export function bivyToolsServerSpec(opts) {
+    const env = { BIVY_SESSION_ID: opts.sessionId };
+    if (opts.endpoint)
+        env.BIVY_MCP_ENDPOINT = opts.endpoint;
+    return { command: opts.bivyCommand ?? "bivy", args: ["mcp-serve"], env };
+}
+/**
+ * Insert the Bivy tools server under `mcpServers.<name>` (default "bivy").
+ * Idempotent: an existing entry of that name is left untouched (returns
+ * `added: false`), so a re-inject or a user's own `bivy` server never doubles up.
+ */
+export function withBivyToolsServer(config, spec, name = "bivy") {
+    const servers = config.mcpServers ?? {};
+    if (servers[name])
+        return { config, added: false };
+    return { config: { ...config, mcpServers: { ...servers, [name]: spec } }, added: true };
+}
 /** JSON MCP-config file candidates for an agent, most-specific (safest) first. */
 export function agentMcpConfigTargets(agentId, ctx) {
     const ws = (...parts) => nodePath.join(ctx.workspace, ...parts);

package/dist/harness/mcp-inject.js

@@ -14,8 +14,8 @@
 // FS + network channels. Unit-tested in test/harness-mcp-inject.test.ts.
 import fs from "node:fs";
 import path from "node:path";
-import { agentMcpConfigTargets, routeThroughProxy, } from "./mcp-config.js";
-import { injectTomlMcp, injectYamlMcp } from "./mcp-config-formats.js";
+import { agentMcpConfigTargets, bivyToolsServerSpec, routeThroughProxy, withBivyToolsServer, } from "./mcp-config.js";
+import { injectTomlMcp, injectYamlMcp, insertTomlServer } from "./mcp-config-formats.js";
 /** The proxy launcher Bivy injects — `bivy mcp-proxy …`. */
 export function bivyProxyLauncher(bivyCommand = "bivy") {
     return { command: bivyCommand, argsPrefix: ["mcp-proxy"] };
@@ -110,6 +110,82 @@ export function injectMcpConfigFile(filePath, launcher) {
         },
     };
 }
+/**
+ * Add the `bivy` tools server (attach_to_chat …) to an agent's MCP config so the
+ * agent DISCOVERS it as a tool. Unlike the proxy inject (which only rewrites
+ * servers a file already has), this CREATES the config when absent so an agent
+ * that ships no MCP config still gets the tool. Handles the most-specific JSON
+ * config (session-local for claude/gemini/opencode/generic) and Codex's TOML
+ * (`~/.codex/config.toml` — Codex has no project-local option). restore() deletes
+ * a file it created and rewrites the exact original bytes of one it modified.
+ * Idempotent (a `bivy` server already present is a no-op, so concurrent sessions
+ * sharing a global config don't double up). Best-effort; never throws. Goose YAML
+ * is a follow-up.
+ */
+export function injectBivyToolsForSession(agentId, ctx, bivyCommand = "bivy") {
+    const target = agentMcpConfigTargets(agentId, ctx).find((t) => {
+        const ext = path.extname(t).toLowerCase();
+        return ext === ".json" || ext === ".toml";
+    });
+    if (!target)
+        return { injected: [], restore: () => { } };
+    const spec = bivyToolsServerSpec({ sessionId: ctx.sessionId, endpoint: ctx.endpoint, bivyCommand });
+    const ext = path.extname(target).toLowerCase();
+    const existed = fs.existsSync(target);
+    let original;
+    if (existed) {
+        try {
+            original = fs.readFileSync(target, "utf8");
+        }
+        catch {
+            return { injected: [], restore: () => { } };
+        }
+    }
+    let nextContent;
+    if (ext === ".json") {
+        let parsed = {};
+        if (original !== undefined) {
+            try {
+                parsed = JSON.parse(original);
+            }
+            catch {
+                // A config we can't parse is not ours to rewrite — leave it be.
+                return { injected: [], restore: () => { } };
+            }
+        }
+        const { config, added } = withBivyToolsServer(parsed, spec);
+        if (!added)
+            return { injected: [], restore: () => { } };
+        nextContent = `${JSON.stringify(config, null, 2)}\n`;
+    }
+    else {
+        const res = insertTomlServer(original ?? "", "bivy", { command: spec.command ?? bivyCommand, args: spec.args, env: spec.env });
+        if (!res.inserted)
+            return { injected: [], restore: () => { } };
+        nextContent = res.content;
+    }
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, nextContent);
+    }
+    catch {
+        return { injected: [], restore: () => { } };
+    }
+    return {
+        injected: [target],
+        restore: () => {
+            try {
+                if (existed && original !== undefined)
+                    fs.writeFileSync(target, original);
+                else
+                    fs.rmSync(target, { force: true });
+            }
+            catch {
+                // Restore is best-effort.
+            }
+        },
+    };
+}
 /**
  * Inject the proxy into every MCP config an agent reads for this session.
  * Returns the injected files and a single restore() covering all of them.

package/dist/harness/mcp-serve-cli.js

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Universal Agent Harness — `bivy mcp-serve` entry point.
+//
+// A Bivy-OWNED stdio MCP server (the mirror of `bivy mcp-proxy`, which wraps the
+// agent's OWN servers). Injected into every non-SDK agent's MCP config at session
+// start (see mcp-inject.ts's injectBivyToolsForSession), it exposes Bivy's chat
+// affordances as first-class tools so ANY agent — codex, gemini, aider, opencode,
+// … — discovers them in its tool list instead of having to be told about a shell
+// command (issue #290). Today it serves one tool, `attach_to_chat`.
+//
+// Claude and Pi already get `attach_to_chat` natively (in-process SDK MCP server /
+// integration ToolProvider); this covers everyone else. The tool just POSTs to the
+// node's existing `POST /api/session/:id/attach` endpoint — the exact plumbing
+// `bivy attach` uses — so it reuses the same workspace confinement, storage, and
+// live broadcast. The session id and node URL arrive via env (BIVY_SESSION_ID /
+// BIVY_MCP_ENDPOINT), stamped into the injected server spec.
+//
+// The attach client is factored out and unit-tested (test/harness-mcp-serve.test.ts)
+// with an injected fetch; the process/transport wiring is thin.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+const DEFAULT_ENDPOINT = "http://127.0.0.1:4317";
+/** The tools this server advertises, in MCP `tools/list` shape. */
+export const BIVY_MCP_TOOLS = [
+    {
+        name: "attach_to_chat",
+        description: "Send a file or image from the session workspace into the chat the user is reading. 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 workspace " +
+            "paths or remote image URLs. Use this to show them a report, screenshot, chart, or any file they asked for. An " +
+            "image renders inline; any other file shows as a downloadable chip. The path must be inside the session " +
+            "workspace. Prefer this over pasting large file contents, describing where a file lives, or markdown image " +
+            "syntax (which will not render).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file to send, inside the session workspace (absolute, or relative to it)." },
+                caption: { type: "string", description: "Optional short note shown with the attachment." },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+    },
+];
+/**
+ * Perform an `attach_to_chat` call by POSTing to the node's attach endpoint,
+ * which confines the path to the workspace, stores the bytes, and broadcasts the
+ * chip. Never throws — every failure is returned as `{ isError: true, text }` so
+ * the agent gets an actionable message instead of a broken tool.
+ */
+export async function runAttachToChat(endpoint, sessionId, args, fetchImpl, token) {
+    if (!sessionId)
+        return { isError: true, text: "No active Bivy session to attach to (BIVY_SESSION_ID is not set)." };
+    const filePath = typeof args.path === "string" ? args.path.trim() : "";
+    if (!filePath)
+        return { isError: true, text: "Provide a `path` to a file inside the session workspace." };
+    const caption = typeof args.caption === "string" ? args.caption : undefined;
+    const base = endpoint.replace(/\/+$/, "");
+    const headers = { "content-type": "application/json" };
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    let res;
+    try {
+        res = await fetchImpl(`${base}/api/session/${encodeURIComponent(sessionId)}/attach`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ path: filePath, caption }),
+        });
+    }
+    catch (error) {
+        return { isError: true, text: `Could not reach the Bivy node to attach the file: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || body?.ok === false) {
+        return { isError: true, text: `Attach failed: ${body?.error || `node returned ${res.status}`}` };
+    }
+    const name = body?.name || filePath;
+    return { isError: false, text: `Attached ${name} to the chat as ${body?.kind === "image" ? "an inline image" : "a downloadable file"}. The user can see it now.` };
+}
+/** Build the Bivy MCP `Server` with tools/list + tools/call handlers wired. */
+export function createBivyMcpServer(deps = {}) {
+    const endpoint = deps.endpoint ?? process.env.BIVY_MCP_ENDPOINT ?? DEFAULT_ENDPOINT;
+    const sessionId = deps.sessionId ?? process.env.BIVY_SESSION_ID ?? process.env.BIVY_MCP_SESSION ?? "";
+    const token = deps.token ?? process.env.BIVY_MCP_TOKEN ?? undefined;
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+    const server = new Server({ name: "bivy", version: "1.0.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: BIVY_MCP_TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        if (req.params.name !== "attach_to_chat") {
+            return { isError: true, content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }] };
+        }
+        const result = await runAttachToChat(endpoint, sessionId, (req.params.arguments ?? {}), fetchImpl, token);
+        return { isError: result.isError, content: [{ type: "text", text: result.text }] };
+    });
+    return server;
+}
+/** Connect the Bivy MCP server to stdio and serve until the stream closes. */
+export async function runMcpServeCli(deps = {}) {
+    const server = createBivyMcpServer(deps);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Resolves when the transport closes (agent disconnects / process is killed).
+    await new Promise((resolve) => transport.onclose = resolve);
+}
+// Run when invoked directly (via `bivy mcp-serve` → tsx this file). Emit nothing
+// to stdout except JSON-RPC — the transport owns stdin/stdout.
+const invokedDirectly = (() => {
+    try {
+        return Boolean(process.argv[1]) && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+})();
+if (invokedDirectly) {
+    void runMcpServeCli().catch((error) => {
+        process.stderr.write(`bivy mcp-serve: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    });
+}

package/dist/integrations/index.js

@@ -1,4 +1,4 @@
 // SPDX-License-Identifier: FSL-1.1-ALv2
 // Copyright (c) 2026 Petter André Sjulstad
 export { IntegrationManager } from "./manager.js";
-export { BUILT_IN_INTEGRATIONS } from "./registry.js";
+export { BUILT_IN_INTEGRATIONS, ATTACH_TO_CHAT_TOOL } from "./registry.js";

package/dist/integrations/manager.js

@@ -2,7 +2,7 @@
 // Copyright (c) 2026 Petter André Sjulstad
 import { randomUUID } from "node:crypto";
 import { IntegrationStore } from "./store.js";
-import { BUILT_IN_INTEGRATIONS } from "./registry.js";
+import { ATTACH_TO_CHAT_TOOL, BUILT_IN_INTEGRATIONS } from "./registry.js";
 import { buildAuthorizeUrl, createPkce, exchangeCode, refreshToken, } from "./oauth.js";
 import { SecretVault } from "../secrets.js";
 /**
@@ -10,9 +10,11 @@ import { SecretVault } from "../secrets.js";
  *
  * - REST handlers in server.ts call `list / connectApiKey / startOAuth /
  *   completeOAuth / disconnect`.
- * - `toolProvider()` exposes the connected integrations' tools as a
- *   runtime-agnostic ToolProvider handed to each session; the tools execute here
- *   on the daemon (where credentials live) for in-process AND remote agents alike.
+ * - `toolProvider()` exposes the connected integrations' tools — plus the
+ *   always-on `attach_to_chat` tool (issue #291), when the daemon wired an
+ *   `attachToChat` callback — as a runtime-agnostic ToolProvider handed to each
+ *   session; the tools execute here on the daemon (where credentials live) for
+ *   in-process AND remote agents alike.
  */
 export class IntegrationManager {
     store;
@@ -21,11 +23,15 @@ export class IntegrationManager {
     pending = new Map();
     /** Names of tools flagged risky (approval-gated), regardless of connection. */
     riskyTools;
-    constructor(appDir, registry = BUILT_IN_INTEGRATIONS) {
+    /** Backs the native `attach_to_chat` tool (see toolProvider); undefined = the
+     *  tool isn't offered (e.g. a test harness that never wired one). */
+    attachToChat;
+    constructor(appDir, registry = BUILT_IN_INTEGRATIONS, attachToChat) {
         this.store = new IntegrationStore(appDir);
         this.secrets = new SecretVault(appDir);
         this.registry = registry;
         this.riskyTools = new Set(registry.flatMap((d) => d.tools.filter((t) => t.risky).map((t) => t.name)));
+        this.attachToChat = attachToChat;
     }
     // --- helpers ------------------------------------------------------------
     def(id) {
@@ -236,15 +242,23 @@ export class IntegrationManager {
     }
     // --- agent-agnostic tool provider ---------------------------------------
     /**
-     * A runtime-agnostic ToolProvider exposing every connected integration's tools.
-     * This is the seam the daemon hands to a session (in-process OR remote) so any
-     * agent can use the tools without the IntegrationManager knowing which agent it
-     * is — the tools execute HERE, on the daemon, where the credentials/HTTP clients
-     * live. A snapshot of the connected set is taken per call (at session start),
-     * mirroring the previous per-session behavior; disconnected integrations
-     * contribute nothing, so the tool surface and system prompt stay clean.
+     * A runtime-agnostic ToolProvider exposing every connected integration's tools,
+     * plus the always-on `attach_to_chat` tool (issue #291) when this manager was
+     * built with an `attachToChat` callback. This is the seam the daemon hands to a
+     * session (in-process OR remote) so any agent can use the tools without the
+     * IntegrationManager knowing which agent it is — the tools execute HERE, on the
+     * daemon, where the credentials/HTTP clients live. A snapshot of the connected
+     * set is taken per call (at session start), mirroring the previous per-session
+     * behavior; disconnected integrations contribute nothing, so the tool surface
+     * and system prompt stay clean.
+     *
+     * `sessionIdRef` resolves the calling session for `attach_to_chat`: the
+     * provider is built before the session it will serve exists (see
+     * AttachToChatFn's doc), so the caller passes a box and fills `.current` in
+     * once the id is known rather than a plain string. Ignored (and the tool
+     * omitted) when either it or the attachToChat callback is absent.
      */
-    toolProvider() {
+    toolProvider(sessionIdRef) {
         const specs = [];
         const executors = new Map();
         for (const def of this.registry) {
@@ -266,6 +280,30 @@ export class IntegrationManager {
                 });
             }
         }
+        if (this.attachToChat && sessionIdRef) {
+            const attachToChat = this.attachToChat;
+            specs.push({
+                name: ATTACH_TO_CHAT_TOOL.name,
+                label: ATTACH_TO_CHAT_TOOL.label,
+                description: ATTACH_TO_CHAT_TOOL.description,
+                promptSnippet: ATTACH_TO_CHAT_TOOL.description,
+                parameters: ATTACH_TO_CHAT_TOOL.parameters,
+            });
+            executors.set(ATTACH_TO_CHAT_TOOL.name, async (params) => {
+                const sessionId = sessionIdRef.current;
+                if (!sessionId)
+                    return { content: [{ type: "text", text: "Session is not ready yet — try again in a moment." }], details: {}, isError: true };
+                const p = (params ?? {});
+                const filePath = typeof p.filePath === "string" ? p.filePath.trim() : "";
+                if (!filePath)
+                    return { content: [{ type: "text", text: "filePath is required" }], details: {}, isError: true };
+                const caption = typeof p.caption === "string" ? p.caption : undefined;
+                const result = attachToChat(sessionId, { filePath, caption });
+                if ("error" in result)
+                    return { content: [{ type: "text", text: result.error }], details: {}, isError: true };
+                return { content: [{ type: "text", text: `Attached ${result.ref.name} (${result.ref.kind}, ${result.ref.mimeType}) to the chat.` }], details: { ref: result.ref } };
+            });
+        }
         return {
             list: () => specs,
             invoke: async (toolName, _toolCallId, params, signal) => {

package/dist/integrations/registry.js

@@ -16,6 +16,29 @@ function toRfc822({ to, subject, body }) {
     const lines = [`To: ${to}`, `Subject: ${subject}`, "Content-Type: text/plain; charset=UTF-8", "", body];
     return Buffer.from(lines.join("\r\n")).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
+// ---------------------------------------------------------------------------
+// attach_to_chat (issue #291): the native, tool-based sibling of the CLI
+// `bivy attach <path>` / POST /api/session/:id/attach path #288 added. Unlike
+// the integrations below it needs no auth and isn't gated on a "connected"
+// account — every agent should always have it — so it's declared here as data
+// (name/description/schema, matching every other tool) but wired up by
+// IntegrationManager.toolProvider instead of BUILT_IN_INTEGRATIONS: its
+// executor needs the calling session's id (to push the attachment into the
+// right chat), which the `http`-only IntegrationToolDef.execute shape below
+// has no room for.
+// ---------------------------------------------------------------------------
+export const ATTACH_TO_CHAT_TOOL = {
+    name: "attach_to_chat",
+    label: "Attach to chat",
+    description: "Push a file or image from the session workspace into the chat as an attachment, exactly like the CLI `bivy attach` " +
+        "or the composer's paperclip upload but as a direct tool call. Use this — not markdown image syntax, not describing " +
+        "where a file lives — whenever the user should see a report, screenshot, chart, or a file they asked for; they " +
+        "cannot see files you only write to disk. The path must be inside the session workspace.",
+    parameters: Type.Object({
+        filePath: Type.String({ description: "Path to the file, absolute or relative to the session workspace." }),
+        caption: Type.Optional(Type.String({ description: "Short caption shown next to the attachment in the chat." })),
+    }),
+};
 export const BUILT_IN_INTEGRATIONS = [
     {
         id: "notion",

package/dist/runtime/claude-code.js

@@ -22,6 +22,7 @@ import fs from "node:fs";
 import { depCacheEnv } from "../harness/dep-cache.js";
 import os from "node:os";
 import path from "node:path";
+import { z } from "zod";
 import { sandboxTier, claudePermissionModeFor } from "../harness/sandbox.js";
 import { autoAttachToolImagesEnabled, PassiveImageBudget } from "../harness/tool-image-attachments.js";
 import { anthropicCredentialPreflight, describeAnthropicError, isAnthropicAuthError } from "./anthropic-preflight.js";
@@ -73,6 +74,46 @@ export const BIVY_ATTACH_SYSTEM_PROMPT = "Sending files and images to the user:
     "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.";
+/** 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>`. */
+export const BIVY_ATTACH_MCP_SERVER_NAME = "bivy";
+/** The tool's own name, unnamespaced (see BIVY_ATTACH_MCP_SERVER_NAME). */
+export const BIVY_ATTACH_TOOL_NAME = "attach_to_chat";
+/**
+ * Build the in-process MCP server that exposes `attach_to_chat` as a native
+ * tool call (issue #291) — the stronger sibling of BIVY_ATTACH_SYSTEM_PROMPT's
+ * shell-out hint: the agent sees this in its actual tool list instead of having
+ * to discover a shell command from prose. Bound to one session's id so the
+ * handler always attaches into the conversation that called it, regardless of
+ * how many Claude sessions this node is running concurrently.
+ *
+ * `sdk` is the already-loaded SDK module (see loadSdk) — `tool`/
+ * createSdkMcpServer are read off it dynamically for the same reason the rest
+ * of this adapter never imports SDK values statically: the package is
+ * optional, and a static import would force every Bivy install to have it.
+ * Returns undefined if this SDK build doesn't export the MCP builder helpers
+ * (older/trimmed installs) — the caller degrades to prompt-only discoverability.
+ */
+function buildAttachMcpServer(sdk, sessionId, attachToChat) {
+    if (typeof sdk?.tool !== "function" || typeof sdk?.createSdkMcpServer !== "function")
+        return undefined;
+    const attachTool = sdk.tool(BIVY_ATTACH_TOOL_NAME, "Push a file or image from the session workspace into the chat as an attachment, exactly like the CLI `bivy attach` " +
+        "or the composer's paperclip upload but as a direct tool call. Use this — not markdown image syntax, not describing " +
+        "where a file lives — whenever the user should see a report, screenshot, chart, or a file they asked for; they " +
+        "cannot see files you only write to disk. The path must be inside the session workspace.", {
+        filePath: z.string().describe("Path to the file, absolute or relative to the session workspace."),
+        caption: z.string().optional().describe("Short caption shown next to the attachment in the chat."),
+    }, async (args) => {
+        const result = attachToChat(sessionId, { filePath: args.filePath, caption: args.caption });
+        if ("error" in result)
+            return { content: [{ type: "text", text: result.error }], isError: true };
+        return {
+            content: [{ type: "text", text: `Attached ${result.ref.name} (${result.ref.kind}, ${result.ref.mimeType}) to the chat.` }],
+        };
+    });
+    return sdk.createSdkMcpServer({ name: BIVY_ATTACH_MCP_SERVER_NAME, tools: [attachTool] });
+}
 export function claudeRuntimeFromEnv() {
     return {
         defaultModel: process.env.BIVY_CLAUDE_MODEL?.trim() || undefined,
@@ -737,6 +778,9 @@ class ClaudeSession {
             // Keep the default Claude Code prompt, appending the note that teaches the
             // agent how to send a file to the user (`bivy attach`) — otherwise the
             // capability is undiscoverable and "send me X as an attachment" fails.
+            // Kept even when the native tool below is also registered: it's a cheap,
+            // harmless fallback for a shell/subprocess the agent spawns that can't
+            // reach the in-process MCP tool directly.
             systemPrompt: { type: "preset", preset: "claude_code", append: BIVY_ATTACH_SYSTEM_PROMPT },
         };
         if (resumeId)
@@ -745,6 +789,16 @@ class ClaudeSession {
             options.sessionId = this.id;
         if (this.desiredModel)
             options.model = this.desiredModel;
+        // Native attach_to_chat tool (issue #291) — the stronger, tool-based sibling
+        // of the system-prompt hint above. Wired only when the daemon handed us a
+        // callback (see ClaudeCodeRuntimeOptions.attachToChat); absent in a few
+        // deliberately minimal test harnesses, and gracefully degrades to the prompt
+        // hint alone if this SDK build lacks the MCP builder helpers.
+        if (this.runtimeOptions.attachToChat) {
+            const attachServer = buildAttachMcpServer(sdk, this.id, this.runtimeOptions.attachToChat);
+            if (attachServer)
+                options.mcpServers = { [BIVY_ATTACH_MCP_SERVER_NAME]: attachServer };
+        }
         const q = sdk.query({ prompt: this.input, options });
         this.query = q;
         void this.consume(q);

package/dist/runtime/index.js

@@ -1457,7 +1457,7 @@ export function makeRuntime(options) {
         case "claude-code-sdk":
             // Share the node's provider logins (the shared vault) so the user doesn't
             // re-auth Anthropic for this agent.
-            return new ClaudeCodeRuntime({ ...claudeRuntimeFromEnv(), credentials: createCredentialStore(options.credsDir), sandbox: options.sandbox });
+            return new ClaudeCodeRuntime({ ...claudeRuntimeFromEnv(), credentials: createCredentialStore(options.credsDir), sandbox: options.sandbox, attachToChat: options.attachToChat });
         default:
             // Every CLI agent in CLI_AGENT_SPECS is dispatched here as data — no per-id
             // case to maintain. Anything that isn't a known CLI agent throws below.

package/dist/server.js

@@ -55,7 +55,7 @@ import { evictToCap, dirSizeBytes } from "./harness/cache-evict.js";
 import { checkDiskAdmission } from "./harness/disk-admission.js";
 import { sandboxTier, setConfiguredSandboxTier, normalizeSandboxTier } from "./harness/sandbox.js";
 import { setConfiguredAutoAttachToolImages } from "./harness/tool-image-attachments.js";
-import { injectMcpProxyForSession } from "./harness/mcp-inject.js";
+import { injectMcpProxyForSession, injectBivyToolsForSession } from "./harness/mcp-inject.js";
 import { parseRepo, inferGitHubRepoFromWorkspace, isSharedCloneRoot, resolveGitHubToken, cloneOrUpdateRepo, resolveDefaultBaseRef, resolveBranchBaseRef, fetchOrigin } from "./repo-workspace.js";
 import { configureGitAuth, writeGitCredentialEndpoint } from "./git-auth.js";
 import { GitHubTaskPoller, resolveGitHubTaskConfig, buildTaskPrompt, buildResumePrompt, buildInteractiveResumePrompt, DEFAULT_ISSUE_INSTRUCTIONS, parseBivyDirectives, commitAll, pushBranch, mergeBaseIntoBranch, completeMerge, abortMerge, findOpenPullRequestForBranch, findPullRequestsForBranch, findMergedPullRequestForBranch, issueBranchName, getPullRequest, commentIssue, listOpenLabelledIssues, selectActionableIssues, getIssue, getIssueCommentBody, addLabel, removeLabel, announcePickup, } from "./github-tasks.js";
@@ -484,7 +484,7 @@ function resolveApproval(id, approved) {
     }
     return ok;
 }
-const integrations = new IntegrationManager(appDir);
+const integrations = new IntegrationManager(appDir, undefined, attachToChatForSession);
 const terminals = new TerminalManager();
 // Per-session agents: a node holds one AgentRuntime instance *per agent id*,
 // built lazily and cached, instead of a single global runtime. `defaultRuntimeId`
@@ -492,7 +492,7 @@ const terminals = new TerminalManager();
 // be swapped under a live conversation, so the agent is chosen at session creation
 // and fixed for that session's life; switching agents in the UI starts a new one.
 let defaultRuntimeId = (process.env.BIVY_RUNTIME ?? "pi").toLowerCase();
-const runtimeHost = new RuntimeHost({ credsDir, piDir, sessionsDir });
+const runtimeHost = new RuntimeHost({ credsDir, piDir, sessionsDir, attachToChat: attachToChatForSession });
 // In-session model reroute (docs/rulesets.md). Opt-in: set
 // BIVY_SESSION_MODEL_FALLBACK to a comma-separated model list and a session that
 // hits an exhausted-credits / rate-limit turn error swaps down the list (via the
@@ -1129,6 +1129,22 @@ function handlePassiveToolImage(record, event) {
         console.warn("[attachments] failed to store a passively-surfaced tool image:", result.error);
     }
 }
+/**
+ * Session-id-keyed wrapper around attachToChat, handed to runtime adapters as
+ * the `attachToChat` callback that backs each agent's native "attach to chat"
+ * tool surface (Claude's SDK tool, Pi's ToolProvider tool — issue #291). Those
+ * tools are wired at runtime/tool-provider construction time, before the
+ * specific session that will run them exists — a per-session circular
+ * dependency (build the tools -> need the session -> need the tools) — so the
+ * callback takes a session id and resolves the live record from openSessions
+ * when it actually fires, exactly like the HTTP endpoint below does by path.
+ */
+function attachToChatForSession(sessionId, opts) {
+    const record = openSessions.get(sessionId);
+    if (!record)
+        return { error: "Session not found" };
+    return attachToChat(record, opts);
+}
 function approvalModeFrom(value) {
     return value === "never" || value === "risky" || value === "always" || value === "autonomous" ? value : undefined;
 }
@@ -6825,7 +6841,9 @@ async function refreshRecordAfterTui(record) {
         record.unsubscribe = undefined;
         const rt = await ensureRuntimeAvailable(record.runtimeId);
         const workspace = record.worktree?.path || oldSession.cwd || record.workspace;
-        const runtimeSessionOptions = { workspace, toolProvider: integrations.toolProvider(), ...(rt.capabilities.toolInterception ? { toolInterceptor: guardianInterceptor } : {}) };
+        // Refreshing an EXISTING record: its id is already known, so attach_to_chat
+        // (see toolProvider's SessionIdRef doc) can be wired live, not deferred.
+        const runtimeSessionOptions = { workspace, toolProvider: integrations.toolProvider({ current: record.id }), ...(rt.capabilities.toolInterception ? { toolInterceptor: guardianInterceptor } : {}) };
         const { session, warning } = await runtimeHost.openSession(rt, { ...runtimeSessionOptions, sessionFile: record.sessionFile });
         record.session = session;
         record.sessionFile = session.sessionFile ?? record.sessionFile;
@@ -7340,7 +7358,12 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
         throw new Error(`Refusing to start a session in the shared clone root ${runtimeWorkspace} without an isolated worktree — ` +
             `this would collide with concurrent sessions on the same repo. Retry; if it persists the checkout may be busy.`);
     }
-    const runtimeSessionOptions = { workspace: runtimeWorkspace, toolProvider: integrations.toolProvider(), ...(rt.capabilities.toolInterception ? { toolInterceptor: guardianInterceptor } : {}) };
+    // A brand-new session's id isn't known until runtimeHost.{create,open}Session
+    // resolves below, but the ToolProvider (and its attach_to_chat tool) must be
+    // built now, up front — so hand it this box instead of a session id and fill
+    // `.current` in the moment `sessionId` is (see toolProvider's SessionIdRef doc).
+    const attachSessionIdRef = {};
+    const runtimeSessionOptions = { workspace: runtimeWorkspace, toolProvider: integrations.toolProvider(attachSessionIdRef), ...(rt.capabilities.toolInterception ? { toolInterceptor: guardianInterceptor } : {}) };
     // Stage 2/3: prefer re-attaching to a still-live remote session — routed to its
     // OWN agent service — over re-opening a fresh copy from disk. Falls back to
     // open/create when nothing live is there.
@@ -7358,6 +7381,10 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
             ? await runtimeHost.openSession(rt, { ...runtimeSessionOptions, sessionFile: requestedSessionFile })
             : await runtimeHost.createSession(rt, runtimeSessionOptions));
     const sessionId = session.id;
+    // Now that it's known, unblock any attach_to_chat call this session's agent
+    // makes (see attachSessionIdRef above) — set synchronously, well before any
+    // prompt (and so any tool call) can reach this session.
+    attachSessionIdRef.current = sessionId;
     // Resuming an existing session: restore Bivy's canonical name onto the runtime
     // session when the runtime didn't itself (the Claude Code adapter resumes by id
     // and starts nameless). Without this getName() is undefined, so opening a
@@ -7411,6 +7438,36 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
             // Injection is best-effort; never block session creation.
         }
     }
+    // Bivy-owned tools (attach_to_chat, …): make them discoverable to non-SDK
+    // agents by adding a `bivy` server (run via `bivy mcp-serve`) to the agent's
+    // config. Default-on (not gated on BIVY_MCP_PROXY) — it only ADDS a safe,
+    // session-scoped, restored capability the agent already has via env, so the
+    // chat can receive files. Claude/Pi expose these natively (in-process SDK MCP
+    // server / integration ToolProvider), so the tool-interception runtimes are
+    // skipped to avoid a duplicate registration.
+    if (!rt.capabilities.toolInterception) {
+        try {
+            const res = injectBivyToolsForSession(rt.id, {
+                workspace: sessionWorkspace,
+                home: os.homedir(),
+                sessionId,
+                endpoint: process.env.BIVY_MCP_ENDPOINT,
+            });
+            if (res.injected.length) {
+                const prev = record.mcpRestore;
+                record.mcpRestore = () => { try {
+                    res.restore();
+                }
+                finally {
+                    prev?.();
+                } };
+                console.log(`MCP tools: added bivy server to ${res.injected.length} config(s) for session ${sessionId}`);
+            }
+        }
+        catch {
+            // Best-effort; never block session creation.
+        }
+    }
     rememberSession(record);
     rememberWorkspace(sessionWorkspace);
     attachSessionListeners(record);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.5.1-staging.59",
+  "version": "0.5.1-staging.61",
   "type": "module",
   "license": "FSL-1.1-ALv2",
   "description": "Run coding agents on machines you own. Source-available, self-hostable agent workspace.",
@@ -37,7 +37,8 @@
     "express": "^5.2.1",
     "node-pty": "^1.1.0",
     "typebox": "^1.3.6",
-    "ws": "^8.21.1"
+    "ws": "^8.21.1",
+    "zod": "^4.0.0"
   },
   "overrides": {
     "@hono/node-server": "2.0.12",