@hheei/pi-subagents 0.3.0 → 0.5.0

package/dist/host-adapter.js

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 import { errorMessage, runCommand, shellQuote } from "@hheei/pi-ext-core";
 const DEFAULT_HOST_ORDER = ["herdr", "cmux"];
 /** Selects a presentation host visibly; an explicit unavailable host never falls back. */
@@ -302,6 +303,144 @@ export function herdrPanelFocused(tabList, workspaceList, tabId) {
     const workspaceFocused = workspace?.focused;
     return typeof workspaceFocused === "boolean" ? workspaceFocused : undefined;
 }
+export async function listHerdrAttachments(runner, timeoutMs) {
+    const status = await runner.run("herdr", ["status", "server"], { timeoutMs });
+    if (status.timedOut || status.exitCode !== 0)
+        return { known: false };
+    const socket = statusField(status.stdout, "socket");
+    if (socket === undefined)
+        return { known: false };
+    let generation;
+    try {
+        const stat = statSync(socket);
+        generation = `${stat.dev}:${stat.ino}`;
+    }
+    catch {
+        return { known: false };
+    }
+    const tabs = await runner.run("herdr", ["tab", "list"], { timeoutMs });
+    if (tabs.timedOut || tabs.exitCode !== 0)
+        return { known: false };
+    const present = herdrTabIds(tabs.stdout);
+    if (present === undefined)
+        return { known: false };
+    return { known: true, generation, present };
+}
+export function herdrTabIds(output) {
+    const entries = herdrCollection(output, "tabs");
+    if (entries === undefined)
+        return undefined;
+    const ids = new Set();
+    for (const entry of entries) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const id = entry.tab_id;
+        if (typeof id === "string" && id !== "")
+            ids.add(id);
+    }
+    return ids;
+}
+export async function listCmuxAttachments(runner, timeoutMs) {
+    const panels = await runner.run("cmux", ["--json", "list-panels"], { timeoutMs });
+    if (panels.timedOut || panels.exitCode !== 0)
+        return { known: false };
+    const present = cmuxSurfaceIds(panels.stdout);
+    if (present === undefined)
+        return { known: false };
+    return { known: true, generation: "cmux", present };
+}
+export function cmuxSurfaceIds(output) {
+    let parsed;
+    try {
+        parsed = JSON.parse(output);
+    }
+    catch {
+        return undefined;
+    }
+    const panels = findNamedObject(parsed, "result")?.panels ?? findNamedObject(parsed, "panels");
+    const list = Array.isArray(panels) ? panels : Array.isArray(parsed) ? parsed : undefined;
+    if (list === undefined)
+        return undefined;
+    const ids = new Set();
+    for (const entry of list) {
+        if (typeof entry === "string" && entry !== "")
+            ids.add(entry);
+        else if (typeof entry === "object" && entry !== null) {
+            const id = entry.surface_id;
+            if (typeof id === "string" && id !== "")
+                ids.add(id);
+        }
+    }
+    return ids;
+}
+export function rebindHerdrTab(options) {
+    const runner = options.runner ?? systemHostCommandRunner;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    return hostAttachment({
+        identity: { host: "herdr", attachmentId: options.tabId, createdBy: options.ownerId },
+        launch: { stdout: "", stderr: "", exitCode: 0, timedOut: false },
+        noun: "tab",
+        reportsFocus: true,
+        observe: async () => {
+            const tabs = await runner.run("herdr", ["tab", "list"], { timeoutMs });
+            if (tabs.timedOut || tabs.exitCode !== 0)
+                return { process: tabs };
+            const ids = herdrTabIds(tabs.stdout);
+            if (ids === undefined)
+                return { process: tabs };
+            return { process: tabs, alive: ids.has(options.tabId) };
+        },
+        close: () => runner.run("herdr", ["tab", "close", options.tabId], { timeoutMs }),
+        ownsAttachment: options.ownsAttachment,
+    });
+}
+export function rebindCmuxSurface(options) {
+    const runner = options.runner ?? systemHostCommandRunner;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    return hostAttachment({
+        identity: { host: "cmux", attachmentId: options.surfaceId, createdBy: options.ownerId },
+        launch: { stdout: "", stderr: "", exitCode: 0, timedOut: false },
+        noun: "surface",
+        reportsFocus: false,
+        observe: async () => {
+            const process = await runner.run("cmux", ["--json", "list-panels"], { timeoutMs });
+            if (process.timedOut || process.exitCode !== 0)
+                return { process };
+            const ids = cmuxSurfaceIds(process.stdout);
+            if (ids === undefined)
+                return { process };
+            return { process, alive: ids.has(options.surfaceId) };
+        },
+        close: () => runner.run("cmux", ["--json", "close-surface", "--surface", options.surfaceId], {
+            timeoutMs,
+        }),
+        ownsAttachment: options.ownsAttachment,
+    });
+}
+function herdrCollection(output, collection) {
+    let parsed;
+    try {
+        parsed = JSON.parse(output);
+    }
+    catch {
+        return undefined;
+    }
+    const list = findNamedObject(parsed, "result")?.[collection];
+    return Array.isArray(list) ? list : undefined;
+}
+function statusField(output, name) {
+    for (const line of output.split("\n")) {
+        const separator = line.indexOf(":");
+        if (separator < 0)
+            continue;
+        if (line.slice(0, separator).trim() !== name)
+            continue;
+        const value = line.slice(separator + 1).trim();
+        if (value !== "")
+            return value;
+    }
+    return undefined;
+}
 function herdrListEntry(output, collection, key, id) {
     let parsed;
     try {

package/dist/info.js

@@ -1,5 +1,6 @@
 import { stripVTControlCharacters } from "node:util";
 import { Text } from "@earendil-works/pi-tui";
+import { readMessageView } from "@hheei/pi-ext-core";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { VISUAL_SUBAGENT_GLYPH, VISUAL_SUBAGENT_TONE } from "./domain.js";
@@ -22,19 +23,44 @@ export function displaySubagentText(text) {
         .replaceAll("\t", "    ")
         .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, "");
 }
-export function renderSubagentInfo(data, expanded, theme) {
+function shownSubagent(data) {
     if (!Value.Check(infoSchema, data))
         return undefined;
-    const id = formatSubagentId(displaySubagentText(data.id).replace(/\s+/gu, " "));
-    const agent = displaySubagentText(data.agent).replace(/\s+/gu, " ");
+    return {
+        id: formatSubagentId(displaySubagentText(data.id).replace(/\s+/gu, " ")),
+        agent: displaySubagentText(data.agent).replace(/\s+/gu, " "),
+        status: data.status,
+        message: displaySubagentText(data.message),
+    };
+}
+export function renderSubagentInfo(data, expanded, theme) {
+    const shown = shownSubagent(data);
+    if (shown === undefined)
+        return undefined;
     const heading = theme.fg("dim", "info · agents · ") +
-        theme.fg(VISUAL_SUBAGENT_TONE[data.status], VISUAL_SUBAGENT_GLYPH[data.status]) +
-        theme.fg("dim", ` ${id} ${agent} · ${data.status}`);
-    return expanded ? `${heading}\n${displaySubagentText(data.message)}` : heading;
+        theme.fg(VISUAL_SUBAGENT_TONE[shown.status], VISUAL_SUBAGENT_GLYPH[shown.status]) +
+        theme.fg("dim", ` ${shown.id} ${shown.agent} · ${shown.status}`);
+    return expanded ? `${heading}\n${shown.message}` : heading;
 }
 /** Native transcript entries survive resume and never enter the model context. */
 export function registerSubagentInfo(pi) {
     pi.registerEntryRenderer(SUBAGENT_INFO_TYPE, (entry, options, theme) => {
+        const create = readMessageView(pi);
+        const shown = create === undefined ? undefined : shownSubagent(entry.data);
+        if (create !== undefined && shown !== undefined) {
+            const message = shown.message.trim();
+            return create({
+                theme,
+                header: {
+                    kind: "agents",
+                    summary: `${VISUAL_SUBAGENT_GLYPH[shown.status]} ${shown.id} ${shown.agent} · ${shown.status}`,
+                    tone: VISUAL_SUBAGENT_TONE[shown.status],
+                },
+                ...(message === "" ? {} : { body: shown.message }),
+                stateHolder: entry,
+                forcedExpanded: options.expanded,
+            });
+        }
         const text = renderSubagentInfo(entry.data, options.expanded, theme);
         return text === undefined ? undefined : new Text(text, 1, 0);
     });

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;