@bivy/bivy 0.19.4-staging.3 → 0.19.4-staging.5

package/bin/bivy.mjs

@@ -43,7 +43,7 @@ import { findAvailablePort, reconcilePort } from "./port-picker.mjs";
 import { resolveAttachSessionId } from "./attach-session-id.mjs";
 import { detectInstallKind as classifyInstallKind, npmGlobalPrefix } from "./install-kind.mjs";
 import { hasConfiguredService as configuredServiceExists } from "./service-state.mjs";
-import { COMMANDS, EXIT, cliError, completionWords, describeCli, describeCommand, renderHelp, resolveCommand, subcommandTable, suggestCommands, wantsJson } from "./cli-commands.mjs";
+import { COMMANDS, EXIT, cliError, completionWords, describeCli, describeCommand, describeTools, renderHelp, resolveCommand, subcommandTable, suggestCommands, toolArgv, wantsJson } from "./cli-commands.mjs";
 
 const selfScript = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(selfScript);
@@ -2541,6 +2541,283 @@ async function cmdSuggest(args = []) {
   console.log(c.green("Suggested in the chat. The user can start it in one tap."));
 }
 
+// Flags shared by the session commands: `--name value` pairs and bare switches,
+// with every other word collected as positional text.
+function parseSessionArgs(args, valueFlags) {
+  const values = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (valueFlags.includes(a)) {
+      const v = args[i + 1];
+      if (v === undefined) return { error: `${a} requires a value.` };
+      (values[a] ??= []).push(v);
+      i++;
+    } else if (!a.startsWith("--")) positional.push(a);
+  }
+  return { values, positional, has: (flag) => args.includes(flag), one: (flag) => values[flag]?.[0] };
+}
+
+// "90", "90s", "10m", "2h" → seconds.
+function durationSeconds(text) {
+  const m = /^(\d+)(s|m|h)?$/.exec(String(text ?? "").trim());
+  return m ? Number(m[1]) * (m[2] === "h" ? 3600 : m[2] === "m" ? 60 : 1) : NaN;
+}
+
+// `bivy notify "<message>" [--urgent]` — reach the user: a card in the chat,
+// and a push naming the session (never the text) when nobody has the app open.
+async function cmdNotify(args = []) {
+  const usage = 'Usage: bivy notify "<message>" [--urgent] [--session <id>] [--json]';
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log(`${usage}
+
+Send the user a message: it appears as a card in the chat, and their devices get
+a push notification (naming this session, not the text) when nobody has the app
+open. --urgent pushes even while they do. At most one push a minute per session;
+later messages still reach the chat. Use it when you finish long work, get
+blocked, or need the user to look at something. --json prints
+{"ok","id","push":"sent"|"user_watching"|"rate_limited","userWatching"}.`);
+    return;
+  }
+  const json = wantsJson(args);
+  const fail = (error) => cliError(error, { json, paint: c.red });
+  const parsed = parseSessionArgs(args, ["--session"]);
+  if (parsed.error) return fail({ code: "usage", message: parsed.error, exit: EXIT.usage });
+  const text = parsed.positional.join(" ").trim();
+  if (!text) return fail({ code: "usage", message: usage, exit: EXIT.usage });
+  const sessionId = resolveAttachSessionId({ sessionFlag: parsed.one("--session"), env: process.env });
+  if (!sessionId) return fail({ code: "no_session", message: "No session id.", hint: "Run inside an agent session ($BIVY_SESSION_ID) or pass --session <id>.", next: "bivy sessions --json", 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 });
+  const res = await sessionPost(config, sessionId, "notify", { text, urgent: parsed.has("--urgent") }).catch((error) => error);
+  if (res instanceof Error) return fail({ code: "node_unreachable", message: `Could not reach the Bivy node: ${res.message}`, next: "bivy status", exit: EXIT.unavailable });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) return fail(sessionHttpError("Notify", res.status, body));
+  if (json) { console.log(JSON.stringify(body)); return; }
+  const pushed = { sent: "and pushed to the user's devices", user_watching: "(no push: the user has the app open; add --urgent to push anyway)", rate_limited: "(no push: this session pushed less than a minute ago)", unavailable: "(no push: this machine isn't signed in to a Bivy account)" }[body.push] ?? "";
+  console.log(c.green(`Posted in the chat ${pushed}.`.replace(" .", ".")));
+}
+
+// `bivy ask "<question>" [--option …]` — the question card, for any agent.
+// Blocks until the user answers (printing the answer), or with --async returns
+// an id to read later with `bivy ask status|wait <id>`.
+const ASK_USAGE = `Usage: bivy ask "<question>" [--option <label>]… [--multi] [--header <label>] [--timeout 10m] [--async] [--json]
+       bivy ask status <id> [--json]
+       bivy ask wait <id> [--timeout 10m] [--json]`;
+
+async function cmdAsk(args = []) {
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log(`${ASK_USAGE}
+
+Ask the user a question in the chat and wait for the answer. Their devices get a
+"needs your input" push. With --option (2 to 8 of them) they pick one (or
+several with --multi) or write their own; without options they type an answer.
+--header is the short label on the card.
+
+Prints the answer and exits 0. Exits 1 if the user dismissed the question and 5
+if --timeout (default 10m, up to 24h) passes first; the card closes then.
+--async returns the question's id at once; 'bivy ask wait <id>' blocks for the
+answer later and 'bivy ask status <id>' checks without waiting.
+--json prints {"id","status":"pending"|"answered"|"dismissed"|"expired","answer"}.`);
+    return;
+  }
+  const json = wantsJson(args);
+  const fail = (error) => cliError(error, { json, paint: c.red });
+  const parsed = parseSessionArgs(args, ["--session", "--option", "--header", "--timeout"]);
+  if (parsed.error) return fail({ code: "usage", message: parsed.error, exit: EXIT.usage });
+  const sessionId = resolveAttachSessionId({ sessionFlag: parsed.one("--session"), env: process.env });
+  if (!sessionId) return fail({ code: "no_session", message: "No session id.", hint: "Run inside an agent session ($BIVY_SESSION_ID) or pass --session <id>.", next: "bivy sessions --json", exit: EXIT.usage });
+  const timeout = parsed.one("--timeout") === undefined ? 600 : durationSeconds(parsed.one("--timeout"));
+  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 base = `${url(config)}/api/session/${encodeURIComponent(sessionId)}/ask`;
+  const call = async (suffix, body) => {
+    const res = await fetch(`${base}${suffix}`, {
+      method: body ? "POST" : "GET",
+      headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    }).catch((error) => error);
+    if (res instanceof Error) return fail({ code: "node_unreachable", message: `Could not reach the Bivy node: ${res.message}`, next: "bivy status", exit: EXIT.unavailable });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) return fail(sessionHttpError("Ask", res.status, data));
+    return data;
+  };
+  const answerText = (result) => Object.values(result.answers ?? {}).join("\n");
+  const finish = (result) => {
+    const out = { id: result.id, status: result.status, ...(result.status === "answered" ? { answer: answerText(result) } : {}) };
+    if (result.status === "answered") { console.log(json ? JSON.stringify(out) : out.answer); return; }
+    if (result.status === "pending") { console.log(json ? JSON.stringify(out) : `Still waiting for an answer. Check again with: bivy ask wait ${result.id}`); process.exit(EXIT.timeout); }
+    if (json) console.log(JSON.stringify(out));
+    else console.error(result.status === "expired" ? "The question timed out without an answer." : "The user dismissed the question without answering.");
+    process.exit(result.status === "expired" ? EXIT.timeout : EXIT.failed);
+  };
+  const waitFor = async (id, seconds) => {
+    const deadline = Date.now() + seconds * 1000;
+    let result = await call(`/${encodeURIComponent(id)}`);
+    while (result.status === "pending" && Date.now() < deadline) {
+      result = await call(`/${encodeURIComponent(id)}/wait`, { timeoutSeconds: Math.max(1, Math.min(240, Math.ceil((deadline - Date.now()) / 1000))) });
+    }
+    return result;
+  };
+
+  const [action, id] = parsed.positional;
+  if ((action === "status" || action === "wait") && id && parsed.positional.length === 2) {
+    const result = action === "status" ? await call(`/${encodeURIComponent(id)}`) : await waitFor(id, timeout);
+    if (action === "status" && result.status === "pending") { console.log(json ? JSON.stringify({ id: result.id, status: "pending" }) : "Still waiting for an answer."); return; }
+    return finish(result);
+  }
+  const question = parsed.positional.join(" ").trim();
+  if (!question) return fail({ code: "usage", message: ASK_USAGE, exit: EXIT.usage });
+  const options = parsed.values["--option"] ?? [];
+  if (options.length === 1) return fail({ code: "usage", message: "Offer at least two --option values, or none for a free-text answer.", exit: EXIT.usage });
+  const started = await call("", {
+    questions: [{ question, header: parsed.one("--header"), options, multiSelect: parsed.has("--multi") }],
+    timeoutSeconds: timeout,
+  });
+  if (parsed.has("--async")) {
+    console.log(json ? JSON.stringify({ id: started.id, status: started.status }) : `Asked. Get the answer with: bivy ask wait ${started.id}`);
+    return;
+  }
+  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 } = {}) {
+  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 });
+  let token;
+  try { token = await localDeviceToken(config); } catch { token = undefined; }
+  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 });
+  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
@@ -5570,6 +5847,57 @@ function cmdHelp(args = []) {
   console.log(`Usage: ${row.usage}\n\n${row.summary}${row.aliases.length ? `\nAliases: ${row.aliases.join(", ")}` : ""}${row.subcommands.length ? `\nSubcommands: ${row.subcommands.join(", ")}` : ""}\n\nFull options: ${row.help}`);
 }
 
+// `bivy guide [topic]` — short playbooks for agents, one markdown file per
+// topic in bin/guides (a "# Title" line, then "Summary: …").
+function readGuides() {
+  const dir = path.join(__dirname, "guides");
+  return fs.readdirSync(dir).filter((file) => file.endsWith(".md")).sort().map((file) => {
+    const markdown = fs.readFileSync(path.join(dir, file), "utf8");
+    return {
+      topic: file.slice(0, -3),
+      title: markdown.match(/^# (.+)$/m)?.[1] ?? file,
+      summary: markdown.match(/^Summary: (.+)$/m)?.[1] ?? "",
+      markdown: markdown.replace(/^Summary: .+\n\n?/m, ""),
+    };
+  });
+}
+
+// `bivy tool <name> '<json>'` — how `bivy mcp-serve` runs a tool: map the input
+// to the command's words and run it with --json, so a tool and its command can't
+// behave differently.
+function cmdTool(args = []) {
+  const [name, raw = "{}"] = args;
+  const tool = describeTools().find((t) => t.name === name);
+  if (!tool) return cliError({ code: "unknown_tool", message: `No tool called "${name}".`, next: "bivy help --json", exit: EXIT.usage }, { json: true });
+  let input;
+  try { input = JSON.parse(raw); } catch { return cliError({ code: "usage", message: "Tool input must be a JSON object.", exit: EXIT.usage }, { json: true }); }
+  const result = spawnSync(process.execPath, [selfScript, ...toolArgv(tool.argv, input ?? {}), "--json"], { stdio: "inherit", env: process.env });
+  process.exit(result.status ?? EXIT.failed);
+}
+
+function cmdGuide(args = []) {
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log("Usage: bivy guide [topic] [--json]\n\nShort playbooks for agents working in Bivy. Without a topic, lists them.");
+    return;
+  }
+  const json = wantsJson(args);
+  const guides = readGuides();
+  const topic = args.find((a) => !a.startsWith("-"));
+  if (!topic) {
+    if (json) { console.log(JSON.stringify({ guides: guides.map(({ topic: t, title, summary }) => ({ topic: t, title, summary })) }, null, 2)); return; }
+    console.log(`${c.bold("Guides")}  (bivy guide <topic>)\n`);
+    for (const guide of guides) console.log(`  ${c.cyan(guide.topic.padEnd(18))} ${guide.summary}`);
+    return;
+  }
+  const guide = guides.find((g) => g.topic === topic);
+  if (!guide) {
+    cliError({ code: "unknown_guide", message: `No guide called "${topic}".`, hint: `Guides: ${guides.map((g) => g.topic).join(", ")}.`, next: "bivy guide", exit: EXIT.notFound }, { json, paint: c.red });
+    return;
+  }
+  if (json) { console.log(JSON.stringify({ topic: guide.topic, title: guide.title, markdown: guide.markdown }, null, 2)); return; }
+  console.log(guide.markdown.trimEnd());
+}
+
 async function main() {
   await hydrateCanonicalConfig();
   const argv = process.argv.slice(2);
@@ -5664,6 +5992,24 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
     case "suggest":
       await cmdSuggest(args);
       break;
+    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;
     case "delegate":
       await cmdDelegate(args);
       break;
@@ -5931,6 +6277,12 @@ Unlike 'bivy run', these commands operate on governed background Runs with check
     case "context":
       await cmdContext(args);
       break;
+    case "guide":
+      cmdGuide(args);
+      break;
+    case "tool":
+      cmdTool(args);
+      break;
     case "version":
       console.log(readSelfVersion());
       break;

package/bin/cli-commands.mjs

@@ -16,6 +16,15 @@
 //   json        true when it accepts --json (or honors BIVY_OUTPUT=json)
 //   subcommands first-argument verbs, for completion and discovery
 //   hidden      plumbing launched by Bivy itself; left out of help and completions
+//   tools       MCP tools `bivy mcp-serve` offers for this command. Each maps
+//               its input to CLI words (`argv`, below) and runs `bivy … --json`,
+//               so a tool behaves exactly like the command. Only session
+//               commands that are safe to call routinely get one; delegation
+//               and Runs stay shell-only on purpose (docs/agent-delegation.md).
+//
+// A tool's `argv` is data: a literal word, {arg} (a positional value),
+// {flag, from} (a flag with a value, repeated for arrays, joined with `join`),
+// or {when, flag} (a bare switch when the input is true).
 
 /** Exit codes shared by the commands agents call. 0 and 1 hold everywhere. */
 export const EXIT = Object.freeze({ ok: 0, failed: 1, usage: 2, notFound: 3, denied: 4, timeout: 5, conflict: 6, unavailable: 75 });
@@ -32,10 +41,22 @@ export const GROUPS = [
 
 export const COMMANDS = [
   // Inside an agent session
-  { name: "context", group: "session", scope: "session", json: true, usage: "context [--json]", summary: "Where this agent is running: session, workspace, machine, apps, and what to run next" },
+  { name: "context", group: "session", scope: "session", json: true, usage: "context [--json]", summary: "Where this agent is running: session, workspace, machine, apps, and what to run next",
+    tools: [{ name: "bivy_context", description: "Where you are running inside Bivy: your session, agent, workspace and git branch, the machine, apps you have published, whether the user has the app open, and the commands that reach them.", input: {}, argv: ["context"] }] },
   { name: "attach", group: "session", scope: "session", json: true, usage: 'attach <file> [--caption "…"] [--artifact]', summary: "Show a local file or image to the user in the chat" },
-  { name: "suggest", group: "session", scope: "session", json: true, usage: 'suggest "<task>" [--title "label"]', summary: "Propose a task the user can start in one tap" },
-  { name: "app", group: "session", scope: "session", json: true, usage: "app <publish|shot|present|share|run|…>", summary: "Live previews: publish a web/terminal/desktop app, screenshot it, present it", subcommands: ["publish", "list", "remove", "shot", "present", "share", "notes", "run", "click", "type", "key", "scroll", "drag", "move", "menu"] },
+  { name: "notify", group: "session", scope: "session", json: true, usage: 'notify "<message>" [--urgent]', summary: "Message the user: a card in the chat, and a push when they're away",
+    tools: [{ name: "notify_user", description: "Send the user a message: a card in the chat, and a push to their phone when nobody has the app open (the push names the session, not the text). Use it when long work finishes, you are blocked, or something needs their attention. At most one push a minute per session.", input: { message: { type: "string", description: "What to tell the user.", required: true }, urgent: { type: "boolean", description: "Push even while the user has the app open." } }, argv: ["notify", { arg: "message" }, { when: "urgent", flag: "--urgent" }] }] },
+  { name: "ask", group: "session", scope: "session", json: true, usage: 'ask "<question>" [--option A --option B] [--async]', summary: "Ask the user a question and wait for the answer", subcommands: ["status", "wait"],
+    tools: [{ name: "ask_user", description: "Ask the user a question in the chat and wait for their answer (their phone gets a push). Offer 2-8 options, or none for a free-text answer; they can always write their own. Returns {status, answer}: status is answered, dismissed (decide yourself) or expired.", input: { question: { type: "string", description: "The question.", required: true }, options: { type: "array", items: { type: "string" }, description: "Choices to pick from (2-8)." }, multiple: { type: "boolean", description: "Allow several choices." }, header: { type: "string", description: "A short label for the card." }, timeout_seconds: { type: "number", description: "How long to wait (default 600)." } }, argv: ["ask", { arg: "question" }, { flag: "--option", from: "options" }, { when: "multiple", flag: "--multi" }, { flag: "--header", from: "header" }, { flag: "--timeout", from: "timeout_seconds" }] }] },
+  { name: "suggest", group: "session", scope: "session", json: true, usage: 'suggest "<task>" [--title "label"]', summary: "Propose a task the user can start in one tap",
+    tools: [{ name: "suggest_task", description: "Propose a next step the user can start in one tap, in this session or in a parallel one with its own copy of the project. Write the task as a complete instruction with paths relative to the project root. Post one per idea instead of listing them.", input: { task: { type: "string", description: "The complete instruction.", required: true }, title: { type: "string", description: "A short label for the card." } }, argv: ["suggest", { arg: "task" }, { flag: "--title", from: "title" }] }] },
+  { name: "app", group: "session", scope: "session", json: true, usage: "app <publish|shot|present|share|run|…>", summary: "Live previews: publish a web/terminal/desktop app, screenshot it, present it", subcommands: ["publish", "list", "remove", "shot", "present", "share", "notes", "run", "click", "type", "key", "scroll", "drag", "move", "menu"],
+    tools: [
+      { name: "app_publish", description: "Give the user a live preview of something with a UI, from an app manifest file (web server port, static build, terminal, or desktop app). Run `bivy app --help` for the manifest format.", input: { manifest_path: { type: "string", description: "Path to the manifest JSON.", required: true } }, argv: ["app", "publish", { arg: "manifest_path" }] },
+      { 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
@@ -48,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" },
@@ -91,16 +114,20 @@ 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"] },
   { name: "completions", aliases: ["completion"], group: "config", scope: "node", usage: "completions <bash|zsh|fish>", summary: "Print a shell completion script", subcommands: ["bash", "zsh", "fish"] },
 
   // Help and discovery
+  { name: "guide", group: "help", scope: "node", json: true, usage: "guide [topic] [--json]", summary: "Short playbooks for agents: show the user, talk to them, long work, more hands, automate",
+    tools: [{ name: "bivy_guide", description: "Short playbooks for working in Bivy. Without a topic, lists them.", input: { topic: { type: "string", description: "show-the-user, talk-to-the-user, long-work, more-hands or automate." } }, argv: ["guide", { arg: "topic" }] }] },
   { name: "help", aliases: ["-h", "--help"], group: "help", scope: "node", json: true, usage: "help [command] [--json]", summary: "Show this help, one command's row, or every command as JSON" },
   { name: "version", aliases: ["--version", "-v"], group: "help", scope: "node", usage: "version", summary: "Print the installed Bivy version" },
 
   // Plumbing
+  { name: "tool", group: "help", scope: "session", hidden: true, json: true, usage: "tool <name> '<json input>'", summary: "Run one MCP tool (from `bivy help --json`) as its bivy command" },
   { name: "mcp-serve", group: "help", scope: "session", hidden: true, usage: "mcp-serve", summary: "Bivy's MCP server for agents (stdio; injected into agent MCP config)" },
   { name: "mcp-proxy", group: "help", scope: "session", hidden: true, usage: "mcp-proxy -- <server command>", summary: "MCP proxy in front of an agent's own MCP servers (stdio)" },
 ];
@@ -154,6 +181,41 @@ export function subcommandTable() {
   }));
 }
 
+/** A tool's input as JSON Schema. */
+function toolSchema(input) {
+  const properties = {};
+  const required = [];
+  for (const [key, { required: isRequired, ...schema }] of Object.entries(input)) {
+    properties[key] = schema;
+    if (isRequired) required.push(key);
+  }
+  return { type: "object", properties, ...(required.length ? { required } : {}), additionalProperties: false };
+}
+
+/** Every MCP tool, with its JSON Schema and argv template: what `bivy mcp-serve` offers. */
+export function describeTools() {
+  return COMMANDS.flatMap((command) => (command.tools ?? []).map((tool) => ({
+    name: tool.name, description: tool.description, inputSchema: toolSchema(tool.input), argv: tool.argv, command: command.name,
+  })));
+}
+
+/** The `bivy` words for a tool call: argv template + the caller's input. */
+export function toolArgv(argv, input = {}) {
+  const words = [];
+  for (const part of argv) {
+    if (typeof part === "string") words.push(part);
+    else if (part.arg) { if (input[part.arg] !== undefined && input[part.arg] !== "") words.push(String(input[part.arg])); }
+    else if (part.when) { if (input[part.when] === true) words.push(part.flag); }
+    else if (part.flag) {
+      const value = input[part.from];
+      if (value === undefined || value === null || value === "") continue;
+      if (Array.isArray(value) && part.join) words.push(part.flag, value.join(part.join));
+      else for (const item of Array.isArray(value) ? value : [value]) words.push(part.flag, String(item));
+    }
+  }
+  return words;
+}
+
 /** One command as plain data: what `bivy help --json` and `bivy help <cmd> --json` print. */
 export function describeCommand(command) {
   const { name, aliases = [], group, usage, summary, scope, json = false, subcommands = [] } = command;
@@ -166,6 +228,7 @@ export function describeCli() {
     output: "Commands marked json accept --json; BIVY_OUTPUT=json turns it on for every such command.",
     errors: "With --json, failures print {\"error\":{\"code\",\"message\",\"hint\"?,\"next\"?}} to stderr.",
     commands: COMMANDS.filter((command) => !command.hidden).map(describeCommand),
+    tools: describeTools(),
   };
 }
 

package/bin/guides/automate.md

@@ -0,0 +1,19 @@
+# Automate
+
+Summary: Automations as code: write, validate, preview, test, apply and trigger.
+
+Automations live in the repository, in `.bivy/automations.yaml`, and apply like
+infrastructure code:
+
+    bivy automation init                           # write a safe starter file
+    bivy automation validate                       # check it
+    bivy automation plan --json                    # triggers, routing, effective safety
+    bivy automation test --event event.json        # which automation an event would start
+    bivy automation apply                          # reconcile the account with the file
+    bivy automation list --json
+    bivy automation trigger <id-or-key>            # run one now
+
+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/long-work.md

@@ -0,0 +1,23 @@
+# Long and unattended work
+
+Summary: One-shot answers, governed Runs with checks and receipts, and following them.
+
+## One question, one answer
+
+    bivy exec "Summarize the open TODOs in src/" --json
+
+Runs a headless session and prints the answer (`{"sessionId","answer"}` with
+`--json`).
+
+## A governed Run
+
+    bivy runs start "Upgrade the test runner and fix what breaks"
+    bivy runs list --json
+    bivy runs wait <id> --timeout 3600 --json
+
+A Run is unattended work with checks, evidence and a Receipt. `runs wait` exits
+0 when it succeeded, 1 when it failed or was cancelled, 2 on timeout.
+
+## While you wait
+
+Tell the user when it matters: `bivy notify "…"` (see `bivy guide talk-to-the-user`).

package/bin/guides/more-hands.md

@@ -0,0 +1,24 @@
+# More hands: other agents and machines
+
+Summary: Delegate a task to another agent or machine, compare several, and follow the result.
+
+Use your own sub-agents for ordinary work. Delegate only when the user asks for
+another agent or another of their machines.
+
+    bivy delegate machines                                   # machines and their agents
+    bivy delegate "Review this branch for bugs" --agent codex --wait
+    bivy delegate "Run the Linux-only build" --machine build-box --agent claude --wait
+    bivy delegate "Propose a fix for issue 42" --to codex,claude@laptop --wait
+
+Write the task so it stands on its own: the other agent does not see this chat.
+`--wait` prints the child's answer and any branch or PR it pushed. Without it you
+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

@@ -0,0 +1,49 @@
+# Show the user something
+
+Summary: Attach files, publish live previews, check them with screenshots, and present a finished change.
+
+The user reads your session in a chat app, often on a phone. They cannot see your
+terminal, your files, or anything you only describe. Put things in front of them.
+
+## A file or image
+
+    bivy attach out/chart.png --caption "Revenue by month"
+    bivy attach report.pdf --artifact
+
+Images render inline; other files download. The path must be inside the session
+workspace. `--artifact` also lists it in the session's Artifacts, for durable
+outputs (reports, coverage, builds). Markdown image syntax with a local path does
+not render; a remote `https://` image does.
+
+## Something with a UI
+
+Publish it once; the user opens it from the chat:
+
+    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",
+      "source":{"kind":"service","port":5173,"start":{"command":"pnpm","args":["dev"]}}}]}
+
+## Check your work before you say it's done
+
+    bivy app shot --widths 390,1280 --themes light,dark
+
+prints PNG paths. Look at them. Screenshots are off until the user turns them
+on (`bivy config set sessions.appScreenshots true`).
+
+## Hand it over
+
+    bivy app present --note "The header now wraps on phones"
+
+posts a card with the app at phone width (before and after) and opens the
+preview. Use it when a visible change is ready, not after every edit.
+
+More: `bivy app --help`, `bivy attach --help`.

package/bin/guides/talk-to-the-user.md

@@ -0,0 +1,38 @@
+# Talk to the user
+
+Summary: When to answer in chat, when to notify, when to ask and wait, and how to offer next steps.
+
+Your chat reply is the default. Reach for these when the chat alone won't do.
+
+## They may be away: notify
+
+    bivy notify "Migration finished: 3 tables rewritten, all tests pass."
+    bivy notify --urgent "Production is serving the old build."
+
+Posts a card in the chat. When nobody has the app open, their devices get a push
+naming this session (the text stays in the chat). `--urgent` pushes even while
+they are looking. One push a minute per session; don't send one per step.
+Good moments: long work finished, you are blocked, something needs a look.
+
+## You need a decision: ask
+
+    bivy ask "Which database?" --option Postgres --option SQLite
+    bivy ask "What should the release be called?"
+
+Blocks until they answer and prints the answer (exit 0). Exit 1 means they
+dismissed it (use your judgment), exit 5 that `--timeout` (default 10m) passed.
+For long waits use `--async`, keep working, and later `bivy ask wait <id>`.
+Ask only when you can't reasonably decide yourself.
+
+## Offer next steps: suggest
+
+    bivy suggest "Add a GET /version endpoint that returns the package version." --title "Add /version"
+
+Each suggestion is a card the user can start in one tap, here or in a parallel
+session with its own copy of the project. Write it as a complete instruction with
+paths relative to the project root. Post one per idea instead of a bulleted list.
+
+## Is anyone there?
+
+`bivy context --json` reports `userConnected` (some device has the app open) and
+`lastDriver` (the device that last typed into this session).

package/dist/agent-instructions.js

@@ -42,11 +42,15 @@ export const BIVY_AGENT_NOTE = [
         '`bivy suggest "<complete instruction>" [--title "short label"]` instead of only listing them. The user can ' +
         "start each in one tap, in this session or in a parallel one that works in its own copy of the project, so " +
         "write it to stand on its own, with paths relative to the project root.",
+    "- When you finish long work, get blocked, or need the user to look at something: " +
+        '`bivy notify "<message>"` (a chat card, plus a push to their phone when they are away). To ask and wait for ' +
+        'an answer: `bivy ask "<question>" [--option A --option B]` prints their answer (or use your own ask-the-user tool).',
     "- Only when the user asks for another agent or another of their machines to take part: " +
         '`bivy delegate "<self-contained task>" --agent <id> [--machine <name>] --wait` runs it there and prints ' +
         "its answer and any branch/PR; `--to codex,grok@<machine>` asks several to compare, `bivy delegate machines` " +
         "lists machines and their agents. Use your own sub-agents for everything else.",
-    "- `bivy context` shows your session, workspace and published apps; `bivy help` lists every command (`--json` for all).",
+    "- `bivy context` shows your session, workspace and published apps; `bivy guide` has short playbooks; " +
+        "`bivy help` lists every command (`--json` for all).",
 ].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.";

package/dist/apps/styles.css

@@ -3119,17 +3119,23 @@ p.setup-note .btn.link { min-height: 44px; margin-block: calc((1lh - 44px) / 2);
 /* Suggested task (SuggestionCard.tsx): a task the agent proposed, one tap to
    start in its own session. Shell from .card; layout only here. */
 .suggestion-card { max-inline-size: 440px; display: flex; flex-direction: column; gap: var(--space-1); }
-.suggestion-eyebrow { margin: 0; color: var(--muted); font-size: var(--text-xs); font-weight: var(--weight-semibold); }
+/* The small label above a chat card's content, shared by every agent-posted card. */
+.suggestion-eyebrow, .delegation-eyebrow, .notice-eyebrow { margin: 0; color: var(--muted); font-size: var(--text-xs); font-weight: var(--weight-semibold); }
 .suggestion-title { margin: 0; font-size: var(--text-base); font-weight: var(--weight-semibold); overflow-wrap: anywhere; }
 .suggestion-text { margin: 0; color: var(--muted); font-size: var(--text-sm); white-space: pre-wrap; overflow-wrap: anywhere; display: -webkit-box; -webkit-line-clamp: 4; -webkit-box-orient: vertical; overflow: hidden; }
 .suggestion-actions, .suggestion-all { display: flex; flex-wrap: wrap; gap: var(--space-2); margin-top: var(--space-2); }
 .suggestion-all { padding-top: var(--space-2); border-top: 1px solid var(--line); }
 .suggestion-status { margin: var(--space-2) 0 0; display: flex; align-items: center; gap: var(--space-2); color: var(--ok); font-size: var(--text-sm); font-weight: var(--weight-medium); }
+/* Notice (NoticeCard.tsx): a message the agent sent with `bivy notify`.
+   Shell and tone from .card, the urgent marker from .badge. */
+.notice-card { max-inline-size: 440px; display: flex; flex-direction: column; gap: var(--space-1); }
+.notice-eyebrow { display: flex; align-items: center; gap: var(--space-2); }
+.notice-text { margin: 0; font-size: var(--text-base); white-space: pre-wrap; overflow-wrap: anywhere; }
+
 /* Delegation (DelegationCard.tsx): a task handed to another agent/machine.
    Shell from .card, status from .badge; layout only here. A fan-out renders as
    one group whose members sit side by side where there is room. */
 .delegation-card { max-inline-size: 440px; display: flex; flex-direction: column; gap: var(--space-1); }
-.delegation-eyebrow { margin: 0; color: var(--muted); font-size: var(--text-xs); font-weight: var(--weight-semibold); }
 .delegation-head { display: flex; align-items: center; justify-content: space-between; gap: var(--space-2); }
 .delegation-head { align-items: flex-start; }
 .delegation-target { display: flex; flex-direction: column; font-weight: var(--weight-semibold); overflow-wrap: anywhere; min-inline-size: 0; }

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

@@ -7,7 +7,11 @@
 // start (see mcp-inject.ts's injectBivyToolsForSession), it exposes Bivy's chat
 // affordances as first-class tools so ANY agent — codex, gemini, aider, opencode,
 // … — discovers them in its tool list instead of having to be told about a shell
-// command (issue #290). Today it serves one tool, `attach_to_chat`.
+// command (issue #290). It serves `attach_to_chat`, plus every tool listed in
+// the `bivy` command table (bin/cli-commands.mjs, read through `bivy help
+// --json`): each runs as `bivy tool <name> <json>`, i.e. the command itself with
+// --json, so tools and commands share one implementation and error contract.
+// The agent guides (`bivy guide`) are served as resources.
 //
 // Claude and Pi already get `attach_to_chat` natively (in-process SDK MCP server /
 // integration ToolProvider); this covers everyone else. The tool just POSTs to the
@@ -20,12 +24,13 @@
 // 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 { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 const DEFAULT_ENDPOINT = "http://127.0.0.1:4317";
 /** The tools this server advertises, in MCP `tools/list` shape. */
 export const BIVY_MCP_TOOLS = [
@@ -89,6 +94,30 @@ 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) {
+    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"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => { stdout += chunk; });
+        child.stderr.on("data", (chunk) => { stderr += chunk; });
+        child.on("error", (error) => resolve({ code: 1, stdout, stderr: stderr || error.message }));
+        child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    });
+}
+/** The tools the command table offers, or none when the CLI can't be asked. */
+async function cliTools(runBivy) {
+    const result = await runBivy(["help", "--json"]);
+    try {
+        const tools = JSON.parse(result.stdout).tools ?? [];
+        return tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }));
+    }
+    catch {
+        return [];
+    }
+}
 /** The user's instructions to advertise at initialize, or undefined when there are none. */
 function readInstructions(file) {
     if (!file)
@@ -107,14 +136,47 @@ export function createBivyMcpServer(deps = {}) {
     const token = deps.token ?? process.env.BIVY_MCP_TOKEN ?? undefined;
     const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
     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 }));
+    const runBivy = deps.runBivy ?? defaultRunBivy(sessionId);
+    let tools;
+    const generated = () => (tools ??= cliTools(runBivy));
+    const server = new Server({ name: "bivy", version: "1.0.0" }, { capabilities: { tools: {}, resources: {} }, ...(instructions ? { instructions } : {}) });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...BIVY_MCP_TOOLS, ...await generated()] }));
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const args = (req.params.arguments ?? {});
-        const result = req.params.name === "attach_to_chat"
-            ? await runAttachToChat(endpoint, sessionId, args, fetchImpl, token)
-            : { isError: true, text: `Unknown tool: ${req.params.name}` };
-        return { isError: result.isError, content: [{ type: "text", text: result.text }] };
+        if (req.params.name === "attach_to_chat") {
+            const result = await runAttachToChat(endpoint, sessionId, args, fetchImpl, token);
+            return { isError: result.isError, content: [{ type: "text", text: result.text }] };
+        }
+        if (!(await generated()).some((tool) => tool.name === req.params.name)) {
+            return { isError: true, content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }] };
+        }
+        const result = await runBivy(["tool", req.params.name, JSON.stringify(args)]);
+        const text = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n") || (result.code === 0 ? "Done." : `bivy exited ${result.code}.`);
+        return { isError: result.code !== 0, content: [{ type: "text", text }] };
+    });
+    // The agent guides, one resource per topic.
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const result = await runBivy(["guide", "--json"]);
+        const guides = (() => { try {
+            return JSON.parse(result.stdout).guides;
+        }
+        catch {
+            return [];
+        } })();
+        return { resources: guides.map((g) => ({ uri: `bivy://guide/${g.topic}`, name: g.title, description: g.summary, mimeType: "text/markdown" })) };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+        const topic = /^bivy:\/\/guide\/([a-z0-9-]+)$/.exec(req.params.uri)?.[1];
+        const result = topic ? await runBivy(["guide", topic, "--json"]) : undefined;
+        const guide = (() => { try {
+            return result && result.code === 0 ? JSON.parse(result.stdout) : undefined;
+        }
+        catch {
+            return undefined;
+        } })();
+        if (!guide)
+            throw new Error(`No Bivy resource at ${req.params.uri}`);
+        return { contents: [{ uri: req.params.uri, mimeType: "text/markdown", text: guide.markdown }] };
     });
     return server;
 }

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/question.js

@@ -48,7 +48,7 @@ export class QuestionManager {
      */
     request(input) {
         const request = {
-            id: randomUUID(),
+            id: input.id ?? randomUUID(),
             sessionId: input.sessionId,
             questions: input.questions,
             createdAt: Date.now(),

package/dist/server.js

@@ -127,6 +127,8 @@ import { createPresenceCommands } from "./controllers/presence-commands.js";
 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 { MAX_NOTICE_TEXT, isAgentNotice, noticePush } from "./session/notices.js";
 import { createForkCommands } from "./controllers/fork-commands.js";
 import { createGithubCommands } from "./controllers/github-commands.js";
 import { createCredentialCommands } from "./controllers/credential-commands.js";
@@ -398,6 +400,7 @@ const auditLog = createAuditLog(path.join(appDir, "audit"), { signer: auditKey.s
 // clarifying question across sessions; the guardian interceptor below raises
 // them, and session.question(.resolved) is broadcast from its listeners.
 const questionManager = new QuestionManager();
+const agentQuestions = new AgentQuestions(questionManager);
 questionManager.onRequest((request) => {
     scheduleAdvertise();
     broadcast({ type: "session.question", sessionId: request.sessionId, requestId: request.id, questions: request.questions, createdAt: request.createdAt });
@@ -11527,10 +11530,65 @@ app.get("/api/session/:id/context", (req, res) => {
         },
         machine: { name: identity.name, platform: process.platform, arch: process.arch },
         presence: presenceBook.get(record.id),
+        userConnected: clients.size > 0 || (relay?.clientCount ?? 0) > 0,
         apps,
         previewAvailable,
     }));
 });
+// `bivy notify "<message>"`: a card in the chat, and a push naming the session
+// (never the text) when nobody has the app open, or when it's urgent. At most
+// one push a minute per session; later notices still post a card.
+const lastNotifyPush = new Map();
+app.post("/api/session/:id/notify", (req, res) => {
+    const record = openSessions.get(String(req.params.id));
+    if (!record)
+        return res.status(404).json({ error: "Session not found" });
+    const text = typeof req.body?.text === "string" ? req.body.text.trim() : "";
+    const notice = { id: `notice-${randomBytes(8).toString("hex")}`, text, ...(req.body?.urgent === true ? { urgent: true } : {}) };
+    if (!isAgentNotice(notice))
+        return res.status(400).json({ error: `A notice needs text (up to ${MAX_NOTICE_TEXT} characters).` });
+    eventLog.appendNotice(record.id, { afterMessageCount: record.session.getMessages().length, notice });
+    broadcast(stampSessionEvent({ type: "session.event", sessionId: record.id, event: { type: "notice", id: notice.id, notice } }));
+    const watching = clients.size > 0 || (relay?.clientCount ?? 0) > 0;
+    const push = noticePush({ urgent: notice.urgent, userWatching: watching, lastPushAt: lastNotifyPush.get(record.id), now: Date.now(), pushConfigured: Boolean(sessionAdvertiseTarget) });
+    if (push === "sent") {
+        lastNotifyPush.set(record.id, Date.now());
+        void sendNotificationHint({
+            kind: "agent_notice",
+            sessionId: record.id,
+            targetSessionId: record.id,
+            title: sessionNotifyLabel(record),
+            body: "Has a message for you — tap to read it.",
+        });
+    }
+    res.json({ ok: true, id: notice.id, push, userWatching: watching });
+});
+// `bivy ask`: the question card and "needs your input" push, for any agent.
+// Returns at once with an id; `/wait` blocks up to 240s per call (under common
+// HTTP client timeouts), so the CLI loops until the user answers.
+app.post("/api/session/:id/ask", (req, res) => {
+    const record = openSessions.get(String(req.params.id));
+    if (!record)
+        return res.status(404).json({ error: "Session not found" });
+    const questions = askQuestionsFrom(req.body?.questions);
+    if (typeof questions === "string")
+        return res.status(400).json({ error: questions });
+    const timeoutSeconds = Number(req.body?.timeoutSeconds);
+    res.status(201).json(agentQuestions.ask(record.id, questions, Number.isFinite(timeoutSeconds) && timeoutSeconds > 0 ? timeoutSeconds * 1000 : 10 * 60 * 1000));
+});
+app.get("/api/session/:id/ask/:askId", (req, res) => {
+    const result = agentQuestions.get(String(req.params.id), String(req.params.askId));
+    if (!result)
+        return res.status(404).json({ error: "Question not found" });
+    res.json(result);
+});
+app.post("/api/session/:id/ask/:askId/wait", async (req, res) => {
+    const seconds = Math.min(Math.max(Number(req.body?.timeoutSeconds) || 240, 1), 240);
+    const result = await agentQuestions.wait(String(req.params.id), String(req.params.askId), seconds * 1000);
+    if (!result)
+        return res.status(404).json({ error: "Question not found" });
+    res.json(result);
+});
 // `bivy suggest "<task>"`: the agent proposes a task the user can start in one
 // tap, here or in a parallel session (see packages/web SuggestionCard).
 app.post("/api/session/:id/suggest", (req, res) => {

package/dist/session/agent-context.js

@@ -3,6 +3,7 @@ export function buildAgentContext(input) {
     return {
         session: input.session,
         machine: input.machine,
+        userConnected: input.userConnected,
         ...(driver ? { lastDriver: { label: driver.label, via: driver.via, at: driver.at } } : {}),
         apps: input.apps.map((app) => ({
             id: app.id,

package/dist/session/agent-questions.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import { randomUUID } from "node:crypto";
+export const MAX_ASK_TIMEOUT_MS = 24 * 60 * 60 * 1000;
+const KEEP_SETTLED_MS = 24 * 60 * 60 * 1000;
+const KEEP_MAX = 200;
+/** Validates `bivy ask` input: 1–4 questions, each with text, a short header and
+ *  none (a free-text answer) or 2–8 options. Returns an error message, or the questions. */
+export function askQuestionsFrom(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 4)
+        return "Ask 1 to 4 questions.";
+    const out = [];
+    for (const raw of value) {
+        const question = typeof raw?.question === "string" ? raw.question.trim() : "";
+        if (!question || question.length > 1000)
+            return "Each question needs text (up to 1000 characters).";
+        const header = typeof raw.header === "string" && raw.header.trim() ? raw.header.trim().slice(0, 40) : "Question";
+        const options = Array.isArray(raw.options) ? raw.options : [];
+        if (options.length === 1 || options.length > 8)
+            return "Offer 2 to 8 options, or none for a free-text answer.";
+        const labels = options.map((o) => (typeof o === "string" ? o : o?.label)).map((l) => (typeof l === "string" ? l.trim() : ""));
+        if (labels.some((l) => !l || l.length > 200))
+            return "Each option needs a label (up to 200 characters).";
+        if (new Set(labels).size !== labels.length)
+            return "Options must be different.";
+        out.push({ question, header, options: labels.map((label) => ({ label })), ...(raw.multiSelect === true ? { multiSelect: true } : {}) });
+    }
+    if (new Set(out.map((q) => q.question)).size !== out.length)
+        return "Questions must be different.";
+    return out;
+}
+export class AgentQuestions {
+    questions;
+    now;
+    results = new Map();
+    waiters = new Map();
+    /** How each of our questions settled. QuestionManager reports it to onResolved
+     *  listeners synchronously, before the request's promise callbacks run. */
+    settled = new Map();
+    constructor(questions, now = Date.now) {
+        this.questions = questions;
+        this.now = now;
+        questions.onResolved((request) => { if (this.results.has(request.id))
+            this.settled.set(request.id, request.status); });
+    }
+    /** Raise the card and return at once; the answer lands in `get`/`wait`. */
+    ask(sessionId, items, timeoutMs) {
+        this.prune();
+        const id = randomUUID();
+        const result = { id, sessionId, status: "pending" };
+        this.results.set(id, result);
+        void this.questions.request({ id, sessionId, questions: items, timeoutMs: Math.min(Math.max(timeoutMs, 1000), MAX_ASK_TIMEOUT_MS) }).then((answer) => {
+            const status = this.settled.get(id);
+            this.settled.delete(id);
+            result.status = answer.behavior === "completed" ? "answered" : status === "expired" ? "expired" : "dismissed";
+            if (answer.behavior === "completed")
+                result.answers = answer.answers;
+            result.settledAt = this.now();
+            for (const wake of this.waiters.get(id) ?? [])
+                wake();
+            this.waiters.delete(id);
+        });
+        return this.view(result);
+    }
+    get(sessionId, id) {
+        const result = this.results.get(id);
+        return result && result.sessionId === sessionId ? this.view(result) : undefined;
+    }
+    /** Resolves when the question settles or after `ms`, whichever is first. */
+    async wait(sessionId, id, ms) {
+        const result = this.results.get(id);
+        if (!result || result.sessionId !== sessionId)
+            return undefined;
+        if (result.status === "pending") {
+            await new Promise((resolve) => {
+                const timer = setTimeout(done, ms);
+                function done() { clearTimeout(timer); resolve(); }
+                const set = this.waiters.get(id) ?? new Set();
+                set.add(done);
+                this.waiters.set(id, set);
+            });
+        }
+        return this.view(result);
+    }
+    view(result) {
+        return { id: result.id, sessionId: result.sessionId, status: result.status, ...(result.answers ? { answers: { ...result.answers } } : {}) };
+    }
+    prune() {
+        const cutoff = this.now() - KEEP_SETTLED_MS;
+        for (const [id, result] of this.results)
+            if (result.settledAt !== undefined && (result.settledAt < cutoff || this.results.size > KEEP_MAX))
+                this.results.delete(id);
+    }
+}

package/dist/session/event-log.js

@@ -32,6 +32,7 @@ import { normalizedIntermediateText, thinkingTextFromContent, mergeTranscript }
 import { DELEGATION_BLOCK, isDelegationCard } from "./delegations.js";
 import { APP_PIN_BLOCK, APP_PUBLICATION_BLOCK, APP_REVIEW_BLOCK, isAppPin, isAppReference, isAppReview } from "../apps/types.js";
 import { SUGGESTION_BLOCK, isTaskSuggestion } from "./suggestions.js";
+import { NOTICE_BLOCK, isAgentNotice } from "./notices.js";
 /**
  * Decompose a transcript message into serialization-independent "atoms": the
  * agent's own tool ids (unique + identical across serializations) and its text
@@ -255,6 +256,12 @@ function isSuggestionEntry(value) {
     const entry = value;
     return entry.bivyKind === "suggestion" && typeof entry.id === "string" && typeof entry.createdAt === "number" && typeof entry.afterMessageCount === "number" && isTaskSuggestion(entry.suggestion);
 }
+function isNoticeEntry(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const entry = value;
+    return entry.bivyKind === "notice" && typeof entry.id === "string" && typeof entry.createdAt === "number" && typeof entry.afterMessageCount === "number" && isAgentNotice(entry.notice);
+}
 function isDelegationEntry(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -274,7 +281,7 @@ function isAppPinEntry(value) {
     return entry.bivyKind === "app-pin" && typeof entry.id === "string" && typeof entry.createdAt === "number" && typeof entry.afterMessageCount === "number" && isAppPin(entry.pin);
 }
 function isRecord(value) {
-    return isDelegationEntry(value) || isOverlay(value) || isBase(value) || isForkDisplay(value) || isAttachment(value) || isOutboundAttachment(value) || isInlineImage(value) || isAppPublication(value) || isAppReviewEntry(value) || isAppPinEntry(value) || isSuggestionEntry(value);
+    return isDelegationEntry(value) || isOverlay(value) || isBase(value) || isForkDisplay(value) || isAttachment(value) || isOutboundAttachment(value) || isInlineImage(value) || isAppPublication(value) || isAppReviewEntry(value) || isAppPinEntry(value) || isSuggestionEntry(value) || isNoticeEntry(value);
 }
 /**
  * Fold attachment records into a text→refs list: last write wins per text (a
@@ -421,7 +428,11 @@ export function replayExtras(entries) {
         role: "assistant", content: [{ type: SUGGESTION_BLOCK, suggestion: entry.suggestion }],
         id: entry.id, afterMessageCount: entry.afterMessageCount, createdAt: entry.createdAt,
     }));
-    return [...foldIntermediate(intermediate), ...foldTool(tool), ...replayOutboundAttachments(entries), ...publications, ...cards, ...pinCards, ...delegationCards, ...suggestions];
+    const notices = entries.filter((entry) => entry.bivyKind === "notice").map((entry) => ({
+        role: "assistant", content: [{ type: NOTICE_BLOCK, notice: entry.notice }],
+        id: entry.id, afterMessageCount: entry.afterMessageCount, createdAt: entry.createdAt,
+    }));
+    return [...foldIntermediate(intermediate), ...foldTool(tool), ...replayOutboundAttachments(entries), ...publications, ...cards, ...pinCards, ...delegationCards, ...suggestions, ...notices];
 }
 /**
  * Fold the outbound (agent-sent) attachment records into time-anchored synthetic
@@ -742,6 +753,10 @@ export class EventLog {
         this.load(id);
         this.enqueue(id, `suggestion:${entry.suggestion.id}`, { bivyKind: "suggestion", createdAt: Date.now(), afterMessageCount: entry.afterMessageCount, id: entry.suggestion.id, suggestion: { ...entry.suggestion } });
     }
+    appendNotice(id, entry) {
+        this.load(id);
+        this.enqueue(id, `notice:${entry.notice.id}`, { bivyKind: "notice", createdAt: Date.now(), afterMessageCount: entry.afterMessageCount, id: entry.notice.id, notice: { ...entry.notice } });
+    }
     appendOutboundAttachment(id, entry) {
         this.load(id);
         const record = {

package/dist/session/notices.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+export const NOTICE_BLOCK = "bivy_notice";
+export const MAX_NOTICE_TEXT = 2000;
+/** At most one push per session in this window; later notices still post a card. */
+export const NOTICE_PUSH_GAP_MS = 60_000;
+/** Whether a notice also buzzes the user's devices. `pushConfigured` is false on
+ *  a node with no account connection, which has no way to push. */
+export function noticePush(input) {
+    if (input.pushConfigured === false)
+        return "unavailable";
+    if (input.lastPushAt !== undefined && input.now - input.lastPushAt < NOTICE_PUSH_GAP_MS)
+        return "rate_limited";
+    if (input.userWatching && !input.urgent)
+        return "user_watching";
+    return "sent";
+}
+export function isAgentNotice(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const n = value;
+    return typeof n.id === "string" && n.id.length > 0
+        && typeof n.text === "string" && n.text.length > 0 && n.text.length <= MAX_NOTICE_TEXT
+        && (n.urgent === undefined || typeof n.urgent === "boolean");
+}

package/package.json

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