@hcflabs/pi-subagent 0.0.0-stage → 27.10.7

package/dist/ephemeral.js

@@ -0,0 +1,916 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { hasDisplayControlCharacters } from "./display-text.js";
+const MAX_OUTPUT_BYTES = 50 * 1024;
+const MAX_JSON_EVENT_BYTES = 1024 * 1024;
+export const DEFAULT_MAX_TURNS = 50;
+export const EXECUTION_BUDGET_ENV = "PI_SUBAGENT_EXECUTION_BUDGET";
+const MAX_ACTIVITY_TEXT_BYTES = 4 * 1024;
+// A JSON string byte can take six source bytes (for example, \u0000).
+const MAX_ACTIVITY_PREFIX_BYTES = 2 * MAX_ACTIVITY_TEXT_BYTES * 6 + 1024;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const POST_EXIT_STDIO_IDLE_MS = 250;
+const POST_EXIT_STDIO_HARD_MS = 1_000;
+const PI_JSON_EVENTS = {
+    agent_start: true,
+    agent_end: true,
+    agent_settled: true,
+    turn_start: true,
+    turn_end: true,
+    message_start: true,
+    message_update: true,
+    message_end: true,
+    tool_execution_start: true,
+    tool_execution_update: true,
+    tool_execution_end: true,
+    queue_update: true,
+    compaction_start: true,
+    compaction_end: true,
+    entry_appended: true,
+    session_info_changed: true,
+    thinking_level_changed: true,
+    auto_retry_start: true,
+    auto_retry_end: true,
+    summarization_retry_scheduled: true,
+    summarization_retry_attempt_start: true,
+    summarization_retry_finished: true,
+    bash_execution_update: true,
+};
+const CONSUMED_JSON_EVENTS = new Set(["message_start", "message_update", "message_end", "agent_settled"]);
+const JSON_EVENT_TYPE = /^\s*\{\s*"type"\s*:\s*"([^"\\]+)"/;
+const JSON_STRING = `"(?:[^"\\\\\u0000-\u001f]|\\\\(?:["\\\\/bfnrt]|u[0-9a-fA-F]{4}))*"`;
+const JSON_OVERSIZED_TOOL_START = new RegExp(`^\\s*\\{\\s*"type"\\s*:\\s*"tool_execution_start"\\s*,\\s*"toolCallId"\\s*:\\s*(${JSON_STRING})\\s*,\\s*"toolName"\\s*:\\s*(${JSON_STRING})(?=\\s*,)`);
+export class EphemeralSubagentError extends Error {
+    name = "EphemeralSubagentError";
+    code;
+    usage;
+    output;
+    constructor(code, message, cause, usage, output) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.code = code;
+        this.usage = usage;
+        this.output = output;
+    }
+}
+function positiveDelay(value, field) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > MAX_TIMER_DELAY_MS) {
+        throw new RangeError(`${field} must be a positive number no greater than ${MAX_TIMER_DELAY_MS}.`);
+    }
+    return value;
+}
+function validateOptions(options) {
+    if (!options || typeof options !== "object")
+        throw new TypeError("Ephemeral Subagent executor options are required.");
+    if (!Number.isSafeInteger(options.maxConcurrency) || options.maxConcurrency < 1) {
+        throw new RangeError("maxConcurrency must be a positive safe integer.");
+    }
+    const maxTurns = options.maxTurns === undefined ? DEFAULT_MAX_TURNS : options.maxTurns;
+    if (!Number.isSafeInteger(maxTurns) || maxTurns < 1) {
+        throw new RangeError("maxTurns must be a safe integer >= 1.");
+    }
+    if (options.maxTokens !== undefined && (!Number.isSafeInteger(options.maxTokens) || options.maxTokens < 1)) {
+        throw new RangeError("maxTokens must be a safe integer >= 1.");
+    }
+    if (!options.timeout || typeof options.timeout !== "object")
+        throw new TypeError("timeout is required.");
+    const timeout = {
+        idleMs: positiveDelay(options.timeout.idleMs, "timeout.idleMs"),
+        maxMs: options.timeout.maxMs === null ? null : positiveDelay(options.timeout.maxMs, "timeout.maxMs"),
+    };
+    if (timeout.maxMs !== null && timeout.maxMs <= timeout.idleMs)
+        throw new RangeError("timeout.maxMs must be greater than timeout.idleMs.");
+    return {
+        maxConcurrency: options.maxConcurrency,
+        maxTurns,
+        ...(options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens }),
+        timeout,
+    };
+}
+function abortError(signal, cause = signal?.reason, usage) {
+    return new EphemeralSubagentError("aborted", "Subagent was aborted.", cause, usage);
+}
+function validateRunInput(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("Ephemeral Subagent run input must be an object.");
+    }
+    const input = value;
+    if (typeof input.prepare !== "function")
+        throw new TypeError("run.prepare must be a function.");
+    if (input.signal !== undefined && !(input.signal instanceof AbortSignal)) {
+        throw new TypeError("run.signal must be an AbortSignal.");
+    }
+    if (input.onUpdate !== undefined && typeof input.onUpdate !== "function") {
+        throw new TypeError("run.onUpdate must be a function.");
+    }
+    if (input.onTokens !== undefined && typeof input.onTokens !== "function") {
+        throw new TypeError("run.onTokens must be a function.");
+    }
+    if (input.onActivity !== undefined && typeof input.onActivity !== "function") {
+        throw new TypeError("run.onActivity must be a function.");
+    }
+    return value;
+}
+function record(value, field) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new TypeError(`${field} must be an object.`);
+    return value;
+}
+function preparedText(value, field) {
+    if (typeof value !== "string" || !value.trim() || value.includes("\0")) {
+        throw new TypeError(`${field} must be non-empty text without NUL bytes.`);
+    }
+    return value;
+}
+function validatePrepared(value) {
+    const prepared = record(value, "Prepared Subagent output");
+    const launch = record(prepared.launch, "Prepared Subagent launch");
+    if (!Array.isArray(launch.args))
+        throw new TypeError("Prepared Subagent launch args must be an array of strings.");
+    const args = [];
+    for (const [index, arg] of launch.args.entries()) {
+        if (typeof arg !== "string" || arg.includes("\0")) {
+            throw new TypeError(`Prepared Subagent launch arg ${index} must be a string without NUL bytes.`);
+        }
+        args.push(arg);
+    }
+    const launchEnv = record(launch.env, "Prepared Subagent launch env");
+    const env = Object.create(null);
+    for (const [name, value] of Object.entries(launchEnv)) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            throw new TypeError(`Invalid prepared launch environment name: ${name}`);
+        if (typeof value !== "string" || value.includes("\0")) {
+            throw new TypeError(`Invalid prepared launch environment value: ${name}`);
+        }
+        env[name] = value;
+    }
+    return {
+        launch: { args, env },
+        task: preparedText(prepared.task, "Prepared Subagent task"),
+        cwd: preparedText(prepared.cwd, "Prepared Subagent cwd"),
+    };
+}
+/**
+ * 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 function createEphemeralSubagentExecutor(options) {
+    const validated = validateOptions(options);
+    if (process.env.PI_CODING_AGENT !== "true" || (process.title !== "pi" && process.title !== "pi-rpc")) {
+        const cause = new Error("Ephemeral Subagent executor requires active Pi (PI_CODING_AGENT=true and process title pi or pi-rpc).");
+        throw new EphemeralSubagentError("prepare", cause.message, cause);
+    }
+    const invocation = piInvocation();
+    let active = 0;
+    const queue = [];
+    const acquire = (signal) => {
+        if (signal?.aborted)
+            return Promise.reject(abortError(signal));
+        if (active < validated.maxConcurrency) {
+            active += 1;
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const abort = () => {
+                const index = queue.indexOf(grant);
+                if (index < 0)
+                    return;
+                queue.splice(index, 1);
+                signal?.removeEventListener("abort", abort);
+                reject(abortError(signal));
+            };
+            const grant = () => {
+                signal?.removeEventListener("abort", abort);
+                resolve();
+            };
+            queue.push(grant);
+            signal?.addEventListener("abort", abort, { once: true });
+        });
+    };
+    const release = () => {
+        const grant = queue.shift();
+        if (grant)
+            grant();
+        else
+            active -= 1;
+    };
+    return {
+        async run(value) {
+            const input = validateRunInput(value);
+            await acquire(input.signal);
+            try {
+                if (input.signal?.aborted)
+                    throw abortError(input.signal);
+                let prepared;
+                try {
+                    prepared = validatePrepared(await input.prepare());
+                }
+                catch (cause) {
+                    if (input.signal?.aborted)
+                        throw abortError(input.signal, cause);
+                    throw new EphemeralSubagentError("prepare", cause instanceof Error ? cause.message : String(cause), cause);
+                }
+                return await runPi(prepared, input, validated, invocation);
+            }
+            finally {
+                release();
+            }
+        },
+    };
+}
+function piInvocation() {
+    const currentScript = process.argv[1];
+    const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
+    if (currentScript && !isBunVirtualScript && existsSync(currentScript)) {
+        return { command: process.execPath, args: [currentScript] };
+    }
+    if (isBunVirtualScript)
+        return { command: process.execPath, args: [] };
+    const executable = basename(process.execPath).toLowerCase();
+    if (!/^(node|bun)(\.exe)?$/.test(executable))
+        return { command: process.execPath, args: [] };
+    const cause = new Error("Ephemeral Subagent executor cannot reuse the active Pi process invocation.");
+    throw new EphemeralSubagentError("prepare", cause.message, cause);
+}
+function assistantText(message) {
+    if (!message || typeof message !== "object" || Array.isArray(message))
+        return;
+    const record = message;
+    if (record.role !== "assistant" || !Array.isArray(record.content))
+        return;
+    const text = record.content
+        .filter((part) => Boolean(part && typeof part === "object" && !Array.isArray(part)
+        && part.type === "text"
+        && typeof part.text === "string"))
+        .map((part) => part.text)
+        .join("\n");
+    return text || undefined;
+}
+function activityTooLong(value) {
+    return typeof value === "string" && Buffer.byteLength(value, "utf8") > MAX_ACTIVITY_TEXT_BYTES;
+}
+function hasTerminalControlChars(text) {
+    return hasDisplayControlCharacters(text) || /[\u2028\u2029]/u.test(text);
+}
+function activityText(value) {
+    return typeof value === "string" && value.trim().length > 0 && !activityTooLong(value) && !hasTerminalControlChars(value);
+}
+function oversizedToolStart(prefix) {
+    const match = JSON_OVERSIZED_TOOL_START.exec(prefix);
+    if (!match)
+        return;
+    try {
+        const toolCallId = JSON.parse(match[1]);
+        const toolName = JSON.parse(match[2]);
+        if (!activityText(toolCallId) || !activityText(toolName))
+            return;
+        return { type: "tool_execution_start", toolCallId, toolName };
+    }
+    catch {
+        return;
+    }
+}
+/** Longest prefix of `text` within `maxBytes` UTF-8 bytes, never splitting a code point. */
+export function utf8Prefix(text, maxBytes) {
+    return new StringDecoder().write(Buffer.from(text).subarray(0, maxBytes));
+}
+function cappedPrefix(text, totalBytes) {
+    if (totalBytes <= MAX_OUTPUT_BYTES)
+        return text;
+    const worstCaseMarker = `\n\n[Output truncated: ${totalBytes} bytes omitted]`;
+    const prefix = utf8Prefix(text, MAX_OUTPUT_BYTES - Buffer.byteLength(worstCaseMarker, "utf8"));
+    const omittedBytes = totalBytes - Buffer.byteLength(prefix, "utf8");
+    return `${prefix}\n\n[Output truncated: ${omittedBytes} bytes omitted]`;
+}
+export function capEphemeralSubagentOutput(text) {
+    return cappedPrefix(text, Buffer.byteLength(text, "utf8"));
+}
+function appendBounded(target, text) {
+    target.totalBytes += Buffer.byteLength(text, "utf8");
+    const remaining = MAX_OUTPUT_BYTES - Buffer.byteLength(target.prefix, "utf8");
+    if (remaining > 0)
+        target.prefix += utf8Prefix(text, remaining);
+}
+function boundedText(target) {
+    return cappedPrefix(target.prefix, target.totalBytes);
+}
+function usageTokens(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return;
+    const total = value.totalTokens;
+    return typeof total === "number" && Number.isFinite(total) && total >= 0 ? Math.round(total) : undefined;
+}
+function nonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function usageFrom(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return;
+    const record = value;
+    if (![record.input, record.output, record.cacheRead, record.cacheWrite, record.totalTokens].every(nonNegativeNumber))
+        return;
+    if (!record.cost || typeof record.cost !== "object" || Array.isArray(record.cost))
+        return;
+    const cost = record.cost;
+    if (![cost.input, cost.output, cost.cacheRead, cost.cacheWrite, cost.total].every(nonNegativeNumber))
+        return;
+    if (record.cacheWrite1h !== undefined && !nonNegativeNumber(record.cacheWrite1h))
+        return;
+    if (record.reasoning !== undefined && !nonNegativeNumber(record.reasoning))
+        return;
+    return {
+        input: record.input,
+        output: record.output,
+        cacheRead: record.cacheRead,
+        cacheWrite: record.cacheWrite,
+        ...(record.cacheWrite1h === undefined ? {} : { cacheWrite1h: record.cacheWrite1h }),
+        ...(record.reasoning === undefined ? {} : { reasoning: record.reasoning }),
+        totalTokens: record.totalTokens,
+        cost: {
+            input: cost.input,
+            output: cost.output,
+            cacheRead: cost.cacheRead,
+            cacheWrite: cost.cacheWrite,
+            total: cost.total,
+        },
+    };
+}
+function sumOptional(left, right) {
+    return left === undefined && right === undefined ? undefined : (left ?? 0) + (right ?? 0);
+}
+export function addUsage(left, right) {
+    if (!left)
+        return right;
+    if (!right)
+        return left;
+    const cacheWrite1h = sumOptional(left.cacheWrite1h, right.cacheWrite1h);
+    const reasoning = sumOptional(left.reasoning, right.reasoning);
+    return {
+        input: left.input + right.input,
+        output: left.output + right.output,
+        cacheRead: left.cacheRead + right.cacheRead,
+        cacheWrite: left.cacheWrite + right.cacheWrite,
+        ...(cacheWrite1h === undefined ? {} : { cacheWrite1h }),
+        ...(reasoning === undefined ? {} : { reasoning }),
+        totalTokens: left.totalTokens + right.totalTokens,
+        cost: {
+            input: left.cost.input + right.cost.input,
+            output: left.cost.output + right.cost.output,
+            cacheRead: left.cost.cacheRead + right.cost.cacheRead,
+            cacheWrite: left.cost.cacheWrite + right.cost.cacheWrite,
+            total: left.cost.total + right.cost.total,
+        },
+    };
+}
+export function formatDuration(milliseconds) {
+    const seconds = Math.max(0, Math.floor(milliseconds / 1_000));
+    const hours = Math.floor(seconds / 3_600);
+    const minutes = Math.floor(seconds % 3_600 / 60);
+    return hours ? `${hours}h ${minutes}m` : minutes ? `${minutes}m ${seconds % 60}s` : `${seconds}s`;
+}
+async function runPi(prepared, input, budget, invocation) {
+    if (input.signal?.aborted)
+        throw abortError(input.signal);
+    const timeoutPolicy = budget.timeout;
+    return await new Promise((resolve, reject) => {
+        const args = [...invocation.args, "--mode", "json", "-p", ...prepared.launch.args, `Task: ${prepared.task}`];
+        const startedAt = Date.now();
+        const maxDeadline = timeoutPolicy.maxMs === null ? undefined : startedAt + timeoutPolicy.maxMs;
+        let child;
+        try {
+            const executionBudget = {
+                maxTurns: budget.maxTurns,
+                maxMs: timeoutPolicy.maxMs,
+                startedAt,
+                ...(budget.maxTokens === undefined ? {} : { maxTokens: budget.maxTokens }),
+            };
+            child = spawn(invocation.command, args, {
+                cwd: prepared.cwd,
+                env: {
+                    ...process.env,
+                    ...prepared.launch.env,
+                    [EXECUTION_BUDGET_ENV]: JSON.stringify(executionBudget),
+                },
+                shell: false,
+                stdio: ["ignore", "pipe", "pipe"],
+                detached: process.platform !== "win32",
+            });
+        }
+        catch (cause) {
+            reject(new EphemeralSubagentError("spawn", cause instanceof Error ? cause.message : String(cause), cause));
+            return;
+        }
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        let lineParts = [];
+        let lineBytes = 0;
+        let linePrefix = "";
+        let lineEventType;
+        let ignoreLine = false;
+        let output = "";
+        let outputTruncated = false;
+        const stderr = { prefix: "", totalBytes: 0 };
+        const partial = { prefix: "", totalBytes: 0 };
+        const updateOutput = (nextOutput) => {
+            output = nextOutput;
+            outputTruncated = partial.totalBytes > MAX_OUTPUT_BYTES;
+        };
+        let hasPartialText = false;
+        let stopReason;
+        let errorMessage;
+        let spawnError;
+        let protocolError;
+        let aborted = false;
+        let settlementAborted = false;
+        let limit;
+        let tokenBudget = "within";
+        let startedTurns = 0;
+        let lastEventAt = startedAt;
+        let deadline = Math.min(startedAt + timeoutPolicy.idleMs, maxDeadline ?? startedAt + timeoutPolicy.idleMs);
+        let timedOutAfterMs;
+        let timeoutReason;
+        let childExited = false;
+        let completedTokens = 0;
+        let currentTokens = 0;
+        let completedUsage;
+        let currentUsage;
+        const accumulatedUsage = () => addUsage(completedUsage, currentUsage);
+        let deadlineTimer;
+        let killTimer;
+        let postExitIdleTimer;
+        let postExitHardTimer;
+        let callbackDrainTimer;
+        let stdoutEnded = false;
+        let stderrEnded = false;
+        let settled = false;
+        let cleaned = false;
+        let callbackFailure;
+        const pendingCallbacks = new Set();
+        let signalCallbackFailure;
+        const callbackFailed = new Promise((resolve) => { signalCallbackFailure = resolve; });
+        let onStdoutData;
+        let onStderrData;
+        let onStdoutEnd;
+        let onStderrEnd;
+        let onStdoutClose;
+        let onStderrClose;
+        let onChildError;
+        let onChildExit;
+        let onChildClose;
+        const clearTimer = (timer) => {
+            if (timer)
+                clearTimeout(timer);
+        };
+        const clearLifecycle = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            clearTimer(deadlineTimer);
+            clearTimer(killTimer);
+            clearTimer(postExitIdleTimer);
+            clearTimer(postExitHardTimer);
+            clearTimer(callbackDrainTimer);
+            input.signal?.removeEventListener("abort", abort);
+            if (onStdoutData)
+                child.stdout.off("data", onStdoutData);
+            if (onStderrData)
+                child.stderr.off("data", onStderrData);
+            if (onStdoutEnd)
+                child.stdout.off("end", onStdoutEnd);
+            if (onStderrEnd)
+                child.stderr.off("end", onStderrEnd);
+            if (onStdoutClose)
+                child.stdout.off("close", onStdoutClose);
+            if (onStderrClose)
+                child.stderr.off("close", onStderrClose);
+            if (onChildError)
+                child.off("error", onChildError);
+            if (onChildExit)
+                child.off("exit", onChildExit);
+            if (onChildClose)
+                child.off("close", onChildClose);
+        };
+        const complete = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearLifecycle();
+            if (callbackFailure) {
+                reject(new EphemeralSubagentError("callback", callbackFailure.message, callbackFailure.cause, accumulatedUsage()));
+            }
+            else if (aborted)
+                reject(abortError(input.signal, input.signal?.reason, accumulatedUsage()));
+            else if (timedOutAfterMs !== undefined) {
+                const message = timeoutReason === "maximum"
+                    ? `Subagent reached its maximum runtime after ${formatDuration(timedOutAfterMs)}.`
+                    : `Subagent timed out after ${formatDuration(timeoutPolicy.idleMs)} without a recognized Pi event.`;
+                reject(new EphemeralSubagentError("timeout", message, new Error(message), accumulatedUsage()));
+            }
+            else if (limit) {
+                const summary = limit === "turn_limit"
+                    ? `Subagent reached its maximum turn limit of ${budget.maxTurns}.`
+                    : `Subagent reached its maximum token limit of ${budget.maxTokens}.`;
+                const message = output ? capEphemeralSubagentOutput(`${summary}\n\nLast assistant output:\n${output}`) : summary;
+                reject(new EphemeralSubagentError(limit, message, new Error(message), accumulatedUsage(), output));
+            }
+            else if (protocolError) {
+                reject(new EphemeralSubagentError("protocol", protocolError.message, protocolError, accumulatedUsage()));
+            }
+            else if (spawnError) {
+                reject(new EphemeralSubagentError("spawn", spawnError.message, spawnError));
+            }
+            else {
+                const exitCode = code ?? 1;
+                if (settlementAborted)
+                    stopReason = "aborted";
+                const outcome = exitCode !== 0 || stopReason === "error" || stopReason === "aborted" ? "failure" : "success";
+                resolve({
+                    outcome,
+                    exitCode,
+                    output,
+                    outputTruncated,
+                    stderr: boundedText(stderr),
+                    stopReason,
+                    errorMessage,
+                    usage: addUsage(completedUsage, currentUsage),
+                });
+            }
+        };
+        const failCallback = (name, cause) => {
+            if (callbackFailure)
+                return;
+            callbackFailure = new EphemeralSubagentError("callback", `Subagent ${name} callback failed.`, cause);
+            signalCallbackFailure();
+            stop(true);
+        };
+        let activityQueue = Promise.resolve();
+        const invokeCallback = (name, callback, value) => {
+            if (!callback || callbackFailure)
+                return;
+            let pending;
+            if (name === "onActivity") {
+                pending = activityQueue.then(() => {
+                    if (!callbackFailure)
+                        return callback(value);
+                }).catch((cause) => { failCallback(name, cause); });
+                activityQueue = pending;
+            }
+            else {
+                try {
+                    pending = Promise.resolve(callback(value)).then(undefined, (cause) => { failCallback(name, cause); });
+                }
+                catch (cause) {
+                    failCallback(name, cause);
+                    return;
+                }
+            }
+            pendingCallbacks.add(pending);
+            void pending.then(() => pendingCallbacks.delete(pending));
+        };
+        const scheduleDeadline = () => {
+            if (deadlineTimer)
+                clearTimeout(deadlineTimer);
+            deadline = Math.min(lastEventAt + timeoutPolicy.idleMs, maxDeadline ?? lastEventAt + timeoutPolicy.idleMs);
+            const scheduledDeadline = deadline;
+            deadlineTimer = setTimeout(() => timeout(scheduledDeadline - startedAt, scheduledDeadline === maxDeadline ? "maximum" : "idle"), Math.max(0, scheduledDeadline - Date.now()));
+            deadlineTimer.unref();
+        };
+        const observeEvent = () => {
+            if (callbackFailure || aborted || timedOutAfterMs !== undefined || limit || childExited)
+                return;
+            const now = Date.now();
+            if (now >= deadline) {
+                timeout(deadline - startedAt, deadline === maxDeadline ? "maximum" : "idle");
+                return;
+            }
+            lastEventAt = now;
+            scheduleDeadline();
+        };
+        const advanceTokenBudget = (event) => {
+            switch (tokenBudget) {
+                case "within":
+                    if (event === "turn_end" && budget.maxTokens !== undefined && completedTokens >= budget.maxTokens) {
+                        tokenBudget = "crossed";
+                    }
+                    return false;
+                case "crossed":
+                    if (event === "turn_start")
+                        tokenBudget = "final_turn";
+                    return false;
+                case "final_turn":
+                    if (event === "turn_start") {
+                        if (!callbackFailure && !aborted && timedOutAfterMs === undefined)
+                            limit = "token_limit";
+                        stop(true);
+                        return true;
+                    }
+                    return false;
+            }
+        };
+        const processLine = (line) => {
+            if (limit || !line.trim())
+                return;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (!event || typeof event !== "object" || Array.isArray(event))
+                return;
+            const record = event;
+            if (typeof record.type !== "string" || !Object.hasOwn(PI_JSON_EVENTS, record.type))
+                return;
+            if (record.type === "agent_settled") {
+                if (typeof record.aborted !== "boolean") {
+                    protocolError = new Error("Subagent agent_settled.aborted must be a boolean.");
+                    stop(true);
+                    return;
+                }
+                settlementAborted ||= record.aborted;
+            }
+            observeEvent();
+            if (record.type === "turn_start") {
+                if (++startedTurns > budget.maxTurns) {
+                    if (!callbackFailure && !aborted && timedOutAfterMs === undefined)
+                        limit = "turn_limit";
+                    stop(true);
+                    return;
+                }
+                if (advanceTokenBudget("turn_start"))
+                    return;
+            }
+            if (record.type === "turn_end")
+                advanceTokenBudget("turn_end");
+            if (record.type === "message_start") {
+                partial.prefix = "";
+                partial.totalBytes = 0;
+                hasPartialText = false;
+                currentUsage = undefined;
+                return;
+            }
+            if (record.type === "message_update") {
+                const tokens = usageTokens(record.usage);
+                if (tokens !== undefined) {
+                    currentTokens = tokens;
+                    invokeCallback("onTokens", input.onTokens, completedTokens + currentTokens);
+                }
+                currentUsage = usageFrom(record.usage) ?? currentUsage;
+                const update = record.assistantMessageEvent;
+                if (update && typeof update === "object" && !Array.isArray(update)) {
+                    const assistantEvent = update;
+                    if (assistantEvent.type === "text_start" && hasPartialText) {
+                        appendBounded(partial, "\n");
+                        updateOutput(boundedText(partial));
+                    }
+                    if (assistantEvent.type === "text_start")
+                        hasPartialText = true;
+                    if (assistantEvent.type === "text_delta" && typeof assistantEvent.delta === "string") {
+                        hasPartialText = true;
+                        appendBounded(partial, assistantEvent.delta);
+                        updateOutput(boundedText(partial));
+                        invokeCallback("onUpdate", input.onUpdate, output);
+                    }
+                }
+                return;
+            }
+            if (record.type === "tool_execution_start" || record.type === "tool_execution_end") {
+                const { toolCallId, toolName } = record;
+                if (!activityText(toolCallId) || !activityText(toolName))
+                    return;
+                if (record.type === "tool_execution_start") {
+                    const args = record.args;
+                    const path = args && typeof args === "object" && !Array.isArray(args)
+                        ? args.path
+                        : undefined;
+                    if (activityTooLong(path))
+                        return;
+                    invokeCallback("onActivity", input.onActivity, {
+                        type: "tool_execution_start",
+                        toolCallId,
+                        toolName,
+                        ...(activityText(path) ? { path } : {}),
+                    });
+                }
+                else {
+                    invokeCallback("onActivity", input.onActivity, { type: "tool_execution_end", toolCallId, toolName });
+                }
+                return;
+            }
+            if (record.type !== "message_end")
+                return;
+            const text = assistantText(record.message);
+            if (text !== undefined) {
+                partial.prefix = "";
+                partial.totalBytes = 0;
+                appendBounded(partial, text);
+                updateOutput(capEphemeralSubagentOutput(text));
+                invokeCallback("onUpdate", input.onUpdate, output);
+            }
+            if (record.message && typeof record.message === "object" && !Array.isArray(record.message)) {
+                const message = record.message;
+                if (message.role === "assistant") {
+                    const finalUsage = usageFrom(message.usage) ?? currentUsage;
+                    completedUsage = addUsage(completedUsage, finalUsage);
+                    completedTokens += usageTokens(message.usage) ?? currentTokens;
+                    currentTokens = 0;
+                    currentUsage = undefined;
+                    invokeCallback("onTokens", input.onTokens, completedTokens);
+                    invokeCallback("onActivity", input.onActivity, { type: "message_end" });
+                }
+                if (typeof message.stopReason === "string")
+                    stopReason = message.stopReason;
+                if (typeof message.errorMessage === "string")
+                    errorMessage = message.errorMessage;
+            }
+        };
+        async function killTree(force) {
+            if (!child.pid)
+                return;
+            if (process.platform === "win32") {
+                await new Promise((done) => {
+                    const taskkill = spawn("taskkill", [...(force ? ["/F"] : []), "/T", "/PID", String(child.pid)], {
+                        stdio: "ignore",
+                        windowsHide: true,
+                    });
+                    taskkill.once("error", () => done());
+                    taskkill.once("close", () => done());
+                });
+                return;
+            }
+            try {
+                process.kill(-child.pid, force ? "SIGKILL" : "SIGTERM");
+            }
+            catch {
+                child.kill(force ? "SIGKILL" : "SIGTERM");
+            }
+        }
+        // `close` waits for stdio EOF, which an escaped descendant can retain after Pi exits.
+        const clearPostExitTimers = () => {
+            clearTimer(postExitIdleTimer);
+            clearTimer(postExitHardTimer);
+            postExitIdleTimer = undefined;
+            postExitHardTimer = undefined;
+        };
+        const destroyOpenStdio = () => {
+            if (!stdoutEnded)
+                child.stdout.destroy();
+            if (!stderrEnded)
+                child.stderr.destroy();
+        };
+        const armPostExitIdleDeadline = () => {
+            if (!childExited || (stdoutEnded && stderrEnded))
+                return;
+            clearTimer(postExitIdleTimer);
+            postExitIdleTimer = setTimeout(destroyOpenStdio, POST_EXIT_STDIO_IDLE_MS);
+            postExitIdleTimer.unref();
+        };
+        const endStdio = () => {
+            if (stdoutEnded && stderrEnded)
+                clearPostExitTimers();
+        };
+        onStdoutData = (data) => {
+            armPostExitIdleDeadline();
+            if (callbackFailure || protocolError || limit)
+                return;
+            let offset = 0;
+            while (offset < data.length) {
+                const newline = data.indexOf("\n", offset);
+                const end = newline === -1 ? data.length : newline;
+                const part = data.slice(offset, end);
+                if (!ignoreLine) {
+                    const remainingPrefix = MAX_ACTIVITY_PREFIX_BYTES - Buffer.byteLength(linePrefix, "utf8");
+                    if (remainingPrefix > 0)
+                        linePrefix += utf8Prefix(part, remainingPrefix);
+                    const eventType = JSON_EVENT_TYPE.exec(linePrefix)?.[1];
+                    if (eventType && !lineEventType)
+                        lineEventType = eventType;
+                    lineBytes += Buffer.byteLength(part, "utf8");
+                    if (lineBytes > MAX_JSON_EVENT_BYTES) {
+                        if (lineEventType && !CONSUMED_JSON_EVENTS.has(lineEventType)) {
+                            ignoreLine = true;
+                            lineParts = [];
+                            lineBytes = 0;
+                        }
+                        else {
+                            protocolError = new Error(`Subagent JSON event exceeds ${MAX_JSON_EVENT_BYTES} bytes.`);
+                            void killTree(true);
+                            return;
+                        }
+                    }
+                    else if (part)
+                        lineParts.push(part);
+                }
+                if (newline === -1)
+                    return;
+                if (!ignoreLine)
+                    processLine(lineParts.join(""));
+                else if (lineEventType === "tool_execution_start") {
+                    const activity = oversizedToolStart(linePrefix);
+                    if (activity) {
+                        observeEvent();
+                        invokeCallback("onActivity", input.onActivity, activity);
+                    }
+                }
+                if (callbackFailure || limit)
+                    return;
+                lineParts = [];
+                lineBytes = 0;
+                linePrefix = "";
+                lineEventType = undefined;
+                ignoreLine = false;
+                offset = newline + 1;
+            }
+        };
+        onStderrData = (data) => {
+            armPostExitIdleDeadline();
+            appendBounded(stderr, data);
+        };
+        onStdoutEnd = () => {
+            stdoutEnded = true;
+            endStdio();
+        };
+        onStderrEnd = () => {
+            stderrEnded = true;
+            endStdio();
+        };
+        onStdoutClose = onStdoutEnd;
+        onStderrClose = onStderrEnd;
+        child.stdout.on("data", onStdoutData);
+        child.stderr.on("data", onStderrData);
+        child.stdout.on("end", onStdoutEnd);
+        child.stderr.on("end", onStderrEnd);
+        child.stdout.on("close", onStdoutClose);
+        child.stderr.on("close", onStderrClose);
+        function stop(force = false) {
+            if (force) {
+                void killTree(true);
+                return;
+            }
+            void killTree(false);
+            killTimer = setTimeout(() => void killTree(true), maxDeadline === undefined ? 5_000 : Math.min(5_000, Math.max(0, maxDeadline - Date.now())));
+            killTimer.unref();
+        }
+        const abort = () => {
+            if (timedOutAfterMs !== undefined || limit || childExited)
+                return;
+            aborted = true;
+            stop();
+        };
+        function timeout(afterMs, reason) {
+            if (timedOutAfterMs !== undefined || limit || childExited)
+                return;
+            if (reason === "maximum") {
+                if (!aborted) {
+                    timedOutAfterMs = afterMs;
+                    timeoutReason = reason;
+                }
+                stop(true);
+                return;
+            }
+            if (aborted)
+                return;
+            timedOutAfterMs = afterMs;
+            timeoutReason = reason;
+            stop();
+        }
+        onChildError = (error) => {
+            spawnError = error;
+            if (input.signal?.aborted)
+                aborted = true;
+        };
+        onChildExit = () => {
+            childExited = true;
+            clearTimer(deadlineTimer);
+            clearTimer(killTimer);
+            void killTree(true);
+            armPostExitIdleDeadline();
+            postExitHardTimer = setTimeout(destroyOpenStdio, POST_EXIT_STDIO_HARD_MS);
+            postExitHardTimer.unref();
+        };
+        onChildClose = async (code) => {
+            if (settled)
+                return;
+            if (!callbackFailure && !protocolError && lineBytes)
+                processLine(lineParts.join(""));
+            await killTree(true);
+            // A caller callback that never settles must not hold `run()` or its permit
+            // past child exit; bound the drain by what remains of the maximum runtime.
+            callbackDrainTimer = setTimeout(() => {
+                callbackFailure ??= new EphemeralSubagentError("callback", "Subagent callback did not settle before the post-exit drain deadline.");
+                signalCallbackFailure();
+            }, maxDeadline === undefined ? 5_000 : Math.min(5_000, Math.max(0, maxDeadline - Date.now())));
+            await Promise.race([Promise.all(pendingCallbacks), callbackFailed]);
+            complete(code);
+        };
+        child.once("error", onChildError);
+        child.once("exit", onChildExit);
+        child.once("close", onChildClose);
+        scheduleDeadline();
+        input.signal?.addEventListener("abort", abort, { once: true });
+        if (input.signal?.aborted)
+            abort();
+    });
+}