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

package/dist/executors/pi-sdk-executor.js

@@ -0,0 +1,722 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { BoundedTextPreview, classifyPiFailure, createPiJsonlStreamCollector, DEFAULT_ABORT_GRACE_MS, DEFAULT_STALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, extractAssistantTextFromPiJson, } from "./pi-executor.js";
+import { serializeSessionEvent } from "./pi-event-serializer.js";
+import { PI_RECOMMENDED_COMPACTION, PI_RECOMMENDED_RETRY, } from "../shared/pi-retry-settings.js";
+let sdkSessionFactoryOverride;
+let sdkImportOverrideForTests;
+let sdkModuleOverrideForTests;
+let activeReuseScopeState;
+/**
+ * Begin a command/workflow-scoped SDK reuse scope.
+ * Callers must invoke endPiSdkReuseScope() at command end to prevent cross-command bleed.
+ */
+export function beginPiSdkReuseScope() {
+    if (activeReuseScopeState && !activeReuseScopeState.disposed) {
+        return;
+    }
+    activeReuseScopeState = { disposed: false };
+}
+/** Return the active reuse scope, if any. */
+export function getActivePiSdkReuseScope() {
+    if (!activeReuseScopeState || activeReuseScopeState.disposed) {
+        return undefined;
+    }
+    const state = activeReuseScopeState;
+    return {
+        isActive: () => !state.disposed,
+        getOrCreateResources: () => getOrCreateSharedResources(state),
+    };
+}
+/** Dispose the active reuse scope and clear cached shared resources. */
+export async function endPiSdkReuseScope() {
+    if (!activeReuseScopeState)
+        return;
+    activeReuseScopeState.disposed = true;
+    activeReuseScopeState.resources = undefined;
+    activeReuseScopeState = undefined;
+}
+/** Test hook: reset command-scoped reuse state between isolated tests. */
+export async function resetPiSdkReuseScopeForTests() {
+    await endPiSdkReuseScope();
+}
+/** Test hook: inject a mock session factory without loading the real SDK. */
+export function setPiSdkSessionFactoryForTests(factory) {
+    sdkSessionFactoryOverride = factory;
+}
+/** Test hook: simulate SDK import success/failure without relying on optionalDependency install state. */
+export function setPiSdkImportOverrideForTests(fn) {
+    sdkImportOverrideForTests = fn;
+}
+/** Test hook: inject a mock Pi SDK module to exercise resolveSdkSessionFactory without optionalDependency. */
+export function setPiSdkModuleOverrideForTests(fn) {
+    sdkModuleOverrideForTests = fn;
+}
+/** Check whether the Pi SDK optional dependency satisfies the 0.80.10 runtime contract. */
+export async function checkPiSdkAvailability(_repoRoot) {
+    if (sdkSessionFactoryOverride) {
+        return { ok: true, detail: "pi SDK session factory override active" };
+    }
+    try {
+        const imported = sdkImportOverrideForTests
+            ? await sdkImportOverrideForTests()
+            : await loadPiSdkModule();
+        const sdk = imported;
+        const ModelRuntime = sdk.ModelRuntime;
+        if (typeof sdk.createAgentSession !== "function" ||
+            typeof sdk.getAgentDir !== "function" ||
+            typeof ModelRuntime?.create !== "function") {
+            return {
+                ok: false,
+                detail: "pi SDK incompatible: requires createAgentSession, getAgentDir, and ModelRuntime.create (0.80.10 contract)",
+            };
+        }
+        return { ok: true, detail: "pi SDK 0.80.10 contract available" };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, detail: `pi SDK not available: ${message}` };
+    }
+}
+/**
+ * Best-effort Pi SDK model catalog (credentialed providers first).
+ * Empty on SDK/auth/runtime failure — callers must fall back to harness tiers.
+ */
+export async function listPiSdkAvailableModels() {
+    try {
+        const imported = sdkImportOverrideForTests
+            ? await sdkImportOverrideForTests()
+            : await loadPiSdkModule();
+        const sdk = imported;
+        const getAgentDir = sdk.getAgentDir;
+        const ModelRuntime = sdk.ModelRuntime;
+        if (typeof getAgentDir !== "function" || typeof ModelRuntime?.create !== "function") {
+            return [];
+        }
+        const agentDir = getAgentDir();
+        const runtime = await ModelRuntime.create({
+            authPath: path.join(agentDir, "auth.json"),
+            modelsPath: path.join(agentDir, "models.json"),
+        });
+        const snapshot = runtime.snapshot ?? {};
+        const configured = snapshot.configuredProviders;
+        const isConfigured = (provider) => configured instanceof Set ? configured.has(provider) : false;
+        return (snapshot.available ?? []).map((entry) => ({
+            provider: entry.provider,
+            id: entry.id,
+            name: entry.name,
+            hasCredentials: isConfigured(entry.provider),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/** Fail-closed probe for the SDK-only structured custom-tool surface. */
+export async function checkPiSdkCustomToolCapability(_repoRoot) {
+    if (sdkSessionFactoryOverride) {
+        return {
+            ok: true,
+            detail: "pi SDK custom-tool session factory override active",
+        };
+    }
+    try {
+        const imported = sdkImportOverrideForTests
+            ? await sdkImportOverrideForTests()
+            : await loadPiSdkModule();
+        const sdk = imported;
+        const { Type } = await import("typebox");
+        const ModelRuntime = sdk.ModelRuntime;
+        if (typeof sdk.createAgentSession !== "function" ||
+            typeof sdk.getAgentDir !== "function" ||
+            typeof ModelRuntime?.create !== "function" ||
+            typeof sdk.defineTool !== "function" ||
+            typeof Type?.Object !== "function") {
+            return {
+                ok: false,
+                detail: "pi SDK custom-tool capability incompatible: requires createAgentSession, getAgentDir, ModelRuntime.create, defineTool, and typebox Type.Object",
+            };
+        }
+        return {
+            ok: true,
+            detail: "pi SDK structured custom-tool capability available",
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            detail: `pi SDK custom-tool capability unavailable: ${message}`,
+        };
+    }
+}
+async function resolveModel(modelRuntime, provider, modelId) {
+    const fromRuntime = modelRuntime.getModel(provider, modelId);
+    if (fromRuntime)
+        return fromRuntime;
+    try {
+        const piAi = (await import("@earendil-works/pi-ai/compat"));
+        return piAi.getModel?.(provider, modelId);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function loadPiSdkModule() {
+    if (sdkModuleOverrideForTests) {
+        return sdkModuleOverrideForTests();
+    }
+    return (await import("@earendil-works/pi-coding-agent"));
+}
+async function getOrCreateSharedResources(state) {
+    if (state.resources)
+        return state.resources;
+    const sdk = await loadPiSdkModule();
+    const getAgentDir = sdk.getAgentDir;
+    const ModelRuntime = sdk.ModelRuntime;
+    if (typeof ModelRuntime?.create !== "function") {
+        throw new Error("incompatible pi SDK: ModelRuntime.create is unavailable");
+    }
+    const agentDir = getAgentDir();
+    const modelRuntime = await ModelRuntime.create({
+        authPath: path.join(agentDir, "auth.json"),
+        modelsPath: path.join(agentDir, "models.json"),
+    });
+    state.resources = { agentDir, modelRuntime };
+    return state.resources;
+}
+async function createSdkSession(sdk, input, shared) {
+    const createAgentSession = sdk.createAgentSession;
+    const SessionManager = sdk.SessionManager;
+    const DefaultResourceLoader = sdk.DefaultResourceLoader;
+    const SettingsManager = sdk.SettingsManager;
+    const getAgentDir = sdk.getAgentDir;
+    const ModelRuntime = sdk.ModelRuntime;
+    const agentDir = shared?.agentDir ?? getAgentDir();
+    if (!shared && typeof ModelRuntime?.create !== "function") {
+        throw new Error("incompatible pi SDK: ModelRuntime.create is unavailable");
+    }
+    const modelRuntime = shared?.modelRuntime ??
+        (await ModelRuntime.create({
+            authPath: path.join(agentDir, "auth.json"),
+            modelsPath: path.join(agentDir, "models.json"),
+        }));
+    const model = input.provider && input.model
+        ? await resolveModel(modelRuntime, input.provider, input.model)
+        : undefined;
+    // Inject rate-limit-tolerant auto-retry settings for the session lifecycle.
+    // Prefer SettingsManager.inMemory so harness runs do not depend on ~/.pi or
+    // project .pi/settings.json being present/trusted.
+    const settingsManager = typeof SettingsManager?.inMemory === "function"
+        ? SettingsManager.inMemory({
+            retry: {
+                ...PI_RECOMMENDED_RETRY,
+                provider: { ...PI_RECOMMENDED_RETRY.provider },
+            },
+            compaction: { ...PI_RECOMMENDED_COMPACTION },
+        }, { projectTrusted: true })
+        : undefined;
+    const loader = new DefaultResourceLoader({
+        cwd: input.cwd,
+        agentDir,
+        noContextFiles: true,
+        noSkills: true,
+        noExtensions: true,
+        ...(settingsManager ? { settingsManager } : {}),
+        appendSystemPromptOverride: (base) => [
+            ...base,
+            input.appendSystemPrompt,
+        ],
+    });
+    await loader.reload();
+    if (input.requireWriterCustomTools) {
+        if (!Array.isArray(input.customTools) || input.customTools.length === 0) {
+            throw new Error("pi writer tool policy missing customTools; refusing to create uncontrolled writer session");
+        }
+    }
+    const created = await createAgentSession({
+        cwd: input.cwd,
+        sessionManager: SessionManager.inMemory(input.cwd),
+        resourceLoader: loader,
+        tools: input.toolNames,
+        modelRuntime,
+        ...(settingsManager ? { settingsManager } : {}),
+        ...(model ? { model } : {}),
+        ...(input.thinking ? { thinkingLevel: input.thinking } : {}),
+        ...(Array.isArray(input.customTools) && input.customTools.length > 0
+            ? { customTools: input.customTools }
+            : {}),
+    });
+    const customToolNames = (input.customTools ?? [])
+        .map((tool) => isRecord(tool) && typeof tool.name === "string" ? tool.name : undefined)
+        .filter((name) => Boolean(name));
+    if (customToolNames.length > 0) {
+        const activeTools = created.session.agent?.state?.tools;
+        if (!Array.isArray(activeTools)) {
+            throw new Error("pi SDK session does not expose agent.state.tools; refusing unverifiable custom-tool activation");
+        }
+        const activeNames = new Set(activeTools
+            .map((tool) => typeof tool?.name === "string" ? tool.name : undefined)
+            .filter((name) => Boolean(name)));
+        for (const customToolName of customToolNames) {
+            const expectedActive = input.toolNames.includes(customToolName);
+            if (activeNames.has(customToolName) !== expectedActive) {
+                throw new Error(`pi SDK custom-tool activation mismatch for ${customToolName}: expectedActive=${expectedActive}`);
+            }
+        }
+    }
+    return created.session;
+}
+/**
+ * Throttle high-noise Pi SDK events from session-events.jsonl.
+ * Always keeps tool lifecycle, turn/agent end, assistant messages, and errors.
+ * Skips thinking_delta and message_update token floods.
+ */
+export function shouldPersistSessionEvent(event) {
+    const type = typeof event.type === "string" ? event.type : "";
+    if (type === "tool_start" ||
+        type === "tool_end" ||
+        type === "tool_execution_start" ||
+        type === "tool_execution_end" ||
+        type === "turn_end" ||
+        type === "agent_end" ||
+        type === "assistant_message" ||
+        type === "message_end") {
+        return true;
+    }
+    if (type === "thinking_delta" || type === "message_update") {
+        return false;
+    }
+    if (type.includes("error") || event.isError === true) {
+        return true;
+    }
+    return true;
+}
+function classifySdkActivityKind(event) {
+    if (!event || typeof event !== "object")
+        return "provider";
+    const type = typeof event.type === "string"
+        ? String(event.type)
+        : "";
+    if (type === "tool_start" ||
+        type === "tool_end" ||
+        type === "tool_execution_start" ||
+        type === "tool_execution_end") {
+        return "tool";
+    }
+    if (type === "thinking_delta" || type === "message_update") {
+        return null;
+    }
+    return "provider";
+}
+/** Write/edit-style tool names emitted by DAG writer customTools.
+ * Used to attribute write-tool activity for writer-thinking-exhausted diagnosis.
+ * Kept as a module-local constant so tests stay deterministic regardless of the
+ * SDK's tool registration quirks. */
+const SDK_WRITE_TOOL_NAMES = new Set(["edit", "write", "str_replace_editor"]);
+function createSessionEventAppender(filePath, onSessionEvent) {
+    let chain = Promise.resolve();
+    let dirEnsured = false;
+    return {
+        append(line, event) {
+            chain = chain.then(async () => {
+                try {
+                    if (!dirEnsured) {
+                        await mkdir(path.dirname(filePath), { recursive: true });
+                        dirEnsured = true;
+                    }
+                    await appendFile(filePath, `${line}\n`, "utf-8");
+                    // Only after successful persistence: surface the persisted session event.
+                    // Transport activity is reported synchronously by the subscription so
+                    // filtered deltas and slow disk writes cannot trip the stall watchdog.
+                    onSessionEvent?.(line, event);
+                }
+                catch {
+                    // best-effort: never fail the pi step
+                }
+            });
+        },
+        drain() {
+            return chain;
+        },
+    };
+}
+async function resolveSdkSessionFactory(reuseScope) {
+    if (sdkSessionFactoryOverride)
+        return sdkSessionFactoryOverride;
+    const sdk = await loadPiSdkModule();
+    return async (input) => {
+        const shared = reuseScope
+            ? await reuseScope.getOrCreateResources()
+            : undefined;
+        return createSdkSession(sdk, input, shared);
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function readUsageNumber(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 undefined;
+}
+function extractSdkUsageSample(event) {
+    const message = isRecord(event.message) ? event.message : undefined;
+    const usageCandidates = [event.usage, message?.usage, event.tokenUsage];
+    let tokens;
+    for (const candidate of usageCandidates) {
+        if (!isRecord(candidate))
+            continue;
+        const input = readUsageNumber(candidate, [
+            "input_tokens",
+            "inputTokens",
+            "prompt_tokens",
+            "promptTokens",
+        ]);
+        const output = readUsageNumber(candidate, [
+            "output_tokens",
+            "outputTokens",
+            "completion_tokens",
+            "completionTokens",
+        ]);
+        const total = readUsageNumber(candidate, ["total_tokens", "totalTokens"]);
+        if (input !== undefined && output !== undefined) {
+            tokens = input + output;
+            break;
+        }
+        if (total !== undefined) {
+            tokens = total;
+            break;
+        }
+    }
+    if (tokens === undefined)
+        return undefined;
+    const responseKeyCandidates = [
+        event.responseId,
+        event.messageId,
+        message?.responseId,
+        message?.id,
+    ];
+    const responseKey = responseKeyCandidates.find((value) => typeof value === "string" && value.length > 0);
+    return responseKey ? { responseKey, tokens } : { tokens };
+}
+/** Extract a non-empty stop reason from a terminal SDK event.
+ * Probes multiple field shapes across SDK versions so a missing field fails
+ * open (undefined) rather than misclassifying an attempt. */
+function readStopReason(event) {
+    const message = isRecord(event.message) ? event.message : undefined;
+    const candidates = [
+        message?.stop_reason,
+        message?.stopReason,
+        event.stopReason,
+        event.stop_reason,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" &&
+            candidate.trim().length > 0) {
+            return candidate.trim();
+        }
+    }
+    return undefined;
+}
+function aggregateSdkTokenUsage(samples) {
+    const identified = new Map();
+    let anonymousMaximum = 0;
+    for (const sample of samples) {
+        if (sample.responseKey) {
+            identified.set(sample.responseKey, Math.max(identified.get(sample.responseKey) ?? 0, sample.tokens));
+        }
+        else {
+            // SDK lifecycle events may repeat cumulative usage without a response id.
+            // Treat anonymous samples as snapshots for this attempt rather than increments.
+            anonymousMaximum = Math.max(anonymousMaximum, sample.tokens);
+        }
+    }
+    return (anonymousMaximum +
+        Array.from(identified.values()).reduce((sum, tokens) => sum + tokens, 0));
+}
+/**
+ * Execute a single Pi step via the SDK.
+ * When reuseScope is active, only shared auth/model resources are reused; each attempt still
+ * creates and disposes its own session and resource loader. Session reuse across steps is
+ * deferred until a proven reset/isolation strategy exists.
+ */
+export async function executeSingleSdkAttempt(options) {
+    const modelConfig = options.modelConfig;
+    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;
+    const piSdkArgs = [
+        "--provider",
+        modelConfig.provider ?? "(default)",
+        "--model",
+        modelConfig.model ?? "(default)",
+        ...(modelConfig.thinking ? ["--thinking", modelConfig.thinking] : []),
+        "--tools",
+        options.toolNames.join(","),
+        "--append-system-prompt",
+        "<in-memory-system-prompt>",
+        ...options.attachedFiles.map((file) => `@${file}`),
+        options.userMessage,
+    ];
+    const startedAt = Date.now();
+    let timedOut = false;
+    let terminationConfirmed = true;
+    let stderr = "";
+    const stdoutPreview = new BoundedTextPreview("stdout");
+    const stdoutCollector = createPiJsonlStreamCollector();
+    const usageSamples = [];
+    // Writer-thinking-exhausted diagnosis evidence (AC-002). Collected in the
+    // subscribe callback regardless of shouldPersistSessionEvent filtering, so a
+    // length-stopped thinking-only attempt with no persisted write tool calls is
+    // still distinguishable from generic empty output.
+    let stopReason;
+    let thinkingObserved = false;
+    let writeToolCallCount = 0;
+    const observeWriterThinkingExhaustionEvidence = (event) => {
+        const type = typeof event.type === "string" ? event.type : "";
+        if (type === "thinking_delta") {
+            thinkingObserved = true;
+        }
+        if (type === "tool_execution_start" &&
+            typeof event.toolName === "string" &&
+            SDK_WRITE_TOOL_NAMES.has(event.toolName)) {
+            writeToolCallCount += 1;
+        }
+        if (type === "turn_end" ||
+            type === "message_end" ||
+            type === "agent_end" ||
+            type === "agent_settled") {
+            const candidate = readStopReason(event);
+            if (candidate)
+                stopReason = candidate;
+        }
+    };
+    let session;
+    let unsubscribe;
+    let timeoutHandle;
+    let stallHandle;
+    let disposeAttempted = false;
+    const sessionEventAppender = options.sessionEventsPath
+        ? createSessionEventAppender(options.sessionEventsPath, options.onSessionEvent)
+        : undefined;
+    const appendStderr = (message) => {
+        stderr = stderr ? `${stderr}\n${message}` : message;
+    };
+    const runSessionActionWithGrace = async (label, action) => {
+        let graceHandle;
+        const outcome = await Promise.race([
+            Promise.resolve()
+                .then(action)
+                .then(() => ({ ok: true }))
+                .catch((error) => ({ ok: false, error })),
+            new Promise((resolve) => {
+                graceHandle = setTimeout(() => resolve({ ok: false, timedOut: true }), abortGraceMs);
+            }),
+        ]);
+        if (graceHandle)
+            clearTimeout(graceHandle);
+        if (outcome.ok)
+            return true;
+        if ("timedOut" in outcome) {
+            appendStderr(`pi SDK ${label} was not confirmed within ${abortGraceMs}ms`);
+        }
+        else {
+            const message = outcome.error instanceof Error
+                ? outcome.error.message
+                : String(outcome.error);
+            appendStderr(`pi SDK ${label} failed: ${message}`);
+        }
+        return false;
+    };
+    try {
+        const createSession = await resolveSdkSessionFactory(options.reuseScope);
+        const writerCustomTools = options.writerToolPolicy?.customTools;
+        const requireWriterCustomTools = options.writerToolPolicy?.requireSdk === true;
+        if (requireWriterCustomTools &&
+            (!Array.isArray(writerCustomTools) || writerCustomTools.length === 0)) {
+            throw new Error("pi writer tool policy missing customTools; refusing to create uncontrolled writer session");
+        }
+        session = await createSession({
+            cwd: options.repoRoot,
+            toolNames: options.toolNames,
+            appendSystemPrompt: options.prompt,
+            provider: modelConfig.provider,
+            model: modelConfig.model,
+            thinking: modelConfig.thinking,
+            ...(Array.isArray(writerCustomTools) && writerCustomTools.length > 0
+                ? { customTools: writerCustomTools }
+                : {}),
+            ...(requireWriterCustomTools ? { requireWriterCustomTools: true } : {}),
+        });
+        let resolveStall;
+        let resolveSettlement;
+        let settled = false;
+        const settlementPromise = new Promise((resolve) => {
+            resolveSettlement = resolve;
+        });
+        const stallPromise = stallTimeoutMs > 0
+            ? new Promise((resolve) => {
+                resolveStall = resolve;
+            })
+            : null;
+        const armStallWatchdog = () => {
+            if (!stallPromise || !resolveStall)
+                return;
+            if (stallHandle)
+                clearTimeout(stallHandle);
+            stallHandle = setTimeout(() => resolveStall?.("stall"), stallTimeoutMs);
+        };
+        unsubscribe = session.subscribe((event) => {
+            if (event.type === "agent_settled" && !settled) {
+                settled = true;
+                resolveSettlement?.("settled");
+            }
+            // Every real SDK event proves transport activity, including noisy deltas
+            // intentionally excluded from persisted JSONL and meaningful DAG progress.
+            armStallWatchdog();
+            const activityKind = classifySdkActivityKind(event);
+            if (activityKind) {
+                try {
+                    options.onActivity?.({
+                        kind: activityKind,
+                        at: new Date().toISOString(),
+                    });
+                }
+                catch {
+                    // best-effort: activity must never change Pi result
+                }
+            }
+            const usageSample = extractSdkUsageSample(event);
+            if (usageSample)
+                usageSamples.push(usageSample);
+            // Capture writer-thinking-exhausted evidence BEFORE the
+            // shouldPersistSessionEvent filter: thinking_delta is intentionally
+            // excluded from persisted JSONL, but must still count toward the
+            // in-memory thinkingObserved/writeToolCallCount/stopReason evidence.
+            observeWriterThinkingExhaustionEvidence(event);
+            if (!shouldPersistSessionEvent(event))
+                return;
+            const line = serializeSessionEvent(event);
+            stdoutPreview.append(`${line}\n`);
+            stdoutCollector.append(`${line}\n`);
+            sessionEventAppender?.append(line, event);
+        });
+        const filePrefix = options.attachedFiles
+            .map((file) => `@${file}`)
+            .join(" ");
+        const promptMessage = filePrefix
+            ? `${filePrefix}\n${options.userMessage}`
+            : options.userMessage;
+        const promptPromise = session.prompt(promptMessage);
+        // A settlement event is permitted to win the race while prompt() remains
+        // pending. Observe a later rejection so it never becomes unhandled.
+        void promptPromise.catch(() => { });
+        armStallWatchdog();
+        const timeoutPromise = timeoutMs > 0
+            ? new Promise((resolve) => {
+                timeoutHandle = setTimeout(() => {
+                    resolve("absolute-timeout");
+                }, timeoutMs);
+            })
+            : null;
+        const raced = await Promise.race([
+            promptPromise.then(() => "done"),
+            settlementPromise,
+            ...(timeoutPromise ? [timeoutPromise] : []),
+            ...(stallPromise ? [stallPromise] : []),
+        ]);
+        if (raced !== "done" && raced !== "settled") {
+            timedOut = true;
+            appendStderr(raced === "stall"
+                ? `pi SDK step stalled after ${stallTimeoutMs}ms with no provider activity`
+                : `pi SDK step timed out after ${timeoutMs}ms`);
+            const abortConfirmed = await runSessionActionWithGrace("abort", () => session.abort());
+            disposeAttempted = true;
+            const disposeConfirmed = await runSessionActionWithGrace("dispose", () => session.dispose());
+            terminationConfirmed = abortConfirmed && disposeConfirmed;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        appendStderr(message);
+    }
+    finally {
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+        if (stallHandle)
+            clearTimeout(stallHandle);
+        unsubscribe?.();
+        if (session && !disposeAttempted) {
+            disposeAttempted = true;
+            const disposeConfirmed = await runSessionActionWithGrace("dispose", () => session.dispose());
+            terminationConfirmed = terminationConfirmed && disposeConfirmed;
+        }
+        if (sessionEventAppender) {
+            try {
+                await sessionEventAppender.drain();
+            }
+            catch {
+                // best-effort: never fail the pi step
+            }
+        }
+    }
+    const stdout = stdoutPreview.text();
+    const durationMs = Date.now() - startedAt;
+    const collected = stdoutCollector.finish();
+    const fallbackParsed = collected.parsedEvents > 0
+        ? undefined
+        : extractAssistantTextFromPiJson(stdout);
+    const assistantText = collected.parsedEvents > 0
+        ? collected.assistantText
+        : (fallbackParsed?.assistantText ?? "");
+    const parsedEvents = collected.parsedEvents > 0
+        ? collected.parsedEvents
+        : (fallbackParsed?.parsedEvents ?? 0);
+    const tokensUsed = aggregateSdkTokenUsage(usageSamples);
+    const failureCategory = terminationConfirmed
+        ? classifyPiFailure({
+            assistantText,
+            exitCode: timedOut ? 1 : stderr ? 1 : 0,
+            outputTooLarge: collected.outputTooLarge,
+            stderr,
+            stdout,
+            timedOut,
+        })
+        : "termination-unconfirmed";
+    return {
+        assistantText,
+        backend: "sdk",
+        command: ["pi-sdk", ...piSdkArgs],
+        durationMs,
+        exitCode: timedOut || stderr ? 1 : 0,
+        failureCategory,
+        modelDisplay,
+        ok: terminationConfirmed &&
+            !timedOut &&
+            !stderr &&
+            assistantText.length > 0 &&
+            !collected.outputTooLarge,
+        parsedEvents,
+        stderr,
+        stdout,
+        stdoutTruncated: stdoutPreview.truncated,
+        outputTooLarge: collected.outputTooLarge,
+        timedOut,
+        tokensUsed,
+        subagentStats: collected.subagentStats,
+        // Writer-thinking-exhausted diagnosis evidence (AC-002). Carried through
+        // the object spread in executePiStep so executeDagPiNode can read them
+        // via a widened type without modifying PiStepExecutionResult's shape.
+        stopReason,
+        thinkingObserved,
+        writeToolCallCount,
+    };
+}