stageflow 0.23.0 → 0.27.0

package/dist/runtime/runManager.d.ts

@@ -1,31 +1,50 @@
+import { type RunSubmission } from "../runstore/submission.js";
 import type { AgentPort, OpaqueAnswer } from "../agent/port.js";
 import type { InlinePipelineDefinition } from "../types/pipeline.js";
+import { type DiskBreakdown, type FreeSpaceReader } from "../runstore/diskUsage.js";
 import { type RunStore } from "../runstore/port.js";
 import type { TaskFile } from "../types/task.js";
 import { type PipelineRunResult } from "./pipelineRunner.js";
+import { type SkillsPayload } from "./runSkills.js";
 import { type FeedbackLoopDecisionKind } from "./feedbackLoopDecision.js";
 import { type RetryStageResult } from "./runRetryCoordinator.js";
 import { type StageExecutionMode } from "./stageConcurrency.js";
 import { StageProcessLauncher } from "./stageProcessLauncher.js";
 import { StageHitlController, type DeliverAnswerResult, type HitlSeams } from "./stageHitl.js";
 import { type StartTaskInput } from "./taskInput.js";
+import { type RetentionSweepReport, type RunRetentionSweepOptions } from "./runRetentionSweep.js";
+import type { A2aStore } from "../a2a/store.js";
 import type { OperatorCatalog } from "./stageAttemptBootstrap.js";
-export type BusyCode = "busy_capacity" | "busy_checkout";
+import { type StartFailureCode } from "./repositoryMaterialize.js";
+export type BusyCode = "busy_capacity" | "busy_checkout" | "busy_caller_quota";
+export type { StartFailureCode } from "./repositoryMaterialize.js";
 export type StartRunResult = {
     ok: true;
     runId: string;
     done: Promise<PipelineRunResult>;
+    queued?: boolean;
+    queuePosition?: number;
+    /** Present when queued because the caller hit its concurrency quota. */
+    queuedCode?: "busy_caller_quota";
 } | {
     ok: false;
     reason: string;
     status?: number;
-    code?: BusyCode;
+    code?: StartFailureCode;
     activeCount?: number;
     maxConcurrent?: number;
     activeRunIds?: string[];
+    scope?: "global" | "project" | "caller";
+    project_root?: string;
+    caller_id?: string;
     conflictingRunId?: string;
     conflictingCheckout?: string;
+    freeBytes?: number;
+    minFreeBytes?: number;
+    stderr?: string;
 };
+export declare const PROJECT_ROOT_UNAVAILABLE_REASON = "project_root_unavailable";
+export declare const INSUFFICIENT_DISK_CANCEL_REASON = "insufficient_disk";
 export type CapacityHealth = {
     ok: true;
     activeRunIds: string[];
@@ -34,7 +53,36 @@ export type CapacityHealth = {
     slotsAvailable: number;
     activeStageProcesses: number;
     maxActiveStageProcesses: number | null;
+    disk?: DiskBreakdown;
+    stage_env_passthrough?: boolean;
+    proxy?: Record<string, unknown>;
+    container?: {
+        max_old_space_size_mb: number;
+        max_active_stage_processes: number;
+        memory_limit_bytes: number | null;
+        source: string;
+    };
+    cache?: {
+        root: string;
+    };
 };
+export type StartRunOnceResult = {
+    ok: true;
+    runId: string;
+    /** False only for the caller whose submission durably created this run for the first time. */
+    reused: boolean;
+    /**
+     * Present when this call observed the run being launched in this process — either it launched
+     * the run itself, or it piggybacked on another in-flight call to the same submission key while
+     * that launch was still starting. Absent when the submission was already durably committed by
+     * an earlier, separate call: `reused: true` does not by itself imply `done` is absent, since a
+     * piggybacked call is also `reused: true`. Callers that need completion regardless of which case
+     * they hit must still fall back to polling run status by `runId`.
+     */
+    done?: Promise<PipelineRunResult>;
+} | Extract<StartRunResult, {
+    ok: false;
+}>;
 export type { DeliverAnswerResult };
 export type { RetryStageResult };
 export type AbandonStageResult = {
@@ -46,6 +94,32 @@ export type AbandonStageResult = {
     reason: string;
     status?: number;
 };
+export type CancelRunResult = {
+    ok: true;
+    runId: string;
+} | {
+    ok: false;
+    reason: string;
+    status?: number;
+};
+export type DeleteRunChannel = "mcp" | "rest" | "cli";
+export type DeleteRunResult = {
+    ok: true;
+    runId: string;
+} | {
+    ok: false;
+    reason: string;
+    status?: number;
+};
+export type GcRunsChannel = "mcp" | "rest" | "cli" | "periodic";
+export type GcRunsResult = ({
+    ok: true;
+} & RetentionSweepReport) | {
+    ok: false;
+    reason: string;
+    status?: number;
+};
+export declare const FORCE_DELETE_CANCEL_REASON = "delete_run: force";
 export type DecideFeedbackLoopResult = {
     ok: true;
     effect: "extended" | "continued" | "abandoned";
@@ -64,20 +138,34 @@ export type StopManualRecoveryResult = {
     reason: string;
     status?: number;
 };
+export declare const STAGEFLOW_AUTO_RESUME_INTERRUPTED = "STAGEFLOW_AUTO_RESUME_INTERRUPTED";
+export declare const STAGEFLOW_MAX_AUTO_RESUMES = "STAGEFLOW_MAX_AUTO_RESUMES";
+export declare function isAutoResumeInterruptedEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function parseMaxAutoResumes(env?: NodeJS.ProcessEnv): number;
 export declare class RunManager {
     private readonly options;
+    private readonly submissionsInFlight;
     private readonly active;
+    private readonly schedulingHalts;
     private readonly checkoutLeases;
     private readonly provisionalIds;
+    private readonly admissionQueue;
+    private readonly pendingQueuedStarts;
+    private readonly queuedDone;
+    private admissionDrainInFlight;
     private readonly resumeInFlight;
     private readonly retryInFlight;
     private readonly retryStartOwner;
     private readonly retryStartWaiters;
     private trackingGeneration;
     private maxConcurrent;
+    private readonly maxQueued;
+    private readonly maxConcurrentPerProject;
+    private readonly callerQuotas;
     private readonly maxActiveStagesPerRun;
     private readonly executionMode;
     private readonly stageProcessLauncher;
+    private a2aStore;
     private readonly hitl;
     private readonly attachedWaiting;
     private readonly retryCoordinator;
@@ -85,6 +173,7 @@ export declare class RunManager {
     private readonly cwd;
     private readonly projectRoot;
     private readonly isGitProject;
+    private acceptingWork;
     constructor(options: {
         agent: AgentPort;
         store: RunStore;
@@ -94,15 +183,47 @@ export declare class RunManager {
         operatorCatalog?: OperatorCatalog;
         seams?: HitlSeams;
         maxConcurrent?: number;
+        maxQueued?: number;
+        maxConcurrentPerProject?: number;
+        /** caller_id → max concurrent active runs for that caller. */
+        callerQuotas?: Record<string, number>;
         maxActiveStagesPerRun?: number;
         executionMode?: StageExecutionMode;
         stageProcessLauncher?: StageProcessLauncher;
+        a2aStore?: A2aStore;
+        knownWritableProjectRoots?: () => Iterable<string> | Promise<Iterable<string>>;
+        freeSpaceReader?: FreeSpaceReader;
+        /** Test-only: await before materialize when activating a queued run. */
+        onBeforeQueuedMaterialize?: (runId: string) => void | Promise<void>;
     });
     getMaxConcurrent(): number;
     setMaxConcurrent(n: number): CapacityHealth;
     getActiveCount(): number;
+    stopAcceptingWork(): void;
+    isAcceptingWork(): boolean;
+    drainActiveStages(options: {
+        deadlineMs: number;
+        isEscalated?: () => boolean;
+    }): Promise<{
+        forced: boolean;
+    }>;
     getActiveRunIds(): string[];
     getHealth(): CapacityHealth;
+    getPerProjectCapacity(): {
+        maxConcurrent: number | undefined;
+        projects: Array<{
+            project_root: string;
+            activeCount: number;
+            maxConcurrent: number | undefined;
+        }>;
+    };
+    private countActiveForProject;
+    private countActiveForCaller;
+    private callerQuotaLimit;
+    /** Capacity plus on-demand durable-root disk breakdown (KTD16). */
+    getHealthWithDisk(): Promise<CapacityHealth>;
+    /** Refresh cached `disk_bytes` for one run after a terminal transition. */
+    refreshRunDiskBytes(runId: string): Promise<void>;
     getHitlController(): StageHitlController;
     /**
      * KTD7/KTD8: discover waiting stages from the store; leave waiting; do not
@@ -121,10 +242,40 @@ export declare class RunManager {
             reason: string;
         }>;
     }>;
+    autoResumeInterruptedStages(): Promise<{
+        resumed: Array<{
+            runId: string;
+            stageId: string;
+        }>;
+        capped: Array<{
+            runId: string;
+            stageId: string;
+        }>;
+        skipped: Array<{
+            runId: string;
+            stageId: string;
+            reason: string;
+        }>;
+    }>;
     resumeStalledSchedules(): Promise<Array<{
         runId: string;
     }>>;
+    /** Rebuild in-memory admission queue from persisted `queued` rows (R27). */
+    reenqueuePersistedQueuedRuns(): Promise<void>;
     abandonStage(runId: string, stageId: string): Promise<AbandonStageResult>;
+    cancelRun(runId: string, reason: string): Promise<CancelRunResult>;
+    setA2aStore(store: A2aStore): void;
+    deleteRun(runId: string, options?: {
+        force?: boolean;
+        channel: DeleteRunChannel;
+    }): Promise<DeleteRunResult>;
+    gcRuns(options?: {
+        execute?: boolean;
+        channel?: GcRunsChannel;
+    } & Pick<RunRetentionSweepOptions, "now" | "windows" | "env" | "artifactMaxBytes" | "bareCacheTtlMs">): Promise<GcRunsResult>;
+    private waitForPromise;
+    startRunOnce(input: Parameters<RunManager["startRun"]>[0], submission: RunSubmission): Promise<StartRunOnceResult>;
+    private startSubmittedRun;
     startRun(input: StartTaskInput & {
         pipeline: string | InlinePipelineDefinition;
         task?: string | TaskFile;
@@ -133,10 +284,24 @@ export declare class RunManager {
         gitSha?: string;
         ciPrUrl?: string;
         ciJobUrl?: string;
+        /**
+         * Absolute store-key project root from the wire (registered path or
+         * seeded-mapped absolute). When set, persisted as run project_root;
+         * Host boot / findProjectRoot are not used to override it.
+         */
+        projectRoot?: string;
+        /** Attribution from auth only — never from request body/query. */
+        callerId?: string | null;
+        skills?: SkillsPayload;
+    }, submission?: RunSubmission): Promise<StartRunResult>;
+    rerun(runId: string, options?: {
+        pinned?: boolean;
+        callerId?: string | null;
     }): Promise<StartRunResult>;
-    rerun(runId: string): Promise<StartRunResult>;
     retryStage(runId: string, stageId: string): Promise<RetryStageResult>;
-    resumeTimedOutStage(runId: string, stageId: string): Promise<RetryStageResult>;
+    resumeTimedOutStage(runId: string, stageId: string, options?: {
+        source?: "explicit" | "auto";
+    }): Promise<RetryStageResult>;
     recoverManualStage(runId: string, stageId: string, guidance?: string): Promise<RetryStageResult>;
     recoverManualStageUntilStop(runId: string, stageId: string, guidance?: string): Promise<{
         ok: true;
@@ -182,7 +347,16 @@ export declare class RunManager {
     private reconstructAndContinue;
     private reserveAndStartPipeline;
     private busyFailure;
+    private insufficientDiskFailure;
+    private checkDiskFloorAdmission;
+    private isProjectRootAvailable;
+    private tryAdmitOrEnqueue;
     private tryReserve;
+    private ensureQueuedDone;
+    private resolveQueuedDone;
+    private attachQueuedDone;
+    private drainAdmissionQueue;
+    private startDequeuedAdmission;
     private clearReservation;
     private track;
     private tryResumeStalledSchedule;
@@ -196,4 +370,5 @@ export declare class RunManager {
     private quarantineAttachRun;
     private untrackIfGeneration;
     private removeActiveEntry;
+    private ensureSchedulingHalt;
 }