@bivy/bivy 0.10.1-staging.299 → 0.10.1-staging.301

package/README.md

@@ -1,28 +1,59 @@
 # Bivy
 
-**Run agents where your environment lives. Reach, automate, and govern them from
-anywhere.**
-
-Bivy makes coding agents on your infrastructure available from anywhere. Use
-Claude Code or Codex with the repositories, tools, services, and compute already
-in your development environment; continue the same Session from a phone, leave
-work running, and return to checked changes or a pull request with a clear
-Receipt.
+**Give coding agents your real environment, then reach them from anywhere.**
+
+A provider sandbox starts from an approximation. A Bivy Machine can use the
+repository, local services and databases, private networks, existing tools and
+caches, and GPUs or local inference already available on your workstation or
+server. Bivy turns that local capability into Sessions you can continue remotely
+and Runs you can leave working unattended.
+
+## What Bivy lets you do
+
+- **Work where the full environment lives.** Run Claude Code, Codex, Pi, or
+  another agent beside real repos, dev servers, databases, internal APIs,
+  toolchains, package caches, and specialized compute.
+- **Continue from a phone, browser, or terminal.** Reconnect to the same Session,
+  steer or stop it, answer questions, and approve supported tool calls. The PWA
+  supports voice input and read-aloud, phone-to-agent file/image uploads, and
+  agent-to-phone attachments. Native terminal Sessions can stay remote-visible;
+  supported runtimes can hand work between terminal and structured chat.
+- **Move work without starting over.** Import existing Claude Code and Codex
+  Sessions, or fork/copy/move a Bivy Session to another agent, model, or Machine.
+  Fidelity is runtime-dependent: a fork may use a native transcript, replayed
+  history, or a bounded seeded continuation, and cross-Machine moves require the
+  destination's repo access, agent, and credentials.
+- **Operate more than one Machine.** Keep a workstation, private-network server,
+  and GPU box on one account; select the environment a Session or Run needs.
+  Optional warm Session replication is Beta, off by default, and manually
+  promoted rather than automatic failover.
+- **Let events start checked work.** Create Runs manually or from failed CI,
+  GitHub/Linear issues, Slack, schedules, and signed webhooks. Automations can
+  pin a Machine, agent, model, sandbox, approval mode, and attempt ceiling, then
+  report bounded check and outcome evidence in a Receipt.
+- **Bring your own stack.** Use provider subscriptions through supported native
+  agent logins, API keys in Bivy's vault, or local/OpenAI-compatible inference.
+  Add an existing ACP or headless process agent with `bivy agent add`; declarative
+  agent plugins are Experimental (`v1alpha1`) and run out of process.
+
+Start with the [five-minute quickstart](docs/quickstart.md), then try the
+[capability recipes](docs/capability-recipes.md) or check the exact
+[runtime support matrix](docs/runtime-support-matrix.md).
 
 Interactive Session traffic is end-to-end encrypted between a Machine and its
-paired devices. The relay cannot decrypt it. Explicitly enabled hosted
-provisioning has a different boundary: the control plane may hold encrypted
-cloud, repository, or key-escrow material that the service can technically
-access. Slack and generic webhook instructions also reach the control plane in
-plaintext. See [Why Bivy](docs/why-bivy.md) and the
-[security model](docs/security-model.md) for the complete trust model.
+paired devices, so the relay cannot decrypt it. The seatbelt has a precise edge:
+explicitly enabled hosted provisioning may give the control plane technical
+access to encrypted cloud, repository, or key-escrow material, while Slack and
+generic webhook instructions reach it in plaintext. See [Why Bivy](docs/why-bivy.md)
+and the [security model](docs/security-model.md) for the complete trust model.
 
 - **Website:** [bivy.sh](https://bivy.sh)
-- **Documentation:** [`docs/`](docs/README.md) — start with the [quickstart](docs/quickstart.md)
+- **Documentation:** [`docs/`](docs/README.md)
 - **License:** [AGPL-3.0-only](LICENSE)
 
-> Bivy is 0.x software. The core loop is solid and used daily, but interfaces
-> and behaviour can change between releases.
+> Bivy is 0.x software. The core loop is solid and used daily, but interfaces,
+> cross-runtime fidelity, and behaviour can change between releases. Check the
+> support matrix before depending on a particular agent capability.
 
 ## Install
 

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

@@ -136,6 +136,36 @@ function buildAttachMcpServer(sdk, sessionId, attachToChat) {
     });
     return sdk.createSdkMcpServer({ name: BIVY_ATTACH_MCP_SERVER_NAME, tools: [attachTool] });
 }
+/** Adapt Bivy's runtime-agnostic ToolProvider to Claude SDK's in-process MCP
+ * builder. Credentials and execution remain on the daemon. */
+function buildToolProviderMcpServer(sdk, provider) {
+    if (typeof sdk?.tool !== "function" || typeof sdk?.createSdkMcpServer !== "function")
+        return undefined;
+    const toShape = (schema) => {
+        const object = schema && typeof schema === "object" ? schema : {};
+        const properties = object.properties && typeof object.properties === "object" ? object.properties : {};
+        const required = new Set(Array.isArray(object.required) ? object.required.filter((v) => typeof v === "string") : []);
+        const shape = {};
+        for (const [name, raw] of Object.entries(properties)) {
+            const field = raw && typeof raw === "object" ? raw : {};
+            let value = field.type === "string" ? z.string()
+                : field.type === "integer" ? z.number().int()
+                    : field.type === "number" ? z.number()
+                        : field.type === "boolean" ? z.boolean()
+                            : field.type === "object" ? z.object(toShape(field)).passthrough()
+                                : z.unknown();
+            if (Array.isArray(field.enum) && field.enum.every((v) => typeof v === "string") && field.enum.length > 0)
+                value = z.enum(field.enum);
+            shape[name] = required.has(name) ? value : value.optional();
+        }
+        return shape;
+    };
+    const tools = provider.list().map((spec) => sdk.tool(spec.name, spec.description, toShape(spec.parameters), async (args) => {
+        const result = await provider.invoke(spec.name, `claude-${randomUUID()}`, args);
+        return { content: result.content, ...(result.isError ? { isError: true } : {}) };
+    }));
+    return sdk.createSdkMcpServer({ name: BIVY_ATTACH_MCP_SERVER_NAME, tools });
+}
 export function claudeRuntimeFromEnv() {
     return {
         defaultModel: process.env.BIVY_CLAUDE_MODEL?.trim() || undefined,
@@ -632,6 +662,7 @@ class ClaudeSession {
     runtimeOptions;
     cwd;
     toolInterceptor;
+    toolProvider;
     query;
     // Re-created on every spawnQuery: the previous SDK query owns the old queue, so
     // a re-spawn (credential reload) must not share it. Not readonly for that reason.
@@ -687,10 +718,11 @@ class ClaudeSession {
      *  init arrives; getCommands() exposes them and a `runtime.commands` event lets
      *  the daemon re-advertise once they're known. */
     commands = [];
-    constructor(runtimeOptions, cwd, toolInterceptor, resumeId) {
+    constructor(runtimeOptions, cwd, toolInterceptor, toolProvider, resumeId) {
         this.runtimeOptions = runtimeOptions;
         this.cwd = cwd;
         this.toolInterceptor = toolInterceptor;
+        this.toolProvider = toolProvider;
         this.resumeId = resumeId;
         this.id = resumeId ?? randomUUID();
         this.desiredModel = runtimeOptions.defaultModel;
@@ -827,11 +859,13 @@ class ClaudeSession {
         // callback (see ClaudeCodeRuntimeOptions.attachToChat); absent in a few
         // deliberately minimal test harnesses, and gracefully degrades to the prompt
         // hint alone if this SDK build lacks the MCP builder helpers.
-        if (this.runtimeOptions.attachToChat) {
-            const attachServer = buildAttachMcpServer(sdk, this.id, this.runtimeOptions.attachToChat);
-            if (attachServer)
-                options.mcpServers = { [BIVY_ATTACH_MCP_SERVER_NAME]: attachServer };
-        }
+        const bivyServer = this.toolProvider
+            ? buildToolProviderMcpServer(sdk, this.toolProvider)
+            : this.runtimeOptions.attachToChat
+                ? buildAttachMcpServer(sdk, this.id, this.runtimeOptions.attachToChat)
+                : undefined;
+        if (bivyServer)
+            options.mcpServers = { [BIVY_ATTACH_MCP_SERVER_NAME]: bivyServer };
         const q = sdk.query({ prompt: this.input, options });
         this.query = q;
         void this.consume(q);
@@ -1369,12 +1403,12 @@ export class ClaudeCodeRuntime {
         return [{ id: "anthropic", name: "Anthropic", oauth: true, models: FALLBACK_MODELS }];
     }
     async createSession(options) {
-        const session = new ClaudeSession(this.options, options.workspace, options.toolInterceptor);
+        const session = new ClaudeSession(this.options, options.workspace, options.toolInterceptor, options.toolProvider);
         this.sessions.push(session);
         return { session };
     }
     async openSession(options) {
-        const session = new ClaudeSession(this.options, options.workspace, options.toolInterceptor, options.sessionFile);
+        const session = new ClaudeSession(this.options, options.workspace, options.toolInterceptor, options.toolProvider, options.sessionFile);
         this.sessions.push(session);
         return {
             session,

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

@@ -44,6 +44,21 @@ export const BIVY_MCP_TOOLS = [
             additionalProperties: false,
         },
     },
+    {
+        name: "start_run",
+        description: "Delegate one bounded task to another governed Bivy Run or Machine. Returns lifecycle and safe references only, never the child transcript, raw tool output, secrets, or file contents.",
+        inputSchema: { type: "object", properties: { instructions: { type: "string", maxLength: 16000 }, repo: { type: "string" }, machine: { type: "string" }, agent: { type: "string" }, model: { type: "string" }, safety: { type: "object", properties: { approval: { type: "string", enum: ["never", "risky", "always", "autonomous"] }, sandbox: { type: "string", enum: ["read-only", "workspace-write", "danger-full-access"] }, maxAttempts: { type: "integer", minimum: 1, maximum: 10 } }, additionalProperties: false }, idempotencyKey: { type: "string", maxLength: 128 } }, required: ["instructions"], additionalProperties: false },
+    },
+    {
+        name: "get_run_status",
+        description: "Inspect a child Run started by this Session. Returns bounded lifecycle, check states, and safe output references only.",
+        inputSchema: { type: "object", properties: { runId: { type: "string" } }, required: ["runId"], additionalProperties: false },
+    },
+    {
+        name: "wait_for_run",
+        description: "Wait up to 300 seconds for a child Run. A wait timeout is reported honestly and does not cancel the child.",
+        inputSchema: { type: "object", properties: { runId: { type: "string" }, timeoutSeconds: { type: "number", minimum: 1, maximum: 300 } }, required: ["runId", "timeoutSeconds"], additionalProperties: false },
+    },
 ];
 /**
  * Perform an `attach_to_chat` call by POSTing to the node's attach endpoint,
@@ -80,6 +95,25 @@ export async function runAttachToChat(endpoint, sessionId, args, fetchImpl, toke
     const name = body?.name || filePath;
     return { isError: false, text: `Attached ${name} to the chat as ${body?.kind === "image" ? "an inline image" : "a downloadable file"}. The user can see it now.` };
 }
+export async function runBivyRunTool(endpoint, sessionId, name, args, fetchImpl, token) {
+    if (!sessionId)
+        return { isError: true, text: "No active Bivy Session (BIVY_SESSION_ID is not set)." };
+    const suffix = name === "start_run" ? "delegated-runs" : name === "get_run_status" ? `delegated-runs/${encodeURIComponent(String(args.runId ?? ""))}` : `delegated-runs/${encodeURIComponent(String(args.runId ?? ""))}/wait`;
+    const headers = { "content-type": "application/json" };
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    try {
+        const method = name === "get_run_status" ? "GET" : "POST";
+        const res = await fetchImpl(`${endpoint.replace(/\/+$/, "")}/api/session/${encodeURIComponent(sessionId)}/${suffix}`, { method, headers, ...(method === "POST" ? { body: JSON.stringify(args) } : {}) });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok)
+            return { isError: true, text: typeof body.error === "string" ? body.error : `Bivy node returned ${res.status}` };
+        return { isError: false, text: JSON.stringify(body) };
+    }
+    catch (error) {
+        return { isError: true, text: `Could not reach the Bivy node: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
 /** Build the Bivy MCP `Server` with tools/list + tools/call handlers wired. */
 export function createBivyMcpServer(deps = {}) {
     const endpoint = deps.endpoint ?? process.env.BIVY_MCP_ENDPOINT ?? DEFAULT_ENDPOINT;
@@ -89,10 +123,12 @@ export function createBivyMcpServer(deps = {}) {
     const server = new Server({ name: "bivy", version: "1.0.0" }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: BIVY_MCP_TOOLS }));
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
-        if (req.params.name !== "attach_to_chat") {
-            return { isError: true, content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }] };
-        }
-        const result = await runAttachToChat(endpoint, sessionId, (req.params.arguments ?? {}), fetchImpl, token);
+        const args = (req.params.arguments ?? {});
+        const result = req.params.name === "attach_to_chat"
+            ? await runAttachToChat(endpoint, sessionId, args, fetchImpl, token)
+            : ["start_run", "get_run_status", "wait_for_run"].includes(req.params.name)
+                ? await runBivyRunTool(endpoint, sessionId, req.params.name, args, fetchImpl, token)
+                : { isError: true, text: `Unknown tool: ${req.params.name}` };
         return { isError: result.isError, content: [{ type: "text", text: result.text }] };
     });
     return server;

package/dist/integrations/manager.js

@@ -26,12 +26,16 @@ export class IntegrationManager {
     /** Backs the native `attach_to_chat` tool (see toolProvider); undefined = the
      *  tool isn't offered (e.g. a test harness that never wired one). */
     attachToChat;
-    constructor(appDir, registry = BUILT_IN_INTEGRATIONS, attachToChat) {
+    /** Additional Bivy-owned tools (for example governed child Runs), bound to
+     * the same lazy Session id as attach_to_chat. */
+    builtInToolProvider;
+    constructor(appDir, registry = BUILT_IN_INTEGRATIONS, attachToChat, builtInToolProvider) {
         this.store = new IntegrationStore(appDir);
         this.secrets = new SecretVault(appDir);
         this.registry = registry;
         this.riskyTools = new Set(registry.flatMap((d) => d.tools.filter((t) => t.risky).map((t) => t.name)));
         this.attachToChat = attachToChat;
+        this.builtInToolProvider = builtInToolProvider;
     }
     // --- helpers ------------------------------------------------------------
     def(id) {
@@ -280,6 +284,13 @@ export class IntegrationManager {
                 });
             }
         }
+        if (this.builtInToolProvider && sessionIdRef) {
+            const provider = this.builtInToolProvider(sessionIdRef);
+            for (const spec of provider.list()) {
+                specs.push(spec);
+                executors.set(spec.name, (params, signal) => provider.invoke(spec.name, `bivy-${randomUUID()}`, params, signal));
+            }
+        }
         if (this.attachToChat && sessionIdRef) {
             const attachToChat = this.attachToChat;
             specs.push({

package/dist/run-tools.js

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import { createHash } from "node:crypto";
+export const RUN_TOOL_LIMITS = {
+    maxInstructions: 16_000,
+    maxDepth: 3,
+    maxConcurrentChildren: 3,
+    maxWaitSeconds: 300,
+    minPollMs: 1_000,
+    maxIdempotencyKey: 128,
+};
+const TERMINAL = new Set(["succeeded", "failed", "cancelled"]);
+const STATUSES = new Set(["pending", "claimed", "running", "waiting", "needs_attention", "succeeded", "failed", "cancelled"]);
+const SOURCE_PREFIX = "agent-delegation:v1:";
+const bounded = (v, n) => typeof v === "string" && v ? v.slice(0, n) : undefined;
+function idempotencyDigest(key) { return key ? createHash("sha256").update(key).digest("base64url").slice(0, 22) : undefined; }
+export function delegationSource(parentSessionId, parentRunId, depth, idempotencyKey) {
+    const digest = idempotencyDigest(idempotencyKey);
+    return `${SOURCE_PREFIX}${depth}:${Buffer.from(parentSessionId).toString("base64url")}:${parentRunId ? Buffer.from(parentRunId).toString("base64url") : "-"}${digest ? `:${digest}` : ""}`;
+}
+export function parseDelegationSource(source) {
+    if (typeof source !== "string" || !source.startsWith(SOURCE_PREFIX))
+        return undefined;
+    const [depthRaw, sessionRaw, runRaw] = source.slice(SOURCE_PREFIX.length).split(":");
+    const depth = Number(depthRaw);
+    if (!Number.isInteger(depth) || depth < 1 || depth > RUN_TOOL_LIMITS.maxDepth || !sessionRaw)
+        return undefined;
+    try {
+        const parentSessionId = Buffer.from(sessionRaw, "base64url").toString("utf8");
+        const parentRunId = runRaw && runRaw !== "-" ? Buffer.from(runRaw, "base64url").toString("utf8") : undefined;
+        if (!parentSessionId || parentSessionId.length > 256 || (parentRunId?.length ?? 0) > 256)
+            return undefined;
+        return { parentSessionId, ...(parentRunId ? { parentRunId } : {}), depth };
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeRun(raw, provenance) {
+    const status = STATUSES.has(raw.status) ? raw.status : "pending";
+    const output = raw.output && typeof raw.output === "object" ? raw.output : {};
+    const references = {
+        sessionId: bounded(output.sessionId, 256), branch: bounded(output.branch, 256),
+        prUrl: bounded(output.prUrl, 1_024), artifactUrl: bounded(output.artifactUrl, 1_024), failure: bounded(output.failure, 500),
+    };
+    const checks = Array.isArray(raw.checks) ? raw.checks.slice(0, 50).flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const c = item;
+        const name = bounded(c.name, 120);
+        const state = bounded(c.status, 40);
+        return name && state ? [{ name, status: state, ...(Number.isInteger(c.exitCode) ? { exitCode: Number(c.exitCode) } : {}) }] : [];
+    }) : undefined;
+    return {
+        runId: bounded(raw.id, 256) ?? "unknown", status,
+        createdAt: bounded(raw.createdAt, 64), startedAt: bounded(raw.startedAt, 64), completedAt: bounded(raw.completedAt, 64),
+        attempt: Number.isInteger(raw.attempt) ? Number(raw.attempt) : undefined,
+        maxAttempts: Number.isInteger(raw.maxAttempts) ? Number(raw.maxAttempts) : undefined,
+        provenance,
+        ...(Object.values(references).some(Boolean) ? { references } : {}),
+        ...(checks?.length ? { checks } : {}),
+    };
+}
+function validateStart(input) {
+    if (!input || typeof input !== "object")
+        throw new Error("input is required");
+    if (typeof input.instructions !== "string" || !input.instructions.trim())
+        throw new Error("instructions are required");
+    if (input.instructions.length > RUN_TOOL_LIMITS.maxInstructions)
+        throw new Error(`instructions must be at most ${RUN_TOOL_LIMITS.maxInstructions} characters`);
+    for (const [key, value, max] of [["repo", input.repo, 200], ["machine", input.machine, 120], ["agent", input.agent, 120], ["model", input.model, 200], ["idempotencyKey", input.idempotencyKey, RUN_TOOL_LIMITS.maxIdempotencyKey]]) {
+        if (value !== undefined && (typeof value !== "string" || !value.trim() || value.length > max))
+            throw new Error(`${key} must be a non-empty string of at most ${max} characters`);
+    }
+    if (input.safety?.maxAttempts !== undefined && (!Number.isInteger(input.safety.maxAttempts) || input.safety.maxAttempts < 1 || input.safety.maxAttempts > 10))
+        throw new Error("safety.maxAttempts must be an integer from 1 to 10");
+}
+export class RunDelegationService {
+    backend;
+    now;
+    sleep;
+    cache = new Map();
+    startLocks = new Map();
+    constructor(backend, now = () => Date.now(), sleep = (ms, signal) => new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => { clearTimeout(timer); reject(signal.reason ?? new Error("wait cancelled; the child Run may still be running")); }, { once: true });
+    })) {
+        this.backend = backend;
+        this.now = now;
+        this.sleep = sleep;
+    }
+    context(sessionId) {
+        const parent = this.backend.parentContext(sessionId);
+        if (!parent)
+            throw new Error("calling Session is not available");
+        const depth = (parent.depth ?? 0) + 1;
+        if (depth > RUN_TOOL_LIMITS.maxDepth)
+            throw new Error(`delegation depth limit (${RUN_TOOL_LIMITS.maxDepth}) reached`);
+        return { parentSessionId: sessionId, ...(parent.parentRunId ? { parentRunId: parent.parentRunId } : {}), depth };
+    }
+    async authorized(sessionId, runId, force = false) {
+        const cached = this.cache.get(`${sessionId}:${runId}`);
+        if (!force && cached && this.now() - cached.at < RUN_TOOL_LIMITS.minPollMs)
+            return cached.value;
+        const raw = await this.backend.get(runId);
+        const provenance = raw ? parseDelegationSource(raw.source) : undefined;
+        if (!raw || provenance?.parentSessionId !== sessionId)
+            throw new Error("delegated Run not found");
+        const value = safeRun(raw, provenance);
+        this.cache.set(`${sessionId}:${runId}`, { at: this.now(), value });
+        return value;
+    }
+    async startRun(sessionId, input) {
+        validateStart(input);
+        const previous = this.startLocks.get(sessionId) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => { release = resolve; });
+        this.startLocks.set(sessionId, current);
+        await previous;
+        try {
+            const provenance = this.context(sessionId);
+            const recent = await this.backend.listRecent();
+            const expectedSource = input.idempotencyKey ? delegationSource(sessionId, provenance.parentRunId, provenance.depth, input.idempotencyKey) : undefined;
+            const existing = expectedSource ? recent.find((r) => r.source === expectedSource) : undefined;
+            if (existing)
+                return safeRun(existing, provenance);
+            const active = recent.filter((r) => parseDelegationSource(r.source)?.parentSessionId === sessionId && !TERMINAL.has(r.status)).length;
+            if (active >= RUN_TOOL_LIMITS.maxConcurrentChildren)
+                throw new Error(`concurrent child Run limit (${RUN_TOOL_LIMITS.maxConcurrentChildren}) reached`);
+            const raw = await this.backend.start(sessionId, input, provenance);
+            const value = safeRun(raw, provenance);
+            this.cache.set(`${sessionId}:${value.runId}`, { at: this.now(), value });
+            return value;
+        }
+        finally {
+            release();
+            if (this.startLocks.get(sessionId) === current)
+                this.startLocks.delete(sessionId);
+        }
+    }
+    getRunStatus(sessionId, runId) { return this.authorized(sessionId, runId); }
+    async waitForRun(sessionId, runId, timeoutSeconds, signal) {
+        if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > RUN_TOOL_LIMITS.maxWaitSeconds)
+            throw new Error(`timeoutSeconds must be from 1 to ${RUN_TOOL_LIMITS.maxWaitSeconds}`);
+        const deadline = this.now() + timeoutSeconds * 1_000;
+        while (true) {
+            if (signal?.aborted)
+                throw signal.reason ?? new Error("wait cancelled; the child Run may still be running");
+            const result = await this.authorized(sessionId, runId, true);
+            if (TERMINAL.has(result.status))
+                return result;
+            if (this.now() >= deadline)
+                return { ...result, timedOut: true, wait: { timedOut: true, childContinues: true } };
+            await this.sleep(Math.min(RUN_TOOL_LIMITS.minPollMs, Math.max(1, deadline - this.now())), signal);
+        }
+    }
+}
+const START_SPEC = { name: "start_run", label: "Delegate Run", description: "Delegate one bounded task to another governed Bivy Run or Machine. Returns references only; never the child transcript or file contents.", promptSnippet: "Use start_run for a focused independent review, test, GPU, or implementation task; then use wait_for_run or get_run_status.", parameters: { type: "object", properties: { instructions: { type: "string", maxLength: RUN_TOOL_LIMITS.maxInstructions }, repo: { type: "string" }, machine: { type: "string" }, agent: { type: "string" }, model: { type: "string" }, safety: { type: "object", properties: { approval: { type: "string", enum: ["never", "risky", "always", "autonomous"] }, sandbox: { type: "string", enum: ["read-only", "workspace-write", "danger-full-access"] }, maxAttempts: { type: "integer", minimum: 1, maximum: 10 } }, additionalProperties: false }, idempotencyKey: { type: "string", maxLength: RUN_TOOL_LIMITS.maxIdempotencyKey } }, required: ["instructions"], additionalProperties: false } };
+const STATUS_SPEC = { name: "get_run_status", label: "Inspect delegated Run", description: "Inspect a child Run started by this Session. Returns bounded lifecycle, check states, and safe references only.", parameters: { type: "object", properties: { runId: { type: "string" } }, required: ["runId"], additionalProperties: false } };
+const WAIT_SPEC = { name: "wait_for_run", label: "Wait for delegated Run", description: `Wait for a child Run for at most ${RUN_TOOL_LIMITS.maxWaitSeconds} seconds. A wait timeout does not cancel the child.`, parameters: { type: "object", properties: { runId: { type: "string" }, timeoutSeconds: { type: "number", minimum: 1, maximum: RUN_TOOL_LIMITS.maxWaitSeconds } }, required: ["runId", "timeoutSeconds"], additionalProperties: false } };
+export const RUN_TOOL_SPECS = [START_SPEC, STATUS_SPEC, WAIT_SPEC];
+export function runToolProvider(service, sessionId) {
+    const text = (value, field) => { if (typeof value !== "string" || !value.trim())
+        throw new Error(`${field} is required`); return value.trim(); };
+    return { list: () => [...RUN_TOOL_SPECS], invoke: async (name, _id, params, signal) => {
+            try {
+                const sid = sessionId();
+                if (!sid)
+                    throw new Error("Session is not ready yet — try again in a moment");
+                const p = (params ?? {});
+                const result = name === "start_run" ? await service.startRun(sid, p)
+                    : name === "get_run_status" ? await service.getRunStatus(sid, text(p.runId, "runId"))
+                        : name === "wait_for_run" ? await service.waitForRun(sid, text(p.runId, "runId"), Number(p.timeoutSeconds), signal)
+                            : (() => { throw new Error(`Unknown Bivy Run tool: ${name}`); })();
+                return { content: [{ type: "text", text: JSON.stringify(result) }], details: { run: result } };
+            }
+            catch (error) {
+                return { content: [{ type: "text", text: (error instanceof Error ? error.message : String(error)).slice(0, 500) }], details: {}, isError: true };
+            }
+        } };
+}

package/dist/runtime/tool-call-map.js

@@ -83,7 +83,7 @@ const PLAN = new Set(["plan", "updateplan", "setplan", "todo", "todowrite", "exi
 // still falls through to the opaque default, never a false "Delegated".
 const DELEGATE = new Set([
     "task", "agent", "subagent", "runagent", "runsubagent", "spawnagent",
-    "dispatchagent", "delegate", "delegatetask", "agenttask", "startagent",
+    "dispatchagent", "delegate", "delegatetask", "agenttask", "startagent", "startrun",
 ]);
 const PATH_KEYS = ["path", "file_path", "filePath", "filename", "fileName", "file", "target_file", "targetFile"];
 /**

package/dist/server.js

@@ -111,6 +111,7 @@ import { redactSecrets } from "./redact.js";
 import { getSttConfig, isSttProvider, removeSttKey, setSttKey, setSttProvider, transcribeAudio, MAX_AUDIO_BYTES, } from "./stt.js";
 import { synthesizeOpenAiSpeech } from "./tts.js";
 import { seal, open } from "./e2e.js";
+import { RunDelegationService, parseDelegationSource, runToolProvider } from "./run-tools.js";
 import { ControlPlaneTaskPoller, resolveControlPlaneTaskConfig, } from "./control-plane-tasks.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, "..");
@@ -436,7 +437,66 @@ function resolveApproval(id, approved) {
     }
     return ok;
 }
-const integrations = new IntegrationManager(appDir, undefined, attachToChatForSession);
+async function delegatedRunRequest(pathname, init = {}) {
+    if (!sessionAdvertiseTarget)
+        throw new Error("Hosted Runs are not configured. Run bivy setup first.");
+    const headers = new Headers(init.headers);
+    headers.set("authorization", `Bearer ${sessionAdvertiseTarget.enrollmentToken}`);
+    if (init.body)
+        headers.set("content-type", "application/json");
+    const response = await fetch(`${sessionAdvertiseTarget.controlPlaneUrl.replace(/\/$/, "")}${pathname}`, { ...init, headers, signal: init.signal ?? AbortSignal.timeout(15_000) });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok)
+        throw new Error(typeof body.error === "string" ? body.error : `control plane returned ${response.status}`);
+    return body;
+}
+const runDelegation = new RunDelegationService({
+    parentContext: (sessionId) => {
+        const record = openSessions.get(sessionId);
+        return record ? { parentRunId: record.automationRunId, depth: record.delegationDepth } : undefined;
+    },
+    listRecent: async () => {
+        const body = await delegatedRunRequest("/node/automation-runs?limit=100");
+        return Array.isArray(body.runs) ? body.runs : [];
+    },
+    get: async (runId) => {
+        try {
+            return await delegatedRunRequest(`/node/automation-runs/${encodeURIComponent(runId)}`);
+        }
+        catch (error) {
+            if (error instanceof Error && /not found/i.test(error.message))
+                return undefined;
+            throw error;
+        }
+    },
+    start: async (_sessionId, input, provenance) => {
+        const machine = input.machine?.trim() || identity.name;
+        const nodes = await delegatedRunRequest("/nodes");
+        const target = Array.isArray(nodes) ? nodes.find((node) => node && typeof node === "object" && node.name === machine) : undefined;
+        const targetId = typeof target?.id === "string" ? target.id : machine === identity.name ? identity.nodeId : undefined;
+        if (!targetId)
+            throw new Error(`Machine not found on this account: ${machine}`);
+        return delegatedRunRequest("/node/automation-runs", {
+            method: "POST",
+            body: JSON.stringify({
+                title: "Delegated Run",
+                body: `bivy-room-v1:${targetId}:${seal(pairingStore.roomKey(), input.instructions)}`,
+                repo: input.repo,
+                node: machine,
+                runtimeId: input.agent,
+                model: input.model,
+                approvalMode: input.safety?.approval,
+                sandbox: input.safety?.sandbox,
+                maxAttempts: input.safety?.maxAttempts ?? 2,
+                idempotencyKey: input.idempotencyKey,
+                parentSessionId: provenance.parentSessionId,
+                parentRunId: provenance.parentRunId,
+                delegationDepth: provenance.depth,
+            }),
+        });
+    },
+});
+const integrations = new IntegrationManager(appDir, undefined, attachToChatForSession, (ref) => runToolProvider(runDelegation, () => ref.current));
 const terminals = new TerminalManager();
 // Per-session agents: a node holds one AgentRuntime instance *per agent id*,
 // built lazily and cached, instead of a single global runtime. `defaultRuntimeId`
@@ -4070,8 +4130,12 @@ function withIssueLock(key, fn) {
     return run;
 }
 function recordRunAuditCorrelation(record, correlation) {
-    if (correlation)
+    if (correlation) {
+        record.automationRunId = correlation.runId;
+        record.delegationDepth ??= 0;
+        persistSessionMetadata(record);
         auditLog.record({ kind: "run.correlation", session: record.id, agent: record.runtimeId, ...correlation });
+    }
 }
 async function runIssueTask(cfg, issue, overrides = {}) {
     const source = `issue:${cfg.owner}/${cfg.repo}#${issue.number}`;
@@ -4988,7 +5052,8 @@ async function runWorkItem(item, report, signal) {
     // definition name is metadata, not part of the instructions, so don't fold it
     // into the prompt. A scheduled chat message must arrive verbatim; the name is
     // only the run/session label.
-    const request = item.source === "schedule"
+    const delegatedProvenance = parseDelegationSource(item.source);
+    const request = item.source === "schedule" || delegatedProvenance
         ? (item.body || item.title)
         : item.body ? `${item.title}\n\n${item.body}` : item.title;
     // Plain chat messages (scheduled "message me later" reminders) skip the
@@ -5028,7 +5093,10 @@ async function runWorkItem(item, report, signal) {
     // `repo:owner/repo`, which is required by branch push/PR detection.
     if (!parsedRepo && !record.worktree)
         record.source = `queue:${item.source}`;
+    record.automationRunId = item.id;
+    record.delegationDepth = delegatedProvenance?.depth ?? 0;
     record.approvalMode = safety.approval;
+    persistSessionMetadata(record);
     if (item.model) {
         try {
             await record.session.setModel("", item.model);
@@ -6143,6 +6211,8 @@ function persistSessionMetadata(record, status = sessionStatus(record)) {
         workspace: record.workspace,
         source: record.source ?? "manual",
         forkedFrom: record.forkedFrom,
+        automationRunId: record.automationRunId,
+        delegationDepth: record.delegationDepth,
         runtimeId: record.runtimeId,
         sandbox: record.sandbox,
         agentName: getRuntime(record.runtimeId).displayName,
@@ -7843,7 +7913,7 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
     // Rehydrating (rather than leaving this undefined for a resumed session)
     // also avoids a persistSessionMetadata call later silently clobbering the
     // stored contract with undefined via its `{...prev, ...input}` merge.
-    const record = { id: sessionId, session, runtimeId: rt.id, sandbox: sessionSandbox, approvalMode: sessionSafety.approval, workspace: sessionWorkspace, sessionFile: session.sessionFile, agentServiceAddress: attachedAddress ?? rt.agentServiceAddress, worktree, source, prUrl: storedMeta?.prUrl, prs: storedMeta?.prs, contract: storedMeta?.contract, lastTouchedAt: resumedLastActive ?? Date.now(), warning: modelFallbackMessage, ephemeral: opts.ephemeral, workspaceState: runGit(["status", "--porcelain", "--untracked-files=normal"], sessionWorkspace) ? "dirty" : "clean" };
+    const record = { id: sessionId, session, runtimeId: rt.id, sandbox: sessionSandbox, approvalMode: sessionSafety.approval, automationRunId: storedMeta?.automationRunId, delegationDepth: storedMeta?.delegationDepth, workspace: sessionWorkspace, sessionFile: session.sessionFile, agentServiceAddress: attachedAddress ?? rt.agentServiceAddress, worktree, source, prUrl: storedMeta?.prUrl, prs: storedMeta?.prs, contract: storedMeta?.contract, lastTouchedAt: resumedLastActive ?? Date.now(), warning: modelFallbackMessage, ephemeral: opts.ephemeral, workspaceState: runGit(["status", "--porcelain", "--untracked-files=normal"], sessionWorkspace) ? "dirty" : "clean" };
     // Migration: a session resumed/reopened from before this feature (or from a
     // node that predates it) has no stored contract. Stamp an honest one now
     // from currently-observed facts rather than leaving it blank forever or
@@ -10408,6 +10478,33 @@ 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-owned child Run tools for MCP agents. These use the exact same service as
+// Pi's native ToolProvider and remain behind /api authentication. The service
+// authorizes every status lookup against this parent Session's provenance.
+app.post("/api/session/:id/delegated-runs", async (req, res) => {
+    try {
+        res.status(201).json(await runDelegation.startRun(String(req.params.id), req.body));
+    }
+    catch (error) {
+        res.status(400).json({ error: error instanceof Error ? error.message : String(error) });
+    }
+});
+app.get("/api/session/:id/delegated-runs/:runId", async (req, res) => {
+    try {
+        res.json(await runDelegation.getRunStatus(String(req.params.id), String(req.params.runId)));
+    }
+    catch (error) {
+        res.status(404).json({ error: error instanceof Error ? error.message : String(error) });
+    }
+});
+app.post("/api/session/:id/delegated-runs/:runId/wait", async (req, res) => {
+    try {
+        res.json(await runDelegation.waitForRun(String(req.params.id), String(req.params.runId), Number(req.body?.timeoutSeconds), AbortSignal.timeout(305_000)));
+    }
+    catch (error) {
+        res.status(400).json({ error: error instanceof Error ? error.message : String(error) });
+    }
+});
 app.post("/api/session/prompt", async (req, res, next) => {
     try {
         const text = String(req.body?.text ?? "").trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.10.1-staging.299",
+  "version": "0.10.1-staging.301",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",
@@ -63,6 +63,6 @@
     "brace-expansion": "5.0.9",
     "undici": "8.9.0"
   },
-  "readme": "# Bivy\n\n**Run agents where your environment lives. Reach, automate, and govern them from\nanywhere.**\n\nBivy makes coding agents on your infrastructure available from anywhere. Use\nClaude Code or Codex with the repositories, tools, services, and compute already\nin your development environment; continue the same Session from a phone, leave\nwork running, and return to checked changes or a pull request with a clear\nReceipt.\n\nInteractive Session traffic is end-to-end encrypted between a Machine and its\npaired devices. The relay cannot decrypt it. Explicitly enabled hosted\nprovisioning has a different boundary: the control plane may hold encrypted\ncloud, repository, or key-escrow material that the service can technically\naccess. Slack and generic webhook instructions also reach the control plane in\nplaintext. See [Why Bivy](docs/why-bivy.md) and the\n[security model](docs/security-model.md) for the complete trust model.\n\n- **Website:** [bivy.sh](https://bivy.sh)\n- **Documentation:** [`docs/`](docs/README.md) — start with the [quickstart](docs/quickstart.md)\n- **License:** [AGPL-3.0-only](LICENSE)\n\n> Bivy is 0.x software. The core loop is solid and used daily, but interfaces\n> and behaviour can change between releases.\n\n## Install\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nmacOS and Linux. Requires Node.js 22.19 or newer; the installer installs it for\nyou on Debian/Ubuntu and otherwise points you at nodejs.org. It installs the\n[`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) package from npm, puts\nthe `bivy` command on your `PATH`, then runs the guided `bivy setup` wizard —\nagent choice, relay/control-plane sign-in, and an auto-start background service\n(launchd on macOS, systemd on Linux). Re-running it on a machine that already\nhas Bivy just applies the latest build and restarts the service.\n\nAlready have Node.js 22.19+? The installer is optional:\n\n```bash\nnpm install -g @bivy/bivy\nbivy setup\n```\n\nOr try it once without installing anything (`npx` always fetches the latest):\n\n```bash\nnpx @bivy/bivy setup\n```\n\nReleases are published from CI with provenance attestations; verify a build's\norigin with `npm audit signatures`. See [`docs/releasing.md`](docs/releasing.md).\n\n### Install options\n\nEnvironment variables passed to the one-line installer change what it does:\n\n| Goal | Variable |\n|---|---|\n| Track the dev channel (new build on every merge to `main`) | `BIVY_CHANNEL=staging` |\n| Pin an exact version | `BIVY_VERSION=0.1.0` |\n| Install without sudo, into a user-owned prefix | `BIVY_NPM_PREFIX=~/.local` |\n| Preinstall every known upstream agent | `BIVY_INSTALL_ALL_AGENTS=1` |\n\nFor example: `BIVY_CHANNEL=staging curl -fsSL https://bivy.sh/install.sh | bash`.\n\nWorking from a checkout of this repository instead:\n\n```bash\npnpm install\npnpm run setup\n```\n\nSee [`docs/install.md`](docs/install.md) for where data lives, service\nmanagement, and uninstall.\n\n## Updating\n\n```bash\nbivy update\n```\n\n`bivy update` detects how Bivy was installed and does the right thing, then\nwaits for any active session to finish its current turn and restarts the\nbackground service so the node reconnects on the new build:\n\n| Install kind | What `bivy update` does |\n|---|---|\n| npm global (`npm i -g`) | `npm install -g @bivy/bivy@<channel>`, then restart the service |\n| installer / packaged | re-runs `install.sh` (migrating to npm if needed), then restart |\n| git checkout | `git pull --ff-only` + `pnpm install --frozen-lockfile`, then restart |\n| `npx` run | nothing to update — each run already fetches the latest |\n\nUpdates follow the release **channel** recorded at install time — `latest`\n(production) by default, or `staging` if you installed with\n`BIVY_CHANNEL=staging`. Switch channels (the choice is remembered for next\ntime), or skip the wait for a busy session:\n\n```bash\nbivy update --staging   # move to the dev channel\nbivy update --stable    # move back to production (latest)\nbivy update --force     # don't wait for an in-flight turn to finish\n```\n\nThe daemon also checks the registry periodically and posts an in-session notice\nwhen a newer build is available.\n\n## Architecture\n\nBivy has three parts. Only the first one holds your data.\n\n```text\n  your machine                     hosted or self-hosted\n\n  ┌──────────────┐               ┌─────────┐        ┌───────────────┐\n  │ node daemon  │  ──dials──▶   │  relay  │ ◀────▶ │ control plane │\n  │ agents, keys │    outbound   │ opaque  │        │ accounts, web │\n  │ repo, tools  │               │ frames  │        │ app, metadata │\n  └──────────────┘               └─────────┘        └───────────────┘\n         ▲                                                  ▲\n         └────────── end-to-end encrypted session ───────────┘\n                     phone · browser · another terminal\n```\n\n- **Node** — a daemon on your machine. Owns the workspace, credentials, and agent\n  processes. Serves an API and WebSocket on `http://localhost:4317` plus a\n  `/healthz` probe. **It hosts no web UI.**\n- **Relay** — forwards encrypted frames between your node and your devices. Your\n  node dials out, so no inbound port is opened. The relay cannot read the frames.\n- **Control plane** — holds your account, node registry, and session index, and\n  serves the web/PWA client. Use the hosted one or run your own.\n\nBecause the node serves no UI, a browser or phone needs a control plane — hosted\nat `app.bivy.sh`, or one you deploy yourself. The terminal CLI needs neither.\n\nSee [`docs/remote-access.md`](docs/remote-access.md) and\n[`docs/security-model.md`](docs/security-model.md).\n\n## Supported agents\n\n**Claude Code and Codex are the recommended, release-certified paths.** The\nbroader catalog remains available under **More agents** for users who need it;\ncapabilities and fidelity vary by runtime:\n\n| Agent | Command | Notes |\n|---|---|---|\n| Pi | `bivy run pi` | Uses the operator-installed `pi` command and Pi auth/config |\n| Claude Code | `bivy run claude` | Uses the operator-installed `claude` command through an SDK bridge |\n| Codex | `bivy run codex` | Installs `@openai/codex` |\n| OpenCode | `bivy run opencode` | Installs `opencode-ai` |\n| Gemini CLI | `bivy run gemini` | Installs `@google/gemini-cli` |\n| Qwen Code | `bivy run qwen` | Installs `@qwen-code/qwen-code` |\n| Goose | `bivy run goose` | Requires `goose` on PATH |\n| Aider | `bivy run aider` | No session resume (upstream gap) |\n| Cline | `bivy run cline` | Installs `cline` |\n| Crush | `bivy run crush` | No session resume (upstream gap) |\n| Cursor | `bivy run cursor` | ACP-capable |\n| GitHub Copilot | `bivy run copilot` | ACP-capable |\n| Grok | `bivy run grok` | Model selection |\n| Amp | `bivy run amp` | Native thread resume |\n| Auggie | `bivy run auggie` | Headless CLI |\n| Droid | `bivy run droid` | Model selection |\n| Continue | `bivy run continue` | Headless CLI |\n| Kilo Code | `bivy run kilocode` | ACP-capable |\n| Rovo Dev | `bivy run rovodev` | Installed out of band |\n\nAny other command works via `bivy run -- ./your-agent --flags`. ACP-capable\nagents can be promoted to Bivy's governed protocol path for per-tool approvals\nand native resume. To add a reusable process or ACP agent to both the CLI and web\npicker without changing Bivy, run `bivy agent add`, or scaffold and install a\ndeclarative [plugin manifest](docs/plugins.md) with `bivy plugin init`. Both use\nthe same schema/store; the plugin SDK, diagnostics, and ACP conformance fixtures\nsupport distributable or custom protocol bridges.\n\n[`docs/runtime-support-matrix.md`](docs/runtime-support-matrix.md) lists exactly\nwhat each agent supports — resume, model selection, approvals, sandboxing.\n\n## Common commands\n\n```bash\nbivy                  # show the command overview\nbivy run pi           # launch Pi as a durable session\nbivy run claude       # run a different agent\nbivy sessions         # list live and saved sessions\nbivy resume           # resume the most recent session\nbivy open             # open the web app (requires relay setup)\nbivy automation init  # create .bivy/automations.yaml\nbivy agent add        # connect an existing ACP or process agent\nbivy plugin list      # installed declarative integration packages\nbivy status           # config summary and node reachability\nbivy doctor           # health check\nbivy logs -f          # tail node logs\nbivy update           # update Bivy and restart the service\n```\n\nFull command list, flags, and examples: [`docs/cli-reference.md`](docs/cli-reference.md).\n\n## Configuration\n\nThe common knobs:\n\n```bash\nBIVY_WORKSPACE=/path/to/repo    # default workspace\nBIVY_SANDBOX=read-only          # read-only | workspace-write (default) | danger-full-access\nBIVY_APPROVAL_MODE=risky        # never | risky | always | autonomous (default)\n```\n\nCreate and inspect the typed node configuration, or add repository-owned\nsafety/check/retry policy:\n\n```bash\nbivy config init\nbivy config set defaults.agent codex\nbivy config explain defaults.sandbox\nbivy config init --project       # .bivy/policy.yaml\n```\n\nSee [`docs/config-as-code.md`](docs/config-as-code.md). Every environment\nvariable and precedence rule remains in\n[`docs/configuration.md`](docs/configuration.md).\n\n## Approvals and sandboxing\n\nThe default approval mode is **`autonomous`**: agents act without per-action\nprompts. The actual protection depends on the selected runtime. Native-sandbox\nagents enforce the chosen access tier; structured runtimes also pass tool calls\nthrough Bivy's policy and approval layer. Process agents that Bivy cannot\nintercept run with your OS user permissions. The picker shows this distinction\nand requires confirmation before selecting that limited path.\n\nWhere Bivy receives structured shell/file calls, a heuristic floor blocks known\ncatastrophic commands and structured writes outside the workspace, and a\nbackstop set (force-push, publish, deploy, sudo) pauses for a human. This catches\naccidents; it is not an adversarial isolation boundary.\n\nIf you want to be asked about more, set the mode explicitly:\n\n```bash\nBIVY_APPROVAL_MODE=risky    # prompt on risky shell commands and file edits\nBIVY_APPROVAL_MODE=always   # prompt on all shell commands and file edits\nBIVY_APPROVAL_MODE=never    # no prompts; structured-tool heuristic blocks still apply where available\n```\n\nApprove from the terminal, browser, or phone.\n\nSandbox tiers (`read-only`, `workspace-write`, `danger-full-access`) are enforced\nnatively by agents that support them — Codex, Claude Code, Gemini CLI, Qwen Code.\nAgents without a native sandbox may expose structured tool or MCP controls, but\nthose controls do not cover activity the agent performs outside those channels;\nsome process adapters run entirely with your user permissions. Check the\npicker's Protection label. **Bivy does not currently ship its own OS-level jail.**\n\n## Credentials\n\nInteractive prompts, transcripts, and workspace files stay encrypted across the\nrelay. Credentials can remain on a Machine or in a vault you control. If you\nexplicitly enable hosted unattended provisioning, Bivy Cloud may instead store\nencrypted cloud, repository, model, or key-escrow material that the service can\ntechnically access. Treat this as an explicit hosted-custody mode, not as relay\nblindness. See the\n[security model](docs/security-model.md#what-the-control-plane-sees).\n\n```bash\nbivy secrets list\nbivy secrets set github.repo-token\nbivy secrets ref github.repo-token op://Bivy/GitHub/repo-token\nbivy secrets doctor\n```\n\n`secret://`, `env://`, and `op://` (1Password) references are resolved on demand\nwhen the daemon provisions an agent run, so the raw values never sit in your\nconfig. See [`docs/key-management.md`](docs/key-management.md).\n\n## Automations as code\n\nDefine governed jobs in `.bivy/automations.yaml`, validate them, and simulate\ntrigger events locally before applying anything:\n\n```bash\nbivy automation init\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml\nbivy automation apply\n```\n\nInstructions are encrypted on the applying node before upload. Safety policy\nlives beside the job—sandbox, approval mode, and a hard attempt ceiling that\nretry/fallback rules cannot exceed. See\n[`docs/automations-as-code.md`](docs/automations-as-code.md).\n\n## GitHub Runs\n\nLabel an issue `bivy` (or `bivy/<machine>` to target a Machine), or mention the\nBivy GitHub App in a comment. Bivy creates a Run on the selected Machine, uses an\nisolated worktree, executes configured checks, and reports an explicit outcome.\n\nAvailable on every plan. On Bivy Cloud, the free trial shows the first 25\ndistinct sessions in the hosted app and includes 10 unattended automations per\nrolling 7-day window across GitHub, Slack, webhooks, and schedules. Sessions keep\nrunning on your machines after the hosted trial is exhausted, but new ones are\nhidden from the hosted app until you subscribe. Pro removes both limits.\nSelf-hosted stacks are unlimited.\n\nA private GitHub App only installs on the account that owns it, so connect one\napp per GitHub account — one for your personal repos, one per organization\n(`bivy github:app-create --org <org>`). A node can serve several at once, each\nwith its own key and `@`-mention handle.\n\nSee [`docs/github-work-queue.md`](docs/github-work-queue.md).\n\n## Linear Runs\n\nApply `bivy` or `bivy/<machine>` to a Linear issue to create a Run on the selected\nMachine. The Machine fetches issue content directly from Linear, works in an\nisolated GitHub worktree, and asks the agent to open a pull request. See\n[`docs/linear-work-queue.md`](docs/linear-work-queue.md).\n\n## Development\n\n```bash\npnpm install\npnpm run dev          # node daemon on http://localhost:4317\npnpm run dev:web      # web client dev server (proxies /api and /ws to the node)\n```\n\nChecks — all of these run in CI:\n\n```bash\npnpm run typecheck\npnpm run typecheck:web\npnpm run lint\npnpm run test:unit\npnpm run test:core\npnpm run check:licenses\npnpm run check:secrets\n```\n\nRepository layout:\n\n- `src/` — node daemon, runtime adapters, approvals, secrets, sessions\n- `bin/` — the `bivy` CLI\n- `packages/core` — shared protocol, pairing, wire format\n- `packages/web` — the React/Vite PWA client (`@bivy/web`)\n- `services/relay` — self-hostable relay\n- `services/control-plane` — self-hostable control plane\n- `deploy/` — self-host deployment examples\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## Self-hosting\n\nNode, relay, and control plane are all in this repository. Point a node at your\nown deployment by passing URLs to `bivy relay:setup` — re-running it switches an\nexisting node over to the new endpoints:\n\n```bash\nbivy relay:setup \\\n  --control-plane https://bivy.example.com \\\n  --relay wss://relay.example.com\n```\n\nEach URL has a flag and an environment-variable equivalent (the flag wins):\n\n| Flag | Environment variable | Points at | Default |\n|---|---|---|---|\n| `--control-plane <url>` | `BIVY_CONTROL_PLANE_URL` | accounts, node registry, and the web-app API | hosted (`app.bivy.sh`) |\n| `--relay <wss-url>` | `BIVY_RELAY_URL` | the encrypted-frame relay your node dials out to | hosted |\n| `--client <url>` | `BIVY_CLIENT_BASE_URL` | base URL used when building app/PWA links | the `--control-plane` URL |\n\nSign-in defaults to GitHub device login (`--github`); pass\n`--email you@example.com` for an email magic-link, or `--session-token <token>`\nto skip interactive sign-in. `relay:setup` checks the control plane is reachable, enrolls\nthis node, and writes the endpoints to `.bivy/relay.json`, so `bivy open`,\n`bivy link`, and `bivy update` all keep using your deployment afterwards.\n\n**Self-hosting is unsupported** — no SLA, community best-effort via GitHub\nissues. You own TLS, backups, upgrades, and hardening. See\n[`docs/self-host.md`](docs/self-host.md).\n\n## Security\n\nReport vulnerabilities through [GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new).\nPlease do not open a public issue. See [`SECURITY.md`](SECURITY.md) for scope,\nresponse times, and safe harbour, and [`docs/security-model.md`](docs/security-model.md)\nfor the trust model and known limitations.\n\n## License\n\nBivy Core is free and open-source software licensed under the GNU Affero General\nPublic License, version 3.0 only (AGPL-3.0-only). You may use, study, modify, and\nself-host it under that license. If you modify Bivy and let users interact with\nit over a network, section 13 requires you to offer those users the corresponding\nsource code.\n\nSee [`LICENSE`](LICENSE), [`CORE.md`](CORE.md), and [`CLOUD.md`](CLOUD.md).\n",
+  "readme": "# Bivy\n\n**Give coding agents your real environment, then reach them from anywhere.**\n\nA provider sandbox starts from an approximation. A Bivy Machine can use the\nrepository, local services and databases, private networks, existing tools and\ncaches, and GPUs or local inference already available on your workstation or\nserver. Bivy turns that local capability into Sessions you can continue remotely\nand Runs you can leave working unattended.\n\n## What Bivy lets you do\n\n- **Work where the full environment lives.** Run Claude Code, Codex, Pi, or\n  another agent beside real repos, dev servers, databases, internal APIs,\n  toolchains, package caches, and specialized compute.\n- **Continue from a phone, browser, or terminal.** Reconnect to the same Session,\n  steer or stop it, answer questions, and approve supported tool calls. The PWA\n  supports voice input and read-aloud, phone-to-agent file/image uploads, and\n  agent-to-phone attachments. Native terminal Sessions can stay remote-visible;\n  supported runtimes can hand work between terminal and structured chat.\n- **Move work without starting over.** Import existing Claude Code and Codex\n  Sessions, or fork/copy/move a Bivy Session to another agent, model, or Machine.\n  Fidelity is runtime-dependent: a fork may use a native transcript, replayed\n  history, or a bounded seeded continuation, and cross-Machine moves require the\n  destination's repo access, agent, and credentials.\n- **Operate more than one Machine.** Keep a workstation, private-network server,\n  and GPU box on one account; select the environment a Session or Run needs.\n  Optional warm Session replication is Beta, off by default, and manually\n  promoted rather than automatic failover.\n- **Let events start checked work.** Create Runs manually or from failed CI,\n  GitHub/Linear issues, Slack, schedules, and signed webhooks. Automations can\n  pin a Machine, agent, model, sandbox, approval mode, and attempt ceiling, then\n  report bounded check and outcome evidence in a Receipt.\n- **Bring your own stack.** Use provider subscriptions through supported native\n  agent logins, API keys in Bivy's vault, or local/OpenAI-compatible inference.\n  Add an existing ACP or headless process agent with `bivy agent add`; declarative\n  agent plugins are Experimental (`v1alpha1`) and run out of process.\n\nStart with the [five-minute quickstart](docs/quickstart.md), then try the\n[capability recipes](docs/capability-recipes.md) or check the exact\n[runtime support matrix](docs/runtime-support-matrix.md).\n\nInteractive Session traffic is end-to-end encrypted between a Machine and its\npaired devices, so the relay cannot decrypt it. The seatbelt has a precise edge:\nexplicitly enabled hosted provisioning may give the control plane technical\naccess to encrypted cloud, repository, or key-escrow material, while Slack and\ngeneric webhook instructions reach it in plaintext. See [Why Bivy](docs/why-bivy.md)\nand the [security model](docs/security-model.md) for the complete trust model.\n\n- **Website:** [bivy.sh](https://bivy.sh)\n- **Documentation:** [`docs/`](docs/README.md)\n- **License:** [AGPL-3.0-only](LICENSE)\n\n> Bivy is 0.x software. The core loop is solid and used daily, but interfaces,\n> cross-runtime fidelity, and behaviour can change between releases. Check the\n> support matrix before depending on a particular agent capability.\n\n## Install\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nmacOS and Linux. Requires Node.js 22.19 or newer; the installer installs it for\nyou on Debian/Ubuntu and otherwise points you at nodejs.org. It installs the\n[`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) package from npm, puts\nthe `bivy` command on your `PATH`, then runs the guided `bivy setup` wizard —\nagent choice, relay/control-plane sign-in, and an auto-start background service\n(launchd on macOS, systemd on Linux). Re-running it on a machine that already\nhas Bivy just applies the latest build and restarts the service.\n\nAlready have Node.js 22.19+? The installer is optional:\n\n```bash\nnpm install -g @bivy/bivy\nbivy setup\n```\n\nOr try it once without installing anything (`npx` always fetches the latest):\n\n```bash\nnpx @bivy/bivy setup\n```\n\nReleases are published from CI with provenance attestations; verify a build's\norigin with `npm audit signatures`. See [`docs/releasing.md`](docs/releasing.md).\n\n### Install options\n\nEnvironment variables passed to the one-line installer change what it does:\n\n| Goal | Variable |\n|---|---|\n| Track the dev channel (new build on every merge to `main`) | `BIVY_CHANNEL=staging` |\n| Pin an exact version | `BIVY_VERSION=0.1.0` |\n| Install without sudo, into a user-owned prefix | `BIVY_NPM_PREFIX=~/.local` |\n| Preinstall every known upstream agent | `BIVY_INSTALL_ALL_AGENTS=1` |\n\nFor example: `BIVY_CHANNEL=staging curl -fsSL https://bivy.sh/install.sh | bash`.\n\nWorking from a checkout of this repository instead:\n\n```bash\npnpm install\npnpm run setup\n```\n\nSee [`docs/install.md`](docs/install.md) for where data lives, service\nmanagement, and uninstall.\n\n## Updating\n\n```bash\nbivy update\n```\n\n`bivy update` detects how Bivy was installed and does the right thing, then\nwaits for any active session to finish its current turn and restarts the\nbackground service so the node reconnects on the new build:\n\n| Install kind | What `bivy update` does |\n|---|---|\n| npm global (`npm i -g`) | `npm install -g @bivy/bivy@<channel>`, then restart the service |\n| installer / packaged | re-runs `install.sh` (migrating to npm if needed), then restart |\n| git checkout | `git pull --ff-only` + `pnpm install --frozen-lockfile`, then restart |\n| `npx` run | nothing to update — each run already fetches the latest |\n\nUpdates follow the release **channel** recorded at install time — `latest`\n(production) by default, or `staging` if you installed with\n`BIVY_CHANNEL=staging`. Switch channels (the choice is remembered for next\ntime), or skip the wait for a busy session:\n\n```bash\nbivy update --staging   # move to the dev channel\nbivy update --stable    # move back to production (latest)\nbivy update --force     # don't wait for an in-flight turn to finish\n```\n\nThe daemon also checks the registry periodically and posts an in-session notice\nwhen a newer build is available.\n\n## Architecture\n\nBivy has three parts. Only the first one holds your data.\n\n```text\n  your machine                     hosted or self-hosted\n\n  ┌──────────────┐               ┌─────────┐        ┌───────────────┐\n  │ node daemon  │  ──dials──▶   │  relay  │ ◀────▶ │ control plane │\n  │ agents, keys │    outbound   │ opaque  │        │ accounts, web │\n  │ repo, tools  │               │ frames  │        │ app, metadata │\n  └──────────────┘               └─────────┘        └───────────────┘\n         ▲                                                  ▲\n         └────────── end-to-end encrypted session ───────────┘\n                     phone · browser · another terminal\n```\n\n- **Node** — a daemon on your machine. Owns the workspace, credentials, and agent\n  processes. Serves an API and WebSocket on `http://localhost:4317` plus a\n  `/healthz` probe. **It hosts no web UI.**\n- **Relay** — forwards encrypted frames between your node and your devices. Your\n  node dials out, so no inbound port is opened. The relay cannot read the frames.\n- **Control plane** — holds your account, node registry, and session index, and\n  serves the web/PWA client. Use the hosted one or run your own.\n\nBecause the node serves no UI, a browser or phone needs a control plane — hosted\nat `app.bivy.sh`, or one you deploy yourself. The terminal CLI needs neither.\n\nSee [`docs/remote-access.md`](docs/remote-access.md) and\n[`docs/security-model.md`](docs/security-model.md).\n\n## Supported agents\n\n**Claude Code and Codex are the recommended, release-certified paths.** The\nbroader catalog remains available under **More agents** for users who need it;\ncapabilities and fidelity vary by runtime:\n\n| Agent | Command | Notes |\n|---|---|---|\n| Pi | `bivy run pi` | Uses the operator-installed `pi` command and Pi auth/config |\n| Claude Code | `bivy run claude` | Uses the operator-installed `claude` command through an SDK bridge |\n| Codex | `bivy run codex` | Installs `@openai/codex` |\n| OpenCode | `bivy run opencode` | Installs `opencode-ai` |\n| Gemini CLI | `bivy run gemini` | Installs `@google/gemini-cli` |\n| Qwen Code | `bivy run qwen` | Installs `@qwen-code/qwen-code` |\n| Goose | `bivy run goose` | Requires `goose` on PATH |\n| Aider | `bivy run aider` | No session resume (upstream gap) |\n| Cline | `bivy run cline` | Installs `cline` |\n| Crush | `bivy run crush` | No session resume (upstream gap) |\n| Cursor | `bivy run cursor` | ACP-capable |\n| GitHub Copilot | `bivy run copilot` | ACP-capable |\n| Grok | `bivy run grok` | Model selection |\n| Amp | `bivy run amp` | Native thread resume |\n| Auggie | `bivy run auggie` | Headless CLI |\n| Droid | `bivy run droid` | Model selection |\n| Continue | `bivy run continue` | Headless CLI |\n| Kilo Code | `bivy run kilocode` | ACP-capable |\n| Rovo Dev | `bivy run rovodev` | Installed out of band |\n\nAny other command works via `bivy run -- ./your-agent --flags`. ACP-capable\nagents can be promoted to Bivy's governed protocol path for per-tool approvals\nand native resume. To add a reusable process or ACP agent to both the CLI and web\npicker without changing Bivy, run `bivy agent add`, or scaffold and install a\ndeclarative [plugin manifest](docs/plugins.md) with `bivy plugin init`. Both use\nthe same schema/store; the plugin SDK, diagnostics, and ACP conformance fixtures\nsupport distributable or custom protocol bridges.\n\n[`docs/runtime-support-matrix.md`](docs/runtime-support-matrix.md) lists exactly\nwhat each agent supports — resume, model selection, approvals, sandboxing.\n\n## Common commands\n\n```bash\nbivy                  # show the command overview\nbivy run pi           # launch Pi as a durable session\nbivy run claude       # run a different agent\nbivy sessions         # list live and saved sessions\nbivy resume           # resume the most recent session\nbivy open             # open the web app (requires relay setup)\nbivy automation init  # create .bivy/automations.yaml\nbivy agent add        # connect an existing ACP or process agent\nbivy plugin list      # installed declarative integration packages\nbivy status           # config summary and node reachability\nbivy doctor           # health check\nbivy logs -f          # tail node logs\nbivy update           # update Bivy and restart the service\n```\n\nFull command list, flags, and examples: [`docs/cli-reference.md`](docs/cli-reference.md).\n\n## Configuration\n\nThe common knobs:\n\n```bash\nBIVY_WORKSPACE=/path/to/repo    # default workspace\nBIVY_SANDBOX=read-only          # read-only | workspace-write (default) | danger-full-access\nBIVY_APPROVAL_MODE=risky        # never | risky | always | autonomous (default)\n```\n\nCreate and inspect the typed node configuration, or add repository-owned\nsafety/check/retry policy:\n\n```bash\nbivy config init\nbivy config set defaults.agent codex\nbivy config explain defaults.sandbox\nbivy config init --project       # .bivy/policy.yaml\n```\n\nSee [`docs/config-as-code.md`](docs/config-as-code.md). Every environment\nvariable and precedence rule remains in\n[`docs/configuration.md`](docs/configuration.md).\n\n## Approvals and sandboxing\n\nThe default approval mode is **`autonomous`**: agents act without per-action\nprompts. The actual protection depends on the selected runtime. Native-sandbox\nagents enforce the chosen access tier; structured runtimes also pass tool calls\nthrough Bivy's policy and approval layer. Process agents that Bivy cannot\nintercept run with your OS user permissions. The picker shows this distinction\nand requires confirmation before selecting that limited path.\n\nWhere Bivy receives structured shell/file calls, a heuristic floor blocks known\ncatastrophic commands and structured writes outside the workspace, and a\nbackstop set (force-push, publish, deploy, sudo) pauses for a human. This catches\naccidents; it is not an adversarial isolation boundary.\n\nIf you want to be asked about more, set the mode explicitly:\n\n```bash\nBIVY_APPROVAL_MODE=risky    # prompt on risky shell commands and file edits\nBIVY_APPROVAL_MODE=always   # prompt on all shell commands and file edits\nBIVY_APPROVAL_MODE=never    # no prompts; structured-tool heuristic blocks still apply where available\n```\n\nApprove from the terminal, browser, or phone.\n\nSandbox tiers (`read-only`, `workspace-write`, `danger-full-access`) are enforced\nnatively by agents that support them — Codex, Claude Code, Gemini CLI, Qwen Code.\nAgents without a native sandbox may expose structured tool or MCP controls, but\nthose controls do not cover activity the agent performs outside those channels;\nsome process adapters run entirely with your user permissions. Check the\npicker's Protection label. **Bivy does not currently ship its own OS-level jail.**\n\n## Credentials\n\nInteractive prompts, transcripts, and workspace files stay encrypted across the\nrelay. Credentials can remain on a Machine or in a vault you control. If you\nexplicitly enable hosted unattended provisioning, Bivy Cloud may instead store\nencrypted cloud, repository, model, or key-escrow material that the service can\ntechnically access. Treat this as an explicit hosted-custody mode, not as relay\nblindness. See the\n[security model](docs/security-model.md#what-the-control-plane-sees).\n\n```bash\nbivy secrets list\nbivy secrets set github.repo-token\nbivy secrets ref github.repo-token op://Bivy/GitHub/repo-token\nbivy secrets doctor\n```\n\n`secret://`, `env://`, and `op://` (1Password) references are resolved on demand\nwhen the daemon provisions an agent run, so the raw values never sit in your\nconfig. See [`docs/key-management.md`](docs/key-management.md).\n\n## Automations as code\n\nDefine governed jobs in `.bivy/automations.yaml`, validate them, and simulate\ntrigger events locally before applying anything:\n\n```bash\nbivy automation init\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml\nbivy automation apply\n```\n\nInstructions are encrypted on the applying node before upload. Safety policy\nlives beside the job—sandbox, approval mode, and a hard attempt ceiling that\nretry/fallback rules cannot exceed. See\n[`docs/automations-as-code.md`](docs/automations-as-code.md).\n\n## GitHub Runs\n\nLabel an issue `bivy` (or `bivy/<machine>` to target a Machine), or mention the\nBivy GitHub App in a comment. Bivy creates a Run on the selected Machine, uses an\nisolated worktree, executes configured checks, and reports an explicit outcome.\n\nAvailable on every plan. On Bivy Cloud, the free trial shows the first 25\ndistinct sessions in the hosted app and includes 10 unattended automations per\nrolling 7-day window across GitHub, Slack, webhooks, and schedules. Sessions keep\nrunning on your machines after the hosted trial is exhausted, but new ones are\nhidden from the hosted app until you subscribe. Pro removes both limits.\nSelf-hosted stacks are unlimited.\n\nA private GitHub App only installs on the account that owns it, so connect one\napp per GitHub account — one for your personal repos, one per organization\n(`bivy github:app-create --org <org>`). A node can serve several at once, each\nwith its own key and `@`-mention handle.\n\nSee [`docs/github-work-queue.md`](docs/github-work-queue.md).\n\n## Linear Runs\n\nApply `bivy` or `bivy/<machine>` to a Linear issue to create a Run on the selected\nMachine. The Machine fetches issue content directly from Linear, works in an\nisolated GitHub worktree, and asks the agent to open a pull request. See\n[`docs/linear-work-queue.md`](docs/linear-work-queue.md).\n\n## Development\n\n```bash\npnpm install\npnpm run dev          # node daemon on http://localhost:4317\npnpm run dev:web      # web client dev server (proxies /api and /ws to the node)\n```\n\nChecks — all of these run in CI:\n\n```bash\npnpm run typecheck\npnpm run typecheck:web\npnpm run lint\npnpm run test:unit\npnpm run test:core\npnpm run check:licenses\npnpm run check:secrets\n```\n\nRepository layout:\n\n- `src/` — node daemon, runtime adapters, approvals, secrets, sessions\n- `bin/` — the `bivy` CLI\n- `packages/core` — shared protocol, pairing, wire format\n- `packages/web` — the React/Vite PWA client (`@bivy/web`)\n- `services/relay` — self-hostable relay\n- `services/control-plane` — self-hostable control plane\n- `deploy/` — self-host deployment examples\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## Self-hosting\n\nNode, relay, and control plane are all in this repository. Point a node at your\nown deployment by passing URLs to `bivy relay:setup` — re-running it switches an\nexisting node over to the new endpoints:\n\n```bash\nbivy relay:setup \\\n  --control-plane https://bivy.example.com \\\n  --relay wss://relay.example.com\n```\n\nEach URL has a flag and an environment-variable equivalent (the flag wins):\n\n| Flag | Environment variable | Points at | Default |\n|---|---|---|---|\n| `--control-plane <url>` | `BIVY_CONTROL_PLANE_URL` | accounts, node registry, and the web-app API | hosted (`app.bivy.sh`) |\n| `--relay <wss-url>` | `BIVY_RELAY_URL` | the encrypted-frame relay your node dials out to | hosted |\n| `--client <url>` | `BIVY_CLIENT_BASE_URL` | base URL used when building app/PWA links | the `--control-plane` URL |\n\nSign-in defaults to GitHub device login (`--github`); pass\n`--email you@example.com` for an email magic-link, or `--session-token <token>`\nto skip interactive sign-in. `relay:setup` checks the control plane is reachable, enrolls\nthis node, and writes the endpoints to `.bivy/relay.json`, so `bivy open`,\n`bivy link`, and `bivy update` all keep using your deployment afterwards.\n\n**Self-hosting is unsupported** — no SLA, community best-effort via GitHub\nissues. You own TLS, backups, upgrades, and hardening. See\n[`docs/self-host.md`](docs/self-host.md).\n\n## Security\n\nReport vulnerabilities through [GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new).\nPlease do not open a public issue. See [`SECURITY.md`](SECURITY.md) for scope,\nresponse times, and safe harbour, and [`docs/security-model.md`](docs/security-model.md)\nfor the trust model and known limitations.\n\n## License\n\nBivy Core is free and open-source software licensed under the GNU Affero General\nPublic License, version 3.0 only (AGPL-3.0-only). You may use, study, modify, and\nself-host it under that license. If you modify Bivy and let users interact with\nit over a network, section 13 requires you to offer those users the corresponding\nsource code.\n\nSee [`LICENSE`](LICENSE), [`CORE.md`](CORE.md), and [`CLOUD.md`](CLOUD.md).\n",
   "readmeFilename": "README.md"
 }