@hheei/pi-subagents 0.1.2

package/dist/pause-gate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Child-side hold used by `turn_end`. Parent pause events arm the gate;
+ * `cancel_pause` or process abort releases it. Returning from `turn_end`
+ * is what lets Pi start the next provider request, so the hook must await
+ * this while a matching generation is holding.
+ */
+export declare class PauseGate {
+    #private;
+    get generation(): number;
+    get holding(): boolean;
+    request(generation: number): void;
+    cancel(generation?: number): void;
+    wait(signal?: AbortSignal): Promise<void>;
+}

package/dist/pause-gate.js

@@ -0,0 +1,64 @@
+/**
+ * Child-side hold used by `turn_end`. Parent pause events arm the gate;
+ * `cancel_pause` or process abort releases it. Returning from `turn_end`
+ * is what lets Pi start the next provider request, so the hook must await
+ * this while a matching generation is holding.
+ */
+export class PauseGate {
+    #generation = 0;
+    #holding = false;
+    #waiters = new Set();
+    get generation() {
+        return this.#generation;
+    }
+    get holding() {
+        return this.#holding;
+    }
+    request(generation) {
+        if (!Number.isInteger(generation) || generation < this.#generation)
+            return;
+        this.#generation = generation;
+        this.#holding = true;
+    }
+    cancel(generation) {
+        if (generation !== undefined && generation < this.#generation)
+            return;
+        if (generation !== undefined)
+            this.#generation = generation;
+        this.#holding = false;
+        this.#release();
+    }
+    wait(signal) {
+        if (!this.#holding)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const finish = (error) => {
+                this.#waiters.delete(onRelease);
+                signal?.removeEventListener("abort", onAbort);
+                if (error !== undefined)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const onRelease = (error) => {
+                finish(error);
+            };
+            const onAbort = () => {
+                this.#holding = false;
+                this.#release();
+            };
+            this.#waiters.add(onRelease);
+            if (signal?.aborted) {
+                onAbort();
+                return;
+            }
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    #release(error) {
+        const waiters = [...this.#waiters];
+        this.#waiters.clear();
+        for (const waiter of waiters)
+            waiter(error);
+    }
+}

package/dist/protocol.d.ts

@@ -0,0 +1,141 @@
+import { type Static, Type } from "typebox";
+export declare const DEFAULT_MAX_FRAME_BYTES: number;
+export declare const DEFAULT_MAX_PENDING_REQUESTS = 128;
+export declare const DEFAULT_MAX_BUFFERED_EVENTS = 256;
+export declare const RUNNER_OPERATIONS: readonly ["prompt", "steer", "follow_up", "abort", "get_state", "get_entries", "get_session_stats", "shutdown", "contact_parent", "report_lifecycle", "report_paused", "pause", "cancel_pause", "close_writer", "start_rpc"];
+export type RunnerOperation = (typeof RUNNER_OPERATIONS)[number];
+/** Runner-local event emitted when the Pi child process exits. */
+export declare const RUNNER_EXIT_EVENT: "runner_exit";
+/** Runner-local event emitted when only the RPC writer exited and the runner stayed up. */
+export declare const WRITER_EXIT_EVENT: "writer_exit";
+/** Runner-local event emitted when buffered events had to be dropped. */
+export declare const RUNNER_EVENTS_DROPPED_EVENT: "runner_events_dropped";
+/** Child-branch event: the TUI left the bound session, quit, or was interrupted. */
+export declare const CHILD_LIFECYCLE_EVENT: "child_lifecycle";
+/** Runner-to-bridge event: hold the current turn_end until close_writer or cancel. */
+export declare const PAUSE_EVENT: "pause";
+/** Runner-to-bridge event: release a previous pause generation. */
+export declare const CANCEL_PAUSE_EVENT: "cancel_pause";
+export declare const HelloFrameSchema: Type.TObject<{
+    parentSessionId: Type.TString;
+    subagentId: Type.TString;
+    runtimeIdentity: Type.TString;
+    endpoint: Type.TString;
+    token: Type.TString;
+    version: Type.TLiteral<1>;
+    type: Type.TLiteral<"hello">;
+    role: Type.TOptional<Type.TUnion<[Type.TLiteral<"controller">, Type.TLiteral<"reporter">, Type.TLiteral<"recovery">, Type.TLiteral<"bridge">]>>;
+    claimId: Type.TOptional<Type.TString>;
+}>;
+export declare const HelloAckFrameSchema: Type.TObject<{
+    version: Type.TLiteral<1>;
+    type: Type.TLiteral<"hello_ack">;
+}>;
+export declare const RequestFrameSchema: Type.TObject<{
+    version: Type.TLiteral<1>;
+    type: Type.TLiteral<"request">;
+    id: Type.TString;
+    operation: Type.TUnion<Type.TLiteral<"steer" | "follow_up" | "contact_parent" | "pause" | "prompt" | "abort" | "get_state" | "get_entries" | "get_session_stats" | "shutdown" | "report_lifecycle" | "report_paused" | "cancel_pause" | "close_writer" | "start_rpc">[]>;
+    payload: Type.TOptional<Type.TUnknown>;
+}>;
+export declare const RunnerErrorSchema: Type.TObject<{
+    code: Type.TString;
+    message: Type.TString;
+}>;
+export declare const ResponseFrameSchema: Type.TUnion<[Type.TObject<{
+    version: Type.TLiteral<1>;
+    type: Type.TLiteral<"response">;
+    id: Type.TString;
+    ok: Type.TLiteral<true>;
+    data: Type.TOptional<Type.TUnknown>;
+}>, Type.TObject<{
+    version: Type.TLiteral<1>;
+    type: Type.TLiteral<"response">;
+    id: Type.TString;
+    ok: Type.TLiteral<false>;
+    error: Type.TObject<{
+        code: Type.TString;
+        message: Type.TString;
+    }>;
+}>]>;
+export declare const EventFrameSchema: Type.TObject<{
+    version: Type.TLiteral<1>;
+    type: Type.TLiteral<"event">;
+    event: Type.TUnknown;
+}>;
+export declare const ServerFrameSchema: Type.TUnion<[Type.TObject<{
+    version: Type.TLiteral<1>;
+    type: Type.TLiteral<"hello_ack">;
+}>, Type.TUnion<[Type.TObject<{
+    version: Type.TLiteral<1>;
+    type: Type.TLiteral<"response">;
+    id: Type.TString;
+    ok: Type.TLiteral<true>;
+    data: Type.TOptional<Type.TUnknown>;
+}>, Type.TObject<{
+    version: Type.TLiteral<1>;
+    type: Type.TLiteral<"response">;
+    id: Type.TString;
+    ok: Type.TLiteral<false>;
+    error: Type.TObject<{
+        code: Type.TString;
+        message: Type.TString;
+    }>;
+}>]>, Type.TObject<{
+    version: Type.TLiteral<1>;
+    type: Type.TLiteral<"event">;
+    event: Type.TUnknown;
+}>]>;
+export declare const PromptPayloadSchema: Type.TObject<{
+    message: Type.TString;
+}>;
+export declare const GetEntriesPayloadSchema: Type.TObject<{
+    since: Type.TString;
+}>;
+export declare const ContactReportPayloadSchema: Type.TObject<{
+    type: Type.TLiteral<"pi_subagent_report">;
+    parentSessionId: Type.TString;
+    childId: Type.TString;
+    runtimeIdentity: Type.TString;
+    reason: Type.TUnion<[Type.TLiteral<"progress_update">, Type.TLiteral<"important_finding">, Type.TLiteral<"need_decision">, Type.TLiteral<"blocked">]>;
+    message: Type.TString;
+    sessionId: Type.TOptional<Type.TString>;
+}>;
+export declare const ChildLifecyclePayloadSchema: Type.TObject<{
+    type: Type.TLiteral<"child_lifecycle">;
+    parentSessionId: Type.TString;
+    childId: Type.TString;
+    runtimeIdentity: Type.TString;
+    kind: Type.TUnion<[Type.TLiteral<"left_session">, Type.TLiteral<"tui_quit">, Type.TLiteral<"user_interrupt">]>;
+    sessionId: Type.TString;
+    message: Type.TOptional<Type.TString>;
+}>;
+export declare const PauseReportPayloadSchema: Type.TObject<{
+    type: Type.TLiteral<"report_paused">;
+    parentSessionId: Type.TString;
+    childId: Type.TString;
+    runtimeIdentity: Type.TString;
+    generation: Type.TInteger;
+}>;
+export type HelloFrame = Static<typeof HelloFrameSchema>;
+export type HelloAckFrame = Static<typeof HelloAckFrameSchema>;
+export type RequestFrame = Static<typeof RequestFrameSchema>;
+export type ResponseFrame = Static<typeof ResponseFrameSchema>;
+export type EventFrame = Static<typeof EventFrameSchema>;
+export type ServerFrame = Static<typeof ServerFrameSchema>;
+export type ContactReportPayload = Static<typeof ContactReportPayloadSchema>;
+export type ChildLifecyclePayload = Static<typeof ChildLifecyclePayloadSchema>;
+export type PauseReportPayload = Static<typeof PauseReportPayloadSchema>;
+export declare function isRunnerOperation(value: unknown): value is RunnerOperation;
+export declare function isHelloFrame(value: unknown): value is HelloFrame;
+export declare function isHelloAckFrame(value: unknown): value is HelloAckFrame;
+export declare function isRequestFrame(value: unknown): value is RequestFrame;
+export declare function isContactReportPayload(value: unknown): value is ContactReportPayload;
+export declare function isChildLifecyclePayload(value: unknown): value is ChildLifecyclePayload;
+export declare function isPauseReportPayload(value: unknown): value is PauseReportPayload;
+export declare function isResponseFrame(value: unknown): value is ResponseFrame;
+export declare function isEventFrame(value: unknown): value is EventFrame;
+export declare function isServerFrame(value: unknown): value is ServerFrame;
+export declare function successResponse(id: string, data?: unknown): ResponseFrame;
+export declare function failureResponse(id: string, code: string, message: string): ResponseFrame;
+export declare function eventFrame(event: unknown): EventFrame;

package/dist/protocol.js

@@ -0,0 +1,168 @@
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { PROTOCOL_VERSION } from "./domain.js";
+export const DEFAULT_MAX_FRAME_BYTES = 1024 * 1024;
+export const DEFAULT_MAX_PENDING_REQUESTS = 128;
+export const DEFAULT_MAX_BUFFERED_EVENTS = 256;
+export const RUNNER_OPERATIONS = [
+    "prompt",
+    "steer",
+    "follow_up",
+    "abort",
+    "get_state",
+    "get_entries",
+    "get_session_stats",
+    "shutdown",
+    "contact_parent",
+    "report_lifecycle",
+    "report_paused",
+    "pause",
+    "cancel_pause",
+    "close_writer",
+    "start_rpc",
+];
+/** Runner-local event emitted when the Pi child process exits. */
+export const RUNNER_EXIT_EVENT = "runner_exit";
+/** Runner-local event emitted when only the RPC writer exited and the runner stayed up. */
+export const WRITER_EXIT_EVENT = "writer_exit";
+/** Runner-local event emitted when buffered events had to be dropped. */
+export const RUNNER_EVENTS_DROPPED_EVENT = "runner_events_dropped";
+/** Child-branch event: the TUI left the bound session, quit, or was interrupted. */
+export const CHILD_LIFECYCLE_EVENT = "child_lifecycle";
+/** Runner-to-bridge event: hold the current turn_end until close_writer or cancel. */
+export const PAUSE_EVENT = "pause";
+/** Runner-to-bridge event: release a previous pause generation. */
+export const CANCEL_PAUSE_EVENT = "cancel_pause";
+const nonEmptyString = Type.String({ minLength: 1 });
+const operationSchema = Type.Union(RUNNER_OPERATIONS.map((operation) => Type.Literal(operation)));
+const identityProperties = {
+    parentSessionId: nonEmptyString,
+    subagentId: nonEmptyString,
+    runtimeIdentity: nonEmptyString,
+    endpoint: nonEmptyString,
+    token: nonEmptyString,
+};
+export const HelloFrameSchema = Type.Object({
+    version: Type.Literal(PROTOCOL_VERSION),
+    type: Type.Literal("hello"),
+    role: Type.Optional(Type.Union([
+        Type.Literal("controller"),
+        Type.Literal("reporter"),
+        Type.Literal("recovery"),
+        Type.Literal("bridge"),
+    ])),
+    claimId: Type.Optional(nonEmptyString),
+    ...identityProperties,
+}, { additionalProperties: false });
+export const HelloAckFrameSchema = Type.Object({ version: Type.Literal(PROTOCOL_VERSION), type: Type.Literal("hello_ack") }, { additionalProperties: false });
+export const RequestFrameSchema = Type.Object({
+    version: Type.Literal(PROTOCOL_VERSION),
+    type: Type.Literal("request"),
+    id: nonEmptyString,
+    operation: operationSchema,
+    payload: Type.Optional(Type.Unknown()),
+}, { additionalProperties: false });
+export const RunnerErrorSchema = Type.Object({ code: nonEmptyString, message: nonEmptyString }, { additionalProperties: false });
+export const ResponseFrameSchema = Type.Union([
+    Type.Object({
+        version: Type.Literal(PROTOCOL_VERSION),
+        type: Type.Literal("response"),
+        id: nonEmptyString,
+        ok: Type.Literal(true),
+        data: Type.Optional(Type.Unknown()),
+    }, { additionalProperties: false }),
+    Type.Object({
+        version: Type.Literal(PROTOCOL_VERSION),
+        type: Type.Literal("response"),
+        id: nonEmptyString,
+        ok: Type.Literal(false),
+        error: RunnerErrorSchema,
+    }, { additionalProperties: false }),
+]);
+export const EventFrameSchema = Type.Object({ version: Type.Literal(PROTOCOL_VERSION), type: Type.Literal("event"), event: Type.Unknown() }, { additionalProperties: false });
+export const ServerFrameSchema = Type.Union([
+    HelloAckFrameSchema,
+    ResponseFrameSchema,
+    EventFrameSchema,
+]);
+export const PromptPayloadSchema = Type.Object({ message: nonEmptyString }, { additionalProperties: false });
+export const GetEntriesPayloadSchema = Type.Object({ since: nonEmptyString }, { additionalProperties: false });
+export const ContactReportPayloadSchema = Type.Object({
+    type: Type.Literal("pi_subagent_report"),
+    parentSessionId: nonEmptyString,
+    childId: nonEmptyString,
+    runtimeIdentity: nonEmptyString,
+    reason: Type.Union([
+        Type.Literal("progress_update"),
+        Type.Literal("important_finding"),
+        Type.Literal("need_decision"),
+        Type.Literal("blocked"),
+    ]),
+    message: nonEmptyString,
+    sessionId: Type.Optional(nonEmptyString),
+}, { additionalProperties: false });
+export const ChildLifecyclePayloadSchema = Type.Object({
+    type: Type.Literal("child_lifecycle"),
+    parentSessionId: nonEmptyString,
+    childId: nonEmptyString,
+    runtimeIdentity: nonEmptyString,
+    kind: Type.Union([
+        Type.Literal("left_session"),
+        Type.Literal("tui_quit"),
+        Type.Literal("user_interrupt"),
+    ]),
+    sessionId: nonEmptyString,
+    message: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+export const PauseReportPayloadSchema = Type.Object({
+    type: Type.Literal("report_paused"),
+    parentSessionId: nonEmptyString,
+    childId: nonEmptyString,
+    runtimeIdentity: nonEmptyString,
+    generation: Type.Integer({ minimum: 1 }),
+}, { additionalProperties: false });
+export function isRunnerOperation(value) {
+    return typeof value === "string" && RUNNER_OPERATIONS.includes(value);
+}
+export function isHelloFrame(value) {
+    return Value.Check(HelloFrameSchema, value);
+}
+export function isHelloAckFrame(value) {
+    return Value.Check(HelloAckFrameSchema, value);
+}
+export function isRequestFrame(value) {
+    return Value.Check(RequestFrameSchema, value);
+}
+export function isContactReportPayload(value) {
+    return Value.Check(ContactReportPayloadSchema, value);
+}
+export function isChildLifecyclePayload(value) {
+    return Value.Check(ChildLifecyclePayloadSchema, value);
+}
+export function isPauseReportPayload(value) {
+    return Value.Check(PauseReportPayloadSchema, value);
+}
+export function isResponseFrame(value) {
+    return Value.Check(ResponseFrameSchema, value);
+}
+export function isEventFrame(value) {
+    return Value.Check(EventFrameSchema, value);
+}
+export function isServerFrame(value) {
+    return Value.Check(ServerFrameSchema, value);
+}
+export function successResponse(id, data) {
+    return {
+        version: PROTOCOL_VERSION,
+        type: "response",
+        id,
+        ok: true,
+        ...(data === undefined ? {} : { data }),
+    };
+}
+export function failureResponse(id, code, message) {
+    return { version: PROTOCOL_VERSION, type: "response", id, ok: false, error: { code, message } };
+}
+export function eventFrame(event) {
+    return { version: PROTOCOL_VERSION, type: "event", event };
+}

package/dist/registry.d.ts

@@ -0,0 +1,41 @@
+import type { RuntimeClaim, SubagentRecord } from "./domain.js";
+export type RegistryErrorCode = "invalid_parent_session" | "corrupt_registry" | "unsupported_version" | "parent_mismatch" | "invalid_record" | "duplicate_child" | "unknown_child" | "stale_revision" | "runtime_mismatch" | "claim_conflict" | "claim_mismatch" | "stopped_child";
+export declare class SubagentRegistryError extends Error {
+    readonly code: RegistryErrorCode;
+    constructor(code: RegistryErrorCode, message: string);
+}
+/**
+ * Per-parent-session JSON registry. It holds only durable facts needed to find and
+ * resume a child: identity, session placement, intent, the non-secret launch
+ * snapshot, and reconnect metadata. Liveness is never inferred from this file, and
+ * no secrets are stored.
+ */
+export interface SubagentRegistry {
+    readonly path: string;
+    readonly parentSessionId: string;
+    get(id: string, signal?: AbortSignal): Promise<SubagentRecord | undefined>;
+    list(signal?: AbortSignal): Promise<readonly SubagentRecord[]>;
+    create(record: SubagentRecord, signal?: AbortSignal): Promise<SubagentRecord>;
+    /**
+     * Conditional write. `expectedRevision` guards against stale writers, and
+     * `expectedRuntimeIdentity` additionally refuses updates whose target runtime has
+     * already been replaced by a newer one. The registry owns `revision` and
+     * `updatedAt`; the updater's values for those fields are ignored.
+     */
+    update(id: string, expectedRevision: number, updater: (record: SubagentRecord) => SubagentRecord, expectedRuntimeIdentity?: string, signal?: AbortSignal): Promise<SubagentRecord>;
+    claim(id: string, expectedRevision: number, claim: RuntimeClaim, expectedRuntimeIdentity?: string, expectedClaimId?: string, signal?: AbortSignal): Promise<SubagentRecord>;
+    markClaimRunner(id: string, claimId: string, runnerPid: number, signal?: AbortSignal): Promise<SubagentRecord>;
+    activateClaim(id: string, claimId: string, runnerPid: number, signal?: AbortSignal): Promise<SubagentRecord>;
+    consumeReconnectClaim(id: string, claimId: string, controllerTokenHash: string, signal?: AbortSignal): Promise<SubagentRecord>;
+    releaseClaim(id: string, claimId: string, signal?: AbortSignal): Promise<SubagentRecord>;
+}
+export interface CreateSubagentRegistryOptions {
+    readonly parentSessionId: string;
+    /** Override for tests and for callers that keep the registry outside the agent dir. */
+    readonly filePath?: string;
+    readonly now?: () => Date;
+}
+export declare function defaultRegistryPath(parentSessionId: string): string;
+/** Strictly revalidates one record read from disk; partial or unknown shapes never become state. */
+export declare function parseSubagentRecord(value: unknown, key: string, parentSessionId: string, path: string): SubagentRecord;
+export declare function createSubagentRegistry(options: CreateSubagentRegistryOptions): SubagentRegistry;