@hheei/pi-subagents 0.1.2

package/dist/extension.js

@@ -0,0 +1,145 @@
+import { registerExtensionLifecycle } from "@hheei/pi-ext-core";
+import { registerChildBridge } from "./child-bridge.js";
+import { bindParentStatus, registerParentCommands } from "./commands.js";
+import { BRIDGE_ENVIRONMENT_KEYS, isThinkingLevel } from "./domain.js";
+import { createCmuxHostAdapter, createHerdrHostAdapter, selectHostAdapter, } from "./host-adapter.js";
+import { SubagentManager } from "./manager.js";
+import { createSubagentRegistry } from "./registry.js";
+import { createRuntimeTokenStore, launchDetachedRunner, recoverDetachedRunner } from "./runtime.js";
+import { persistSubagentIntent, resolveSubagentLaunch } from "./session-bootstrap.js";
+import { registerParentTools } from "./tools.js";
+import { createSubagentWidget } from "./widget.js";
+const CHILD_ENV_KEYS = Object.values(BRIDGE_ENVIRONMENT_KEYS);
+function requiredBridgeValue(env, key) {
+    const value = env[key];
+    if (typeof value !== "string" || value === "") {
+        throw new Error("Invalid partial pi-subagents child identity environment");
+    }
+    return value;
+}
+function childIdentityFromEnv(env) {
+    const present = CHILD_ENV_KEYS.filter((key) => env[key] !== undefined);
+    if (present.length === 0)
+        return undefined;
+    return {
+        parentSessionId: requiredBridgeValue(env, BRIDGE_ENVIRONMENT_KEYS.parentSessionId),
+        subagentId: requiredBridgeValue(env, BRIDGE_ENVIRONMENT_KEYS.childId),
+        runtimeIdentity: requiredBridgeValue(env, BRIDGE_ENVIRONMENT_KEYS.runtimeId),
+        endpoint: requiredBridgeValue(env, BRIDGE_ENVIRONMENT_KEYS.endpoint),
+        token: requiredBridgeValue(env, BRIDGE_ENVIRONMENT_KEYS.token),
+    };
+}
+export default function piSubagentsExtension(pi) {
+    const child = childIdentityFromEnv(process.env);
+    if (child !== undefined) {
+        registerChildBridge(pi, child);
+        return;
+    }
+    registerExtensionLifecycle(pi, {
+        key: "@hheei/pi-subagents",
+        async start(runtime) {
+            const context = runtime.extension;
+            const parentSessionId = context.sessionManager.getSessionId();
+            const registry = createSubagentRegistry({ parentSessionId });
+            const tokens = createRuntimeTokenStore();
+            const channel = {
+                async deliver(report) {
+                    pi.sendMessage({
+                        customType: "pi-subagent-report",
+                        content: `[Subagent ${report.agent} ${report.childId}: ${report.reason}]\n${report.message}`,
+                        display: true,
+                        details: report,
+                    }, { triggerTurn: true, deliverAs: "nextTurn" });
+                },
+            };
+            let manager;
+            const ownsAttachment = (identity) => manager.ownsHostAttachment(identity);
+            manager = new SubagentManager({
+                parentSessionId,
+                registry,
+                channel,
+                tokens,
+                async resolve(input) {
+                    const model = context.model;
+                    if (model === undefined)
+                        throw new Error("No parent model is selected");
+                    const thinking = context.thinkingLevel ?? pi.getThinkingLevel();
+                    if (!isThinkingLevel(thinking)) {
+                        throw new Error(`Unsupported parent thinking level: ${thinking}`);
+                    }
+                    return resolveSubagentLaunch({
+                        input,
+                        cwd: context.cwd,
+                        modelRegistry: context.modelRegistry,
+                        parent: {
+                            model: { provider: model.provider, id: model.id },
+                            thinking,
+                        },
+                    });
+                },
+                bootstrap(input) {
+                    return persistSubagentIntent({ registry, ...input });
+                },
+                launch(record) {
+                    return launchDetachedRunner({
+                        registry,
+                        record,
+                        tokens,
+                        signal: runtime.signal,
+                    });
+                },
+                connect(record) {
+                    return recoverDetachedRunner({
+                        registry,
+                        record,
+                        tokens,
+                        signal: runtime.signal,
+                    });
+                },
+                attachHost: {
+                    select(preferredHost) {
+                        return selectHostAdapter({
+                            adapters: {
+                                herdr: createHerdrHostAdapter({
+                                    ownerId: parentSessionId,
+                                    ownsAttachment,
+                                }),
+                                cmux: createCmuxHostAdapter({
+                                    ownerId: parentSessionId,
+                                    ownsAttachment,
+                                }),
+                            },
+                            ...(preferredHost === undefined ? {} : { preferredHost }),
+                        });
+                    },
+                },
+            });
+            const recovery = await manager.recover();
+            if (recovery.failures.length > 0) {
+                pi.sendMessage({
+                    customType: "pi-subagent-recovery-failure",
+                    content: `Subagent recovery failed:\n${recovery.failures
+                        .map((failure) => `- ${failure.childId}: ${failure.reason}`)
+                        .join("\n")}`,
+                    display: true,
+                    details: recovery.failures,
+                }, { triggerTurn: false });
+            }
+            registerParentTools(pi, manager);
+            registerParentCommands(pi, manager);
+            const widget = createSubagentWidget(pi, context, runtime.signal);
+            const refreshWidget = () => {
+                void manager.list().then((children) => widget?.refresh(children));
+            };
+            const unsubscribe = manager.onChange(refreshWidget);
+            const unbindStatus = bindParentStatus(pi, context, manager);
+            refreshWidget();
+            runtime.resources.add("subagent-widget", () => {
+                unsubscribe();
+                unbindStatus();
+                widget?.dispose();
+            });
+            runtime.resources.add("subagent-manager", () => manager.closeLocalConnections());
+        },
+    });
+}

package/dist/host-adapter.d.ts

@@ -0,0 +1,76 @@
+import type { LaunchSpec } from "./launch-spec.js";
+export type HostKind = "herdr" | "cmux";
+/** Where a host command failed: session/env, layout, or the launch command itself. */
+export type HostFailureClass = "environment" | "pane" | "command";
+export interface HostCommandResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number | null;
+    readonly timedOut: boolean;
+}
+export interface HostCommandRunner {
+    run(command: string, args: readonly string[], options?: {
+        readonly timeoutMs?: number;
+    }): Promise<HostCommandResult>;
+}
+export interface HostCapability {
+    readonly host: HostKind;
+    readonly available: boolean;
+    readonly reason: string;
+}
+export type HostSelection = {
+    readonly available: true;
+    readonly selectedHost: HostKind;
+    readonly adapter: HostAdapter;
+    readonly explicit: boolean;
+    readonly reason: string;
+    readonly attempts: readonly HostCapability[];
+} | {
+    readonly available: false;
+    readonly selectedHost: null;
+    readonly explicit: boolean;
+    readonly reason: string;
+    readonly attempts: readonly HostCapability[];
+};
+export interface HostAttachmentIdentity {
+    readonly host: HostKind;
+    readonly attachmentId: string;
+    readonly createdBy: string;
+}
+export interface HostObservation {
+    readonly identity: HostAttachmentIdentity;
+    readonly alive: boolean;
+    readonly known: boolean;
+    readonly detail: string;
+}
+export interface HostAttachment {
+    readonly identity: HostAttachmentIdentity;
+    readonly launch: HostCommandResult;
+    observe(): Promise<HostObservation>;
+    cleanup(): Promise<HostCommandResult>;
+}
+export interface HostAdapter {
+    readonly kind: HostKind;
+    probe(): Promise<HostCapability>;
+    attach(spec: LaunchSpec): Promise<HostAttachment>;
+}
+export interface SelectHostAdapterOptions {
+    readonly adapters: Readonly<Record<HostKind, HostAdapter>>;
+    readonly preferredHost?: HostKind;
+}
+/** Selects a presentation host visibly; an explicit unavailable host never falls back. */
+export declare function selectHostAdapter(options: SelectHostAdapterOptions): Promise<HostSelection>;
+export declare class HostCommandError extends Error {
+    readonly kind: HostFailureClass;
+    readonly result: HostCommandResult;
+    constructor(kind: HostFailureClass, message: string, result: HostCommandResult);
+}
+export declare const systemHostCommandRunner: HostCommandRunner;
+export interface HostAdapterOptions {
+    readonly runner?: HostCommandRunner;
+    readonly ownerId: string;
+    readonly ownsAttachment: (identity: HostAttachmentIdentity) => boolean;
+    readonly timeoutMs?: number;
+}
+export declare function createHerdrHostAdapter(options: HostAdapterOptions): HostAdapter;
+export declare function createCmuxHostAdapter(options: HostAdapterOptions): HostAdapter;

package/dist/host-adapter.js

@@ -0,0 +1,323 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const DEFAULT_HOST_ORDER = ["herdr", "cmux"];
+/** Selects a presentation host visibly; an explicit unavailable host never falls back. */
+export async function selectHostAdapter(options) {
+    const explicit = options.preferredHost !== undefined;
+    const order = explicit ? [options.preferredHost] : DEFAULT_HOST_ORDER;
+    const attempts = [];
+    for (const host of order) {
+        const adapter = options.adapters[host];
+        const capability = await adapter.probe();
+        attempts.push(capability);
+        if (capability.available) {
+            const priorFailures = attempts
+                .slice(0, -1)
+                .map((attempt) => `${attempt.host}: ${attempt.reason}`)
+                .join("; ");
+            return {
+                available: true,
+                selectedHost: host,
+                adapter,
+                explicit,
+                reason: priorFailures === ""
+                    ? `${explicit ? "explicit" : "default"} host ${host} is available`
+                    : `selected ${host} after ${priorFailures}`,
+                attempts,
+            };
+        }
+    }
+    const failure = attempts.map((attempt) => `${attempt.host}: ${attempt.reason}`).join("; ");
+    return {
+        available: false,
+        selectedHost: null,
+        explicit,
+        reason: explicit
+            ? `explicit host unavailable: ${failure}`
+            : `no presentation host available: ${failure}`,
+        attempts,
+    };
+}
+export class HostCommandError extends Error {
+    kind;
+    result;
+    constructor(kind, message, result) {
+        super(message);
+        this.name = "HostCommandError";
+        this.kind = kind;
+        this.result = result;
+    }
+}
+export const systemHostCommandRunner = {
+    async run(command, args, options = {}) {
+        try {
+            const result = await execFileAsync(command, [...args], {
+                timeout: options.timeoutMs,
+                maxBuffer: 1024 * 1024,
+                windowsHide: true,
+            });
+            return { stdout: result.stdout, stderr: result.stderr, exitCode: 0, timedOut: false };
+        }
+        catch (error) {
+            const value = error;
+            if (value.code === "ENOENT") {
+                return {
+                    stdout: "",
+                    stderr: `command not found: ${command}`,
+                    exitCode: 127,
+                    timedOut: false,
+                };
+            }
+            return {
+                stdout: value.stdout ?? "",
+                stderr: value.stderr ?? value.message ?? String(error),
+                exitCode: typeof value.code === "number" ? value.code : null,
+                timedOut: value.killed === true,
+            };
+        }
+    },
+};
+export function createHerdrHostAdapter(options) {
+    const runner = options.runner ?? systemHostCommandRunner;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    return {
+        kind: "herdr",
+        async probe() {
+            if (process.env.HERDR_ENV !== "1") {
+                return { host: "herdr", available: false, reason: "HERDR_ENV is not 1" };
+            }
+            const current = await runner.run("herdr", ["pane", "current", "--current"], { timeoutMs });
+            if (current.timedOut) {
+                return { host: "herdr", available: false, reason: "herdr pane probe timed out" };
+            }
+            if (current.exitCode === 127) {
+                return { host: "herdr", available: false, reason: current.stderr };
+            }
+            if (current.exitCode !== 0) {
+                return {
+                    host: "herdr",
+                    available: false,
+                    reason: `herdr pane probe failed: ${current.stderr}`,
+                };
+            }
+            const pane = parseHerdrPaneId(current.stdout);
+            return pane === undefined
+                ? { host: "herdr", available: false, reason: "herdr probe returned no current pane id" }
+                : { host: "herdr", available: true, reason: `current pane ${pane}` };
+        },
+        async attach(spec) {
+            const current = await runner.run("herdr", ["pane", "current", "--current"], { timeoutMs });
+            const parentPane = parseHerdrPaneId(current.stdout);
+            if (parentPane === undefined) {
+                throw new HostCommandError("pane", "herdr current pane unavailable", current);
+            }
+            const split = await runner.run("herdr", herdrSplitArgs(parentPane, spec), { timeoutMs });
+            const childPane = parseHerdrPaneId(split.stdout);
+            if (childPane === undefined) {
+                throw new HostCommandError("pane", "herdr split returned no child pane id", split);
+            }
+            // pane run sends text+Enter to the new shell. Timeout is not rollback: the pane
+            // already exists and the process may still start after the CLI deadline.
+            const launch = await runner.run("herdr", ["pane", "run", childPane, quotedArgv(spec.command, spec.argv)], { timeoutMs });
+            return hostAttachment({
+                identity: { host: "herdr", attachmentId: childPane, createdBy: options.ownerId },
+                launch,
+                noun: "pane",
+                observe: () => runner.run("herdr", ["pane", "process-info", "--pane", childPane], { timeoutMs }),
+                isAlive: (result) => result.exitCode === 0 && herdrChildProcessIsRunning(result.stdout),
+                close: () => runner.run("herdr", ["pane", "close", childPane], { timeoutMs }),
+                ownsAttachment: options.ownsAttachment,
+            });
+        },
+    };
+}
+export function createCmuxHostAdapter(options) {
+    const runner = options.runner ?? systemHostCommandRunner;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    return {
+        kind: "cmux",
+        async probe() {
+            const ping = await runner.run("cmux", ["ping"], { timeoutMs });
+            if (ping.timedOut)
+                return { host: "cmux", available: false, reason: "cmux ping timed out" };
+            if (ping.exitCode !== 0) {
+                return { host: "cmux", available: false, reason: `cmux unavailable: ${ping.stderr}` };
+            }
+            const capabilities = await runner.run("cmux", ["capabilities", "--json"], { timeoutMs });
+            if (capabilities.timedOut || capabilities.exitCode !== 0) {
+                return { host: "cmux", available: false, reason: "cmux capability query failed" };
+            }
+            return { host: "cmux", available: true, reason: "cmux responded and exposed capabilities" };
+        },
+        async attach(spec) {
+            const launch = await runner.run("cmux", ["--json", "new-split", "right", "--command", cmuxLaunchCommand(spec)], { timeoutMs });
+            const attachmentId = parseCmuxSurfaceId(launch.stdout);
+            if (attachmentId === undefined) {
+                throw new HostCommandError("pane", "cmux split returned no surface id; process state is unknown", launch);
+            }
+            return hostAttachment({
+                identity: { host: "cmux", attachmentId, createdBy: options.ownerId },
+                launch,
+                noun: "surface",
+                observe: () => runner.run("cmux", ["--json", "list-panels"], { timeoutMs }),
+                isAlive: (result) => result.exitCode === 0 && containsString(result.stdout, attachmentId),
+                close: () => runner.run("cmux", ["--json", "close-surface", "--surface", attachmentId], {
+                    timeoutMs,
+                }),
+                ownsAttachment: options.ownsAttachment,
+            });
+        },
+    };
+}
+function hostAttachment(options) {
+    const observe = async () => {
+        const result = await options.observe();
+        return {
+            identity: options.identity,
+            alive: !result.timedOut && options.isAlive(result),
+            known: !result.timedOut,
+            detail: result.stderr || result.stdout,
+        };
+    };
+    return {
+        identity: options.identity,
+        launch: options.launch,
+        observe,
+        async cleanup() {
+            if (!options.ownsAttachment(options.identity)) {
+                return failedResult(`${options.noun} ownership was revoked`);
+            }
+            const observed = await observe();
+            if (!options.ownsAttachment(options.identity)) {
+                return failedResult(`${options.noun} ownership was revoked during observation`);
+            }
+            if (!observed.known) {
+                return failedResult(`${options.noun} observation timed out; not closing`);
+            }
+            return options.close();
+        },
+    };
+}
+function herdrSplitArgs(parentPane, spec) {
+    const args = [
+        "pane",
+        "split",
+        "--pane",
+        parentPane,
+        "--direction",
+        "right",
+        "--cwd",
+        spec.cwd,
+        "--no-focus",
+    ];
+    for (const [key, value] of Object.entries(spec.env)) {
+        args.push("--env", `${key}=${value}`);
+    }
+    return args;
+}
+/** Herdr `pane run` concatenates extra argv with spaces, so quoting happens here once. */
+function quotedArgv(command, argv) {
+    return [command, ...argv].map(shellQuote).join(" ");
+}
+/**
+ * cmux `new-split --command` is shell text. Encode cwd + env + argv without inventing Pi flags.
+ */
+function cmuxLaunchCommand(spec) {
+    const directory = `cd ${shellQuote(spec.cwd)}`;
+    const environment = Object.entries(spec.env)
+        .map(([key, value]) => `${key}=${shellQuote(value)}`)
+        .join(" ");
+    return [directory, "&&", environment, quotedArgv(spec.command, spec.argv)]
+        .filter((part) => part.length > 0)
+        .join(" ");
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function containsString(output, target) {
+    try {
+        return valueContainsString(JSON.parse(output), target);
+    }
+    catch {
+        return false;
+    }
+}
+function valueContainsString(value, target) {
+    if (value === target)
+        return true;
+    if (typeof value !== "object" || value === null)
+        return false;
+    return Object.values(value).some((child) => valueContainsString(child, target));
+}
+function parseHerdrPaneId(output) {
+    return parseJsonId(output, ["pane_id"]);
+}
+function parseCmuxSurfaceId(output) {
+    const named = parseJsonId(output, ["surface_id", "surfaceId"]);
+    if (named !== undefined)
+        return named;
+    const generic = parseJsonId(output, ["id"], (value) => !value.startsWith("cli:"));
+    return generic;
+}
+function parseJsonId(output, keys, accept = () => true) {
+    try {
+        return findString(JSON.parse(output), keys, accept);
+    }
+    catch {
+        return undefined;
+    }
+}
+function findString(value, keys, accept) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    for (const key of keys) {
+        const candidate = value[key];
+        if (typeof candidate === "string" && candidate.length > 0 && accept(candidate)) {
+            return candidate;
+        }
+    }
+    for (const child of Object.values(value)) {
+        const found = findString(child, keys, accept);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function herdrChildProcessIsRunning(output) {
+    try {
+        const info = findNamedObject(JSON.parse(output), "process_info");
+        if (info === undefined)
+            return false;
+        const shellPid = typeof info.shell_pid === "number" ? info.shell_pid : undefined;
+        const foreground = info.foreground_processes;
+        if (!Array.isArray(foreground))
+            return false;
+        return foreground.some((proc) => {
+            if (typeof proc !== "object" || proc === null)
+                return false;
+            const pid = proc.pid;
+            return typeof pid === "number" && pid !== shellPid;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+function findNamedObject(value, name) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const record = value;
+    const direct = record[name];
+    if (typeof direct === "object" && direct !== null)
+        return direct;
+    for (const child of Object.values(record)) {
+        const found = findNamedObject(child, name);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function failedResult(message) {
+    return { stdout: "", stderr: message, exitCode: null, timedOut: false };
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./extension.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { default } from "./extension.js";

package/dist/json-lines.d.ts

@@ -0,0 +1,14 @@
+import type { Readable, Writable } from "node:stream";
+export type JsonLineErrorCode = "frame_too_large" | "malformed_json" | "stream_error";
+export declare class JsonLineError extends Error {
+    readonly code: JsonLineErrorCode;
+    constructor(code: JsonLineErrorCode, message: string);
+}
+export interface JsonLineReaderOptions {
+    readonly maxFrameBytes: number;
+    readonly onValue: (value: unknown) => void;
+    readonly onError: (error: JsonLineError) => void;
+}
+export declare function attachJsonLineReader(stream: Readable, options: JsonLineReaderOptions): () => void;
+export declare function serializeJsonLine(value: unknown, maxFrameBytes: number): Buffer;
+export declare function writeJsonLine(stream: Writable, value: unknown, maxFrameBytes: number): Promise<void>;

package/dist/json-lines.js

@@ -0,0 +1,94 @@
+export class JsonLineError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "JsonLineError";
+        this.code = code;
+    }
+}
+export function attachJsonLineReader(stream, options) {
+    if (!Number.isSafeInteger(options.maxFrameBytes) || options.maxFrameBytes < 1) {
+        throw new Error("maxFrameBytes must be a positive safe integer");
+    }
+    let buffer = Buffer.alloc(0);
+    let stopped = false;
+    const fail = (error) => {
+        if (stopped)
+            return;
+        stopped = true;
+        cleanup();
+        options.onError(error);
+    };
+    const onData = (chunk) => {
+        if (stopped)
+            return;
+        const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        buffer = buffer.length === 0 ? incoming : Buffer.concat([buffer, incoming]);
+        while (!stopped) {
+            const newline = buffer.indexOf(0x0a);
+            if (newline < 0) {
+                if (buffer.length > options.maxFrameBytes) {
+                    fail(new JsonLineError("frame_too_large", "JSON line exceeds frame limit"));
+                }
+                return;
+            }
+            if (newline > options.maxFrameBytes) {
+                fail(new JsonLineError("frame_too_large", "JSON line exceeds frame limit"));
+                return;
+            }
+            let frame = buffer.subarray(0, newline);
+            buffer = buffer.subarray(newline + 1);
+            if (frame.length > 0 && frame[frame.length - 1] === 0x0d) {
+                frame = frame.subarray(0, frame.length - 1);
+            }
+            if (frame.length === 0)
+                continue;
+            try {
+                options.onValue(JSON.parse(frame.toString("utf8")));
+            }
+            catch (error) {
+                fail(new JsonLineError("malformed_json", `Malformed JSON line: ${error instanceof Error ? error.message : String(error)}`));
+            }
+        }
+    };
+    const onStreamError = (error) => {
+        fail(new JsonLineError("stream_error", error.message));
+    };
+    const cleanup = () => {
+        stream.off("data", onData);
+        stream.off("error", onStreamError);
+        buffer = Buffer.alloc(0);
+    };
+    stream.on("data", onData);
+    stream.on("error", onStreamError);
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        cleanup();
+    };
+}
+export function serializeJsonLine(value, maxFrameBytes) {
+    const encoded = Buffer.from(`${JSON.stringify(value)}\n`, "utf8");
+    if (encoded.length - 1 > maxFrameBytes) {
+        throw new JsonLineError("frame_too_large", "Serialized JSON line exceeds frame limit");
+    }
+    return encoded;
+}
+export function writeJsonLine(stream, value, maxFrameBytes) {
+    let encoded;
+    try {
+        encoded = serializeJsonLine(value, maxFrameBytes);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    return new Promise((resolve, reject) => {
+        stream.write(encoded, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}