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

package/bin/bivy.mjs

@@ -2521,18 +2521,18 @@ async function cmdContext(args = []) {
   console.log(`\nEverything else: ${c.cyan("bivy help")} (or ${c.cyan("bivy help --json")}).`);
 }
 
-// `bivy suggest "<task>" [--title "…"] [--session <id>]` — propose a task the
-// user can start in one tap, beside this session or in it. For an agent
+// `bivy suggest "<task>" [--title "…"] [--run here|subagents|new] [--session <id>]`
+// — propose a task the user can start in one tap, in this session or beside it. For an agent
 // offering next steps: write the task as a complete instruction.
 async function cmdSuggest(args = []) {
-  const usage = 'Usage: bivy suggest "<task>" [--title "short label"] [--session <id>] [--json]';
+  const usage = 'Usage: bivy suggest "<task>" [--title "short label"] [--run here|subagents|new] [--session <id>] [--json]';
   if (args.includes("-h") || args.includes("--help")) {
-    console.log(`${usage}\n\nPost a task the user can start in one tap, in this session or in a parallel one that works in its own copy of the project. Write it as a complete instruction, with paths relative to the project root. --json prints {"ok","id"}.`);
+    console.log(`${usage}\n\nPost a task the user can start in one tap: in this session, through your sub-agents, or in a parallel session that works in its own copy of the project. Write it as a complete instruction, with paths relative to the project root.\n\n--run says where you recommend running it, which becomes the card's main button: here (builds on this conversation), subagents (independent tasks you can split across your own sub-agents; only if you have them), or new (bigger independent work the user will want to follow in its own session). Without it, one card recommends here and several recommend new.\n\n--json prints {"ok","id"}.`);
     return;
   }
   const json = wantsJson(args);
   const fail = (error) => cliError(error, { json, paint: c.red });
-  const flagsWithValue = new Set(["--session", "--title"]);
+  const flagsWithValue = new Set(["--session", "--title", "--run"]);
   const flag = (name) => {
     const i = args.indexOf(name);
     return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
@@ -2540,10 +2540,12 @@ async function cmdSuggest(args = []) {
   const text = args.filter((a, i) => !a.startsWith("-") && !(i > 0 && flagsWithValue.has(args[i - 1]))).join(" ").trim();
   const sessionId = resolveAttachSessionId({ sessionFlag: flag("--session"), env: process.env });
   if (!text) return fail({ code: "usage", message: usage, exit: EXIT.usage });
+  const run = flag("--run");
+  if (run !== undefined && !["here", "subagents", "new"].includes(run)) return fail({ code: "usage", message: `--run is here, subagents or new (got "${run}").`, exit: EXIT.usage });
   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, "suggest", { text, title: flag("--title") }).catch((error) => error);
+  const res = await sessionPost(config, sessionId, "suggest", { text, title: flag("--title"), run }).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("Suggest", res.status, body));

package/bin/cli-commands.mjs

@@ -48,8 +48,8 @@ export const COMMANDS = [
     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: "suggest", group: "session", scope: "session", json: true, usage: 'suggest "<task>" [--title "label"] [--run here|subagents|new]', 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, through your sub-agents, or in a parallel session 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." }, run: { type: "string", enum: ["here", "subagents", "new"], description: "Where you recommend running it: here (builds on this conversation), subagents (independent tasks you can split across your own sub-agents; only if you have them), or new (bigger independent work in its own session). Defaults: here for one card, new for several." } }, argv: ["suggest", { arg: "task" }, { flag: "--title", from: "title" }, { flag: "--run", from: "run" }] }] },
   { 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" }] },

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

@@ -28,9 +28,18 @@ Ask only when you can't reasonably decide yourself.
 
     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.
+Each suggestion is a card the user can start in one tap: here, through your
+sub-agents, 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.
+
+`--run` picks the card's main button; the others stay one tap away:
+
+| `--run` | When |
+|---|---|
+| `here` | It builds on this conversation, or it's small. Default for a single card. |
+| `subagents` | Independent tasks you can split across your own sub-agents and report back on. Only if you have sub-agents. |
+| `new` | Bigger independent work the user will want to follow, review or merge on its own. Default for several cards. |
 
 ## Is anyone there?
 

package/dist/agent-instructions.js

@@ -39,9 +39,12 @@ export const BIVY_AGENT_NOTE = [
         "can check your work; `bivy app present` tells the user a visible change is ready to look at. " +
         "`bivy app --help` has the details.",
     "- Proposing tasks the user could hand you (next steps, ideas, options): post each with " +
-        '`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.",
+        '`bivy suggest "<complete instruction>" [--title "short label"] [--run here|subagents|new]` instead of only ' +
+        "listing them. The user can start each in one tap, in this session, through your sub-agents, 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. `--run` is the one you recommend: here when it builds on this conversation, subagents for " +
+        "independent tasks you can split and supervise (only if you have sub-agents), new for bigger work worth its " +
+        "own session.",
     "- 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).',

package/dist/apps/styles.css

@@ -3127,8 +3127,14 @@ p.setup-note .btn.link { min-height: 44px; margin-block: calc((1lh - 44px) / 2);
 .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-actions { display: flex; flex-wrap: wrap; gap: var(--space-2); margin-top: var(--space-2); }
+.suggestion-bar, .suggestion-all { display: flex; flex-direction: column; gap: var(--space-1); margin-top: var(--space-2); }
 .suggestion-all { padding-top: var(--space-2); border-top: 1px solid var(--line); }
+.suggestion-bar .suggestion-actions, .suggestion-all .suggestion-actions { margin-top: 0; }
+.suggestion-hint { margin: 0; color: var(--muted); font-size: var(--text-xs); }
+/* In a set, the title is the checkbox's label, so the whole line is the tap target. */
+.suggestion-pick { display: flex; align-items: flex-start; gap: var(--space-2); cursor: pointer; }
+.suggestion-pick input { flex: none; inline-size: 18px; block-size: 18px; margin: 2px 0 0; accent-color: var(--accent); }
 .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. */

package/dist/server.js

@@ -74,7 +74,7 @@ import { exportProviderAuth, exportAccountApiKeys, exportAccountOAuthCredentials
 import { listProviders } from "./runtime/provider-catalog.js";
 import { exportLocalModels, importLocalModels } from "./runtime/local-model-store.js";
 import { sessionLikeFields } from "./session/start-like.js";
-import { MAX_SUGGESTION_TEXT, MAX_SUGGESTION_TITLE, isTaskSuggestion } from "./session/suggestions.js";
+import { MAX_SUGGESTION_TEXT, MAX_SUGGESTION_TITLE, SUGGESTION_RUNS, isTaskSuggestion } from "./session/suggestions.js";
 import { BIVY_AGENT_NOTE, mergeSyncedAgentInstructions, readAgentInstructions, sessionInstructions, writeAgentInstructions, MAX_AGENT_INSTRUCTIONS_BYTES } from "./agent-instructions.js";
 import { execEphemeralRequest } from "./ephemeral-exec.js";
 import { ApprovalManager } from "./approval.js";
@@ -11666,16 +11666,18 @@ app.get("/api/session/:id/automations/apply/:proposalId", (req, res) => {
     res.json(proposal);
 });
 // `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).
+// tap, here, through this agent's sub-agents, or in a parallel session; `run`
+// is the one the agent recommends (see packages/web SuggestionCard).
 app.post("/api/session/:id/suggest", (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 title = typeof req.body?.title === "string" && req.body.title.trim() ? req.body.title.trim() : undefined;
-    const suggestion = { id: `suggestion-${randomBytes(8).toString("hex")}`, text, ...(title ? { title } : {}) };
+    const run = req.body?.run || undefined;
+    const suggestion = { id: `suggestion-${randomBytes(8).toString("hex")}`, text, ...(title ? { title } : {}), ...(run ? { run } : {}) };
     if (!isTaskSuggestion(suggestion))
-        return res.status(400).json({ error: `A suggestion needs text (up to ${MAX_SUGGESTION_TEXT} characters) and an optional title (up to ${MAX_SUGGESTION_TITLE}).` });
+        return res.status(400).json({ error: `A suggestion needs text (up to ${MAX_SUGGESTION_TEXT} characters), an optional title (up to ${MAX_SUGGESTION_TITLE}) and an optional run (${SUGGESTION_RUNS.join(", ")}).` });
     eventLog.appendSuggestion(record.id, { afterMessageCount: record.session.getMessages().length, suggestion });
     broadcast(stampSessionEvent({ type: "session.event", sessionId: record.id, event: { type: "suggestion", id: suggestion.id, suggestion } }));
     res.json({ ok: true, id: suggestion.id });

package/dist/session/suggestions.js

@@ -1,5 +1,8 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright (c) 2026 Petter André Sjulstad
+/** here: this session's agent. subagents: this agent, through its own sub-agents. new: a session per task. */
+export const SUGGESTION_RUNS = ["here", "subagents", "new"];
+const isRun = (value) => value === undefined || SUGGESTION_RUNS.includes(value);
 export const SUGGESTION_BLOCK = "bivy_suggestion";
 export const MAX_SUGGESTION_TEXT = 4000;
 export const MAX_SUGGESTION_TITLE = 120;
@@ -9,5 +12,6 @@ export function isTaskSuggestion(value) {
     const s = value;
     return typeof s.id === "string" && s.id.length > 0
         && typeof s.text === "string" && s.text.length > 0 && s.text.length <= MAX_SUGGESTION_TEXT
-        && (s.title === undefined || (typeof s.title === "string" && s.title.length <= MAX_SUGGESTION_TITLE));
+        && (s.title === undefined || (typeof s.title === "string" && s.title.length <= MAX_SUGGESTION_TITLE))
+        && isRun(s.run);
 }

package/package.json

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