stageflow 0.1.0

package/dist/agent/piAdapter.js

@@ -0,0 +1,967 @@
+/**
+ * Pi implementation of AgentPort.
+ *
+ * One stage = one `createAgentSession` (single-shot SDK path, not
+ * AgentSessionRuntime / interactive / RPC). The session is sealed from host
+ * and global Pi resources so the stage YAML system prompt is the only
+ * instruction source. Operator credentials come from
+ * `ModelRuntime.create({ authPath })` using the factory-resolved binding
+ * (`pi_home` or `.stageflow/agent/auth.json`).
+ *
+ * Extension-backed providers (e.g. Cursor via pi-cursor-sdk) plug in through
+ * `StageProviderSupport` — see `providerSupport.ts` / `cursorProvider.ts`.
+ * Built-in providers (anthropic, openai, …) need no support module: sealed
+ * session + resolveCliModel after bindExtensions is enough.
+ *
+ * Lifecycle: create persisted session under the stage workspace →
+ * bindExtensions → setModel → `prompt()` → bounded abort + `dispose()` in
+ * finally (session file is kept). Stage completion is signaled only by
+ * `emit_stage_envelope` returning `terminate: true` (do not abort from
+ * inside the tool — that deadlocks bridges that wait on the tool result).
+ *
+ * HITL: `openStage` wires `AskOperatorWaitChannel` into a real StageHandle
+ * (tool Promise → wait yield → deliverAnswer). Same-process prefers the live
+ * channel; after process loss, open arms wait then `deliverAnswer` injects
+ * via `injectOpaqueAnswerIntoSession` and continues. Missing/corrupt session
+ * fails closed with `StageSessionReconstructError` (KTD7). Epic proving
+ * vehicle: pipeline `plan-review-proving` (Pi live wait + console answers).
+ *
+ * `ask_operator` is always registered on sealed stage sessions (allowlist +
+ * customTools).
+ */
+import { existsSync } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createAgentSession, DefaultResourceLoader, defineTool, ModelRuntime, resolveCliModel, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { isAdvancingEnvelope } from "../envelope/check.js";
+import { formatPriorEnvelope } from "../prompt/priorEnvelope.js";
+import { attemptContext, noAttemptContext, } from "../runtime/stageAttemptContext.js";
+import { createEmitStageEnvelopeTool, } from "../tools/emitStageEnvelope.js";
+import { createAskOperatorTool, } from "../tools/askOperator.js";
+import { createWriteStageArtifactTool } from "../tools/writeStageArtifact.js";
+import "./cursorProvider.js";
+import { findProviderSupport } from "./providerSupport.js";
+import { mapSessionEventToActivity } from "./activity.js";
+import { createStageActivityObserver } from "./activityObserver.js";
+import { DEFAULT_STAGE_TIMEOUT_MS, runStageViaOpen } from "./port.js";
+/**
+ * Stage tool allowlist for sealed Pi sessions.
+ * Always includes `ask_operator` (R7); `write_stage_artifact` when registered
+ * (always, for bound and unbound — bound/unbound only gates cwd / env bind).
+ */
+export function resolveStageToolNames(emitToolName, artifactToolName, askOperatorToolName = "ask_operator") {
+    const tools = [
+        "read",
+        "bash",
+        "write",
+        "edit",
+        emitToolName,
+        askOperatorToolName,
+    ];
+    if (artifactToolName) {
+        tools.push(artifactToolName);
+    }
+    return tools;
+}
+/**
+ * In-process wait channel for `ask_operator` → StageHandle yield/deliver.
+ * HITL `openStage` connects this via `setWaitHandler` + handle `deliverAnswer`.
+ */
+export class AskOperatorWaitChannel {
+    pending;
+    onWait;
+    setWaitHandler(handler) {
+        this.onWait = handler;
+    }
+    requestWait(prompt) {
+        const handler = this.onWait;
+        if (!handler) {
+            return Promise.reject(new Error("ask_operator: Pi live wait channel not connected (openStage must setWaitHandler; use FakeAgent for scripted HITL)"));
+        }
+        if (this.pending) {
+            return Promise.reject(new Error("ask_operator: wait already pending for this stage session"));
+        }
+        return new Promise((resolve, reject) => {
+            this.pending = { prompt, resolve, reject };
+            try {
+                handler(prompt);
+            }
+            catch (err) {
+                this.pending = undefined;
+                reject(err);
+            }
+        });
+    }
+    deliverAnswer(answer) {
+        if (!this.pending)
+            return false;
+        const { resolve } = this.pending;
+        this.pending = undefined;
+        resolve(answer);
+        return true;
+    }
+    rejectPending(reason) {
+        if (!this.pending)
+            return;
+        const { reject } = this.pending;
+        this.pending = undefined;
+        reject(new Error(reason));
+    }
+    get hasPending() {
+        return this.pending !== undefined;
+    }
+}
+/**
+ * Bridge used when no StageHandle wait loop is connected.
+ * Calling ask_operator fails closed instead of hanging the session.
+ */
+export function createUnconnectedAskWaitBridge() {
+    return {
+        requestWait: async () => {
+            throw new Error("ask_operator: Pi live wait channel not connected (openStage must setWaitHandler; use FakeAgent for scripted HITL)");
+        },
+    };
+}
+/**
+ * Connect `AskOperatorWaitChannel` (tool Promise) to a StageHandle wait/deliver
+ * loop. Pipeline park stays on StageHitlController via this handle only —
+ * runtime never imports the channel.
+ */
+export function createConnectedAskWaitStageHandle(options) {
+    const { askWaitChannel: channel } = options;
+    let closed = false;
+    let runLaunched = false;
+    let resumeArmed = options.resume !== undefined;
+    let resumeResolve;
+    let resumePromise;
+    let resumeDeliverError;
+    let resumeDeliverStarted = false;
+    if (resumeArmed) {
+        resumePromise = new Promise((resolve) => {
+            resumeResolve = resolve;
+        });
+    }
+    const eventQueue = [];
+    const eventWaiters = [];
+    const enqueue = (event) => {
+        const waiter = eventWaiters.shift();
+        if (waiter) {
+            waiter(event);
+            return;
+        }
+        eventQueue.push(event);
+    };
+    const takeEvent = () => {
+        if (eventQueue.length > 0) {
+            return Promise.resolve(eventQueue.shift());
+        }
+        return new Promise((resolve) => {
+            eventWaiters.push(resolve);
+        });
+    };
+    const settleFromRun = (run) => {
+        void run()
+            .then((result) => {
+            if (!closed) {
+                enqueue({ status: "completed", result });
+            }
+        })
+            .catch((err) => {
+            if (!closed) {
+                enqueue({
+                    status: "completed",
+                    result: {
+                        ok: false,
+                        reason: err instanceof Error ? err.message : String(err),
+                    },
+                });
+            }
+        });
+    };
+    channel.setWaitHandler((prompt) => {
+        options.onBeforeWaitYield?.(prompt);
+        enqueue({ status: "waiting_for_input", request: prompt });
+    });
+    return {
+        stageId: options.stageId,
+        async next() {
+            if (closed) {
+                return {
+                    status: "completed",
+                    result: { ok: false, reason: "stage handle closed" },
+                };
+            }
+            if (resumeArmed) {
+                await resumePromise;
+                resumeArmed = false;
+                if (closed) {
+                    return {
+                        status: "completed",
+                        result: { ok: false, reason: "stage handle closed" },
+                    };
+                }
+                if (resumeDeliverError !== undefined) {
+                    return {
+                        status: "completed",
+                        result: {
+                            ok: false,
+                            reason: resumeDeliverError instanceof Error
+                                ? resumeDeliverError.message
+                                : String(resumeDeliverError),
+                        },
+                    };
+                }
+                settleFromRun(options.resume.continueRun);
+                return takeEvent();
+            }
+            if (!runLaunched) {
+                runLaunched = true;
+                settleFromRun(options.run);
+            }
+            return takeEvent();
+        },
+        deliverAnswer(answer) {
+            if (resumeArmed && options.resume && !resumeDeliverStarted) {
+                resumeDeliverStarted = true;
+                try {
+                    options.resume.onDeliver(answer);
+                }
+                catch (err) {
+                    resumeDeliverError = err;
+                }
+                const resolve = resumeResolve;
+                resumeResolve = undefined;
+                resolve?.(answer);
+                return;
+            }
+            channel.deliverAnswer(answer);
+        },
+        async close(closeOptions) {
+            closed = true;
+            if (closeOptions?.park) {
+                await options.onClose?.({ park: true });
+                return;
+            }
+            channel.rejectPending("stage handle closed");
+            if (resumeResolve) {
+                const resolve = resumeResolve;
+                resumeResolve = undefined;
+                resumeArmed = false;
+                resolve(undefined);
+            }
+            while (eventWaiters.length > 0) {
+                const waiter = eventWaiters.shift();
+                waiter?.({
+                    status: "completed",
+                    result: { ok: false, reason: "stage handle closed" },
+                });
+            }
+            await options.onClose?.({ park: false });
+        },
+    };
+}
+/**
+ * Map Pi session events to StageActivityEvent at the adapter edge, then
+ * forward to the activity observer (stderr + onActivity).
+ */
+function attachStageProgress(session, onActivity) {
+    const observer = createStageActivityObserver({ onActivity, writeStderr: true });
+    const unsubscribe = session.subscribe((event) => {
+        if (event.type === "message_update" &&
+            event.assistantMessageEvent.type === "text_delta") {
+            observer.onAssistantTextDelta(event.assistantMessageEvent.delta ?? "");
+            return;
+        }
+        if (event.type === "message_end" || event.type === "agent_end") {
+            observer.onStreamBoundary();
+        }
+        if (event.type === "agent_start" ||
+            event.type === "turn_start" ||
+            event.type === "tool_execution_start") {
+            observer.onStreamBoundary();
+        }
+        const activity = mapSessionEventToActivity(event);
+        if (!activity) {
+            return;
+        }
+        observer.onActivity(activity);
+    });
+    return () => {
+        unsubscribe();
+        observer.dispose();
+    };
+}
+function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName) {
+    let emitHint = emitHintOverride ??
+        `Required final action: call ${emitToolName} exactly once with status, summary, and artifacts (run-relative paths).`;
+    if (input.stage.payload_schema !== undefined) {
+        emitHint += `\nOn status=success, payload is required and must match this JSON Schema:\n${JSON.stringify(input.stage.payload_schema, null, 2)}`;
+    }
+    const attempt = input.roots.attempt ?? 1;
+    const attemptArtifactsPath = `stages/${input.stage.id}/attempts/${attempt}/artifacts/`;
+    const skillBaseDir = input.stage.skill !== undefined && input.skillFilePath !== undefined
+        ? path.dirname(input.skillFilePath)
+        : undefined;
+    const artifactGuidance = input.roots.mode === "bound" && artifactToolName !== undefined
+        ? [
+            `Project checkout (agent cwd): ${input.roots.checkoutRoot}`,
+            `Factory run workspace: ${input.roots.runWorkspaceDir}`,
+            `Builtin tools (read, bash, write, edit) are for work inside the project checkout.`,
+            skillBaseDir !== undefined
+                ? `Absolute read and bash against ${skillBaseDir} are in bounds for the linked skill.`
+                : undefined,
+            `Create factory stage artifacts only with ${artifactToolName} (path relative to ${attemptArtifactsPath}). Use the returned run-relative path in ${emitToolName}.`,
+            `This is soft guidance: prefer ${artifactToolName} for factory files under the run workspace; do not rely on relative builtin writes for those files.`,
+        ]
+            .filter(Boolean)
+            .join("\n")
+        : artifactToolName !== undefined
+            ? [
+                `Create factory stage artifacts with ${artifactToolName} (path relative to ${attemptArtifactsPath}). Use the returned run-relative path in ${emitToolName}.`,
+                `This is soft guidance: prefer ${artifactToolName} for factory files under the run workspace; do not rely on relative builtin writes for those files.`,
+            ].join("\n")
+            : `Create factory stage artifacts under ${attemptArtifactsPath} relative to the run folder.`;
+    return [
+        `Task id: ${input.task.id}`,
+        `Stage id: ${input.stage.id}`,
+        `Goal: ${input.task.goal}`,
+        input.task.context ? `Context: ${input.task.context}` : "",
+        input.task.constraints ? `Constraints: ${input.task.constraints}` : "",
+        formatPriorEnvelope(input.priorEnvelope),
+        "",
+        artifactGuidance,
+        emitHint,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+export function composeStageUserPrompt(input, emitToolName, emitHintOverride, artifactToolName) {
+    const body = buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName);
+    if (input.stage.skill !== undefined) {
+        return `/skill:${input.stage.skill} ${body}`;
+    }
+    return body;
+}
+/**
+ * DefaultResourceLoader with host/global discovery turned off.
+ *
+ * Without these flags the loader walks up from the run folder and would pick
+ * up the consumer project's AGENTS.md, `.agents/skills/`, `.pi/extensions`,
+ * and APPEND_SYSTEM.md. Stages must not inherit that context.
+ *
+ * `additionalExtensionPaths` is the only way extensions enter a sealed stage
+ * (used by StageProviderSupport implementations). With `noExtensions: true`,
+ * discovered global/project packages stay out; only allowlisted paths load.
+ * `additionalSkillPaths` is the matching allowlist for one named skill.
+ */
+export function createSealedResourceLoader(options) {
+    return new DefaultResourceLoader({
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        settingsManager: options.settingsManager,
+        systemPromptOverride: () => options.systemPrompt,
+        appendSystemPromptOverride: () => [],
+        additionalExtensionPaths: options.additionalExtensionPaths,
+        additionalSkillPaths: options.additionalSkillPaths,
+        noContextFiles: true,
+        noExtensions: true,
+        noSkills: true,
+        noPromptTemplates: true,
+        noThemes: true,
+    });
+}
+async function shutdownSession(session) {
+    if (!session) {
+        return;
+    }
+    // Bound abort: waitForIdle can hang if a provider bridge is mid-flight.
+    try {
+        await Promise.race([
+            session.abort(),
+            new Promise((resolve) => setTimeout(resolve, 3_000)),
+        ]);
+    }
+    catch {
+        // ignore abort errors during teardown
+    }
+    try {
+        session.dispose();
+    }
+    catch {
+        // ignore dispose errors during teardown
+    }
+}
+function resultFromCapture(capture) {
+    if (capture.error && !capture.envelope) {
+        return { ok: false, reason: capture.error };
+    }
+    if (!capture.envelope) {
+        return { ok: false, reason: "missing emit_stage_envelope" };
+    }
+    if (!isAdvancingEnvelope(capture.envelope)) {
+        return {
+            ok: false,
+            reason: "status: failure",
+            envelope: capture.envelope,
+        };
+    }
+    return { ok: true, envelope: capture.envelope };
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Stable Pi session JSONL path under the run workspace stage dir. */
+export function stageSessionFilePath(roots, stageId) {
+    const ctx = roots.attempt !== undefined
+        ? attemptContext(roots.attempt)
+        : noAttemptContext();
+    return ctx.sessionPath(roots.runWorkspaceDir, stageId);
+}
+export class StageSessionReconstructError extends Error {
+    stageId;
+    sessionFile;
+    constructor(message, options) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "StageSessionReconstructError";
+        this.stageId = options.stageId;
+        this.sessionFile = options.sessionFile;
+    }
+}
+/**
+ * Create or reopen the durable stage session file under the run workspace.
+ * Touches an empty file first so Pi flushes the session header immediately.
+ */
+export async function createStageSessionManager(roots, stageId) {
+    const sessionFile = stageSessionFilePath(roots, stageId);
+    await mkdir(path.dirname(sessionFile), { recursive: true });
+    if (!(await fileExists(sessionFile))) {
+        await writeFile(sessionFile, "");
+    }
+    return SessionManager.open(sessionFile, path.dirname(sessionFile), roots.cwd);
+}
+/**
+ * Open an existing stage session for post-restart reconstruct.
+ * Missing or corrupt files fail closed (KTD7) — never create a fresh session.
+ */
+export async function openStageSessionManager(roots, stageId) {
+    const sessionFile = stageSessionFilePath(roots, stageId);
+    if (!(await fileExists(sessionFile))) {
+        throw new StageSessionReconstructError(`stage session file missing for resume: ${sessionFile}`, { stageId, sessionFile });
+    }
+    try {
+        return SessionManager.open(sessionFile, path.dirname(sessionFile), roots.cwd);
+    }
+    catch (err) {
+        throw new StageSessionReconstructError(`stage session file corrupt or unreadable for resume: ${sessionFile}`, { stageId, sessionFile, cause: err });
+    }
+}
+/**
+ * Ensure the session is on disk before signaling waiting_for_input (KTD4).
+ * Dispose of the live AgentSession must not delete this file.
+ */
+export function ensureStageSessionFlushed(sessionManager, stageId) {
+    const sessionFile = sessionManager.getSessionFile();
+    if (!sessionManager.isPersisted() || !sessionFile) {
+        throw new StageSessionReconstructError("stage session is not persisted; cannot wait for input", { stageId, sessionFile: sessionFile ?? "(none)" });
+    }
+    return sessionFile;
+}
+const PREMATURE_ASK_OPERATOR_CLOSE = "stage handle closed";
+/**
+ * Remove an erroneous ask_operator toolResult written when a parked worker
+ * tears down before the operator answers. Restores an open tool call on disk.
+ */
+export async function repairPrematureAskOperatorClosure(sessionFile) {
+    let text;
+    try {
+        text = await readFile(sessionFile, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const lines = text.split("\n").filter((line) => line.trim().length > 0);
+    if (lines.length === 0) {
+        return false;
+    }
+    const entries = [];
+    for (const line of lines) {
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            return false;
+        }
+    }
+    let changed = false;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        if (!entry || typeof entry !== "object")
+            continue;
+        if (entry.type !== "message")
+            continue;
+        const message = entry.message;
+        if (!message || message.role !== "toolResult")
+            continue;
+        if (message.toolName !== "ask_operator" || message.isError !== true)
+            continue;
+        const content = message.content;
+        if (!Array.isArray(content))
+            continue;
+        const first = content[0];
+        if (first?.text !== PREMATURE_ASK_OPERATOR_CLOSE)
+            continue;
+        entries.splice(i, 1);
+        changed = true;
+        while (i < entries.length) {
+            const next = entries[i];
+            if (!next || typeof next !== "object")
+                break;
+            if (next.type !== "message")
+                break;
+            const nextMessage = next.message;
+            if (nextMessage?.role !== "assistant")
+                break;
+            if (nextMessage.stopReason === "error" ||
+                typeof nextMessage.errorMessage === "string") {
+                entries.splice(i, 1);
+                continue;
+            }
+            break;
+        }
+        break;
+    }
+    if (!changed) {
+        return false;
+    }
+    await writeFile(sessionFile, `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`);
+    return true;
+}
+function opaqueAnswerToText(answer) {
+    if (typeof answer === "string")
+        return answer;
+    try {
+        return JSON.stringify(answer);
+    }
+    catch {
+        return String(answer);
+    }
+}
+function findOpenToolCall(sessionManager) {
+    const entries = sessionManager.buildContextEntries();
+    const answered = new Set();
+    for (const entry of entries) {
+        if (entry.type !== "message")
+            continue;
+        const message = entry.message;
+        if (message.role === "toolResult" && typeof message.toolCallId === "string") {
+            answered.add(message.toolCallId);
+        }
+    }
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        if (entry.type !== "message")
+            continue;
+        const message = entry.message;
+        if (message.role !== "assistant" || !Array.isArray(message.content))
+            continue;
+        for (const block of message.content) {
+            if (block &&
+                typeof block === "object" &&
+                block.type === "toolCall") {
+                const toolCall = block;
+                if (typeof toolCall.id === "string" &&
+                    typeof toolCall.name === "string" &&
+                    !answered.has(toolCall.id)) {
+                    return { toolCallId: toolCall.id, toolName: toolCall.name };
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Inject an opaque operator answer into the persisted conversation (R9).
+ * Prefers completing an open tool call as a tool result (T2 seam); otherwise
+ * appends a custom message that stays in LLM context.
+ */
+export function injectOpaqueAnswerIntoSession(sessionManager, answer) {
+    const text = opaqueAnswerToText(answer);
+    const open = findOpenToolCall(sessionManager);
+    if (open) {
+        sessionManager.appendMessage({
+            role: "toolResult",
+            toolCallId: open.toolCallId,
+            toolName: open.toolName,
+            content: [{ type: "text", text }],
+            isError: false,
+            timestamp: Date.now(),
+        });
+        return {
+            injectedAs: "tool_result",
+            toolCallId: open.toolCallId,
+            toolName: open.toolName,
+        };
+    }
+    sessionManager.appendCustomMessageEntry("stageflow.operator_answer", text, true, { answer });
+    return { injectedAs: "custom_message" };
+}
+async function prepareStageSessionWiring(input, sessionManager, existingAskWaitChannel) {
+    const { roots } = input;
+    const provider = findProviderSupport(input.stage.model);
+    const capture = {};
+    const askWaitChannel = existingAskWaitChannel ?? new AskOperatorWaitChannel();
+    const emitDef = createEmitStageEnvelopeTool(capture, input.stage.payload_schema);
+    const emitTool = defineTool(emitDef);
+    const askDef = createAskOperatorTool({
+        requestWait: (prompt) => askWaitChannel.requestWait(prompt),
+    });
+    const askTool = defineTool(askDef);
+    const artifactDef = createWriteStageArtifactTool({
+        runWorkspaceDir: roots.runWorkspaceDir,
+        stageId: input.stage.id,
+        attempt: roots.attempt ?? 1,
+    });
+    const artifactTool = defineTool(artifactDef);
+    if (input.stage.skill !== undefined && input.skillFilePath === undefined) {
+        return {
+            ok: false,
+            reason: `Skill "${input.stage.skill}" is not installed`,
+        };
+    }
+    const additionalExtensionPaths = [];
+    let restoreProvider;
+    if (provider) {
+        const prepared = provider.prepare(input.stage.model);
+        if (prepared.error) {
+            return { ok: false, reason: prepared.error };
+        }
+        additionalExtensionPaths.push(...prepared.extensionPaths);
+        restoreProvider = prepared.restore;
+    }
+    try {
+        const modelRuntime = await ModelRuntime.create(roots.authPath ? { authPath: roots.authPath } : undefined);
+        const settingsManager = SettingsManager.inMemory({
+            compaction: { enabled: false },
+        });
+        const loader = createSealedResourceLoader({
+            cwd: roots.cwd,
+            agentDir: roots.agentDir,
+            settingsManager,
+            systemPrompt: input.stage.system_prompt,
+            additionalExtensionPaths,
+            ...(input.skillFilePath !== undefined
+                ? { additionalSkillPaths: [input.skillFilePath] }
+                : {}),
+        });
+        await loader.reload();
+        const extensionErrors = loader.getExtensions().errors;
+        if (extensionErrors.length > 0) {
+            restoreProvider?.();
+            return {
+                ok: false,
+                reason: `Failed to load Pi extension(s): ${extensionErrors
+                    .map((e) => `${e.path}: ${e.error}`)
+                    .join("; ")}`,
+            };
+        }
+        const skillDiagnostics = loader
+            .getSkills()
+            .diagnostics.filter((d) => d.type === "error" || d.type === "collision");
+        if (skillDiagnostics.length > 0) {
+            restoreProvider?.();
+            return {
+                ok: false,
+                reason: `Failed to load skill(s): ${skillDiagnostics
+                    .map((d) => (d.path !== undefined ? `${d.path}: ${d.message}` : d.message))
+                    .join("; ")}`,
+            };
+        }
+        if (input.stage.skill !== undefined &&
+            !loader.getSkills().skills.some((skill) => skill.name === input.stage.skill)) {
+            restoreProvider?.();
+            return {
+                ok: false,
+                reason: `Skill "${input.stage.skill}" is not installed`,
+            };
+        }
+        const customTools = [emitTool, askTool, artifactTool];
+        return {
+            sessionManager,
+            modelRuntime,
+            settingsManager,
+            loader,
+            tools: resolveStageToolNames(emitDef.name, artifactDef.name, askDef.name),
+            customTools,
+            emitDefName: emitDef.name,
+            askOperatorDefName: askDef.name,
+            artifactDefName: artifactDef.name,
+            providerEmitHint: provider?.emitToolHint?.(emitDef.name),
+            restoreProvider,
+            capture,
+            askWaitChannel,
+        };
+    }
+    catch (err) {
+        restoreProvider?.();
+        throw err;
+    }
+}
+function isStageRunResult(value) {
+    return "ok" in value;
+}
+/**
+ * Reconstruct an equivalent Pi session after process loss and inject the
+ * operator answer into conversation context (R5, R9, R10 / KTD5).
+ * Does not auto-continue the model turn — U4 owns the yield loop.
+ */
+export async function reconstructStageSessionForAnswer(input, answer) {
+    const sessionManager = await openStageSessionManager(input.roots, input.stage.id);
+    const sessionFile = ensureStageSessionFlushed(sessionManager, input.stage.id);
+    let injection;
+    try {
+        injection = injectOpaqueAnswerIntoSession(sessionManager, answer);
+    }
+    catch (err) {
+        throw new StageSessionReconstructError(`failed to inject answer into stage session: ${sessionFile}`, { stageId: input.stage.id, sessionFile, cause: err });
+    }
+    const wiring = await prepareStageSessionWiring(input, sessionManager);
+    if (isStageRunResult(wiring)) {
+        throw new StageSessionReconstructError(wiring.ok === false ? wiring.reason : "stage session reconstruct failed", { stageId: input.stage.id, sessionFile });
+    }
+    let session;
+    try {
+        const created = await createAgentSession({
+            cwd: input.roots.cwd,
+            agentDir: input.roots.agentDir,
+            modelRuntime: wiring.modelRuntime,
+            tools: wiring.tools,
+            customTools: wiring.customTools,
+            resourceLoader: wiring.loader,
+            sessionManager,
+            settingsManager: wiring.settingsManager,
+        });
+        session = created.session;
+        await session.bindExtensions({});
+        const resolved = resolveCliModel({
+            cliModel: input.stage.model,
+            modelRuntime: wiring.modelRuntime,
+        });
+        if (resolved.error || !resolved.model) {
+            throw new StageSessionReconstructError(resolved.error ?? `Model not found: ${input.stage.model}`, { stageId: input.stage.id, sessionFile });
+        }
+        await session.setModel(resolved.model);
+        if (resolved.thinkingLevel) {
+            session.setThinkingLevel(resolved.thinkingLevel);
+        }
+        const liveSession = session;
+        return {
+            session: liveSession,
+            sessionManager,
+            sessionFile,
+            injection,
+            restore: () => {
+                wiring.restoreProvider?.();
+            },
+            shutdown: async () => {
+                await shutdownSession(liveSession);
+                wiring.restoreProvider?.();
+            },
+        };
+    }
+    catch (err) {
+        await shutdownSession(session);
+        wiring.restoreProvider?.();
+        if (err instanceof StageSessionReconstructError)
+            throw err;
+        throw new StageSessionReconstructError(`failed to reconstruct stage session: ${err instanceof Error ? err.message : String(err)}`, { stageId: input.stage.id, sessionFile, cause: err });
+    }
+}
+async function bindStageSession(input, sessionManager, wiring) {
+    const { roots } = input;
+    const created = await createAgentSession({
+        cwd: roots.cwd,
+        agentDir: roots.agentDir,
+        modelRuntime: wiring.modelRuntime,
+        tools: wiring.tools,
+        customTools: wiring.customTools,
+        resourceLoader: wiring.loader,
+        sessionManager,
+        settingsManager: wiring.settingsManager,
+    });
+    const session = created.session;
+    ensureStageSessionFlushed(sessionManager, input.stage.id);
+    await session.bindExtensions({});
+    const resolved = resolveCliModel({
+        cliModel: input.stage.model,
+        modelRuntime: wiring.modelRuntime,
+    });
+    if (resolved.error || !resolved.model) {
+        await shutdownSession(session);
+        return {
+            ok: false,
+            reason: resolved.error ?? `Model not found: ${input.stage.model}`,
+        };
+    }
+    try {
+        await session.setModel(resolved.model);
+        if (resolved.thinkingLevel) {
+            session.setThinkingLevel(resolved.thinkingLevel);
+        }
+    }
+    catch (err) {
+        await shutdownSession(session);
+        return {
+            ok: false,
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+    return session;
+}
+function syncAgentMessagesFromSession(session, sessionManager) {
+    session.agent.state.messages = sessionManager.buildSessionContext().messages;
+}
+export class PiAgentAdapter {
+    openStage(input) {
+        const timeoutMs = input.timeoutMs ?? DEFAULT_STAGE_TIMEOUT_MS;
+        const askWaitChannel = new AskOperatorWaitChannel();
+        const sessionFile = input.resumeToken ?? stageSessionFilePath(input.roots, input.stage.id);
+        let sessionManager;
+        let resumeWaiting = false;
+        if (existsSync(sessionFile)) {
+            try {
+                sessionManager = SessionManager.open(sessionFile, path.dirname(sessionFile), input.roots.cwd);
+            }
+            catch (err) {
+                throw new StageSessionReconstructError(`stage session file corrupt or unreadable for resume: ${sessionFile}`, {
+                    stageId: input.stage.id,
+                    sessionFile,
+                    cause: err,
+                });
+            }
+            ensureStageSessionFlushed(sessionManager, input.stage.id);
+            if (!findOpenToolCall(sessionManager)) {
+                throw new StageSessionReconstructError(`stage session has no open tool call for resume: ${sessionFile}`, { stageId: input.stage.id, sessionFile });
+            }
+            resumeWaiting = true;
+        }
+        let session;
+        let wiring;
+        let unsubscribeProgress;
+        let prepareError;
+        const preparePromise = (async () => {
+            if (!sessionManager) {
+                sessionManager = await createStageSessionManager(input.roots, input.stage.id);
+            }
+            const prepared = await prepareStageSessionWiring(input, sessionManager, askWaitChannel);
+            if (isStageRunResult(prepared)) {
+                prepareError = prepared;
+                return;
+            }
+            wiring = prepared;
+            const bound = await bindStageSession(input, sessionManager, wiring);
+            if (bound && typeof bound === "object" && "ok" in bound) {
+                prepareError = bound;
+                wiring.restoreProvider?.();
+                wiring = undefined;
+                return;
+            }
+            session = bound;
+            unsubscribeProgress = attachStageProgress(session, input.onActivity);
+        })();
+        const runWithTimeout = async (work) => {
+            await preparePromise;
+            if (prepareError)
+                return prepareError;
+            if (!session || !wiring || !sessionManager) {
+                return { ok: false, reason: "stage session failed to prepare" };
+            }
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const workPromise = work();
+                const abortPromise = new Promise((_, reject) => {
+                    controller.signal.addEventListener("abort", () => {
+                        reject(new Error(`stage timed out after ${timeoutMs}ms`));
+                    });
+                });
+                await Promise.race([workPromise, abortPromise]);
+                return resultFromCapture(wiring.capture);
+            }
+            catch (err) {
+                if (wiring.capture.envelope && isAdvancingEnvelope(wiring.capture.envelope)) {
+                    return { ok: true, envelope: wiring.capture.envelope };
+                }
+                return {
+                    ok: false,
+                    reason: err instanceof Error ? err.message : String(err),
+                    envelope: wiring.capture.envelope,
+                };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        return createConnectedAskWaitStageHandle({
+            stageId: input.stage.id,
+            askWaitChannel,
+            onBeforeWaitYield: () => {
+                if (sessionManager) {
+                    ensureStageSessionFlushed(sessionManager, input.stage.id);
+                }
+            },
+            run: async () => {
+                return runWithTimeout(async () => {
+                    const userPrompt = composeStageUserPrompt(input, wiring.emitDefName, wiring.providerEmitHint, wiring.artifactDefName);
+                    await session.prompt(userPrompt);
+                });
+            },
+            resume: resumeWaiting
+                ? {
+                    onDeliver: (answer) => {
+                        if (!sessionManager) {
+                            throw new StageSessionReconstructError("stage session missing during resume deliver", { stageId: input.stage.id, sessionFile });
+                        }
+                        injectOpaqueAnswerIntoSession(sessionManager, answer);
+                        if (session) {
+                            syncAgentMessagesFromSession(session, sessionManager);
+                        }
+                    },
+                    continueRun: async () => {
+                        return runWithTimeout(async () => {
+                            if (!session || !sessionManager) {
+                                throw new StageSessionReconstructError("stage session missing during resume continue", { stageId: input.stage.id, sessionFile });
+                            }
+                            syncAgentMessagesFromSession(session, sessionManager);
+                            await session.agent.continue();
+                        });
+                    },
+                }
+                : undefined,
+            onClose: async (closeOptions) => {
+                await preparePromise.catch(() => undefined);
+                if (closeOptions?.park) {
+                    if (sessionManager) {
+                        ensureStageSessionFlushed(sessionManager, input.stage.id);
+                        if (askWaitChannel.hasPending) {
+                            await repairPrematureAskOperatorClosure(sessionFile);
+                        }
+                    }
+                    return;
+                }
+                askWaitChannel.rejectPending(PREMATURE_ASK_OPERATOR_CLOSE);
+                unsubscribeProgress?.();
+                await shutdownSession(session);
+                wiring?.restoreProvider?.();
+            },
+        });
+    }
+    async runStage(input) {
+        return runStageViaOpen(this, input);
+    }
+}