stageflow 0.32.0 → 0.33.0

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.32.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.32.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/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/runRetentionSweep.d.ts

@@ -15,8 +15,6 @@ export type RunRetentionSweepOptions = {
     artifactMaxBytes?: number;
     bareCacheTtlMs?: number;
 };
-export declare function getSlimWalkCallCount(): number;
-export declare function resetSlimWalkCallCount(): void;
 /**
  * Walk attempt + legacy artifact trees and remove SLIM-eligible paths.
  * Never removes envelope.json, log.jsonl, or under-threshold artifacts.

package/dist/runtime/runRetentionSweep.js

@@ -7,13 +7,6 @@ import { reclaimWorkspaceBinding, worktreePathForRun, } from "./repositoryMateri
 import { deleteRunEverywhere } from "./runDeletion.js";
 const SLIM_ATTEMPT_FILES = ["pi-session.jsonl", "stream.log"];
 const SLIM_ATTEMPT_DIRS = [".pi-agent"];
-let slimWalkCallCount = 0;
-export function getSlimWalkCallCount() {
-    return slimWalkCallCount;
-}
-export function resetSlimWalkCallCount() {
-    slimWalkCallCount = 0;
-}
 async function pathExists(target) {
     try {
         await stat(target);
@@ -84,7 +77,6 @@ async function slimAttemptDir(attemptDir, maxBytes) {
  * Never removes envelope.json, log.jsonl, or under-threshold artifacts.
  */
 export async function slimRunWorkspaceArtifacts(workspaceDir, maxBytes) {
-    slimWalkCallCount += 1;
     const stagesRoot = path.join(workspaceDir, "stages");
     if (!(await pathExists(stagesRoot)))
         return;

package/dist/runtime/stageRoots.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { isCursorModelRef } from "../agent/cursorProvider.js";
 import { stageDir } from "../runstore/paths.js";
 import { noAttemptContext } from "./stageAttemptContext.js";
-import { resolveCredentialBinding } from "./credentialBinding.js";
+import { resolveCredentialBinding, currentExplicitAuthPath } from "./credentialBinding.js";
 export const STAGEFLOW_CHECKOUT = "STAGEFLOW_CHECKOUT";
 export const STAGEFLOW_RUN_WORKSPACE = "STAGEFLOW_RUN_WORKSPACE";
 export const STAGEFLOW_REPOSITORY = "STAGEFLOW_REPOSITORY";
@@ -127,6 +127,10 @@ export function stageBindingEnvFromRun(options) {
 export function withResolvedAuthPath(roots, factoryCwd) {
     if (roots.authPath)
         return roots;
+    const explicit = currentExplicitAuthPath();
+    if (explicit !== undefined) {
+        return { ...roots, authPath: explicit };
+    }
     const binding = resolveCredentialBinding(factoryCwd);
     return { ...roots, authPath: binding.authPath };
 }

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "stageflow",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Stageflow — CLI pipeline runtime for configurable stages on Pi",
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "bin": {
     "sf": "./dist/cli.js",
     "stageflow": "./dist/cli.js"