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

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

@@ -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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.5.1-staging.59",
+  "version": "0.5.1-staging.60",
   "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",