pi-subagents 0.80.0 → 0.82.0

package/src/runs/shared/rex-pane-host.js

@@ -0,0 +1,327 @@
+import { createHash } from "node:crypto";
+import * as path from "node:path";
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { remoteShellCommand, sshMachineAccess } from "./herdr-connection.js";
+import { localMachineAccess } from "./local-machine-access.js";
+import { getPiSpawnCommand } from "./pi-spawn.js";
+import { createPlacedRuntimeDir, PLACED_MANIFEST_READ_SCRIPT, PlacedRunOwner, removePlacedRuntimeDir } from "./placed-run-owner.js";
+import { withHerdrPaneAllocationLock } from "./placement-host.js";
+import { isRexLocalMachine, REX_BUNDLE_BIN, REX_CALL_TIMEOUT_MS, REX_EXIT_GONE, REX_EXIT_UNREACHABLE, REX_MAX_OUTPUT, resolveRexBinary, rexCommandEnv, rexGlobalArgs } from "./rex-machine.js";
+const REX_CLOSE_POLLS = 20, REX_CLOSE_POLL_MS = 50;
+/** On a Rex SSH machine, placed tabs open in the one session with this label. */
+export const REX_SSH_SESSION_LABEL = "subagents";
+const sessionInspection = Compile(Type.Object({ session_id: Type.String() }));
+const sessionList = Compile(Type.Object({ sessions: Type.Array(Type.Object({ session_id: Type.String(), label: Type.Optional(Type.String()) })) }));
+const createdWindow = Compile(Type.Object({ window_id: Type.String(), block_ids: Type.Tuple([Type.String()]) }));
+const sessionWindows = Compile(Type.Object({ windows: Type.Array(Type.Object({ window_id: Type.String(), label: Type.Optional(Type.String()), layers: Type.Array(Type.Object({ blocks: Type.Array(Type.Object({ block_id: Type.String() })) })) })) }));
+const blockProcess = Compile(Type.Object({ foreground: Type.Object({ pid: Type.Integer() }) }));
+const bridgeManifestPid = Compile(Type.Object({ pid: Type.Integer() }));
+/** Rex runtime directories go under /tmp: the bridge socket path inside a macOS TMPDIR exceeds the unix socket path limit. */
+function rexAccess() { return localMachineAccess({ env: { ...rexCommandEnv(), TMPDIR: "/tmp" } }); }
+/** The same /tmp rule on the remote, whatever TMPDIR its SSH session has. */
+function rexSshAccess(machine, access = sshMachineAccess(machine)) { return { ...access, shellCommand: (script, args) => remoteShellCommand(`TMPDIR=/tmp; export TMPDIR; ${script}`, args) }; }
+function asRexMachine(machine) { if (machine.provider !== "rex")
+    throw new Error("The Rex pane host only places runs on Rex machines."); return machine; }
+/** Runs one rex command on the pane machine with --autostart=false, the recorded server, and no inherited Rex selectors; exit 4 always throws. */
+async function runRex(endpoint, args, what) {
+    const result = await endpoint.access.runAsync(endpoint.access.shellCommand('exec /usr/bin/env -u REX_SESSION -u REX_BLOCK -u REX_SERVER "$@"', [endpoint.bin, ...rexGlobalArgs(endpoint.server), ...args]), { timeout: REX_CALL_TIMEOUT_MS, maxBuffer: REX_MAX_OUTPUT });
+    if (result.error)
+        throw new Error(`Rex ${what} failed: ${result.error.message}`, { cause: result.error });
+    if (result.status === REX_EXIT_UNREACHABLE)
+        throw new Error(`The Rex server is unreachable (rex ${what} exited 4); the placed pane's state is unknown.`);
+    if (result.status === null)
+        throw new Error(`Rex ${what} did not finish; the placed pane's state is unknown.`);
+    return { ...result, status: result.status };
+}
+function requireRexSuccess(result, what) {
+    if (result.status === REX_EXIT_GONE)
+        throw new Error(`Rex ${what} failed because its target no longer exists (exit 3): ${result.stderr.trim().slice(0, 512)}`);
+    if (result.status !== 0)
+        throw new Error(`Rex ${what} exited with code ${result.status}: ${result.stderr.trim().slice(0, 512)}`);
+}
+/** Parses rex's JSON output against its schema; undefined when the shape does not match. */
+function parseRexJson(text, validator, what) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Rex ${what} returned malformed JSON.`);
+    }
+    return validator.Check(value) ? value : undefined;
+}
+/** One remote lookup, matching resolveRexBinary: `$REX_BIN_DIR/rex`, then `rex` on PATH, then the Rex server bundle under the remote home. */
+async function resolveRemoteRexBinary(access, machine) {
+    const script = `for c in "\${REX_BIN_DIR:+$REX_BIN_DIR/rex}" "$(command -v rex 2>/dev/null)" "$HOME/${REX_BUNDLE_BIN}"; do if [ -n "$c" ] && [ -f "$c" ] && [ -x "$c" ]; then printf '%s\\n' "$c"; exit 0; fi; done; exit 1`;
+    const found = await access.runAsync(access.shellCommand(script), { timeout: REX_CALL_TIMEOUT_MS, maxBuffer: 64 * 1024 });
+    if (found.error)
+        throw new Error(`Could not look for the Rex CLI on ${machine.id}: ${found.error.message}`, { cause: found.error });
+    const bin = found.stdout.trim();
+    if (found.status !== 0 || !path.posix.isAbsolute(bin) || bin.includes("\n"))
+        throw new Error(`The Rex CLI was not found on ${machine.id}. Install Rex there or put rex on its PATH.`);
+    return bin;
+}
+/** The pane's cwd as the remote Pi will report it: `~` expanded and symlinks resolved. Rex does not expand `~` itself. */
+async function resolveRemoteCwd(access, machine) {
+    const script = `case "$1" in "~") d=$HOME;; "~/"*) d=$HOME/\${1#"~/"};; *) d=$1;; esac; cd -P -- "$d" 2>/dev/null && pwd -P`;
+    const resolved = await access.runAsync(access.shellCommand(script, [machine.cwd]), { timeout: REX_CALL_TIMEOUT_MS, maxBuffer: 64 * 1024 });
+    if (resolved.error)
+        throw new Error(`Could not check ${machine.cwd} on ${machine.id}: ${resolved.error.message}`, { cause: resolved.error });
+    const cwd = resolved.stdout.trim();
+    if (resolved.status !== 0 || !path.posix.isAbsolute(cwd) || cwd.includes("\n"))
+        throw new Error(`Nothing at ${machine.cwd} on ${machine.id}. Clone the repo there first; pi-subagents never clones, pulls, or checks out on a machine.`);
+    return cwd;
+}
+/** The remote Pi as a Rex tab's login environment finds it. */
+async function resolveRemotePi(access, machine) {
+    const found = await access.runAsync(access.shellCommand(`exec "\${SHELL:-/bin/sh}" -lc 'command -v pi'`), { timeout: REX_CALL_TIMEOUT_MS, maxBuffer: 64 * 1024 });
+    if (found.error)
+        throw new Error(`Could not look for Pi on ${machine.id}: ${found.error.message}`, { cause: found.error });
+    const pi = found.stdout.trim().split("\n").at(-1)?.trim() ?? "";
+    if (found.status !== 0 || !path.posix.isAbsolute(pi))
+        throw new Error(`Pi was not found on ${machine.id}: its login shell has no pi on PATH. Install Pi there.`);
+    return pi;
+}
+async function labeledSessions(endpoint) {
+    const listed = await runRex(endpoint, ["ls", "--json"], "ls");
+    requireRexSuccess(listed, "ls");
+    const parsed = parseRexJson(listed.stdout, sessionList, "ls");
+    if (!parsed)
+        throw new Error("Rex ls did not list the server's sessions.");
+    return parsed.sessions.filter((session) => session.label === REX_SSH_SESSION_LABEL).map((session) => session.session_id);
+}
+/**
+ * The session labeled `subagents` on the SSH machine, created when there is none. Rex allows duplicate labels, so two or
+ * more fail closed, also after creating one. Only launch calls this; reconnect and cleanup use the recorded session id.
+ */
+async function subagentsSession(endpoint, machine) {
+    return withHerdrPaneAllocationLock(JSON.stringify(["rex-session", machine.target, REX_SSH_SESSION_LABEL]), async () => {
+        let sessions = await labeledSessions(endpoint);
+        if (sessions.length === 0) {
+            requireRexSuccess(await runRex(endpoint, ["new", REX_SSH_SESSION_LABEL, "--json"], "new"), "new");
+            sessions = await labeledSessions(endpoint);
+        }
+        const [session] = sessions;
+        if (sessions.length > 1)
+            throw new Error(`Rex on ${machine.id} has ${sessions.length} sessions labeled ${REX_SSH_SESSION_LABEL}; close or rename the extras so placed runs have one session to open in.`);
+        if (!session)
+            throw new Error(`Rex on ${machine.id} did not list the ${REX_SSH_SESSION_LABEL} session it just created.`);
+        return session;
+    });
+}
+/** The server must confirm the recorded session; a missing session fails closed. A Rex SSH machine's session is the one recorded at launch. */
+export async function connectRex(machine, options = {}) {
+    const rex = asRexMachine(machine);
+    let endpoint;
+    if (isRexLocalMachine(rex)) {
+        endpoint = { access: options.access ?? rexAccess(), bin: options.bin ?? resolveRexBinary(), session: rex.session };
+        if (rex.server)
+            endpoint.server = rex.server;
+    }
+    else {
+        if (!options.session)
+            throw new Error(`Rex machine '${rex.id}' has no recorded session; a placed run never picks one by label after launch.`);
+        const access = options.access ?? rexSshAccess(rex);
+        endpoint = { access, bin: options.bin ?? await resolveRemoteRexBinary(access, rex), session: options.session };
+    }
+    const inspected = await runRex(endpoint, ["session", "inspect", endpoint.session, "--json"], "session inspect");
+    if (inspected.status === REX_EXIT_GONE)
+        throw new Error(`Rex session ${endpoint.session} no longer exists on the Rex server.`);
+    requireRexSuccess(inspected, "session inspect");
+    if (parseRexJson(inspected.stdout, sessionInspection, "session inspect")?.session_id !== endpoint.session)
+        throw new Error("Rex session identity changed: the server reported a different session id.");
+    return { ...endpoint, ...endpoint.access.openSockets() };
+}
+async function inspectBlock(connection, blockId) {
+    const inspected = await runRex(connection, ["block", "inspect", "-s", connection.session, blockId], "block inspect");
+    if (inspected.status === REX_EXIT_GONE)
+        return "gone";
+    requireRexSuccess(inspected, "block inspect");
+    return "present";
+}
+/** Ownership is the never-reused block id in the recorded session. The block counts as closed only once `block inspect` exits 3. */
+export async function closeOwnedRexPane(connection, owned) {
+    if (owned.workspaceId !== connection.session)
+        throw new Error("Refusing Rex cleanup: the owned pane belongs to a different Rex session.");
+    if (await inspectBlock(connection, owned.paneId) === "gone")
+        return;
+    const closed = await runRex(connection, ["block", "close", "-s", connection.session, owned.paneId], "block close");
+    if (closed.status !== REX_EXIT_GONE)
+        requireRexSuccess(closed, "block close");
+    for (let poll = 0; poll < REX_CLOSE_POLLS; poll++) {
+        if (await inspectBlock(connection, owned.paneId) === "gone")
+            return;
+        await new Promise((resolve) => setTimeout(resolve, REX_CLOSE_POLL_MS));
+    }
+    throw new Error(`Rex block ${owned.paneId} still exists after close; refusing to report the placed pane closed.`);
+}
+function reconcileRexPlacedRun(identity, candidate, proveEvidence) {
+    if (!candidate.present)
+        return { ok: false, reason: "Owned Rex block is gone." };
+    if (candidate.foregroundPid === undefined || candidate.foregroundPid !== candidate.bridgePid)
+        return { ok: false, reason: "The owned Rex block's foreground process is not the placed Pi." };
+    const proof = proveEvidence();
+    if (!proof.ok)
+        return proof;
+    return { ok: true, state: "unknown", paneId: identity.paneId, cursor: proof.cursor };
+}
+async function readBridgePid(connection, runtimeDir) {
+    const manifest = await connection.access.runAsync(connection.access.shellCommand(PLACED_MANIFEST_READ_SCRIPT, [runtimeDir]), { timeout: 5_000, maxBuffer: 64 * 1024 });
+    if (manifest.status !== 0)
+        return undefined;
+    return parseRexJson(manifest.stdout, bridgeManifestPid, "bridge manifest")?.pid;
+}
+/**
+ * `window new` failed, timed out, or printed something unreadable, so the server may still have opened this run's window.
+ * Find it by the run's tab label in the recorded session and close its blocks with the same close-then-prove-gone rule.
+ */
+async function closeUntrackedRexWindow(connection, label, failure) {
+    try {
+        const inspected = await runRex(connection, ["session", "inspect", connection.session, "--json"], "session inspect");
+        if (inspected.status === REX_EXIT_GONE)
+            throw failure;
+        requireRexSuccess(inspected, "session inspect");
+        const windows = parseRexJson(inspected.stdout, sessionWindows, "session inspect")?.windows.filter((window) => window.label === label);
+        if (!windows)
+            throw new Error("Rex session inspect did not list the session's windows.");
+        if (windows.length > 1)
+            throw new Error(`The Rex session has ${windows.length} windows labeled ${label}; refusing to guess which one this run opened.`);
+        for (const window of windows)
+            for (const layer of window.layers)
+                for (const block of layer.blocks)
+                    await closeOwnedRexPane(connection, { workspaceId: connection.session, tabId: window.window_id, paneId: block.block_id });
+    }
+    catch (cleanupError) {
+        if (cleanupError === failure)
+            throw failure;
+        throw new AggregateError([failure, cleanupError], `Rex window new failed, and the window labeled ${label} that it may have opened could not be closed.`, { cause: failure });
+    }
+    throw failure;
+}
+/** Opens the run's background window; on any failure, closes the window the server may have opened before rethrowing. */
+async function openRexWindow(connection, label, cwd, argv) {
+    try {
+        const created = await runRex(connection, ["window", "new", "-s", connection.session, label, "-c", cwd, "--focus=false", "--json", "--", ...argv], "window new");
+        requireRexSuccess(created, "window new");
+        const window = parseRexJson(created.stdout, createdWindow, "window new");
+        if (!window)
+            throw new Error(`Rex window new did not return exactly one block: ${created.stdout.trim().slice(0, 512)}`);
+        return window;
+    }
+    catch (error) {
+        return closeUntrackedRexWindow(connection, label, error instanceof Error ? error : new Error(String(error)));
+    }
+}
+/**
+ * Rex pane host: rex CLI calls on this machine, always with an explicit session. A local child opens as a background
+ * window in the parent's session; a Rex SSH child in the remote `subagents` session, with every rex call run over SSH.
+ * Pi starts through the login shell's environment (as Rex starts any window) with the bridge variables set by
+ * /usr/bin/env. There is no status subscription: a dead Pi closes the bridge socket (directly, or through the SSH
+ * forward), and the reconnect that follows checks the block with `rex block call process` and fails closed.
+ */
+export const rexPaneHost = {
+    connect: connectRex,
+    sessionOf(connection) { return connection.session; },
+    async launch(connection, machine, runId, _runtimeDir, request, onPane) {
+        if (request.kind !== "pi")
+            throw new Error("Rex supports native Pi children only.");
+        const environment = Object.entries(request.environment ?? {});
+        if (environment.some(([name]) => !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name)))
+            throw new Error("Rex launch environment names must be shell variable names.");
+        const rex = asRexMachine(machine);
+        let pi;
+        if (isRexLocalMachine(rex)) {
+            pi = getPiSpawnCommand(request.args);
+            if (!path.isAbsolute(pi.command))
+                throw new Error("Rex placement needs an absolute Pi executable; set PI_SUBAGENT_PI_BINARY to the Pi binary path.");
+        }
+        else
+            pi = { command: await resolveRemotePi(connection.access, rex), args: request.args };
+        const window = await openRexWindow(connection, `subagent-${runId.slice(-8)}`, rex.cwd, ["/usr/bin/env", ...environment.map(([name, value]) => `${name}=${value}`), pi.command, ...pi.args]);
+        const owned = { workspaceId: connection.session, tabId: window.window_id, paneId: window.block_ids[0] };
+        await onPane(owned);
+        return { owned, terminalId: owned.paneId };
+    },
+    async prompt(connection, identity, text) {
+        requireRexSuccess(await runRex(connection, ["send", "-s", connection.session, "-b", identity.paneId, "--", text], "send"), "send");
+        requireRexSuccess(await runRex(connection, ["send-key", "-s", connection.session, "-b", identity.paneId, "enter"], "send-key"), "send-key");
+    },
+    async subscribe() { return () => { }; },
+    paneEvent() { return undefined; },
+    async panes(connection, identity) {
+        const processInfo = await runRex(connection, ["block", "call", "-s", connection.session, "-b", identity.paneId, "process"], "block process");
+        if (processInfo.status === REX_EXIT_GONE)
+            return { present: false };
+        requireRexSuccess(processInfo, "block process");
+        const candidate = { present: true };
+        const foregroundPid = parseRexJson(processInfo.stdout, blockProcess, "block process")?.foreground.pid;
+        if (foregroundPid !== undefined)
+            candidate.foregroundPid = foregroundPid;
+        const bridgePid = await readBridgePid(connection, identity.runtimeDir);
+        if (bridgePid !== undefined)
+            candidate.bridgePid = bridgePid;
+        return candidate;
+    },
+    reconcile: reconcileRexPlacedRun,
+    closeOwnedPane: closeOwnedRexPane,
+};
+function runtimeDirPresent(access, runtimeDir) {
+    const result = access.run(access.shellCommand('test -e "$1" || test -L "$1"', [runtimeDir]), { timeout: 10_000, maxBuffer: 4096 });
+    if (result.error)
+        throw new Error(`Could not check the owned runtime directory: ${result.error.message}`, { cause: result.error });
+    return result.status === 0;
+}
+/** A closed local Pi removes its own runtime directory on shutdown, so already-removed counts as removed. */
+function removeRexRuntimeDir(access, runtimeDir) {
+    if (!runtimeDirPresent(access, runtimeDir))
+        return;
+    try {
+        removePlacedRuntimeDir(access, runtimeDir);
+    }
+    catch (error) {
+        if (runtimeDirPresent(access, runtimeDir))
+            throw error;
+    }
+}
+/** The placed-run owner bound to Rex and the pane machine's access. */
+export class RexPlacedRunOwner extends PlacedRunOwner {
+    constructor(machine, runId, runtimeDir, connection, access, host) { super(machine, runId, runtimeDir, connection, host, access, () => removeRexRuntimeDir(access, runtimeDir)); }
+    /** A Rex SSH owner's machine carries the resolved remote cwd, and its host reconnects only to the session recorded here. */
+    static async create(machine, runId, options = {}) {
+        // A short hash names the directory, so /tmp/pi-subagents-herdr-<hash>-XXXXXXXX/bridge.sock (57 bytes) fits the 103-byte macOS socket path limit for any run id.
+        const hash = createHash("sha256").update(runId).digest("hex").slice(0, 12);
+        if (isRexLocalMachine(machine)) {
+            const access = rexAccess(), runtimeDir = await createPlacedRuntimeDir(access, hash);
+            try {
+                return new RexPlacedRunOwner(machine, runId, runtimeDir, await connectRex(machine, { access }), access, rexPaneHost);
+            }
+            catch (error) {
+                try {
+                    removeRexRuntimeDir(access, runtimeDir);
+                }
+                catch (cleanupError) {
+                    throw new AggregateError([error, cleanupError], "Rex owner creation failed and runtime cleanup also failed.", { cause: error });
+                }
+                throw error;
+            }
+        }
+        const access = rexSshAccess(machine, options.sshAccess), bin = await resolveRemoteRexBinary(access, machine);
+        const placed = { ...machine, cwd: await resolveRemoteCwd(access, machine) };
+        const session = await subagentsSession({ access, bin }, placed);
+        const host = { ...rexPaneHost, connect: (target) => connectRex(target, { access, bin, session }) };
+        const runtimeDir = await createPlacedRuntimeDir(access, hash);
+        try {
+            return new RexPlacedRunOwner(placed, runId, runtimeDir, await host.connect(placed), access, host);
+        }
+        catch (error) {
+            try {
+                removeRexRuntimeDir(access, runtimeDir);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], "Rex owner creation failed and runtime cleanup also failed.", { cause: error });
+            }
+            throw error;
+        }
+    }
+}

package/src/runs/shared/structured-output.d.ts

@@ -2,6 +2,7 @@ import type { Message } from "@earendil-works/pi-ai";
 import type { JsonSchemaObject } from "../../shared/types.ts";
 import type { ResolvedAcceptanceReportMode } from "./acceptance.ts";
 export declare const MISSING_STRUCTURED_OUTPUT_CALL_ERROR = "Missing structured_output call; this step has outputSchema and must finish by calling structured_output.";
+export declare const STRUCTURED_OUTPUT_FOLLOW_UP = "You ended without calling `structured_output`. Call it now with your result. Do not repeat the work.";
 export declare const MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR = "Missing acceptanceReport in structured_output call; acceptance.report is \"on\".";
 export declare const STRUCTURED_OUTPUT_REJECTION_ERROR = "structured_output was invoked but no valid output was captured.";
 export declare const INVALID_STRUCTURED_OUTPUT_SCHEMA_ERROR = "Structured output invocation was rejected: invalid outputSchema.";

package/src/runs/shared/structured-output.js

@@ -14,6 +14,7 @@ import { pathToFileURL } from "node:url";
 import { PI_CODING_AGENT_PACKAGE_ROOT_ENV } from "../../shared/utils.js";
 import { resolveInstalledPiPackageRoot, resolvePiPackageRoot } from "./pi-spawn.js";
 export const MISSING_STRUCTURED_OUTPUT_CALL_ERROR = "Missing structured_output call; this step has outputSchema and must finish by calling structured_output.";
+export const STRUCTURED_OUTPUT_FOLLOW_UP = "You ended without calling `structured_output`. Call it now with your result. Do not repeat the work.";
 export const MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR = "Missing acceptanceReport in structured_output call; acceptance.report is \"on\".";
 export const STRUCTURED_OUTPUT_REJECTION_ERROR = "structured_output was invoked but no valid output was captured.";
 export const INVALID_STRUCTURED_OUTPUT_SCHEMA_ERROR = "Structured output invocation was rejected: invalid outputSchema.";

package/src/shared/accessible-dir.js

@@ -4,7 +4,10 @@ export function ensureAccessibleDir(dirPath, options = {}) {
     const fsImpl = options.fs ?? fs;
     const pid = options.pid ?? process.pid;
     const retryDirectoryErrors = options.retryDirectoryErrors ?? process.platform === "win32";
-    const retryDelaysMs = retryDirectoryErrors ? options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS : [];
+    // Runs synchronously at extension registration. The full ladder would block
+    // every Pi start for ~7.9 s on a directory with broken ACLs before reaching
+    // the pid fallback, so only its first steps (85 ms per operation) are used here.
+    const retryDelaysMs = retryDirectoryErrors ? options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS.slice(0, 3) : [];
     const wait = options.wait ?? waitForFileSystemRetry;
     const mkdirWithRetry = (target) => {
         runFileSystemOperationWithRetry(() => {

package/src/shared/completion-owner.d.ts

@@ -1,2 +1,7 @@
+/**
+ * The completion owner of a result whose own owner process is dead: whichever session owns the run
+ * delivers it. Delivery consumes the result.
+ */
+export declare const OWNING_SESSION_COMPLETION_OWNER = "owning-session";
 /** Stable for one parent Pi process across extension reloads. */
 export declare function currentCompletionOwnerId(): string;

package/src/shared/completion-owner.js

@@ -1,5 +1,10 @@
 import { randomUUID } from "node:crypto";
 const COMPLETION_OWNER_KEY = Symbol.for("pi-subagents.completion-owner-id");
+/**
+ * The completion owner of a result whose own owner process is dead: whichever session owns the run
+ * delivers it. Delivery consumes the result.
+ */
+export const OWNING_SESSION_COMPLETION_OWNER = "owning-session";
 /** Stable for one parent Pi process across extension reloads. */
 export function currentCompletionOwnerId() {
     const runtime = globalThis;

package/src/shared/provider-diagnostics.d.ts

@@ -0,0 +1,9 @@
+import type { SubagentDelegationProviderDiagnostics } from "../api/delegation.ts";
+import type { ChildSessionEvent } from "../runs/shared/child-session.ts";
+type Diagnostics = SubagentDelegationProviderDiagnostics;
+/** Immutable, bounded observations only. This never decides whether to retry. */
+export declare function observeProviderDiagnostics(current: Diagnostics | undefined, event: ChildSessionEvent, at: number): Diagnostics | undefined;
+export declare function clearProviderRetry(current: Diagnostics | undefined): Diagnostics | undefined;
+export declare function snapshotProviderDiagnostics(current: Diagnostics | undefined): Diagnostics | undefined;
+export declare function sameProviderDiagnostics(left: Diagnostics | undefined, right: Diagnostics | undefined): boolean;
+export {};

package/src/shared/provider-diagnostics.js

@@ -0,0 +1,75 @@
+import { isRetryableAssistantError } from "@earendil-works/pi-ai";
+// Account exhaustion can also carry 429. Do not present it as transient throttling.
+// Pi's classifier supplies its own provider-specific quota/billing exclusions too.
+const ACCOUNT_LIMIT = /quota|billing|out of budget|available balance|(?:account|subscription|credits?|balance|usage)[\s_-]*(?:(?:is|are|has been|have been)[\s_-]*)?(?:limit|exhaust|deplet|exceed)|(?:insufficient|exhausted|depleted|low|no(?:[\s_-]+remaining)?)[\s_-]*(?:credits?|balance|fund)/i;
+const RATE_LIMIT = /\brate[\s_-]*limit(?:ed|ing|s|_(?:exceeded|error))?\b|\btoo[\s_-]+many[\s_-]+requests\b|\b(?:HTTP(?:\/\d(?:\.\d)?)?\s*[:=]?\s*429|(?:status|statusCode|status_code)["']?\s*[:=]?\s*429)\b|^\s*429\b/i;
+function classifyError(message) {
+    const text = message.errorMessage;
+    if (!text || ACCOUNT_LIMIT.test(text) || !isRetryableAssistantError(message))
+        return "unknown";
+    return RATE_LIMIT.test(text) ? "rate_limited" : "transient_other";
+}
+const SAFE_ERROR_MESSAGES = {
+    rate_limited: "Assistant request was rate limited.",
+    transient_other: "Assistant request encountered a transient provider or transport error.",
+    unknown: "Assistant request failed.",
+};
+/** Immutable, bounded observations only. This never decides whether to retry. */
+export function observeProviderDiagnostics(current, event, at) {
+    if (event.type === "message_end") {
+        const message = event.message;
+        if (message?.role === "assistant" && message.stopReason === "error") {
+            const kind = classifyError(message);
+            return {
+                ...current,
+                errorCount: (current?.errorCount ?? 0) + 1,
+                lastError: { kind, message: SAFE_ERROR_MESSAGES[kind], at },
+            };
+        }
+    }
+    else if (event.type === "auto_retry_start") {
+        const { attempt, maxAttempts, delayMs } = event;
+        if (typeof attempt === "number" && Number.isSafeInteger(attempt) && attempt > 0
+            && typeof maxAttempts === "number" && Number.isSafeInteger(maxAttempts) && maxAttempts >= attempt
+            && typeof delayMs === "number" && Number.isFinite(delayMs) && delayMs >= 0) {
+            return { ...current, errorCount: current?.errorCount ?? 0, retry: { phase: "backoff", attempt, maxAttempts, delayMs, scheduledAt: at } };
+        }
+    }
+    else if ((event.type === "agent_start" || event.type === "turn_start") && current?.retry?.phase === "backoff") {
+        return { ...current, retry: { ...current.retry, phase: "in_flight" } };
+    }
+    else if (event.type === "auto_retry_end" || event.type === "agent_settled") {
+        return clearProviderRetry(current);
+    }
+    return current;
+}
+export function clearProviderRetry(current) {
+    if (!current?.retry)
+        return current;
+    const { retry: _retry, ...history } = current;
+    return history;
+}
+export function snapshotProviderDiagnostics(current) {
+    if (!current)
+        return undefined;
+    return {
+        errorCount: current.errorCount,
+        ...(current.lastError ? { lastError: { ...current.lastError } } : {}),
+        ...(current.retry ? { retry: { ...current.retry } } : {}),
+    };
+}
+export function sameProviderDiagnostics(left, right) {
+    if (left === right)
+        return true;
+    if (!left || !right)
+        return false;
+    return left.errorCount === right.errorCount
+        && left.lastError?.kind === right.lastError?.kind
+        && left.lastError?.message === right.lastError?.message
+        && left.lastError?.at === right.lastError?.at
+        && left.retry?.phase === right.retry?.phase
+        && left.retry?.attempt === right.retry?.attempt
+        && left.retry?.maxAttempts === right.retry?.maxAttempts
+        && left.retry?.delayMs === right.retry?.delayMs
+        && left.retry?.scheduledAt === right.retry?.scheduledAt;
+}

package/src/shared/session-identity.d.ts

@@ -3,4 +3,6 @@ interface SessionIdentityManager {
     getSessionId(): string | null | undefined;
 }
 export declare function resolveCurrentSessionId(sessionManager: SessionIdentityManager): string;
+/** The id in a Pi session file's header, which `pi --session <id>` resolves; only ids that need no shell quoting. */
+export declare function resolvePiSessionId(sessionFile: string | undefined): string | undefined;
 export {};

package/src/shared/session-identity.js

@@ -1,6 +1,32 @@
+import * as fs from "node:fs";
 export function resolveCurrentSessionId(sessionManager) {
     const sessionId = sessionManager.getSessionFile() ?? sessionManager.getSessionId();
     if (!sessionId)
         throw new Error("Current session identity is unavailable.");
     return sessionId;
 }
+/** The id in a Pi session file's header, which `pi --session <id>` resolves; only ids that need no shell quoting. */
+export function resolvePiSessionId(sessionFile) {
+    if (!sessionFile)
+        return undefined;
+    try {
+        const fd = fs.openSync(sessionFile, "r");
+        try {
+            const buffer = Buffer.alloc(16 * 1024);
+            const bytes = fs.readSync(fd, buffer, 0, buffer.length, 0);
+            const line = buffer.toString("utf-8", 0, bytes).split("\n", 1)[0];
+            if (!line)
+                return undefined;
+            const header = JSON.parse(line);
+            if (header.type === "session" && typeof header.id === "string" && /^[A-Za-z0-9-]{8,}$/.test(header.id))
+                return header.id;
+            return undefined;
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return undefined;
+    }
+}