@bivy/bivy 0.18.9-staging.4 → 0.18.9-staging.5

package/bin/codex-app-server-shim.mjs

@@ -478,6 +478,9 @@ function threadParams(msg, extra = {}) {
     approvalPolicy: APPROVAL_POLICY,
     sandbox: SANDBOX_MODE,
     ...(selectedModel ? { model: selectedModel } : {}),
+    // The user's account-wide Bivy instructions ride as developer instructions,
+    // alongside (not instead of) the AGENTS.md files Codex loads itself.
+    ...(typeof msg.instructions === "string" && msg.instructions ? { developerInstructions: msg.instructions } : {}),
     ...extra,
   };
 }

package/dist/agent-instructions.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Account-wide agent instructions: one Markdown file of the user's global
+ * preferences, handed to every agent session IN ADDITION to the repo's own
+ * AGENTS.md/CLAUDE.md (which the agent keeps loading itself).
+ *
+ * The source of truth on a machine is `<appDir>/AGENTS.md` — plain Markdown the
+ * user can also edit by hand. Its mtime is the last-writer-wins clock: the
+ * 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.
+ *
+ * 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;
+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 composedPath(appDir) {
+    return path.join(appDir, "agent-instructions.composed.md");
+}
+export function readAgentInstructions(appDir) {
+    try {
+        const file = agentInstructionsPath(appDir);
+        return { text: fs.readFileSync(file, "utf8"), updatedAt: Math.trunc(fs.statSync(file).mtimeMs) };
+    }
+    catch {
+        return { text: "", updatedAt: 0 };
+    }
+}
+export function writeAgentInstructions(appDir, text, updatedAt = Date.now()) {
+    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 });
+    fs.writeFileSync(file, text);
+    fs.utimesSync(file, new Date(updatedAt), new Date(updatedAt));
+    return readAgentInstructions(appDir);
+}
+/**
+ * Reconcile a synced copy with the local file (last writer wins).
+ * - "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.
+ */
+export function mergeSyncedAgentInstructions(appDir, incoming) {
+    const local = readAgentInstructions(appDir);
+    const synced = incoming && typeof incoming === "object" ? incoming : undefined;
+    if (typeof synced?.text !== "string" || typeof synced.updatedAt !== "number") {
+        return local.updatedAt > 0 ? "local-newer" : "unchanged";
+    }
+    if (synced.text === local.text)
+        return "unchanged";
+    if (synced.updatedAt > local.updatedAt) {
+        writeAgentInstructions(appDir, synced.text, synced.updatedAt);
+        return "imported";
+    }
+    return "local-newer";
+}
+/** Wrap the user's text in the precedence preamble; "" when there is nothing to send. */
+export function composeAgentInstructions(text) {
+    const body = text.trim();
+    return body ? `${PREAMBLE}\n\n${body}\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
+ * agents that take a file path rather than text.
+ */
+export function sessionInstructions(appDir) {
+    const text = composeAgentInstructions(readAgentInstructions(appDir).text);
+    const file = composedPath(appDir);
+    try {
+        if (!text) {
+            // An MCP server spec injected earlier may still point here; don't let it
+            // serve instructions the user has since cleared.
+            fs.rmSync(file, { force: true });
+            return undefined;
+        }
+        let current;
+        try {
+            current = fs.readFileSync(file, "utf8");
+        }
+        catch { /* not written yet */ }
+        if (current !== text)
+            fs.writeFileSync(file, text);
+        return { text, file };
+    }
+    catch (error) {
+        // Never block a session on this; it just starts without them.
+        console.warn("[agent-instructions] could not prepare instructions:", error.message);
+        return undefined;
+    }
+}

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

@@ -880,7 +880,9 @@ class ClaudeSession {
             // 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 },
+            // 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") },
             ...(this.runtimeOptions.executablePath ? { pathToClaudeCodeExecutable: this.runtimeOptions.executablePath } : {}),
         };
         if (resumeId)
@@ -1511,12 +1513,12 @@ export class ClaudeCodeRuntime {
         return [{ id: "anthropic", name: "Anthropic", oauth: true, models: FALLBACK_MODELS }];
     }
     async createSession(options) {
-        const session = new ClaudeSession(await withSessionCredentials(this.options, options.credentialLabels), options.workspace, options.toolInterceptor, options.toolProvider);
+        const session = new ClaudeSession({ ...(await withSessionCredentials(this.options, options.credentialLabels)), instructions: options.instructions?.text }, options.workspace, options.toolInterceptor, options.toolProvider);
         this.sessions.push(session);
         return { session };
     }
     async openSession(options) {
-        const session = new ClaudeSession(await withSessionCredentials(this.options, options.credentialLabels), options.workspace, options.toolInterceptor, options.toolProvider, options.sessionFile);
+        const session = new ClaudeSession({ ...(await withSessionCredentials(this.options, options.credentialLabels)), instructions: options.instructions?.text }, options.workspace, options.toolInterceptor, options.toolProvider, options.sessionFile);
         this.sessions.push(session);
         return {
             session,

package/dist/agents/pi/runtime.js

@@ -459,6 +459,9 @@ export class PiRuntime {
                 modelRuntime,
                 resourceLoaderOptions: {
                     extensionFactories: [guardianFactory(sessionId, options.toolInterceptor), ...providedTools],
+                    // Additive: keep whatever Pi discovered itself, then the user's
+                    // account-wide instructions (see OpenSessionOptions.instructions).
+                    ...(options.instructions ? { appendSystemPromptOverride: (base) => [...base, options.instructions.text] } : {}),
                 },
             });
             // Override only the built-in bash definition. Pi still owns rendering,

package/dist/agents/profiles.js

@@ -48,6 +48,9 @@ export const AGENT_PROFILES = {
         // `opencode run -s <id> "<prompt>"` continues a prior session by its own id
         // (`-s, --session  session id to continue`, per `opencode run --help`).
         resume: { template: ["run", "-s", "{id}"] },
+        // OPENCODE_CONFIG_CONTENT is merged over OpenCode's own config; its
+        // `instructions` entries are loaded alongside the repo's AGENTS.md.
+        instructions: { env: { OPENCODE_CONFIG_CONTENT: '{"instructions":["{fileJson}"]}' } },
         // `opencode run --model <provider/model> "<prompt>"` — the flag follows the
         // `run` subcommand (insertAt: 1). Models are `provider/model` ids.
         model: {

package/dist/harness/mcp-config.js

@@ -97,6 +97,10 @@ export function bivyToolsServerSpec(opts) {
     const env = { BIVY_SESSION_ID: opts.sessionId };
     if (opts.endpoint)
         env.BIVY_MCP_ENDPOINT = opts.endpoint;
+    // The user's account-wide instructions, advertised as the server's MCP
+    // `instructions` — the best-effort channel for agents with no native one.
+    if (opts.instructionsFile)
+        env.BIVY_AGENT_INSTRUCTIONS_FILE = opts.instructionsFile;
     return { command: opts.bivyCommand ?? "bivy", args: ["mcp-serve"], env };
 }
 /**

package/dist/harness/mcp-inject.js

@@ -136,7 +136,7 @@ export function injectBivyToolsForSession(agentId, ctx, bivyCommand = "bivy") {
     });
     if (!target)
         return { injected: [], restore: () => { } };
-    const spec = bivyToolsServerSpec({ sessionId: ctx.sessionId, endpoint: ctx.endpoint, bivyCommand });
+    const spec = bivyToolsServerSpec({ sessionId: ctx.sessionId, endpoint: ctx.endpoint, bivyCommand, instructionsFile: ctx.instructionsFile });
     const ext = path.extname(target).toLowerCase();
     const openCode = agentId === "opencode" || isOpenCodeConfigFile(target);
     const existed = fs.existsSync(target);

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

@@ -20,6 +20,7 @@
 // with an injected fetch; the process/transport wiring is thin. Deliberately do
 // not expose governed Runs here: agents should use their native sub-agent tools,
 // which stay inside the parent Session instead of cluttering the Session list.
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -88,13 +89,25 @@ export async function runAttachToChat(endpoint, sessionId, args, fetchImpl, toke
     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.` };
 }
+/** The user's instructions to advertise at initialize, or undefined when there are none. */
+function readInstructions(file) {
+    if (!file)
+        return undefined;
+    try {
+        return fs.readFileSync(file, "utf8").trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** 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: {} } });
+    const instructions = readInstructions(deps.instructionsFile ?? process.env.BIVY_AGENT_INSTRUCTIONS_FILE);
+    const server = new Server({ name: "bivy", version: "1.0.0" }, { capabilities: { tools: {} }, ...(instructions ? { instructions } : {}) });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: BIVY_MCP_TOOLS }));
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const args = (req.params.arguments ?? {});

package/dist/runtime/agent-service.js

@@ -135,8 +135,8 @@ export class AgentService {
             const toolProvider = message.options.toolSpecs?.length ? this.makeToolProvider(svc, message.options.toolSpecs) : undefined;
             const workspace = message.options.workspace ?? process.cwd();
             const result = message.op === "open" && message.options.sessionFile
-                ? await runtime.openSession({ workspace, credentialLabels: message.options.credentialLabels, sessionFile: message.options.sessionFile, toolInterceptor, toolProvider })
-                : await runtime.createSession({ workspace, credentialLabels: message.options.credentialLabels, toolInterceptor, toolProvider });
+                ? await runtime.openSession({ workspace, credentialLabels: message.options.credentialLabels, sessionFile: message.options.sessionFile, toolInterceptor, toolProvider, instructions: message.options.instructions })
+                : await runtime.createSession({ workspace, credentialLabels: message.options.credentialLabels, toolInterceptor, toolProvider, instructions: message.options.instructions });
             svc.session = result.session;
             svc.id = result.session.id;
             svc.lastSent = this.mirror(result.session);

package/dist/runtime/index.js

@@ -643,6 +643,7 @@ function acpRuntimeOptions(opts) {
         // An ACP-promoted opencode still surfaces/expands its on-disk commands (the
         // ACP handshake doesn't carry them); a bare ACP agent has none.
         ...(slashCommands ? { slashCommands } : {}),
+        ...(opts.instructionsEnv ? { instructionsEnv: opts.instructionsEnv } : {}),
         ...(opts.credsDir ? { credentials: createCredentialStore(opts.credsDir) } : {}),
         // Declared credential behaviors apply to the governed path exactly as they do
         // to the pipe path: the preflight surfaces a clear no-credential error before
@@ -1147,6 +1148,7 @@ function makeCliRuntime(id, options, spec) {
             ...(spec.authOwner && spec.authOwner !== "agent" ? { credsDir: options.credsDir } : {}),
             sandbox: options.sandbox,
             mcpConfig: options.mcpConfig,
+            instructionsEnv: spec.instructions?.env,
         }));
     }
     const structured = executionMode === "structured-pipe";
@@ -1264,6 +1266,7 @@ function makeCliRuntime(id, options, spec) {
         thinking: cliThinkingConfig(id, spec),
         usageReporting: cliUsageReporting(spec),
         slashCommands: cliSlashCommands(spec),
+        ...(spec.instructions ? { instructionsEnv: spec.instructions.env } : {}),
         ...resumeOpts,
         ...nativeSessionOpts,
     });

package/dist/runtime/process.js

@@ -8,7 +8,7 @@ import { buildAgentCredentialEnv } from "./credentials.js";
 import { withSessionCredentials, credentialEnvFallback } from "../credentials/session.js";
 import { egressEnv, sessionEgressEnv } from "../harness/egress.js";
 import { depCacheEnv } from "../harness/dep-cache.js";
-import { bivySessionEnv } from "./session-env.js";
+import { bivySessionEnv, withSessionInstructions } from "./session-env.js";
 import { withExactCapabilitySurface } from "./types.js";
 /**
  * Send `signal` to `child`'s whole process group when possible, so a forking CLI
@@ -539,7 +539,7 @@ export class ProcessRuntime {
         return [...byProvider.values()];
     }
     async createSession(options) {
-        const session = new ProcessSession(await withSessionCredentials(this.options, options.credentialLabels), options.workspace);
+        const session = new ProcessSession(withSessionInstructions(await withSessionCredentials(this.options, options.credentialLabels), options.instructions), options.workspace);
         this.sessions.push(session);
         return { session, warning: "Generic CLI runtime streams stdout/stderr only; approvals, model picker, and resume depend on the underlying agent protocol." };
     }
@@ -547,7 +547,7 @@ export class ProcessRuntime {
         // Resumable runtimes bind the agent's session id so each prompt continues it
         // (see resumeArgs); non-resumable ones ignore the ref and start fresh.
         if (this.options.resumable) {
-            const session = new ProcessSession(await withSessionCredentials(this.options, options.credentialLabels), options.workspace, options.sessionFile);
+            const session = new ProcessSession(withSessionInstructions(await withSessionCredentials(this.options, options.credentialLabels), options.instructions), options.workspace, options.sessionFile);
             this.sessions.push(session);
             return { session };
         }

package/dist/runtime/protocol.js

@@ -5,7 +5,7 @@ import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { buildAgentCredentialEnv } from "./credentials.js";
 import { withSessionCredentials, credentialEnvFallback } from "../credentials/session.js";
-import { bivySessionEnv } from "./session-env.js";
+import { bivySessionEnv, withSessionInstructions } from "./session-env.js";
 import { mergeAgentCommands } from "./slash-commands.js";
 import { withExactCapabilitySurface } from "./types.js";
 import { extractTokenUsage } from "./cli-parsers.js";
@@ -157,6 +157,7 @@ class ProtocolSession {
     cwd;
     capabilitiesRef;
     toolInterceptor;
+    instructions;
     id;
     child;
     buffer = "";
@@ -225,11 +226,15 @@ class ProtocolSession {
     // taking the ref as its id — otherwise the daemon persists a SECOND metadata
     // row keyed by the ref, duplicating the conversation. Falls back to the ref,
     // then a fresh UUID, preserving the prior behaviour when no id is supplied.
-    canonicalId) {
+    canonicalId, 
+    // The user's account-wide instructions (OpenSessionOptions.instructions),
+    // sent on session.create/session.resume for the shim to hand its agent.
+    instructions) {
         this.runtimeOptions = runtimeOptions;
         this.cwd = cwd;
         this.capabilitiesRef = capabilitiesRef;
         this.toolInterceptor = toolInterceptor;
+        this.instructions = instructions;
         this.id = canonicalId || resumeRef || randomUUID();
         this.resumeRef = resumeRef;
         if (resumeRef) {
@@ -891,12 +896,15 @@ class ProtocolSession {
         // resume.
         const resumeRef = this.resumeRef ?? this.runtimeSessionRef;
         const created = resumeRef && this.capabilitiesRef.resume
-            ? await this.command("session.resume", { workspace: this.cwd, sessionId: this.id, runtimeSessionRef: resumeRef, resumeRef })
-            : await this.command("session.create", { workspace: this.cwd, sessionId: this.id });
+            ? await this.command("session.resume", { workspace: this.cwd, sessionId: this.id, runtimeSessionRef: resumeRef, resumeRef, ...this.instructionsField() })
+            : await this.command("session.create", { workspace: this.cwd, sessionId: this.id, ...this.instructionsField() });
         if (typeof created.runtimeSessionRef === "string")
             this.runtimeSessionRef = created.runtimeSessionRef;
         this.started = true;
     }
+    instructionsField() {
+        return this.instructions ? { instructions: this.instructions } : {};
+    }
     async prompt(text, options) {
         const wasStarted = this.started;
         await this.open();
@@ -1039,7 +1047,7 @@ export class ProtocolRuntime {
         return this.options.catalog ?? [];
     }
     async createSession(options) {
-        const session = new ProtocolSession(await withSessionCredentials(this.options, options.credentialLabels), options.workspace, this.capabilities, options.toolInterceptor);
+        const session = new ProtocolSession(withSessionInstructions(await withSessionCredentials(this.options, options.credentialLabels), options.instructions), options.workspace, this.capabilities, options.toolInterceptor, undefined, undefined, options.instructions?.text);
         try {
             await session.start();
             this.sessions.push(session);
@@ -1056,7 +1064,7 @@ export class ProtocolRuntime {
         // Adopt the caller's canonical id (a reopen of a known session) so the
         // resumed session keeps its original id instead of taking `sessionFile` (the
         // agent's own ref) as its id — see OpenSessionOptions.canonicalId.
-        const session = new ProtocolSession(await withSessionCredentials(this.options, options.credentialLabels), options.workspace, this.capabilities, options.toolInterceptor, options.sessionFile, options.canonicalId);
+        const session = new ProtocolSession(withSessionInstructions(await withSessionCredentials(this.options, options.credentialLabels), options.instructions), options.workspace, this.capabilities, options.toolInterceptor, options.sessionFile, options.canonicalId, options.instructions?.text);
         try {
             await session.start();
             if (!this.options.resumable && !this.capabilities.resume) {

package/dist/runtime/remote.js

@@ -543,12 +543,12 @@ export class RemoteRuntime {
     async createSession(options) {
         const transport = await this.config.connect();
         const toolSpecs = options.toolProvider?.list();
-        return startRemoteSession(transport, { runtime: this.id, sandbox: this.config.sandbox, op: "create", options: { credentialLabels: options.credentialLabels, workspace: options.workspace, hasToolInterceptor: Boolean(options.toolInterceptor), ...(toolSpecs?.length ? { toolSpecs } : {}) } }, { toolInterceptor: options.toolInterceptor, toolProvider: options.toolProvider });
+        return startRemoteSession(transport, { runtime: this.id, sandbox: this.config.sandbox, op: "create", options: { credentialLabels: options.credentialLabels, workspace: options.workspace, ...(options.instructions ? { instructions: options.instructions } : {}), hasToolInterceptor: Boolean(options.toolInterceptor), ...(toolSpecs?.length ? { toolSpecs } : {}) } }, { toolInterceptor: options.toolInterceptor, toolProvider: options.toolProvider });
     }
     async openSession(options) {
         const transport = await this.config.connect();
         const toolSpecs = options.toolProvider?.list();
-        return startRemoteSession(transport, { runtime: this.id, sandbox: this.config.sandbox, op: "open", options: { credentialLabels: options.credentialLabels, workspace: options.workspace, sessionFile: options.sessionFile, hasToolInterceptor: Boolean(options.toolInterceptor), ...(toolSpecs?.length ? { toolSpecs } : {}) } }, { toolInterceptor: options.toolInterceptor, toolProvider: options.toolProvider });
+        return startRemoteSession(transport, { runtime: this.id, sandbox: this.config.sandbox, op: "open", options: { credentialLabels: options.credentialLabels, workspace: options.workspace, sessionFile: options.sessionFile, ...(options.instructions ? { instructions: options.instructions } : {}), hasToolInterceptor: Boolean(options.toolInterceptor), ...(toolSpecs?.length ? { toolSpecs } : {}) } }, { toolInterceptor: options.toolInterceptor, toolProvider: options.toolProvider });
     }
     /**
      * Re-attach to a session already live on the agent service (Stage 2 routing).

package/dist/runtime/session-env.js

@@ -1,5 +1,3 @@
-// SPDX-License-Identifier: AGPL-3.0-only
-// 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
@@ -20,3 +18,21 @@
 export function bivySessionEnv(sessionId) {
     return { BIVY_SESSION_ID: sessionId };
 }
+/**
+ * Apply a profile's instructions env template (AgentProfile.instructions) for one
+ * session: `{file}` → the composed instructions file, `{fileJson}` → the same
+ * path escaped for use inside a JSON string. A variable the operator already set
+ * is left alone rather than clobbered. No template or no instructions = options
+ * returned unchanged.
+ */
+export function withSessionInstructions(options, instructions) {
+    if (!options.instructionsEnv || !instructions)
+        return options;
+    const patch = {};
+    for (const [name, template] of Object.entries(options.instructionsEnv)) {
+        if (process.env[name] !== undefined || options.env?.[name] !== undefined)
+            continue;
+        patch[name] = template.replace(/\{fileJson\}/g, JSON.stringify(instructions.file).slice(1, -1)).replace(/\{file\}/g, instructions.file);
+    }
+    return { ...options, env: { ...options.env, ...patch } };
+}

package/dist/server.js

@@ -72,6 +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 { execEphemeralRequest } from "./ephemeral-exec.js";
 import { ApprovalManager } from "./approval.js";
 import { QuestionManager, validQuestions, isAskUserQuestionTool, formatQuestionResult } from "./question.js";
@@ -1373,9 +1374,21 @@ 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 },
     };
 }
 async function applyNodeSettings(patch) {
+    // Account-wide agent instructions live in their own file (not config.yaml) and
+    // sync through the E2E vault. Applied first so a rejected save changes nothing.
+    if (typeof patch.agentInstructions === "string") {
+        const current = readAgentInstructions(appDir);
+        const base = Number(patch.agentInstructionsBaseUpdatedAt);
+        if (Number.isFinite(base) && current.updatedAt > base && current.text !== patch.agentInstructions) {
+            throw new Error("These instructions were changed on another device. Reload them before saving.");
+        }
+        writeAgentInstructions(appDir, patch.agentInstructions);
+        void pushModelAuthToControlPlane();
+    }
     const settings = readSettings();
     if (typeof patch.name === "string" && patch.name.trim()) {
         const prev = identity.name;
@@ -3289,8 +3302,8 @@ function ensureLocalModelAuthVaultKey() {
 // silently exchange an incompatible structure. `decrypt` tolerates a bare map
 // for forward-safety.
 const MODEL_AUTH_ENVELOPE_VERSION = 3;
-function encryptModelAuthProviders(providers, deletedAt, localModels, vaultKeyB64, records = {}, recordsDeletedAt = {}) {
-    const envelope = { v: MODEL_AUTH_ENVELOPE_VERSION, providers, deletedAt, localModels, records, recordsDeletedAt };
+function encryptModelAuthProviders(providers, deletedAt, localModels, vaultKeyB64, records = {}, recordsDeletedAt = {}, agentInstructions) {
+    const envelope = { v: MODEL_AUTH_ENVELOPE_VERSION, providers, deletedAt, localModels, records, recordsDeletedAt, ...(agentInstructions ? { agentInstructions } : {}) };
     return seal(Buffer.from(vaultKeyB64, "base64"), JSON.stringify(envelope));
 }
 function decryptModelAuthEnvelope(ciphertext, vaultKeyB64) {
@@ -3309,6 +3322,7 @@ function decryptModelAuthEnvelope(ciphertext, vaultKeyB64) {
             localModels: obj(envelope.localModels),
             records: obj(envelope.records),
             recordsDeletedAt: obj(envelope.recordsDeletedAt),
+            agentInstructions: envelope.agentInstructions,
         };
     }
     // Back-compat: a bare `{ [id]: Credential }` map (pre-envelope / other sender).
@@ -3486,6 +3500,12 @@ async function syncModelAuthFromControlPlane() {
                 await importProviderAuth(credsDir, providers, deletedAt);
             }
             importLocalModels(localModelsDir, localModels);
+            // Account-wide agent instructions reconcile last-writer-wins. Hosted
+            // runners hold only the filtered credential snapshot, which never carries
+            // them, so they neither import nor republish.
+            const instructionsSync = hostedCustody ? "unchanged" : mergeSyncedAgentInstructions(appDir, decrypted.agentInstructions);
+            if (instructionsSync === "imported")
+                broadcast({ type: "node.settings", settings: nodeSettingsSnapshot() });
             // A synced key or config change can both alter the projection, so always
             // regenerate it (and refresh the panel) after importing the vault.
             await writePiModelsProjection();
@@ -3500,6 +3520,8 @@ async function syncModelAuthFromControlPlane() {
             broadcast({ type: "providers.list", providers: await listProvidersUnified() });
             if (!hostedCustody && data.vault?.needsRotation)
                 await pushModelAuthToControlPlane(true);
+            else if (instructionsSync === "local-newer")
+                await pushModelAuthToControlPlane();
         }
         else if (targetVault?.ciphertext && !vaultKeyB64 && !hostedCustody) {
             await modelAuthFetch("/node/model-auth-key/request", { method: "POST", body: JSON.stringify({ publicKey: pairingStore.nodePublicKeyB64() }) });
@@ -3509,7 +3531,8 @@ async function syncModelAuthFromControlPlane() {
             ensureModelAuthColdStart();
         }
         else if (Object.keys(await exportProviderAuth(credsDir)).length > 0 ||
-            Object.keys(exportLocalModels(localModelsDir)).length > 0) {
+            Object.keys(exportLocalModels(localModelsDir)).length > 0 ||
+            readAgentInstructions(appDir).updatedAt > 0) {
             await pushModelAuthToControlPlane();
         }
         await processModelAuthKeyRequests(data.requests ?? []);
@@ -3617,7 +3640,8 @@ async function pushModelAuthToControlPlane(rotateKey = false, throwOnFailure = f
         const vaultKeyB64 = rotateKey ? randomBytes(32).toString("base64") : ensureLocalModelAuthVaultKey();
         if (rotateKey)
             writeLocalModelAuthVaultKey(vaultKeyB64);
-        const ciphertext = encryptModelAuthProviders(providers, deletedAt, localModels, vaultKeyB64, records, recordsDeletedAt);
+        const instructions = readAgentInstructions(appDir);
+        const ciphertext = encryptModelAuthProviders(providers, deletedAt, localModels, vaultKeyB64, records, recordsDeletedAt, instructions.updatedAt > 0 ? instructions : undefined);
         if (!rotateKey && ciphertext === lastPushedModelAuthCiphertext) {
             await pushHostedModelAuthToControlPlane(allowEmptyHostedEscrow);
             return;
@@ -7843,7 +7867,7 @@ async function refreshRecordAfterTui(record) {
         const workspace = record.worktree?.path || oldSession.cwd || record.workspace;
         // 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 = { credentialLabels: record.credentialLabels, workspace, toolProvider: integrations.toolProvider({ current: record.id }), ...(rt.capabilities.toolInterception ? { toolInterceptor: guardianInterceptor } : {}) };
+        const runtimeSessionOptions = { credentialLabels: record.credentialLabels, workspace, toolProvider: integrations.toolProvider({ current: record.id }), instructions: sessionInstructions(appDir), ...(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;
@@ -8080,6 +8104,7 @@ async function recoverRecordAfterAbort(record) {
             workspace,
             credentialLabels: record.credentialLabels,
             toolProvider: integrations.toolProvider({ current: record.id }),
+            instructions: sessionInstructions(appDir),
             ...(rt.capabilities.toolInterception ? { toolInterceptor: guardianInterceptor } : {}),
         };
         const { session, warning } = await runtimeHost.openSession(rt, {
@@ -8269,7 +8294,9 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
     // `.current` in the moment `sessionId` is (see toolProvider's SessionIdRef doc).
     const attachSessionIdRef = {};
     const credentialLabels = opts.credentialLabels ?? storedMeta?.credentialLabels;
-    const runtimeSessionOptions = { credentialLabels, workspace: runtimeWorkspace, toolProvider: integrations.toolProvider(attachSessionIdRef), ...(rt.capabilities.toolInterception ? { toolInterceptor: guardianInterceptor } : {}) };
+    // The user's account-wide instructions, as of this session's start.
+    const instructions = sessionInstructions(appDir);
+    const runtimeSessionOptions = { credentialLabels, workspace: runtimeWorkspace, toolProvider: integrations.toolProvider(attachSessionIdRef), instructions, ...(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.
@@ -8387,6 +8414,7 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
                 home: os.homedir(),
                 sessionId,
                 endpoint: process.env.BIVY_MCP_ENDPOINT,
+                instructionsFile: instructions?.file,
             });
             if (res.injected.length) {
                 const prev = record.mcpRestore;

package/package.json

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