@bivy/bivy 0.5.1-staging.71 → 0.5.1-staging.73

package/dist/command-launch.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+/**
+ * Keep terminal semantics opt-in for short-lived commands. Native interactive
+ * commands must set requiresTty; ordinary commands stay on direct pipes and do
+ * not pay for a Python PTY relay.
+ */
+export function commandLaunch(command, args, requiresTty, pythonCommand, ptyRunnerScript) {
+    return requiresTty
+        ? { command: pythonCommand, args: [ptyRunnerScript, command, ...args], usesPty: true }
+        : { command, args: [...args], usesPty: false };
+}

package/dist/runtime/index.js

@@ -80,6 +80,7 @@ function claudeCodeInfo() {
     const installed = claudeSdkInstalled();
     return {
         id: "claude-code-sdk",
+        executionMode: "protocol",
         displayName: "Claude Code SDK",
         description: "Anthropic's Claude Agent SDK driven as a Bivy runtime: streaming turns, model picker, and tool approvals via the SDK permission callback.",
         status: installed ? "available" : "planned",
@@ -117,6 +118,7 @@ function genericCliInfo() {
     const resume = Boolean(options?.resumeArgs);
     return {
         id: "generic-cli",
+        executionMode: "pipe",
         displayName: process.env.BIVY_AGENT_NAME?.trim() || "Generic CLI Agent",
         description: "Run any local agent CLI underneath Bivy by spawning a configured process and streaming stdout/stderr.",
         status: configured ? "available" : "planned",
@@ -899,10 +901,23 @@ function cliAgentInfo(id) {
     let resume = id === "codex" || Boolean(cliResumeTemplate(id));
     let modelSelection = Boolean(cliModelConfig(id));
     const usageReporting = cliUsageReporting(id);
+    const structuredPref = process.env.BIVY_AGENT_STRUCTURED;
+    const structuredAvailable = Boolean(process.env.BIVY_AGENT_PARSER || spec.parserId) && (!spec.parserUnverified || structuredPref === "1") && structuredPref !== "0";
     // When the agent is promoted to ACP (spec.acp + BIVY_<ID>_ACP / BIVY_PREFER_ACP),
     // it runs through the governed ProtocolRuntime — so it honestly gains per-tool
     // approvals and resume. Reflect that in the catalog the picker reads.
     const acpActive = prefersAcp(id);
+    // Catalog discovery must remain usable even when an operator has configured
+    // an invalid mode. The actual launch path resolves strictly and reports the
+    // actionable error; the picker falls back to the honest default here.
+    let executionMode;
+    try {
+        executionMode = resolveCliExecutionMode({ requested: requestedCliExecutionMode(id), protocolAvailable: Boolean(spec.acp), structuredAvailable, protocolPreferred: acpActive });
+    }
+    catch {
+        executionMode = structuredAvailable ? "structured-pipe" : "pipe";
+    }
+    const structured = executionMode === "structured-pipe";
     if (acpActive)
         resume = true;
     // Opt-in self-healing: if the installed binary's --help doesn't evidence a
@@ -918,6 +933,7 @@ function cliAgentInfo(id) {
     }
     return {
         id,
+        executionMode,
         displayName: spec.displayName,
         description: spec.blurb ?? `Run the local ${spec.displayName} CLI underneath Bivy in the session workspace.`,
         status: installed ? "available" : "external",
@@ -950,6 +966,7 @@ function codexApprovalsInfo() {
     const installed = commandAvailable("codex");
     return {
         id: "codex-approvals",
+        executionMode: "protocol",
         displayName: "Codex",
         description: "Codex driven through its app-server: every shell command or file change it proposes is gated through Bivy's Approve/Deny before it runs (not just the exec jail), and sessions resume with full history.",
         status: installed ? "available" : "external",
@@ -1144,10 +1161,45 @@ function prefersAcp(id) {
         return false;
     return process.env.BIVY_PREFER_ACP === "1" || process.env[`BIVY_${id.toUpperCase()}_ACP`] === "1";
 }
+/**
+ * Resolve the communication mode for a CLI agent. This is deliberately pure so
+ * it can be tested without starting a process. PTY is a terminal-launch mode,
+ * not a governed ProcessRuntime mode; callers must handle it explicitly.
+ */
+export function resolveCliExecutionMode(input) {
+    const raw = input.requested?.trim().toLowerCase() || "auto";
+    const requested = (raw === "structured" ? "structured-pipe" : raw);
+    if (!["auto", "protocol", "structured-pipe", "pipe", "pty"].includes(requested)) {
+        throw new Error(`Invalid agent execution mode "${input.requested}". Use auto, protocol, structured-pipe, pipe, or pty.`);
+    }
+    if (requested === "pty")
+        return "pty";
+    if (requested === "protocol") {
+        if (!input.protocolAvailable)
+            throw new Error("Protocol execution was requested, but this agent has no configured protocol adapter.");
+        return "protocol";
+    }
+    if (requested === "structured-pipe") {
+        if (!input.structuredAvailable)
+            throw new Error("Structured pipe execution was requested, but this agent has no available structured parser.");
+        return "structured-pipe";
+    }
+    if (requested === "pipe")
+        return "pipe";
+    if (input.protocolAvailable && input.protocolPreferred)
+        return "protocol";
+    if (input.structuredAvailable)
+        return "structured-pipe";
+    return "pipe";
+}
+function requestedCliExecutionMode(id) {
+    return process.env[`BIVY_${id.toUpperCase()}_MODE`] ?? process.env.BIVY_AGENT_MODE;
+}
 function acpInfo() {
     const configured = Boolean(process.env.BIVY_ACP_COMMAND?.trim());
     return {
         id: "acp",
+        executionMode: "protocol",
         displayName: process.env.BIVY_ACP_NAME?.trim() || "ACP Agent",
         description: "Any Agent Client Protocol (ACP) agent, driven through Bivy's shim for per-tool approvals, streaming, and resume.",
         status: configured ? "available" : "planned",
@@ -1202,6 +1254,7 @@ function openClawInfo() {
     const installCommand = `npm install --global --prefix ${npmPrefix} openclaw`;
     return {
         id: "openclaw",
+        executionMode: "pipe",
         displayName: options.displayName,
         description: "Run the local OpenClaw CLI underneath Bivy in the session workspace.",
         status: installed ? "available" : "external",
@@ -1228,6 +1281,7 @@ function protocolInfo() {
     const commands = protocolCommandsFromEnv();
     return {
         id: "bivy-agent-protocol",
+        executionMode: "protocol",
         displayName: process.env.BIVY_PROTOCOL_NAME?.trim() || "Bivy Protocol",
         description: "JSON-lines process protocol for any agent to expose structured events, tool calls, approvals, models, and sessions without a bespoke Bivy adapter.",
         status: configured ? "available" : "planned",
@@ -1244,6 +1298,7 @@ function protocolInfo() {
 export const RUNTIME_CATALOG = [
     {
         id: "pi",
+        executionMode: "protocol",
         displayName: "Pi",
         description: "Native Bivy/Pi coding agent runtime with packages, approvals, and model picker.",
         status: "available",
@@ -1476,23 +1531,26 @@ function makeCliRuntime(id, options) {
     const spec = CLI_AGENT_SPECS[id];
     if (!commandAvailable(spec.command))
         throw new Error(`${spec.displayName} command not found on PATH: ${spec.command}`);
-    // ACP promotion: when the agent declares an `acp` mode and it's preferred
-    // (BIVY_<ID>_ACP=1 / BIVY_PREFER_ACP=1), drive it through the governed
-    // ProtocolRuntime (per-tool approvals + streaming + resume) instead of the
-    // one-shot pipe below — the high-capability path, selected as data.
-    if (spec.acp && prefersAcp(id)) {
+    // Resolve the mode before launching anything. ACP and structured parsing
+    // remain data-driven; explicit mode overrides are fail-closed rather than
+    // silently degrading to a less capable path.
+    const structuredPref = process.env.BIVY_AGENT_STRUCTURED;
+    const structuredAvailable = Boolean(process.env.BIVY_AGENT_PARSER || spec.parserId) && (!spec.parserUnverified || structuredPref === "1") && structuredPref !== "0";
+    const executionMode = resolveCliExecutionMode({
+        requested: requestedCliExecutionMode(id),
+        protocolAvailable: Boolean(spec.acp),
+        structuredAvailable,
+        protocolPreferred: prefersAcp(id),
+    });
+    if (executionMode === "pty") {
+        throw new Error(`PTY mode is for interactive terminal launches. Use 'bivy run ${spec.command}' instead of a governed chat session.`);
+    }
+    if (executionMode === "protocol") {
+        if (!spec.acp)
+            throw new Error(`${spec.displayName} does not declare an ACP/protocol launch mode.`);
         return new ProtocolRuntime(acpRuntimeOptions({ id, displayName: spec.displayName, command: spec.command, agentArgs: spec.acp.args, credsDir: options.credsDir }));
     }
-    // Phase 4 — structured mode ON by default when the agent has a VALIDATED JSON
-    // parser: launch with its native JSON flags and parse stdout into normalized
-    // events. BIVY_AGENT_STRUCTURED=0 forces the dumb-pipe fallback everywhere;
-    // BIVY_AGENT_STRUCTURED=1 opts INTO structured mode for agents whose parser
-    // is still unverified (spec.parserUnverified — safe default is dumb pipe so a
-    // wrong flag can't regress a working agent). BIVY_AGENT_PARSER overrides the
-    // parser id (e.g. to "bivy-protocol").
-    const structuredPref = process.env.BIVY_AGENT_STRUCTURED;
-    const parserReady = Boolean(spec.parserId) && (!spec.parserUnverified || structuredPref === "1");
-    const structured = parserReady && structuredPref !== "0";
+    const structured = executionMode === "structured-pipe";
     const parserId = process.env.BIVY_AGENT_PARSER || (structured ? spec.parserId : undefined);
     const tier = sandboxTier(options.sandbox);
     // BIVY_<ID>_ARGS overrides the launch flags for a CLI version we haven't

package/dist/server.js

@@ -46,6 +46,7 @@ import { buildSessionSnapshot, applySessionSnapshot } from "./session/snapshot.j
 import { createCheckpointBundle, applyCheckpointBundle, materializeCheckpoint } from "./session/checkpoint-pack.js";
 import { PolicyEngine } from "./policy/policy-engine.js";
 import { TerminalManager } from "./terminal.js";
+import { commandLaunch } from "./command-launch.js";
 import { listMultiplexerSessions, attachCommand } from "./multiplexer.js";
 import { createWorktree, removeWorktree, branchSlug, gitRepoRoot } from "./worktree.js";
 import { HarnessManager } from "./harness/manager.js";
@@ -1415,12 +1416,12 @@ const commands = [
     { name: "/help", description: "Show quick chat help.", kind: "server", run: () => ({
             text: "Use /commands to open the command list. Press Cmd/Ctrl+Enter to send a prompt. Attach files/images with the + button or by dragging them into the message box.",
         }) },
-    { name: "/login", description: "Connect a model provider in Terminal.", kind: "native", spawn: { command: process.execPath, args: [...agentPrefix, "/login"] } },
-    { name: "/model", description: "Open the searchable model selector.", kind: "native", spawn: { command: process.execPath, args: [...agentPrefix, "/model"] } },
-    { name: "/terminal", description: "Start the terminal agent in this workspace and stream its output.", kind: "native", spawn: { command: process.execPath, args: [...agentPrefix] } },
-    { name: "/config", description: "Show agent configuration.", kind: "native", spawn: { command: process.execPath, args: [...agentPrefix, "config"] } },
-    { name: "/list", description: "List installed agent packages.", kind: "native", spawn: { command: process.execPath, args: [...agentPrefix, "list"] } },
-    { name: "/update", description: "Update agent packages.", kind: "native", spawn: { command: process.execPath, args: [...agentPrefix, "update"] } },
+    { name: "/login", description: "Connect a model provider in Terminal.", kind: "native", spawn: { command: process.execPath, args: [...agentPrefix, "/login"], requiresTty: true } },
+    { name: "/model", description: "Open the searchable model selector.", kind: "native", spawn: { command: process.execPath, args: [...agentPrefix, "/model"], requiresTty: true } },
+    { name: "/terminal", description: "Start the terminal agent in this workspace and stream its output.", kind: "native", spawn: { command: process.execPath, args: [...agentPrefix], requiresTty: true } },
+    { name: "/config", description: "Show agent configuration.", kind: "native", spawn: { command: process.execPath, args: [...agentPrefix, "config"], requiresTty: true } },
+    { name: "/list", description: "List installed agent packages.", kind: "native", spawn: { command: process.execPath, args: [...agentPrefix, "list"], requiresTty: true } },
+    { name: "/update", description: "Update agent packages.", kind: "native", spawn: { command: process.execPath, args: [...agentPrefix, "update"], requiresTty: true } },
 ];
 // A local client whose send buffer has grown past this is behind on reads (slow
 // network, background tab); used by both broadcast paths below.
@@ -5309,9 +5310,6 @@ function stripAnsi(text) {
         .replace(/\r\n/g, "\n")
         .replace(/\r/g, "\n");
 }
-function wrapWithSystemPty(spawnCommand, args) {
-    return { command: pythonCommand, args: [ptyRunnerScript, spawnCommand, ...args] };
-}
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -5433,18 +5431,20 @@ function runNativeCommand(command) {
         throw new Error(`Command ${command.name} is not executable`);
     const runId = `cmd-${Date.now()}`;
     broadcast({ type: "command.started", runId, command: command.name });
-    const wrapped = wrapWithSystemPty(command.spawn.command, command.spawn.args);
-    const child = spawn(wrapped.command, wrapped.args, {
-        cwd: repoRoot,
-        env: {
-            ...process.env,
-            PI_CODING_AGENT_DIR: piDir,
-            BIVY_WORKSPACE: active?.workspace ?? defaultWorkspace,
-            TERM: "xterm-256color",
-            FORCE_COLOR: "0",
-            NO_COLOR: "1",
-        },
-    });
+    const env = {
+        ...process.env,
+        PI_CODING_AGENT_DIR: piDir,
+        BIVY_WORKSPACE: active?.workspace ?? defaultWorkspace,
+        TERM: "xterm-256color",
+        FORCE_COLOR: "0",
+        NO_COLOR: "1",
+    };
+    // Native commands (login/model/config/etc.) need a TTY for prompts and the
+    // terminal UI. Everything else uses ordinary pipes: this avoids an extra
+    // Python process and PTY relay for non-interactive commands while preserving
+    // the old behavior for commands that genuinely require terminal semantics.
+    const launch = commandLaunch(command.spawn.command, command.spawn.args, command.spawn.requiresTty, pythonCommand, ptyRunnerScript);
+    const child = spawn(launch.command, launch.args, { cwd: repoRoot, env });
     commandProcesses.set(runId, child);
     child.stdout.on("data", (data) => {
         broadcast({ type: "command.output", runId, command: command.name, stream: "stdout", text: stripAnsi(String(data)) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.5.1-staging.71",
+  "version": "0.5.1-staging.73",
   "type": "module",
   "license": "FSL-1.1-ALv2",
   "description": "Run coding agents on machines you own. Source-available, self-hostable agent workspace.",