@hcflabs/pi-subagent 0.0.0-stage → 27.10.7

package/dist/discard.js

@@ -0,0 +1,218 @@
+import { existsSync, realpathSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { runGit } from "./git-process.js";
+import { inspectIndexFlags, OWNED_BRANCH_PATTERN, WORKTREES_DIRNAME } from "./worktree.js";
+import { requireGit, within } from "./prune.js";
+export function discardResources(state) {
+    return [
+        ...state.tasks.flatMap((task) => task.kind === "changeset" ? task.attempts.map((attempt, index) => ({
+            key: `task/${task.taskId}/${index + 1}`, task, attempt,
+            worktree: attempt.allocations.filter((item) => item.kind === "worktree").at(-1)?.worktree,
+        })) : task.attempts.flatMap((attempt) => attempt.cleanup ? [{
+                key: `task/${task.taskId}/${attempt.number}`, textAttempt: attempt,
+                worktree: { path: attempt.cleanup.path, cwd: attempt.cleanup.path, branch: attempt.cleanup.branch,
+                    repoRoot: dirname(dirname(attempt.cleanup.path)) },
+            }] : [])),
+        ...state.integration.generations.map((generation) => ({ key: `integration/${generation.number}`, generation, worktree: generation.worktree })),
+    ];
+}
+export async function primaryCheckout(root, run = runGit) {
+    const first = (await requireGit(run, ["worktree", "list", "--porcelain", "-z"], root)).split("\0")[0];
+    if (!first?.startsWith("worktree "))
+        throw new Error("Primary Git checkout is unavailable.");
+    return realpathSync.native(first.slice(9));
+}
+const identity = (resource) => JSON.stringify([resource.worktree, resource.attempt?.allocations]);
+/** Read-only evidence. A resource is one worker attempt or integration generation, including its host resources. */
+export async function inspectDiscardResource(primary, mainCwd, resource, guards, run = runGit) {
+    const { worktree, attempt } = resource;
+    const allocations = attempt?.allocations ?? [];
+    const item = {
+        key: resource.key, identity: identity(resource), checkout: false, ignored: [], blockers: [],
+        hosts: allocations.filter((allocation) => allocation.kind !== "worktree").map((allocation) => JSON.stringify(allocation)),
+    };
+    const blocked = await guards.blocked();
+    if (blocked)
+        item.blockers.push(blocked);
+    if (allocations.some((allocation) => allocation.status === "allocating" || allocation.status === "unknown")) {
+        item.blockers.push("Allocation ownership is uncertain; inspect the recorded resources.");
+    }
+    if (!worktree)
+        return item;
+    item.path = worktree.path;
+    item.branch = worktree.branch;
+    if (!OWNED_BRANCH_PATTERN.test(worktree.branch) || worktree.repoRoot !== primary
+        || worktree.path !== join(primary, WORKTREES_DIRNAME, basename(worktree.branch))) {
+        item.blockers.push("Checkout or branch is not at this repository's owned path.");
+        return item;
+    }
+    const ref = `refs/heads/${worktree.branch}`;
+    const branches = (await requireGit(run, ["for-each-ref", "--format=%(refname) %(objectname) %(symref)", ref], primary)).split("\n");
+    const branch = branches.find((line) => line.startsWith(`${ref} `))?.split(" ");
+    item.tip = branch?.[1];
+    if (branch?.[2])
+        item.blockers.push("Owned branch is a symbolic reference; inspect it manually.");
+    if (item.tip && worktree.baseCommit)
+        item.commits = Number(await requireGit(run, ["rev-list", "--count", `${worktree.baseCommit}..${item.tip}`], primary));
+    const records = (await requireGit(run, ["worktree", "list", "--porcelain", "-z"], primary)).split("\0\0");
+    const registered = records.filter((record) => record.split("\0").includes(`branch refs/heads/${worktree.branch}`));
+    const owned = records.find((record) => record.startsWith(`worktree ${worktree.path}\0`));
+    if (registered.some((record) => !record.startsWith(`worktree ${worktree.path}\0`)))
+        item.blockers.push("Branch is checked out at another path.");
+    item.checkout = existsSync(worktree.path);
+    const cleanup = attempt?.cleanup ?? resource.generation?.cleanup;
+    if (item.checkout && (resource.textAttempt?.cleanup?.outcome === "pruned" || cleanup?.some((step) => step.kind === "worktree" && step.status === "completed"))
+        || item.tip && (resource.textAttempt?.cleanup?.outcome === "pruned" || cleanup?.some((step) => step.kind === "branch" && step.status === "completed"))) {
+        item.blockers.push("A resource exists after completed cleanup; new ownership is unproved.");
+    }
+    if (allocations.filter((allocation) => allocation.kind === "worktree").at(-1)?.status === "absent"
+        && (item.checkout || item.tip))
+        item.blockers.push("Allocation was recorded absent; ownership of the existing resource is unproved.");
+    if (owned && !item.checkout)
+        item.blockers.push("Checkout registration remains but its directory is missing; inspect it manually.");
+    if (!item.checkout)
+        return item;
+    if (!owned || !owned.split("\0").includes(`branch refs/heads/${worktree.branch}`))
+        item.blockers.push("Checkout registration changed or checkout is detached.");
+    if (owned?.split("\0").some((field) => field === "locked" || field.startsWith("locked ")))
+        item.blockers.push("Checkout is locked.");
+    const real = realpathSync.native(worktree.path);
+    if (real !== worktree.path)
+        item.blockers.push("Owned checkout path is redirected.");
+    if (within(real, realpathSync.native(mainCwd)))
+        item.blockers.push("Main runs inside the checkout.");
+    const status = (await requireGit(run, ["--no-optional-locks", "status", "--porcelain=v1", "-z", "--ignored=matching", "--untracked-files=normal", "--ignore-submodules=none"], worktree.path)).split("\0").filter(Boolean);
+    item.ignored = status.filter((entry) => entry.startsWith("!! ")).map((entry) => entry.slice(3));
+    item.dirty = status.some((entry) => !entry.startsWith("!! "));
+    if (!item.dirty) {
+        const flags = await inspectIndexFlags(worktree.path, run);
+        if (flags.failure || flags.hidden) {
+            delete item.dirty;
+            item.blockers.push(flags.failure ?? "Index flags hide tracked files; dirty state cannot be proved.");
+        }
+    }
+    const submodules = await requireGit(run, ["submodule", "status", "--recursive"], worktree.path);
+    if (submodules.split("\n").some((line) => line && !line.startsWith("-"))) {
+        item.blockers.push("Initialized submodules require separate inspection of their commits and ignored files.");
+    }
+    try {
+        const ownPanes = allocations.flatMap((allocation) => allocation.status !== "owned" ? []
+            : allocation.kind === "workspace" ? [allocation.rootPaneId]
+                : allocation.kind === "worker_tab" || allocation.kind === "agent" ? [allocation.paneId] : []);
+        const foreign = (await guards.panes()).filter((pane) => !ownPanes.includes(pane.paneId)
+            && pane.cwds.some((cwd) => within(real, cwd) || within(worktree.path, cwd)));
+        if (foreign.length)
+            item.blockers.push(`Other Herdr panes use this checkout: ${foreign.map((pane) => pane.paneId).join(", ")}`);
+    }
+    catch (error) {
+        item.blockers.push(`Herdr cannot be inspected: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return item;
+}
+export async function inspectDiscard(primary, mainCwd, state, guards) {
+    const items = [];
+    for (const resource of discardResources(state)) {
+        try {
+            const item = await inspectDiscardResource(primary, mainCwd, resource, guards);
+            const complete = resource.textAttempt?.cleanup?.outcome === "pruned"
+                || (resource.attempt?.cleanup ?? resource.generation?.cleanup)?.every((step) => step.status === "completed");
+            if (!complete || item.checkout || item.tip || item.blockers.length)
+                items.push(item);
+        }
+        catch (error) {
+            items.push({ key: resource.key, identity: identity(resource), path: resource.worktree?.path,
+                branch: resource.worktree?.branch, checkout: false, ignored: [], hosts: [], blockers: [`Inspection failed: ${String(error)}`] });
+        }
+    }
+    return items;
+}
+/** Called only after the command's confirmation. Never exposed as an agent tool. */
+export async function removeDiscardResources(handle, primary, mainCwd, reviewed, guards, close, run = runGit) {
+    const results = [];
+    const removals = [];
+    for (const item of reviewed) {
+        const resource = discardResources(handle.state).find((resource) => resource.key === item.key);
+        if (!resource || identity(resource) !== item.identity || item.blockers.length) {
+            results.push({ key: item.key, outcome: "skipped", reason: "Ownership changed or the reviewed item is blocked." });
+            continue;
+        }
+        let checkoutRemoved = false;
+        const verify = async () => {
+            if (!guards.current())
+                throw new Error("Session changed; reopen /subagent.");
+            const fresh = await inspectDiscardResource(primary, mainCwd, resource, guards, run);
+            if (fresh.blockers.length)
+                throw new Error(fresh.blockers.join("; "));
+            if (fresh.tip !== item.tip)
+                throw new Error("Branch was deleted or moved since review; branch kept.");
+            if (fresh.checkout !== (checkoutRemoved ? false : item.checkout))
+                throw new Error("Checkout changed since review.");
+            if (fresh.ignored.some((entry) => !item.ignored.includes(entry)))
+                throw new Error("Ignored entries changed since review.");
+            const blocked = await guards.blocked();
+            if (blocked)
+                throw new Error(blocked);
+            if (!guards.current())
+                throw new Error("Session changed; reopen /subagent.");
+        };
+        try {
+            await verify();
+        }
+        catch (error) {
+            results.push({ key: item.key, outcome: "skipped", reason: String(error) });
+            continue;
+        }
+        const failed = async (error) => {
+            const pending = (resource.attempt?.cleanup ?? resource.generation?.cleanup)?.find((step) => step.status === "running");
+            if (pending) {
+                pending.failure = `User-confirmed discard failed: ${String(error)}`.slice(0, 500);
+                await handle.save();
+            }
+            results.push({ key: item.key, outcome: "failed", reason: `${checkoutRemoved ? "Checkout removed; " : ""}${String(error)}` });
+        };
+        try {
+            await close(resource, verify);
+        }
+        catch (error) {
+            await failed(error);
+            continue;
+        }
+        // Close all reviewed workers and host resources before any Git checkout is removed.
+        removals.push(async () => {
+            try {
+                const pending = [{ kind: "worktree", status: "pending" }, { kind: "branch", status: "pending" }];
+                const steps = resource.attempt?.cleanup ?? (resource.generation ? resource.generation.cleanup ??= pending : pending);
+                for (const kind of ["worktree", "branch"]) {
+                    const step = steps.find((step) => step.kind === kind);
+                    await verify();
+                    if (step.status === "completed")
+                        continue;
+                    step.status = "running";
+                    delete step.failure;
+                    await handle.save();
+                    await verify();
+                    if (kind === "worktree" && item.checkout) {
+                        await requireGit(run, ["worktree", "remove", "--force", item.path], primary);
+                        checkoutRemoved = true;
+                    }
+                    else if (kind === "branch" && item.tip) {
+                        await requireGit(run, ["update-ref", "--no-deref", "-d", `refs/heads/${item.branch}`, item.tip], primary);
+                    }
+                    step.status = "completed";
+                    if (resource.textAttempt)
+                        resource.textAttempt.cleanup = kind === "branch"
+                            ? { outcome: "pruned", path: item.path, branch: item.branch }
+                            : { outcome: "recovery", path: item.path, branch: item.branch, note: "User confirmed discard: checkout removed; branch cleanup pending." };
+                    await handle.save();
+                }
+                results.push({ key: item.key, outcome: "removed", reason: "Reviewed resources removed; cleanup saved." });
+            }
+            catch (error) {
+                await failed(error);
+            }
+        });
+    }
+    for (const remove of removals)
+        await remove();
+    return results;
+}

package/dist/display-text.d.ts

@@ -0,0 +1,5 @@
+export declare const DISPLAY_TEXT_CONTRACT: {
+    readonly controlRanges: "\\u0000-\\u001F\\u007F-\\u009F";
+    readonly pattern: "^(?![\\s\\S]*[\\u0000-\\u001F\\u007F-\\u009F])[\\s\\S]+$";
+};
+export declare function hasDisplayControlCharacters(value: string): boolean;

package/dist/display-text.js

@@ -0,0 +1,9 @@
+const C0_C1_CONTROL_RANGES = "\\u0000-\\u001F\\u007F-\\u009F";
+export const DISPLAY_TEXT_CONTRACT = {
+    controlRanges: C0_C1_CONTROL_RANGES,
+    pattern: `^(?![\\s\\S]*[${C0_C1_CONTROL_RANGES}])[\\s\\S]+$`,
+};
+const DISPLAY_TEXT_CONTROL_PATTERN = new RegExp(`[${DISPLAY_TEXT_CONTRACT.controlRanges}]`, "u");
+export function hasDisplayControlCharacters(value) {
+    return DISPLAY_TEXT_CONTROL_PATTERN.test(value);
+}

package/dist/ephemeral.d.ts

@@ -0,0 +1,79 @@
+import type { Usage } from "@earendil-works/pi-ai";
+import type { PiLaunch } from "./index.ts";
+export declare const DEFAULT_MAX_TURNS = 50;
+export declare const EXECUTION_BUDGET_ENV = "PI_SUBAGENT_EXECUTION_BUDGET";
+export interface EphemeralSubagentExecutionBudget {
+    maxTurns: number;
+    maxMs: number | null;
+    startedAt: number;
+    maxTokens?: number;
+}
+export interface EphemeralSubagentTimeout {
+    idleMs: number;
+    maxMs: number | null;
+}
+export interface EphemeralSubagentExecutorOptions {
+    maxConcurrency: number;
+    maxTurns?: number;
+    maxTokens?: number;
+    timeout: EphemeralSubagentTimeout;
+}
+export type EphemeralSubagentActivityEvent = {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    path?: string;
+} | {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+} | {
+    type: "message_end";
+};
+export interface EphemeralSubagentRunInput {
+    signal?: AbortSignal;
+    onUpdate?: (text: string) => void;
+    onTokens?: (tokens: number) => void;
+    onActivity?: (event: EphemeralSubagentActivityEvent) => void;
+    prepare: () => Promise<{
+        launch: PiLaunch;
+        task: string;
+        cwd: string;
+    }>;
+}
+interface EphemeralSubagentResultBase {
+    exitCode: number;
+    output: string;
+    outputTruncated: boolean;
+    stderr: string;
+    stopReason?: string;
+    errorMessage?: string;
+    usage?: Usage;
+}
+export type EphemeralSubagentResult = (EphemeralSubagentResultBase & {
+    outcome: "success";
+}) | (EphemeralSubagentResultBase & {
+    outcome: "failure";
+});
+export type EphemeralSubagentErrorCode = "aborted" | "timeout" | "turn_limit" | "token_limit" | "spawn" | "protocol" | "prepare" | "callback";
+export declare class EphemeralSubagentError extends Error {
+    name: string;
+    readonly code: EphemeralSubagentErrorCode;
+    readonly usage?: Usage;
+    readonly output?: string;
+    constructor(code: EphemeralSubagentErrorCode, message: string, cause?: unknown, usage?: Usage, output?: string);
+}
+export interface EphemeralSubagentExecutor {
+    run(input: EphemeralSubagentRunInput): Promise<EphemeralSubagentResult>;
+}
+/**
+ * Creates a bounded ephemeral executor for callers already running inside Pi.
+ * It reuses the active Pi process invocation; it does not resolve a standalone Pi installation.
+ */
+export declare function createEphemeralSubagentExecutor(options: EphemeralSubagentExecutorOptions): EphemeralSubagentExecutor;
+/** Longest prefix of `text` within `maxBytes` UTF-8 bytes, never splitting a code point. */
+export declare function utf8Prefix(text: string, maxBytes: number): string;
+export declare function capEphemeralSubagentOutput(text: string): string;
+export declare function addUsage(left: Usage | undefined, right: Usage | undefined): Usage | undefined;
+export declare function formatDuration(milliseconds: number): string;
+export {};