@bivy/bivy 0.19.4-staging.4 → 0.19.4-staging.6

package/bin/bivy.mjs

@@ -511,7 +511,19 @@ function nativeAgentAuthDetected(choice) {
 }
 
 function url(config) {
-  return `http://localhost:${config.port}`;
+  // BIVY_NODE_URL: set by `bivy mcp-serve` for the CLI it runs, so tools reach
+  // the node that started the agent whatever data dir this process resolves.
+  const override = process.env.BIVY_NODE_URL?.trim().replace(/\/+$/, "");
+  return override || `http://localhost:${config.port}`;
+}
+
+// The credential for a request about `sessionId`: the agent's own session token
+// ($BIVY_SESSION_TOKEN) when it is that session, else a device token when this
+// user can mint one, else none (loopback on a single-user host needs none).
+async function sessionAuth(config, sessionId) {
+  const own = resolveAttachSessionId({ env: process.env });
+  if (process.env.BIVY_SESSION_TOKEN && sessionId && sessionId === own) return process.env.BIVY_SESSION_TOKEN;
+  try { return await localDeviceToken(config); } catch { return undefined; }
 }
 
 // The host the node will bind (mirrors src/server.ts). We probe on this same
@@ -2424,8 +2436,7 @@ async function cmdAttach(args = []) {
 // (loopback bypasses auth), but include one when available so multi-user
 // hosts work too.
 async function sessionPost(config, sessionId, action, body) {
-  let token;
-  try { token = await localDeviceToken(config); } catch { token = undefined; }
+  const token = await sessionAuth(config, sessionId);
   return fetch(`${url(config)}/api/session/${encodeURIComponent(sessionId)}/${action}`, {
     method: "POST",
     headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
@@ -2437,7 +2448,7 @@ async function sessionPost(config, sessionId, action, body) {
 function sessionHttpError(what, status, body) {
   const message = `${what} failed (${status}): ${body?.error || "unknown error"}`;
   if (status === 404) return { code: "session_not_found", message, hint: "The session must be open on this node.", next: "bivy context", exit: EXIT.notFound };
-  if (status === 401 || status === 403) return { code: "denied", message, exit: EXIT.denied };
+  if (status === 401 || status === 403) return { code: "denied", message, hint: "A session's token only reaches that session; run it from the session's own shell, or from a terminal signed in to this node.", exit: EXIT.denied };
   if (status === 400) return { code: "invalid", message, exit: EXIT.usage };
   return { code: "failed", message, exit: EXIT.failed };
 }
@@ -2472,8 +2483,7 @@ async function cmdContext(args = []) {
   let node = { session: null };
   if (sessionId) {
     const config = loadConfig();
-    let token;
-    try { token = await localDeviceToken(config); } catch { token = undefined; }
+    const token = await sessionAuth(config, sessionId);
     try {
       const res = await fetch(`${url(config)}/api/session/${encodeURIComponent(sessionId)}/context`, { headers: token ? { authorization: `Bearer ${token}` } : {} });
       const body = await res.json().catch(() => ({}));
@@ -2631,8 +2641,7 @@ answer later and 'bivy ask status <id>' checks without waiting.
   if (!Number.isFinite(timeout) || timeout < 1) return fail({ code: "usage", message: "--timeout takes seconds or a duration like 90s, 10m or 2h.", exit: EXIT.usage });
   const config = loadConfig();
   if (!(await ensureNodeRunning(config))) return fail({ code: "node_unreachable", message: `Could not reach the Bivy node at ${url(config)}.`, next: "bivy status", exit: EXIT.unavailable });
-  let token;
-  try { token = await localDeviceToken(config); } catch { token = undefined; }
+  const token = await sessionAuth(config, sessionId);
   const base = `${url(config)}/api/session/${encodeURIComponent(sessionId)}/ask`;
   const call = async (suffix, body) => {
     const res = await fetch(`${base}${suffix}`, {
@@ -2684,6 +2693,139 @@ answer later and 'bivy ask status <id>' checks without waiting.
   finish(await waitFor(started.id, timeout + 5));
 }
 
+// One JSON request to the local node for the commands below: starts the node if
+// needed and returns { status, body }, or fails in the shared error shape.
+async function nodeRequest(method, pathname, body, { json = false, sessionId } = {}) {
+  const config = loadConfig();
+  if (!(await ensureNodeRunning(config))) return cliError({ code: "node_unreachable", message: `Could not reach the Bivy node at ${url(config)}.`, next: "bivy status", exit: EXIT.unavailable }, { json, paint: c.red });
+  const token = await sessionAuth(config, sessionId);
+  const res = await fetch(`${url(config)}${pathname}`, {
+    method,
+    headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  }).catch((error) => error);
+  if (res instanceof Error) return cliError({ code: "node_unreachable", message: `Could not reach the Bivy node: ${res.message}`, next: "bivy status", exit: EXIT.unavailable }, { json, paint: c.red });
+  return { status: res.status, body: await res.json().catch(() => ({})) };
+}
+
+// `bivy fork [session-id]` — the app's Fork on this machine: a new session with
+// the same conversation, agent and uncommitted work, on its own branch. Give it
+// its next task with `bivy send <new-id> "…"`.
+async function cmdFork(args = []) {
+  const usage = "Usage: bivy fork [session-id] [--model <provider/id>] [--json]";
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log(`${usage}\n\nCopy a session (default: this one, $BIVY_SESSION_ID) into a new session on this machine: the same conversation and agent, with uncommitted work carried into a fresh worktree on its own branch. --model switches the fork's model. Prints the new session's id; send it work with 'bivy send <id> "…"'. --json prints {"sessionId","fidelity"}.`);
+    return;
+  }
+  const json = wantsJson(args);
+  const fail = (error) => cliError(error, { json, paint: c.red });
+  const parsed = parseSessionArgs(args, ["--model", "--session"]);
+  if (parsed.error) return fail({ code: "usage", message: parsed.error, exit: EXIT.usage });
+  const sessionId = parsed.positional[0] ?? resolveAttachSessionId({ sessionFlag: parsed.one("--session"), env: process.env });
+  if (!sessionId) return fail({ code: "no_session", message: "No session to fork.", hint: "Pass a session id, or run inside an agent session ($BIVY_SESSION_ID).", next: "bivy sessions --json", exit: EXIT.usage });
+  // "provider/id" or a bare model id, as the fork command takes it.
+  const modelArg = parsed.one("--model");
+  const slash = modelArg?.indexOf("/") ?? -1;
+  const model = modelArg ? (slash > 0 ? { provider: modelArg.slice(0, slash), id: modelArg.slice(slash + 1) } : { provider: "", id: modelArg }) : undefined;
+  const { status, body } = await nodeRequest("POST", "/api/session/fork", { sessionId, ...(model ? { model } : {}) }, { json, sessionId });
+  if (status === 404) return fail({ code: "node_outdated", message: "This node is older than 'bivy fork'.", next: "bivy update", exit: EXIT.unavailable });
+  if (status >= 400 || body.error) return fail({ code: /not found/i.test(body.error ?? "") ? "session_not_found" : "failed", message: `Fork failed: ${body.error || `HTTP ${status}`}`, exit: /not found/i.test(body.error ?? "") ? EXIT.notFound : EXIT.failed });
+  if (json) { console.log(JSON.stringify({ sessionId: body.sessionId, fidelity: body.fidelity, ...(body.missing?.length ? { missing: body.missing } : {}) })); return; }
+  console.log(c.green(`Forked into ${body.sessionId}.`) + ` Give it work with: bivy send ${body.sessionId} "…"`);
+}
+
+// `bivy approvals` — tool calls waiting for a person, and answering them. For a
+// supervising agent or script; the app shows the same requests as cards.
+async function cmdApprovals(args = []) {
+  const usage = "Usage: bivy approvals [list] [--json]\n       bivy approvals approve <id> [--json]\n       bivy approvals reject <id> [--json]";
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log(`${usage}\n\nList the tool calls on this node waiting for approval, or answer one. The app shows the same requests as cards; answering here resolves them there too.`);
+    return;
+  }
+  const json = wantsJson(args);
+  const fail = (error) => cliError(error, { json, paint: c.red });
+  const [action = "list", id] = args.filter((a) => !a.startsWith("-"));
+  if (action === "list") {
+    const { body } = await nodeRequest("GET", "/api/approvals", undefined, { json });
+    const pending = (Array.isArray(body) ? body : []).filter((a) => a.status === "pending");
+    if (json) { console.log(JSON.stringify(pending, null, 2)); return; }
+    if (!pending.length) { console.log("No approvals waiting."); return; }
+    for (const a of pending) console.log(`${c.cyan(a.id)}  ${a.toolName}${a.risk ? c.dim(` (${a.risk})`) : ""}  session ${a.sessionId}\n    ${a.reason}`);
+    return;
+  }
+  if ((action === "approve" || action === "reject") && id) {
+    const { status } = await nodeRequest("POST", `/api/approvals/${encodeURIComponent(id)}/${action}`, {}, { json });
+    if (status === 404) return fail({ code: "not_found", message: `No pending approval ${id}.`, next: "bivy approvals --json", exit: EXIT.notFound });
+    if (json) { console.log(JSON.stringify({ ok: true, id, approved: action === "approve" })); return; }
+    console.log(c.green(action === "approve" ? `Approved ${id}.` : `Rejected ${id}.`));
+    return;
+  }
+  fail({ code: "usage", message: usage, exit: EXIT.usage });
+}
+
+// `bivy issues` — the node's GitHub issue pickup: open issues labelled for an
+// agent, and starting a session on one (it claims the issue with a label).
+async function cmdIssues(args = []) {
+  const usage = "Usage: bivy issues [list] [--json]\n       bivy issues pickup <number> [--json]";
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log(`${usage}\n\nOpen GitHub issues labelled for an agent in this node's repository, and picking one up: pickup claims the issue with its claim label and starts a session on it. Needs GitHub issue pickup configured (see docs/github-work-queue.md).`);
+    return;
+  }
+  const json = wantsJson(args);
+  const fail = (error) => cliError(error, { json, paint: c.red });
+  const [action = "list", number] = args.filter((a) => !a.startsWith("-"));
+  if (action === "list") {
+    const { status, body } = await nodeRequest("GET", "/api/github/issues", undefined, { json });
+    if (status >= 400) return fail({ code: "not_configured", message: body.error || `HTTP ${status}`, exit: EXIT.failed });
+    if (json) { console.log(JSON.stringify(body, null, 2)); return; }
+    if (!body.issues?.length) { console.log(`No open issues labelled ${body.label} in ${body.repo}.`); return; }
+    for (const issue of body.issues) console.log(`${c.cyan(`#${issue.number}`)}  ${issue.title}`);
+    return;
+  }
+  if (action === "pickup" && number) {
+    const { status, body } = await nodeRequest("POST", `/api/github/issues/${encodeURIComponent(number)}/pickup`, {}, { json });
+    if (status >= 400) return fail({ code: status === 404 ? "not_found" : status === 409 ? "conflict" : "failed", message: body.error || `HTTP ${status}`, exit: status === 404 ? EXIT.notFound : status === 409 ? EXIT.conflict : status === 400 ? EXIT.usage : EXIT.failed });
+    if (json) { console.log(JSON.stringify(body)); return; }
+    console.log(c.green(`Picked up #${body.issue?.number} in ${body.repo}; a session is starting on it.`));
+    return;
+  }
+  fail({ code: "usage", message: usage, exit: EXIT.usage });
+}
+
+// `bivy instructions` — the account-wide instructions every agent session gets
+// (Settings → Agent instructions). `set` refuses to overwrite a newer edit
+// made elsewhere since the text was read.
+async function cmdInstructions(args = []) {
+  const usage = "Usage: bivy instructions [show] [--json]\n       bivy instructions set <file|-> [--json]\n       bivy instructions path";
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log(`${usage}\n\nThe account-wide instructions every agent session receives (the same text as Settings → Agent instructions). 'set' replaces them from a file, or from stdin with '-'; it applies to sessions started afterwards. 'path' prints the file on this machine.`);
+    return;
+  }
+  const json = wantsJson(args);
+  const fail = (error) => cliError(error, { json, paint: c.red });
+  const [action = "show", source] = args.filter((a) => a === "-" || !a.startsWith("-"));
+  if (action === "path") { console.log(path.join(appDir, "AGENTS.md")); return; }
+  const { status, body } = await nodeRequest("GET", "/api/node/settings", undefined, { json });
+  const current = body.agentInstructions;
+  if (status >= 400 || !current) return fail({ code: "node_outdated", message: "This node does not report agent instructions.", next: "bivy update", exit: EXIT.unavailable });
+  if (action === "show") {
+    if (json) { console.log(JSON.stringify({ text: current.text, updatedAt: current.updatedAt, bivyNote: current.bivyNote })); return; }
+    console.log(current.text || c.dim("(none yet)"));
+    return;
+  }
+  if (action === "set" && source) {
+    let text;
+    try { text = source === "-" ? fs.readFileSync(0, "utf8") : fs.readFileSync(path.resolve(source), "utf8"); }
+    catch (error) { return fail({ code: "file_not_found", message: `Could not read ${source}: ${error?.message || error}`, exit: EXIT.notFound }); }
+    const saved = await nodeRequest("POST", "/api/node/settings", { agentInstructions: text, agentInstructionsBaseUpdatedAt: current.updatedAt }, { json });
+    if (saved.status >= 400) return fail({ code: /another device/.test(saved.body.error ?? "") ? "conflict" : "invalid", message: saved.body.error || `HTTP ${saved.status}`, exit: /another device/.test(saved.body.error ?? "") ? EXIT.conflict : EXIT.usage });
+    if (json) { console.log(JSON.stringify({ ok: true, bytes: Buffer.byteLength(text) })); return; }
+    console.log(c.green("Saved. Sessions started from now on get these instructions."));
+    return;
+  }
+  fail({ code: "usage", message: usage, exit: EXIT.usage });
+}
+
 // Cross-agent / cross-machine delegation (docs/agent-delegation.md): hand a
 // self-contained task from this session to another agent, optionally on another
 // account machine, and get its answer back. Agent-agnostic — any agent with a
@@ -2720,8 +2862,7 @@ async function cmdDelegate(args = []) {
   if (!sessionId) { console.error(c.red("No session id. Run inside an agent session ($BIVY_SESSION_ID) or pass --session <id>.")); process.exit(1); return; }
   const config = loadConfig();
   if (!(await ensureNodeRunning(config))) { console.error(c.red(`Could not reach the Bivy node at ${url(config)}.`)); process.exit(1); return; }
-  let token;
-  try { token = await localDeviceToken(config); } catch { token = undefined; }
+  const token = await sessionAuth(config, sessionId);
   const base = `${url(config)}/api/session/${encodeURIComponent(sessionId)}/delegated-runs`;
   const call = async (path, body) => {
     const res = await fetch(`${base}${path}`, {
@@ -3002,9 +3143,9 @@ async function appMenu(rest, { json = false } = {}) {
 async function appRequest(action, body, { print = true } = {}) {
   const config = loadConfig();
   if (!(await ensureNodeRunning(config))) throw new Error("Could not reach the Bivy node.");
-  const token = await localDeviceToken(config);
+  const token = await sessionAuth(config, body.sessionId);
   const response = await fetch(`${url(config)}/api/apps/${action}`, {
-    method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify(body),
+    method: "POST", headers: { ...(token ? { authorization: `Bearer ${token}` } : {}), "content-type": "application/json" }, body: JSON.stringify(body),
   });
   const result = await response.json();
   if (!response.ok || result.error) throw new Error(result.error || `App command failed (${response.status}).`);
@@ -5687,6 +5828,22 @@ function readSelfVersion() {
   }
 }
 
+// A command an agent tried that doesn't exist is the best hint for what it
+// expected Bivy to have. Inside a session, keep the word (never its arguments)
+// in <data-dir>/agent-cli-misses.jsonl for `pnpm run eval:agent-ux` and
+// whoever names the next command. Bounded: one rotation at 256 KiB.
+function recordAgentMiss(word) {
+  const session = resolveAttachSessionId({ env: process.env });
+  if (!session || typeof word !== "string" || word.length > 64) return;
+  try {
+    const file = path.join(appDir, "agent-cli-misses.jsonl");
+    if (fs.existsSync(file) && fs.statSync(file).size > 256 * 1024) fs.renameSync(file, `${file}.1`);
+    fs.appendFileSync(file, `${JSON.stringify({ ts: Date.now(), session, word })}\n`, { mode: 0o600 });
+  } catch {
+    // Best-effort: a miss log must never change what the command does.
+  }
+}
+
 function printHelp() {
   const details = { run: `Agents: ${[...AGENT_INTEGRATIONS.keys()].join(" | ")}, or -- <command>` };
   console.log(`\n${renderHelp({ paint: c.cyan, bold: c.bold, details })}\n`);
@@ -5764,13 +5921,27 @@ function cmdGuide(args = []) {
   console.log(guide.markdown.trimEnd());
 }
 
+// Inside an agent session the daemon names its own CLI ($BIVY_NODE_CLI). When
+// `bivy` was found on PATH (every installer links it by that name) and is
+// another file, run the node's, so the agent gets the commands its node
+// documents. Running a file on purpose (`node …/bin/bivy.mjs`) is left alone.
+function nodeCliToRun() {
+  const nodeCli = process.env.BIVY_NODE_CLI;
+  if (path.basename(process.argv[1] ?? "") !== "bivy") return undefined;
+  if (!nodeCli || !path.isAbsolute(nodeCli) || !fs.existsSync(nodeCli)) return undefined;
+  try { return fs.realpathSync(nodeCli) === fs.realpathSync(selfScript) ? undefined : nodeCli; } catch { return undefined; }
+}
+
 async function main() {
+  const nodeCli = nodeCliToRun();
+  if (nodeCli) process.exit(spawnSync(process.execPath, [nodeCli, ...process.argv.slice(2)], { stdio: "inherit", env: process.env }).status ?? 1);
   await hydrateCanonicalConfig();
   const argv = process.argv.slice(2);
   const [command, ...args] = argv;
   if (command === undefined) { printHelp(); return; }
   const entry = resolveCommand(command);
   if (!entry) {
+    recordAgentMiss(command);
     const close = suggestCommands(command);
     cliError({
       code: "unknown_command",
@@ -5861,6 +6032,18 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
     case "notify":
       await cmdNotify(args);
       break;
+    case "fork":
+      await cmdFork(args);
+      break;
+    case "approvals":
+      await cmdApprovals(args);
+      break;
+    case "issues":
+      await cmdIssues(args);
+      break;
+    case "instructions":
+      await cmdInstructions(args);
+      break;
     case "ask":
       await cmdAsk(args);
       break;

package/bin/cli-commands.mjs

@@ -56,6 +56,7 @@ export const COMMANDS = [
       { name: "app_screenshot", description: "Screenshot this session's web views (or one app) and return the PNG paths, to check your work before saying a UI change is done.", input: { app: { type: "string", description: "App ID or name (default: all web views)." }, widths: { type: "array", items: { type: "number" }, description: "Viewport widths, e.g. [390, 1280]." }, path: { type: "string", description: "Page path, e.g. /settings." } }, argv: ["app", "shot", { arg: "app" }, { flag: "--widths", from: "widths", join: "," }, { flag: "--path", from: "path" }] },
       { name: "app_present", description: "Tell the user a visible change is ready: a card in the chat with the app at phone width (before and after), and the preview opens.", input: { view: { type: "string", description: "App or view name or ID (default: the one opened last)." }, note: { type: "string", description: "What changed." }, path: { type: "string", description: "Page path to show." } }, argv: ["app", "present", { arg: "view" }, { flag: "--note", from: "note" }, { flag: "--path", from: "path" }] },
     ] },
+  { name: "fork", group: "session", scope: "session", json: true, usage: "fork [session-id] [--model <model>]", summary: "Copy this session (conversation and uncommitted work) into a new one on its own branch" },
   { name: "delegate", group: "session", scope: "session", json: true, usage: 'delegate "<task>" [--agent <id>] [--machine <name>] [--wait]', summary: "Hand a task to another agent or machine and get its answer back", subcommands: ["machines", "status", "wait"] },
 
   // Agents and sessions
@@ -68,6 +69,8 @@ export const COMMANDS = [
   { name: "takeover", group: "sessions", scope: "node", usage: "takeover <id>", summary: "Stop a run-terminal's native TUI and continue it as a governed chat" },
   { name: "promote", group: "sessions", scope: "node", usage: "promote <session-id>", summary: "Continue a warm-replicated session on this node" },
   { name: "prune", aliases: ["clean"], group: "sessions", scope: "node", json: true, usage: "prune [--keep N] [--older-than 7d] [--dry-run]", summary: "Delete old sessions, workspaces and worktrees" },
+  { name: "approvals", group: "sessions", scope: "node", json: true, usage: "approvals [list|approve <id>|reject <id>]", summary: "List pending tool approvals on this node, or answer one", subcommands: ["list", "approve", "reject"] },
+  { name: "issues", group: "sessions", scope: "node", json: true, usage: "issues [list|pickup <number>]", summary: "GitHub issues waiting for an agent; pick one up to start a session on it", subcommands: ["list", "pickup"] },
   { name: "agents", group: "sessions", scope: "node", json: true, usage: "agents [--json]", summary: "List supported agents and which are installed" },
   { name: "agent", group: "sessions", scope: "node", json: true, usage: "agent <add|list|remove>", summary: "Connect, list or remove a user-owned agent", subcommands: ["add", "list", "remove"] },
   { name: "agents:install", aliases: ["runtimes:install"], group: "sessions", scope: "node", usage: "agents:install [--bridges]", summary: "Install known upstream agents" },
@@ -111,6 +114,7 @@ export const COMMANDS = [
   { name: "github:app-sync", group: "accounts", scope: "account", usage: "github:app-sync [on|off]", summary: "Sync GitHub App keys to this account's other nodes" },
 
   // Configuration and extensions
+  { name: "instructions", group: "config", scope: "account", json: true, usage: "instructions [show|set <file|->|path]", summary: "The account-wide instructions every agent session receives", subcommands: ["show", "set", "path"] },
   { name: "config", group: "config", scope: "node", json: true, usage: "config <show|get|set|unset|explain|validate|init|path>", summary: "Typed node configuration", subcommands: ["init", "validate", "show", "get", "set", "unset", "explain", "path"] },
   { name: "plugin", aliases: ["plugins"], group: "config", scope: "node", json: true, usage: "plugin <init|validate|doctor|test|install|list|remove>", summary: "Build and install plugins", subcommands: ["init", "validate", "doctor", "test", "install", "list", "remove"] },
   { name: "voice", aliases: ["stt"], group: "config", scope: "node", usage: "voice <provider|key|remove|status>", summary: "Configure speech-to-text", subcommands: ["provider", "key", "remove", "status"] },

package/bin/guides/automate.md

@@ -13,6 +13,7 @@ infrastructure code:
     bivy automation list --json
     bivy automation trigger <id-or-key>            # run one now
 
-Always `validate` and `plan` before `apply`, and show the user the plan when it
+To pause one, set `enabled: false` on it and apply. Always `validate` and
+`plan` before `apply`, and show the user the plan when it
 changes something they didn't ask for. `apply --prune` also removes automations
 the file no longer has. `bivy automation --help` has every flag.

package/bin/guides/more-hands.md

@@ -15,4 +15,10 @@ Write the task so it stands on its own: the other agent does not see this chat.
 get a run id: `bivy delegate status <id>`, `bivy delegate wait <id>`.
 Code comes back by git: fetch the branch or review the PR.
 
+To try another approach from the same point, fork this session and give the
+copy its task (it gets its own branch):
+
+    id=$(bivy fork --json | jq -r .sessionId)
+    bivy send "$id" "Try the same fix with a streaming parser instead."
+
 For unattended work with checks and a receipt, see `bivy guide long-work`.

package/bin/guides/show-the-user.md

@@ -19,9 +19,14 @@ not render; a remote `https://` image does.
 
 Publish it once; the user opens it from the chat:
 
-    bivy app run -- pnpm dev                     # a desktop app, no manifest
+    bivy app run -- cargo run                    # a desktop app, no manifest
     bivy app publish app.json                    # web server, static build, terminal
 
+A `terminal` view is a command the user can watch and type into from the app,
+such as a REPL or a log tail:
+
+    {"kind":"terminal","name":"Console","command":"bin/rails","args":["console"]}
+
 A manifest with a server Bivy starts on first open:
 
     {"version":1,"name":"Site","views":[{"kind":"web","name":"Web",

package/dist/auth.js

@@ -251,12 +251,31 @@ export function requestOriginAllowed(req) {
     return true;
 }
 /** Express middleware enforcing auth on /api routes. */
-export function authMiddleware(identity) {
+export function authMiddleware(identity, sessionTokens) {
     return (req, res, next) => {
         if (!requestOriginAllowed(req)) {
             res.status(403).json({ error: "Forbidden origin" });
             return;
         }
+        // An agent session's token: only that session's own routes, even over
+        // loopback, so a token-carrying request is never more than its session.
+        const token = tokenFromRequest(req);
+        if (sessionTokens?.claims(token)) {
+            const sessionId = sessionTokens.verify(token);
+            if (!sessionId) {
+                res.status(401).json({ error: "Unknown or expired session token" });
+                return;
+            }
+            const call = { method: req.method, path: req.baseUrl + req.path, body: req.body };
+            if (!sessionTokens.allows(sessionId, call)) {
+                res.status(403).json({ error: `A session token can only reach its own session's routes, not ${call.method} ${call.path}.` });
+                return;
+            }
+            sessionTokens.used?.(sessionId, call);
+            req.auth = { deviceId: null, loopback: isLoopbackAddress(req.socket?.remoteAddress), sessionId };
+            next();
+            return;
+        }
         const ctx = resolveAuth(identity, req);
         if (!isAuthorized(ctx)) {
             res.status(401).json({ error: "Unauthorized" });

package/dist/certification/agent-ux.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+/**
+ * Scoring for the agent-UX eval (certification/agent-ux.json, run by
+ * scripts/agent-ux-eval.ts): given what a real agent did in a session, did it
+ * use Bivy the way the task needed? Pure, so the rules are testable without an
+ * agent or a model.
+ */
+function globToRegExp(glob) {
+    return new RegExp(`^${glob.split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join("[^/]*")}$`);
+}
+/** Every expectation of a task, checked against an observation. `vars` fills {name} placeholders. */
+export function scoreAgentUx(expect, seen, vars = {}) {
+    const fill = (text) => text.replace(/\{(\w+)\}/g, (whole, name) => vars[name] ?? whole);
+    return expect.map((rule) => {
+        if ("block" in rule) {
+            const min = rule.min ?? 1;
+            return { expectation: `${min}+ ${rule.block}`, passed: (seen.blocks[rule.block] ?? 0) >= min };
+        }
+        if ("asked" in rule)
+            return { expectation: "asked a question", passed: seen.asked };
+        if ("reply" in rule) {
+            const text = fill(rule.reply);
+            return { expectation: `reply mentions "${text}"`, passed: seen.reply.toLowerCase().includes(text.toLowerCase()) };
+        }
+        const pattern = globToRegExp(rule.file);
+        return { expectation: `file ${rule.file}`, passed: seen.files.some((file) => pattern.test(file)) };
+    });
+}
+/** Count `bivy_*` chat card blocks anywhere in a history payload's messages. */
+export function countCardBlocks(messages) {
+    const counts = {};
+    const walk = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                walk(item);
+            return;
+        }
+        if (!value || typeof value !== "object")
+            return;
+        const type = value.type;
+        if (typeof type === "string" && type.startsWith("bivy_"))
+            counts[type] = (counts[type] ?? 0) + 1;
+        walk(value.content);
+    };
+    walk(messages);
+    return counts;
+}

package/dist/harness/mcp-config.js

@@ -16,6 +16,7 @@
 // the fs inject/restore step (mcp-inject.ts) reads/writes; the transform itself
 // is shared.
 import nodePath from "node:path";
+import { bivySessionEnv } from "../runtime/session-env.js";
 /** Marker arg the proxy CLI recognizes, so a config can be detected as already routed. */
 export const PROXY_MARKER = "--bivy-mcp";
 /** True when a server spec already launches through the Bivy proxy. */
@@ -94,7 +95,9 @@ export function parseProxiedArgs(args) {
 // 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 };
+    // Some agents start MCP servers with a trimmed environment, so the session's
+    // token travels in the spec rather than being inherited.
+    const env = { ...bivySessionEnv(opts.sessionId) };
     if (opts.endpoint)
         env.BIVY_MCP_ENDPOINT = opts.endpoint;
     // The user's account-wide instructions, advertised as the server's MCP

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

@@ -94,11 +94,12 @@ 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.` };
 }
-/** Run this install's `bivy` (bin/bivy.mjs, two levels up from src/ or dist/). */
-function defaultRunBivy(sessionId) {
+/** Run this install's `bivy` (bin/bivy.mjs, two levels up from src/ or dist/),
+ *  against the node that injected this server. */
+function defaultRunBivy(sessionId, endpoint) {
     const cli = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../bin/bivy.mjs");
     return (args) => new Promise((resolve) => {
-        const child = spawn(process.execPath, [cli, ...args], { env: { ...process.env, BIVY_SESSION_ID: sessionId, NO_COLOR: "1" }, stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawn(process.execPath, [cli, ...args], { env: { ...process.env, BIVY_SESSION_ID: sessionId, BIVY_NODE_URL: endpoint, NO_COLOR: "1" }, stdio: ["ignore", "pipe", "pipe"] });
         let stdout = "";
         let stderr = "";
         child.stdout.on("data", (chunk) => { stdout += chunk; });
@@ -133,10 +134,10 @@ function readInstructions(file) {
 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 token = deps.token ?? process.env.BIVY_MCP_TOKEN ?? process.env.BIVY_SESSION_TOKEN ?? undefined;
     const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
     const instructions = readInstructions(deps.instructionsFile ?? process.env.BIVY_AGENT_INSTRUCTIONS_FILE);
-    const runBivy = deps.runBivy ?? defaultRunBivy(sessionId);
+    const runBivy = deps.runBivy ?? defaultRunBivy(sessionId, endpoint);
     let tools;
     const generated = () => (tools ??= cliTools(runBivy));
     const server = new Server({ name: "bivy", version: "1.0.0" }, { capabilities: { tools: {}, resources: {} }, ...(instructions ? { instructions } : {}) });

package/dist/protocol/client-command-routes.js

@@ -8,6 +8,7 @@ export const CLIENT_COMMAND_ROUTES = [
     { method: "post", path: "/api/auth/credentials/native-preview", kind: "credentials.native.preview" },
     { method: "post", path: "/api/auth/credentials/native-import", kind: "credentials.native.import" },
     { method: "post", path: "/api/session/pause", kind: "session.pause" },
+    { method: "post", path: "/api/session/fork", kind: "session.fork.local" },
     ...["get", "draft"].map((action) => ({ method: "post", path: `/api/session/presence/${action}`, kind: `session.presence.${action}` })),
     { method: "post", path: "/api/session/resume", kind: "session.resume" },
     { method: "post", path: "/api/session/question/answer", kind: "session.question.answer" },

package/dist/protocol/client-command-schemas.js

@@ -11,6 +11,7 @@ export const CLIENT_COMMAND_SCHEMAS = {
     ping: Type.Object(request),
     "apps.list": Type.Object({ ...request, ...optionalSession }),
     "artifacts.list": Type.Object(request),
+    "session.fork.local": Type.Object({ ...request, ...session, model: Type.Optional(Type.Object({ provider: Type.Optional(Type.String({ maxLength: 200 })), id: Type.String({ maxLength: 200 }) })) }),
     "apps.publish": Type.Object({ ...request, ...session, manifest: Type.Unknown() }),
     "apps.offers": Type.Object({ ...request, ...session }),
     "apps.adopt": Type.Object({ ...request, ...session, port: Type.Integer({ minimum: 1024, maximum: 65535 }) }),

package/dist/runtime/session-env.js

@@ -15,8 +15,16 @@
 // 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.
+//
+// With a signer registered (the daemon does at startup), the env also carries
+// BIVY_SESSION_TOKEN: a credential for that session's own routes only (see
+// src/session/session-tokens.ts), which the `bivy` CLI and MCP tools prefer.
+let signSessionToken;
+export function setSessionTokenSigner(sign) {
+    signSessionToken = sign;
+}
 export function bivySessionEnv(sessionId) {
-    return { BIVY_SESSION_ID: sessionId };
+    return { BIVY_SESSION_ID: sessionId, ...(signSessionToken ? { BIVY_SESSION_TOKEN: signSessionToken(sessionId) } : {}) };
 }
 /**
  * Apply a profile's instructions env template (AgentProfile.instructions) for one

package/dist/server.js

@@ -128,6 +128,8 @@ import { createArtifactCommands } from "./controllers/artifact-commands.js";
 import { PresenceBook, deviceFrom } from "./session/presence.js";
 import { buildAgentContext } from "./session/agent-context.js";
 import { AgentQuestions, askQuestionsFrom } from "./session/agent-questions.js";
+import { createSessionTokenCodec, isSessionToken, sessionTokenAllows } from "./session/session-tokens.js";
+import { setSessionTokenSigner } from "./runtime/session-env.js";
 import { MAX_NOTICE_TEXT, isAgentNotice, noticePush } from "./session/notices.js";
 import { createForkCommands } from "./controllers/fork-commands.js";
 import { createGithubCommands } from "./controllers/github-commands.js";
@@ -169,6 +171,12 @@ import { TERMINAL_DELEGATION, isDelegatedFrom } from "./session/delegations.js";
 import { ControlPlaneTaskPoller, resolveControlPlaneTaskConfig, } from "./control-plane-tasks.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, "..");
+// Agents inherit this: the `bivy` on their PATH (another install, or an older
+// version) hands their commands to this node's own CLI, so the commands the
+// agent note names always exist. Agent shells that rebuild PATH from the
+// user's rc files keep ordinary variables like this one.
+if (!process.env.BIVY_NODE_CLI && fs.existsSync(path.join(repoRoot, "bin", "bivy.mjs")))
+    process.env.BIVY_NODE_CLI = path.join(repoRoot, "bin", "bivy.mjs");
 // Asset root holds read-only bundled files (public/, helper scripts); data dir
 // holds writable per-install state (.bivy). Both default to the repo when
 // running from source. Packaged/release builds may override them (BIVY_ASSET_ROOT,
@@ -395,6 +403,9 @@ const sessionAllowRules = new SessionAllowRules();
 // `bivy audit --verify` can prove it — the basis of an attested Receipt (2A).
 const auditKey = loadOrCreateAuditKey(path.join(appDir, "audit"));
 const auditLog = createAuditLog(path.join(appDir, "audit"), { signer: auditKey.signer });
+// Agent sessions get a token for their own routes in their env (BIVY_SESSION_TOKEN).
+const sessionTokens = createSessionTokenCodec();
+setSessionTokenSigner(sessionTokens.sign);
 // Bivy owns the AskUserQuestion → question-card feature at the guardian layer,
 // runtime-agnostically (see src/question.ts). The manager holds every pending
 // clarifying question across sessions; the guardian interceptor below raises
@@ -9397,7 +9408,14 @@ app.post("/api/auth/bootstrap", sensitiveRateLimiter, (req, res) => {
 });
 // All other /api routes require auth (loopback may bypass, per config and host
 // — see loopbackAllowed()/isMultiUserHost() in src/auth.ts).
-app.use("/api", authMiddleware(identity));
+app.use("/api", authMiddleware(identity, {
+    verify: sessionTokens.verify,
+    claims: isSessionToken,
+    allows: sessionTokenAllows,
+    // What an agent did through Bivy, per session (`bivy audit --session <id>`).
+    used: (sessionId, call) => { if (call.method !== "GET")
+        auditLog.record({ kind: "agent.call", session: sessionId, tool: `${call.method} ${call.path}` }); },
+}));
 // Reload relay.json without forcing the user to restart the whole node. This is
 // used by `bivy relay:setup` after it enrolls the node.
 app.post("/api/relay/reload", (_req, res) => {

package/dist/session/session-tokens.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+/**
+ * Session tokens: a credential each agent session gets in its environment
+ * ($BIVY_SESSION_TOKEN, via bivySessionEnv) that reaches only that session's
+ * own routes. They let `bivy attach`, `notify`, `ask`, `app` and the MCP tools
+ * work where the loopback bypass doesn't apply (multi-user hosts,
+ * BIVY_REQUIRE_LOCAL_AUTH) and where the agent can't read the node's data dir to
+ * mint a device token (sandboxed agents), without handing it the node.
+ *
+ * A token is `bst_<session id, base64url>.<HMAC-SHA256>` under a key that lives
+ * only in the daemon's memory, so it needs no storage and stops working when
+ * the daemon restarts (along with the agent processes that held it).
+ */
+const PREFIX = "bst_";
+export function isSessionToken(token) {
+    return typeof token === "string" && token.startsWith(PREFIX);
+}
+export function createSessionTokenCodec(key = randomBytes(32)) {
+    const mac = (id) => createHmac("sha256", key).update(`bivy-session-token:${id}`).digest("base64url");
+    return {
+        sign(sessionId) {
+            return `${PREFIX}${Buffer.from(sessionId).toString("base64url")}.${mac(sessionId)}`;
+        },
+        verify(token) {
+            if (!isSessionToken(token))
+                return undefined;
+            const [encoded, signature] = token.slice(PREFIX.length).split(".");
+            if (!encoded || !signature)
+                return undefined;
+            const sessionId = Buffer.from(encoded, "base64url").toString();
+            const expected = Buffer.from(mac(sessionId));
+            const given = Buffer.from(signature);
+            return sessionId && given.length === expected.length && timingSafeEqual(given, expected) ? sessionId : undefined;
+        },
+    };
+}
+/**
+ * What a session token may call: its own session's agent-facing routes, and
+ * the read-only machine list `bivy delegate machines` needs. `session` says
+ * where the request names its session (a path segment or body.sessionId); it
+ * must be the token's own. Adding a route is adding a row.
+ */
+export const SESSION_TOKEN_ROUTES = [
+    { method: "GET", path: /^\/api\/session\/([^/]+)\/context$/, session: "path" },
+    { method: "POST", path: /^\/api\/session\/([^/]+)\/(attach|suggest|notify)$/, session: "path" },
+    { method: "POST", path: /^\/api\/session\/([^/]+)\/ask$/, session: "path" },
+    { method: "GET", path: /^\/api\/session\/([^/]+)\/ask\/[^/]+$/, session: "path" },
+    { method: "POST", path: /^\/api\/session\/([^/]+)\/ask\/[^/]+\/wait$/, session: "path" },
+    { method: "POST", path: /^\/api\/session\/([^/]+)\/delegated-runs$/, session: "path" },
+    { method: "GET", path: /^\/api\/session\/([^/]+)\/delegated-runs\/[^/]+$/, session: "path" },
+    { method: "POST", path: /^\/api\/session\/([^/]+)\/delegated-runs\/[^/]+\/wait$/, session: "path" },
+    { method: "POST", path: /^\/api\/apps\/[a-zA-Z]+$/, session: "body" },
+    { method: "POST", path: /^\/api\/session\/fork$/, session: "body" },
+    { method: "GET", path: /^\/api\/machines$/, session: "none" },
+];
+/** Whether a request made with `sessionId`'s token is one it may make. */
+export function sessionTokenAllows(sessionId, req) {
+    for (const route of SESSION_TOKEN_ROUTES) {
+        if (route.method !== req.method)
+            continue;
+        const match = route.path.exec(req.path);
+        if (!match)
+            continue;
+        if (route.session === "none")
+            return true;
+        const named = route.session === "path"
+            ? decodeURIComponent(match[1] ?? "")
+            : req.body?.sessionId;
+        return named === sessionId;
+    }
+    return false;
+}

package/package.json

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