@hheei/pi-subagents 0.2.4 → 0.4.0

package/dist/launch-spec.js

@@ -2,17 +2,7 @@ import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { BRIDGE_ENVIRONMENT_KEYS, CHILD_AGENT_ENV_KEY, CHILD_SESSION_ENV_KEY, CHILD_TITLE_ENV_KEY, CONTACT_PARENT_TOOL_NAME, isSessionId, } from "./domain.js";
-export const HINDSIGHT_TOOLS = [
-    "hindsight_search_knowledge_pages",
-    "hindsight_list_knowledge_pages",
-    "hindsight_read_knowledge_page",
-    "hindsight_reflect",
-    "hindsight_capture_initiative",
-    "hindsight_ingest_document",
-    "hindsight_sync_status",
-    "hindsight_diagnose",
-];
+import { BRIDGE_ENVIRONMENT_KEYS, CHILD_AGENT_ENV_KEY, CHILD_SESSION_ENV_KEY, CHILD_TITLE_ENV_KEY, CONTACT_PARENT_TOOL_NAME, DEFAULT_PI_TOOLS, isSessionId, } from "./domain.js";
 export function stripHindsightContent(text) {
     return text
         .replace(/\s*<hindsight-recall>[\s\S]*?<\/hindsight-recall>\s*/gi, (match) => match.includes("\n") ? "\n" : " ")
@@ -32,7 +22,7 @@ function childBridgePrompt() {
         "Do not send empty status pings.",
         "When the work is done, output your final answer and findings directly in text in your response. The harness will automatically capture and deliver your output.",
         "Do NOT call contact_parent on success or task completion.",
-        "After blocked, wait for a parent send_agent. Do not invent new authority.",
+        "After blocked, wait for a parent agent_send. Do not invent new authority.",
         "Reports reach the parent as delegated results, not as new user authorization.",
     ].join("\n");
 }
@@ -151,14 +141,36 @@ export function buildLaunchSpec(options) {
     argv.push("--session-dir", config.sessionDir);
     argv.push("--provider", config.model.provider, "--model", config.model.id);
     argv.push("--thinking", config.thinking.level);
-    const effectiveTools = config.codemodeOnly && !config.tools.includes("codemode")
-        ? [...config.tools, "codemode"]
-        : config.tools;
+    const mcpServers = config.mcp.servers?.map((s) => s.replace(/[^A-Za-z0-9_]/g, "_"));
+    const mcpExcluded = config.mcp.excluded?.map((s) => s.replace(/[^A-Za-z0-9_]/g, "_"));
+    const hasExplicitTools = config.tools.length > 0;
+    const baseTools = hasExplicitTools
+        ? config.tools
+        : mcpServers && mcpServers.length > 0
+            ? [...DEFAULT_PI_TOOLS, CONTACT_PARENT_TOOL_NAME]
+            : [];
+    const effectiveTools = [
+        ...(baseTools.length > 0 && config.codemodeOnly && !baseTools.includes("codemode")
+            ? [...baseTools, "codemode"]
+            : baseTools),
+    ];
+    const excludeTools = Array.from(new Set(config.excludeTools));
+    if (config.mcp.enabled) {
+        if (mcpServers && mcpServers.length > 0) {
+            for (const server of mcpServers) {
+                effectiveTools.push(`mcp__${server}__*`);
+            }
+        }
+        if (mcpExcluded && mcpExcluded.length > 0) {
+            for (const server of mcpExcluded) {
+                excludeTools.push(`mcp__${server}__*`);
+            }
+        }
+    }
     if (effectiveTools.length > 0)
-        argv.push("--tools", effectiveTools.join(","));
-    const excludeTools = Array.from(new Set([...config.excludeTools, ...HINDSIGHT_TOOLS]));
+        argv.push("--tools", Array.from(new Set(effectiveTools)).join(","));
     if (excludeTools.length > 0)
-        argv.push("--exclude-tools", excludeTools.join(","));
+        argv.push("--exclude-tools", Array.from(new Set(excludeTools)).join(","));
     if (!config.extensions.discovery)
         argv.push("--no-extensions");
     for (const path of config.extensions.paths)
@@ -167,6 +179,8 @@ export function buildLaunchSpec(options) {
         argv.push("--no-skills");
     for (const path of config.skills.paths)
         argv.push("--skill", path);
+    if (!config.mcp.enabled)
+        argv.push("--no-mcp");
     argv.push("--append-system-prompt", config.prompt);
     const env = {
         [BRIDGE_ENVIRONMENT_KEYS.parentSessionId]: options.bridge.parentSessionId,
@@ -179,6 +193,12 @@ export function buildLaunchSpec(options) {
         [CHILD_TITLE_ENV_KEY]: config.title ?? "",
         PI_HINDSIGHT_DISABLE: "1",
         ...(config.codemodeOnly ? { PI_CODEMODE_MODE: "only" } : {}),
+        ...(mcpExcluded && mcpExcluded.length > 0
+            ? { PI_SUBAGENT_MCP_EXCLUDE: mcpExcluded.join(",") }
+            : {}),
+        ...(mcpServers && mcpServers.length > 0
+            ? { PI_SUBAGENT_MCP_SERVERS: mcpServers.join(",") }
+            : {}),
     };
     return Object.freeze({
         command: options.invocation.command,

package/dist/lease.d.ts

@@ -0,0 +1,83 @@
+import type { SubagentRecord } from "./domain.js";
+import { type SubagentRegistry } from "./registry.js";
+/**
+ * Durable ownership of one parent session's children. Callers learn three operations. The parent
+ * and child lifecycle matrices stay behind them.
+ *
+ * `commit` is the only write: intent, a runtime, or its removal. `roster` is this session's ledger.
+ * `ready` is the barrier before a model turn: it rebinds surfaces that are still there and
+ * reopens only the panels a new host generation took down. Cancel is not an operation.
+ */
+export declare const RUNTIME_ENDED_RESUME = "The child runtime ended while a turn was in flight; the session is unchanged and a send resumes it";
+export declare const PARENT_EXIT_NOTE = "The child runtime ended with the parent process; a later send starts it again from the same session";
+/** How a removed runtime is recorded. `clear` only drops it. `drop` is a gone writer. */
+export type RuntimeGoneOutcome = "clear" | "drop" | "parent-exit" | "finished";
+export declare const LEASE_EDGES: readonly ["spawn-intent", "runtime-bound", "attachment-bound", "stop-intent", "runtime-gone", "left-session"];
+export type LeaseEdge = {
+    readonly type: "spawn-intent";
+} | {
+    readonly type: "runtime-bound";
+    readonly runtimeIdentity: string;
+    readonly endpoint: string;
+} | {
+    readonly type: "attachment-bound";
+    readonly attachment: NonNullable<NonNullable<SubagentRecord["runtime"]>["attachment"]>;
+} | {
+    readonly type: "stop-intent";
+} | {
+    readonly type: "runtime-gone";
+    readonly outcome?: RuntimeGoneOutcome;
+} | {
+    readonly type: "left-session";
+};
+export type HostList = {
+    readonly known: false;
+} | {
+    readonly known: true;
+    readonly generation: string;
+    readonly present: ReadonlySet<string>;
+};
+export interface HostDirectory {
+    readonly host: "herdr" | "cmux";
+    list(): Promise<HostList>;
+    /** Opens the same child session in a new panel. Does not write the lease. */
+    open(record: SubagentRecord): Promise<{
+        readonly id: string;
+    } | {
+        readonly failure: string;
+    }>;
+    /** True when a human Pi already has this child session open. Those children are not rehydrated. */
+    occupied?(record: SubagentRecord): boolean;
+}
+export interface ProcessDirectory {
+    alive(pid: number): boolean;
+}
+export type LeaseReady = {
+    readonly ok: true;
+    readonly rebound: readonly string[];
+    readonly rehydrated: readonly string[];
+    readonly stopped: readonly string[];
+    /** Children whose runtime was dropped because the writer is gone. */
+    readonly released: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: "unknown";
+};
+export interface ConversationLease {
+    commit(id: string, edge: LeaseEdge, expectedRevision?: number): Promise<SubagentRecord>;
+    roster(): Promise<readonly SubagentRecord[]>;
+    ready(): Promise<LeaseReady>;
+}
+type RegistryStore = Pick<SubagentRegistry, "get" | "list" | "update" | "path">;
+export declare function createConversationLease(options: {
+    readonly registry: RegistryStore;
+    readonly hosts: HostDirectory;
+    readonly processes: ProcessDirectory;
+    readonly forgetRuntime?: (runtimeIdentity: string) => void;
+}): ConversationLease;
+export declare function commitLease(registry: Pick<SubagentRegistry, "get" | "update">, id: string, edge: LeaseEdge, expectedRevision?: number, expectedRuntimeIdentity?: string): Promise<SubagentRecord>;
+/** `undefined` means the edge changes nothing, so the caller must not write. */
+export declare function applyLeaseEdge(record: SubagentRecord, edge: LeaseEdge): SubagentRecord | undefined;
+export declare function readHostGeneration(filePath: string, parentSessionId: string): Promise<string | undefined>;
+export declare function writeHostGeneration(filePath: string, parentSessionId: string, generation: string): Promise<void>;
+export {};

package/dist/lease.js

@@ -0,0 +1,239 @@
+import { existsSync } from "node:fs";
+import { processLockHeld, processLockPath } from "./process-lock.js";
+import { SubagentRegistryError } from "./registry.js";
+import { openStateDb, readMeta, writeMeta } from "./state-db.js";
+/**
+ * Durable ownership of one parent session's children. Callers learn three operations. The parent
+ * and child lifecycle matrices stay behind them.
+ *
+ * `commit` is the only write: intent, a runtime, or its removal. `roster` is this session's ledger.
+ * `ready` is the barrier before a model turn: it rebinds surfaces that are still there and
+ * reopens only the panels a new host generation took down. Cancel is not an operation.
+ */
+export const RUNTIME_ENDED_RESUME = "The child runtime ended while a turn was in flight; the session is unchanged and a send resumes it";
+export const PARENT_EXIT_NOTE = "The child runtime ended with the parent process; a later send starts it again from the same session";
+export const LEASE_EDGES = [
+    "spawn-intent",
+    "runtime-bound",
+    "attachment-bound",
+    "stop-intent",
+    "runtime-gone",
+    "left-session",
+];
+export function createConversationLease(options) {
+    const { registry, hosts, processes, forgetRuntime } = options;
+    return {
+        commit(id, edge, expectedRevision) {
+            return commitLease(registry, id, edge, expectedRevision);
+        },
+        roster() {
+            return registry.list();
+        },
+        ready() {
+            return reconcile(registry, hosts, processes, forgetRuntime);
+        },
+    };
+}
+export async function commitLease(registry, id, edge, expectedRevision, expectedRuntimeIdentity) {
+    const current = await registry.get(id);
+    if (current === undefined) {
+        throw new SubagentRegistryError("unknown_child", `Unknown child ${id}`);
+    }
+    const next = applyLeaseEdge(current, edge);
+    if (next === undefined)
+        return current;
+    return registry.update(id, expectedRevision ?? current.revision, () => next, expectedRuntimeIdentity);
+}
+/** `undefined` means the edge changes nothing, so the caller must not write. */
+export function applyLeaseEdge(record, edge) {
+    switch (edge.type) {
+        case "spawn-intent":
+            return record.intent === "active" ? undefined : { ...record, intent: "active" };
+        case "attachment-bound": {
+            if (record.runtime?.attachment !== undefined)
+                return undefined;
+            if (record.runtime === undefined) {
+                throw new Error(`Child ${record.subagentId} has no runtime to attach`);
+            }
+            return {
+                ...record,
+                runtime: { ...record.runtime, attachment: edge.attachment },
+            };
+        }
+        case "runtime-bound": {
+            if (record.runtime?.runtimeIdentity === edge.runtimeIdentity &&
+                record.runtime.endpoint === edge.endpoint &&
+                record.runtime.attachment === undefined) {
+                return undefined;
+            }
+            return {
+                ...record,
+                runtime: { runtimeIdentity: edge.runtimeIdentity, endpoint: edge.endpoint },
+            };
+        }
+        case "stop-intent":
+            return record.intent === "stopped" ? undefined : { ...record, intent: "stopped" };
+        case "runtime-gone":
+            return applyRuntimeGone(record, edge.outcome ?? "clear");
+        case "left-session":
+            if (record.runtime === undefined && record.state === "done")
+                return undefined;
+            return {
+                ...omitRuntime(record),
+                state: "done",
+                interrupted: "The child left its session; the surface is no longer controlled by the parent",
+            };
+        default: {
+            const unreachable = edge;
+            return unreachable;
+        }
+    }
+}
+function applyRuntimeGone(record, outcome) {
+    if (outcome === "clear") {
+        if (record.runtime === undefined)
+            return undefined;
+        return omitRuntime(record);
+    }
+    if (outcome === "drop") {
+        if (record.intent === "stopped") {
+            if (record.runtime === undefined)
+                return undefined;
+            return omitRuntime(record);
+        }
+        if (record.runtime === undefined && record.state !== "running")
+            return undefined;
+        const rest = omitRuntime(record);
+        if (record.state !== "running")
+            return rest;
+        return { ...rest, state: "blocked", interrupted: RUNTIME_ENDED_RESUME };
+    }
+    if (outcome === "parent-exit") {
+        if (record.runtime === undefined) {
+            if (record.intent === "stopped" || record.state !== "running")
+                return undefined;
+            return { ...record, state: "done", interrupted: PARENT_EXIT_NOTE };
+        }
+        const rest = omitRuntime(record);
+        return {
+            ...rest,
+            ...(record.state === "running" ? { state: "done" } : {}),
+            interrupted: PARENT_EXIT_NOTE,
+        };
+    }
+    if (record.runtime === undefined && record.state === "done")
+        return undefined;
+    const rest = record.runtime === undefined ? record : omitRuntime(record);
+    return { ...rest, state: "done" };
+}
+async function reconcile(registry, hosts, processes, forgetRuntime) {
+    const list = await hosts.list();
+    if (!list.known)
+        return { ok: false, reason: "unknown" };
+    const all = await registry.list();
+    const released = new Set();
+    for (const record of all) {
+        if (record.runtime === undefined)
+            continue;
+        const lockPath = processLockPath(registry.path, record.parentSessionId, record.subagentId);
+        if (lockPath === undefined || !existsSync(lockPath))
+            continue;
+        let held = true;
+        try {
+            held = processLockHeld(lockPath);
+        }
+        catch {
+            continue;
+        }
+        if (held)
+            continue;
+        await releaseRuntime(registry, record, { type: "runtime-gone", outcome: "drop" }, forgetRuntime);
+        released.add(record.subagentId);
+    }
+    const records = all.filter((record) => !released.has(record.subagentId));
+    const parentSessionId = all[0]?.parentSessionId;
+    const stored = parentSessionId === undefined
+        ? undefined
+        : await readHostGeneration(registry.path, parentSessionId);
+    const rebound = [];
+    const rehydrated = [];
+    const stopped = [];
+    let held = false;
+    const panels = records.flatMap((record) => {
+        const id = panelId(record);
+        return id === undefined ? [] : [{ record, id }];
+    });
+    const present = panels.filter((item) => list.present.has(item.id));
+    const missing = panels.filter((item) => !list.present.has(item.id));
+    for (const item of present)
+        rebound.push(item.record.subagentId);
+    const generationChanged = stored !== undefined && stored !== list.generation;
+    const reopen = generationChanged || (stored === undefined && present.length === 0 && missing.length > 0);
+    if (reopen) {
+        for (const item of missing) {
+            if (item.record.intent !== "active")
+                continue;
+            if (hosts.occupied?.(item.record) === true) {
+                held = true;
+                continue;
+            }
+            const opened = await hosts.open(item.record);
+            if ("failure" in opened)
+                continue;
+            await commitLease(registry, item.record.subagentId, {
+                type: "attachment-bound",
+                attachment: { kind: "panel", host: hosts.host, id: opened.id },
+            });
+            rehydrated.push(item.record.subagentId);
+        }
+    }
+    else {
+        for (const item of missing) {
+            if (item.record.intent === "active") {
+                await commitLease(registry, item.record.subagentId, { type: "stop-intent" });
+                stopped.push(item.record.subagentId);
+            }
+            await releaseRuntime(registry, item.record, { type: "runtime-gone" }, forgetRuntime);
+        }
+    }
+    for (const record of records) {
+        const attachment = record.runtime?.attachment;
+        if (attachment?.kind !== "process")
+            continue;
+        if (processes.alive(attachment.pid)) {
+            rebound.push(record.subagentId);
+            continue;
+        }
+        await releaseRuntime(registry, record, { type: "runtime-gone", outcome: "drop" }, forgetRuntime);
+        released.add(record.subagentId);
+    }
+    if (!held && parentSessionId !== undefined && stored !== list.generation)
+        await writeHostGeneration(registry.path, parentSessionId, list.generation);
+    return { ok: true, rebound, rehydrated, stopped, released: [...released] };
+}
+function panelId(record) {
+    const attachment = record.runtime?.attachment;
+    return attachment?.kind === "panel" ? attachment.id : undefined;
+}
+async function releaseRuntime(registry, record, edge, forgetRuntime) {
+    const identity = record.runtime?.runtimeIdentity;
+    const next = await commitLease(registry, record.subagentId, edge);
+    if (identity !== undefined && next.runtime === undefined)
+        forgetRuntime?.(identity);
+}
+function omitRuntime(record) {
+    const { runtime: _runtime, ...rest } = record;
+    return rest;
+}
+export function readHostGeneration(filePath, parentSessionId) {
+    const value = readMeta(openStateDb(filePath), parentSessionId, "hostGeneration");
+    return Promise.resolve(value === "" ? undefined : value);
+}
+export function writeHostGeneration(filePath, parentSessionId, generation) {
+    const db = openStateDb(filePath);
+    const current = readMeta(db, parentSessionId, "hostGeneration");
+    if (current === generation)
+        return Promise.resolve();
+    writeMeta(db, parentSessionId, "hostGeneration", generation);
+    return Promise.resolve();
+}

package/dist/mailbox.d.ts

@@ -0,0 +1,46 @@
+export interface MailboxRequest {
+    readonly childId: string;
+    readonly operation: string;
+    readonly payload: unknown;
+}
+export interface MailboxTransport {
+    readonly endpoint: string;
+    isConnected(childId: string): boolean;
+    disconnect(childId: string): void;
+    request(childId: string, operation: string, payload?: unknown, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<unknown>;
+    onEvent(listener: (childId: string, event: unknown) => void): () => void;
+    onConnectionChange(listener: (childId: string, connected: boolean) => void): () => void;
+    waitUntilSeen(childId: string, options?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<boolean>;
+    close(): void;
+}
+export declare function createMailboxTransport(options: {
+    readonly filePath: string;
+    readonly parentSessionId: string;
+    readonly handleRequest: (request: MailboxRequest) => Promise<unknown>;
+    readonly pollMs?: number;
+    readonly diagnose?: (message: string) => void;
+}): MailboxTransport;
+export interface ChildMailbox {
+    readonly connected: boolean;
+    start(): void;
+    report(operation: string, payload: unknown, signal?: AbortSignal): Promise<unknown>;
+    sendEvent(event: unknown): void;
+    close(): void;
+}
+export declare function attachChildMailbox(options: {
+    readonly filePath: string;
+    readonly parentSessionId: string;
+    readonly subagentId: string;
+    readonly pollMs?: number;
+    readonly handleRequest: (request: {
+        readonly operation: string;
+        readonly payload: unknown;
+    }) => Promise<unknown>;
+    readonly diagnose?: (message: string) => void;
+}): ChildMailbox;