@hheei/pi-subagents 0.1.2 → 0.2.3

package/dist/bridge-client.js

@@ -0,0 +1,453 @@
+import { randomUUID } from "node:crypto";
+import { createConnection } from "node:net";
+import { errorMessage } from "@hheei/pi-ext-core";
+import { PROTOCOL_VERSION } from "./domain.js";
+import { attachJsonLineReader, JsonLineError, serializeJsonLine, writeJsonLine, } from "./json-lines.js";
+import { BridgeError, CHILD_INPUT_EVENT, DEFAULT_MAX_BUFFERED_EVENTS, DEFAULT_MAX_FRAME_BYTES, failureResponse, isHelloAckFrame, isRequestFrame, isResponseFrame, successResponse, } from "./protocol.js";
+/** How long a child waits before dialing the parent again. */
+const DEFAULT_RECONNECT_DELAY_MS = 500;
+/** A socket the parent accepts but never answers on is not a working control channel. */
+const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+/**
+ * How long a delivered report waits for the parent's answer before it fails. Without this a parent
+ * that keeps the socket open and never answers would hold the report queue forever.
+ */
+const DEFAULT_REPORT_TIMEOUT_MS = 30_000;
+/**
+ * The child side of the bridge: one long-lived connection to the parent, carrying both directions
+ * of control.
+ *
+ * The child therefore never owns its own lifecycle endpoint: it dials the parent, keeps dialing
+ * while the parent is away, and reconnects with the same identity when the parent comes back (a
+ * parent restart re-listens the same socket path). Reports the parent has not accepted yet are
+ * buffered here, bounded, and flushed in order after a reconnect, so a report is never silently
+ * lost just because the parent was momentarily gone. Pi events are advisory snapshots and are
+ * dropped instead of buffered.
+ */
+export class ChildBridgeClient {
+    #options;
+    #queued = [];
+    #inFlight = new Map();
+    #disconnectWaiters = new Set();
+    #socket;
+    /** The socket of a handshake in progress, so close() can end it too. */
+    #handshakeSocket;
+    /** Identifies this client instance, so request ids stay unique across child relaunches. */
+    #instanceId = randomUUID().slice(0, 8);
+    #detachReader;
+    #requestSeq = 0;
+    #connected = false;
+    #closed = false;
+    #flushing = false;
+    #loop;
+    constructor(options) {
+        this.#options = options;
+    }
+    get connected() {
+        return this.#connected;
+    }
+    /**
+     * Starts the connect loop. It keeps retrying on its own: a panel child outlives the parent
+     * process that started it, so being unable to reach the parent is a state to wait out, not a
+     * failure to give up on. Call `close()` to stop it.
+     */
+    start() {
+        if (this.#loop !== undefined || this.#closed)
+            return;
+        this.#loop = this.#run();
+    }
+    /** Sends an advisory frame: Pi events and child lifecycle signals. */
+    sendEvent(event) {
+        const socket = this.#socket;
+        if (socket === undefined || !this.#connected)
+            return;
+        let encoded;
+        try {
+            encoded = serializeJsonLine({ version: PROTOCOL_VERSION, type: "event", event }, this.#frameLimit());
+        }
+        catch (error) {
+            // The frame can never be sent — too large, or not serializable — and that says nothing about
+            // the connection. An advisory event is dropped so the control channel stays usable.
+            if (process.env.DEBUG || process.env.PI_SUBAGENTS_DEBUG) {
+                this.#diagnose(`dropped an advisory frame: ${errorMessage(error)}`);
+            }
+            return;
+        }
+        socket.write(encoded, (error) => {
+            // A write failure is the connection's problem: the reconnect loop owns it from here.
+            if (error)
+                this.#teardown(socket);
+        });
+    }
+    /**
+     * Tells the parent that input arrived, with its source and nothing else. The parent uses this
+     * to cancel an idle countdown, so the text of a human message stays inside the child.
+     */
+    sendChildInput(source) {
+        const { parentSessionId, subagentId, runtimeIdentity } = this.#options.identity;
+        this.sendEvent({
+            type: CHILD_INPUT_EVENT,
+            parentSessionId,
+            childId: subagentId,
+            runtimeIdentity,
+            source,
+        });
+    }
+    /**
+     * Reports to the parent, waiting for its answer. While the parent is unreachable the report is
+     * buffered instead of failed, and delivered after the reconnect.
+     */
+    sendReport(operation, payload, signal) {
+        if (this.#closed) {
+            return Promise.reject(new BridgeError("bridge_closed", "The child bridge is closed"));
+        }
+        let delivery;
+        const delivered = new Promise((resolve, reject) => {
+            const limit = this.#options.maxBufferedReports ?? DEFAULT_MAX_BUFFERED_EVENTS;
+            while (this.#queued.length >= limit) {
+                // The report being delivered is still the head of the queue: evicting it would fail the
+                // caller with "dropped" while the parent may already be acting on it.
+                const index = this.#inFlight.size === 0 ? 0 : 1;
+                const dropped = this.#queued.splice(index, 1)[0];
+                if (dropped === undefined)
+                    break;
+                this.#diagnose(`dropped a buffered ${dropped.operation} report: the buffer is full`);
+                dropped.reject(new BridgeError("report_buffer_full", `The ${dropped.operation} report was dropped: the parent is unreachable and the buffer is full`));
+            }
+            delivery = {
+                id: `child-${this.#instanceId}-${++this.#requestSeq}`,
+                operation,
+                payload,
+                resolve,
+                reject,
+                requeued: false,
+            };
+            this.#queued.push(delivery);
+            void this.#flush();
+        });
+        if (signal === undefined)
+            return delivered;
+        // The caller is a tool call that can be cancelled. Without this the report would wait for the
+        // parent to come back, and a cancelled call would hang until the process ends.
+        if (signal.aborted) {
+            this.#abandon(delivery);
+            return Promise.reject(new BridgeError("aborted", `The ${operation} report was cancelled`));
+        }
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                this.#abandon(delivery);
+                reject(new BridgeError("aborted", `The ${operation} report was cancelled`));
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            void delivered.then((value) => {
+                signal.removeEventListener("abort", onAbort);
+                resolve(value);
+            }, (error) => {
+                signal.removeEventListener("abort", onAbort);
+                reject(error instanceof Error ? error : new Error(errorMessage(error)));
+            });
+        });
+    }
+    /**
+     * Gives up on a report whose caller was cancelled: it leaves the queue instead of being delivered
+     * later, because the request it carried belongs to a tool call that no longer exists.
+     */
+    #abandon(delivery) {
+        const index = this.#queued.indexOf(delivery);
+        if (index >= 0)
+            this.#queued.splice(index, 1);
+        const inFlight = this.#inFlight.get(delivery.id);
+        if (inFlight !== undefined) {
+            clearTimeout(inFlight.timer);
+            this.#inFlight.delete(delivery.id);
+        }
+        delivery.reject(new BridgeError("aborted", `The ${delivery.operation} report was cancelled`));
+    }
+    /** Stops reconnecting and fails everything still waiting for the parent. */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        const socket = this.#socket ?? this.#handshakeSocket;
+        this.#socket = undefined;
+        this.#handshakeSocket = undefined;
+        this.#connected = false;
+        this.#detachReader?.();
+        this.#detachReader = undefined;
+        // `destroySoon` ends the socket after what is already written has gone out, so a lifecycle
+        // notice reported just before the close is not dropped with the socket.
+        socket?.destroySoon();
+        const error = new BridgeError("bridge_closed", "The child bridge is closed");
+        for (const inFlight of this.#inFlight.values()) {
+            clearTimeout(inFlight.timer);
+            inFlight.reject(error);
+        }
+        this.#inFlight.clear();
+        for (const delivery of this.#queued.splice(0)) {
+            delivery.reject(error);
+        }
+        this.#wakeDisconnectWaiters();
+    }
+    async #run() {
+        while (!this.#closed) {
+            const opened = await this.#attemptOpen();
+            if (this.#closed)
+                return;
+            if (opened)
+                await this.#waitForDisconnect();
+            if (this.#closed)
+                return;
+            await this.#delay();
+        }
+    }
+    /** Dials the parent and completes the handshake; false means "try again later". */
+    async #attemptOpen() {
+        const socket = createConnection(this.#options.endpoint);
+        this.#handshakeSocket = socket;
+        let handshaked = false;
+        try {
+            await new Promise((resolve, reject) => {
+                let settled = false;
+                const settle = (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    if (error === undefined)
+                        resolve();
+                    else
+                        reject(error);
+                };
+                const timer = setTimeout(() => settle(new BridgeError("connect_timeout", "The parent did not answer the hello")), this.#options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS);
+                socket.on("error", (error) => settle(error));
+                socket.on("close", () => settle(new BridgeError("connection_lost", "The parent closed the bridge socket")));
+                socket.once("connect", () => {
+                    void writeJsonLine(socket, {
+                        version: PROTOCOL_VERSION,
+                        type: "hello",
+                        role: "child",
+                        ...this.#options.identity,
+                        token: this.#options.identity.token,
+                    }, this.#frameLimit()).catch((error) => settle(new Error(errorMessage(error))));
+                });
+                this.#detachReader = attachJsonLineReader(socket, {
+                    maxFrameBytes: this.#frameLimit(),
+                    onError: (error) => {
+                        if (!handshaked) {
+                            settle(error);
+                            return;
+                        }
+                        // A frame the reader cannot parse means this socket can never deliver a response, so
+                        // it is dropped like any other lost connection instead of staying "connected" and mute.
+                        this.#teardown(socket);
+                    },
+                    onValue: (value) => {
+                        if (!handshaked) {
+                            if (!isHelloAckFrame(value)) {
+                                settle(new BridgeError("invalid_handshake", "The parent sent an invalid handshake response"));
+                                return;
+                            }
+                            handshaked = true;
+                            settle();
+                            return;
+                        }
+                        this.#receive(value);
+                    },
+                });
+            });
+        }
+        catch {
+            this.#detachReader?.();
+            this.#detachReader = undefined;
+            if (this.#handshakeSocket === socket)
+                this.#handshakeSocket = undefined;
+            socket.destroy();
+            return false;
+        }
+        if (this.#handshakeSocket === socket)
+            this.#handshakeSocket = undefined;
+        if (this.#closed || socket.destroyed) {
+            socket.destroy();
+            return false;
+        }
+        this.#socket = socket;
+        this.#connected = true;
+        socket.on("close", () => this.#teardown(socket));
+        socket.on("error", () => this.#teardown(socket));
+        void this.#flush();
+        return true;
+    }
+    #receive(value) {
+        if (isResponseFrame(value)) {
+            const inFlight = this.#inFlight.get(value.id);
+            if (inFlight === undefined)
+                return;
+            this.#inFlight.delete(value.id);
+            clearTimeout(inFlight.timer);
+            if (value.ok)
+                inFlight.resolve(value.data);
+            else
+                inFlight.reject(new BridgeError(value.error.code, value.error.message));
+            return;
+        }
+        if (isRequestFrame(value)) {
+            void this.#serve(value.id, value.operation, value.payload);
+            return;
+        }
+        this.#diagnose("ignored a frame the child bridge does not understand");
+    }
+    async #serve(id, operation, payload) {
+        try {
+            const data = await this.#options.handleRequest({ operation, payload });
+            this.#send(successResponse(id, data), id);
+        }
+        catch (error) {
+            const code = error instanceof BridgeError ? error.code : "bridge_error";
+            this.#send(failureResponse(id, code, errorMessage(error)));
+        }
+    }
+    /** Delivers queued reports in order, one at a time, so the parent sees them as they happened. */
+    async #flush() {
+        if (this.#flushing)
+            return;
+        this.#flushing = true;
+        try {
+            while (!this.#closed) {
+                const delivery = this.#queued[0];
+                const socket = this.#socket;
+                if (delivery === undefined || socket === undefined || !this.#connected)
+                    return;
+                let value;
+                try {
+                    value = await this.#deliver(socket, delivery);
+                }
+                catch (error) {
+                    // A dropped connection leaves the report at the head of the queue, marked for retry;
+                    // only a report the parent actually answered (or a closed bridge) stops being retried.
+                    if (delivery.requeued)
+                        return;
+                    if (this.#queued[0] === delivery)
+                        this.#queued.shift();
+                    delivery.reject(error instanceof Error ? error : new Error(errorMessage(error)));
+                    continue;
+                }
+                if (this.#queued[0] === delivery)
+                    this.#queued.shift();
+                delivery.resolve(value);
+            }
+        }
+        finally {
+            this.#flushing = false;
+        }
+    }
+    async #deliver(socket, delivery) {
+        delivery.requeued = false;
+        let encoded;
+        try {
+            encoded = serializeJsonLine({
+                version: PROTOCOL_VERSION,
+                type: "request",
+                id: delivery.id,
+                operation: delivery.operation,
+                ...(delivery.payload === undefined ? {} : { payload: delivery.payload }),
+            }, this.#frameLimit());
+        }
+        catch (error) {
+            // The frame itself cannot be sent — too large, or not serializable — so retrying it on every
+            // reconnect would never succeed. Only writing it is a connection problem.
+            throw error instanceof JsonLineError
+                ? new BridgeError(error.code, error.message)
+                : new BridgeError("unserializable_frame", errorMessage(error));
+        }
+        return await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const inFlight = this.#inFlight.get(delivery.id);
+                if (inFlight === undefined)
+                    return;
+                this.#inFlight.delete(delivery.id);
+                reject(new BridgeError("timeout", `The parent did not answer the ${delivery.operation} report in time`));
+            }, this.#options.reportTimeoutMs ?? DEFAULT_REPORT_TIMEOUT_MS);
+            this.#inFlight.set(delivery.id, { delivery, resolve, reject, timer });
+            socket.write(encoded, (error) => {
+                if (!error)
+                    return;
+                // A transport failure is the connection's problem: the teardown path requeues this report
+                // and reconnects, so a report is not lost to a momentary write error.
+                this.#teardown(socket);
+            });
+        });
+    }
+    #send(frame, responseId) {
+        const socket = this.#socket;
+        if (socket === undefined || !this.#connected)
+            return;
+        void writeJsonLine(socket, frame, this.#frameLimit()).catch((error) => {
+            if (responseId === undefined) {
+                this.#teardown(socket);
+                return;
+            }
+            // A response the parent cannot receive must not take the control channel down with it: it
+            // gets a visible failure instead, and the connection stays usable.
+            this.#diagnose(`could not answer request ${responseId}: ${errorMessage(error)}`);
+            void writeJsonLine(socket, failureResponse(responseId, "response_too_large", errorMessage(error)), this.#frameLimit()).catch(() => {
+                this.#teardown(socket);
+            });
+        });
+    }
+    #teardown(socket) {
+        if (this.#closed)
+            return;
+        if (this.#socket !== undefined && this.#socket !== socket) {
+            socket.destroy();
+            return;
+        }
+        this.#socket = undefined;
+        this.#connected = false;
+        this.#detachReader?.();
+        this.#detachReader = undefined;
+        if (!socket.destroyed)
+            socket.destroy();
+        for (const [id, inFlight] of this.#inFlight) {
+            this.#inFlight.delete(id);
+            clearTimeout(inFlight.timer);
+            // The parent never answered, so this report still owes it a delivery. It is already the head
+            // of the queue (a report leaves that position only once it is answered), so it is marked for
+            // the retry and not pushed again: a duplicate would report contact_parent twice.
+            inFlight.delivery.requeued = true;
+            inFlight.reject(new BridgeError("connection_lost", "The parent bridge connection was lost"));
+        }
+        this.#wakeDisconnectWaiters();
+    }
+    /** Wakes every reconnect wait; the next loop registers its own. */
+    #wakeDisconnectWaiters() {
+        const waiters = [...this.#disconnectWaiters];
+        this.#disconnectWaiters.clear();
+        for (const waiter of waiters) {
+            waiter();
+        }
+    }
+    #waitForDisconnect() {
+        // The socket may already have dropped between the handshake and this call.
+        if (!this.#connected)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.#disconnectWaiters.add(resolve);
+        });
+    }
+    #delay() {
+        const delayMs = this.#options.reconnectDelayMs ?? DEFAULT_RECONNECT_DELAY_MS;
+        return new Promise((resolve) => {
+            setTimeout(resolve, delayMs);
+        });
+    }
+    #frameLimit() {
+        return this.#options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES;
+    }
+    #diagnose(message) {
+        if (this.#options.diagnose !== undefined)
+            this.#options.diagnose(message);
+        else if (process.env.DEBUG || process.env.PI_SUBAGENTS_DEBUG) {
+            console.error(`pi-subagents child bridge: ${message}`);
+        }
+    }
+}

package/dist/bridge-server.d.ts

@@ -0,0 +1,72 @@
+import { type HelloFrame } from "./protocol.js";
+/** How long the parent waits for a child's answer before failing the call visibly. */
+export declare const DEFAULT_CHILD_REQUEST_TIMEOUT_MS = 30000;
+export interface ChildRequest {
+    readonly childId: string;
+    readonly runtimeIdentity: string;
+    readonly operation: string;
+    readonly payload: unknown;
+}
+export interface ChildBridgeServerOptions {
+    /** Socket path this parent session owns; children connect here. */
+    readonly endpoint: string;
+    /** The parent session served here; a hello naming another session is refused. */
+    readonly parentSessionId: string;
+    /**
+     * Verifies the child's hello — its runtime token, and whatever else the parent needs to believe
+     * it (for example that this runtime is the one the registry records for this child). Returns a
+     * message to refuse the connection, or undefined to accept it.
+     */
+    readonly authorize: (frame: HelloFrame) => string | undefined | Promise<string | undefined>;
+    /**
+     * Child-initiated requests the parent answers: reports and task results.
+     */
+    readonly handleRequest: (request: ChildRequest) => Promise<unknown>;
+    readonly requestTimeoutMs?: number;
+    readonly maxFrameBytes?: number;
+    readonly maxPendingRequests?: number;
+    readonly diagnose?: (message: string) => void;
+}
+export interface ChildRequestOptions {
+    readonly timeoutMs?: number;
+}
+/**
+ * The parent side of the child bridge: one Unix socket per parent session, one long-lived
+ * connection per child, carrying both directions of control.
+ *
+ * Control lives in the parent process instead of a helper process, so a child presented in a host
+ * panel and a child running headless are driven by exactly the same requests. A child that
+ * reconnects (parent restart, extension reload, dropped socket) replaces its previous connection
+ * and is otherwise treated as the same runtime.
+ */
+export declare class ChildBridgeServer {
+    #private;
+    constructor(options: ChildBridgeServerOptions);
+    get endpoint(): string;
+    /** Binds the endpoint, refusing one that another live bridge server still owns. */
+    listen(): Promise<void>;
+    isConnected(childId: string): boolean;
+    connectedChildren(): string[];
+    /** Sends a request to a connected child and waits for its answer. */
+    request(childId: string, operation: string, payload?: unknown, options?: ChildRequestOptions): Promise<unknown>;
+    /**
+     * Waits for a child's bridge to come up. A child that survived a parent restart reconnects on
+     * its own schedule, so adoption is a bounded wait rather than a spawn.
+     */
+    waitForConnection(childId: string, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<boolean>;
+    /**
+     * Ends a child's connection from this side. The parent uses it when the process stopped being the
+     * child: leaving the socket open would let a relaunch mistake the old connection for the new
+     * runtime and send into a session the parent no longer owns.
+     */
+    disconnect(childId: string): void;
+    /** Subscribes to the fire-and-forget frames a child pushes: Pi events, lifecycle, input. */
+    onEvent(listener: (childId: string, event: unknown) => void): () => void;
+    /** Subscribes to connection transitions; a reconnect is what tells the parent a child is alive. */
+    onConnectionChange(listener: (childId: string, connected: boolean) => void): () => void;
+    /** Closes every connection and removes the socket this server created. */
+    close(): Promise<void>;
+}