@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/runtime/remote.js

@@ -0,0 +1,541 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+/**
+ * Remote runtime adapter — the daemon-side half of Stage 1
+ * (docs/agent-node-decoupling.md). `RemoteRuntimeSession implements
+ * RuntimeSession` but owns no child process: it speaks the RPC protocol
+ * (src/runtime/rpc-protocol.ts) to an agent service that hosts the real runtime
+ * in another process. Because it satisfies the same `RuntimeSession` interface,
+ * server.ts's ~40 `openSessions` call sites are untouched — the seam is
+ * `RuntimeHost.get()` returning a `RemoteRuntime` instead of an in-process one.
+ *
+ * Two design points make this a faithful drop-in:
+ *  - The synchronous accessors the daemon reads (getMessages/getName/
+ *    getCurrentModel/isStreaming/sessionFile/activePid/…) cannot round-trip, so
+ *    they read a LOCAL MIRROR the service keeps current via snapshot deltas that
+ *    ride each event. The mutated fields land on the SAME frame as `agent_end`,
+ *    so the mirror is correct at the boundary the daemon's post-turn logic reads
+ *    (usage refresh, worktree diff, PR detection) — matching process.ts timing.
+ *  - The tool interceptor (the guardian/QuestionManager hook) stays on the
+ *    daemon. The service asks the daemon to adjudicate each tool via a reverse
+ *    RPC (`intercept`), so AskUserQuestion is answered by the daemon exactly as
+ *    in-process and no `user_question` event ever crosses this link.
+ *
+ * The concrete socket transport lives here too, but the session/runtime take an
+ * injected `RpcTransport`, so they unit-test against a fake (see the tests).
+ */
+import { EventEmitter } from "node:events";
+import net from "node:net";
+import { RPC_PROTOCOL_VERSION, FrameDecoder, encodeFrame, } from "./rpc-protocol.js";
+/** A RuntimeSession backed by an agent service over an RpcTransport. */
+export class RemoteRuntimeSession {
+    id;
+    cwd;
+    emitter = new EventEmitter();
+    transport;
+    toolInterceptor;
+    toolProvider;
+    onDispose;
+    nextId = 1;
+    pending = new Map();
+    /** In-flight interceptor calls, so abort() can settle a blocked question card. */
+    interceptAborts = new Map();
+    disposed = false;
+    // ---- Mirror of the synchronous RuntimeSession state ----------------------
+    _sessionFile;
+    _isStreaming;
+    _name;
+    _currentModel;
+    _activePid;
+    _thinkingLevel;
+    _messages;
+    _supportsThinking;
+    _availableThinkingLevels;
+    _commands;
+    constructor(transport, snapshot, options = {}) {
+        this.transport = transport;
+        this.toolInterceptor = options.toolInterceptor;
+        this.toolProvider = options.toolProvider;
+        this.onDispose = options.onDispose;
+        this.id = snapshot.sessionId;
+        this.cwd = snapshot.cwd;
+        this._sessionFile = snapshot.sessionFile ?? undefined;
+        this._isStreaming = snapshot.isStreaming;
+        this._name = snapshot.name ?? undefined;
+        this._currentModel = snapshot.currentModel ?? undefined;
+        this._activePid = snapshot.activePid ?? undefined;
+        this._thinkingLevel = snapshot.thinkingLevel ?? undefined;
+        this._messages = snapshot.messages ?? [];
+        this._supportsThinking = snapshot.supportsThinking;
+        this._availableThinkingLevels = snapshot.availableThinkingLevels ?? [];
+        this._commands = snapshot.commands ?? [];
+    }
+    // ---- Inbound wiring (driven by the transport owner) -----------------------
+    /** Apply one service→daemon message. Public so the connector can route it. */
+    handleMessage(message) {
+        switch (message.t) {
+            case "event":
+                if (message.snapshot)
+                    this.applySnapshot(message.snapshot);
+                this.emitter.emit("event", message.event);
+                return;
+            case "state":
+                this.applySnapshot(message.snapshot);
+                return;
+            case "res": {
+                const entry = this.pending.get(message.id);
+                if (!entry)
+                    return;
+                this.pending.delete(message.id);
+                if (message.ok) {
+                    if (message.snapshot)
+                        this.applySnapshot(message.snapshot);
+                    entry.resolve(message.value);
+                }
+                else {
+                    entry.reject(new Error(message.error));
+                }
+                return;
+            }
+            case "intercept":
+                void this.handleIntercept(message.id, message.ctx);
+                return;
+            case "tool-invoke":
+                void this.handleToolInvoke(message.id, message.toolName, message.toolCallId, message.params);
+                return;
+            case "started":
+                // Late/duplicate handshake reply — the connector already consumed it.
+                return;
+        }
+    }
+    /** Called when the underlying link closes. Fails a live turn cleanly. */
+    handleClose(err) {
+        if (this.disposed)
+            return;
+        const error = err ?? new Error("agent service connection closed");
+        for (const { reject } of this.pending.values())
+            reject(error);
+        this.pending.clear();
+        for (const controller of this.interceptAborts.values())
+            controller.abort();
+        this.interceptAborts.clear();
+        // If a turn was live, surface an error + close it so the daemon's busy
+        // tracking and post-turn logic don't hang waiting for an agent_end.
+        if (this._isStreaming) {
+            this._isStreaming = false;
+            this._activePid = undefined;
+            this.emitter.emit("event", { type: "session.error", error: error.message });
+            this.emitter.emit("event", { type: "agent_end", code: null, signal: null, disconnected: true });
+        }
+    }
+    applySnapshot(s) {
+        if (s.isStreaming !== undefined)
+            this._isStreaming = s.isStreaming;
+        if (s.sessionFile !== undefined)
+            this._sessionFile = s.sessionFile ?? undefined;
+        if (s.name !== undefined)
+            this._name = s.name ?? undefined;
+        if (s.currentModel !== undefined)
+            this._currentModel = s.currentModel ?? undefined;
+        if (s.activePid !== undefined)
+            this._activePid = s.activePid ?? undefined;
+        if (s.thinkingLevel !== undefined)
+            this._thinkingLevel = s.thinkingLevel ?? undefined;
+        if (s.messages !== undefined)
+            this._messages = s.messages;
+    }
+    async handleIntercept(id, ctx) {
+        const controller = new AbortController();
+        this.interceptAborts.set(id, controller);
+        let decision = {};
+        try {
+            if (this.toolInterceptor) {
+                const call = { sessionId: ctx.sessionId, toolName: ctx.toolName, input: ctx.input, signal: controller.signal };
+                decision = (await this.toolInterceptor(call)) || {};
+            }
+        }
+        catch (error) {
+            decision = { block: true, reason: error instanceof Error ? error.message : String(error) };
+        }
+        finally {
+            this.interceptAborts.delete(id);
+        }
+        if (!this.disposed)
+            this.transport.send({ t: "intercept-res", id, decision });
+    }
+    /**
+     * Execute a node-hosted tool the remote agent invoked (reverse RPC). The tool
+     * runs HERE on the daemon via the injected ToolProvider — where its credentials
+     * live — and the result goes back to the service, which hands it to the agent.
+     */
+    async handleToolInvoke(id, toolName, toolCallId, params) {
+        let result;
+        try {
+            result = this.toolProvider
+                ? await this.toolProvider.invoke(toolName, toolCallId, params)
+                : { content: [{ type: "text", text: `No tool provider for ${toolName}` }], isError: true };
+        }
+        catch (error) {
+            result = { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true };
+        }
+        if (!this.disposed)
+            this.transport.send({ t: "tool-invoke-res", id, result });
+    }
+    // ---- Request/response helpers --------------------------------------------
+    request(method, args) {
+        if (this.disposed)
+            return Promise.reject(new Error("session disposed"));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: resolve, reject });
+            this.transport.send({ t: "req", id, method, args });
+        });
+    }
+    notify(method, args) {
+        if (this.disposed && method !== "dispose")
+            return;
+        this.transport.send({ t: "notify", method, args });
+    }
+    // ---- RuntimeSession: streaming state --------------------------------------
+    get sessionFile() {
+        return this._sessionFile;
+    }
+    get isStreaming() {
+        return this._isStreaming;
+    }
+    activePid() {
+        return this._activePid;
+    }
+    getMessages() {
+        return this._messages;
+    }
+    subscribe(listener) {
+        this.emitter.on("event", listener);
+        return () => this.emitter.off("event", listener);
+    }
+    // ---- RuntimeSession: turn control -----------------------------------------
+    async prompt(text, options) {
+        await this.request("prompt", [text, options ?? {}]);
+    }
+    async abort() {
+        // Settle any question card blocking on the interceptor before the round-trip.
+        for (const controller of this.interceptAborts.values())
+            controller.abort();
+        await this.request("abort", []);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        // Send the `dispose` notify BEFORE closing so the agent service reaps the
+        // child (rather than detaching it). If the link is already gone the session
+        // was detached earlier, so there is nothing local left to reap.
+        try {
+            this.notify("dispose", []);
+        }
+        catch {
+            // best-effort
+        }
+        this.teardownLocal("session disposed");
+    }
+    /**
+     * Drop this local handle WITHOUT reaping the remote session (Stage 2). No
+     * `dispose` notify is sent, so the agent service sees only the transport close
+     * and DETACHES — keeping the child alive so another handle (this daemon later,
+     * or another daemon) can re-attach via RemoteRuntime.attachSession. Used when
+     * the daemon evicts a session from its local cache without ending it.
+     */
+    detach() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.teardownLocal("session detached");
+    }
+    teardownLocal(reason) {
+        for (const { reject } of this.pending.values())
+            reject(new Error(reason));
+        this.pending.clear();
+        for (const controller of this.interceptAborts.values())
+            controller.abort();
+        this.interceptAborts.clear();
+        this.emitter.removeAllListeners();
+        try {
+            this.transport.close();
+        }
+        catch {
+            // best-effort
+        }
+        this.onDispose?.();
+    }
+    // ---- RuntimeSession: models -----------------------------------------------
+    async getModels() {
+        return (await this.request("getModels", [])) ?? [];
+    }
+    getCurrentModel() {
+        return this._currentModel;
+    }
+    async setModel(provider, id) {
+        // The `res` snapshot carries the new currentModel, applied by handleMessage.
+        await this.request("setModel", [provider, id]);
+    }
+    async getAllModels() {
+        return (await this.request("getAllModels", [])) ?? [];
+    }
+    // ---- RuntimeSession: thinking ---------------------------------------------
+    getThinkingLevel() {
+        return this._thinkingLevel;
+    }
+    setThinkingLevel(level) {
+        // Optimistically mirror so the daemon reads it back immediately, then notify.
+        this._thinkingLevel = this._availableThinkingLevels.includes(level.trim()) ? level.trim() : undefined;
+        this.notify("setThinkingLevel", [level]);
+    }
+    getAvailableThinkingLevels() {
+        return this._availableThinkingLevels;
+    }
+    supportsThinking() {
+        return this._supportsThinking;
+    }
+    // ---- RuntimeSession: naming -----------------------------------------------
+    getName() {
+        return this._name;
+    }
+    setName(name) {
+        this._name = name;
+        this.notify("setName", [name]);
+    }
+    async suggestName(firstPrompt) {
+        return this.request("suggestName", [firstPrompt]);
+    }
+    // ---- RuntimeSession: misc capabilities ------------------------------------
+    async interactiveTuiCommand() {
+        return (await this.request("interactiveTuiCommand", [])) ?? null;
+    }
+    async getUsage() {
+        return this.request("getUsage", []);
+    }
+    getCommands() {
+        return this._commands;
+    }
+    async invokeCommand(name, args) {
+        await this.request("invokeCommand", [name, args]);
+    }
+}
+/**
+ * Drive the `start` handshake on a fresh transport and return a live session.
+ * Buffers any events the service emits between `started` and the session being
+ * wired, then replays them, so the first streamed frames are never dropped.
+ */
+export async function startRemoteSession(transport, params, options = {}) {
+    const startId = 1;
+    const buffered = [];
+    // Held in an object so the closures below can read it before the (single) late
+    // assignment once the handshake resolves.
+    const state = {};
+    let settle;
+    let fail;
+    const ready = new Promise((resolve, reject) => {
+        settle = resolve;
+        fail = reject;
+    });
+    transport.onMessage((message) => {
+        if (state.session) {
+            state.session.handleMessage(message);
+            return;
+        }
+        if (message.t === "started" && message.id === startId) {
+            settle?.(message.snapshot);
+            return;
+        }
+        if (message.t === "res" && message.id === startId && message.ok === false) {
+            fail?.(new Error(message.error));
+            return;
+        }
+        buffered.push(message);
+    });
+    transport.onClose((err) => {
+        if (state.session)
+            state.session.handleClose(err);
+        else
+            fail?.(err ?? new Error("agent service connection closed during start"));
+    });
+    transport.send({
+        t: "start",
+        id: startId,
+        protocol: RPC_PROTOCOL_VERSION,
+        runtime: params.runtime,
+        sandbox: params.sandbox,
+        op: params.op,
+        options: params.options,
+    });
+    const snapshot = await ready;
+    const session = new RemoteRuntimeSession(transport, snapshot, options);
+    state.session = session;
+    for (const message of buffered)
+        session.handleMessage(message);
+    return { session, warning: snapshot.warning };
+}
+/** Parse a remote-runtime address into `net.connect` options. */
+export function parseRemoteAddress(raw) {
+    const value = raw.trim();
+    if (value.startsWith("unix:"))
+        return { path: value.slice("unix:".length) };
+    if (value.startsWith("/") || value.startsWith("./"))
+        return { path: value };
+    const lastColon = value.lastIndexOf(":");
+    if (lastColon >= 0) {
+        const host = value.slice(0, lastColon) || "127.0.0.1";
+        const port = Number(value.slice(lastColon + 1));
+        if (Number.isInteger(port) && port > 0)
+            return { host, port };
+    }
+    const port = Number(value);
+    if (Number.isInteger(port) && port > 0)
+        return { host: "127.0.0.1", port };
+    throw new Error(`Invalid remote runtime address: ${raw}`);
+}
+/** Connect a real socket transport to the agent service. */
+export function connectSocketTransport(raw) {
+    const opts = parseRemoteAddress(raw);
+    return new Promise((resolve, reject) => {
+        const socket = net.connect(opts);
+        const decoder = new FrameDecoder();
+        let messageHandler;
+        let closeHandler;
+        let settled = false;
+        let closeErr;
+        socket.once("connect", () => {
+            settled = true;
+            resolve({
+                send(message) {
+                    socket.write(encodeFrame(message));
+                },
+                onMessage(handler) {
+                    messageHandler = handler;
+                },
+                onClose(handler) {
+                    closeHandler = handler;
+                    if (closeErr)
+                        handler(closeErr);
+                },
+                close() {
+                    // Graceful FIN so any just-written frame (notably the `dispose` notify,
+                    // which the service must see to REAP rather than detach) flushes first.
+                    // Fall back to a hard destroy if the peer doesn't close promptly.
+                    try {
+                        socket.end();
+                        setTimeout(() => socket.destroy(), 1000).unref();
+                    }
+                    catch {
+                        socket.destroy();
+                    }
+                },
+            });
+        });
+        socket.on("data", (chunk) => {
+            let messages;
+            try {
+                messages = decoder.push(chunk);
+            }
+            catch (error) {
+                socket.destroy(error instanceof Error ? error : new Error(String(error)));
+                return;
+            }
+            if (messageHandler)
+                for (const message of messages)
+                    messageHandler(message);
+        });
+        socket.on("error", (error) => {
+            if (!settled) {
+                settled = true;
+                reject(error);
+                return;
+            }
+            closeErr = error;
+        });
+        socket.on("close", () => {
+            if (closeHandler)
+                closeHandler(closeErr);
+        });
+    });
+}
+/**
+ * `AgentRuntime` facade the daemon holds in place of an in-process runtime. Each
+ * createSession/openSession opens its OWN transport to the agent service (one
+ * connection per session), which makes the service's lifecycle bookkeeping and
+ * child ownership per-session and unambiguous.
+ */
+export class RemoteRuntime {
+    config;
+    id;
+    displayName;
+    capabilities;
+    /** The agent-service address this runtime drives (for Stage 2 advertise/route). */
+    agentServiceAddress;
+    constructor(config) {
+        this.config = config;
+        this.id = config.targetRuntime;
+        this.displayName = config.displayName;
+        this.capabilities = config.capabilities;
+        this.agentServiceAddress = config.agentServiceAddress;
+    }
+    async createSession(options) {
+        const transport = await this.config.connect();
+        const toolSpecs = options.toolProvider?.list();
+        return startRemoteSession(transport, { runtime: this.id, sandbox: this.config.sandbox, op: "create", options: { workspace: options.workspace, hasToolInterceptor: Boolean(options.toolInterceptor), ...(toolSpecs?.length ? { toolSpecs } : {}) } }, { toolInterceptor: options.toolInterceptor, toolProvider: options.toolProvider });
+    }
+    async openSession(options) {
+        const transport = await this.config.connect();
+        const toolSpecs = options.toolProvider?.list();
+        return startRemoteSession(transport, { runtime: this.id, sandbox: this.config.sandbox, op: "open", options: { workspace: options.workspace, sessionFile: options.sessionFile, hasToolInterceptor: Boolean(options.toolInterceptor), ...(toolSpecs?.length ? { toolSpecs } : {}) } }, { toolInterceptor: options.toolInterceptor, toolProvider: options.toolProvider });
+    }
+    /**
+     * Re-attach to a session already live on the agent service (Stage 2 routing).
+     * The agent service keeps a session running after a daemon disconnect (the
+     * "detach & keep running" policy), so ANY daemon that knows the session's
+     * agent-service address can rebind to the same live child via the Stage 1
+     * `attach` op — no in-process handle required. The daemon re-supplies its tool
+     * interceptor so the guardian keeps adjudicating every tool after the hand-off.
+     */
+    async attachSession(sessionId, options = {}) {
+        const transport = await this.config.connect();
+        const toolSpecs = options.toolProvider?.list();
+        return startRemoteSession(transport, { runtime: this.id, sandbox: this.config.sandbox, op: "attach", options: { sessionId, hasToolInterceptor: Boolean(options.toolInterceptor), ...(toolSpecs?.length ? { toolSpecs } : {}) } }, { toolInterceptor: options.toolInterceptor, toolProvider: options.toolProvider });
+    }
+    async listSessions() {
+        return (await this.runtimeCall("listSessions", [])) ?? [];
+    }
+    async deleteSession(sessionId, sessionFile) {
+        return (await this.runtimeCall("deleteSession", [sessionId, sessionFile])) ?? false;
+    }
+    /** Session-less runtime-level RPC on a short-lived connection. */
+    async runtimeCall(method, args) {
+        const transport = await this.config.connect();
+        return new Promise((resolve, reject) => {
+            const id = 1;
+            let done = false;
+            const finish = (fn) => {
+                if (done)
+                    return;
+                done = true;
+                try {
+                    transport.close();
+                }
+                catch {
+                    // ignore
+                }
+                fn();
+            };
+            transport.onMessage((message) => {
+                if (message.t === "res" && message.id === id) {
+                    if (message.ok)
+                        finish(() => resolve(message.value));
+                    else
+                        finish(() => reject(new Error(message.error)));
+                }
+            });
+            transport.onClose((err) => finish(() => (err ? reject(err) : resolve(undefined))));
+            transport.send({ t: "rt", id, protocol: RPC_PROTOCOL_VERSION, runtime: this.id, sandbox: this.config.sandbox, method, args });
+        });
+    }
+}

package/dist/runtime/rpc-protocol.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+/**
+ * Protocol version. Bump on any breaking change to the message shapes below.
+ * The handshake (`start`) carries it so a daemon and service that disagree fail
+ * loudly at connect time instead of misparsing frames mid-session.
+ */
+export const RPC_PROTOCOL_VERSION = 1;
+/** 4-byte big-endian length prefix; guards against a hostile/buggy peer. */
+export const FRAME_HEADER_BYTES = 4;
+/** Hard cap on a single decoded frame. Generous — a big diff/file read fits. */
+export const MAX_RPC_FRAME_BYTES = 64 * 1024 * 1024;
+// ---------------------------------------------------------------------------
+// Framing codec
+// ---------------------------------------------------------------------------
+/** Encode one message as a length-prefixed JSON frame. */
+export function encodeFrame(message) {
+    const json = Buffer.from(JSON.stringify(message), "utf8");
+    if (json.length > MAX_RPC_FRAME_BYTES) {
+        throw new Error(`RPC frame too large: ${json.length} > ${MAX_RPC_FRAME_BYTES}`);
+    }
+    const header = Buffer.allocUnsafe(FRAME_HEADER_BYTES);
+    header.writeUInt32BE(json.length, 0);
+    return Buffer.concat([header, json]);
+}
+/**
+ * Streaming decoder: feed it socket chunks, get back complete messages. Buffers
+ * partial frames across chunk boundaries. Throws on a frame that exceeds the cap
+ * (a corrupt/hostile length prefix) so the caller can drop the connection rather
+ * than allocate unbounded memory.
+ */
+export class FrameDecoder {
+    buf = Buffer.alloc(0);
+    push(chunk) {
+        this.buf = this.buf.length ? Buffer.concat([this.buf, chunk]) : chunk;
+        const out = [];
+        for (;;) {
+            if (this.buf.length < FRAME_HEADER_BYTES)
+                break;
+            const len = this.buf.readUInt32BE(0);
+            if (len > MAX_RPC_FRAME_BYTES) {
+                throw new Error(`RPC frame too large: ${len} > ${MAX_RPC_FRAME_BYTES}`);
+            }
+            if (this.buf.length < FRAME_HEADER_BYTES + len)
+                break;
+            const body = this.buf.subarray(FRAME_HEADER_BYTES, FRAME_HEADER_BYTES + len);
+            out.push(JSON.parse(body.toString("utf8")));
+            this.buf = this.buf.subarray(FRAME_HEADER_BYTES + len);
+        }
+        return out;
+    }
+    /** Bytes currently buffered awaiting a complete frame (test/introspection). */
+    get pending() {
+        return this.buf.length;
+    }
+}