stageflow 0.1.0

package/dist/agent/fakeAgent.js

@@ -0,0 +1,295 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { assertRequiredEnvelope, isAdvancingEnvelope, } from "../envelope/check.js";
+import { assertEnvelopePayload } from "../envelope/payloadSchema.js";
+import { assertAnswerMatchesPrompt, parseAskOperatorAnswer, } from "../tools/askOperator.js";
+import { tryParsePendingPrompt } from "../runtime/stageHitl.js";
+import { runStageViaOpen } from "./port.js";
+function opaqueEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+export function fakeHitlResumePath(roots, stageId) {
+    return path.join(roots.runWorkspaceDir, "stages", stageId, "fake-hitl-resume.json");
+}
+function writeFakeHitlResume(roots, stageId, state) {
+    const filePath = fakeHitlResumePath(roots, stageId);
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    writeFileSync(filePath, `${JSON.stringify(state)}\n`, "utf8");
+}
+function clearFakeHitlResume(roots, stageId) {
+    const filePath = fakeHitlResumePath(roots, stageId);
+    if (existsSync(filePath)) {
+        unlinkSync(filePath);
+    }
+}
+function loadFakeHitlResume(roots, stageId) {
+    const filePath = fakeHitlResumePath(roots, stageId);
+    if (!existsSync(filePath))
+        return undefined;
+    try {
+        const raw = JSON.parse(readFileSync(filePath, "utf8"));
+        if (!raw ||
+            !Array.isArray(raw.waitRequests) ||
+            typeof raw.waitIndex !== "number" ||
+            raw.envelope === undefined) {
+            return "corrupt";
+        }
+        return raw;
+    }
+    catch {
+        return "corrupt";
+    }
+}
+export class FakeAgent {
+    behavior;
+    lastRoots;
+    receivedAnswers = [];
+    constructor(behavior) {
+        this.behavior = behavior;
+    }
+    openStage(input) {
+        this.lastRoots = input.roots;
+        this.receivedAnswers = [];
+        let behavior = this.behavior;
+        const receivedAnswers = this.receivedAnswers;
+        let waitIndex = 0;
+        let waiting = false;
+        let closed = false;
+        let answerResolver;
+        let answerPromise;
+        let started = false;
+        let resumeCorrupt = false;
+        const armWait = () => {
+            waiting = true;
+            answerPromise = new Promise((resolve) => {
+                answerResolver = resolve;
+            });
+        };
+        const awaitAnswer = async () => {
+            if (!answerPromise)
+                return undefined;
+            const answer = await answerPromise;
+            waiting = false;
+            answerResolver = undefined;
+            answerPromise = undefined;
+            return answer;
+        };
+        if (behavior.type === "wait_then_emit") {
+            const loaded = loadFakeHitlResume(input.roots, input.stage.id);
+            if (loaded === "corrupt") {
+                resumeCorrupt = true;
+            }
+            else if (loaded) {
+                behavior = {
+                    type: "wait_then_emit",
+                    waitRequests: loaded.waitRequests,
+                    expectedAnswers: loaded.expectedAnswers,
+                    envelope: loaded.envelope,
+                };
+                waitIndex = loaded.waitIndex;
+                armWait();
+            }
+        }
+        const emitStartActivity = () => {
+            if (started)
+                return;
+            started = true;
+            input.onActivity?.({ event: "agent_start" });
+            input.onActivity?.({
+                event: "tool_start",
+                toolName: "fake_tool",
+                toolCallId: "fake-1",
+            });
+            input.onActivity?.({
+                event: "tool_end",
+                toolName: "fake_tool",
+                toolCallId: "fake-1",
+                isError: false,
+            });
+        };
+        const finishEmit = () => {
+            clearFakeHitlResume(input.roots, input.stage.id);
+            if (behavior.type === "throw") {
+                input.onActivity?.({ event: "agent_end" });
+                return {
+                    status: "completed",
+                    result: { ok: false, reason: behavior.message },
+                };
+            }
+            if (behavior.type === "never_emit") {
+                input.onActivity?.({ event: "agent_end" });
+                return {
+                    status: "completed",
+                    result: { ok: false, reason: "missing emit_stage_envelope" },
+                };
+            }
+            const envelopeValue = behavior.type === "emit" || behavior.type === "wait_then_emit"
+                ? behavior.envelope
+                : undefined;
+            try {
+                const envelope = assertRequiredEnvelope(envelopeValue);
+                assertEnvelopePayload(envelope, input.stage.payload_schema);
+                if (!isAdvancingEnvelope(envelope)) {
+                    input.onActivity?.({ event: "agent_end" });
+                    return {
+                        status: "completed",
+                        result: {
+                            ok: false,
+                            reason: "status: failure",
+                            envelope,
+                        },
+                    };
+                }
+                input.onActivity?.({
+                    event: "message",
+                    role: "assistant",
+                    text: envelope.summary,
+                });
+                input.onActivity?.({ event: "agent_end" });
+                return { status: "completed", result: { ok: true, envelope } };
+            }
+            catch (err) {
+                input.onActivity?.({ event: "agent_end" });
+                return {
+                    status: "completed",
+                    result: {
+                        ok: false,
+                        reason: err instanceof Error ? err.message : String(err),
+                    },
+                };
+            }
+        };
+        return {
+            stageId: input.stage.id,
+            async next() {
+                if (closed) {
+                    return {
+                        status: "completed",
+                        result: { ok: false, reason: "stage handle closed" },
+                    };
+                }
+                if (resumeCorrupt) {
+                    input.onActivity?.({ event: "agent_end" });
+                    return {
+                        status: "completed",
+                        result: {
+                            ok: false,
+                            reason: "corrupt resume context for waiting stage",
+                        },
+                    };
+                }
+                emitStartActivity();
+                if (behavior.type !== "wait_then_emit") {
+                    return finishEmit();
+                }
+                if (waiting) {
+                    const answer = await awaitAnswer();
+                    if (answer === undefined && closed) {
+                        return {
+                            status: "completed",
+                            result: { ok: false, reason: "stage handle closed" },
+                        };
+                    }
+                    const priorRequest = behavior.waitRequests[waitIndex - 1];
+                    const t2Prompt = tryParsePendingPrompt(priorRequest);
+                    if (t2Prompt !== undefined && answer !== undefined) {
+                        try {
+                            const parsed = parseAskOperatorAnswer(answer);
+                            assertAnswerMatchesPrompt(t2Prompt, parsed);
+                        }
+                        catch (err) {
+                            input.onActivity?.({ event: "agent_end" });
+                            clearFakeHitlResume(input.roots, input.stage.id);
+                            return {
+                                status: "completed",
+                                result: {
+                                    ok: false,
+                                    reason: err instanceof Error
+                                        ? err.message
+                                        : `invalid T2 answer at wait ${waitIndex - 1}`,
+                                },
+                            };
+                        }
+                    }
+                    const expected = behavior.expectedAnswers?.[waitIndex - 1];
+                    if (expected !== undefined &&
+                        answer !== undefined &&
+                        !opaqueEqual(answer, expected)) {
+                        input.onActivity?.({ event: "agent_end" });
+                        clearFakeHitlResume(input.roots, input.stage.id);
+                        return {
+                            status: "completed",
+                            result: {
+                                ok: false,
+                                reason: `unexpected answer at wait ${waitIndex - 1}`,
+                            },
+                        };
+                    }
+                }
+                if (waitIndex < behavior.waitRequests.length) {
+                    const request = behavior.waitRequests[waitIndex];
+                    waitIndex += 1;
+                    armWait();
+                    writeFakeHitlResume(input.roots, input.stage.id, {
+                        waitRequests: behavior.waitRequests,
+                        expectedAnswers: behavior.expectedAnswers,
+                        envelope: behavior.envelope,
+                        waitIndex,
+                    });
+                    return { status: "waiting_for_input", request };
+                }
+                return finishEmit();
+            },
+            deliverAnswer(answer) {
+                if (!waiting || !answerResolver)
+                    return;
+                const resolve = answerResolver;
+                answerResolver = undefined;
+                receivedAnswers.push(answer);
+                resolve(answer);
+            },
+            async close(options) {
+                closed = true;
+                if (options?.park) {
+                    return;
+                }
+                if (waiting && answerResolver) {
+                    const resolve = answerResolver;
+                    answerResolver = undefined;
+                    waiting = false;
+                    answerPromise = undefined;
+                    resolve(undefined);
+                }
+            },
+        };
+    }
+    async runStage(input) {
+        return runStageViaOpen(this, input);
+    }
+}
+export function scriptedFakeAgent(behaviors) {
+    const recorded = [];
+    let index = 0;
+    return {
+        recorded,
+        openStage(input) {
+            const behavior = behaviors[index] ?? { type: "never_emit" };
+            index += 1;
+            const agent = new FakeAgent(behavior);
+            const handle = agent.openStage(input);
+            if (agent.lastRoots)
+                recorded.push(agent.lastRoots);
+            return handle;
+        },
+        async runStage(input) {
+            return runStageViaOpen(this, input);
+        },
+    };
+}

package/dist/agent/oauthSessionManager.d.ts

@@ -0,0 +1,33 @@
+import type { AuthEvent, AuthPrompt } from "@earendil-works/pi-ai";
+import { type ProviderAuthContext, type ProviderAuthStatus } from "./providerAuth.js";
+export type LoginSessionStatus = "running" | "completed" | "failed" | "cancelled";
+export type LoginSessionPendingPrompt = {
+    type: AuthPrompt["type"];
+    message: string;
+    placeholder?: string;
+    options?: readonly {
+        id: string;
+        label: string;
+        description?: string;
+    }[];
+};
+export type LoginSessionProjection = {
+    id: string;
+    providerId: string;
+    authType: "oauth";
+    status: LoginSessionStatus;
+    events: AuthEvent[];
+    pendingPrompt?: LoginSessionPendingPrompt;
+    error?: {
+        message: string;
+    };
+    warning?: {
+        message: string;
+    };
+    provider?: ProviderAuthStatus;
+};
+export declare function getLoginSession(sessionId: string): LoginSessionProjection | undefined;
+export declare function answerLoginSession(sessionId: string, value: string): LoginSessionProjection;
+export declare function cancelLoginSession(sessionId: string): LoginSessionProjection;
+export declare function resetSessionsForTests(): void;
+export declare function startOAuthLoginSession(cwd: string, providerId: string, ctx?: ProviderAuthContext): Promise<LoginSessionProjection>;

package/dist/agent/oauthSessionManager.js

@@ -0,0 +1,214 @@
+import { randomUUID } from "node:crypto";
+import { CredentialSynchronizationError } from "@earendil-works/pi-coding-agent";
+import { defaultContext, openRuntime, statusForProvider, ProviderAuthError, } from "./providerAuth.js";
+const loginSessions = new Map();
+let runningLoginSessionId;
+function promptMeta(prompt) {
+    if (prompt.type === "select") {
+        return {
+            type: "select",
+            message: prompt.message,
+            options: prompt.options.map((o) => ({
+                id: o.id,
+                label: o.label,
+                ...(o.description !== undefined ? { description: o.description } : {}),
+            })),
+        };
+    }
+    return {
+        type: prompt.type,
+        message: prompt.message,
+        ...(prompt.placeholder !== undefined
+            ? { placeholder: prompt.placeholder }
+            : {}),
+    };
+}
+function projectLoginSession(session) {
+    return {
+        id: session.id,
+        providerId: session.providerId,
+        authType: "oauth",
+        status: session.status,
+        events: [...session.events],
+        ...(session.pendingPrompt
+            ? { pendingPrompt: session.pendingPrompt.meta }
+            : {}),
+        ...(session.error ? { error: session.error } : {}),
+        ...(session.warning ? { warning: session.warning } : {}),
+        ...(session.provider ? { provider: session.provider } : {}),
+    };
+}
+function rejectPendingPrompt(session, reason) {
+    const pending = session.pendingPrompt;
+    if (!pending)
+        return;
+    session.pendingPrompt = undefined;
+    pending.reject(reason);
+}
+function clearRunningIf(sessionId) {
+    if (runningLoginSessionId === sessionId) {
+        runningLoginSessionId = undefined;
+    }
+}
+export function getLoginSession(sessionId) {
+    const session = loginSessions.get(sessionId);
+    return session ? projectLoginSession(session) : undefined;
+}
+export function answerLoginSession(sessionId, value) {
+    const session = loginSessions.get(sessionId);
+    if (!session) {
+        throw new ProviderAuthError("Login session not found", 404);
+    }
+    if (session.status !== "running") {
+        throw new ProviderAuthError("Login session is not awaiting input", 409);
+    }
+    if (!session.pendingPrompt) {
+        throw new ProviderAuthError("No pending login prompt", 409);
+    }
+    if (typeof value !== "string") {
+        throw new ProviderAuthError("value is required", 400);
+    }
+    const pending = session.pendingPrompt;
+    session.pendingPrompt = undefined;
+    pending.resolve(value);
+    return projectLoginSession(session);
+}
+export function cancelLoginSession(sessionId) {
+    const session = loginSessions.get(sessionId);
+    if (!session) {
+        throw new ProviderAuthError("Login session not found", 404);
+    }
+    if (session.status !== "running") {
+        return projectLoginSession(session);
+    }
+    session.status = "cancelled";
+    session.error = { message: "Login cancelled" };
+    clearRunningIf(sessionId);
+    rejectPendingPrompt(session, new Error("Login cancelled"));
+    session.abortController.abort();
+    return projectLoginSession(session);
+}
+export function resetSessionsForTests() {
+    for (const session of loginSessions.values()) {
+        if (session.status === "running") {
+            session.status = "cancelled";
+            rejectPendingPrompt(session, new Error("Login cancelled"));
+            session.abortController.abort();
+        }
+    }
+    loginSessions.clear();
+    runningLoginSessionId = undefined;
+}
+export async function startOAuthLoginSession(cwd, providerId, ctx = defaultContext) {
+    if (runningLoginSessionId !== undefined) {
+        throw new ProviderAuthError("An OAuth login is already in progress", 409);
+    }
+    const runtime = await openRuntime(cwd, ctx);
+    const provider = runtime.getProvider(providerId);
+    if (!provider) {
+        throw new ProviderAuthError("Provider not found", 404);
+    }
+    if (provider.auth.oauth === undefined) {
+        throw new ProviderAuthError("Provider does not support oauth login", 400);
+    }
+    const sessionId = randomUUID();
+    const abortController = new AbortController();
+    const session = {
+        id: sessionId,
+        providerId,
+        authType: "oauth",
+        status: "running",
+        events: [],
+        abortController,
+    };
+    loginSessions.set(sessionId, session);
+    runningLoginSessionId = sessionId;
+    const interaction = {
+        signal: abortController.signal,
+        notify(event) {
+            if (session.status !== "running")
+                return;
+            session.events.push(event);
+        },
+        prompt(prompt) {
+            if (session.status !== "running") {
+                return Promise.reject(new Error("Login session is not running"));
+            }
+            if (abortController.signal.aborted || prompt.signal?.aborted) {
+                return Promise.reject(new Error("Login cancelled"));
+            }
+            return new Promise((resolve, reject) => {
+                const onAbort = () => {
+                    if (session.pendingPrompt) {
+                        session.pendingPrompt = undefined;
+                        reject(new Error("Login cancelled"));
+                    }
+                };
+                abortController.signal.addEventListener("abort", onAbort, {
+                    once: true,
+                });
+                if (prompt.signal) {
+                    prompt.signal.addEventListener("abort", onAbort, { once: true });
+                }
+                session.pendingPrompt = {
+                    meta: promptMeta(prompt),
+                    resolve: (value) => {
+                        abortController.signal.removeEventListener("abort", onAbort);
+                        prompt.signal?.removeEventListener("abort", onAbort);
+                        resolve(value);
+                    },
+                    reject: (err) => {
+                        abortController.signal.removeEventListener("abort", onAbort);
+                        prompt.signal?.removeEventListener("abort", onAbort);
+                        reject(err);
+                    },
+                };
+            });
+        },
+    };
+    void (async () => {
+        try {
+            await runtime.login(providerId, "oauth", interaction);
+            if (session.status !== "running")
+                return;
+            session.status = "completed";
+            session.provider = await statusForProvider(runtime, providerId);
+        }
+        catch (err) {
+            if (session.status === "cancelled") {
+                return;
+            }
+            if (err instanceof CredentialSynchronizationError) {
+                session.status = "completed";
+                session.warning = {
+                    message: "Connected, but model catalog sync failed. Credentials were saved — you can retry later without disconnecting.",
+                };
+                try {
+                    session.provider = await statusForProvider(runtime, providerId);
+                }
+                catch {
+                    session.provider = {
+                        providerId,
+                        configured: true,
+                        authKind: "oauth",
+                    };
+                }
+                return;
+            }
+            if (abortController.signal.aborted) {
+                session.status = "cancelled";
+                session.error = { message: "Login cancelled" };
+                return;
+            }
+            session.status = "failed";
+            session.error = { message: "Provider login failed" };
+        }
+        finally {
+            if (session.pendingPrompt) {
+                rejectPendingPrompt(session, new Error("Login finished"));
+            }
+            clearRunningIf(sessionId);
+        }
+    })();
+    return projectLoginSession(session);
+}

package/dist/agent/piAdapter.d.ts

@@ -0,0 +1,128 @@
+import { type AgentSession, DefaultResourceLoader, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import type { StageRoots } from "../runtime/stageRoots.js";
+import { type AskOperatorPrompt, type AskOperatorWaitBridge } from "../tools/askOperator.js";
+import "./cursorProvider.js";
+import type { AgentPort, OpaqueAnswer, StageHandle, StageHandleCloseOptions, StageRunInput, StageRunResult } 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 declare function resolveStageToolNames(emitToolName: string, artifactToolName?: string, askOperatorToolName?: string): string[];
+/**
+ * In-process wait channel for `ask_operator` → StageHandle yield/deliver.
+ * HITL `openStage` connects this via `setWaitHandler` + handle `deliverAnswer`.
+ */
+export declare class AskOperatorWaitChannel implements AskOperatorWaitBridge {
+    private pending;
+    private onWait;
+    setWaitHandler(handler: (prompt: AskOperatorPrompt) => void): void;
+    requestWait(prompt: AskOperatorPrompt): Promise<unknown>;
+    deliverAnswer(answer: unknown): boolean;
+    rejectPending(reason: string): void;
+    get hasPending(): boolean;
+}
+/**
+ * Bridge used when no StageHandle wait loop is connected.
+ * Calling ask_operator fails closed instead of hanging the session.
+ */
+export declare function createUnconnectedAskWaitBridge(): AskOperatorWaitBridge;
+export type ConnectedAskWaitResume = {
+    onDeliver: (answer: OpaqueAnswer) => void;
+    continueRun: () => Promise<StageRunResult>;
+};
+export type ConnectedAskWaitStageHandleOptions = {
+    stageId: string;
+    askWaitChannel: AskOperatorWaitChannel;
+    run: () => Promise<StageRunResult>;
+    onBeforeWaitYield?: (prompt: AskOperatorPrompt) => void;
+    onClose?: (options?: StageHandleCloseOptions) => Promise<void>;
+    resume?: ConnectedAskWaitResume;
+};
+/**
+ * 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 declare function createConnectedAskWaitStageHandle(options: ConnectedAskWaitStageHandleOptions): StageHandle;
+export declare function composeStageUserPrompt(input: StageRunInput, emitToolName: string, emitHintOverride?: string, artifactToolName?: string): string;
+/**
+ * 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 declare function createSealedResourceLoader(options: {
+    cwd: string;
+    agentDir: string;
+    settingsManager: SettingsManager;
+    systemPrompt: string;
+    additionalExtensionPaths?: string[];
+    additionalSkillPaths?: string[];
+}): DefaultResourceLoader;
+/** Stable Pi session JSONL path under the run workspace stage dir. */
+export declare function stageSessionFilePath(roots: Pick<StageRoots, "runWorkspaceDir" | "attempt">, stageId: string): string;
+export declare class StageSessionReconstructError extends Error {
+    readonly stageId: string;
+    readonly sessionFile: string;
+    constructor(message: string, options: {
+        stageId: string;
+        sessionFile: string;
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare function createStageSessionManager(roots: StageRoots, stageId: string): Promise<SessionManager>;
+/**
+ * Open an existing stage session for post-restart reconstruct.
+ * Missing or corrupt files fail closed (KTD7) — never create a fresh session.
+ */
+export declare function openStageSessionManager(roots: StageRoots, stageId: string): Promise<SessionManager>;
+/**
+ * Ensure the session is on disk before signaling waiting_for_input (KTD4).
+ * Dispose of the live AgentSession must not delete this file.
+ */
+export declare function ensureStageSessionFlushed(sessionManager: SessionManager, stageId: string): string;
+/**
+ * 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 declare function repairPrematureAskOperatorClosure(sessionFile: string): Promise<boolean>;
+export type InjectOpaqueAnswerResult = {
+    injectedAs: "tool_result" | "custom_message";
+    toolCallId?: string;
+    toolName?: string;
+};
+/**
+ * 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 declare function injectOpaqueAnswerIntoSession(sessionManager: SessionManager, answer: OpaqueAnswer): InjectOpaqueAnswerResult;
+export type ReconstructedStageSession = {
+    session: AgentSession;
+    sessionManager: SessionManager;
+    sessionFile: string;
+    injection: InjectOpaqueAnswerResult;
+    restore: () => void;
+    shutdown: () => Promise<void>;
+};
+/**
+ * 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 declare function reconstructStageSessionForAnswer(input: StageRunInput, answer: OpaqueAnswer): Promise<ReconstructedStageSession>;
+export declare class PiAgentAdapter implements AgentPort {
+    openStage(input: StageRunInput): StageHandle;
+    runStage(input: StageRunInput): Promise<StageRunResult>;
+}