@bivy/bivy 0.18.9-staging.12 → 0.18.9-staging.13

package/dist/agent-instructions.js

@@ -12,36 +12,71 @@ import path from "node:path";
  * account-wide copy rides in the E2E model-auth vault envelope (see server.ts),
  * and a synced import stamps the file with the writer's timestamp so every
  * machine compares like with like. Clearing is an empty file, not a delete, so
- * the empty state carries a timestamp and propagates too.
+ * the empty state carries a timestamp and propagates too. The one switch beside
+ * the text — whether sessions also get the Bivy note — lives in a small sidecar
+ * file and shares that clock: flipping it rewrites AGENTS.md's timestamp.
  *
  * Delivery is the caller's business; this module only produces the composed
  * text (and a file holding it, for agents that take a path).
  */
 /** Cap on the editable text. It rides on every turn of every session. */
 export const MAX_AGENT_INSTRUCTIONS_BYTES = 16 * 1024;
+/**
+ * What every agent session is told about running under Bivy, whether or not the
+ * user wrote instructions: that the user is in a chat, and which `bivy` commands
+ * reach it. The commands read $BIVY_SESSION_ID (src/runtime/session-env.ts), so
+ * this works for any agent with a shell. Keep it short: it rides on every turn.
+ */
+export const BIVY_AGENT_NOTE = [
+    "You are running inside Bivy. The user follows this session in a chat app (web or phone): they cannot see your " +
+        "terminal or files you only write to disk. $BIVY_SESSION_ID identifies this session; the `bivy` commands below use it.",
+    "- Show a LOCAL file or image (report, screenshot, chart, a file they asked for): run " +
+        '`bivy attach <path> [--caption "short note"]`, or call the `attach_to_chat` tool if you have it. Images render ' +
+        "inline, other files as downloads; the path must be inside the session workspace. Markdown image syntax like " +
+        "![](path) does not render a local path. A REMOTE `https://` image in markdown does render.",
+    "- Something with a UI: `bivy app publish <manifest.json>` (a web server's port, a static build, a terminal) or " +
+        "`bivy app run -- <command>` (a desktop app) gives the user a live preview; `bivy app shot` screenshots it so you " +
+        "can check your work; `bivy app present` tells the user a visible change is ready to look at. " +
+        "`bivy app --help` has the details.",
+].join("\n");
 const PREAMBLE = "The user's global Bivy instructions follow. They apply to every workspace; where they conflict with " +
     "instructions from the current repository (AGENTS.md, CLAUDE.md, …), the repository's instructions win.";
 export function agentInstructionsPath(appDir) {
     return path.join(appDir, "AGENTS.md");
 }
+function optionsPath(appDir) {
+    return path.join(appDir, "agent-instructions.json");
+}
+function readBivyNote(appDir) {
+    try {
+        return JSON.parse(fs.readFileSync(optionsPath(appDir), "utf8")).bivyNote !== false;
+    }
+    catch {
+        return true;
+    }
+}
 function composedPath(appDir) {
     return path.join(appDir, "agent-instructions.composed.md");
 }
 export function readAgentInstructions(appDir) {
+    const bivyNote = readBivyNote(appDir);
     try {
         const file = agentInstructionsPath(appDir);
-        return { text: fs.readFileSync(file, "utf8"), updatedAt: Math.trunc(fs.statSync(file).mtimeMs) };
+        return { text: fs.readFileSync(file, "utf8"), updatedAt: Math.trunc(fs.statSync(file).mtimeMs), bivyNote };
     }
     catch {
-        return { text: "", updatedAt: 0 };
+        return { text: "", updatedAt: 0, bivyNote };
     }
 }
-export function writeAgentInstructions(appDir, text, updatedAt = Date.now()) {
+/** Write the text (and optionally the Bivy-note switch), stamped `updatedAt`. */
+export function writeAgentInstructions(appDir, text, updatedAt = Date.now(), bivyNote) {
     if (Buffer.byteLength(text, "utf8") > MAX_AGENT_INSTRUCTIONS_BYTES) {
         throw new Error(`Agent instructions are limited to ${MAX_AGENT_INSTRUCTIONS_BYTES / 1024} KB.`);
     }
     const file = agentInstructionsPath(appDir);
     fs.mkdirSync(appDir, { recursive: true });
+    if (bivyNote !== undefined)
+        fs.writeFileSync(optionsPath(appDir), `${JSON.stringify({ bivyNote })}\n`);
     fs.writeFileSync(file, text);
     fs.utimesSync(file, new Date(updatedAt), new Date(updatedAt));
     return readAgentInstructions(appDir);
@@ -51,6 +86,8 @@ export function writeAgentInstructions(appDir, text, updatedAt = Date.now()) {
  * - "imported": the synced copy was newer and is now the local file.
  * - "local-newer": this machine holds a newer copy the account should get.
  * - "unchanged": nothing to do.
+ * A synced copy without `bivyNote` comes from a peer that predates the switch,
+ * where the note was always on.
  */
 export function mergeSyncedAgentInstructions(appDir, incoming) {
     const local = readAgentInstructions(appDir);
@@ -58,26 +95,29 @@ export function mergeSyncedAgentInstructions(appDir, incoming) {
     if (typeof synced?.text !== "string" || typeof synced.updatedAt !== "number") {
         return local.updatedAt > 0 ? "local-newer" : "unchanged";
     }
-    if (synced.text === local.text)
+    const bivyNote = synced.bivyNote !== false;
+    if (synced.text === local.text && bivyNote === local.bivyNote)
         return "unchanged";
     if (synced.updatedAt > local.updatedAt) {
-        writeAgentInstructions(appDir, synced.text, synced.updatedAt);
+        writeAgentInstructions(appDir, synced.text, synced.updatedAt, bivyNote);
         return "imported";
     }
     return "local-newer";
 }
-/** Wrap the user's text in the precedence preamble; "" when there is nothing to send. */
-export function composeAgentInstructions(text) {
+/** The Bivy note (unless switched off), then the user's text (if any) under the precedence preamble. */
+export function composeAgentInstructions(text, bivyNote = true) {
     const body = text.trim();
-    return body ? `${PREAMBLE}\n\n${body}\n` : "";
+    return [bivyNote ? BIVY_AGENT_NOTE : "", body ? `${PREAMBLE}\n\n${body}` : ""].filter(Boolean).map((part) => `${part}\n`).join("\n");
 }
 /**
- * The instructions for a session starting now, or undefined when the user has
- * none. Keeps a composed copy on disk (rewritten only when it changes) for
+ * The instructions for a session starting now, or undefined when there is
+ * nothing to send (no text and the Bivy note switched off) or the file can't be
+ * written. Keeps a composed copy on disk (rewritten only when it changes) for
  * agents that take a file path rather than text.
  */
 export function sessionInstructions(appDir) {
-    const text = composeAgentInstructions(readAgentInstructions(appDir).text);
+    const { text: userText, bivyNote } = readAgentInstructions(appDir);
+    const text = composeAgentInstructions(userText, bivyNote);
     const file = composedPath(appDir);
     try {
         if (!text) {
@@ -86,6 +126,7 @@ export function sessionInstructions(appDir) {
             fs.rmSync(file, { force: true });
             return undefined;
         }
+        fs.mkdirSync(appDir, { recursive: true });
         let current;
         try {
             current = fs.readFileSync(file, "utf8");

package/dist/agents/claude-code/runtime.js

@@ -82,30 +82,6 @@ function brandClaudeModel(model) {
     const family = CLAUDE_MODEL_FAMILIES.find((f) => model.name === f || model.name.startsWith(`${f} `));
     return family ? { ...model, name: `Claude ${model.name}` } : model;
 }
-/**
- * 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.
- *
- * The chat still has no route to a LOCAL/workspace file path, so that half of the
- * guidance (use `bivy attach`, not markdown, for those) stands. A REMOTE
- * `https://` image URL is different: the node now fetches it server-side and
- * serves it back to the chat (see src/session/inline-image-fetch.ts, issue #293),
- * so plain markdown is the right tool there — `bivy attach` only works on files
- * already inside the workspace, which a URL by definition isn't.
- */
-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 has no route to a workspace file path. " +
-    "To show them a LOCAL 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) for a local file or workspace path — it will not render; " +
-    "always use `bivy attach` for those. A REMOTE image you already have a URL for is different: plain markdown " +
-    "`![alt](https://...)` renders it inline, no attach needed. Prefer `bivy attach` / markdown links 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>`. */
@@ -114,8 +90,8 @@ export const BIVY_ATTACH_MCP_SERVER_NAME = "bivy";
 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
+ * tool call (issue #291) — the stronger sibling of the Bivy note's
+ * `bivy attach` 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.
@@ -877,15 +853,11 @@ 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.
-            // 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.
-            // The user's account-wide instructions follow it; the repo's CLAUDE.md
-            // still loads through the preset as usual.
-            systemPrompt: { type: "preset", preset: "claude_code", append: [BIVY_ATTACH_SYSTEM_PROMPT, this.runtimeOptions.instructions].filter(Boolean).join("\n\n") },
+            // Keep the default Claude Code prompt, appending the session instructions:
+            // the Bivy note (how to reach the user's chat — `bivy attach`, previews)
+            // and the user's account-wide instructions. The repo's CLAUDE.md still
+            // loads through the preset as usual.
+            systemPrompt: { type: "preset", preset: "claude_code", ...(this.runtimeOptions.instructions ? { append: this.runtimeOptions.instructions } : {}) },
             ...(this.runtimeOptions.executablePath ? { pathToClaudeCodeExecutable: this.runtimeOptions.executablePath } : {}),
         };
         if (resumeId)
@@ -895,7 +867,7 @@ class ClaudeSession {
         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
+        // of the Bivy note's `bivy attach` line. 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.

package/dist/apps/styles.css

@@ -2863,6 +2863,8 @@ textarea.picker-search { resize: vertical; font-family: ui-monospace, monospace;
 .node-menu-glyph { color: var(--accent); flex: none; }
 .eph-steps { margin: 4px 0; padding-left: 18px; color: var(--muted); font-size: 13px; display: grid; gap: 4px; }
 .code-snippet { margin: 6px 0 0; overflow: auto; border: 1px solid var(--line); border-radius: var(--radius-md); padding: 10px; background: var(--surface); font-size: 12px; }
+/* Settings → Agent instructions: Bivy's note, wrapped to the sheet's width. */
+.agent-note-text { white-space: pre-wrap; overflow-wrap: anywhere; }
 select.picker-search { appearance: auto; }
 .node-menu-sep { height: 1px; background: var(--line); margin: 4px 0; }
 /* PrToast, UpdatePrompt (both `.update-toast`), and ErrorToast used to each

package/dist/runtime/session-env.js

@@ -4,7 +4,7 @@
 // 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
+// BIVY_AGENT_NOTE (src/agent-instructions.ts) 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.

package/dist/server.js

@@ -72,7 +72,7 @@ import { createSessionEngine } from "./session/engine.js";
 import { exportProviderAuth, exportAccountApiKeys, exportAccountOAuthCredentials, importAccountOAuthCredentials, exportSyncableProviderAuth, exportProviderAuthTombstones, importProviderAuth, removeProvider, setProviderApiKey, listCredentialRecords, setProviderApiKeyLabeled, setProviderReferenceLabeled, removeProviderCredential, setCredentialSync, setCredentialUnattended, exportUnattendedRecords, unattendedCredentialRevision, getCredentialPresets, setActiveCredentialPreset, setCredentialPresetMapping, exportSyncableRecords, exportRecordTombstones, importCredentialRecords, reconcileHostedCredentialRecords } from "./credentials/api.js";
 import { listProviders } from "./runtime/provider-catalog.js";
 import { exportLocalModels, importLocalModels } from "./runtime/local-model-store.js";
-import { mergeSyncedAgentInstructions, readAgentInstructions, sessionInstructions, writeAgentInstructions, MAX_AGENT_INSTRUCTIONS_BYTES } from "./agent-instructions.js";
+import { BIVY_AGENT_NOTE, mergeSyncedAgentInstructions, readAgentInstructions, sessionInstructions, writeAgentInstructions, MAX_AGENT_INSTRUCTIONS_BYTES } from "./agent-instructions.js";
 import { execEphemeralRequest } from "./ephemeral-exec.js";
 import { ApprovalManager } from "./approval.js";
 import { QuestionManager, validQuestions, isAskUserQuestionTool, formatQuestionResult } from "./question.js";
@@ -1374,7 +1374,7 @@ function nodeSettingsSnapshot() {
         autoAttachToolImages: readSettings().autoAttachToolImages === true,
         appScreenshots: appScreenshotsEnabled(),
         forkWorkspaceMaxBytes: Number.isInteger(readSettings().forkWorkspaceMaxBytes) ? Number(readSettings().forkWorkspaceMaxBytes) : 50 * 1024 * 1024,
-        agentInstructions: { ...readAgentInstructions(appDir), maxBytes: MAX_AGENT_INSTRUCTIONS_BYTES },
+        agentInstructions: { ...readAgentInstructions(appDir), maxBytes: MAX_AGENT_INSTRUCTIONS_BYTES, bivyNoteText: BIVY_AGENT_NOTE },
     };
 }
 async function applyNodeSettings(patch) {
@@ -1389,6 +1389,11 @@ async function applyNodeSettings(patch) {
         writeAgentInstructions(appDir, patch.agentInstructions);
         void pushModelAuthToControlPlane();
     }
+    // The Bivy-note switch syncs with the text: keep the text, stamp a new time.
+    if (typeof patch.agentInstructionsBivyNote === "boolean") {
+        writeAgentInstructions(appDir, readAgentInstructions(appDir).text, Date.now(), patch.agentInstructionsBivyNote);
+        void pushModelAuthToControlPlane();
+    }
     const settings = readSettings();
     if (typeof patch.name === "string" && patch.name.trim()) {
         const prev = identity.name;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.18.9-staging.12",
+  "version": "0.18.9-staging.13",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",