@hheei/pi-subagents 0.1.2 → 0.2.2

package/dist/rpc-adapter.d.ts

@@ -1,40 +0,0 @@
-import type { ChildProcessWithoutNullStreams } from "node:child_process";
-import { type RunnerOperation } from "./protocol.js";
-/**
- * Runner operations that map onto a real Pi `--mode rpc` command. Runner-local
- * shutdown, writer handoff, and contact_parent operations are never forwarded to Pi.
- */
-export type PiRpcOperation = Exclude<RunnerOperation, "shutdown" | "contact_parent" | "report_lifecycle" | "report_paused" | "pause" | "cancel_pause" | "close_writer" | "start_rpc">;
-/** A forwarded Pi RPC command did not answer within its deadline. */
-export declare class PiRpcTimeoutError extends Error {
-    constructor(message: string);
-}
-export interface PiRpcAdapterOptions {
-    readonly process: ChildProcessWithoutNullStreams;
-    readonly maxFrameBytes?: number;
-    readonly maxPendingRequests?: number;
-    readonly requestTimeoutMs?: number;
-    /**
-     * Receives exceptions thrown by event listeners. A listener that throws must
-     * not be mistaken for a malformed Pi frame, so the error is reported here.
-     */
-    readonly onListenerError?: (error: unknown) => void;
-}
-/**
- * Thin request/response transport over one Pi `--mode rpc` child process.
- *
- * Pi stdout is RPC JSON lines only. Responses are matched to in-flight requests
- * by request ID; everything else is delivered to event listeners unchanged.
- */
-export declare class PiRpcAdapter {
-    #private;
-    constructor(options: PiRpcAdapterOptions);
-    onEvent(listener: (event: unknown) => void): () => void;
-    /** Confirms readiness with a real `get_state` round trip. */
-    ready(signal?: AbortSignal): Promise<unknown>;
-    request(operation: PiRpcOperation, payload?: unknown, options?: {
-        readonly signal?: AbortSignal;
-        readonly timeoutMs?: number;
-    }): Promise<unknown>;
-    close(reason?: Error): void;
-}

package/dist/rpc-adapter.js

@@ -1,194 +0,0 @@
-import { Value } from "typebox/value";
-import { abortError, toError } from "./diagnostics.js";
-import { isRecord } from "./domain.js";
-import { attachJsonLineReader, serializeJsonLine } from "./json-lines.js";
-import { DEFAULT_MAX_FRAME_BYTES, DEFAULT_MAX_PENDING_REQUESTS, GetEntriesPayloadSchema, PromptPayloadSchema, } from "./protocol.js";
-/** A forwarded Pi RPC command did not answer within its deadline. */
-export class PiRpcTimeoutError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "PiRpcTimeoutError";
-    }
-}
-/**
- * Thin request/response transport over one Pi `--mode rpc` child process.
- *
- * Pi stdout is RPC JSON lines only. Responses are matched to in-flight requests
- * by request ID; everything else is delivered to event listeners unchanged.
- */
-export class PiRpcAdapter {
-    #process;
-    #maxFrameBytes;
-    #maxPendingRequests;
-    #requestTimeoutMs;
-    #onListenerError;
-    #pending = new Map();
-    #listeners = new Set();
-    #nextRequestId = 0;
-    #closedError;
-    #detachReader;
-    constructor(options) {
-        this.#process = options.process;
-        this.#maxFrameBytes = options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES;
-        this.#maxPendingRequests = options.maxPendingRequests ?? DEFAULT_MAX_PENDING_REQUESTS;
-        this.#requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
-        this.#onListenerError =
-            options.onListenerError ??
-                ((error) => {
-                    process.stderr.write(`pi-subagents rpc listener error: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
-                });
-        const onStreamError = (error) => this.#fail(error);
-        this.#process.stdin.on("error", onStreamError);
-        this.#process.stdout.on("error", onStreamError);
-        this.#process.once("error", onStreamError);
-        this.#process.once("exit", (code, signal) => {
-            this.#fail(new Error(`Pi RPC exited (code=${String(code)}, signal=${String(signal)})`));
-        });
-        this.#detachReader = attachJsonLineReader(this.#process.stdout, {
-            maxFrameBytes: this.#maxFrameBytes,
-            onValue: (value) => this.#handleValue(value),
-            onError: (error) => this.#fail(error),
-        });
-    }
-    onEvent(listener) {
-        this.#listeners.add(listener);
-        return () => {
-            this.#listeners.delete(listener);
-        };
-    }
-    /** Confirms readiness with a real `get_state` round trip. */
-    async ready(signal) {
-        return this.request("get_state", undefined, signal === undefined ? {} : { signal });
-    }
-    request(operation, payload, options = {}) {
-        let command;
-        try {
-            command = buildPiCommand(operation, payload);
-        }
-        catch (error) {
-            return Promise.reject(toError(error));
-        }
-        return this.#send(command, options);
-    }
-    close(reason = new Error("Pi RPC adapter closed")) {
-        this.#fail(reason);
-    }
-    #send(command, options) {
-        if (this.#closedError)
-            return Promise.reject(this.#closedError);
-        if (this.#process.exitCode !== null) {
-            return Promise.reject(new Error(`Pi RPC process already exited (code=${this.#process.exitCode})`));
-        }
-        if (options.signal?.aborted)
-            return Promise.reject(abortError());
-        if (this.#pending.size >= this.#maxPendingRequests) {
-            return Promise.reject(new Error("Pi RPC pending request limit exceeded"));
-        }
-        const id = `pi-${++this.#nextRequestId}`;
-        let encoded;
-        try {
-            encoded = serializeJsonLine({ ...command, id }, this.#maxFrameBytes);
-        }
-        catch (error) {
-            return Promise.reject(toError(error));
-        }
-        return new Promise((resolve, reject) => {
-            const settle = (error, value) => {
-                const pending = this.#pending.get(id);
-                if (!pending)
-                    return;
-                this.#pending.delete(id);
-                pending.cleanup();
-                if (error)
-                    pending.reject(error);
-                else
-                    pending.resolve(value);
-            };
-            const timeout = setTimeout(() => settle(new PiRpcTimeoutError(`Pi RPC ${command.type} timed out`)), options.timeoutMs ?? this.#requestTimeoutMs);
-            const onAbort = () => settle(abortError());
-            const cleanup = () => {
-                clearTimeout(timeout);
-                options.signal?.removeEventListener("abort", onAbort);
-            };
-            this.#pending.set(id, { command: command.type, resolve, reject, cleanup });
-            options.signal?.addEventListener("abort", onAbort, { once: true });
-            this.#process.stdin.write(encoded, (error) => {
-                if (error)
-                    settle(error);
-            });
-        });
-    }
-    #handleValue(value) {
-        if (!isRecord(value) || value.type !== "response") {
-            for (const listener of this.#listeners) {
-                try {
-                    listener(value);
-                }
-                catch (error) {
-                    this.#onListenerError(error);
-                }
-            }
-            return;
-        }
-        if (typeof value.id !== "string" ||
-            typeof value.command !== "string" ||
-            typeof value.success !== "boolean" ||
-            (value.success === false && typeof value.error !== "string")) {
-            this.#fail(new Error("Malformed Pi RPC response"));
-            return;
-        }
-        const pending = this.#pending.get(value.id);
-        if (!pending)
-            return;
-        this.#pending.delete(value.id);
-        pending.cleanup();
-        if (value.command !== pending.command) {
-            pending.reject(new Error(`Pi RPC response command mismatch: expected ${pending.command}`));
-            return;
-        }
-        if (!value.success) {
-            pending.reject(new Error(value.error));
-            return;
-        }
-        pending.resolve(value.data);
-    }
-    #fail(error) {
-        if (this.#closedError)
-            return;
-        this.#closedError = toError(error);
-        this.#detachReader?.();
-        this.#detachReader = undefined;
-        const closed = this.#closedError;
-        for (const pending of this.#pending.values()) {
-            pending.cleanup();
-            pending.reject(closed);
-        }
-        this.#pending.clear();
-    }
-}
-function buildPiCommand(operation, payload) {
-    switch (operation) {
-        case "prompt":
-        case "steer":
-        case "follow_up": {
-            if (!Value.Check(PromptPayloadSchema, payload)) {
-                throw new Error(`${operation} requires a payload with only a non-empty message`);
-            }
-            return { type: operation, message: payload.message };
-        }
-        case "get_entries": {
-            if (payload === undefined)
-                return { type: operation };
-            if (!Value.Check(GetEntriesPayloadSchema, payload)) {
-                throw new Error("get_entries payload must be undefined or contain only a non-empty since string");
-            }
-            return { type: operation, since: payload.since };
-        }
-        case "abort":
-        case "get_state":
-        case "get_session_stats":
-            if (payload !== undefined)
-                throw new Error(`${operation} does not accept a payload`);
-            return { type: operation };
-    }
-}

package/dist/runner-entry.d.ts

@@ -1,24 +0,0 @@
-#!/usr/bin/env node
-import { type Static, Type } from "typebox";
-import type { ChildIdentity } from "./domain.js";
-export declare const RUNNER_JOB_FLAG = "--job";
-export declare const JOB_FROM_STDIN = "-";
-/** Bytes of Pi child stderr kept for failure diagnostics. */
-export declare const STDERR_TAIL_BYTES: number;
-export declare const RunnerJobSchema: Type.TObject<{
-    invocation: Type.TObject<{
-        command: Type.TString;
-        args: Type.TArray<Type.TString>;
-    }>;
-    cwd: Type.TString;
-    sessionId: Type.TString;
-    sessionPath: Type.TOptional<Type.TString>;
-    claimId: Type.TOptional<Type.TString>;
-    env: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
-}>;
-export type RunnerJob = Static<typeof RunnerJobSchema>;
-/** Reads the runner identity from the shared environment contract. */
-export declare function readIdentityFromEnv(env: NodeJS.ProcessEnv): ChildIdentity;
-/** Resolves the job source: `--job <path>`, a positional path, or stdin. */
-export declare function resolveJobSource(argv: readonly string[]): string;
-export declare function readRunnerJob(source: string, stdin?: AsyncIterable<Buffer | string>): Promise<RunnerJob>;

package/dist/runner-entry.js

@@ -1,166 +0,0 @@
-#!/usr/bin/env node
-/**
- * Executable entry for one independently living pi-subagents runner.
- *
- * Usage:
- *   node runner-entry.js --job <job.json>      # or: node runner-entry.js <job.json>
- *   node runner-entry.js -                     # job JSON on stdin
- *
- * The job file carries the pre-resolved Pi `--mode rpc` invocation (command and
- * complete argv), cwd, session identity and extra environment variables. This
- * process never guesses the Pi CLI: it spawns exactly what the launch-spec
- * builder resolved in the parent.
- *
- * Identity comes from the `PI_SUBAGENTS_*` environment contract, which is also
- * inherited by the Pi child so its child branch can identify itself and reach
- * this runner's endpoint.
- */
-import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
-import { readFile, stat } from "node:fs/promises";
-import { Type } from "typebox";
-import { Value } from "typebox/value";
-import { errorMessage, writeDiagnostic } from "./diagnostics.js";
-import { createSubagentRegistry } from "./registry.js";
-import { startRunner } from "./runner.js";
-export const RUNNER_JOB_FLAG = "--job";
-export const JOB_FROM_STDIN = "-";
-/** Bytes of Pi child stderr kept for failure diagnostics. */
-export const STDERR_TAIL_BYTES = 16 * 1024;
-export const RunnerJobSchema = Type.Object({
-    invocation: Type.Object({ command: Type.String({ minLength: 1 }), args: Type.Array(Type.String()) }, { additionalProperties: false }),
-    cwd: Type.String({ minLength: 1 }),
-    sessionId: Type.String({ minLength: 1 }),
-    sessionPath: Type.Optional(Type.String({ minLength: 1 })),
-    claimId: Type.Optional(Type.String({ minLength: 1 })),
-    env: Type.Optional(Type.Record(Type.String(), Type.String())),
-}, { additionalProperties: false });
-const IDENTITY_ENV_KEYS = {
-    parentSessionId: "PI_SUBAGENTS_PARENT_SESSION_ID",
-    subagentId: "PI_SUBAGENTS_CHILD_ID",
-    runtimeIdentity: "PI_SUBAGENTS_RUNTIME_ID",
-    endpoint: "PI_SUBAGENTS_ENDPOINT",
-    token: "PI_SUBAGENTS_TOKEN",
-};
-/** Reads the runner identity from the shared environment contract. */
-export function readIdentityFromEnv(env) {
-    const read = (key) => {
-        const value = env[key];
-        if (value === undefined || value === "") {
-            throw new Error(`runner requires ${key} in its environment`);
-        }
-        return value;
-    };
-    return {
-        parentSessionId: read(IDENTITY_ENV_KEYS.parentSessionId),
-        subagentId: read(IDENTITY_ENV_KEYS.subagentId),
-        runtimeIdentity: read(IDENTITY_ENV_KEYS.runtimeIdentity),
-        endpoint: read(IDENTITY_ENV_KEYS.endpoint),
-        token: read(IDENTITY_ENV_KEYS.token),
-    };
-}
-/** Resolves the job source: `--job <path>`, a positional path, or stdin. */
-export function resolveJobSource(argv) {
-    const flagIndex = argv.indexOf(RUNNER_JOB_FLAG);
-    if (flagIndex >= 0) {
-        const value = argv[flagIndex + 1];
-        if (value === undefined || value === "")
-            throw new Error(`${RUNNER_JOB_FLAG} requires a path`);
-        return value;
-    }
-    const positional = argv.find((argument) => !argument.startsWith("--"));
-    if (positional === undefined) {
-        throw new Error(`runner requires a job: ${RUNNER_JOB_FLAG} <path> or ${JOB_FROM_STDIN}`);
-    }
-    return positional;
-}
-export async function readRunnerJob(source, stdin = process.stdin) {
-    const raw = source === JOB_FROM_STDIN ? await readStream(stdin) : await readFile(source, "utf8");
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        throw new Error(`runner job is not valid JSON: ${errorMessage(error)}`);
-    }
-    if (!Value.Check(RunnerJobSchema, parsed))
-        throw new Error("runner job does not match the runner job schema");
-    return parsed;
-}
-async function readStream(stdin) {
-    const chunks = [];
-    for await (const chunk of stdin) {
-        chunks.push(Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk);
-    }
-    return chunks.join("");
-}
-async function main() {
-    const job = await readRunnerJob(resolveJobSource(process.argv.slice(2)));
-    const identity = readIdentityFromEnv(process.env);
-    const cwd = await stat(job.cwd).catch(() => undefined);
-    if (cwd === undefined || !cwd.isDirectory()) {
-        throw new Error(`runner job cwd is not a directory: ${job.cwd}`);
-    }
-    const registry = createSubagentRegistry({ parentSessionId: identity.parentSessionId });
-    if (job.claimId !== undefined) {
-        await registry.markClaimRunner(identity.subagentId, job.claimId, process.pid);
-        await registry.activateClaim(identity.subagentId, job.claimId, process.pid);
-    }
-    let stderrTail = "";
-    const spawnWriter = () => {
-        const next = spawn(job.invocation.command, [...job.invocation.args], {
-            cwd: job.cwd,
-            env: {
-                ...process.env,
-                ...(job.env ?? {}),
-                [IDENTITY_ENV_KEYS.parentSessionId]: identity.parentSessionId,
-                [IDENTITY_ENV_KEYS.subagentId]: identity.subagentId,
-                [IDENTITY_ENV_KEYS.runtimeIdentity]: identity.runtimeIdentity,
-                [IDENTITY_ENV_KEYS.endpoint]: identity.endpoint,
-                [IDENTITY_ENV_KEYS.token]: identity.token,
-            },
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        next.stderr.on("data", (chunk) => {
-            process.stderr.write(chunk);
-            stderrTail = `${stderrTail}${chunk.toString("utf8")}`.slice(-STDERR_TAIL_BYTES);
-        });
-        return next;
-    };
-    const child = spawnWriter();
-    try {
-        const runner = await startRunner({
-            identity,
-            process: child,
-            spawnWriter,
-            sessionId: job.sessionId,
-            authorizeRecovery: async (claimId, token) => {
-                const tokenHash = createHash("sha256").update(token).digest("hex");
-                await registry.consumeReconnectClaim(identity.subagentId, claimId, tokenHash);
-                return true;
-            },
-            onDiagnostic: (line) => writeDiagnostic("runner", line),
-        });
-        writeDiagnostic("runner", `ready endpoint=${identity.endpoint} child=${identity.subagentId} session=${job.sessionId}`);
-        const stop = (signal) => {
-            void runner.shutdown(new Error(`runner received ${signal}`));
-        };
-        process.once("SIGTERM", () => stop("SIGTERM"));
-        process.once("SIGINT", () => stop("SIGINT"));
-        const exit = await runner.closed();
-        if (stderrTail !== "" && !exit.requested) {
-            writeDiagnostic("runner", `Pi child stderr tail:\n${stderrTail}`);
-        }
-        // An explicit shutdown is a clean end; a child that died on its own is not.
-        process.exitCode = exit.requested ? 0 : (exit.code ?? (exit.signal === null ? 0 : 1));
-    }
-    catch (error) {
-        if (stderrTail !== "")
-            writeDiagnostic("runner", `Pi child stderr tail:\n${stderrTail}`);
-        throw error;
-    }
-}
-void main().catch((error) => {
-    writeDiagnostic("runner-entry", errorMessage(error));
-    process.exitCode = 1;
-});

package/dist/runner.d.ts

@@ -1,52 +0,0 @@
-import type { ChildProcessWithoutNullStreams } from "node:child_process";
-import { type ChildIdentity } from "./domain.js";
-export interface SubagentRunnerOptions {
-    readonly identity: ChildIdentity;
-    /** The Pi `--mode rpc` child owned by this runner. */
-    readonly process: ChildProcessWithoutNullStreams;
-    /**
-     * Recreates a Pi RPC writer with the same job. Required for attach recovery
-     * (`start_rpc`) so the runner endpoint survives writer replacement.
-     */
-    readonly spawnWriter?: () => ChildProcessWithoutNullStreams;
-    readonly maxFrameBytes?: number;
-    readonly maxPendingRequests?: number;
-    readonly maxBufferedEvents?: number;
-    /** Queued bytes tolerated on a controller socket before it is dropped. */
-    readonly maxControllerBufferBytes?: number;
-    readonly requestTimeoutMs?: number;
-    readonly readyTimeoutMs?: number;
-    readonly handshakeTimeoutMs?: number;
-    readonly shutdownGraceMs?: number;
-    readonly killGraceMs?: number;
-    readonly onDiagnostic?: (line: string) => void;
-    /** Atomically consumes a durable recovery claim for a one-time controller token. */
-    readonly authorizeRecovery?: (claimId: string, token: string) => Promise<boolean>;
-    /** Bound child session; reporters for a different session are rejected after a leave. */
-    readonly sessionId?: string;
-}
-/** Observed end of the Pi child owned by the runner. */
-export interface RunnerExit {
-    readonly code: number | null;
-    readonly signal: string | null;
-    readonly reason: Error;
-    /** True when an explicit shutdown ended the runtime, not the child itself. */
-    readonly requested: boolean;
-}
-export interface SubagentRunner {
-    readonly endpoint: string;
-    readonly identity: ChildIdentity;
-    /** Real `get_state` data captured when the Pi child became ready. */
-    readonly readiness: unknown;
-    /** Resolves once the Pi child exited and every runner resource is released. */
-    closed(): Promise<RunnerExit>;
-    shutdown(reason?: Error): Promise<RunnerExit>;
-}
-/**
- * Starts the reconnectable runner endpoint for one Pi RPC child.
- *
- * The runner owns the child stdio, accepts exactly one authenticated controller
- * at a time, and stays alive across controller disconnects: only an explicit
- * `shutdown` request, the end of the Pi child, or process termination stops it.
- */
-export declare function startRunner(options: SubagentRunnerOptions): Promise<SubagentRunner>;