stageflow 0.23.0 → 0.27.0

package/dist/runtime/repositoryMaterialize.d.ts

@@ -0,0 +1,47 @@
+import type { RunMeta, RunStore } from "../runstore/port.js";
+import type { TaskFile } from "../types/task.js";
+import type { WorkspaceBinding } from "./workspaceBinding.js";
+export type StartFailureCode = "busy_capacity" | "busy_checkout" | "busy_caller_quota" | "repository_auth_failed" | "repository_not_found" | "ref_not_found" | "repository_fetch_failed" | "worktree_create_failed" | "git_missing" | "insufficient_disk" | "disk_check_failed" | "pinned_sha_unavailable" | "invalid_run_branch" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid" | "task.invalid_shape" | "task.load_error" | "start.token_rejected" | "inline_pipeline_too_large" | "skills_invalid_name" | "skills_invalid_path" | "skills_missing_skill_md" | "skills_payload_too_large" | "missing_tool" | "tool_version_mismatch" | "unknown_version" | "secret_unavailable" | "unresolved_var" | "shutting_down" | "autostart_disabled" | "ensure_project_not_allowed" | "claude_as_root";
+export type MaterializedBinding = {
+    runId: string;
+    checkoutRoot?: string;
+    repository?: string;
+    ref?: string;
+    resolvedSha?: string;
+    runBranch?: string;
+};
+export type DerivedBindingKind = "repository" | "checkout" | "unbound";
+export declare function derivedBindingKindFromMeta(meta: RunMeta): DerivedBindingKind;
+export declare function worktreePathForRun(runId: string): string;
+export declare function resolveRunBranchTemplate(task: TaskFile): string;
+export declare class StartLinkError extends Error {
+    readonly code: StartFailureCode;
+    readonly status: number;
+    readonly stderr?: string;
+    constructor(message: string, options: {
+        code: StartFailureCode;
+        status: number;
+        stderr?: string;
+    });
+}
+export declare function throwMappedGitError(err: unknown, phase: "fetch" | "resolve" | "worktree"): never;
+export type MaterializeOptions = {
+    runId: string;
+    task: TaskFile;
+    binding: WorkspaceBinding;
+    checkoutRoot?: string;
+    pinned?: {
+        ref: string;
+        resolvedSha: string;
+    };
+};
+export type ReclaimWorkspaceBindingOptions = {
+    /** When true, remove the worktree but leave `run_branch` (SLIM must keep the branch). */
+    keepRunBranch?: boolean;
+};
+export declare function reclaimWorkspaceBinding(meta: RunMeta, options?: ReclaimWorkspaceBindingOptions): Promise<void>;
+export declare function reclaimWorkspaceOnRunSucceeded(store: RunStore, runId: string): Promise<void>;
+export declare function materializeWorkspaceBinding(options: MaterializeOptions): Promise<{
+    materialized: MaterializedBinding;
+    rollback: () => Promise<void>;
+}>;

package/dist/runtime/repositoryMaterialize.js

@@ -0,0 +1,235 @@
+import { existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { bareCachePath, ensureBareCache, } from "../git/cache.js";
+import { GitError } from "../git/errors.js";
+import { catFileCommit, checkRefFormat, deleteBranch, resolveRef, revParse, worktreeAdd, worktreePrune, worktreeRemove, } from "../git/operations.js";
+import { ensureGlobalHome, globalStageflowHome } from "../project/globalHome.js";
+const DEFAULT_BRANCH_TEMPLATE = "stageflow/run-<runId>";
+const FULL_SHA_RE = /^[0-9a-f]{40}$/i;
+export function derivedBindingKindFromMeta(meta) {
+    if (meta.repository != null && meta.repository !== "") {
+        return "repository";
+    }
+    if (meta.checkout_root != null && meta.checkout_root !== "") {
+        return "checkout";
+    }
+    return "unbound";
+}
+export function worktreePathForRun(runId) {
+    return path.join(globalStageflowHome(), "worktrees", runId);
+}
+function renderBranchTemplate(template, runId, taskId) {
+    return template.replaceAll("<runId>", runId).replaceAll("<taskId>", taskId);
+}
+export function resolveRunBranchTemplate(task) {
+    const fromTask = task.run_branch_template?.trim();
+    if (fromTask)
+        return fromTask;
+    const fromEnv = process.env.STAGEFLOW_RUN_BRANCH_TEMPLATE?.trim();
+    if (fromEnv)
+        return fromEnv;
+    return DEFAULT_BRANCH_TEMPLATE;
+}
+export class StartLinkError extends Error {
+    code;
+    status;
+    stderr;
+    constructor(message, options) {
+        super(message);
+        this.name = "StartLinkError";
+        this.code = options.code;
+        this.status = options.status;
+        this.stderr = options.stderr;
+    }
+}
+function mapGitCode(code, phase) {
+    switch (code) {
+        case "auth_failed":
+            return { code: "repository_auth_failed", status: 401 };
+        case "repo_not_found":
+            return { code: "repository_not_found", status: 404 };
+        case "ref_not_found":
+            return { code: "ref_not_found", status: 404 };
+        case "network":
+        case "timeout":
+            return { code: "repository_fetch_failed", status: 502 };
+        case "disk_full":
+            return { code: "insufficient_disk", status: 507 };
+        case "git_missing":
+            return { code: "git_missing", status: 500 };
+        default:
+            if (phase === "worktree") {
+                return { code: "worktree_create_failed", status: 500 };
+            }
+            if (phase === "resolve") {
+                return { code: "ref_not_found", status: 404 };
+            }
+            return { code: "repository_fetch_failed", status: 502 };
+    }
+}
+export function throwMappedGitError(err, phase) {
+    if (err instanceof StartLinkError)
+        throw err;
+    if (err instanceof GitError) {
+        const mapped = mapGitCode(err.code, phase);
+        throw new StartLinkError(err.message, {
+            code: mapped.code,
+            status: mapped.status,
+            stderr: err.stderr,
+        });
+    }
+    throw err;
+}
+async function runRollbackThunks(thunks) {
+    for (const thunk of thunks) {
+        try {
+            await thunk();
+        }
+        catch (cleanupErr) {
+            console.error(`repository link rollback failed: ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`);
+        }
+    }
+}
+export async function reclaimWorkspaceBinding(meta, options) {
+    if (derivedBindingKindFromMeta(meta) !== "repository") {
+        return;
+    }
+    const cachePath = bareCachePath(meta.repository);
+    try {
+        await worktreeRemove(cachePath, meta.checkout_root);
+    }
+    catch {
+    }
+    try {
+        await worktreePrune(cachePath);
+    }
+    catch {
+    }
+    if (options?.keepRunBranch) {
+        return;
+    }
+    try {
+        await deleteBranch(cachePath, meta.run_branch);
+    }
+    catch {
+    }
+}
+export async function reclaimWorkspaceOnRunSucceeded(store, runId) {
+    try {
+        const meta = await store.readRunMeta(runId);
+        await reclaimWorkspaceBinding(meta, { keepRunBranch: true });
+    }
+    catch (err) {
+        console.error(`reclaimWorkspaceOnRunSucceeded: failed for ${runId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export async function materializeWorkspaceBinding(options) {
+    const { runId, task, binding } = options;
+    const rollbacks = [];
+    const rollback = async () => runRollbackThunks(rollbacks);
+    if (binding.kind === "unbound") {
+        return { materialized: { runId }, rollback };
+    }
+    if (binding.kind === "checkout") {
+        const checkoutRoot = options.checkoutRoot;
+        if (checkoutRoot === undefined) {
+            throw new StartLinkError("Checkout path is required", {
+                code: "worktree_create_failed",
+                status: 500,
+            });
+        }
+        let resolvedSha;
+        if (options.pinned?.resolvedSha) {
+            resolvedSha = options.pinned.resolvedSha;
+        }
+        else {
+            try {
+                const head = await revParse(checkoutRoot, ["HEAD"]);
+                if (FULL_SHA_RE.test(head)) {
+                    resolvedSha = head;
+                }
+            }
+            catch {
+                // non-git path checkouts leave resolved_sha null (KD6/KD7)
+            }
+        }
+        return {
+            materialized: {
+                runId,
+                checkoutRoot,
+                ...(resolvedSha !== undefined ? { resolvedSha } : {}),
+            },
+            rollback,
+        };
+    }
+    const repository = binding.repository;
+    const refToRecord = options.pinned?.ref ?? binding.ref;
+    let resolvedSha;
+    let cachePath;
+    if (options.pinned) {
+        cachePath = bareCachePath(repository);
+        const present = existsSync(cachePath) &&
+            (await catFileCommit(cachePath, options.pinned.resolvedSha));
+        if (!present) {
+            throw new StartLinkError(`Pinned SHA is not available in the local cache: ${options.pinned.resolvedSha}`, { code: "pinned_sha_unavailable", status: 404 });
+        }
+        resolvedSha = options.pinned.resolvedSha;
+    }
+    else {
+        try {
+            const ensured = await ensureBareCache(repository, binding.ref);
+            cachePath = ensured.cachePath;
+        }
+        catch (err) {
+            throwMappedGitError(err, "fetch");
+        }
+        try {
+            resolvedSha = await resolveRef(cachePath, binding.ref);
+        }
+        catch (err) {
+            throwMappedGitError(err, "resolve");
+        }
+    }
+    const template = resolveRunBranchTemplate(task);
+    const runBranch = renderBranchTemplate(template, runId, task.id);
+    const branchOk = await checkRefFormat(runBranch);
+    if (!branchOk) {
+        throw new StartLinkError(`Invalid run branch name from template: ${runBranch}`, { code: "invalid_run_branch", status: 400 });
+    }
+    ensureGlobalHome();
+    const checkoutRoot = worktreePathForRun(runId);
+    mkdirSync(path.dirname(checkoutRoot), { recursive: true });
+    try {
+        await worktreeAdd(cachePath, {
+            worktreePath: checkoutRoot,
+            branch: runBranch,
+            startPoint: resolvedSha,
+        });
+    }
+    catch (err) {
+        throwMappedGitError(err, "worktree");
+    }
+    rollbacks.push(async () => {
+        try {
+            await worktreeRemove(cachePath, checkoutRoot);
+        }
+        catch {
+            // prune recovers admin state when the dir is already gone
+        }
+        await worktreePrune(cachePath);
+    });
+    rollbacks.push(async () => {
+        await deleteBranch(cachePath, runBranch);
+    });
+    return {
+        materialized: {
+            runId,
+            checkoutRoot,
+            repository,
+            ref: refToRecord,
+            resolvedSha,
+            runBranch,
+        },
+        rollback,
+    };
+}

package/dist/runtime/resolveEnvelopeRef.d.ts

@@ -0,0 +1,30 @@
+import { type StoreLookupKind } from "../server/operatorResults.js";
+import type { RunStore } from "../runstore/port.js";
+import type { TaskFile } from "../types/task.js";
+export type EnvelopeRefInput = {
+    runId: string;
+    stageId: string;
+    attempt?: number;
+};
+type EnvelopeRefStore = Pick<RunStore, "readRunMeta" | "readRun" | "readEnvelope">;
+/** Carries enough to map onto either MCP's textResult shape or an A2aApplicationError. */
+export declare class EnvelopeRefError extends Error {
+    readonly status: number;
+    readonly kind: StoreLookupKind;
+    constructor(message: string, status: number, kind: StoreLookupKind);
+}
+/**
+ * Resolves one or more Envelope References (ADR-0002) into a TaskFile for
+ * the next standalone stage call — shared by the MCP run_stage tool and the
+ * A2A run_stage operation so this resolution logic exists in exactly one
+ * place (it was duplicated between them once already; see the reuse finding
+ * from this feature's code review).
+ *
+ * A single ref keeps today's exact shape: goal = its summary, input = its
+ * payload verbatim. Multiple refs namespace each resolved payload under its
+ * stageId (disambiguated by runId only if two refs share a stageId), so a
+ * stage author addresses each source by name in their own io.input.schema
+ * instead of one silently overwriting another on a key collision.
+ */
+export declare function resolveEnvelopeRefsToTask(store: EnvelopeRefStore, refs: EnvelopeRefInput | EnvelopeRefInput[], checkout?: string): Promise<TaskFile>;
+export {};

package/dist/runtime/resolveEnvelopeRef.js

@@ -0,0 +1,79 @@
+import { mapStoreLookupError } from "../server/operatorResults.js";
+/** Carries enough to map onto either MCP's textResult shape or an A2aApplicationError. */
+export class EnvelopeRefError extends Error {
+    status;
+    kind;
+    constructor(message, status, kind) {
+        super(message);
+        this.status = status;
+        this.kind = kind;
+    }
+}
+async function resolveOne(store, ref) {
+    try {
+        await store.readRunMeta(ref.runId);
+    }
+    catch (err) {
+        const mapped = mapStoreLookupError(err, { policy: "run" });
+        throw new EnvelopeRefError(mapped.error, mapped.status, mapped.kind);
+    }
+    try {
+        const detail = await store.readRun(ref.runId);
+        if (!detail.stages.some((s) => s.stage_id === ref.stageId)) {
+            throw new EnvelopeRefError(`Stage not found: ${ref.stageId}`, 404, "not_found");
+        }
+        return await store.readEnvelope(ref.runId, ref.stageId, ref.attempt);
+    }
+    catch (err) {
+        if (err instanceof EnvelopeRefError)
+            throw err;
+        const mapped = mapStoreLookupError(err, { policy: "envelope" });
+        throw new EnvelopeRefError(mapped.error, mapped.status, mapped.kind);
+    }
+}
+/**
+ * Resolves one or more Envelope References (ADR-0002) into a TaskFile for
+ * the next standalone stage call — shared by the MCP run_stage tool and the
+ * A2A run_stage operation so this resolution logic exists in exactly one
+ * place (it was duplicated between them once already; see the reuse finding
+ * from this feature's code review).
+ *
+ * A single ref keeps today's exact shape: goal = its summary, input = its
+ * payload verbatim. Multiple refs namespace each resolved payload under its
+ * stageId (disambiguated by runId only if two refs share a stageId), so a
+ * stage author addresses each source by name in their own io.input.schema
+ * instead of one silently overwriting another on a key collision.
+ */
+export async function resolveEnvelopeRefsToTask(store, refs, checkout) {
+    const list = Array.isArray(refs) ? refs : [refs];
+    const resolved = [];
+    for (const ref of list) {
+        resolved.push({ ref, envelope: await resolveOne(store, ref) });
+    }
+    if (resolved.length === 1) {
+        const { ref, envelope } = resolved[0];
+        return {
+            id: `ref-${ref.runId}-${ref.stageId}`,
+            goal: envelope.summary,
+            input: envelope.payload ?? {},
+            ...(checkout ? { checkout } : {}),
+        };
+    }
+    const usedKeys = new Set();
+    const input = {};
+    const summaryLines = [];
+    for (const { ref, envelope } of resolved) {
+        let key = ref.stageId;
+        if (usedKeys.has(key))
+            key = `${ref.stageId}:${ref.runId}`;
+        usedKeys.add(key);
+        input[key] = envelope.payload ?? {};
+        summaryLines.push(`${key}: ${envelope.summary}`);
+    }
+    return {
+        id: `ref-${list.map((r) => r.stageId).join("+")}`,
+        goal: summaryLines.join("\n"),
+        input,
+        ...(checkout ? { checkout } : {}),
+    };
+}

package/dist/runtime/resumeTimedOut.d.ts

@@ -17,7 +17,7 @@ export type ResumeTimedOutContext = {
     maxActiveStagesPerRun: number;
     operatorCatalog?: OperatorCatalog;
 };
-export declare function assertTimedOutStageEligible(status: string, events: ReadonlyArray<{
+export declare function assertResumableStage(status: string, events: ReadonlyArray<{
     event: string;
     reason?: string;
 }>): {

package/dist/runtime/resumeTimedOut.js

@@ -11,11 +11,14 @@ import { openStageAttempt, } from "./stageAttemptBootstrap.js";
 import { buildStageRoots, withResolvedAuthPath } from "./stageRoots.js";
 import { isStageTimeoutReason, lastFailedReason, } from "../agent/stageTimeout.js";
 import { deriveExecutionPatchFromEvent } from "../runstore/stageExecution.js";
-export function assertTimedOutStageEligible(status, events) {
+export function assertResumableStage(status, events) {
+    if (status === "interrupted") {
+        return { ok: true };
+    }
     if (status !== "failed") {
         return {
             ok: false,
-            reason: `Stage is not timed out (status=${status})`,
+            reason: `Stage is not resumable (status=${status})`,
             status: 409,
         };
     }

package/dist/runtime/runChangeBus.js

@@ -49,6 +49,13 @@ export function wrapRunStoreWithChangeBus(store, bus) {
         await store.updateRunStatus(runId, status);
         bus.emit({ runId, kind: "status" });
     };
+    const tryUpdateRunStatus = async (runId, status, expectedStatus) => {
+        const updated = await store.tryUpdateRunStatus(runId, status, expectedStatus);
+        if (updated) {
+            bus.emit({ runId, kind: "status" });
+        }
+        return updated;
+    };
     const appendStageEvent = async (runId, stageId, event, options) => {
         await store.appendStageEvent(runId, stageId, event, options);
         if (event.event === "waiting_for_input" || event.event === "resumed") {
@@ -66,6 +73,8 @@ export function wrapRunStoreWithChangeBus(store, bus) {
                 return createRun;
             if (prop === "updateRunStatus")
                 return updateRunStatus;
+            if (prop === "tryUpdateRunStatus")
+                return tryUpdateRunStatus;
             if (prop === "appendStageEvent")
                 return appendStageEvent;
             const cached = boundCache.get(prop);

package/dist/runtime/runDeletion.d.ts

@@ -0,0 +1,7 @@
+import type { A2aStore } from "../a2a/store.js";
+import type { RunStore } from "../runstore/port.js";
+/**
+ * Hard-delete a run across A2A, workspace, worktree/branch, then store rows last.
+ * Filesystem/git step failures are logged and do not abort the sequence (R10).
+ */
+export declare function deleteRunEverywhere(store: RunStore, a2aStore: A2aStore, runId: string): Promise<void>;

package/dist/runtime/runDeletion.js

@@ -0,0 +1,37 @@
+import { rm } from "node:fs/promises";
+import { reclaimWorkspaceBinding } from "./repositoryMaterialize.js";
+/**
+ * Hard-delete a run across A2A, workspace, worktree/branch, then store rows last.
+ * Filesystem/git step failures are logged and do not abort the sequence (R10).
+ */
+export async function deleteRunEverywhere(store, a2aStore, runId) {
+    try {
+        await a2aStore.deleteByRunId(runId);
+    }
+    catch (err) {
+        console.error(`deleteRunEverywhere: A2A cleanup failed for ${runId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let meta;
+    try {
+        meta = await store.readRunMeta(runId);
+    }
+    catch {
+        meta = undefined;
+    }
+    const workspaceDir = store.getWorkspaceDir(runId);
+    try {
+        await rm(workspaceDir, { recursive: true, force: true });
+    }
+    catch (err) {
+        console.error(`deleteRunEverywhere: workspace rm failed for ${runId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (meta !== undefined) {
+        try {
+            await reclaimWorkspaceBinding(meta);
+        }
+        catch (err) {
+            console.error(`deleteRunEverywhere: reclaimWorkspaceBinding failed for ${runId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    await store.deleteRun(runId);
+}