@bivy/bivy 0.4.0-staging.52 → 0.4.0-staging.54

package/bin/attach-session-id.mjs

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Pure session-id resolution for `bivy attach` (bin/bivy.mjs's cmdAttach),
+// extracted so it's unit-testable without executing the CLI.
+//
+// Every runtime adapter injects BIVY_SESSION_ID into its agent's subprocess env
+// (see src/runtime/session-env.ts) so `bivy attach <path>`, run from the agent's
+// own shell, can resolve its session without being told the id. Pi
+// (src/runtime/pi.ts) is the one exception: its agent loop runs in-process
+// rather than under a subprocess Bivy controls, so it has no hook to inject
+// BIVY_SESSION_ID into its own bash tool's env the way the other adapters do.
+// The pi-coding-agent SDK's bash tool already exposes PI_SESSION_ID to every
+// command it runs by default — and that id IS the Bivy session id for a pi
+// session (PiSession.id reads the exact same SessionManager the SDK reads it
+// from) — so it's accepted here as an equivalent fallback.
+export function resolveAttachSessionId({ sessionFlag, env } = {}) {
+  const flag = typeof sessionFlag === "string" ? sessionFlag.trim() : "";
+  if (flag) return flag;
+  const bivy = env?.BIVY_SESSION_ID?.trim?.();
+  if (bivy) return bivy;
+  const pi = env?.PI_SESSION_ID?.trim?.();
+  if (pi) return pi;
+  return undefined;
+}

package/bin/bivy.mjs

@@ -38,6 +38,7 @@ import { resolveSessionsLimit, truncateSavedSessions } from "./sessions-list.mjs
 import { renderManagedBlock, upsertManagedBlock, removeManagedBlock, rcFileForShell } from "./shim-path.mjs";
 import { removeExcept } from "./uninstall-paths.mjs";
 import { findAvailablePort, reconcilePort } from "./port-picker.mjs";
+import { resolveAttachSessionId } from "./attach-session-id.mjs";
 
 const selfScript = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(selfScript);
@@ -1977,16 +1978,19 @@ async function cmdSend(args = []) {
 // `bivy attach <file> [--caption "…"] [--session <id>]` — surface a file the
 // agent produced into the chat as an image/file attachment (the reverse of the
 // composer paperclip). The universal path: any agent that can run a shell command
-// can call this. The session id defaults to $BIVY_SESSION_ID, which the daemon
-// injects into the agent's subprocess env. The file is resolved to an absolute
-// path here (the CLI's cwd is the agent's workdir) and confined to the session
-// workspace server-side.
+// can call this. The session id defaults to $BIVY_SESSION_ID, which every
+// runtime adapter injects into the agent's subprocess env (see
+// src/runtime/session-env.ts) — except pi, whose SDK exposes its own
+// $PI_SESSION_ID instead (same id, different var name; see
+// resolveAttachSessionId). The file is resolved to an absolute path here (the
+// CLI's cwd is the agent's workdir) and confined to the session workspace
+// server-side.
 async function cmdAttach(args = []) {
   const flag = (name) => {
     const i = args.indexOf(name);
     return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
   };
-  const sessionId = flag("--session") || process.env.BIVY_SESSION_ID;
+  const sessionId = resolveAttachSessionId({ sessionFlag: flag("--session"), env: process.env });
   const caption = flag("--caption");
   const name = flag("--name");
   const mimeType = flag("--mime") || flag("--mimeType");

package/dist/runtime/claude-code.js

@@ -26,6 +26,7 @@ import { sandboxTier, claudePermissionModeFor } from "../harness/sandbox.js";
 import { anthropicCredentialPreflight, describeAnthropicError, isAnthropicAuthError } from "./anthropic-preflight.js";
 import { toModelInfo as sharedToModelInfo } from "./normalize.js";
 import { hasLiveProcessForCwd } from "./native-process-scan.js";
+import { bivySessionEnv } from "./session-env.js";
 /** Binary names a live Claude Code process could be running under (see
  *  native-process-scan.ts's best-effort cwd match). */
 const CLAUDE_BIN_NAMES = ["claude"];
@@ -56,6 +57,21 @@ const FALLBACK_MODELS = [
     { provider: "anthropic", id: "claude-sonnet-5", name: "Claude Sonnet 5", reasoning: true },
     { provider: "anthropic", id: "claude-haiku-4-5-20251001", name: "Claude Haiku 4.5", reasoning: true },
 ];
+/**
+ * Appended to the Claude Code system prompt so the agent DISCOVERS the outbound
+ * attachment capability. `bivy attach` is just a shell command — without this the
+ * agent has no way to know it exists and, when asked to "send a file", concludes
+ * it can't (it looks for a tool, finds none). BIVY_SESSION_ID is injected into the
+ * subprocess env (see spawnQuery), so the bare command resolves the session. Keep
+ * this short: it rides on every turn's system prompt.
+ */
+export const BIVY_ATTACH_SYSTEM_PROMPT = "Sending files and images to the user: the person you're talking to is in a chat UI. They cannot see files you only " +
+    "write to disk, and the chat cannot load remote image URLs or workspace file paths. " +
+    "To show them a file or image — a report, screenshot, chart, or a file they asked for — run " +
+    '`bivy attach <path> [--caption "short note"]` in your shell. ' +
+    "An image renders inline in the chat; any other file shows as a downloadable chip. The path must be inside the session " +
+    "workspace. Do NOT use markdown image syntax like ![](path) to show a local file or a URL — it will not render; always " +
+    "use `bivy attach`. Prefer this over pasting large file contents or describing where a file lives on disk.";
 export function claudeRuntimeFromEnv() {
     return {
         defaultModel: process.env.BIVY_CLAUDE_MODEL?.trim() || undefined,
@@ -673,9 +689,9 @@ class ClaudeSession {
         Object.assign(env, credEnv);
         // Let the agent's own shell surface a file into the chat via `bivy attach`
         // (POST /api/session/:id/attach). The session id is otherwise invisible to
-        // the subprocess. Other runtimes should set this the same way to enable the
-        // universal attach path for their agents.
-        env.BIVY_SESSION_ID = this.id;
+        // the subprocess. Shared with process.ts and protocol.ts via bivySessionEnv
+        // (see session-env.ts) so every CLI-spawning adapter injects it the same way.
+        Object.assign(env, bivySessionEnv(this.id));
         this.spawnedToken = authTokenFromEnv(credEnv);
         const options = {
             cwd: this.cwd,
@@ -688,6 +704,10 @@ class ClaudeSession {
             permissionMode,
             canUseTool,
             env,
+            // 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.
+            systemPrompt: { type: "preset", preset: "claude_code", append: BIVY_ATTACH_SYSTEM_PROMPT },
         };
         if (resumeId)
             options.resume = resumeId;

package/dist/runtime/pi.js

@@ -17,6 +17,7 @@ import { createPiModelRuntime } from "./pi-oauth.js";
 import { toModelInfo as sharedToModelInfo } from "./normalize.js";
 import { provisionPiAuthJson } from "./credential-provisioning.js";
 import { isNativeOAuthProvider } from "./oauth/model-oauth-providers.js";
+import { bivySessionEnv } from "./session-env.js";
 /**
  * Extract Pi's own slash commands from a live AgentSession: extension commands
  * (`pi.registerCommand`, exposed via `extensionRunner.getRegisteredCommands()`),
@@ -175,6 +176,17 @@ class PiSession {
      * daemon's own agent dir and session store (same files the SDK reads) and
      * resumes by session file, so the TUI shows the live conversation. Returns
      * null for an unsaved session (nothing to resume yet).
+     *
+     * This is also the one place PiSession spawns a subprocess Bivy itself
+     * configures, so it's where BIVY_SESSION_ID (see session-env.ts) is injected
+     * for this adapter. It does NOT cover the live-chat case (an agent turn
+     * running pi's own bash tool): pi's SDK runs its agent loop in-process and
+     * builds that tool's subprocess env internally, with no hook for a host to
+     * inject its own vars. That gap is closed differently — the SDK's bash tool
+     * already exposes PI_SESSION_ID to every command it runs, and that id IS the
+     * Bivy session id for a pi session (this.id reads the exact same
+     * SessionManager the SDK reads it from) — so `bivy attach` accepts
+     * PI_SESSION_ID as an equivalent fallback (see bin/attach-session-id.mjs).
      */
     async interactiveTuiCommand() {
         const file = this.sessionFile;
@@ -187,7 +199,7 @@ class PiSession {
         return {
             command: process.execPath,
             args: [this.tui.piCli, "--session", file, "--session-dir", this.tui.sessionsDir],
-            env: { PI_CODING_AGENT_DIR: this.tui.piDir },
+            env: { PI_CODING_AGENT_DIR: this.tui.piDir, ...bivySessionEnv(this.id) },
         };
     }
     prompt(text, options) {

package/dist/runtime/process.js

@@ -7,6 +7,7 @@ import { stripAnsi } from "./ansi.js";
 import { buildAgentCredentialEnv } from "./credentials.js";
 import { egressEnv } from "../harness/egress.js";
 import { depCacheEnv } from "../harness/dep-cache.js";
+import { bivySessionEnv } from "./session-env.js";
 /**
  * Send `signal` to `child`'s whole process group when possible, so a forking CLI
  * agent's grandchildren (it shells out to git/npm/build tools, or forks its own
@@ -279,7 +280,10 @@ class ProcessSession {
             cwd: this.cwd,
             // egressEnv() routes this agent's outbound traffic through the harness
             // network broker when BIVY_EGRESS_PROXY is enabled (else it's {}).
-            env: { ...process.env, ...depCacheEnv(), ...this.runtimeOptions.env, ...credentialEnv, ...prepareEnv, ...egressEnv() },
+            // bivySessionEnv() lets the agent's own shell resolve its session for
+            // `bivy attach <path>` (see session-env.ts); spread last so it can never
+            // be shadowed by an operator-configured env var of the same name.
+            env: { ...process.env, ...depCacheEnv(), ...this.runtimeOptions.env, ...credentialEnv, ...prepareEnv, ...egressEnv(), ...bivySessionEnv(this.id) },
             stdio: "pipe",
             // Detached so the child becomes the leader of its own process group
             // (POSIX) — see killProcessGroup() / abort() below, which kill that whole

package/dist/runtime/protocol.js

@@ -4,6 +4,7 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { buildAgentCredentialEnv } from "./credentials.js";
+import { bivySessionEnv } from "./session-env.js";
 import { extractTokenUsage } from "./cli-parsers.js";
 /** A protocol `usage` message → UsageSnapshot (reuses the CLI token-key scan). */
 function parseProtocolUsage(raw) {
@@ -258,7 +259,10 @@ class ProtocolSession {
             : {};
         const child = spawn(this.runtimeOptions.command, this.runtimeOptions.args ?? [], {
             cwd: this.cwd,
-            env: { ...process.env, ...this.runtimeOptions.env, ...credentialEnv },
+            // bivySessionEnv() lets the agent's own shell resolve its session for
+            // `bivy attach <path>` (see session-env.ts); spread last so it can never
+            // be shadowed by an operator-configured env var of the same name.
+            env: { ...process.env, ...this.runtimeOptions.env, ...credentialEnv, ...bivySessionEnv(this.id) },
             stdio: "pipe",
         });
         this.child = child;

package/dist/runtime/session-env.js

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Shared across every runtime adapter that spawns (or configures the spawn of) a
+// subprocess for its agent: fold this into that subprocess's env so the agent's
+// own shell can resolve its chat session without being told the id.
+// `bivy attach <path>` (bin/bivy.mjs's cmdAttach) reads $BIVY_SESSION_ID to know
+// which session to post an outbound attachment to — see
+// claude-code.ts's BIVY_ATTACH_SYSTEM_PROMPT for the discoverability half of this
+// feature (issue #288 shipped attach; issue #290 is making it universal). One
+// helper, one env-var name, so a new adapter can't independently invent — or
+// simply forget — its own convention.
+//
+// Used by claude-code.ts (spawnQuery), process.ts (ProcessSession.prompt), and
+// protocol.ts (ProtocolSession.start). pi.ts is the one exception: Pi runs its
+// agent loop in-process rather than spawning a subprocess Bivy controls, so it
+// has no hook to inject this into its bash tool's env the same way — see the
+// comment on PiSession.interactiveTuiCommand and bin/attach-session-id.mjs for
+// how that gap is closed instead.
+export function bivySessionEnv(sessionId) {
+    return { BIVY_SESSION_ID: sessionId };
+}

package/package.json

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