stageflow 0.1.0

package/dist/runtime/runRetryCoordinator.d.ts

@@ -0,0 +1,85 @@
+import type { AgentPort } from "../agent/port.js";
+import type { RunDetail, RunStatus, RunStore } from "../runstore/port.js";
+import type { PipelineRunResult } from "./pipelineRunner.js";
+import { type SchedulerPreparedPipeline } from "./pipelineScheduler.js";
+import type { StageExecutionMode } from "./stageConcurrency.js";
+import type { StageProcessLauncher } from "./stageProcessLauncher.js";
+import type { StageHitlController } from "./stageHitl.js";
+import type { OperatorCatalog } from "./stageAttemptBootstrap.js";
+export declare class DuplicateRetryRootError extends Error {
+    constructor(runId: string, stageId: string);
+}
+export declare class RetryCoordinatorInactiveError extends Error {
+    constructor(runId: string);
+}
+export declare class RetryRootWaitTimeoutError extends Error {
+    constructor(runId: string, stageId: string, attempt: number);
+}
+export type RunRetryCoordinatorStartOptions = {
+    runId: string;
+    roots: Map<string, number>;
+    prepared: SchedulerPreparedPipeline;
+    maxActiveStagesPerRun: number;
+    executionMode?: StageExecutionMode;
+    stageProcessLauncher?: StageProcessLauncher;
+    onLoopTick?: () => void | Promise<void>;
+};
+export type RetryStageResult = {
+    ok: true;
+    runId: string;
+    stageId: string;
+    attemptIndex: number;
+} | {
+    ok: false;
+    reason: string;
+    status?: number;
+};
+export type RetryTrackingPort = {
+    ensureResumeTracked(runId: string): Promise<{
+        ok: true;
+        insertedForResume?: boolean;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    onOrchestrationStarted(runId: string, promise: Promise<PipelineRunResult>): void;
+    rollbackStartTracking(runId: string, state: {
+        insertedForResume: boolean;
+        bumpedRunning: boolean;
+        priorRunStatus: RunStatus;
+    }): Promise<void>;
+};
+export type RetryStageRequest = {
+    runId: string;
+    stageId: string;
+    store: RunStore;
+    agent: AgentPort;
+    cwd: string;
+    operatorCatalog?: OperatorCatalog;
+    maxActiveStagesPerRun: number;
+    executionMode: StageExecutionMode;
+    stageProcessLauncher?: StageProcessLauncher;
+    hitl: StageHitlController;
+    orchestrationConflict: boolean;
+    tracking: RetryTrackingPort;
+};
+export declare function assertStageRetryEligible(detail: RunDetail, stageId: string, opts?: {
+    recoveryActive?: boolean;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    status: number;
+};
+export declare class RunRetryCoordinator {
+    private readonly sessions;
+    isActive(runId: string): boolean;
+    getOrchestrationPromise(runId: string): Promise<PipelineRunResult> | undefined;
+    getActiveRoots(runId: string): ReadonlyMap<string, number> | undefined;
+    signalExternalRetryRootTerminal(runId: string, stageId: string): void;
+    start(options: RunRetryCoordinatorStartOptions): void;
+    addRoot(runId: string, stageId: string, attempt: number): Promise<void>;
+    retryStage(req: RetryStageRequest): Promise<RetryStageResult>;
+    waitForRoot(runId: string, stageId: string, _store: RunStore): Promise<void>;
+}

package/dist/runtime/runRetryCoordinator.js

@@ -0,0 +1,372 @@
+import { retryRun, } from "./pipelineScheduler.js";
+import { loadRunContext } from "./resumeReconstruct.js";
+import { syncRunStatusFromStages } from "./stageRecovery.js";
+export class DuplicateRetryRootError extends Error {
+    constructor(runId, stageId) {
+        super(`Retry already in progress for run ${runId} stage ${stageId}`);
+        this.name = "DuplicateRetryRootError";
+    }
+}
+export class RetryCoordinatorInactiveError extends Error {
+    constructor(runId) {
+        super(`Retry coordinator is not active for run ${runId}`);
+        this.name = "RetryCoordinatorInactiveError";
+    }
+}
+export class RetryRootWaitTimeoutError extends Error {
+    constructor(runId, stageId, attempt) {
+        super(`Retry root wait timed out for run ${runId} stage ${stageId} attempt ${attempt}`);
+        this.name = "RetryRootWaitTimeoutError";
+    }
+}
+export function assertStageRetryEligible(detail, stageId, opts) {
+    const stageSnap = detail.stages.find((s) => s.stage_id === stageId);
+    if (!stageSnap) {
+        return {
+            ok: false,
+            reason: `Stage not found: ${stageId}`,
+            status: 404,
+        };
+    }
+    if (stageSnap.status === "waiting_for_input") {
+        return {
+            ok: false,
+            reason: `Stage is waiting for input and cannot be retried`,
+            status: 409,
+        };
+    }
+    const recoveryActive = opts?.recoveryActive === true;
+    if (detail.status !== "failed") {
+        if (!(detail.status === "running" && recoveryActive)) {
+            return {
+                ok: false,
+                reason: `Run is not failed (status=${detail.status})`,
+                status: 409,
+            };
+        }
+    }
+    if (stageSnap.status !== "failed") {
+        return {
+            ok: false,
+            reason: `Stage is not failed (status=${stageSnap.status})`,
+            status: 409,
+        };
+    }
+    return { ok: true };
+}
+function mutationKey(stageId, attempt) {
+    return `${stageId}\0${attempt}`;
+}
+function rootWaitKey(runId, stageId, attempt) {
+    return `${runId}\0${stageId}\0${attempt}`;
+}
+function readRetryRootWaitTimeoutMs() {
+    const raw = process.env.STAGEFLOW_RETRY_ROOT_WAIT_TIMEOUT_MS;
+    if (raw !== undefined && raw !== "") {
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return 30 * 60 * 1000;
+}
+function logRetryRoots(runId, size, action) {
+    console.info(JSON.stringify({ event: "retry_roots", runId, size, action }));
+}
+function createMutationQueue() {
+    const pendingDeltas = [];
+    const waiters = new Map();
+    const rejectPendingEnqueues = (reason) => {
+        pendingDeltas.length = 0;
+        for (const list of waiters.values()) {
+            for (const waiter of list) {
+                waiter.reject(reason);
+            }
+        }
+        waiters.clear();
+    };
+    const mutationQueue = {
+        enqueue(stageId, attempt) {
+            return new Promise((resolve, reject) => {
+                pendingDeltas.push({ stageId, attempt });
+                const key = mutationKey(stageId, attempt);
+                const list = waiters.get(key) ?? [];
+                list.push({ resolve, reject });
+                waiters.set(key, list);
+            });
+        },
+        drainPending(apply) {
+            for (const delta of pendingDeltas.splice(0)) {
+                apply(delta.stageId, delta.attempt);
+                const key = mutationKey(delta.stageId, delta.attempt);
+                const list = waiters.get(key);
+                if (list !== undefined) {
+                    for (const waiter of list) {
+                        waiter.resolve();
+                    }
+                    waiters.delete(key);
+                }
+            }
+        },
+        pendingStageIds() {
+            return new Set(pendingDeltas.map((delta) => delta.stageId));
+        },
+    };
+    return { mutationQueue, rejectPendingEnqueues };
+}
+export class RunRetryCoordinator {
+    sessions = new Map();
+    isActive(runId) {
+        return this.sessions.has(runId);
+    }
+    getOrchestrationPromise(runId) {
+        return this.sessions.get(runId)?.orchestrationPromise;
+    }
+    getActiveRoots(runId) {
+        return this.sessions.get(runId)?.activeRoots;
+    }
+    signalExternalRetryRootTerminal(runId, stageId) {
+        const session = this.sessions.get(runId);
+        if (session === undefined)
+            return;
+        const attempt = session.activeRoots.get(stageId);
+        if (attempt === undefined)
+            return;
+        const key = rootWaitKey(runId, stageId, attempt);
+        if (session.terminalRoots.has(key))
+            return;
+        session.terminalRoots.add(key);
+        const list = session.rootWaiters.get(key);
+        if (list === undefined)
+            return;
+        for (const waiter of list) {
+            clearTimeout(waiter.timer);
+            waiter.resolve();
+        }
+        session.rootWaiters.delete(key);
+    }
+    start(options) {
+        const { runId, roots } = options;
+        if (this.sessions.has(runId)) {
+            throw new Error(`Retry coordinator already active for run ${runId}`);
+        }
+        const activeRoots = new Map(roots);
+        const { mutationQueue, rejectPendingEnqueues } = createMutationQueue();
+        const store = options.prepared.store;
+        const terminalRoots = new Set();
+        const rootWaiters = new Map();
+        const resolveRootWaiters = (key) => {
+            const list = rootWaiters.get(key);
+            if (list === undefined)
+                return;
+            for (const waiter of list) {
+                clearTimeout(waiter.timer);
+                waiter.resolve();
+            }
+            rootWaiters.delete(key);
+        };
+        const rejectPendingRootWaiters = (reason) => {
+            for (const list of rootWaiters.values()) {
+                for (const waiter of list) {
+                    clearTimeout(waiter.timer);
+                    waiter.reject(reason);
+                }
+            }
+            rootWaiters.clear();
+        };
+        const orchestrationPromise = retryRun({
+            prepared: options.prepared,
+            retryRoots: activeRoots,
+            maxActiveStagesPerRun: options.maxActiveStagesPerRun,
+            executionMode: options.executionMode,
+            stageProcessLauncher: options.stageProcessLauncher,
+            mutationQueue,
+            onLoopTick: options.onLoopTick,
+            onRetryRootTerminal: (stageId, attempt) => {
+                const key = rootWaitKey(runId, stageId, attempt);
+                terminalRoots.add(key);
+                resolveRootWaiters(key);
+            },
+        }).finally(async () => {
+            try {
+                await syncRunStatusFromStages(store, runId);
+            }
+            catch {
+                // ignore secondary failures
+            }
+            logRetryRoots(runId, activeRoots.size, "complete");
+            rejectPendingRootWaiters(new RetryCoordinatorInactiveError(runId));
+            rejectPendingEnqueues(new RetryCoordinatorInactiveError(runId));
+            this.sessions.delete(runId);
+        });
+        this.sessions.set(runId, {
+            activeRoots,
+            orchestrationPromise,
+            mutationQueue,
+            rejectPendingEnqueues,
+            terminalRoots,
+            rootWaiters,
+            rejectPendingRootWaiters,
+        });
+        logRetryRoots(runId, activeRoots.size, "start");
+    }
+    async addRoot(runId, stageId, attempt) {
+        const session = this.sessions.get(runId);
+        if (session === undefined) {
+            throw new RetryCoordinatorInactiveError(runId);
+        }
+        if (session.activeRoots.has(stageId)) {
+            throw new DuplicateRetryRootError(runId, stageId);
+        }
+        session.activeRoots.set(stageId, attempt);
+        await session.mutationQueue.enqueue(stageId, attempt);
+        logRetryRoots(runId, session.activeRoots.size, "add");
+    }
+    async retryStage(req) {
+        const { runId, stageId, store, tracking } = req;
+        let detail;
+        try {
+            detail = await store.readRun(runId);
+        }
+        catch {
+            return { ok: false, reason: `Run not found: ${runId}`, status: 404 };
+        }
+        const recoveryActive = this.isActive(runId);
+        const eligibility = assertStageRetryEligible(detail, stageId, {
+            recoveryActive,
+        });
+        if (!eligibility.ok) {
+            return {
+                ok: false,
+                reason: eligibility.reason,
+                status: eligibility.status,
+            };
+        }
+        if (recoveryActive) {
+            if (this.getActiveRoots(runId)?.has(stageId)) {
+                return {
+                    ok: false,
+                    reason: `Retry already in progress for run ${runId} stage ${stageId}`,
+                    status: 409,
+                };
+            }
+        }
+        if (!recoveryActive && req.orchestrationConflict) {
+            return {
+                ok: false,
+                reason: `Run ${runId} already has active orchestration`,
+                status: 409,
+            };
+        }
+        const priorRunStatus = detail.status;
+        let insertedForResume = false;
+        let bumpedRunning = false;
+        try {
+            if (!recoveryActive) {
+                const tracked = await tracking.ensureResumeTracked(runId);
+                if (!tracked.ok) {
+                    return {
+                        ok: false,
+                        reason: tracked.reason,
+                        status: 409,
+                    };
+                }
+                insertedForResume = tracked.insertedForResume === true;
+                if (priorRunStatus === "failed") {
+                    await store.updateRunStatus(runId, "running");
+                    bumpedRunning = true;
+                }
+            }
+            const existingAttempts = await store.countStageAttempts(runId, stageId);
+            if (existingAttempts === 0) {
+                const snap = detail.stages.find((s) => s.stage_id === stageId);
+                if (snap &&
+                    (snap.status === "failed" || snap.status === "succeeded")) {
+                    await store.createStageExecution(runId, stageId);
+                }
+            }
+            const execution = await store.createStageExecution(runId, stageId);
+            const { meta, task, loaded, workspaceDir } = await loadRunContext(store, runId, req.cwd);
+            const prepared = {
+                task,
+                loaded,
+                run: { runId, workspaceDir },
+                agent: req.agent,
+                store,
+                cwd: req.cwd,
+                checkoutRoot: meta.checkout_root,
+                hitl: req.hitl,
+                operatorCatalog: req.operatorCatalog,
+            };
+            if (recoveryActive) {
+                await this.addRoot(runId, stageId, execution.attempt);
+            }
+            else {
+                this.start({
+                    runId,
+                    roots: new Map([[stageId, execution.attempt]]),
+                    prepared,
+                    maxActiveStagesPerRun: req.maxActiveStagesPerRun,
+                    executionMode: req.executionMode,
+                    stageProcessLauncher: req.stageProcessLauncher,
+                });
+                const orchestrationPromise = this.getOrchestrationPromise(runId);
+                if (orchestrationPromise !== undefined) {
+                    tracking.onOrchestrationStarted(runId, orchestrationPromise);
+                }
+            }
+            await this.waitForRoot(runId, stageId, store);
+            return {
+                ok: true,
+                runId,
+                stageId,
+                attemptIndex: execution.attempt,
+            };
+        }
+        catch (err) {
+            await tracking.rollbackStartTracking(runId, {
+                insertedForResume,
+                bumpedRunning,
+                priorRunStatus,
+            });
+            if (err instanceof DuplicateRetryRootError) {
+                return { ok: false, reason: err.message, status: 409 };
+            }
+            const reason = err instanceof Error ? err.message : String(err);
+            return { ok: false, reason, status: 500 };
+        }
+    }
+    async waitForRoot(runId, stageId, _store) {
+        const session = this.sessions.get(runId);
+        if (session === undefined) {
+            throw new RetryCoordinatorInactiveError(runId);
+        }
+        const expectedAttempt = session.activeRoots.get(stageId);
+        if (expectedAttempt === undefined) {
+            throw new Error(`Retry root not registered for stage ${stageId}`);
+        }
+        const key = rootWaitKey(runId, stageId, expectedAttempt);
+        if (session.terminalRoots.has(key)) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const list = session.rootWaiters.get(key);
+                if (list !== undefined) {
+                    const remaining = list.filter((waiter) => waiter.timer !== timer);
+                    if (remaining.length === 0) {
+                        session.rootWaiters.delete(key);
+                    }
+                    else {
+                        session.rootWaiters.set(key, remaining);
+                    }
+                }
+                reject(new RetryRootWaitTimeoutError(runId, stageId, expectedAttempt));
+            }, readRetryRootWaitTimeoutMs());
+            const waiter = { resolve, reject, timer };
+            const list = session.rootWaiters.get(key) ?? [];
+            list.push(waiter);
+            session.rootWaiters.set(key, list);
+        });
+    }
+}

package/dist/runtime/settingsFile.d.ts

@@ -0,0 +1,17 @@
+export declare const SETTINGS_FILE_NAME = "settings.json";
+export declare const INVALID_SLOT_COUNT_MESSAGE = "maxConcurrent must be an integer >= 1";
+export declare const INVALID_CREDENTIAL_SOURCE_MESSAGE = "credentialSource must be \"pi_home\" or \"sf_owned\"";
+export type CredentialSource = "pi_home" | "sf_owned";
+export type FactorySettings = {
+    maxConcurrent?: number;
+    credentialSource?: CredentialSource;
+};
+export declare function settingsFilePath(cwd: string): string;
+export declare function parseSlotCount(value: unknown): number | undefined;
+export declare function parseCredentialSource(value: unknown): CredentialSource | undefined;
+export declare function readFactorySettings(cwd: string): FactorySettings;
+export declare function writeFactorySettings(cwd: string, patch: FactorySettings): void;
+export declare function readMaxConcurrentFromFile(cwd: string): number | undefined;
+export declare function writeMaxConcurrentToFile(cwd: string, maxConcurrent: number): void;
+export declare function readCredentialSourceFromFile(cwd: string): CredentialSource | undefined;
+export declare function writeCredentialSourceToFile(cwd: string, credentialSource: CredentialSource): void;

package/dist/runtime/settingsFile.js

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { storeRootFor } from "../runstore/paths.js";
+export const SETTINGS_FILE_NAME = "settings.json";
+export const INVALID_SLOT_COUNT_MESSAGE = "maxConcurrent must be an integer >= 1";
+export const INVALID_CREDENTIAL_SOURCE_MESSAGE = 'credentialSource must be "pi_home" or "sf_owned"';
+export function settingsFilePath(cwd) {
+    return path.join(storeRootFor(cwd), SETTINGS_FILE_NAME);
+}
+export function parseSlotCount(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        return undefined;
+    }
+    return value;
+}
+export function parseCredentialSource(value) {
+    if (value === "pi_home" || value === "sf_owned") {
+        return value;
+    }
+    return undefined;
+}
+function readRawSettings(cwd) {
+    const filePath = settingsFilePath(cwd);
+    if (!existsSync(filePath))
+        return {};
+    try {
+        const raw = JSON.parse(readFileSync(filePath, "utf8"));
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            return {};
+        }
+        return raw;
+    }
+    catch {
+        return {};
+    }
+}
+export function readFactorySettings(cwd) {
+    const raw = readRawSettings(cwd);
+    const settings = {};
+    const maxConcurrent = parseSlotCount(raw.maxConcurrent);
+    if (maxConcurrent !== undefined) {
+        settings.maxConcurrent = maxConcurrent;
+    }
+    const credentialSource = parseCredentialSource(raw.credentialSource);
+    if (credentialSource !== undefined) {
+        settings.credentialSource = credentialSource;
+    }
+    return settings;
+}
+export function writeFactorySettings(cwd, patch) {
+    if (patch.credentialSource !== undefined &&
+        parseCredentialSource(patch.credentialSource) === undefined) {
+        throw new Error(INVALID_CREDENTIAL_SOURCE_MESSAGE);
+    }
+    if (patch.maxConcurrent !== undefined &&
+        parseSlotCount(patch.maxConcurrent) === undefined) {
+        throw new Error(INVALID_SLOT_COUNT_MESSAGE);
+    }
+    const current = readFactorySettings(cwd);
+    const next = { ...current };
+    if (patch.maxConcurrent !== undefined) {
+        next.maxConcurrent = patch.maxConcurrent;
+    }
+    if (patch.credentialSource !== undefined) {
+        next.credentialSource = patch.credentialSource;
+    }
+    const out = {};
+    if (next.maxConcurrent !== undefined) {
+        out.maxConcurrent = next.maxConcurrent;
+    }
+    if (next.credentialSource !== undefined) {
+        out.credentialSource = next.credentialSource;
+    }
+    mkdirSync(storeRootFor(cwd), { recursive: true });
+    writeFileSync(settingsFilePath(cwd), `${JSON.stringify(out, null, 2)}\n`, "utf8");
+}
+export function readMaxConcurrentFromFile(cwd) {
+    return readFactorySettings(cwd).maxConcurrent;
+}
+export function writeMaxConcurrentToFile(cwd, maxConcurrent) {
+    writeFactorySettings(cwd, { maxConcurrent });
+}
+export function readCredentialSourceFromFile(cwd) {
+    return readFactorySettings(cwd).credentialSource;
+}
+export function writeCredentialSourceToFile(cwd, credentialSource) {
+    writeFactorySettings(cwd, { credentialSource });
+}

package/dist/runtime/stageAttemptBootstrap.d.ts

@@ -0,0 +1,40 @@
+import type { AgentPort, StageHandle, StageRunInput } from "../agent/port.js";
+import type { RunStore } from "../runstore/port.js";
+import type { StageEnvelope } from "../types/envelope.js";
+import type { ResolvedPipelineDag } from "../types/pipeline.js";
+import type { StageConfig } from "../types/stage.js";
+import type { TaskFile } from "../types/task.js";
+import { type StageAttemptContext } from "./stageAttemptContext.js";
+import { type StageRoots } from "./stageRoots.js";
+export type OperatorCatalog = {
+    cwd?: string;
+    agentDir?: string;
+};
+export type StageAttemptOpenInput = {
+    agent: Pick<AgentPort, "openStage">;
+    store: RunStore;
+    runId: string;
+    stage: StageConfig;
+    task: TaskFile;
+    dag: ResolvedPipelineDag;
+    checkoutRoot?: string;
+    workspaceDir: string;
+    factoryCwd?: string;
+    attemptCtx?: StageAttemptContext;
+    operatorCatalog?: OperatorCatalog;
+    onActivity?: StageRunInput["onActivity"];
+    roots?: StageRoots;
+    resumeToken?: string;
+    workerRoots?: boolean;
+    completedEnvelopes?: Map<string, StageEnvelope>;
+};
+export type StageAttemptOpenResult = {
+    ok: true;
+    handle: StageHandle;
+    roots: StageRoots;
+    prior: StageEnvelope | null;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function openStageAttempt(input: StageAttemptOpenInput): Promise<StageAttemptOpenResult>;

package/dist/runtime/stageAttemptBootstrap.js

@@ -0,0 +1,82 @@
+import { resolveSkillByName } from "../config/listSkills.js";
+import { buildCompletedEnvelopesFromRun, resolvePriorEnvelope, } from "./envelopeRouting.js";
+import { resumeSessionFilePath } from "./stageAttemptContext.js";
+import { buildStageRoots, rootsForStageWorker, withResolvedAuthPath, } from "./stageRoots.js";
+async function resolveStageSkillForRun(stage, catalog) {
+    const name = stage.skill;
+    if (name === undefined)
+        return { ok: true };
+    if (catalog?.agentDir === undefined) {
+        return { ok: false, reason: `Skill "${name}" is not installed` };
+    }
+    const resolved = await resolveSkillByName(name, {
+        cwd: catalog.cwd ?? process.cwd(),
+        agentDir: catalog.agentDir,
+    });
+    if (!resolved) {
+        return { ok: false, reason: `Skill "${name}" is not installed` };
+    }
+    return { ok: true, skillFilePath: resolved.filePath };
+}
+async function openStageWithOperatorCatalog(agent, input, catalog) {
+    const skill = await resolveStageSkillForRun(input.stage, catalog);
+    if (!skill.ok)
+        return skill;
+    try {
+        const handle = agent.openStage({
+            ...input,
+            ...(skill.skillFilePath !== undefined
+                ? { skillFilePath: skill.skillFilePath }
+                : {}),
+        });
+        return { ok: true, handle };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function resolveAttemptRoots(input) {
+    const baseRoots = input.roots ??
+        (input.workerRoots
+            ? rootsForStageWorker(input.workspaceDir, input.stage.id, input.stage.model, input.checkoutRoot, input.attemptCtx)
+            : buildStageRoots(input.workspaceDir, input.stage.id, input.checkoutRoot, input.attemptCtx));
+    return input.factoryCwd !== undefined
+        ? withResolvedAuthPath(baseRoots, input.factoryCwd)
+        : baseRoots;
+}
+export async function openStageAttempt(input) {
+    const completedEnvelopes = input.completedEnvelopes ??
+        (await buildCompletedEnvelopesFromRun(input.store, input.runId));
+    const priorResult = await resolvePriorEnvelope({
+        dag: input.dag,
+        stageId: input.stage.id,
+        completedEnvelopes,
+        store: input.store,
+        runId: input.runId,
+    });
+    if (!priorResult.ok)
+        return priorResult;
+    const roots = resolveAttemptRoots(input);
+    const attempt = input.attemptCtx?.attempt ?? 1;
+    const resumeToken = input.resumeToken ??
+        resumeSessionFilePath(input.workspaceDir, input.stage.id, attempt);
+    const opened = await openStageWithOperatorCatalog(input.agent, {
+        roots,
+        stage: input.stage,
+        task: input.task,
+        priorEnvelope: priorResult.prior,
+        resumeToken,
+        onActivity: input.onActivity,
+    }, input.operatorCatalog);
+    if (!opened.ok)
+        return opened;
+    return {
+        ok: true,
+        handle: opened.handle,
+        roots,
+        prior: priorResult.prior,
+    };
+}

package/dist/runtime/stageAttemptContext.d.ts

@@ -0,0 +1,11 @@
+export type StageAttemptContext = {
+    readonly attempt: number;
+    eventOptions(): {
+        attempt: number;
+    } | undefined;
+    sessionPath(workspaceDir: string, stageId: string): string;
+    agentDirPath(workspaceDir: string, stageId: string): string;
+};
+export declare function attemptContext(attempt: number): StageAttemptContext;
+export declare function noAttemptContext(): StageAttemptContext;
+export declare function resumeSessionFilePath(workspaceDir: string, stageId: string, attempt: number): string;