stageflow 0.31.0 → 0.33.0

package/dist/hosted/sequencer.d.ts

@@ -0,0 +1,28 @@
+import { type HostedEventBody, type HostedEventSink, type HostedRunContext } from "./types.js";
+export declare class HostedEventSequencer {
+    private readonly sink;
+    private readonly context;
+    private readonly timeoutMs;
+    private readonly attempts;
+    private chain;
+    private held;
+    private holding;
+    private sequence;
+    private runId;
+    failed: boolean;
+    failure?: {
+        eventType: string;
+        sequence: number;
+        message: string;
+    };
+    constructor(sink: HostedEventSink, context: HostedRunContext, timeoutMs: number, attempts: number);
+    setRunId(runId: string): void;
+    emit(body: HostedEventBody): Promise<void>;
+    emitNow(body: HostedEventBody): Promise<void>;
+    release(): void;
+    rejectHeld(error: unknown): void;
+    private enqueue;
+    private deliver;
+    private envelope;
+    private failureError;
+}

package/dist/hosted/sequencer.js

@@ -0,0 +1,129 @@
+import { redactString } from "../logging/redact.js";
+import { HostedRuntimeError } from "./errors.js";
+import { HOSTED_EVENT_SCHEMA_VERSION, } from "./types.js";
+export class HostedEventSequencer {
+    sink;
+    context;
+    timeoutMs;
+    attempts;
+    chain = Promise.resolve();
+    held = [];
+    holding = true;
+    sequence = 0;
+    runId = "";
+    failed = false;
+    failure;
+    constructor(sink, context, timeoutMs, attempts) {
+        this.sink = sink;
+        this.context = context;
+        this.timeoutMs = timeoutMs;
+        this.attempts = attempts;
+    }
+    setRunId(runId) {
+        this.runId = runId;
+    }
+    emit(body) {
+        if (this.failed)
+            return Promise.reject(this.failureError());
+        if (this.holding) {
+            return new Promise((resolve, reject) => {
+                this.held.push({ body, resolve, reject });
+            });
+        }
+        return this.enqueue(body);
+    }
+    emitNow(body) {
+        if (this.failed)
+            return Promise.reject(this.failureError());
+        return this.enqueue(body);
+    }
+    release() {
+        if (!this.holding)
+            return;
+        this.holding = false;
+        const queued = this.held;
+        this.held = [];
+        for (const item of queued) {
+            const run = this.chain.then(() => this.deliver(item.body));
+            this.chain = run.then(() => undefined, () => undefined);
+            void run.then(item.resolve, item.reject);
+        }
+    }
+    rejectHeld(error) {
+        this.holding = false;
+        const queued = this.held;
+        this.held = [];
+        for (const item of queued)
+            item.reject(error);
+    }
+    enqueue(body) {
+        const run = this.chain.then(() => this.deliver(body));
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async deliver(body) {
+        if (this.failed)
+            throw this.failureError();
+        const sequence = ++this.sequence;
+        const event = this.envelope(body, sequence);
+        let last;
+        for (let attempt = 1; attempt <= this.attempts; attempt += 1) {
+            try {
+                await withTimeout(this.sink.onEvent(event), this.timeoutMs);
+                return;
+            }
+            catch (error) {
+                last = error;
+            }
+        }
+        const message = redactString(errorMessage(last));
+        this.failed = true;
+        this.failure = { eventType: event.type, sequence, message };
+        throw this.failureError();
+    }
+    envelope(body, sequence) {
+        return {
+            schemaVersion: HOSTED_EVENT_SCHEMA_VERSION,
+            eventId: `${this.context.externalAttemptId}:${sequence}`,
+            sequence,
+            occurredAt: new Date().toISOString(),
+            runId: this.runId,
+            externalRunId: this.context.externalRunId,
+            externalAttemptId: this.context.externalAttemptId,
+            packageRevision: this.context.packageRevision,
+            ...(this.context.attributes !== undefined
+                ? { attributes: this.context.attributes }
+                : {}),
+            ...body,
+        };
+    }
+    failureError() {
+        const failure = this.failure;
+        return new HostedRuntimeError(failure?.message ?? "hosted event sink failed", {
+            code: "event_sink_failed",
+            externalRunId: this.context.externalRunId,
+            externalAttemptId: this.context.externalAttemptId,
+            ...(this.runId !== "" ? { runId: this.runId } : {}),
+            ...(failure !== undefined
+                ? { eventType: failure.eventType, sequence: failure.sequence }
+                : {}),
+        });
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function withTimeout(work, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error("hosted event sink timed out"));
+        }, timeoutMs);
+        work.then(() => {
+            clearTimeout(timer);
+            resolve();
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}

package/dist/hosted/translate.d.ts

@@ -0,0 +1,3 @@
+import type { StageLogLine } from "../agent/activity.js";
+import type { HostedEventBody } from "./types.js";
+export declare function translateStageEvent(stageId: string, event: StageLogLine, attempt: number): HostedEventBody | undefined;

package/dist/hosted/translate.js

@@ -0,0 +1,43 @@
+import { redactString } from "../logging/redact.js";
+const ACTIVITY_EVENTS = new Set([
+    "agent_start",
+    "agent_end",
+    "turn_start",
+    "tool_start",
+    "tool_end",
+    "tool_progress",
+    "message",
+    "operator_prompt",
+    "operator_answer",
+]);
+function redactActivity(event) {
+    return JSON.parse(redactString(JSON.stringify(event)));
+}
+export function translateStageEvent(stageId, event, attempt) {
+    if (ACTIVITY_EVENTS.has(event.event)) {
+        return {
+            type: "stage.activity",
+            stageId,
+            attempt,
+            activity: redactActivity(event),
+        };
+    }
+    switch (event.event) {
+        case "started":
+            return { type: "stage.started", stageId, attempt };
+        case "waiting_for_input":
+            return { type: "stage.waiting", stageId, attempt };
+        case "succeeded":
+            return { type: "stage.succeeded", stageId, attempt };
+        case "failed":
+        case "interrupted":
+            return {
+                type: "stage.failed",
+                stageId,
+                attempt,
+                reason: redactString(event.reason),
+            };
+        default:
+            return undefined;
+    }
+}

package/dist/hosted/types.d.ts

@@ -0,0 +1,108 @@
+import type { StageActivityEvent } from "../agent/activity.js";
+import type { HostedErrorCode } from "./errors.js";
+export declare const HOSTED_EVENT_SCHEMA_VERSION: 1;
+/** One sink call is attempted this many times. Delivery is at least once, not exactly once. */
+export declare const HOSTED_DELIVERY_ATTEMPTS = 2;
+/** Bound for a single sink call. The private sink and Cloud worker own further retries. */
+export declare const DEFAULT_EVENT_DELIVERY_TIMEOUT_MS = 10000;
+/**
+ * After cancellation or timeout, Core waits at most this long for in-flight
+ * stage work to stop. `AgentPort` handles must stop inside `close()`.
+ */
+export declare const HOSTED_CANCEL_GRACE_MS = 5000;
+export type HostedRunContext = {
+    /** Opaque Cloud run id. Core copies it and does not interpret it. */
+    externalRunId: string;
+    /** Opaque Cloud attempt id. Core copies it and does not interpret it. */
+    externalAttemptId: string;
+    /** Revision of the package Cloud already materialized. */
+    packageRevision: string;
+    /** Extra non-secret correlation strings. */
+    attributes?: Readonly<Record<string, string>>;
+};
+export type HostedPipelineInput = {
+    packageRoot: string;
+    pipeline: string;
+    taskYaml: string;
+    context: HostedRunContext;
+    signal?: AbortSignal;
+    maxActiveStagesPerRun?: number;
+    /** Wall-clock limit for the hosted run. Omit for no hosted-level limit. */
+    timeoutMs?: number;
+};
+export type HostedExecutionReceipt = {
+    coreVersion: string;
+    eventSchemaVersion: typeof HOSTED_EVENT_SCHEMA_VERSION;
+    packageRevision: string;
+    executionMode: "inline";
+    startedAt: string;
+    finishedAt: string;
+};
+export type HostedPipelineResult = {
+    /** Null when the run failed before Core created a local run. */
+    runId: string | null;
+    externalRunId: string;
+    externalAttemptId: string;
+    status: "succeeded" | "failed" | "cancelled" | "waiting";
+    code?: HostedErrorCode;
+    reason?: string;
+    /** Present once a local run exists. Caller exports artifacts from here. */
+    workspaceDir?: string;
+    receipt: HostedExecutionReceipt;
+};
+export type HostedEventEnvelope = {
+    schemaVersion: typeof HOSTED_EVENT_SCHEMA_VERSION;
+    eventId: string;
+    sequence: number;
+    occurredAt: string;
+    runId: string;
+    externalRunId: string;
+    externalAttemptId: string;
+    packageRevision: string;
+    attributes?: Readonly<Record<string, string>>;
+};
+export type HostedRunEvent = HostedEventEnvelope & ({
+    type: "run.created";
+} | {
+    type: "run.started";
+} | {
+    type: "stage.started";
+    stageId: string;
+    attempt: number;
+} | {
+    type: "stage.activity";
+    stageId: string;
+    attempt: number;
+    activity: StageActivityEvent;
+} | {
+    type: "stage.waiting";
+    stageId: string;
+    attempt: number;
+} | {
+    type: "stage.succeeded";
+    stageId: string;
+    attempt: number;
+} | {
+    type: "stage.failed";
+    stageId: string;
+    attempt: number;
+    reason?: string;
+} | {
+    type: "run.succeeded";
+    receipt: HostedExecutionReceipt;
+} | {
+    type: "run.failed";
+    code?: HostedErrorCode;
+    reason?: string;
+    receipt: HostedExecutionReceipt;
+} | {
+    type: "run.cancelled";
+    reason?: string;
+    receipt: HostedExecutionReceipt;
+});
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type HostedEventBody = DistributiveOmit<HostedRunEvent, keyof HostedEventEnvelope>;
+export interface HostedEventSink {
+    onEvent(event: HostedRunEvent): Promise<void>;
+}
+export {};

package/dist/hosted/types.js

@@ -0,0 +1,10 @@
+export const HOSTED_EVENT_SCHEMA_VERSION = 1;
+/** One sink call is attempted this many times. Delivery is at least once, not exactly once. */
+export const HOSTED_DELIVERY_ATTEMPTS = 2;
+/** Bound for a single sink call. The private sink and Cloud worker own further retries. */
+export const DEFAULT_EVENT_DELIVERY_TIMEOUT_MS = 10_000;
+/**
+ * After cancellation or timeout, Core waits at most this long for in-flight
+ * stage work to stop. `AgentPort` handles must stop inside `close()`.
+ */
+export const HOSTED_CANCEL_GRACE_MS = 5_000;

package/dist/index.d.ts

@@ -5,10 +5,17 @@ export { resolveStageflowContext, projectContextFromStageflow, type StageflowCon
 export { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 export type { StageEnvelope } from "./types/envelope.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
-export type { AgentPort } from "./agent/port.js";
+export type { AgentPort, StageHandle, StageHandleEvent, StageRunInput, StageRunResult, } from "./agent/port.js";
+export { createPiAgentPort } from "./agent/resolveAgentPort.js";
+export { configurePiProviderApiKey } from "./agent/providerAuth.js";
 export type { StageActivityEvent, StageLogLine } from "./agent/activity.js";
 export type { StageRoots } from "./runtime/stageRoots.js";
 export { runPipeline, startPipeline } from "./runtime/pipelineRunner.js";
+export { createHostedRuntime, type HostedRuntime, } from "./hosted/runtime.js";
+export { HostedRuntimeError, HOSTED_ERROR_CODES } from "./hosted/errors.js";
+export type { HostedErrorCode } from "./hosted/errors.js";
+export { HOSTED_EVENT_SCHEMA_VERSION, HOSTED_DELIVERY_ATTEMPTS, DEFAULT_EVENT_DELIVERY_TIMEOUT_MS, HOSTED_CANCEL_GRACE_MS, } from "./hosted/types.js";
+export type { HostedRunContext, HostedPipelineInput, HostedPipelineResult, HostedExecutionReceipt, HostedEventEnvelope, HostedRunEvent, HostedEventSink, } from "./hosted/types.js";
 export { createRunStore } from "./runstore/createStore.js";
 export type { RunStoreConfig, RunStoreKind } from "./runstore/createStore.js";
 export type { RunStore, RunSummary, RunDetail, RunMeta, RunStatus, StageSnapshot, StageLogEvent, CreatedRun, } from "./runstore/port.js";

package/dist/index.js

@@ -4,7 +4,12 @@ export { resolveProjectContext, legacyProjectContext, } from "./project/resolveP
 export { resolveStageflowContext, projectContextFromStageflow, } from "./project/resolveStageflowContext.js";
 export { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
+export { createPiAgentPort } from "./agent/resolveAgentPort.js";
+export { configurePiProviderApiKey } from "./agent/providerAuth.js";
 export { runPipeline, startPipeline } from "./runtime/pipelineRunner.js";
+export { createHostedRuntime, } from "./hosted/runtime.js";
+export { HostedRuntimeError, HOSTED_ERROR_CODES } from "./hosted/errors.js";
+export { HOSTED_EVENT_SCHEMA_VERSION, HOSTED_DELIVERY_ATTEMPTS, DEFAULT_EVENT_DELIVERY_TIMEOUT_MS, HOSTED_CANCEL_GRACE_MS, } from "./hosted/types.js";
 export { createRunStore } from "./runstore/createStore.js";
 export { deriveStatusFromStages } from "./runstore/port.js";
 export { RunManager } from "./runtime/runManager.js";

package/dist/package-meta.d.ts

@@ -1,3 +1,3 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.31.0";
+export declare const PACKAGE_VERSION = "0.33.0";
 export declare const BUILD_SHA: string;

package/dist/package-meta.js

@@ -1,3 +1,3 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.31.0";
+export const PACKAGE_VERSION = "0.33.0";
 export const BUILD_SHA = process.env.STAGEFLOW_BUILD_SHA ?? "unknown";

package/dist/projection/projectRun.d.ts

@@ -46,4 +46,3 @@ export type RunProjection = {
     total_cost_usd?: number;
 };
 export declare function projectRun(detail: RunDetail): RunProjection;
-export { projectRun as projectRunForMcp };

package/dist/projection/projectRun.js

@@ -80,4 +80,3 @@ export function projectRun(detail) {
         })),
     };
 }
-export { projectRun as projectRunForMcp };

package/dist/runstore/port.d.ts

@@ -78,6 +78,8 @@ export type RunMeta = {
 };
 export type CreatedRun = {
     runId: string;
+    /** False when a durable dispatch key already belongs to this run. */
+    created?: boolean;
     /** Opaque agent workspace path (artifacts live under this tree). */
     workspaceDir: string;
 };
@@ -338,6 +340,7 @@ export type FeedbackLoopHistory = {
     fork_generations: ForkGenerationRecord[];
 };
 export type CreateRunInput = {
+    dispatchKey?: string;
     submission?: RunSubmission;
     runId?: string;
     pipelineId: string;
@@ -396,6 +399,7 @@ export interface RunStore {
     }>;
     getRunBySubmission(key: string): Promise<RunSubmissionRecord | null>;
     createRun(input: CreateRunInput): Promise<CreatedRun>;
+    findRunByDispatchKey?(dispatchKey: string): Promise<CreatedRun | undefined>;
     updateRunStatus(runId: string, status: RunStatus): Promise<void>;
     /**
      * Conditional status update (CAS): sets `status` only when the row currently

package/dist/runstore/sqlite/SqliteRunStore.d.ts

@@ -24,6 +24,7 @@ export declare class SqliteRunStore implements RunStore {
     get connection(): Database.Database;
     getWorkspaceDir(runId: string): string;
     createRun(input: CreateRunInput): Promise<CreatedRun>;
+    findRunByDispatchKey(dispatchKey: string): Promise<CreatedRun | undefined>;
     private readSubmission;
     getRunBySubmission(key: string): Promise<RunSubmissionRecord | null>;
     updateRunStatus(runId: string, status: RunStatus): Promise<void>;

package/dist/runstore/sqlite/SqliteRunStore.js

@@ -189,9 +189,13 @@ export class SqliteRunStore {
     }
     async createRun(input) {
         await this.ready();
+        const existing = input.dispatchKey ? await this.findRunByDispatchKey(input.dispatchKey) : undefined;
+        if (existing)
+            return existing;
         const runId = input.runId ?? newRunId();
         const workspaceDir = this.getWorkspaceDir(runId);
-        await mkdir(path.join(workspaceDir, "stages"), { recursive: true });
+        if (!input.dispatchKey)
+            await mkdir(path.join(workspaceDir, "stages"), { recursive: true });
         const now = new Date().toISOString();
         const pipelinePath = input.pipelinePath
             ? normalizeCatalogPath(input.pipelinePath)
@@ -214,13 +218,15 @@ export class SqliteRunStore {
                 if (existing)
                     throw new RunSubmissionExistsError(existing);
             }
-            this.db
+            const inserted = this.db
                 .prepare(`INSERT INTO runs
-          (run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root, repository, ref, resolved_sha, run_branch, git_author_name, git_author_email, pipeline_source, pipeline_body, caller_id, run_manifest, skip_gates)
+          (run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root, repository, ref, resolved_sha, run_branch, git_author_name, git_author_email, pipeline_source, pipeline_body, caller_id, run_manifest, skip_gates, dispatch_key)
          VALUES
-          (@run_id, @pipeline_id, @task_id, @task_yaml, @status, @created_at, @updated_at, @checkout_root, @pipeline_dag_json, @git_sha, @ci_pr_url, @ci_job_url, @pipeline_path, @task_path, @project_root, @repository, @ref, @resolved_sha, @run_branch, @git_author_name, @git_author_email, @pipeline_source, @pipeline_body, @caller_id, @run_manifest, @skip_gates)`)
+          (@run_id, @pipeline_id, @task_id, @task_yaml, @status, @created_at, @updated_at, @checkout_root, @pipeline_dag_json, @git_sha, @ci_pr_url, @ci_job_url, @pipeline_path, @task_path, @project_root, @repository, @ref, @resolved_sha, @run_branch, @git_author_name, @git_author_email, @pipeline_source, @pipeline_body, @caller_id, @run_manifest, @skip_gates, @dispatch_key)
+          ON CONFLICT(dispatch_key) DO NOTHING`)
                 .run({
                 run_id: runId,
+                dispatch_key: input.dispatchKey ?? null,
                 pipeline_id: input.pipelineId,
                 task_id: input.taskId ?? null,
                 task_yaml: input.taskYaml,
@@ -251,12 +257,25 @@ export class SqliteRunStore {
                     : null,
                 skip_gates: input.skipGates === undefined ? null : input.skipGates ? 1 : 0,
             });
+            if (!inserted.changes)
+                return;
             if (input.submission) {
                 this.db.prepare("INSERT INTO run_submissions (submission_key, request_hash, run_id) VALUES (?, ?, ?)")
                     .run(input.submission.key, input.submission.requestHash, runId);
             }
         })();
-        return { runId, workspaceDir };
+        if (input.dispatchKey) {
+            const selected = await this.findRunByDispatchKey(input.dispatchKey);
+            if (selected && selected.runId !== runId)
+                return selected;
+            await mkdir(path.join(workspaceDir, "stages"), { recursive: true });
+        }
+        return { runId, workspaceDir, ...(input.dispatchKey ? { created: true } : {}) };
+    }
+    async findRunByDispatchKey(dispatchKey) {
+        await this.ready();
+        const row = this.db.prepare("SELECT run_id FROM runs WHERE dispatch_key = ?").get(dispatchKey);
+        return row ? { runId: row.run_id, workspaceDir: this.getWorkspaceDir(row.run_id), created: false } : undefined;
     }
     readSubmission(key) {
         const row = this.db.prepare("SELECT submission_key AS key, request_hash AS requestHash, run_id AS runId FROM run_submissions WHERE submission_key = ?")

package/dist/runstore/sqlite/migrations/011-email-dispatch-key.d.ts

@@ -0,0 +1,7 @@
+import type Database from "better-sqlite3";
+export declare const MIGRATION_011: {
+    version: number;
+    name: string;
+    minStageflowVersion: string;
+    up(db: Database.Database): void;
+};

package/dist/runstore/sqlite/migrations/011-email-dispatch-key.js

@@ -0,0 +1,12 @@
+import { PACKAGE_VERSION } from "../../../package-meta.js";
+export const MIGRATION_011 = {
+    version: 11,
+    name: "011_email_dispatch_key",
+    minStageflowVersion: PACKAGE_VERSION,
+    up(db) {
+        const columns = db.prepare("PRAGMA table_info(runs)").all();
+        if (!columns.some(column => column.name === "dispatch_key"))
+            db.exec("ALTER TABLE runs ADD COLUMN dispatch_key TEXT");
+        db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_runs_dispatch_key ON runs(dispatch_key)");
+    },
+};

package/dist/runstore/sqlite/migrations/index.js

@@ -9,6 +9,7 @@ import { MIGRATION_007 } from "./007-projects-registry.js";
 import { MIGRATION_008 } from "./008-triggers-table.js";
 import { MIGRATION_009 } from "./009-trigger-next-run.js";
 import { MIGRATION_010 } from "./010-trigger-adapter-state.js";
+import { MIGRATION_011 } from "./011-email-dispatch-key.js";
 const DEFAULT_MIGRATIONS = [
     MIGRATION_001,
     MIGRATION_002,
@@ -20,6 +21,7 @@ const DEFAULT_MIGRATIONS = [
     MIGRATION_008,
     MIGRATION_009,
     MIGRATION_010,
+    MIGRATION_011,
 ];
 export const CURRENT_SCHEMA_VERSION = DEFAULT_MIGRATIONS[DEFAULT_MIGRATIONS.length - 1].version;
 function throwStoreSchemaTooNew(db, version, maxKnown) {

package/dist/runtime/containerLimits.d.ts

@@ -1,4 +1,3 @@
-import os from "node:os";
 export type ContainerLimits = {
     memoryLimitBytes: number | undefined;
     maxActiveStageProcesses: number;
@@ -12,5 +11,3 @@ export declare function readContainerMemoryLimit(roots?: readonly string[]): {
 export declare function deriveContainerLimits(memoryLimitBytes: number | undefined, source?: ContainerLimits["source"]): ContainerLimits;
 export declare function getContainerLimits(): ContainerLimits;
 export declare function resetContainerLimitsForTests(): void;
-/** Test hook: prove sizing never consults os.totalmem. */
-export declare function assertNoOsTotalmemInSizing(): typeof os.totalmem;

package/dist/runtime/containerLimits.js

@@ -1,5 +1,4 @@
 import { readFileSync, existsSync } from "node:fs";
-import os from "node:os";
 const HOST_RESERVE_MIB = 512;
 const WORKER_BUDGET_MIB = 512;
 const MAX_CAP = 8;
@@ -78,7 +77,3 @@ export function getContainerLimits() {
 export function resetContainerLimitsForTests() {
     cached = undefined;
 }
-/** Test hook: prove sizing never consults os.totalmem. */
-export function assertNoOsTotalmemInSizing() {
-    return os.totalmem;
-}

package/dist/runtime/credentialBinding.d.ts

@@ -19,5 +19,8 @@ export declare function stageflowAgentAuthPath(override?: string): string;
 export declare function piHomeAuthPath(override?: string): string;
 export declare function isUsableAuthFile(authPath: string): boolean;
 export declare function ensureSfOwnedAuthStore(): string;
+/** Use this auth file for credential binding and do not create the operator home. */
+export declare function runWithExplicitAuthPath<T>(authPath: string, fn: () => Promise<T>): Promise<T>;
+export declare function currentExplicitAuthPath(): string | undefined;
 export declare function resolveCredentialBinding(ctx: ProjectContext | string, _options?: ResolveCredentialBindingOptions): CredentialBinding;
 export { readCredentialSourceFromFile, writeCredentialSourceToFile, } from "./settingsFile.js";

package/dist/runtime/credentialBinding.js

@@ -1,4 +1,5 @@
 import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { AsyncLocalStorage } from "node:async_hooks";
 import path from "node:path";
 import { ensureGlobalHome } from "../project/globalHome.js";
 import { resolveProjectContext, } from "../project/resolveProjectContext.js";
@@ -53,6 +54,14 @@ export function ensureSfOwnedAuthStore() {
     }
     return authPath;
 }
+const explicitAuthPath = new AsyncLocalStorage();
+/** Use this auth file for credential binding and do not create the operator home. */
+export function runWithExplicitAuthPath(authPath, fn) {
+    return explicitAuthPath.run(path.resolve(authPath), fn);
+}
+export function currentExplicitAuthPath() {
+    return explicitAuthPath.getStore();
+}
 export function resolveCredentialBinding(ctx, _options = {}) {
     const projectCtx = typeof ctx === "string" ? resolveProjectContext(ctx) : ctx;
     const persisted = readCredentialSourceFromContext(projectCtx);

package/dist/runtime/pipelineRunner.d.ts

@@ -41,6 +41,7 @@ export type PipelineRunResult = {
     findings?: ValidationFinding[];
 };
 export type StartedPipeline = {
+    created?: boolean;
     runId: string;
     runDir: string;
     done: Promise<PipelineRunResult>;
@@ -51,6 +52,7 @@ export type PreparedPipeline = {
     run: {
         runId: string;
         workspaceDir: string;
+        created?: boolean;
     };
     agent: AgentPort;
     store: RunStore;
@@ -97,6 +99,7 @@ export declare function runPipeline(options: {
 }): Promise<PipelineRunResult>;
 /** Create the run immediately, then execute stages in the returned promise. */
 export declare function startPipeline(options: {
+    dispatchKey?: string;
     submission?: RunSubmission;
     agent: AgentPort;
     store: RunStore;

package/dist/runtime/pipelineRunner.js

@@ -197,6 +197,7 @@ async function preparePipeline(options) {
             namedSecrets,
         });
         run = await options.store.createRun({
+            dispatchKey: options.dispatchKey,
             submission: options.submission,
             runId,
             pipelineId: loaded.pipeline.id,
@@ -299,6 +300,7 @@ export async function startPipeline(options) {
     const cwd = options.cwd ?? process.cwd();
     const projectRoot = options.projectRoot ?? cwd;
     const prepared = await preparePipeline({
+        dispatchKey: options.dispatchKey,
         submission: options.submission,
         agent: options.agent,
         store: options.store,
@@ -327,6 +329,15 @@ export async function startPipeline(options) {
         callerId: options.callerId,
         ...(options.skills !== undefined ? { skills: options.skills } : {}),
     });
+    if (prepared.run.created === false) {
+        const meta = await prepared.store.readRunMeta(prepared.run.runId);
+        return {
+            created: false,
+            runId: prepared.run.runId,
+            runDir: prepared.run.workspaceDir,
+            done: Promise.resolve({ ok: meta.status === "succeeded", outcome: meta.status === "succeeded" ? "succeeded" : "failed", runId: prepared.run.runId, runDir: prepared.run.workspaceDir, reason: "Recovered existing dispatch; execution was not restarted" }),
+        };
+    }
     const done = executeStages(prepared, {
         maxActiveStagesPerRun: options.maxActiveStagesPerRun,
         executionMode: prepared.executionMode,

package/dist/runtime/pipelineScheduler.js

@@ -968,6 +968,9 @@ export async function runPipelineDag(options) {
                     runId: run.runId,
                     stageId,
                     rootDir: factoryCwd,
+                    stage,
+                    factoryCwd,
+                    workspaceDir: run.workspaceDir,
                     attempt,
                     env: stageBinding.env,
                     bindingKind: stageBinding.kind,

package/dist/runtime/runManager.d.ts

@@ -285,6 +285,7 @@ export declare class RunManager {
         pipeline: string | InlinePipelineDefinition;
         task?: string | TaskFile;
         checkoutOverride?: string;
+        dispatchKey?: string;
         skipGates?: boolean;
         gitSha?: string;
         ciPrUrl?: string;