@hheei/pi-subagents 0.7.0 → 0.8.0

package/dist/controller-ipc.js

@@ -0,0 +1,292 @@
+import { chmodSync, unlinkSync } from "node:fs";
+import { createConnection, createServer } from "node:net";
+import { historyEntry } from "./delegation.js";
+import { parseDelegateInput } from "./mcp/delegate.js";
+import { listReceipts } from "./receipts.js";
+import { defaultRegistryPath } from "./registry.js";
+const openSockets = new WeakMap();
+/** Bumped whenever this call surface changes: a client never talks to a controller from another build. */
+export const CONTROLLER_PROTOCOL = 2;
+export async function serveControllerIpc(options) {
+    try {
+        unlinkSync(options.socketPath);
+    }
+    catch {
+        // A leftover socket is removed only when this owner holds the workspace lock.
+    }
+    const waiting = { count: 0 };
+    const filePath = options.statePath ?? defaultRegistryPath(options.parentSessionId);
+    const sockets = new Set();
+    const server = createServer((socket) => {
+        if (sockets.size >= MAX_CONNECTIONS) {
+            socket.destroy();
+            return;
+        }
+        sockets.add(socket);
+        socket.on("error", () => { });
+        const abort = new AbortController();
+        socket.once("close", () => {
+            sockets.delete(socket);
+            abort.abort();
+        });
+        socket.setEncoding("utf8");
+        let buffer = "";
+        socket.on("data", (chunk) => {
+            buffer += chunk;
+            if (Buffer.byteLength(buffer) > MAX_FRAME) {
+                socket.destroy();
+                return;
+            }
+            let newline = buffer.indexOf("\n");
+            while (newline !== -1) {
+                const line = buffer.slice(0, newline);
+                buffer = buffer.slice(newline + 1);
+                newline = buffer.indexOf("\n");
+                void handleLine(socket, line, options.parentSessionId, options.manager, abort.signal, waiting, filePath);
+            }
+        });
+    });
+    openSockets.set(server, sockets);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.socketPath, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    chmodSync(options.socketPath, 0o600);
+    return server;
+}
+/** Stops listening and drops open calls. `server.close()` alone waits until every wait:true socket ends. */
+export function closeControllerIpc(server) {
+    const sockets = openSockets.get(server);
+    return new Promise((resolve, reject) => {
+        server.close((error) => {
+            openSockets.delete(server);
+            if (error === undefined)
+                resolve();
+            else
+                reject(error);
+        });
+        if (sockets !== undefined) {
+            for (const socket of sockets)
+                socket.destroy();
+        }
+    });
+}
+/** The call surface of the controller listening here. Only an actual answer can be foreign. */
+export async function controllerProtocol(socketPath) {
+    try {
+        const reply = await callController(socketPath, { op: "protocol", input: {} }, AbortSignal.timeout(2_000));
+        const result = reply.result;
+        if (reply.ok !== true || typeof result !== "object" || result === null)
+            return { state: "foreign" };
+        const protocol = "protocol" in result ? result.protocol : undefined;
+        return typeof protocol === "number" ? { state: "ready", protocol } : { state: "foreign" };
+    }
+    catch {
+        return { state: "silent" };
+    }
+}
+export function callController(socketPath, call, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason instanceof Error ? signal.reason : new Error("Controller call aborted"));
+            return;
+        }
+        const socket = createConnection(socketPath);
+        let buffer = "";
+        let settled = false;
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", onAbort);
+            socket.removeAllListeners();
+            socket.on("error", () => { });
+            socket.destroy();
+            if (outcome.error !== undefined)
+                reject(outcome.error);
+            else if (outcome.reply !== undefined)
+                resolve(outcome.reply);
+            else
+                reject(new Error("Controller closed the connection without a reply"));
+        };
+        const onAbort = () => {
+            const reason = signal?.reason;
+            finish({ error: reason instanceof Error ? reason : new Error("Controller call aborted") });
+        };
+        socket.setEncoding("utf8");
+        socket.on("error", (error) => finish({ error }));
+        socket.on("data", (chunk) => {
+            buffer += chunk;
+            const newline = buffer.indexOf("\n");
+            if (newline === -1)
+                return;
+            try {
+                finish({ reply: parseReply(JSON.parse(buffer.slice(0, newline))) });
+            }
+            catch (error) {
+                finish({ error: error instanceof Error ? error : new Error(String(error)) });
+            }
+        });
+        socket.on("end", () => finish({}));
+        socket.on("close", () => finish({}));
+        if (signal !== undefined)
+            signal.addEventListener("abort", onAbort, { once: true });
+        socket.write(`${JSON.stringify(call)}\n`);
+    });
+}
+async function handleLine(socket, line, parentSessionId, manager, signal, waiting, filePath) {
+    let reply;
+    try {
+        const call = parseCall(JSON.parse(line));
+        reply = {
+            ok: true,
+            result: await dispatch(call, parentSessionId, manager, signal, waiting, filePath),
+        };
+    }
+    catch (error) {
+        reply = {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (socket.destroyed || !socket.writable)
+        return;
+    socket.write(`${JSON.stringify(reply)}\n`, (error) => {
+        if (error !== undefined && error !== null)
+            socket.destroy();
+    });
+}
+const MAX_FRAME = 1024 * 1024;
+const MAX_CONNECTIONS = 16;
+const MAX_WAITING = 12;
+async function dispatch(call, parentSessionId, manager, signal, waiting, filePath) {
+    switch (call.op) {
+        case "protocol":
+            return { protocol: CONTROLLER_PROTOCOL };
+        case "receipts": {
+            const page = listReceipts(filePath, parentSessionId, numberField(call.input, "cursor"), numberField(call.input, "limit", 50) || 20);
+            return {
+                receipts: page.receipts.flatMap((receipt) => {
+                    const entry = historyEntry(receipt);
+                    return entry === undefined ? [] : [entry];
+                }),
+                ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
+            };
+        }
+        case "get": {
+            const revision = numberField(call.input, "revision");
+            return manager.inspect({
+                id: stringField(call.input, "id"),
+                ...(revision === 0 ? {} : { revision }),
+                includeOutput: booleanField(call.input, "includeOutput"),
+            });
+        }
+        case "list":
+            return manager.dashboard();
+        case "stop":
+            return manager.stopAgent(stringField(call.input, "id"));
+        case "transcript":
+            return transcriptPage(manager, stringField(call.input, "id"), call.input);
+        case "delegate": {
+            const input = parseDelegateInput(call.input);
+            return runDelegation(manager, input, signal, waiting);
+        }
+        default:
+            throw new Error(`Unknown controller operation ${call.op}`);
+    }
+}
+async function runDelegation(manager, input, signal, waiting) {
+    const wait = input.wait !== false;
+    if (wait && waiting.count >= MAX_WAITING) {
+        throw new Error("Controller is busy with waiting delegations");
+    }
+    if (wait)
+        waiting.count += 1;
+    try {
+        return await manager.delegate(input, signal);
+    }
+    finally {
+        if (wait)
+            waiting.count -= 1;
+    }
+}
+function parseCall(value) {
+    if (typeof value !== "object" || value === null)
+        throw new Error("Invalid controller call");
+    const record = value;
+    if (!isOp(record.op))
+        throw new Error("Invalid controller call");
+    return { op: record.op, input: record.input };
+}
+const OPS = [
+    "protocol",
+    "delegate",
+    "receipts",
+    "get",
+    "list",
+    "stop",
+    "transcript",
+];
+function isOp(value) {
+    return typeof value === "string" && OPS.includes(value);
+}
+function parseReply(value) {
+    if (typeof value !== "object" || value === null)
+        throw new Error("Invalid controller reply");
+    const record = value;
+    if (typeof record.ok !== "boolean")
+        throw new Error("Invalid controller reply");
+    return {
+        ok: record.ok,
+        ...(record.result === undefined ? {} : { result: record.result }),
+        ...(typeof record.error === "string" ? { error: record.error } : {}),
+    };
+}
+async function transcriptPage(manager, id, input) {
+    const cursor = numberField(input, "cursor");
+    const limit = numberField(input, "limit", 50) || 20;
+    const page = await manager.getEntries(id, { cursor, limit });
+    if (page === undefined)
+        throw new Error(`Unknown child ${id}`);
+    return {
+        id,
+        entries: page.entries.map(boundedEntry),
+        ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
+    };
+}
+function boundedEntry(entry) {
+    try {
+        const text = JSON.stringify(entry);
+        if (text === undefined)
+            return null;
+        if (text.length <= 4000)
+            return JSON.parse(text);
+        return { truncated: true, text: text.slice(0, 4000) };
+    }
+    catch {
+        return String(entry);
+    }
+}
+function record(input) {
+    return typeof input === "object" && input !== null
+        ? input
+        : undefined;
+}
+function stringField(input, key) {
+    const value = record(input)?.[key];
+    if (typeof value !== "string" || value === "")
+        throw new Error(`${key} is required`);
+    return value;
+}
+function numberField(input, key, cap) {
+    const value = record(input)?.[key];
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0)
+        return 0;
+    return cap === undefined ? value : Math.min(value, cap);
+}
+function booleanField(input, key) {
+    return record(input)?.[key] === true;
+}

package/dist/controller-main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/controller-main.js

@@ -0,0 +1,26 @@
+import { StandaloneControllerError, startStandaloneController } from "./controller.js";
+import { STANDALONE_CONTROLLER_ENV_KEY } from "./domain.js";
+process.env[STANDALONE_CONTROLLER_ENV_KEY] = "1";
+const workspace = process.argv[2];
+const agentDir = process.argv[3];
+if (workspace === undefined || agentDir === undefined) {
+    console.error("usage: controller <workspace> <agent-dir>");
+    process.exit(2);
+}
+try {
+    const controller = await startStandaloneController({ workspace, agentDir });
+    console.log(`ready ${controller.socketPath}`);
+    const stop = () => {
+        void controller.dispose().then(() => process.exit(0), (error) => {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        });
+    };
+    process.on("SIGTERM", stop);
+    process.on("SIGINT", stop);
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(error instanceof StandaloneControllerError ? `${error.code} ${message}` : message);
+    process.exit(1);
+}

package/dist/controller-role.d.ts

@@ -0,0 +1,40 @@
+import type { SkillCatalogEntry } from "./agent-resolver.js";
+import type { DashboardView, DelegationView } from "./delegation.js";
+import type { DelegateSubagentInput, OperationError, PublicSubagent } from "./domain.js";
+import type { ParentChannel } from "./manager.js";
+export interface ControllerManager {
+    delegate(input: DelegateSubagentInput & {
+        readonly wait?: boolean;
+    }, signal?: AbortSignal): Promise<DelegationView | OperationError>;
+    inspect(input: {
+        readonly id: string;
+        readonly revision?: number;
+        readonly includeOutput?: boolean;
+    }): Promise<DelegationView | OperationError>;
+    dashboard(): Promise<DashboardView>;
+    stopAgent(id: string): Promise<DelegationView | OperationError>;
+    get(id: string): Promise<PublicSubagent | OperationError>;
+    list(): Promise<readonly PublicSubagent[]>;
+    stop(id: string): Promise<PublicSubagent | OperationError>;
+    getEntries(id: string, range?: {
+        readonly cursor?: number;
+        readonly limit?: number;
+    }): Promise<{
+        readonly entries: readonly unknown[];
+        readonly nextCursor?: number;
+    } | undefined>;
+}
+/** In-process ownership for one standalone controller. Print mode is not this signal. */
+export interface ControllerRole extends ParentChannel {
+    readonly skills: readonly SkillCatalogEntry[];
+    applied: boolean;
+    modelId?: string;
+    provider?: string;
+    credential: "present" | "missing";
+    readonly manager: Promise<ControllerManager>;
+    bindManager(manager: ControllerManager): void;
+    dispose(): void;
+}
+export declare function beginControllerRole(skills: readonly SkillCatalogEntry[]): ControllerRole;
+export declare function activeControllerRole(): ControllerRole | undefined;
+export declare function endControllerRole(role: ControllerRole): void;

package/dist/controller-role.js

@@ -0,0 +1,37 @@
+let current;
+export function beginControllerRole(skills) {
+    if (current !== undefined)
+        throw new Error("Standalone controller role is already active");
+    let closed = false;
+    let resolveManager;
+    const manager = new Promise((resolve) => {
+        resolveManager = resolve;
+    });
+    const role = {
+        skills,
+        applied: false,
+        credential: "missing",
+        manager,
+        bindManager(value) {
+            resolveManager?.(value);
+        },
+        deliver() {
+            if (closed)
+                return Promise.reject(new Error("Standalone controller report sink is closed"));
+            return Promise.resolve();
+        },
+        dispose() {
+            closed = true;
+        },
+    };
+    current = role;
+    return role;
+}
+export function activeControllerRole() {
+    return current;
+}
+export function endControllerRole(role) {
+    role.dispose();
+    if (current === role)
+        current = undefined;
+}

package/dist/controller-socket.d.ts

@@ -0,0 +1,6 @@
+export declare function createControllerSocket(options: {
+    readonly locate: () => string;
+    readonly ready: (socketPath: string) => Promise<boolean>;
+    readonly start: () => Promise<string>;
+}): () => Promise<string>;
+export declare function retryableControllerStart(error: Error): boolean;

package/dist/controller-socket.js

@@ -0,0 +1,43 @@
+export function createControllerSocket(options) {
+    let opening;
+    return () => {
+        if (opening !== undefined)
+            return opening;
+        const attempt = openControllerSocket(options).finally(() => {
+            if (opening === attempt)
+                opening = undefined;
+        });
+        opening = attempt;
+        return attempt;
+    };
+}
+export function retryableControllerStart(error) {
+    const message = error.message;
+    return (message.startsWith("busy ") ||
+        message.includes("already running") ||
+        message.includes("not accepting connections"));
+}
+async function openControllerSocket(options) {
+    const socketPath = options.locate();
+    let lastError;
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+        if (await options.ready(socketPath))
+            return socketPath;
+        try {
+            const started = await options.start();
+            if (await options.ready(started))
+                return started;
+            throw new Error("Controller announced a socket that is not accepting connections");
+        }
+        catch (error) {
+            const wrapped = error instanceof Error ? error : new Error(String(error));
+            if (await options.ready(socketPath))
+                return socketPath;
+            if (!retryableControllerStart(wrapped))
+                throw wrapped;
+            lastError = wrapped;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    throw lastError ?? new Error("Controller socket did not become ready");
+}

package/dist/controller.d.ts

@@ -0,0 +1,25 @@
+export type StandaloneControllerFailure = "busy" | "model_unavailable";
+export declare class StandaloneControllerError extends Error {
+    readonly code: StandaloneControllerFailure;
+    readonly parentSessionId: string | undefined;
+    constructor(code: StandaloneControllerFailure, message: string, parentSessionId?: string);
+}
+export interface StandaloneController {
+    readonly workspace: string;
+    readonly parentSessionId: string;
+    readonly sessionFile: string;
+    readonly socketPath: string;
+    dispose(): Promise<void>;
+}
+export declare function controllerSocketPath(agentDir: string, workspace: string): string;
+export declare function startStandaloneController(options: {
+    readonly workspace: string;
+    readonly agentDir: string;
+}): Promise<StandaloneController>;
+/**
+ * A controller left behind by an earlier build keeps this workspace's socket and lock. Its calls are
+ * not this build's to make, so it is stopped here and the caller starts its own.
+ */
+export declare function stopPreviousController(agentDir: string, workspace: string, expectedPid?: number): Promise<void>;
+/** Pid recorded for this workspace, when the binding names one. */
+export declare function recordedControllerPid(agentDir: string, workspace: string): number | undefined;