@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/runtime/process.js

@@ -0,0 +1,499 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { stripAnsi } from "./ansi.js";
+import { buildAgentCredentialEnv } from "./credentials.js";
+import { egressEnv } from "../harness/egress.js";
+import { depCacheEnv } from "../harness/dep-cache.js";
+/**
+ * Send `signal` to `child`'s whole process group when possible, so a forking CLI
+ * agent's grandchildren (it shells out to git/npm/build tools, or forks its own
+ * worker processes) die with it instead of being orphaned. Relies on the child
+ * having been spawned `detached` (making it its own process-group leader, POSIX
+ * only — see the spawn() call in ProcessSession.prompt); `process.kill(-pid,
+ * signal)` then targets the whole group, mirroring `pty-runner.py`'s
+ * `os.killpg`. Falls back to killing just the direct child on Windows (no
+ * negative-pid group kill there) or if the group is already gone.
+ */
+function killProcessGroup(child, signal) {
+    const pid = child.pid;
+    if (pid && process.platform !== "win32") {
+        try {
+            process.kill(-pid, signal);
+            return;
+        }
+        catch {
+            // No such process group (already exited) or we're not its leader — fall
+            // through to a direct kill of the child itself.
+        }
+    }
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // Already exited.
+    }
+}
+function splitArgs(value) {
+    if (!value?.trim())
+        return [];
+    try {
+        const parsed = JSON.parse(value);
+        if (Array.isArray(parsed))
+            return parsed.map(String);
+    }
+    catch {
+        // fall through to a small shell-like splitter
+    }
+    const out = [];
+    const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    let match;
+    while ((match = re.exec(value)))
+        out.push(match[1] ?? match[2] ?? match[3] ?? "");
+    return out;
+}
+/**
+ * Generic resume primitive for the escape-hatch CLI runtime: `BIVY_AGENT_RESUME_
+ * TEMPLATE` (a JSON arg array with an `{id}` placeholder for the agent's own
+ * session ref) opts a hand-configured agent into the same data-driven resume path
+ * the built-in CLI agents get from `CLI_AGENT_SPECS[id].resume` (see
+ * src/runtime/index.ts) — purely as operator config, no code. Absent = a fresh
+ * process per prompt, same as any other unconfigured CLI agent.
+ */
+function genericResumeTemplateFromEnv() {
+    const raw = process.env.BIVY_AGENT_RESUME_TEMPLATE?.trim();
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed) && parsed.length)
+            return parsed.map(String);
+    }
+    catch {
+        // malformed override — resume stays off
+    }
+    return undefined;
+}
+export function processRuntimeFromEnv() {
+    const command = process.env.BIVY_AGENT_COMMAND?.trim();
+    if (!command)
+        return null;
+    const resumeTemplate = genericResumeTemplateFromEnv();
+    return {
+        id: process.env.BIVY_AGENT_ID?.trim() || "generic-cli",
+        displayName: process.env.BIVY_AGENT_NAME?.trim() || "Generic CLI Agent",
+        command,
+        args: splitArgs(process.env.BIVY_AGENT_ARGS),
+        promptMode: process.env.BIVY_AGENT_PROMPT_MODE === "argv" ? "argv" : "stdin",
+        ...(resumeTemplate
+            ? {
+                resumable: true,
+                resumeArgs: (sessionId) => resumeTemplate.map((a) => a.replace(/\{id\}/g, sessionId)),
+            }
+            : {}),
+    };
+}
+class ProcessSession {
+    runtimeOptions;
+    cwd;
+    /** For a resumed session the id IS the agent's session id (so the daemon's
+     *  session ref round-trips); a fresh session gets a random id. */
+    id;
+    child;
+    messages = [];
+    emitter = new EventEmitter();
+    streaming = false;
+    name;
+    /** Set when this session was opened to resume an existing agent session. */
+    resumeId;
+    constructor(runtimeOptions, cwd, resumeId) {
+        this.runtimeOptions = runtimeOptions;
+        this.cwd = cwd;
+        this.resumeId = resumeId;
+        this.id = resumeId ?? randomUUID();
+        // Preload prior history so a reopened session isn't blank (resumable runtimes).
+        if (resumeId && runtimeOptions.loadHistory) {
+            try {
+                this.messages = runtimeOptions.loadHistory(resumeId);
+            }
+            catch {
+                this.messages = [];
+            }
+        }
+    }
+    /** The resume token handed back to the daemon; the id doubles as the ref. */
+    get sessionFile() {
+        return this.resumeId;
+    }
+    get isStreaming() {
+        return this.streaming;
+    }
+    /** PID of the live agent subprocess for the current turn (see RuntimeSession). */
+    activePid() {
+        return this.child?.pid;
+    }
+    getMessages() {
+        return this.messages;
+    }
+    /** Currently selected model id, or undefined to run on the agent's own default. */
+    currentModelId;
+    /** Provider of the selected model — scopes custom base-URL env injection. */
+    currentModelProvider;
+    /** Currently selected thinking level, or undefined for the agent's own default. */
+    currentThinkingLevel;
+    /** Best-effort usage parsed from the most recent turn (see getUsage). */
+    lastUsage;
+    getModels() {
+        return this.runtimeOptions.model?.models ?? [];
+    }
+    getCurrentModel() {
+        if (!this.currentModelId)
+            return undefined;
+        const known = this.getModels().find((m) => m.id === this.currentModelId);
+        // A free-form id (e.g. an operator-supplied model not in the curated list)
+        // still round-trips so the picker reflects the actual selection.
+        return known ?? { provider: "", id: this.currentModelId, name: this.currentModelId };
+    }
+    async setModel(provider, id) {
+        if (!this.runtimeOptions.model)
+            throw new Error("Model selection is not supported by this runtime.");
+        // Accept any non-empty id (curated or free-form). An empty id clears the
+        // selection so the agent falls back to its own default.
+        this.currentModelId = id.trim() || undefined;
+        this.currentModelProvider = provider?.trim().toLowerCase() || undefined;
+    }
+    // ---- Thinking / reasoning effort (see ProcessThinkingConfig) --------------
+    supportsThinking() {
+        return Boolean(this.runtimeOptions.thinking?.levels.length);
+    }
+    getAvailableThinkingLevels() {
+        return this.runtimeOptions.thinking?.levels ?? [];
+    }
+    getThinkingLevel() {
+        return this.currentThinkingLevel ?? this.runtimeOptions.thinking?.default;
+    }
+    setThinkingLevel(level) {
+        if (!this.runtimeOptions.thinking)
+            return;
+        const next = level.trim();
+        // Only accept advertised levels; anything else (incl. "off"/"") clears it so
+        // the agent runs on its own default reasoning.
+        this.currentThinkingLevel = this.runtimeOptions.thinking.levels.includes(next) ? next : undefined;
+    }
+    // ---- Usage (see ProcessRuntimeOptions.usageReporting) ---------------------
+    async getUsage() {
+        return this.lastUsage;
+    }
+    getName() {
+        return this.name;
+    }
+    setName(name) {
+        this.name = name;
+    }
+    async suggestName() {
+        // The generic CLI "dumb-pipe" runtime has no model of its own to name a
+        // session with. Returning a raw 60-char truncation of the first message here
+        // was actively harmful: it *overrode* the clean first-few-words title (and
+        // branch slug) maybeNameSession() derives deterministically, and it's never
+        // an agent-written title. Return undefined so that deterministic title stands
+        // — and so the node-level LLM namer (server.ts's suggestSessionNameFromNode,
+        // which uses whatever model credentials the node holds) can refine it.
+        return undefined;
+    }
+    subscribe(listener) {
+        this.emitter.on("event", listener);
+        return () => this.emitter.off("event", listener);
+    }
+    emit(event) {
+        this.emitter.emit("event", event);
+    }
+    async prompt(text, _options) {
+        if (this.streaming)
+            throw new Error("Agent is already running.");
+        const prompt = text.trim();
+        if (!prompt)
+            return;
+        this.messages.push({ role: "user", content: prompt, timestamp: Date.now() });
+        this.streaming = true;
+        this.emit({ type: "agent_start" });
+        this.emit({ type: "turn_start" });
+        // A resumed session continues the agent's own session id each turn via
+        // resumeArgs (e.g. `codex exec resume <id> --json`); otherwise the base args.
+        const baseArgs = this.resumeId && this.runtimeOptions.resumeArgs
+            ? this.runtimeOptions.resumeArgs(this.resumeId)
+            : (this.runtimeOptions.args ?? []);
+        // Selection flags (model + thinking level) splice into the base args at their
+        // configured positions — before a trailing prompt flag, or after a leading
+        // subcommand. Both `insertAt` values index the ORIGINAL base args, so we apply
+        // them highest-index-first: an earlier splice would otherwise shift the indices
+        // a later one is relative to. No selection = the agent's own default, untouched.
+        const modelConfig = this.runtimeOptions.model;
+        const thinkingConfig = this.runtimeOptions.thinking;
+        const injections = [];
+        if (modelConfig && this.currentModelId)
+            injections.push({ at: modelConfig.insertAt ?? 0, args: modelConfig.modelArgs(this.currentModelId) });
+        // Only inject an *explicitly chosen* level — an untouched session runs on the
+        // agent's own default (which we advertise via getThinkingLevel for display).
+        if (thinkingConfig && this.currentThinkingLevel)
+            injections.push({ at: thinkingConfig.insertAt ?? 0, args: thinkingConfig.thinkingArgs(this.currentThinkingLevel) });
+        let argsWithFlags = baseArgs;
+        for (const { at, args: inject } of injections.sort((a, b) => b.at - a.at)) {
+            const idx = Math.min(Math.max(at, 0), argsWithFlags.length);
+            argsWithFlags = [...argsWithFlags.slice(0, idx), ...inject, ...argsWithFlags.slice(idx)];
+        }
+        const args = this.runtimeOptions.promptMode === "argv" ? [...argsWithFlags, prompt] : argsWithFlags;
+        // Resolve credentials per prompt so freshly-refreshed OAuth tokens (and keys
+        // added after this session started) reach the agent. The vault wins over any
+        // ambient key so Bivy's shared sign-in is authoritative.
+        const credentialEnv = this.runtimeOptions.credentials
+            ? await buildAgentCredentialEnv(this.runtimeOptions.credentials, undefined, this.currentModelProvider).catch(() => ({}))
+            : {};
+        // Optional prepare step (e.g. Codex materializes its auth.json from the vault
+        // and pins CODEX_HOME). Runs after credentials, before preflight/spawn; its
+        // env patch flows into both. Best-effort — failures never block the run.
+        const prepareEnv = this.runtimeOptions.prepare
+            ? (await Promise.resolve(this.runtimeOptions.prepare({ ...process.env, ...this.runtimeOptions.env, ...credentialEnv })).catch(() => undefined)) ?? {}
+            : {};
+        // Credential preflight: if the agent has no usable credential, surface a
+        // clear, actionable error instead of spawning a subprocess that dies with an
+        // opaque upstream 401 (e.g. Codex's "unexpected status 401 Unauthorized:
+        // Missing bearer …" when no OpenAI key/login is present).
+        const preflightError = this.runtimeOptions.preflight?.({ ...process.env, ...this.runtimeOptions.env, ...credentialEnv, ...prepareEnv }, { provider: this.currentModelProvider });
+        if (preflightError) {
+            this.streaming = false;
+            const message = { role: "assistant", content: "", errorMessage: preflightError };
+            this.messages.push(message);
+            this.emit({ type: "message_start", message: { role: "assistant", content: "" } });
+            this.emit({ type: "session.error", error: preflightError });
+            this.emit({ type: "message_end", message });
+            this.emit({ type: "turn_end" });
+            this.emit({ type: "agent_end", code: 1, signal: null });
+            return;
+        }
+        // The agent enforces its own containment via its native sandbox (Codex
+        // --sandbox, Gemini --approval-mode, Claude permissionMode; see
+        // src/harness/sandbox.ts). Bivy no longer wraps the process in an OS jail.
+        const child = spawn(this.runtimeOptions.command, args, {
+            cwd: this.cwd,
+            // egressEnv() routes this agent's outbound traffic through the harness
+            // network broker when BIVY_EGRESS_PROXY is enabled (else it's {}).
+            env: { ...process.env, ...depCacheEnv(), ...this.runtimeOptions.env, ...credentialEnv, ...prepareEnv, ...egressEnv() },
+            stdio: "pipe",
+            // Detached so the child becomes the leader of its own process group
+            // (POSIX) — see killProcessGroup() / abort() below, which kill that whole
+            // group instead of just this direct child. Without this, a forking CLI
+            // agent's grandchildren survive `abort()` as orphans.
+            detached: process.platform !== "win32",
+        });
+        this.child = child;
+        let stdout = "";
+        let stderr = "";
+        let startedMessage = false;
+        // Phase 4 — structured mode: feed each complete stdout line to a CliParser
+        // and emit its normalized events (streaming text, tool cards, transcript)
+        // instead of the raw-stdout blob.
+        const parser = this.runtimeOptions.parserFactory?.();
+        let lineBuf = "";
+        let messagesPushed = false;
+        // Emit a batch of parser events; the moment the turn ends (agent_end), sync
+        // the parser's transcript into this.messages so getMessages() is correct as
+        // soon as agent_end fires — the parser emits agent_end during stdout parsing
+        // (on session.done), before the child 'close' handler runs.
+        const emitParserEvents = (activeParser, events) => {
+            for (const event of events)
+                this.emit(event);
+            if (!messagesPushed && events.some((e) => e.type === "agent_end")) {
+                messagesPushed = true;
+                for (const message of activeParser.messages())
+                    this.messages.push(message);
+                // Capture the turn's best-effort usage so getUsage() is ready by the time
+                // the daemon's agent_end handler (refreshSessionUsage) reads it.
+                const usage = activeParser.usage?.();
+                if (usage)
+                    this.lastUsage = usage;
+            }
+        };
+        const feedParser = (activeParser, text) => {
+            lineBuf += text;
+            let nl;
+            while ((nl = lineBuf.indexOf("\n")) >= 0) {
+                const line = lineBuf.slice(0, nl);
+                lineBuf = lineBuf.slice(nl + 1);
+                emitParserEvents(activeParser, activeParser.onLine(line));
+            }
+        };
+        const update = () => {
+            if (!startedMessage) {
+                startedMessage = true;
+                this.emit({ type: "message_start", message: { role: "assistant", content: "" } });
+            }
+            this.emit({ type: "message_update", message: { role: "assistant", content: stripAnsi(stdout) } });
+        };
+        child.stdout.on("data", (chunk) => {
+            const text = chunk.toString("utf8");
+            stdout += text;
+            if (parser)
+                feedParser(parser, text);
+            else
+                update();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+            this.emit({ type: "tool_execution_update", toolName: "agent_output", toolCallId: "agent-output", input: { stream: "stderr", output: stripAnsi(stderr.slice(-4000)) } });
+        });
+        child.on("error", (error) => {
+            stderr += error.message;
+        });
+        child.on("close", (code, signal) => {
+            this.child = undefined;
+            this.streaming = false;
+            if (parser) {
+                // Flush any trailing partial line, then let the parser close the turn.
+                // The parser owns the full turn lifecycle (message_end/turn_end/
+                // agent_end via onClose/session.done), so we don't emit our own here.
+                // emitParserEvents pushes the transcript on agent_end; if the parser
+                // already finalized mid-stream this close is a no-op for messages.
+                if (lineBuf.trim())
+                    emitParserEvents(parser, parser.onLine(lineBuf));
+                lineBuf = "";
+                emitParserEvents(parser, parser.onClose(code, stderr));
+                if (!messagesPushed)
+                    for (const message of parser.messages())
+                        this.messages.push(message);
+                return;
+            }
+            const failed = code && code !== 0;
+            const content = stripAnsi(stdout.trim() || (failed ? stderr.trim() : ""));
+            const cleanStderr = stripAnsi(stderr.trim());
+            const message = { role: "assistant", content, ...(failed ? { errorMessage: `Process exited with code ${code}${cleanStderr ? `: ${cleanStderr}` : ""}` } : {}) };
+            this.messages.push(message);
+            if (!startedMessage)
+                this.emit({ type: "message_start", message: { role: "assistant", content: "" } });
+            this.emit({ type: "message_end", message });
+            this.emit({ type: "turn_end" });
+            this.emit({ type: "agent_end", code, signal });
+        });
+        if (this.runtimeOptions.promptMode !== "argv") {
+            child.stdin.end(`${prompt}\n`);
+        }
+        else {
+            // Prompt is already in argv. Still close stdin so agents that also read it
+            // (e.g. `codex exec` waits for stdin EOF even with a prompt arg) don't hang
+            // forever waiting for input that will never come.
+            child.stdin.end();
+        }
+    }
+    async abort() {
+        // Capture the live child now — not inside the timer below — so a fast
+        // re-spawn (a new prompt() started after this turn's process has already
+        // exited) can never be caught by the delayed SIGKILL: the timer always
+        // targets *this* turn's process/group, whatever `this.child` points to by
+        // the time it fires.
+        const child = this.child;
+        if (!child)
+            return;
+        killProcessGroup(child, "SIGTERM");
+        setTimeout(() => killProcessGroup(child, "SIGKILL"), 2000).unref();
+    }
+    dispose() {
+        void this.abort();
+        this.emitter.removeAllListeners();
+    }
+}
+export class ProcessRuntime {
+    options;
+    id;
+    displayName;
+    capabilities;
+    sessions = [];
+    constructor(options) {
+        this.options = options;
+        this.id = options.id ?? "generic-cli";
+        this.displayName = options.displayName ?? "Generic CLI Agent";
+        this.capabilities = {
+            toolInterception: false,
+            // Model selection only when a model config with a non-empty list is wired
+            // (e.g. Gemini/Qwen/Aider/OpenCode); otherwise the agent runs on its own
+            // default and the picker must not render a control that no-ops.
+            modelSelection: Boolean(options.model?.models.length),
+            packages: false,
+            // Resume only when the runtime was configured for it (e.g. Codex).
+            resume: Boolean(options.resumable),
+            fork: false,
+            // Usage reporting when a usage-emitting parser is wired (see getUsage).
+            usageReporting: Boolean(options.usageReporting),
+        };
+    }
+    /** Session-less catalog contribution: this CLI agent's configured models, grouped by provider. */
+    listCatalog() {
+        const byProvider = new Map();
+        for (const model of this.options.model?.models ?? []) {
+            const id = model.provider?.trim().toLowerCase();
+            if (!id)
+                continue;
+            let entry = byProvider.get(id);
+            if (!entry) {
+                entry = { id, name: id, models: [] };
+                byProvider.set(id, entry);
+            }
+            entry.models.push(model);
+        }
+        return [...byProvider.values()];
+    }
+    async createSession(options) {
+        const session = new ProcessSession(this.options, options.workspace);
+        this.sessions.push(session);
+        return { session, warning: "Generic CLI runtime streams stdout/stderr only; approvals, model picker, and resume depend on the underlying agent protocol." };
+    }
+    async openSession(options) {
+        // Resumable runtimes bind the agent's session id so each prompt continues it
+        // (see resumeArgs); non-resumable ones ignore the ref and start fresh.
+        if (this.options.resumable) {
+            const session = new ProcessSession(this.options, options.workspace, options.sessionFile);
+            this.sessions.push(session);
+            return { session };
+        }
+        return this.createSession(options);
+    }
+    async listSessions() {
+        return this.sessions.map((session) => ({
+            id: session.id,
+            cwd: session.cwd,
+            name: session.getName(),
+            messageCount: session.getMessages().length,
+        }));
+    }
+    /**
+     * Forget a session on a user-initiated delete. Drops the in-memory handle so
+     * listSessions (which reports the runtime's live sessions) stops returning it,
+     * and — for resume-capable agents that persist transcripts in their own store
+     * (Codex) — removes that on-disk rollout via `deleteHistory` so it can't be
+     * re-surfaced. Returns true if anything was removed.
+     */
+    async deleteSession(sessionId, sessionFile) {
+        let removed = false;
+        for (let i = this.sessions.length - 1; i >= 0; i--) {
+            const s = this.sessions[i];
+            if (s.id === sessionId || (sessionFile && s.sessionFile === sessionFile)) {
+                try {
+                    s.dispose();
+                }
+                catch { /* already torn down by the caller's close */ }
+                this.sessions.splice(i, 1);
+                removed = true;
+            }
+        }
+        if (this.options.deleteHistory) {
+            try {
+                this.options.deleteHistory(sessionId);
+                removed = true;
+            }
+            catch {
+                // Best-effort store cleanup — a missing/locked rollout must not fail the delete.
+            }
+        }
+        return removed;
+    }
+}