@hheei/pi-subagents 0.3.0 → 0.4.0

package/dist/bridge-client.js

@@ -1,459 +0,0 @@
-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));
-        try {
-            this.#options.onConnect?.();
-        }
-        catch (error) {
-            this.#diagnose(`onConnect handler failed: ${errorMessage(error)}`);
-        }
-        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

@@ -1,72 +0,0 @@
-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>;
-}