@hheei/pi-subagents 0.1.2

package/dist/connector.js

@@ -0,0 +1,283 @@
+import { createConnection } from "node:net";
+import { abortError, errorMessage, toError, writeDiagnostic } from "./diagnostics.js";
+import { PROTOCOL_VERSION } from "./domain.js";
+import { attachJsonLineReader, writeJsonLine } from "./json-lines.js";
+import { DEFAULT_MAX_FRAME_BYTES, DEFAULT_MAX_PENDING_REQUESTS, isEventFrame, isHelloAckFrame, isResponseFrame, } from "./protocol.js";
+/** Bounded memory of locally finished request IDs, used to ignore late responses. */
+const MAX_RETIRED_REQUEST_IDS = 256;
+/**
+ * Parent-side client of the runner IPC endpoint.
+ *
+ * The connection is re-connectable by design: `close()` only releases this
+ * parent's local socket and in-flight requests. It never terminates the runner
+ * or the Pi child that the runner owns.
+ */
+export class RunnerConnection {
+    #options;
+    #pending = new Map();
+    #retired = new Set();
+    #eventListeners = new Set();
+    #socket;
+    #detachReader;
+    #nextId = 0;
+    #connectPromise;
+    constructor(options) {
+        this.#options = options;
+    }
+    connect(signal) {
+        if (this.#socket && !this.#socket.destroyed)
+            return Promise.resolve();
+        if (this.#connectPromise !== undefined)
+            return this.#connectPromise;
+        const promise = this.#open(signal);
+        this.#connectPromise = promise;
+        void promise
+            .finally(() => {
+            if (this.#connectPromise === promise)
+                this.#connectPromise = undefined;
+        })
+            .catch(() => undefined);
+        return promise;
+    }
+    get connected() {
+        return this.#socket !== undefined && !this.#socket.destroyed;
+    }
+    request(operation, payload, options = {}) {
+        const socket = this.#socket;
+        if (!socket || socket.destroyed)
+            return Promise.reject(new Error("Runner is not connected"));
+        if (options.signal?.aborted)
+            return Promise.reject(abortError());
+        const limit = this.#options.maxPendingRequests ?? DEFAULT_MAX_PENDING_REQUESTS;
+        if (this.#pending.size >= limit) {
+            return Promise.reject(new Error("Runner pending request limit exceeded"));
+        }
+        const id = `controller-${++this.#nextId}`;
+        // `Promise.withResolvers` needs lib ES2024; this workspace targets ES2022.
+        return new Promise((resolve, reject) => {
+            const settle = (error, value) => {
+                const pending = this.#pending.get(id);
+                if (!pending)
+                    return;
+                this.#pending.delete(id);
+                this.#retire(id);
+                pending.cleanup();
+                if (error)
+                    pending.reject(error);
+                else
+                    pending.resolve(value);
+            };
+            const timeout = setTimeout(() => settle(new Error(`Runner ${operation} request timed out`)), options.timeoutMs ?? this.#options.requestTimeoutMs ?? 30_000);
+            const onAbort = () => settle(abortError());
+            const cleanup = () => {
+                clearTimeout(timeout);
+                options.signal?.removeEventListener("abort", onAbort);
+            };
+            this.#pending.set(id, { resolve, reject, cleanup });
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+            void writeJsonLine(socket, { version: PROTOCOL_VERSION, type: "request", id, operation, payload }, this.#options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES).catch((error) => {
+                settle(toError(error));
+            });
+        });
+    }
+    onEvent(listener) {
+        this.#eventListeners.add(listener);
+        return () => {
+            this.#eventListeners.delete(listener);
+        };
+    }
+    /**
+     * Releases the local socket, reader, listeners and in-flight requests. The
+     * runner keeps running and can be reconnected from the same identity.
+     */
+    close() {
+        const socket = this.#socket;
+        this.#disconnectFor(socket, new Error("Runner connection closed"));
+    }
+    async #open(signal) {
+        if (signal?.aborted)
+            throw abortError();
+        const socket = createConnection(this.#options.endpoint);
+        this.#socket = socket;
+        return new Promise((resolve, reject) => {
+            let handshakeSettled = false;
+            const settleHandshake = (error) => {
+                if (handshakeSettled)
+                    return;
+                handshakeSettled = true;
+                clearTimeout(timeout);
+                signal?.removeEventListener("abort", onAbort);
+                if (error === undefined)
+                    resolve();
+                else {
+                    this.#disconnectFor(socket, error);
+                    reject(error);
+                }
+            };
+            const streamError = (error) => {
+                if (!handshakeSettled)
+                    settleHandshake(error);
+                else if (this.#socket === socket)
+                    this.#disconnectFor(socket, error);
+            };
+            const timeout = setTimeout(() => settleHandshake(new Error("Runner connection timed out")), this.#options.connectTimeoutMs ?? 10_000);
+            const onAbort = () => settleHandshake(abortError());
+            signal?.addEventListener("abort", onAbort, { once: true });
+            socket.on("error", streamError);
+            socket.on("close", () => {
+                streamError(new Error("Runner disconnected"));
+            });
+            const detach = attachJsonLineReader(socket, {
+                maxFrameBytes: this.#options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES,
+                onError: streamError,
+                onValue: (value) => {
+                    if (!handshakeSettled) {
+                        if (!isHelloAckFrame(value)) {
+                            settleHandshake(new Error("Runner sent an invalid handshake response"));
+                            return;
+                        }
+                        settleHandshake();
+                        return;
+                    }
+                    if (this.#socket !== socket)
+                        return;
+                    this.#handleFrame(value);
+                },
+            });
+            this.#detachReader = detach;
+            socket.once("connect", () => {
+                void writeJsonLine(socket, {
+                    version: PROTOCOL_VERSION,
+                    type: "hello",
+                    ...(this.#options.role === undefined ? {} : { role: this.#options.role }),
+                    ...(this.#options.claimId === undefined ? {} : { claimId: this.#options.claimId }),
+                    ...this.#options.identity,
+                    token: this.#options.token,
+                }, this.#options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES).catch((error) => settleHandshake(toError(error)));
+            });
+        });
+    }
+    #handleFrame(value) {
+        if (isEventFrame(value)) {
+            for (const listener of this.#eventListeners) {
+                try {
+                    listener(value.event);
+                }
+                catch (error) {
+                    writeDiagnostic("controller", `event listener failed: ${errorMessage(error)}`);
+                }
+            }
+            return;
+        }
+        const socket = this.#socket;
+        if (!isResponseFrame(value)) {
+            this.#disconnectFor(socket, new Error("Runner sent a malformed frame"));
+            return;
+        }
+        const pending = this.#pending.get(value.id);
+        if (pending === undefined) {
+            if (this.#retired.has(value.id))
+                return;
+            this.#disconnectFor(socket, new Error(`Runner sent unknown response ID: ${value.id}`));
+            return;
+        }
+        this.#pending.delete(value.id);
+        this.#retire(value.id);
+        pending.cleanup();
+        if (value.ok)
+            pending.resolve(value.data);
+        else
+            pending.reject(new Error(`${value.error.code}: ${value.error.message}`));
+    }
+    /** Remembers an ID that finished locally so a late response is ignored. */
+    #retire(id) {
+        this.#retired.add(id);
+        if (this.#retired.size <= MAX_RETIRED_REQUEST_IDS)
+            return;
+        const oldest = this.#retired.values().next();
+        if (!oldest.done)
+            this.#retired.delete(oldest.value);
+    }
+    #disconnectFor(socket, error) {
+        if (socket !== undefined && this.#socket !== socket) {
+            socket.destroy();
+            return;
+        }
+        this.#socket = undefined;
+        this.#detachReader?.();
+        this.#detachReader = undefined;
+        if (socket !== undefined && !socket.destroyed)
+            socket.destroy();
+        const pending = [...this.#pending.values()];
+        this.#pending.clear();
+        for (const entry of pending) {
+            entry.cleanup();
+            entry.reject(error);
+        }
+    }
+}
+/** Sends one child report through a short-lived authenticated reporter connection. */
+export async function sendReportToRunner(identity, report, signal) {
+    await sendReporterRequest(identity, "contact_parent", report, signal);
+}
+/** Sends one child lifecycle event through a short-lived authenticated reporter connection. */
+export async function sendLifecycleToRunner(identity, payload, signal) {
+    await sendReporterRequest(identity, "report_lifecycle", payload, signal);
+}
+async function sendReporterRequest(identity, operation, payload, signal) {
+    const connection = new RunnerConnection({
+        endpoint: identity.endpoint,
+        identity,
+        token: identity.token,
+        role: "reporter",
+    });
+    try {
+        await connection.connect(signal);
+        await connection.request(operation, payload, signal === undefined ? {} : { signal });
+    }
+    finally {
+        connection.close();
+    }
+}
+/**
+ * Connects to a runner endpoint that may still be starting up.
+ *
+ * Readiness is never a fixed sleep: each attempt is a real connect plus
+ * identity handshake, so a resolved promise means the runner accepted this
+ * controller. Only connection-level failures inside the deadline are retried.
+ */
+export async function connectWithRetry(connection, options = {}) {
+    const attempts = options.attempts ?? 40;
+    const delayMs = options.delayMs ?? 50;
+    let lastError = new Error("Runner connection was not attempted");
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        if (options.signal?.aborted)
+            throw abortError();
+        try {
+            await connection.connect(options.signal);
+            return;
+        }
+        catch (error) {
+            lastError = toError(error);
+            if (lastError.name === "AbortError")
+                throw lastError;
+            if (attempt === attempts - 1)
+                break;
+            await sleep(delayMs, options.signal);
+        }
+    }
+    throw lastError;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortError());
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Runner-side shared diagnostics.
+ *
+ * The runner process owns the Pi child stdio: Pi stdout carries RPC JSON lines
+ * only, so every runner diagnostic goes to the runner process stderr.
+ */
+export declare function writeDiagnostic(scope: string, message: string): void;
+export declare function toError(value: unknown): Error;
+export declare function errorMessage(value: unknown): string;
+export declare function abortError(): Error;

package/dist/diagnostics.js

@@ -0,0 +1,20 @@
+/**
+ * Runner-side shared diagnostics.
+ *
+ * The runner process owns the Pi child stdio: Pi stdout carries RPC JSON lines
+ * only, so every runner diagnostic goes to the runner process stderr.
+ */
+export function writeDiagnostic(scope, message) {
+    process.stderr.write(`pi-subagents ${scope}: ${message}\n`);
+}
+export function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+export function errorMessage(value) {
+    return value instanceof Error ? value.message : String(value);
+}
+export function abortError() {
+    const error = new Error("Operation aborted");
+    error.name = "AbortError";
+    return error;
+}

package/dist/domain.d.ts

@@ -0,0 +1,192 @@
+export declare const PROTOCOL_VERSION: 1;
+export declare const REGISTRY_VERSION: 1;
+export type SubagentState = "starting" | "running" | "idle" | "done" | "stopped" | "failed";
+export type ExecutionMode = "rpc" | "tui";
+export type SendMode = "steer" | "follow_up" | "auto";
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type LaunchValueSource = "agent" | "parent";
+export type SubagentIntent = "active" | "stopped";
+export type PersistenceState = "never_flushed" | "flushed";
+export interface ChildIdentity {
+    readonly parentSessionId: string;
+    readonly subagentId: string;
+    readonly runtimeIdentity: string;
+    readonly endpoint: string;
+    readonly token: string;
+}
+/**
+ * The non-secret half of {@link ChildIdentity}: what a launch spec may contain and
+ * what may be persisted. The controller token is added by the launcher at spawn
+ * time and never written to a registry snapshot.
+ */
+export interface ChildBridgeEnvironment {
+    readonly parentSessionId: string;
+    readonly subagentId: string;
+    readonly runtimeIdentity: string;
+    readonly endpoint: string;
+}
+export interface PiInvocation {
+    /** Executable or runtime binary, never resolved through a shell. */
+    readonly command: string;
+    /** Host-resolved leading argv (for example an absolute `cli.js`). Feature flags are appended by the launch builder. */
+    readonly args: readonly string[];
+}
+export interface ResolvedAgentIdentity {
+    readonly name: string;
+    readonly displayName?: string;
+    readonly description?: string;
+    readonly hidden: boolean;
+    readonly sourcePath: string;
+    readonly instructions: string;
+}
+export interface ResolvedModel {
+    readonly provider: string;
+    readonly id: string;
+    readonly source: LaunchValueSource;
+}
+export interface ResolvedThinking {
+    readonly level: ThinkingLevel;
+    readonly source: LaunchValueSource;
+}
+export interface ExtensionSelection {
+    readonly discovery: boolean;
+    readonly paths: readonly string[];
+}
+export interface SkillSelection {
+    readonly discovery: boolean;
+    readonly paths: readonly string[];
+}
+export interface EffectiveLaunchConfig {
+    /** Logical child id; the same value the child bridge reports back. */
+    readonly subagentId: string;
+    readonly invocation: PiInvocation;
+    readonly cwd: string;
+    readonly sessionId: string;
+    /** Directory Pi uses for this child's session file; always passed explicitly so recovery can find the file. */
+    readonly sessionDir: string;
+    /** Known only once the session has been flushed to disk. */
+    readonly sessionPath?: string;
+    readonly agent: ResolvedAgentIdentity;
+    readonly model: ResolvedModel;
+    readonly thinking: ResolvedThinking;
+    readonly tools: readonly string[];
+    readonly excludeTools: readonly string[];
+    readonly extensions: ExtensionSelection;
+    readonly skills: SkillSelection;
+    readonly prompt: string;
+    readonly bridgeExtensionPath: string;
+    /** Frozen at spawn. Interactive children do not auto-wake the parent except via contact_parent. */
+    readonly interactive: boolean;
+}
+export interface ResolvedAgentPolicy {
+    readonly agent: ResolvedAgentIdentity;
+    readonly model: ResolvedModel;
+    readonly thinking: ResolvedThinking;
+    readonly tools: readonly string[];
+    readonly excludeTools: readonly string[];
+    readonly extensions: ExtensionSelection;
+    readonly skills: SkillSelection;
+    readonly interactive: boolean;
+}
+export interface RuntimeMetadata {
+    readonly runtimeIdentity: string;
+    readonly endpoint: string;
+    readonly pid?: number;
+}
+export type RuntimeClaimKind = "reconnect" | "replacement";
+/** Non-secret, durable ownership claim used to serialize reconnect and replacement. */
+export interface RuntimeClaim {
+    readonly claimId: string;
+    readonly kind: RuntimeClaimKind;
+    readonly holderPid: number;
+    readonly runtimeIdentity: string;
+    readonly endpoint: string;
+    /** SHA-256 of the one-time controller token; the token itself is never persisted. */
+    readonly controllerTokenHash: string;
+    /** Set by the runner before it starts the Pi writer. */
+    readonly runnerPid?: number;
+}
+export interface UsageSummary {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    readonly costUsd: number | null;
+    readonly turns: number;
+}
+export interface SubagentRecord {
+    readonly subagentId: string;
+    readonly parentSessionId: string;
+    readonly revision: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly sessionId: string;
+    readonly sessionPath?: string;
+    readonly cwd: string;
+    readonly initialTask: string;
+    readonly intent: SubagentIntent;
+    readonly state: SubagentState;
+    readonly mode: ExecutionMode;
+    readonly persistence: PersistenceState;
+    readonly launchConfig: EffectiveLaunchConfig;
+    readonly runtime?: RuntimeMetadata;
+    readonly claim?: RuntimeClaim;
+    readonly latestSummary?: string;
+    readonly usage?: UsageSummary;
+    readonly interrupted?: string;
+    readonly unacknowledgedInput?: string;
+}
+export interface PublicSubagent {
+    readonly id: string;
+    readonly agent: string;
+    readonly displayName?: string;
+    readonly state: SubagentState;
+    readonly mode: ExecutionMode;
+    readonly cwd: string;
+    readonly sessionId: string;
+    readonly summary?: string;
+    readonly usage?: UsageSummary;
+    readonly interrupted?: string;
+    readonly freshness: "live" | "last_known";
+    readonly interactive: boolean;
+    readonly model: ResolvedModel;
+    readonly thinking: ResolvedThinking;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface OperationError {
+    readonly operation: string;
+    readonly childId?: string;
+    readonly reason: string;
+    readonly sideEffects: readonly string[];
+    readonly state?: SubagentState;
+    readonly safeToRetry: boolean;
+}
+export interface SpawnSubagentInput {
+    readonly task: string;
+    readonly agent: string;
+    readonly cwd?: string;
+}
+/** Child bridge tool name; agent tool policy must never remove it. */
+export declare const CONTACT_PARENT_TOOL_NAME: "contact_parent";
+/** Environment contract between a parent launch and the child branch of this extension. */
+export declare const BRIDGE_ENVIRONMENT_KEYS: {
+    readonly parentSessionId: "PI_SUBAGENTS_PARENT_SESSION_ID";
+    readonly childId: "PI_SUBAGENTS_CHILD_ID";
+    readonly runtimeId: "PI_SUBAGENTS_RUNTIME_ID";
+    readonly endpoint: "PI_SUBAGENTS_ENDPOINT";
+    readonly token: "PI_SUBAGENTS_TOKEN";
+};
+/** Non-secret agent label for the child TUI identity line. Not part of handshake. */
+export declare const CHILD_AGENT_ENV_KEY: "PI_SUBAGENTS_AGENT";
+/** Bound Pi session id for the child branch. Not part of the runner handshake. */
+export declare const CHILD_SESSION_ENV_KEY: "PI_SUBAGENTS_SESSION_ID";
+/** Pi session ids reach argv and file names, so they must stay in Pi's accepted alphabet. */
+export declare function isSessionId(value: unknown): value is string;
+export declare function isThinkingLevel(value: unknown): value is ThinkingLevel;
+export declare function isSubagentState(value: unknown): value is SubagentState;
+export declare function isExecutionMode(value: unknown): value is ExecutionMode;
+export declare function isSubagentIntent(value: unknown): value is SubagentIntent;
+export declare function isPersistenceState(value: unknown): value is PersistenceState;
+export declare function isLaunchValueSource(value: unknown): value is LaunchValueSource;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/domain.js

@@ -0,0 +1,63 @@
+export const PROTOCOL_VERSION = 1;
+export const REGISTRY_VERSION = 1;
+/** Child bridge tool name; agent tool policy must never remove it. */
+export const CONTACT_PARENT_TOOL_NAME = "contact_parent";
+/** Environment contract between a parent launch and the child branch of this extension. */
+export const BRIDGE_ENVIRONMENT_KEYS = {
+    parentSessionId: "PI_SUBAGENTS_PARENT_SESSION_ID",
+    childId: "PI_SUBAGENTS_CHILD_ID",
+    runtimeId: "PI_SUBAGENTS_RUNTIME_ID",
+    endpoint: "PI_SUBAGENTS_ENDPOINT",
+    token: "PI_SUBAGENTS_TOKEN",
+};
+/** Non-secret agent label for the child TUI identity line. Not part of handshake. */
+export const CHILD_AGENT_ENV_KEY = "PI_SUBAGENTS_AGENT";
+/** Bound Pi session id for the child branch. Not part of the runner handshake. */
+export const CHILD_SESSION_ENV_KEY = "PI_SUBAGENTS_SESSION_ID";
+const SESSION_ID_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
+/** Pi session ids reach argv and file names, so they must stay in Pi's accepted alphabet. */
+export function isSessionId(value) {
+    return typeof value === "string" && SESSION_ID_PATTERN.test(value);
+}
+const THINKING_LEVELS = {
+    off: true,
+    minimal: true,
+    low: true,
+    medium: true,
+    high: true,
+    xhigh: true,
+    max: true,
+};
+export function isThinkingLevel(value) {
+    return typeof value === "string" && THINKING_LEVELS[value] === true;
+}
+const SUBAGENT_STATES = {
+    starting: true,
+    running: true,
+    idle: true,
+    done: true,
+    stopped: true,
+    failed: true,
+};
+export function isSubagentState(value) {
+    return typeof value === "string" && SUBAGENT_STATES[value] === true;
+}
+const EXECUTION_MODES = { rpc: true, tui: true };
+export function isExecutionMode(value) {
+    return typeof value === "string" && EXECUTION_MODES[value] === true;
+}
+const SUBAGENT_INTENTS = { active: true, stopped: true };
+export function isSubagentIntent(value) {
+    return typeof value === "string" && SUBAGENT_INTENTS[value] === true;
+}
+const PERSISTENCE_STATES = { never_flushed: true, flushed: true };
+export function isPersistenceState(value) {
+    return typeof value === "string" && PERSISTENCE_STATES[value] === true;
+}
+const LAUNCH_VALUE_SOURCES = { agent: true, parent: true };
+export function isLaunchValueSource(value) {
+    return typeof value === "string" && LAUNCH_VALUE_SOURCES[value] === true;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/extension.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function piSubagentsExtension(pi: ExtensionAPI): void;