@hheei/pi-subagents 0.1.2

package/dist/state.js

@@ -0,0 +1,168 @@
+const EMPTY_USAGE = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    costUsd: 0,
+    turns: 0,
+};
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value))
+        : undefined;
+}
+function finite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function assistant(entry) {
+    const item = record(entry);
+    const message = record(item?.message);
+    return item?.type === "message" && typeof item.id === "string" && message?.role === "assistant"
+        ? { id: item.id, message }
+        : undefined;
+}
+function text(message) {
+    if (!Array.isArray(message.content))
+        return undefined;
+    const value = message.content
+        .map((part) => {
+        const item = record(part);
+        return item?.type === "text" && typeof item.text === "string" ? item.text : "";
+    })
+        .join("")
+        .trim();
+    return value === "" ? undefined : value;
+}
+function completed(message) {
+    return message.stopReason !== "pending" && message.stopReason !== "deferred";
+}
+function diagnostic(message) {
+    if (message.stopReason === "aborted")
+        return "Assistant turn was interrupted";
+    if (message.stopReason !== "error")
+        return undefined;
+    return typeof message.errorMessage === "string" && message.errorMessage !== ""
+        ? message.errorMessage
+        : "Assistant turn failed";
+}
+function messageUsage(message) {
+    const usage = record(message.usage);
+    const inputTokens = finite(usage?.input);
+    const outputTokens = finite(usage?.output);
+    const cacheReadTokens = finite(usage?.cacheRead);
+    const cacheWriteTokens = finite(usage?.cacheWrite);
+    if (inputTokens === undefined ||
+        outputTokens === undefined ||
+        cacheReadTokens === undefined ||
+        cacheWriteTokens === undefined)
+        return undefined;
+    return {
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        costUsd: finite(record(usage?.cost)?.total) ?? null,
+    };
+}
+function add(total, next) {
+    return {
+        inputTokens: total.inputTokens + next.inputTokens,
+        outputTokens: total.outputTokens + next.outputTokens,
+        cacheReadTokens: total.cacheReadTokens + next.cacheReadTokens,
+        cacheWriteTokens: total.cacheWriteTokens + next.cacheWriteTokens,
+        costUsd: total.costUsd === null || next.costUsd === null ? null : total.costUsd + next.costUsd,
+        turns: total.turns + 1,
+    };
+}
+export function summarizeCurrentBranch(entries) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry === undefined)
+            continue;
+        const item = assistant(entry);
+        if (item === undefined || !completed(item.message))
+            continue;
+        const value = text(item.message);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+export function aggregateUsage(entries) {
+    let total = EMPTY_USAGE;
+    const seen = new Set();
+    for (const entry of entries) {
+        const item = assistant(entry);
+        if (item === undefined || seen.has(item.id) || !completed(item.message))
+            continue;
+        seen.add(item.id);
+        const usage = messageUsage(item.message);
+        if (usage !== undefined)
+            total = add(total, usage);
+    }
+    return total;
+}
+export function createStateProjector(initialState = "starting") {
+    let state = initialState;
+    let summary;
+    let interrupted;
+    let usage = EMPTY_USAGE;
+    const snapshot = () => ({
+        state,
+        ...(summary === undefined ? {} : { summary }),
+        ...(interrupted === undefined ? {} : { interrupted }),
+        usage,
+    });
+    return {
+        applyEvent(event) {
+            const value = record(event);
+            if (value === undefined)
+                return snapshot();
+            if (value.type === "agent_start")
+                state = "running";
+            else if (value.type === "agent_end" || value.type === "agent_settled") {
+                state = "idle";
+                const messages = Array.isArray(value.messages) ? value.messages : [];
+                const message = record(messages.length > 0 ? messages[messages.length - 1] : value.message);
+                if (message?.role === "assistant") {
+                    summary = text(message) ?? summary;
+                    interrupted = diagnostic(message) ?? interrupted;
+                    if (message.stopReason === "error")
+                        state = "failed";
+                }
+            }
+            else if (value.type === "error") {
+                state = "failed";
+                interrupted =
+                    typeof value.message === "string" ? value.message : "Runner reported an error";
+            }
+            else if (value.type === "runner_events_dropped") {
+                const count = typeof value.count === "number" ? value.count : undefined;
+                interrupted =
+                    count === undefined
+                        ? "Runner dropped events; live state may be stale"
+                        : `Runner dropped ${count} events; live state may be stale`;
+            }
+            else if (value.type === "runner_exit" || value.type === "exit") {
+                state = value.code === 0 ? "done" : "failed";
+                if (value.code !== 0)
+                    interrupted = `Runner exited${typeof value.code === "number" ? ` with code ${value.code}` : " unexpectedly"}`;
+            }
+            return snapshot();
+        },
+        rebuild(entries) {
+            summary = summarizeCurrentBranch(entries);
+            usage = aggregateUsage(entries);
+            for (const entry of entries) {
+                const item = assistant(entry);
+                if (item === undefined || !completed(item.message))
+                    continue;
+                interrupted = diagnostic(item.message) ?? interrupted;
+                if (item.message.stopReason === "error")
+                    state = "failed";
+            }
+            return snapshot();
+        },
+        snapshot,
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ChildIdentity } from "./domain.js";
+import type { SubagentManager } from "./manager.js";
+export declare function registerParentTools(pi: ExtensionAPI, manager: SubagentManager): void;
+export interface RegisterChildToolsOptions {
+    readonly onReport?: () => void;
+    readonly isBound?: (sessionId: string) => boolean;
+}
+export declare function registerChildTools(pi: ExtensionAPI, identity: ChildIdentity, onReportOrOptions?: (() => void) | RegisterChildToolsOptions): void;

package/dist/tools.js

@@ -0,0 +1,158 @@
+import { getToolTui, registerToolTuiTrace } from "@hheei/pi-ext-core";
+import { Type } from "typebox";
+import { sendReportToRunner } from "./connector.js";
+import { isRecord } from "./domain.js";
+const spawnSchema = Type.Object({
+    task: Type.String({ minLength: 1 }),
+    agent: Type.String({ minLength: 1 }),
+    cwd: Type.Optional(Type.String()),
+});
+const sendSchema = Type.Object({
+    id: Type.String({ minLength: 1 }),
+    message: Type.String({ minLength: 1 }),
+    mode: Type.Optional(Type.Union([Type.Literal("steer"), Type.Literal("follow_up"), Type.Literal("auto")])),
+});
+const idSchema = Type.Object({ id: Type.String({ minLength: 1 }) });
+const contactSchema = Type.Object({
+    reason: Type.Union([
+        Type.Literal("progress_update"),
+        Type.Literal("important_finding"),
+        Type.Literal("need_decision"),
+        Type.Literal("blocked"),
+    ]),
+    message: Type.String({ minLength: 1 }),
+});
+const emptySchema = Type.Object({});
+function isOperationError(value) {
+    return (isRecord(value) &&
+        typeof value.operation === "string" &&
+        typeof value.reason === "string" &&
+        Array.isArray(value.sideEffects));
+}
+function result(value) {
+    if (isOperationError(value))
+        throw new Error(JSON.stringify(value));
+    return {
+        content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value) }],
+        details: value,
+    };
+}
+const SPAWN_DESCRIPTION = "Start an independent background RPC subagent. This call waits until the child runtime is ready, then returns the child id and initial state. Do NOT poll get_subagent or list_subagents to wait for the child's work. When the child reports via contact_parent, the harness delivers that report as a pi-subagent-report message and starts your next turn. After this tool returns, either end your turn or work on other independent tasks, including spawning more subagents in parallel. Do not fabricate or assume the child's results.";
+const SPAWN_SNIPPET = "Start a background RPC subagent. Returns when the runtime is ready. Results arrive later as pi-subagent-report; do not poll.";
+const SPAWN_GUIDELINES = [
+    "Do not poll get_subagent or list_subagents waiting for the child to finish.",
+    "Do not sleep, wait, or tail session/log files to detect completion. The harness delivers reports.",
+    "When the child calls contact_parent, a pi-subagent-report message starts your next turn.",
+    "After spawn returns, end your turn or do other independent work, including more parallel spawns.",
+    "Do not fabricate, assume, or summarize the child's results before a report arrives.",
+];
+const SEND_DESCRIPTION = "Send a steer or follow-up message to one owned child. Do NOT poll get_subagent or list_subagents afterwards. Child reports arrive as pi-subagent-report messages that start your next turn.";
+const SEND_SNIPPET = "Send a message to one owned child. Reports arrive as pi-subagent-report; do not poll afterwards.";
+const GET_DESCRIPTION = "Inspect one owned child: state, mode, summary, usage, and whether the view is live or last-known. Use this when you need current identity or state, not to wait for the child to finish.";
+const LIST_DESCRIPTION = "List children owned by this parent session. Use this when you need ids or current state, not to wait for work to finish. Reports still arrive as pi-subagent-report messages.";
+const STOP_DESCRIPTION = "Persist a stopped intent, then end that child's runtime.";
+const CONTACT_DESCRIPTION = "Report progress, an important finding, a decision you need, or a blocker to the parent. The parent is woken automatically; do not retry the same report. After need_decision or blocked, wait for a parent send_subagent. Do not invent new authority.";
+const CONTACT_SNIPPET = "Report to the parent. The parent is woken automatically; do not retry the same report.";
+const CONTACT_GUIDELINES = [
+    "Call contact_parent when the parent needs a progress update, finding, decision, or blocker.",
+    "Do not send empty status pings or retry the same report.",
+    "After need_decision or blocked, wait for a parent send_subagent. Do not invent new authority.",
+];
+export function registerParentTools(pi, manager) {
+    registerToolTuiTrace(pi);
+    const tui = getToolTui(pi);
+    const spawn = {
+        name: "spawn_subagent",
+        label: "Spawn subagent",
+        description: SPAWN_DESCRIPTION,
+        promptSnippet: SPAWN_SNIPPET,
+        promptGuidelines: [...SPAWN_GUIDELINES],
+        parameters: spawnSchema,
+        async execute(_id, params) {
+            return result(await manager.spawn(params));
+        },
+    };
+    const send = {
+        name: "send_subagent",
+        label: "Send to subagent",
+        description: SEND_DESCRIPTION,
+        promptSnippet: SEND_SNIPPET,
+        promptGuidelines: [
+            "Do not poll get_subagent or list_subagents afterwards.",
+            "Child reports arrive as pi-subagent-report messages that start your next turn.",
+        ],
+        parameters: sendSchema,
+        async execute(_id, params, signal) {
+            return result(await manager.send(params.id, params.message, params.mode, signal));
+        },
+    };
+    const get = {
+        name: "get_subagent",
+        label: "Get subagent",
+        description: GET_DESCRIPTION,
+        promptSnippet: GET_DESCRIPTION,
+        parameters: idSchema,
+        async execute(_id, params) {
+            return result(await manager.get(params.id));
+        },
+    };
+    const list = {
+        name: "list_subagents",
+        label: "List subagents",
+        description: LIST_DESCRIPTION,
+        promptSnippet: LIST_DESCRIPTION,
+        parameters: emptySchema,
+        async execute() {
+            return result(await manager.list());
+        },
+    };
+    const stop = {
+        name: "stop_subagent",
+        label: "Stop subagent",
+        description: STOP_DESCRIPTION,
+        parameters: idSchema,
+        async execute(_id, params, signal) {
+            return result(await manager.stop(params.id, signal));
+        },
+    };
+    pi.registerTool(tui.frame(spawn, { summary: (args) => args.agent }));
+    pi.registerTool(tui.frame(send, { summary: (args) => args.id }));
+    pi.registerTool(tui.frame(get, { summary: (args) => args.id }));
+    pi.registerTool(tui.frame(list, { summary: () => "owned children" }));
+    pi.registerTool(tui.frame(stop, { summary: (args) => args.id }));
+}
+export function registerChildTools(pi, identity, onReportOrOptions) {
+    const options = typeof onReportOrOptions === "function"
+        ? { onReport: onReportOrOptions }
+        : (onReportOrOptions ?? {});
+    const tool = {
+        name: "contact_parent",
+        label: "Contact parent",
+        description: CONTACT_DESCRIPTION,
+        promptSnippet: CONTACT_SNIPPET,
+        promptGuidelines: [...CONTACT_GUIDELINES],
+        parameters: contactSchema,
+        async execute(_id, params, signal, _onUpdate, ctx) {
+            const sessionId = ctx.sessionManager.getSessionId();
+            if (options.isBound !== undefined && !options.isBound(sessionId)) {
+                throw new Error("This Pi session is not the bound subagent session; contact_parent is disabled.");
+            }
+            const details = {
+                type: "pi_subagent_report",
+                parentSessionId: identity.parentSessionId,
+                childId: identity.subagentId,
+                runtimeIdentity: identity.runtimeIdentity,
+                reason: params.reason,
+                message: params.message,
+                sessionId,
+            };
+            await sendReportToRunner(identity, details, signal);
+            options.onReport?.();
+            return {
+                content: [{ type: "text", text: "Report queued for the parent." }],
+                details,
+            };
+        },
+    };
+    pi.registerTool(tool);
+}

package/dist/widget.d.ts

@@ -0,0 +1,16 @@
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { PublicSubagent } from "./domain.js";
+export interface SubagentWidget {
+    refresh(children: readonly PublicSubagent[]): void;
+    dispose(): void;
+}
+export declare function isWidgetVisibleChild(child: PublicSubagent): boolean;
+export declare function formatElapsed(fromIso: string, nowMs?: number): string;
+export declare function renderSubagentWidget(children: readonly PublicSubagent[], width: number, theme: Theme, nowMs?: number): string[];
+export declare function createSubagentWidget(pi: ExtensionAPI, context: ExtensionContext, signal: AbortSignal, initial?: readonly PublicSubagent[]): SubagentWidget | undefined;
+export interface ChildIdentityWidgetOptions {
+    readonly agent: string;
+    readonly toolCount: number;
+}
+export declare function renderChildIdentityWidget(options: ChildIdentityWidgetOptions, width: number, theme: Theme): string[];
+export declare function createChildIdentityWidget(pi: ExtensionAPI, context: ExtensionContext, signal: AbortSignal, options: ChildIdentityWidgetOptions): SubagentWidget | undefined;

package/dist/widget.js

@@ -0,0 +1,158 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { registerWidget } from "@hheei/pi-ext-core";
+const WIDGET_ID = "@hheei/pi-subagents:status";
+const CHILD_WIDGET_ID = "@hheei/pi-subagents:child-identity";
+const MAX_ROWS = 8;
+const ELAPSED_TICK_MS = 1_000;
+export function isWidgetVisibleChild(child) {
+    return child.state === "starting" || child.state === "running" || child.state === "idle";
+}
+function visibleChildren(children) {
+    return children.filter(isWidgetVisibleChild);
+}
+function stateGlyph(state, theme) {
+    if (state === "running")
+        return theme.fg("accent", "◐");
+    if (state === "starting")
+        return theme.fg("muted", "○");
+    return theme.fg("dim", "○");
+}
+function stateLabel(child, theme) {
+    const mode = child.mode === "tui" ? ` ${child.state} tui` : ` ${child.state}`;
+    const freshness = child.freshness === "last_known" ? " last known" : "";
+    const label = `${mode.trim()}${freshness}`;
+    if (child.state === "running" && child.freshness === "live")
+        return theme.fg("accent", label);
+    if (child.interrupted !== undefined || child.freshness === "last_known") {
+        return theme.fg("warning", label);
+    }
+    return theme.fg("dim", label);
+}
+export function formatElapsed(fromIso, nowMs = Date.now()) {
+    const from = Date.parse(fromIso);
+    if (Number.isNaN(from))
+        return "";
+    const totalSeconds = Math.max(0, Math.floor((nowMs - from) / 1000));
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0)
+        return `${hours}h ${minutes}m`;
+    return `${minutes}m ${seconds}s`;
+}
+export function renderSubagentWidget(children, width, theme, nowMs = Date.now()) {
+    const visible = visibleChildren(children);
+    if (visible.length === 0)
+        return [];
+    const running = visible.filter((child) => child.state === "running").length;
+    const headingColor = running > 0 ? "accent" : "dim";
+    const heading = `${theme.fg(headingColor, running > 0 ? "●" : "○")} ${theme.fg("text", `Subagents (${visible.length})`)}`;
+    const lines = [truncateToWidth(heading, width, "...")];
+    const rows = visible.slice(0, MAX_ROWS);
+    for (let index = 0; index < rows.length; index++) {
+        const child = rows[index];
+        if (child === undefined)
+            continue;
+        const last = index === rows.length - 1 && visible.length <= MAX_ROWS;
+        const branch = theme.fg("dim", last ? "└─" : "├─");
+        const name = theme.fg("text", child.displayName ?? child.agent);
+        const elapsed = formatElapsed(child.createdAt, nowMs);
+        const age = elapsed === "" ? "" : `  ${theme.fg("dim", `· ${elapsed}`)}`;
+        const snippet = child.summary === undefined ? "" : child.summary.replace(/\s+/g, " ").trim();
+        const summary = snippet === "" ? "" : `  ${theme.fg("dim", snippet)}`;
+        const id = theme.fg("dim", child.id);
+        lines.push(truncateToWidth(`${branch} ${stateGlyph(child.state, theme)} ${name}  ${stateLabel(child, theme)}${age}${summary}  ${id}`, width, "..."));
+    }
+    if (visible.length > MAX_ROWS) {
+        lines.push(truncateToWidth(theme.fg("dim", `└─ +${visible.length - MAX_ROWS} more`), width, "..."));
+    }
+    lines.push("");
+    return lines;
+}
+export function createSubagentWidget(pi, context, signal, initial = []) {
+    if (context.mode !== "tui")
+        return undefined;
+    let children = initial;
+    let disposed = false;
+    let tick;
+    const hasRows = () => visibleChildren(children).length > 0;
+    const widget = registerWidget(pi, context, signal, {
+        id: WIDGET_ID,
+        placement: "aboveEditor",
+        visible: hasRows(),
+        create: (_tui, theme) => ({
+            render: (width) => renderSubagentWidget(children, width, theme),
+            invalidate: () => undefined,
+            dispose: () => undefined,
+        }),
+    });
+    const stopTick = () => {
+        if (tick === undefined)
+            return;
+        clearInterval(tick);
+        tick = undefined;
+    };
+    const syncTick = () => {
+        if (disposed || !hasRows()) {
+            stopTick();
+            return;
+        }
+        if (tick !== undefined)
+            return;
+        tick = setInterval(() => {
+            widget.requestRender();
+        }, ELAPSED_TICK_MS);
+    };
+    syncTick();
+    signal.addEventListener("abort", stopTick, { once: true });
+    return {
+        refresh(next) {
+            if (disposed)
+                return;
+            children = next;
+            if (!hasRows())
+                widget.setVisible(false);
+            else {
+                widget.setVisible(true);
+                widget.requestRender();
+            }
+            syncTick();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            stopTick();
+            widget.dispose();
+        },
+    };
+}
+export function renderChildIdentityWidget(options, width, theme) {
+    const label = options.agent.trim() === "" ? "child" : options.agent.trim();
+    const line = `${theme.fg("accent", `[${label}]`)} ${theme.fg("dim", "child")}  ${theme.fg("muted", "report via contact_parent")}  ${theme.fg("dim", `${options.toolCount} tools`)}`;
+    return [truncateToWidth(line, width, "..."), ""];
+}
+export function createChildIdentityWidget(pi, context, signal, options) {
+    if (context.mode !== "tui")
+        return undefined;
+    const widget = registerWidget(pi, context, signal, {
+        id: CHILD_WIDGET_ID,
+        placement: "aboveEditor",
+        visible: true,
+        create: (_tui, theme) => ({
+            render: (width) => renderChildIdentityWidget(options, width, theme),
+            invalidate: () => undefined,
+            dispose: () => undefined,
+        }),
+    });
+    return {
+        refresh(_next) {
+            widget.requestRender();
+        },
+        dispose() {
+            widget.dispose();
+        },
+    };
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+	"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"
+	}
+}