@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/dist/pi-intercom/bridge-rpc-process.js

@@ -0,0 +1,264 @@
+import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+import { trySignalChildTree } from "../shared/post-exit-stdio-guard.js";
+import { isRecord } from "../shared/unknown.js";
+import { Fault, log, wait } from "./bridge-protocol.js";
+const FRAME_LIMIT = 4 * 1024 * 1024;
+function launchEnvironment(packageRoot) {
+    const environment = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("PI_SUBAGENT_")));
+    return { ...environment, PI_PACKAGE_DIR: packageRoot };
+}
+// Native RpcClient lacks public EOF/exit/UI control and retains/reprints unbounded stderr.
+// This owner implements only get_state and dialog cancellation, never a remote RPC proxy.
+export class RpcProcess {
+    child;
+    exited;
+    status = "starting";
+    failure;
+    decoder = new StringDecoder("utf8");
+    buffer = "";
+    discarding = false;
+    sequence = 0;
+    pending;
+    stopping;
+    stderrBytes = 0;
+    exitObserved = false;
+    constructor(policy, cwd, sessionFile) {
+        this.child = spawn(process.execPath, this.arguments(policy, sessionFile), {
+            cwd,
+            detached: true,
+            env: launchEnvironment(policy.packageRoot),
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.exited = new Promise((resolveExit) => {
+            this.child.once("close", (code, signal) => {
+                this.exitObserved = true;
+                this.buffer = "";
+                this.discarding = false;
+                this.status = "exited";
+                this.fail(new Fault(503, "session_exited", "Launched Pi process exited."));
+                log("launch_exit", { pid: this.child.pid, code, signal, stderrBytes: this.stderrBytes });
+                resolveExit();
+            });
+        });
+        this.child.once("error", () => this.fail(new Fault(503, "launch_failed", "Pi process could not start.")));
+        this.child.stdin.on("error", () => {
+            this.fail(new Fault(503, "rpc_closed", "Pi RPC input closed."));
+            this.cleanup();
+        });
+        this.child.stdout.once("end", () => {
+            this.fail(new Fault(503, "rpc_closed", "Pi RPC output closed."));
+            this.cleanup();
+        });
+        for (const stream of [this.child.stdout, this.child.stderr]) {
+            stream.on("error", () => {
+                this.fail(new Fault(503, "rpc_closed", "Pi RPC output failed."));
+                this.cleanup();
+            });
+        }
+        this.child.stdout.on("data", (chunk) => this.read(this.decoder.write(chunk)));
+        this.child.stderr.on("data", (chunk) => {
+            // Drain without retaining or exposing diagnostics, including credential-bearing extension errors.
+            this.stderrBytes = Math.min(Number.MAX_SAFE_INTEGER, this.stderrBytes + chunk.length);
+        });
+    }
+    get pid() {
+        return this.child.pid;
+    }
+    arguments(policy, sessionFile) {
+        const args = [
+            policy.cli,
+            "--mode",
+            "rpc",
+            "--session",
+            sessionFile,
+            "--provider",
+            policy.provider,
+            "--model",
+            policy.model,
+            policy.trustProject ? "--approve" : "--no-approve",
+        ];
+        if (!policy.discoverResources) {
+            args.push("--no-extensions", "--no-skills", "--no-prompt-templates", "--no-themes", "--no-context-files");
+        }
+        if (policy.offline) {
+            args.push("--offline");
+        }
+        for (const extension of policy.extensions) {
+            args.push("--extension", extension);
+        }
+        return args;
+    }
+    fail(error) {
+        this.failure ??= error;
+        this.pending?.reject(this.failure);
+        this.pending = undefined;
+    }
+    retainedChunk(chunk) {
+        if (!this.discarding) {
+            return chunk;
+        }
+        const end = chunk.indexOf("\n");
+        if (end < 0) {
+            return "";
+        }
+        this.discarding = false;
+        return chunk.slice(end + 1);
+    }
+    read(chunk) {
+        this.buffer += this.retainedChunk(chunk);
+        let newline = this.buffer.indexOf("\n");
+        while (newline >= 0) {
+            const line = this.buffer.slice(0, newline);
+            this.buffer = this.buffer.slice(newline + 1);
+            if (Buffer.byteLength(line) > FRAME_LIMIT) {
+                this.oversize(line);
+            }
+            else {
+                this.record(line);
+            }
+            newline = this.buffer.indexOf("\n");
+        }
+        if (Buffer.byteLength(this.buffer) > FRAME_LIMIT) {
+            this.discarding = this.oversize(this.buffer);
+            this.buffer = "";
+        }
+    }
+    oversize(prefix) {
+        // Native event serializers put the discriminant first; responses may put their request ID first.
+        // ponytail: drain large native data events through LF; use token streaming if producer headers change.
+        const header = /^\{"type":"([a-z_]+)"[,}]/.exec(prefix.slice(0, 256));
+        const event = header?.[1];
+        if (event !== undefined &&
+            !["response", "extension_ui_request", "agent_start", "agent_settled"].includes(event)) {
+            log("rpc_event_discarded", { pid: this.pid, result: "oversized" });
+            return true;
+        }
+        this.protocolFailure();
+        return false;
+    }
+    protocolFailure() {
+        this.fail(new Fault(503, "rpc_invalid", "Pi RPC output violated its bounded JSONL contract."));
+        this.cleanup();
+    }
+    record(line) {
+        let data;
+        try {
+            data = JSON.parse(line);
+        }
+        catch {
+            this.protocolFailure();
+            return;
+        }
+        if (!isRecord(data)) {
+            this.protocolFailure();
+            return;
+        }
+        if (data.type === "response" && data.id === this.pending?.id) {
+            this.response(data);
+        }
+        else if (data.type === "extension_ui_request") {
+            this.dialog(data);
+        }
+        else if (!this.failure) {
+            this.event(data.type);
+        }
+    }
+    event(type) {
+        if (type === "agent_start") {
+            this.status = "running";
+        }
+        else if (type === "agent_settled") {
+            this.status = "idle";
+        }
+    }
+    response(data) {
+        const pending = this.pending;
+        this.pending = undefined;
+        if (data.success === true && data.command === "get_state" && isRecord(data.data)) {
+            pending?.resolve(data.data);
+        }
+        else {
+            pending?.reject(new Fault(503, "rpc_failed", "Pi RPC state request failed."));
+        }
+    }
+    dialog(data) {
+        if (typeof data.method !== "string" ||
+            !["confirm", "select", "input", "editor"].includes(data.method)) {
+            return;
+        }
+        if (typeof data.id === "string") {
+            this.write({ type: "extension_ui_response", id: data.id, cancelled: true });
+        }
+        this.fail(new Fault(409, "interaction_required", "Pi requested unsupported interactive input; dialog cancelled and session stopped."));
+        this.cleanup();
+    }
+    write(command) {
+        // Only one bounded state request can be in flight; no arbitrary input or growing write queue.
+        if (!this.child.stdin.write(`${JSON.stringify(command)}\n`)) {
+            this.fail(new Fault(503, "rpc_backpressure", "Pi RPC input is not being consumed."));
+            this.cleanup();
+        }
+    }
+    async state(signal) {
+        if (this.failure) {
+            throw this.failure;
+        }
+        const id = `state-${++this.sequence}`;
+        const result = new Promise((resolve, reject) => {
+            this.pending = { id, resolve, reject };
+            this.write({ type: "get_state", id });
+        });
+        try {
+            return await wait(result, signal);
+        }
+        finally {
+            this.pending = undefined;
+        }
+    }
+    ready() {
+        if (this.failure || this.exitObserved) {
+            throw this.failure ?? new Fault(503, "session_exited", "Pi exited during startup.");
+        }
+        if (this.status === "starting") {
+            this.status = "idle";
+        }
+    }
+    cleanup() {
+        this.stop().catch(() => log("launch_cleanup", { pid: this.child.pid, result: "failed" }));
+    }
+    stop() {
+        if (this.exitObserved) {
+            return this.exited;
+        }
+        this.stopping ??= this.shutdown().finally(() => {
+            this.stopping = undefined;
+        });
+        return this.stopping;
+    }
+    async shutdown() {
+        if (this.exitObserved) {
+            return;
+        }
+        this.status = "stopping";
+        this.fail(new Fault(410, "session_stopped", "Launched session is stopping."));
+        this.child.stdin.end();
+        const terminate = setTimeout(() => {
+            trySignalChildTree(this.child, "SIGTERM");
+        }, 1000);
+        const kill = setTimeout(() => {
+            trySignalChildTree(this.child, "SIGKILL");
+        }, 3000);
+        const deadline = AbortSignal.timeout(8000);
+        try {
+            await wait(this.exited, deadline);
+        }
+        catch {
+            throw new Fault(503, "stop_timeout", "Launched Pi did not close within the cleanup deadline; inspect sessions before retrying.");
+        }
+        finally {
+            clearTimeout(terminate);
+            clearTimeout(kill);
+        }
+    }
+}

package/dist/pi-intercom/bridge-session.js

@@ -0,0 +1,420 @@
+import { randomUUID } from "node:crypto";
+import { IntercomClient } from "./broker/client.js";
+import { formatSessionTarget, resolveSessionProjectId, resolveSessionTarget, } from "./session-targets.js";
+import { Fault, INBOX_BYTES, INBOX_COUNT, cancelled, log, wait } from "./bridge-protocol.js";
+import { WaitingAsk } from "./bridge-ask.js";
+const MAX_REQUESTS = 8;
+const IDLE_TIMEOUT = 5 * 60 * 1000;
+const SEND_TIMEOUT = 8000;
+const LIST_TIMEOUT = 5000;
+export class Session {
+    generation = randomUUID();
+    identity;
+    owner;
+    expires;
+    client = new IntercomClient({
+        sendTimeoutMs: SEND_TIMEOUT,
+        listTimeoutMs: LIST_TIMEOUT,
+    });
+    requests = new Set();
+    inbox = new Map();
+    inboxBytes = 0;
+    pending;
+    closed = false;
+    connecting;
+    disconnecting;
+    retirement;
+    lease;
+    closeReason = new Fault(503, "broker_unavailable", "Broker connection failed.");
+    constructor(owner, identity, expires) {
+        this.owner = owner;
+        this.identity = identity;
+        this.expires = expires;
+        this.client.on("error", () => this.close(new Fault(503, "broker_unavailable", "Broker connection failed.")));
+        this.client.on("disconnected", () => this.close(new Fault(503, "broker_disconnected", "Broker disconnected.")));
+        this.client.on("_registered", () => {
+            // Socket acquisition is not abortable: retire a cancelled generation before any application write.
+            if (this.closed) {
+                this.disconnect().catch((error) => this.cleanupFailed(error));
+            }
+        });
+        this.client.on("message", (from, message) => this.receive(from, message));
+        this.client.on("session_left", (id) => this.peerLeft(id));
+        this.touch();
+    }
+    guard(signal) {
+        if (signal) {
+            cancelled(signal);
+        }
+        if (this.closed) {
+            throw this.closeReason;
+        }
+        if (!this.owner.allowed(this.identity)) {
+            throw new Fault(403, "revoked", "Identity is no longer authorized.");
+        }
+        if (this.expires <= Date.now()) {
+            const error = new Fault(403, "certificate_expired", "Client certificate expired.");
+            this.close(error);
+            throw error;
+        }
+    }
+    touch() {
+        clearTimeout(this.lease);
+        this.lease = setTimeout(() => this.close(this.expires <= Date.now()
+            ? new Fault(403, "certificate_expired", "Client certificate expired.")
+            : new Fault(410, "lease_expired", "Bridge session idle lease expired.")), Math.max(1, Math.min(IDLE_TIMEOUT, this.expires - Date.now())));
+    }
+    begin() {
+        this.guard();
+        if (this.requests.size >= MAX_REQUESTS) {
+            throw new Fault(429, "too_many_requests", "Too many concurrent requests for this identity.");
+        }
+        const controller = new AbortController();
+        this.requests.add(controller);
+        this.touch();
+        return controller;
+    }
+    end(controller) {
+        this.requests.delete(controller);
+    }
+    fields() {
+        return { name: this.identity.name, fingerprint: this.identity.fingerprint256 };
+    }
+    async establish() {
+        const projectId = await resolveSessionProjectId(this.identity.cwd);
+        this.guard();
+        const id = `remote-${this.identity.fingerprint256.toLowerCase()}`;
+        await this.client.connect({
+            name: this.identity.name,
+            cwd: this.identity.cwd,
+            model: "remote-bridge",
+            projectId,
+            status: "idle",
+            acceptsAsks: true,
+            pendingAsks: 0,
+        }, id);
+        if (this.closed) {
+            await this.disconnect();
+            return;
+        }
+        if (this.client.sessionId !== id) {
+            const fault = new Fault(409, "identity_in_use", "This remote identity is already registered by another connection.");
+            this.close(fault);
+            throw fault;
+        }
+        log("registered", this.fields());
+    }
+    async connect(signal) {
+        this.guard(signal);
+        this.connecting ??= this.establish().catch((error) => {
+            if (!this.closed) {
+                this.close(error instanceof Fault
+                    ? error
+                    : new Fault(503, "broker_unavailable", "Local broker is unavailable; bridge does not start it."));
+            }
+            throw error;
+        });
+        await wait(this.connecting, signal);
+        this.guard(signal);
+    }
+    disconnect() {
+        this.disconnecting ??= this.client.disconnect().finally(() => {
+            this.disconnecting = undefined;
+        });
+        return this.disconnecting;
+    }
+    cleanupFailed(_error) {
+        // Never log caught broker details or remove an unsuccessfully retired generation.
+        log("session_cleanup", { ...this.fields(), result: "failed" });
+    }
+    async retire() {
+        await this.disconnect();
+        try {
+            await this.connecting;
+        }
+        catch {
+            // The original request receives the connection failure; teardown must still close a late socket.
+        }
+        await this.disconnect();
+        this.owner.retired(this.identity.fingerprint256, this.generation);
+        log("session_closed", { ...this.fields(), result: this.closeReason.code });
+    }
+    close(error) {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.closeReason = error;
+        clearTimeout(this.lease);
+        this.pending?.reject(error);
+        for (const controller of this.requests) {
+            controller.abort(error);
+        }
+        this.owner.lost(this.identity.fingerprint256, this.inbox.size);
+        this.inbox.clear();
+        this.inboxBytes = 0;
+        // Retain the generation until acquisition/registration AND final disconnect settle.
+        this.startRetirement();
+    }
+    startRetirement() {
+        this.retirement = this.retire().catch((caught) => this.cleanupFailed(caught));
+    }
+    async settled() {
+        await this.retirement;
+    }
+    peerLeft(id) {
+        if (this.pending?.peer === id && !this.pending.settled) {
+            this.pending.reject(new Fault(409, "peer_offline", "Ask recipient disconnected.", { id: this.pending.id }));
+        }
+        for (const [messageId, entry] of this.inbox) {
+            if (entry.from.id === id && entry.message.expectsReply === true) {
+                this.remove(messageId);
+                this.owner.lost(this.identity.fingerprint256);
+            }
+        }
+        this.presence();
+    }
+    receive(from, message) {
+        if (this.closed) {
+            return;
+        }
+        try {
+            this.guard();
+        }
+        catch (error) {
+            this.close(error instanceof Fault
+                ? error
+                : new Fault(403, "revoked", "Identity is no longer authorized."));
+            return;
+        }
+        log("received", { ...this.fields(), peer: from.id, messageId: message.id, result: "received" });
+        const pending = this.pending;
+        if (pending?.matches(from.id, message.replyTo) === true) {
+            pending.resolve({ from, message });
+            return;
+        }
+        if (this.inbox.has(message.id)) {
+            this.owner.lost(this.identity.fingerprint256);
+            return;
+        }
+        const bytes = Buffer.byteLength(JSON.stringify({ from, message }));
+        if (this.inbox.size >= INBOX_COUNT || this.inboxBytes + bytes > INBOX_BYTES) {
+            this.owner.lost(this.identity.fingerprint256);
+            log("inbox_overflow", {
+                ...this.fields(),
+                peer: from.id,
+                messageId: message.id,
+                result: "lost",
+            });
+            return;
+        }
+        // ponytail: bounded volatile inbox; use a private durable journal if restart/lease-loss recovery is required.
+        this.inbox.set(message.id, { from, message, bytes, replying: false });
+        this.inboxBytes += bytes;
+        this.presence();
+    }
+    remove(id) {
+        const entry = this.inbox.get(id);
+        if (entry) {
+            this.inboxBytes -= entry.bytes;
+            this.inbox.delete(id);
+        }
+    }
+    presence() {
+        if (this.closed) {
+            return;
+        }
+        const pendingAsks = [...this.inbox.values()].filter((entry) => entry.message.expectsReply === true).length;
+        this.client.updatePresence({
+            pendingAsks,
+            acceptsAsks: this.inbox.size < INBOX_COUNT && this.inboxBytes < INBOX_BYTES,
+        });
+    }
+    async peers(signal) {
+        this.guard(signal);
+        let peers;
+        try {
+            peers = await wait(this.client.listSessions(), signal);
+        }
+        catch (error) {
+            cancelled(signal);
+            if (error instanceof Error && error.message === "List sessions timeout") {
+                throw new Fault(504, "list_timeout", "Broker session list deadline exceeded.");
+            }
+            throw new Fault(503, "broker_unavailable", "Broker session list failed.");
+        }
+        this.guard(signal);
+        return peers;
+    }
+    async connectedPeers(signal) {
+        await this.connect(signal);
+        return this.peers(signal);
+    }
+    async target(to, signal) {
+        const resolution = resolveSessionTarget(await this.peers(signal), to);
+        if (resolution.status === "none") {
+            throw new Fault(404, "peer_offline", "Peer is not connected.");
+        }
+        if (resolution.status !== "found" || !resolution.target) {
+            throw new Fault(409, "ambiguous_target", "Use an unambiguous peer name or session ID (prefixes need at least 8 characters).");
+        }
+        if (resolution.target.id === this.client.sessionId) {
+            throw new Fault(400, "self_target", "Choose another peer.");
+        }
+        return resolution.target;
+    }
+    async send(peer, message, context, options = {}) {
+        const { signal, requestId } = context;
+        context.onPeer(peer);
+        this.guard(signal);
+        const id = options.messageId ?? randomUUID();
+        log("send", { ...this.fields(), requestId, peer, messageId: id, result: "attempt" });
+        let result;
+        try {
+            result = await wait(this.client.send(peer, { text: message, delivery: "steer", ...options, messageId: id }), signal);
+        }
+        catch {
+            cancelled(signal);
+            const fault = new Fault(504, "send_unconfirmed", "Broker acknowledgement was not received; delivery is unknown. Do not automatically retry.", { id, deliveryUnknown: true });
+            this.close(fault);
+            throw fault;
+        }
+        this.guard(signal);
+        log("send_result", {
+            ...this.fields(),
+            requestId,
+            peer,
+            messageId: id,
+            result: result.accepted ? "accepted" : "rejected",
+        });
+        if (!result.accepted) {
+            throw new Fault(409, "delivery_failed", result.reason ?? "Broker rejected delivery.", {
+                id,
+                accepted: false,
+                delivered: false,
+            });
+        }
+        return result;
+    }
+    async ask(operation, context) {
+        if (this.pending) {
+            throw new Fault(409, "ask_in_progress", "Only one concurrent ask is allowed per identity.");
+        }
+        const waiting = new WaitingAsk();
+        this.pending = waiting;
+        const { signal } = context;
+        const abort = () => {
+            try {
+                cancelled(signal);
+            }
+            catch (error) {
+                waiting.reject(error instanceof Error
+                    ? error
+                    : new Fault(499, "client_aborted", "HTTP client disconnected; delivery may be unknown."));
+            }
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        try {
+            await this.connect(signal);
+            const peer = await this.target(operation.to, signal);
+            this.guard(signal);
+            waiting.peer = peer.id;
+            waiting.deadline(operation.timeoutMs, (error) => this.close(error));
+            waiting.receipt = await this.send(peer.id, operation.message, context, {
+                messageId: waiting.id,
+                expectsReply: true,
+            });
+            const answer = await wait(waiting.reply, signal);
+            this.guard(signal);
+            return { ...waiting.receipt, replied: true, reply: answer };
+        }
+        finally {
+            waiting.clear();
+            signal.removeEventListener("abort", abort);
+            if (this.pending === waiting) {
+                this.pending = undefined;
+            }
+        }
+    }
+    ack(ids) {
+        const acked = [];
+        const retained = [];
+        for (const id of ids) {
+            const entry = this.inbox.get(id);
+            if (entry?.message.expectsReply === true) {
+                retained.push(id);
+            }
+            else if (entry) {
+                this.remove(id);
+                acked.push(id);
+            }
+        }
+        this.presence();
+        return { acked, retained };
+    }
+    async answer(replyTo, message, context) {
+        const entry = this.inbox.get(replyTo);
+        if (entry?.message.expectsReply !== true) {
+            throw new Fault(404, "unknown_ask", "replyTo must identify an unanswered inbound ask.");
+        }
+        if (entry.replying) {
+            throw new Fault(409, "reply_in_progress", "This ask already has a reply in flight.");
+        }
+        entry.replying = true;
+        const peer = entry.from.id;
+        context.onPeer(peer);
+        try {
+            const peers = await this.peers(context.signal);
+            if (!peers.some((candidate) => candidate.id === peer)) {
+                throw new Fault(409, "peer_offline", "Original ask sender is disconnected.");
+            }
+            this.guard(context.signal);
+            if (this.inbox.get(replyTo) !== entry) {
+                throw new Fault(409, "ask_retired", "Inbound ask is no longer replyable.");
+            }
+            const data = { ...(await this.send(peer, message, context, { replyTo })) };
+            this.remove(replyTo);
+            this.presence();
+            return data;
+        }
+        finally {
+            entry.replying = false;
+        }
+    }
+    async execute(operation, context) {
+        this.guard(context.signal);
+        if (operation.route === "POST /v1/ask") {
+            return this.ask(operation, context);
+        }
+        await this.connect(context.signal);
+        switch (operation.route) {
+            case "POST /v1/register":
+                return { sessionId: this.client.sessionId, name: this.identity.name };
+            case "GET /v1/list": {
+                const sessions = await this.peers(context.signal);
+                return {
+                    sessionId: this.client.sessionId,
+                    sessions: sessions.map(({ topics: _topics, subscriptions: _subscriptions, ...entry }) => {
+                        return Object.assign(entry, { target: formatSessionTarget(entry, sessions) });
+                    }),
+                };
+            }
+            case "GET /v1/inbox": {
+                const lostMessages = this.owner.losses(this.identity.fingerprint256);
+                return {
+                    messages: [...this.inbox.values()].map(({ from, message }) => ({ from, message })),
+                    overflow: lostMessages > 0,
+                    lostMessages,
+                };
+            }
+            case "POST /v1/ack":
+                return this.ack(operation.ids);
+            case "POST /v1/send":
+                return {
+                    ...(await this.send((await this.target(operation.to, context.signal)).id, operation.message, context)),
+                };
+            case "POST /v1/reply":
+                return this.answer(operation.replyTo, operation.message, context);
+        }
+    }
+}