@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/executors/pi-executor.js

@@ -0,0 +1,981 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { PI_REUSE_RUNTIME_ENV, isPiReuseRuntimeEffective, resolvePiReuseRuntimeMode as resolveConfiguredPiReuseRuntimeMode, } from "./pi-runtime-reuse.js";
+import { cleanupPiPromptTransport, createPiPromptTransport, } from "./pi-prompt-transport.js";
+import { processTreeSpawnOptions, terminateProcessTree, } from "./process-tree.js";
+export function extractSubagentStats(stdout) {
+    let totalCalls = 0;
+    let failedCalls = 0;
+    const modes = new Set();
+    const agents = new Set();
+    for (const line of stdout.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const event = JSON.parse(trimmed);
+            if (event.type === "tool_execution_start" &&
+                event.toolName === "subagent") {
+                totalCalls += 1;
+                if (isRecord(event.input)) {
+                    if (event.input.agent)
+                        agents.add(String(event.input.agent));
+                    if (event.input.tasks)
+                        modes.add("parallel");
+                    if (event.input.chain)
+                        modes.add("chain");
+                    if (event.input.agent && !event.input.tasks && !event.input.chain)
+                        modes.add("single");
+                }
+            }
+            if (event.type === "tool_execution_end" &&
+                event.toolName === "subagent") {
+                if (event.isError === true)
+                    failedCalls += 1;
+            }
+        }
+        catch {
+            // tolerate non-json noise
+        }
+    }
+    if (totalCalls === 0)
+        return "calls=0";
+    const parts = [`calls=${totalCalls}`];
+    if (failedCalls > 0)
+        parts.push(`${failedCalls} failed`);
+    if (modes.size > 0)
+        parts.push(Array.from(modes).sort().join("+"));
+    if (agents.size > 0)
+        parts.push(`agents=[${Array.from(agents).sort().join(",")}]`);
+    return parts.join(" | ");
+}
+/** Absolute max wall clock for a single Pi attempt (4h). Not renewed by empty heartbeats. */
+export const DEFAULT_TIMEOUT_MS = 14_400_000;
+export const MAX_ALLOWED_TIMEOUT_MS = 14_400_000;
+/** Max provider/CLI transport silence before initiating a controlled abort (15m). */
+export const DEFAULT_STALL_TIMEOUT_MS = 900_000;
+/** Grace after SIGTERM before SIGKILL on absolute max. */
+export const DEFAULT_ABORT_GRACE_MS = 30_000;
+const PI_BACKEND_ENV = "CODE_AGENT_PI_BACKEND";
+const OUTPUT_PREVIEW_HEAD_CHARS = 64_000;
+const OUTPUT_PREVIEW_TAIL_CHARS = 64_000;
+const MAX_STREAM_JSONL_LINE_CHARS = 16_000_000;
+const MAX_ASSISTANT_TEXT_CHARS = 16_000_000;
+const PI_CLI_PACKAGE_NAMES = [
+    "@earendil-works/pi-coding-agent",
+    "@mariozechner/pi-coding-agent",
+];
+export { PI_REUSE_RUNTIME_ENV };
+/** Resolve configured Pi SDK runtime reuse mode. Default off; unknown values fall back to off. */
+export function resolvePiReuseRuntimeMode() {
+    return resolveConfiguredPiReuseRuntimeMode();
+}
+/** True only when reuse is opt-in and SDK path is allowed (not cli-only). */
+export function isPiReuseRuntimeEnabled() {
+    return isPiReuseRuntimeEffective(resolvePiReuseRuntimeMode(), resolvePiBackend());
+}
+/**
+ * Run `fn` inside an opt-in Pi SDK reuse scope when effective.
+ * When reuse is off or backend is cli-only, calls `fn` directly with no scope.
+ */
+export async function withPiReuseRuntimeScope(fn) {
+    if (!isPiReuseRuntimeEnabled()) {
+        return fn();
+    }
+    const { beginPiSdkReuseScope, endPiSdkReuseScope } = await import("./pi-sdk-executor.js");
+    beginPiSdkReuseScope();
+    try {
+        return await fn();
+    }
+    finally {
+        await endPiSdkReuseScope();
+    }
+}
+/** Resolve configured Pi backend mode. Default sdk-first; cli-only preserves pure CLI path. */
+export function resolvePiBackend() {
+    const raw = process.env[PI_BACKEND_ENV]?.trim().toLowerCase();
+    if (raw === "cli-only")
+        return "cli-only";
+    if (raw === "sdk-first" || !raw)
+        return "sdk-first";
+    return "sdk-first";
+}
+function piCliPathFromPackageRoot(nodeModulesRoot, packageName) {
+    return path.join(nodeModulesRoot, ...packageName.split("/"), "dist", "cli.js");
+}
+function findExistingPiCliUnderNodeModules(nodeModulesRoot) {
+    for (const packageName of PI_CLI_PACKAGE_NAMES) {
+        const candidate = piCliPathFromPackageRoot(nodeModulesRoot, packageName);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function resolveGlobalNpmPiCliPath() {
+    try {
+        const npmRoot = spawnSync("npm", ["root", "-g"], { encoding: "utf-8" });
+        if (npmRoot.status === 0 && npmRoot.stdout.trim()) {
+            return findExistingPiCliUnderNodeModules(npmRoot.stdout.trim());
+        }
+    }
+    catch {
+        // npm not available
+    }
+    return undefined;
+}
+function resolvePiCliNearShim(shimPath) {
+    if (!existsSync(shimPath))
+        return undefined;
+    const shimDir = path.dirname(shimPath);
+    const nearGlobalShim = findExistingPiCliUnderNodeModules(path.join(shimDir, "node_modules"));
+    if (nearGlobalShim)
+        return nearGlobalShim;
+    if (shimDir.endsWith(`${path.sep}.bin`)) {
+        const nearLocalBin = findExistingPiCliUnderNodeModules(path.join(shimDir, ".."));
+        if (nearLocalBin)
+            return nearLocalBin;
+    }
+    return undefined;
+}
+function resolvePiCliFromPathLookup() {
+    const lookupCommands = process.platform === "win32"
+        ? [{ command: "where.exe", args: ["pi"] }]
+        : [{ command: "which", args: ["pi"] }];
+    for (const lookup of lookupCommands) {
+        try {
+            const result = spawnSync(lookup.command, lookup.args, {
+                encoding: "utf-8",
+            });
+            if (result.status !== 0 || !result.stdout.trim())
+                continue;
+            for (const rawPath of result.stdout.split(/\r?\n/)) {
+                const lookupPath = rawPath.trim();
+                if (!lookupPath)
+                    continue;
+                const nearShim = resolvePiCliNearShim(lookupPath);
+                if (nearShim)
+                    return nearShim;
+                if (process.platform !== "win32") {
+                    try {
+                        const realPathResult = spawnSync("readlink", ["-f", lookupPath], {
+                            encoding: "utf-8",
+                        });
+                        if (realPathResult.status === 0 && realPathResult.stdout.trim()) {
+                            const resolved = realPathResult.stdout.trim();
+                            const nearResolvedShim = resolvePiCliNearShim(resolved);
+                            if (nearResolvedShim)
+                                return nearResolvedShim;
+                            if (existsSync(resolved))
+                                return resolved;
+                        }
+                    }
+                    catch {
+                        // readlink not available
+                    }
+                }
+                if (existsSync(lookupPath))
+                    return lookupPath;
+            }
+        }
+        catch {
+            // lookup command not available
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve the pi CLI script path.
+ * Uses the same resolution as `which pi` but avoids relying on `#!/usr/bin/env node`
+ * in the child process, which can lose provider visibility when spawned from tsx.
+ */
+function resolvePiCliPath() {
+    // Check common installation paths
+    const home = homedir();
+    // Try nvm paths with both "v"-prefixed and non-prefixed version directories
+    const nodeVersion = process.versions.node; // e.g. "22.19.0"
+    const nvmBase = path.join(home, ".nvm", "versions", "node");
+    const nvmCandidates = [
+        path.join(nvmBase, `v${nodeVersion}`, "lib", "node_modules"),
+        path.join(nvmBase, nodeVersion, "lib", "node_modules"),
+    ].flatMap((nodeModulesRoot) => PI_CLI_PACKAGE_NAMES.map((packageName) => piCliPathFromPackageRoot(nodeModulesRoot, packageName)));
+    const otherCandidates = [
+        // Prefer the project-local Pi dependency. `npm run` adds node_modules/.bin
+        // to PATH, but direct invocations from the DAG runner may not, so resolve
+        // the package from the current workspace explicitly.
+        ...PI_CLI_PACKAGE_NAMES.map((packageName) => piCliPathFromPackageRoot(path.resolve(process.cwd(), "node_modules"), packageName)),
+        // Global npm installation (non-nvm)
+        ...PI_CLI_PACKAGE_NAMES.map((packageName) => piCliPathFromPackageRoot("/usr/local/lib/node_modules", packageName)),
+        // Bun installation
+        ...PI_CLI_PACKAGE_NAMES.map((packageName) => piCliPathFromPackageRoot(path.join(home, ".bun", "install", "global", "node_modules"), packageName)),
+    ];
+    const allCandidates = [...nvmCandidates, ...otherCandidates];
+    for (const candidate of allCandidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    const globalNpmPi = resolveGlobalNpmPiCliPath();
+    if (globalNpmPi)
+        return globalNpmPi;
+    const pathLookupPi = resolvePiCliFromPathLookup();
+    if (pathLookupPi)
+        return pathLookupPi;
+    throw new Error("Could not resolve pi CLI path. Ensure pi is installed.");
+}
+let cachedPiCliPath;
+/** Lazily resolve and cache the pi CLI script path (avoids import-time sync I/O). */
+export function getPiCliPath() {
+    if (!cachedPiCliPath) {
+        cachedPiCliPath = resolvePiCliPath();
+    }
+    return cachedPiCliPath;
+}
+/** Test-only: reset lazy CLI path cache between isolated contract tests. */
+export function resetPiCliPathCacheForTests() {
+    cachedPiCliPath = undefined;
+}
+export function checkPiAvailability() {
+    // Use process.execPath to run pi CLI directly, avoiding shebang-based
+    // resolution that can drop built-in providers when spawned from tsx.
+    const result = spawnSync(process.execPath, [getPiCliPath(), "--help"], {
+        encoding: "utf-8",
+    });
+    if (result.error) {
+        return { ok: false, detail: result.error.message };
+    }
+    if (result.status !== 0) {
+        return { ok: false, detail: result.stderr || `exit ${result.status}` };
+    }
+    return { ok: true, detail: "pi available" };
+}
+export function extractAssistantTextFromPiJson(stdout) {
+    let assistantText = "";
+    let parsedEvents = 0;
+    for (const line of stdout.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const event = JSON.parse(trimmed);
+            parsedEvents += 1;
+            const candidate = extractAssistantTextFromEvent(event);
+            if (candidate !== undefined)
+                assistantText = candidate;
+        }
+        catch {
+            // tolerate non-json noise
+        }
+    }
+    return { assistantText: assistantText.trim(), parsedEvents };
+}
+export function extractTokenUsageFromPiJson(stdout) {
+    let totalTokens = 0;
+    for (const line of stdout.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const event = JSON.parse(trimmed);
+            const usage = extractUsageFromEvent(event);
+            if (usage !== null) {
+                totalTokens += usage;
+            }
+        }
+        catch {
+            // tolerate non-json noise
+        }
+    }
+    return totalTokens;
+}
+function extractUsageFromEvent(event) {
+    const candidates = [
+        event.usage,
+        isRecord(event.message) ? event.message.usage : undefined,
+        event.tokenUsage,
+    ];
+    for (const candidate of candidates) {
+        if (!isRecord(candidate))
+            continue;
+        const input = readNumericUsageField(candidate, [
+            "input_tokens",
+            "inputTokens",
+            "prompt_tokens",
+            "promptTokens",
+        ]);
+        const output = readNumericUsageField(candidate, [
+            "output_tokens",
+            "outputTokens",
+            "completion_tokens",
+            "completionTokens",
+        ]);
+        const total = readNumericUsageField(candidate, [
+            "total_tokens",
+            "totalTokens",
+        ]);
+        if (input !== null && output !== null)
+            return input + output;
+        if (total !== null)
+            return total;
+    }
+    return null;
+}
+function readNumericUsageField(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+            return Math.trunc(value);
+        }
+    }
+    return null;
+}
+function extractAssistantTextFromEvent(event) {
+    if ((event.type === "turn_end" || event.type === "message_end") &&
+        isRecord(event.message) &&
+        event.message.role === "assistant") {
+        return extractAssistantTextFromMessage(event.message);
+    }
+    if (event.type === "agent_end" && Array.isArray(event.messages)) {
+        for (let i = event.messages.length - 1; i >= 0; i -= 1) {
+            const message = event.messages[i];
+            if (isRecord(message) && message.role === "assistant") {
+                // The terminal assistant message is authoritative even when it only
+                // contains thinking/tool content. Do not walk farther back and reuse a
+                // stale progress sentence as the final node output.
+                return extractAssistantTextFromMessage(message);
+            }
+        }
+        return "";
+    }
+    return undefined;
+}
+function extractAssistantTextFromMessage(message) {
+    if (message.role !== "assistant" || !Array.isArray(message.content))
+        return "";
+    const textParts = message.content
+        .filter(isRecord)
+        .filter((item) => item.type === "text" && typeof item.text === "string")
+        .map((item) => item.text);
+    return textParts.join("\n").trim();
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export class BoundedTextPreview {
+    label;
+    headMax;
+    tailMax;
+    parts = [];
+    head = "";
+    tail = "";
+    bufferedChars = 0;
+    totalChars = 0;
+    truncated = false;
+    constructor(label, headMax = OUTPUT_PREVIEW_HEAD_CHARS, tailMax = OUTPUT_PREVIEW_TAIL_CHARS) {
+        this.label = label;
+        this.headMax = headMax;
+        this.tailMax = tailMax;
+    }
+    append(chunk) {
+        if (!chunk)
+            return;
+        this.totalChars += chunk.length;
+        if (!this.truncated) {
+            if (this.bufferedChars + chunk.length <= this.headMax + this.tailMax) {
+                this.parts.push(chunk);
+                this.bufferedChars += chunk.length;
+                return;
+            }
+            const combined = this.parts.join("") + chunk;
+            this.head = combined.slice(0, this.headMax);
+            this.tail = combined.slice(-this.tailMax);
+            this.parts = [];
+            this.bufferedChars = 0;
+            this.truncated = true;
+            return;
+        }
+        this.tail = (this.tail + chunk).slice(-this.tailMax);
+    }
+    text() {
+        if (!this.truncated)
+            return this.parts.join("");
+        const omitted = Math.max(0, this.totalChars - this.head.length - this.tail.length);
+        return [
+            this.head,
+            `[${this.label} truncated: omitted ${omitted} chars; kept first ${this.head.length} and last ${this.tail.length}]`,
+            this.tail,
+        ].join("\n");
+    }
+}
+export class PiJsonlStreamCollector {
+    lineBuffer = "";
+    discardUntilNewline = false;
+    assistantText = "";
+    parsedEvents = 0;
+    tokensUsed = 0;
+    outputTooLarge = false;
+    subagentTotalCalls = 0;
+    subagentFailedCalls = 0;
+    subagentModes = new Set();
+    subagentAgents = new Set();
+    append(chunk) {
+        if (!chunk)
+            return;
+        const lines = chunk.split(/\r?\n/);
+        for (let index = 0; index < lines.length; index += 1) {
+            const part = lines[index] ?? "";
+            const isLast = index === lines.length - 1;
+            if (this.discardUntilNewline) {
+                if (!isLast)
+                    this.discardUntilNewline = false;
+                continue;
+            }
+            if (this.lineBuffer.length + part.length > MAX_STREAM_JSONL_LINE_CHARS) {
+                this.outputTooLarge = true;
+                this.lineBuffer = "";
+                if (isLast)
+                    this.discardUntilNewline = true;
+                continue;
+            }
+            this.lineBuffer += part;
+            if (!isLast) {
+                this.consumeLine(this.lineBuffer);
+                this.lineBuffer = "";
+            }
+        }
+    }
+    finish() {
+        if (!this.discardUntilNewline && this.lineBuffer.trim()) {
+            this.consumeLine(this.lineBuffer);
+        }
+        this.lineBuffer = "";
+        return {
+            assistantText: this.assistantText.trim(),
+            outputTooLarge: this.outputTooLarge,
+            parsedEvents: this.parsedEvents,
+            subagentStats: this.formatSubagentStats(),
+            tokensUsed: this.tokensUsed,
+        };
+    }
+    consumeLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        try {
+            const event = JSON.parse(trimmed);
+            this.parsedEvents += 1;
+            this.consumeEvent(event);
+        }
+        catch {
+            // tolerate non-json noise
+        }
+    }
+    consumeEvent(event) {
+        const candidate = extractAssistantTextFromEvent(event);
+        if (candidate !== undefined) {
+            if (candidate.length > MAX_ASSISTANT_TEXT_CHARS) {
+                this.outputTooLarge = true;
+                this.assistantText = candidate.slice(0, MAX_ASSISTANT_TEXT_CHARS);
+            }
+            else {
+                this.assistantText = candidate;
+            }
+        }
+        const usage = extractUsageFromEvent(event);
+        if (usage !== null)
+            this.tokensUsed += usage;
+        if (event.type === "tool_execution_start" &&
+            event.toolName === "subagent") {
+            this.subagentTotalCalls += 1;
+            if (isRecord(event.input)) {
+                if (event.input.agent)
+                    this.subagentAgents.add(String(event.input.agent));
+                if (event.input.tasks)
+                    this.subagentModes.add("parallel");
+                if (event.input.chain)
+                    this.subagentModes.add("chain");
+                if (event.input.agent && !event.input.tasks && !event.input.chain) {
+                    this.subagentModes.add("single");
+                }
+            }
+        }
+        if (event.type === "tool_execution_end" && event.toolName === "subagent") {
+            if (event.isError === true)
+                this.subagentFailedCalls += 1;
+        }
+    }
+    formatSubagentStats() {
+        if (this.subagentTotalCalls === 0)
+            return "calls=0";
+        const parts = [`calls=${this.subagentTotalCalls}`];
+        if (this.subagentFailedCalls > 0)
+            parts.push(`${this.subagentFailedCalls} failed`);
+        if (this.subagentModes.size > 0)
+            parts.push(Array.from(this.subagentModes).sort().join("+"));
+        if (this.subagentAgents.size > 0) {
+            parts.push(`agents=[${Array.from(this.subagentAgents).sort().join(",")}]`);
+        }
+        return parts.join(" | ");
+    }
+}
+export function createPiJsonlStreamCollector() {
+    return new PiJsonlStreamCollector();
+}
+function withSubagentStats(result) {
+    return {
+        ...result,
+        subagentStats: result.subagentStats ?? extractSubagentStats(result.stdout),
+    };
+}
+function withCliBackend(result) {
+    return { ...result, backend: "cli" };
+}
+/** CLI-only orchestration: primary attempt + optional fallback model retry. */
+async function runCliOrchestration(options, meta) {
+    const promptTransport = createPiPromptTransport(options.prompt);
+    try {
+        return await runCliOrchestrationWithPromptFile(options, promptTransport.filePath, meta);
+    }
+    finally {
+        const cleanup = cleanupPiPromptTransport(promptTransport);
+        for (const warning of cleanup.warnings) {
+            process.stderr.write(`${warning}\n`);
+        }
+    }
+}
+async function runCliOrchestrationWithPromptFile(options, promptFilePath, meta) {
+    const primary = options.modelConfig ?? {};
+    const attemptedModels = [];
+    if (meta?.prependAttemptedModel) {
+        attemptedModels.push(meta.prependAttemptedModel);
+    }
+    const primaryResult = await executeSingleCliAttempt(options, primary, promptFilePath);
+    attemptedModels.push(primaryResult.modelDisplay);
+    let primaryIssues = [];
+    if (primaryResult.ok && options.validateOutput) {
+        primaryIssues = options.validateOutput(primaryResult.assistantText);
+    }
+    const primaryHardFail = !primaryResult.ok;
+    const primaryInvalidOutput = primaryResult.ok && primaryIssues.length > 0;
+    const shouldFallback = primary.fallback &&
+        ((primaryHardFail &&
+            primaryResult.failureCategory !== "termination-unconfirmed" &&
+            shouldRetryWithFallback(primaryResult.stderr, primaryResult.stdout)) ||
+            primaryInvalidOutput);
+    if (shouldFallback) {
+        const fallbackResult = await executeSingleCliAttempt(options, primary.fallback, promptFilePath);
+        attemptedModels.push(fallbackResult.modelDisplay);
+        const combinedStderr = [primaryResult.stderr, fallbackResult.stderr]
+            .filter(Boolean)
+            .join("\n--- fallback ---\n");
+        const combinedStdout = [primaryResult.stdout, fallbackResult.stdout]
+            .filter(Boolean)
+            .join("\n--- fallback ---\n");
+        const combinedStdoutTruncated = primaryResult.stdoutTruncated || fallbackResult.stdoutTruncated;
+        const combinedStderrTruncated = primaryResult.stderrTruncated || fallbackResult.stderrTruncated;
+        const combinedOutputTooLarge = primaryResult.outputTooLarge || fallbackResult.outputTooLarge;
+        let fallbackIssues = [];
+        if (fallbackResult.ok && options.validateOutput) {
+            fallbackIssues = options.validateOutput(fallbackResult.assistantText);
+        }
+        if (fallbackResult.ok && fallbackIssues.length === 0) {
+            return withSubagentStats(withCliBackend({
+                ...fallbackResult,
+                attemptedModels,
+                fallbackUsed: true,
+                sdkAttempted: meta?.sdkAttempted,
+                stderr: combinedStderr,
+                stdout: combinedStdout,
+                stdoutTruncated: combinedStdoutTruncated,
+                stderrTruncated: combinedStderrTruncated,
+                outputTooLarge: combinedOutputTooLarge,
+            }));
+        }
+        if (fallbackResult.ok && fallbackIssues.length > 0) {
+            return withSubagentStats(withCliBackend({
+                ...fallbackResult,
+                ok: false,
+                failureCategory: "invalid-output",
+                attemptedModels,
+                fallbackUsed: true,
+                sdkAttempted: meta?.sdkAttempted,
+                stderr: combinedStderr + `\n[invalid-output] ${fallbackIssues.join("; ")}`,
+                stdout: combinedStdout,
+                stdoutTruncated: combinedStdoutTruncated,
+                stderrTruncated: combinedStderrTruncated,
+                outputTooLarge: combinedOutputTooLarge,
+            }));
+        }
+        return withSubagentStats(withCliBackend({
+            ...fallbackResult,
+            attemptedModels,
+            fallbackUsed: true,
+            sdkAttempted: meta?.sdkAttempted,
+            stderr: combinedStderr,
+            stdout: combinedStdout,
+            stdoutTruncated: combinedStdoutTruncated,
+            stderrTruncated: combinedStderrTruncated,
+            outputTooLarge: combinedOutputTooLarge,
+        }));
+    }
+    if (primaryInvalidOutput) {
+        return withSubagentStats(withCliBackend({
+            ...primaryResult,
+            ok: false,
+            failureCategory: "invalid-output",
+            attemptedModels,
+            fallbackUsed: false,
+            sdkAttempted: meta?.sdkAttempted,
+            stderr: primaryResult.stderr +
+                `\n[invalid-output] ${primaryIssues.join("; ")}`,
+        }));
+    }
+    return withSubagentStats(withCliBackend({
+        ...primaryResult,
+        attemptedModels,
+        fallbackUsed: false,
+        sdkAttempted: meta?.sdkAttempted,
+    }));
+}
+function shouldFallbackSdkToCli(sdkResult, validationIssues, options) {
+    // Writers must never fall back to unrestricted CLI mutation tools.
+    if (options?.writerToolPolicy?.requireSdk)
+        return false;
+    if (sdkResult.ok && validationIssues.length > 0)
+        return true;
+    if (!sdkResult.ok &&
+        (sdkResult.failureCategory === "auth" ||
+            sdkResult.failureCategory === "timeout" ||
+            sdkResult.failureCategory === "termination-unconfirmed")) {
+        return false;
+    }
+    if (!sdkResult.ok &&
+        shouldRetryWithFallback(sdkResult.stderr, sdkResult.stdout))
+        return true;
+    return false;
+}
+function writerPolicyFailureResult(options, message, extras) {
+    return {
+        assistantText: "",
+        command: [],
+        durationMs: 0,
+        exitCode: 1,
+        failureCategory: "tool-policy",
+        modelDisplay: options.modelConfig?.model
+            ? `${options.modelConfig.provider ?? "default"}/${options.modelConfig.model}`
+            : "default",
+        ok: false,
+        parsedEvents: 0,
+        stderr: message,
+        stdout: "",
+        timedOut: false,
+        attemptedModels: [],
+        fallbackUsed: false,
+        tokensUsed: 0,
+        backend: extras?.backend,
+        sdkAttempted: extras?.sdkAttempted ?? false,
+    };
+}
+export async function executePiStep(options) {
+    const backendMode = resolvePiBackend();
+    const writerRequiresSdk = options.writerToolPolicy?.requireSdk === true;
+    if (backendMode === "cli-only") {
+        if (writerRequiresSdk) {
+            return writerPolicyFailureResult(options, "pi writer tool policy requires SDK backend; CODE_AGENT_PI_BACKEND=cli-only is fail-closed for writers", { sdkAttempted: false, backend: "cli" });
+        }
+        return runCliOrchestration(options, { sdkAttempted: false });
+    }
+    if (writerRequiresSdk) {
+        const customTools = options.writerToolPolicy?.customTools;
+        if (!Array.isArray(customTools) || customTools.length === 0) {
+            return writerPolicyFailureResult(options, "pi writer tool policy missing customTools; refusing uncontrolled writer session", { sdkAttempted: false });
+        }
+    }
+    const { checkPiSdkAvailability, executeSingleSdkAttempt, getActivePiSdkReuseScope, } = await import("./pi-sdk-executor.js");
+    const sdkCheck = await checkPiSdkAvailability(options.repoRoot);
+    if (!sdkCheck.ok) {
+        if (writerRequiresSdk) {
+            return writerPolicyFailureResult(options, `pi writer tool policy requires SDK; ${sdkCheck.detail}`, { sdkAttempted: false });
+        }
+        return runCliOrchestration(options, { sdkAttempted: false });
+    }
+    const reuseScope = isPiReuseRuntimeEnabled()
+        ? getActivePiSdkReuseScope()
+        : undefined;
+    const reuseRuntimeActive = Boolean(reuseScope);
+    const primary = options.modelConfig ?? {};
+    const sdkResult = await executeSingleSdkAttempt({
+        ...options,
+        modelConfig: primary,
+        reuseScope,
+    });
+    let validationIssues = [];
+    if (sdkResult.ok && options.validateOutput) {
+        validationIssues = options.validateOutput(sdkResult.assistantText);
+    }
+    if (sdkResult.ok && validationIssues.length === 0) {
+        return withSubagentStats({
+            ...sdkResult,
+            attemptedModels: [sdkResult.modelDisplay],
+            fallbackUsed: false,
+            sdkAttempted: true,
+            reuseRuntimeActive,
+        });
+    }
+    if (!shouldFallbackSdkToCli(sdkResult, validationIssues, options)) {
+        const failureCategory = validationIssues.length > 0
+            ? "invalid-output"
+            : sdkResult.failureCategory;
+        const stderr = validationIssues.length > 0
+            ? sdkResult.stderr + `\n[invalid-output] ${validationIssues.join("; ")}`
+            : sdkResult.stderr;
+        return withSubagentStats({
+            ...sdkResult,
+            ok: validationIssues.length > 0 ? false : sdkResult.ok,
+            failureCategory,
+            attemptedModels: [sdkResult.modelDisplay],
+            fallbackUsed: false,
+            sdkAttempted: true,
+            reuseRuntimeActive,
+            stderr,
+        });
+    }
+    const cliResult = await runCliOrchestration(options, {
+        sdkAttempted: true,
+        prependAttemptedModel: sdkResult.modelDisplay,
+    });
+    return { ...cliResult, reuseRuntimeActive };
+}
+async function executeSingleCliAttempt(options, modelConfig, promptFilePath) {
+    const modelDisplay = modelConfig.provider && modelConfig.model
+        ? `${modelConfig.provider}/${modelConfig.model}`
+        : (modelConfig.model ?? "default");
+    const timeoutMs = options.timeoutMs ?? modelConfig.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const stallTimeoutMs = options.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+    const abortGraceMs = options.abortGraceMs ?? DEFAULT_ABORT_GRACE_MS;
+    let timedOut = false;
+    let terminationUnconfirmed = false;
+    let supervisionStderr = "";
+    let timeoutHandle;
+    let stallHandle;
+    let sigkillHandle;
+    let exitConfirmationHandle;
+    // Build pi CLI arguments (same as before).
+    // We invoke pi via `node <pi-cli-path>` instead of relying on `#!/usr/bin/env node`
+    // to avoid provider resolution issues when spawned from tsx-managed processes.
+    const piArgs = [
+        "-p",
+        "--mode",
+        "json",
+        "--no-session",
+        "--no-context-files",
+        "--no-skills",
+        "--no-extensions",
+    ];
+    if (modelConfig.provider) {
+        piArgs.push("--provider", modelConfig.provider);
+    }
+    if (modelConfig.model) {
+        piArgs.push("--model", modelConfig.model);
+    }
+    if (modelConfig.thinking) {
+        piArgs.push("--thinking", modelConfig.thinking);
+    }
+    piArgs.push("--tools", options.toolNames.join(","));
+    piArgs.push("--append-system-prompt", promptFilePath);
+    piArgs.push(...options.attachedFiles.map((file) => `@${file}`));
+    piArgs.push(options.userMessage);
+    const recordedPiArgs = piArgs.map((arg, index) => index > 0 && piArgs[index - 1] === "--append-system-prompt"
+        ? "<system-prompt-file>"
+        : arg);
+    const startedAt = Date.now();
+    return await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [getPiCliPath(), ...piArgs], {
+            cwd: options.repoRoot,
+            ...processTreeSpawnOptions(),
+            env: {
+                ...process.env,
+                // Explicitly propagate API keys that pi needs to recognise providers.
+                // When tsx runs inside a non-login shell, some vars set in ~/.zshrc
+                // may not be in process.env; this ensures pi can resolve providers.
+                HOME: process.env.HOME,
+                DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? "",
+                AIMAX_API_KEY: process.env.AIMAX_API_KEY ?? "",
+                OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY ?? "",
+                NODE_PATH: process.env.NODE_PATH ?? "",
+                // Prevent upstream Node loader hooks (tsx/preload/import) from leaking into pi.
+                NODE_OPTIONS: "",
+                PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+            },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdoutPreview = new BoundedTextPreview("stdout");
+        const stderrPreview = new BoundedTextPreview("stderr", 16_000, 16_000);
+        const stdoutCollector = new PiJsonlStreamCollector();
+        let settled = false;
+        child.stdout.setEncoding("utf-8");
+        child.stderr.setEncoding("utf-8");
+        const clearSupervisionTimers = () => {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            if (stallHandle)
+                clearTimeout(stallHandle);
+            if (sigkillHandle)
+                clearTimeout(sigkillHandle);
+            if (exitConfirmationHandle)
+                clearTimeout(exitConfirmationHandle);
+        };
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearSupervisionTimers();
+            const durationMs = Date.now() - startedAt;
+            const stdout = stdoutPreview.text();
+            const capturedStderr = stderrPreview.text();
+            const stderr = [supervisionStderr, capturedStderr]
+                .filter(Boolean)
+                .join("\n");
+            const collected = stdoutCollector.finish();
+            const failureCategory = terminationUnconfirmed
+                ? "termination-unconfirmed"
+                : classifyPiFailure({
+                    assistantText: collected.assistantText,
+                    exitCode: code,
+                    stderr,
+                    stdout,
+                    timedOut,
+                    outputTooLarge: collected.outputTooLarge,
+                });
+            resolve({
+                assistantText: collected.assistantText,
+                command: ["pi", ...recordedPiArgs],
+                durationMs,
+                exitCode: code,
+                failureCategory,
+                modelDisplay,
+                ok: !timedOut &&
+                    code === 0 &&
+                    collected.assistantText.length > 0 &&
+                    !collected.outputTooLarge,
+                parsedEvents: collected.parsedEvents,
+                stderr,
+                stdout,
+                stdoutTruncated: stdoutPreview.truncated,
+                stderrTruncated: stderrPreview.truncated,
+                outputTooLarge: collected.outputTooLarge,
+                timedOut,
+                tokensUsed: collected.tokensUsed,
+                subagentStats: collected.subagentStats,
+            });
+        };
+        const hasConfirmedExitCode = () => child.exitCode !== null && child.exitCode !== undefined;
+        const beginControlledTermination = (reason) => {
+            if (timedOut || settled)
+                return;
+            timedOut = true;
+            supervisionStderr = reason;
+            terminateProcessTree(child, "SIGTERM");
+            sigkillHandle = setTimeout(() => {
+                if (settled)
+                    return;
+                if (hasConfirmedExitCode()) {
+                    finish(child.exitCode);
+                    return;
+                }
+                terminateProcessTree(child, "SIGKILL");
+                exitConfirmationHandle = setTimeout(() => {
+                    if (settled)
+                        return;
+                    if (hasConfirmedExitCode()) {
+                        finish(child.exitCode);
+                        return;
+                    }
+                    terminationUnconfirmed = true;
+                    supervisionStderr += `\npi CLI exit was not confirmed within ${abortGraceMs}ms after SIGKILL`;
+                    finish(null);
+                }, abortGraceMs);
+            }, abortGraceMs);
+        };
+        const armStallWatchdog = () => {
+            if (stallTimeoutMs <= 0 || timedOut || settled)
+                return;
+            if (stallHandle)
+                clearTimeout(stallHandle);
+            stallHandle = setTimeout(() => {
+                beginControlledTermination(`pi CLI step stalled after ${stallTimeoutMs}ms with no stdout/stderr activity`);
+            }, stallTimeoutMs);
+        };
+        const reportOutputActivity = () => {
+            armStallWatchdog();
+            try {
+                options.onActivity?.({ kind: "output", at: new Date().toISOString() });
+            }
+            catch {
+                // best-effort: never fail the pi step
+            }
+        };
+        child.stdout.on("data", (chunk) => {
+            stdoutPreview.append(chunk);
+            stdoutCollector.append(chunk);
+            if (chunk.length > 0)
+                reportOutputActivity();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderrPreview.append(chunk);
+            if (chunk.length > 0)
+                reportOutputActivity();
+        });
+        child.on("error", (err) => {
+            clearSupervisionTimers();
+            settled = true;
+            reject(err);
+        });
+        child.on("close", (code) => {
+            finish(code);
+        });
+        armStallWatchdog();
+        if (timeoutMs > 0) {
+            timeoutHandle = setTimeout(() => {
+                beginControlledTermination(`pi CLI step timed out after ${timeoutMs}ms`);
+            }, timeoutMs);
+        }
+    });
+}
+export function shouldRetryWithFallback(stderr, stdout) {
+    const category = classifyPiFailure({
+        assistantText: "",
+        exitCode: null,
+        stderr,
+        stdout,
+        timedOut: false,
+    });
+    return ["quota", "rate-limit", "unavailable", "network"].includes(category);
+}
+export function classifyPiFailure(input) {
+    if (input.timedOut)
+        return "timeout";
+    if (input.outputTooLarge)
+        return "output-too-large";
+    if (input.exitCode === 0 && input.assistantText.trim())
+        return "success";
+    const combined = `${input.stderr}\n${input.stdout}`.toLowerCase();
+    // Prefer explicit rate-limit / HTTP 429 before generic "limit" quota phrases.
+    // Chinese gateways often say "请求频率已达到限制" without English "rate limit".
+    if (/rate.?limit|too many requests|\b429\b|请求频率|频率.*限制|rpm|tpm/.test(combined))
+        return "rate-limit";
+    if (/quota|usage limit|reached.*limit|5\s*小时|5小时|insufficient_quota|billing/.test(combined))
+        return "quota";
+    if (/\bunauthorized\b|\bhttp\s*40[13]\b|invalid api key|authentication (?:failed|required|error)|auth(?:entication)? failed/.test(combined))
+        return "auth";
+    if (/unknown provider|unknown model|model.*unavailable|provider.*unavailable|\bunavailable\b|overloaded|capacity|temporarily unavailable/.test(combined))
+        return "unavailable";
+    if (/network|econnreset|etimedout|socket hang up|connection reset|connection error|request timed out|dns|fetch failed/.test(combined))
+        return "network";
+    if (input.exitCode === 0 && !input.assistantText.trim())
+        return "empty-output";
+    if (input.exitCode !== 0)
+        return "nonzero-exit";
+    return "unknown";
+}