@hheei/pi-subagents 0.1.2 → 0.2.2

package/package.json

@@ -1,53 +1,52 @@
 {
-	"name": "@hheei/pi-subagents",
-	"version": "0.1.2",
-	"description": "Independent background Pi subagent sessions with durable identity and RPC control.",
-	"type": "module",
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
-	"exports": {
-		".": "./dist/index.js"
-	},
-	"files": [
-		"dist",
-		"README.md",
-		"LICENSE"
-	],
-	"pi": {
-		"extensions": [
-			"dist/extension.js"
-		]
-	},
-	"scripts": {
-		"prepack": "pnpm run build",
-		"build": "node -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json"
-	},
-	"keywords": [
-		"pi",
-		"pi-package",
-		"pi-extension",
-		"hepi",
-		"subagents"
-	],
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/hheei/hepi-mono.git",
-		"directory": "packages/pi-subagents"
-	},
-	"publishConfig": {
-		"access": "public"
-	},
-	"dependencies": {
-		"@hheei/pi-ext-core": "workspace:^0.1.1",
-		"typebox": "1.3.27"
-	},
-	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": ">=0.87.0",
-		"@earendil-works/pi-tui": ">=0.87.0"
-	},
-	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "0.87.0",
-		"@earendil-works/pi-tui": "0.87.0"
-	}
-}
+  "name": "@hheei/pi-subagents",
+  "version": "0.2.2",
+  "description": "Independent background Pi subagent sessions with durable identity and RPC control.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "dist/extension.js"
+    ]
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "hepi",
+    "subagents"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hheei/hepi-mono.git",
+    "directory": "packages/pi-subagents"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hheei/pi-ext-core": "^0.2.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=1.0.0",
+    "@earendil-works/pi-tui": ">=1.0.0",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0"
+  },
+  "scripts": {
+    "build": "node -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json"
+  }
+}

package/dist/child-nudge.d.ts

@@ -1,24 +0,0 @@
-/**
- * Child-side completion reminder.
- *
- * Adapted from HazAT/maplezzk pi-interactive-subagents `subagent-done.ts`
- * (MIT, upstream 7a5c96be138158a5cf6413ac819509eff12b1ccd). This version
- * reminds the child to call `contact_parent` and never exits the session.
- */
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-/** Return true only when the latest assistant message ended by the model stopping normally. */
-export declare function shouldScheduleAgentEndNudge(messages: readonly {
-    role?: string;
-    stopReason?: string;
-}[] | undefined): boolean;
-export interface ChildNudgeController {
-    markReported(): void;
-    listen(pi: ExtensionAPI): void;
-    dispose(): void;
-}
-/** Owns the delay timer and the “already reported / user took over” gates. */
-export declare function createChildNudgeController(options?: {
-    readonly delayMs?: number;
-    readonly disabled?: boolean;
-}): ChildNudgeController;
-export declare function registerChildNudge(pi: ExtensionAPI): ChildNudgeController;

package/dist/child-nudge.js

@@ -1,102 +0,0 @@
-import { isRecord } from "./domain.js";
-const ASSISTANT_ROLE = "assistant";
-const NORMAL_STOP_REASON = "stop";
-const DEFAULT_NUDGE_DELAY_MS = 5_000;
-const MIN_NUDGE_DELAY_MS = 1_000;
-const NUDGE_TEXT = "You finished a turn without calling contact_parent. If the parent needs a progress update, important finding, decision, or blocker, call contact_parent now. Do not wait for the parent to poll you.";
-/** Return true only when the latest assistant message ended by the model stopping normally. */
-export function shouldScheduleAgentEndNudge(messages) {
-    if (messages === undefined || messages.length === 0)
-        return false;
-    for (let index = messages.length - 1; index >= 0; index--) {
-        const message = messages[index];
-        if (message?.role !== ASSISTANT_ROLE)
-            continue;
-        return message.stopReason === NORMAL_STOP_REASON;
-    }
-    return false;
-}
-function parseNudgeDelayMs(rawValue) {
-    const parsed = Number.parseInt(rawValue ?? "", 10);
-    if (!Number.isFinite(parsed))
-        return DEFAULT_NUDGE_DELAY_MS;
-    return Math.max(MIN_NUDGE_DELAY_MS, parsed);
-}
-function agentEndMessages(event) {
-    if (!isRecord(event) || !Array.isArray(event.messages))
-        return undefined;
-    const messages = [];
-    for (const item of event.messages) {
-        if (!isRecord(item))
-            continue;
-        messages.push({
-            ...(typeof item.role === "string" ? { role: item.role } : {}),
-            ...(typeof item.stopReason === "string" ? { stopReason: item.stopReason } : {}),
-        });
-    }
-    return messages;
-}
-/** Owns the delay timer and the “already reported / user took over” gates. */
-export function createChildNudgeController(options = {}) {
-    const delayMs = options.delayMs ?? parseNudgeDelayMs(process.env.PI_SUBAGENTS_NUDGE_DELAY_MS);
-    const disabled = options.disabled ?? process.env.PI_SUBAGENTS_NUDGE_DISABLE === "1";
-    let reported = false;
-    let userInputAfterAgentEnd = false;
-    let agentStarted = false;
-    let userTookOver = false;
-    let timer = null;
-    const clearTimer = () => {
-        if (timer === null)
-            return;
-        clearTimeout(timer);
-        timer = null;
-    };
-    return {
-        markReported() {
-            reported = true;
-            clearTimer();
-        },
-        listen(pi) {
-            pi.on("input", () => {
-                userInputAfterAgentEnd = true;
-                clearTimer();
-                if (agentStarted)
-                    userTookOver = true;
-            });
-            pi.on("before_agent_start", () => {
-                clearTimer();
-            });
-            pi.on("agent_start", () => {
-                agentStarted = true;
-                reported = false;
-                userInputAfterAgentEnd = false;
-                clearTimer();
-            });
-            pi.on("agent_end", (event) => {
-                if (disabled || reported || userTookOver) {
-                    clearTimer();
-                    return;
-                }
-                if (!shouldScheduleAgentEndNudge(agentEndMessages(event))) {
-                    clearTimer();
-                    return;
-                }
-                clearTimer();
-                timer = setTimeout(() => {
-                    timer = null;
-                    if (reported || userInputAfterAgentEnd || userTookOver)
-                        return;
-                    pi.sendUserMessage(NUDGE_TEXT, { deliverAs: "followUp" });
-                }, delayMs);
-            });
-        },
-        dispose() {
-            clearTimer();
-        },
-    };
-}
-export function registerChildNudge(pi) {
-    const controller = createChildNudgeController();
-    controller.listen(pi);
-    return controller;
-}

package/dist/connector.d.ts

@@ -1,53 +0,0 @@
-import { type ChildIdentity } from "./domain.js";
-import { type RunnerOperation } from "./protocol.js";
-export interface RunnerConnectionOptions {
-    /** Unix socket path published by the runner. */
-    readonly endpoint: string;
-    readonly identity: ChildIdentity;
-    readonly token: string;
-    readonly maxFrameBytes?: number;
-    readonly maxPendingRequests?: number;
-    readonly requestTimeoutMs?: number;
-    readonly connectTimeoutMs?: number;
-    readonly role?: "controller" | "reporter" | "recovery" | "bridge";
-    readonly claimId?: string;
-}
-/**
- * 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 declare class RunnerConnection {
-    #private;
-    constructor(options: RunnerConnectionOptions);
-    connect(signal?: AbortSignal): Promise<void>;
-    get connected(): boolean;
-    request(operation: RunnerOperation, payload?: unknown, options?: {
-        readonly signal?: AbortSignal;
-        readonly timeoutMs?: number;
-    }): Promise<unknown>;
-    onEvent(listener: (event: unknown) => void): () => void;
-    /**
-     * Releases the local socket, reader, listeners and in-flight requests. The
-     * runner keeps running and can be reconnected from the same identity.
-     */
-    close(): void;
-}
-/** Sends one child report through a short-lived authenticated reporter connection. */
-export declare function sendReportToRunner(identity: ChildIdentity, report: unknown, signal?: AbortSignal): Promise<void>;
-/** Sends one child lifecycle event through a short-lived authenticated reporter connection. */
-export declare function sendLifecycleToRunner(identity: ChildIdentity, payload: unknown, signal?: AbortSignal): Promise<void>;
-/**
- * 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 declare function connectWithRetry(connection: Pick<RunnerConnection, "connect">, options?: {
-    readonly attempts?: number;
-    readonly delayMs?: number;
-    readonly signal?: AbortSignal;
-}): Promise<void>;

package/dist/connector.js

@@ -1,283 +0,0 @@
-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/pause-gate.d.ts

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,64 +0,0 @@
-/**
- * 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);
-    }
-}