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

package/dist/server.js

@@ -126,6 +126,9 @@ import { createSessionControlCommands } from "./controllers/session-control.js";
 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";
@@ -397,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 });
@@ -11505,6 +11509,86 @@ app.post("/api/session/:id/attach", (req, res) => {
     const { hash, name, mimeType, size, kind } = result.ref;
     res.json({ ok: true, hash, name, mimeType, size, kind });
 });
+// `bivy context`: what an agent in this session needs to orient itself.
+app.get("/api/session/:id/context", (req, res) => {
+    const record = openSessions.get(String(req.params.id));
+    if (!record)
+        return res.status(404).json({ error: "Session not found" });
+    const { apps, previewAvailable } = appService.list(record.id);
+    res.json(buildAgentContext({
+        session: {
+            id: record.id,
+            name: record.session.getName() || undefined,
+            agent: record.runtimeId,
+            agentName: getRuntime(record.runtimeId).displayName,
+            workspace: harnessDirFor(record),
+            branch: record.worktree?.branch,
+            prUrl: record.prUrl,
+            forkedFrom: record.forkedFrom,
+            delegatedFrom: record.delegatedFrom?.sessionId,
+            busy: sessionBusy(record),
+        },
+        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

@@ -0,0 +1,15 @@
+export function buildAgentContext(input) {
+    const driver = input.presence.driver;
+    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,
+            name: app.name,
+            views: app.views.map((view) => ({ id: view.id, name: view.name, kind: view.kind })),
+        })),
+        previewAvailable: input.previewAvailable,
+    };
+}

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.2",
+  "version": "0.19.4-staging.4",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",