stageflow 0.23.0 → 0.27.0

package/dist/cli/runCommand.d.ts

@@ -1,11 +1,12 @@
 import type { RunStore } from "../runstore/port.js";
 import type { StartRunResult } from "../runtime/runManager.js";
+import type { TaskFile } from "../types/task.js";
 import { type EnsureGlobalServiceResult } from "../server/ensureGlobalService.js";
 import { type CliRunReportIo } from "./runOutput.js";
-export declare const RUN_USAGE = "Usage:\n  sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]";
+export declare const RUN_USAGE = "Usage:\n  sf run --task <path> --pipeline <path> [--checkout <path>] [--repository <owner/repo>] [--ref <ref>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]";
 export type RunCommandIo = CliRunReportIo;
 export type StartRunFn = (input: {
-    task: string;
+    task: string | TaskFile;
     pipeline: string;
     checkoutOverride?: string;
     skipGates?: boolean;

package/dist/cli/runCommand.js

@@ -1,11 +1,16 @@
-import { PipelineValidationError } from "../runtime/pipelineRunner.js";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { coerceTaskFile } from "../config/loadTask.js";
+import { relativizeLocalPathForNetwork } from "../config/catalogRelativePath.js";
+import { PipelinePreflightError, PipelineValidationError } from "../runtime/pipelineRunner.js";
 import { ensureGlobalService, hostBaseUrl, } from "../server/ensureGlobalService.js";
-import { httpStartRun, httpStoreReader, resolveAbsolute } from "./hostClient.js";
-import { reportCliRun, } from "./runOutput.js";
+import { httpEnsureProject, httpStartRun, httpStoreReader } from "./hostClient.js";
+import { reportCliRun, writeQueuedAdmissionLine, } from "./runOutput.js";
 import { resolveCiIdentity } from "./ciIdentity.js";
 import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
 export const RUN_USAGE = `Usage:
-  sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]`;
+  sf run --task <path> --pipeline <path> [--checkout <path>] [--repository <owner/repo>] [--ref <ref>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]`;
 const defaultIo = {
     log: (line) => console.log(line),
     error: (line) => console.error(line),
@@ -20,6 +25,8 @@ function parseRunArgs(args) {
     let task;
     let pipeline;
     let checkout;
+    let repository;
+    let ref;
     let gitSha;
     let ciPrUrl;
     let ciJobUrl;
@@ -55,6 +62,20 @@ function parseRunArgs(args) {
             }
             checkout = value;
         }
+        else if (arg === "--repository") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --repository");
+            }
+            repository = value;
+        }
+        else if (arg === "--ref") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --ref");
+            }
+            ref = value;
+        }
         else if (arg === "--git-sha") {
             const value = args[++i];
             if (value === undefined || value.length === 0) {
@@ -123,6 +144,8 @@ function parseRunArgs(args) {
         task,
         pipeline,
         checkout,
+        repository,
+        ref,
         gitSha,
         ciPrUrl,
         ciJobUrl,
@@ -130,18 +153,60 @@ function parseRunArgs(args) {
         operatorAgentDir,
     };
 }
+async function loadTaskWithBindingOverrides(taskPath, cwd, overrides) {
+    const absolute = path.resolve(cwd, taskPath);
+    const yamlText = await readFile(absolute, "utf8");
+    const raw = parseYaml(yamlText);
+    const task = coerceTaskFile(raw);
+    if (task === undefined) {
+        throw new Error(`Invalid task file ${absolute}: id and goal are required strings`);
+    }
+    if (overrides.repository !== undefined)
+        task.repository = overrides.repository;
+    if (overrides.ref !== undefined)
+        task.ref = overrides.ref;
+    return task;
+}
 function defaultStartRun(cwd, base, ensureService) {
     return async (input) => {
         const ensured = await ensureService();
         if (!ensured.ok) {
-            return { ok: false, reason: ensured.message, status: 503 };
+            return {
+                ok: false,
+                reason: ensured.message,
+                status: 503,
+                ...(ensured.reason === "autostart_disabled"
+                    ? { code: "autostart_disabled" }
+                    : {}),
+            };
         }
+        const pipelineRef = relativizeLocalPathForNetwork(cwd, input.pipeline);
+        let task = input.task;
+        let projectRoot = pipelineRef.project_root;
+        if (typeof input.task === "string") {
+            const absTask = path.resolve(cwd, input.task);
+            const cwdAbs = path.resolve(cwd);
+            const relTask = path.relative(cwdAbs, absTask);
+            if (relTask.startsWith("..") || path.isAbsolute(relTask)) {
+                task = await loadTaskWithBindingOverrides(input.task, cwd, {});
+            }
+            else {
+                const taskRef = relativizeLocalPathForNetwork(cwd, input.task);
+                task = taskRef.path;
+                projectRoot = taskRef.project_root;
+            }
+        }
+        const ensuredProject = await httpEnsureProject(base, projectRoot);
+        if (!ensuredProject.ok)
+            return ensuredProject;
+        const checkoutOverride = input.checkoutOverride !== undefined
+            ? relativizeLocalPathForNetwork(cwd, input.checkoutOverride).path
+            : undefined;
         return httpStartRun(base, {
-            pipeline: resolveAbsolute(cwd, input.pipeline),
-            task: resolveAbsolute(cwd, input.task),
-            ...(input.checkoutOverride !== undefined
-                ? { checkoutOverride: resolveAbsolute(cwd, input.checkoutOverride) }
-                : {}),
+            pipeline: pipelineRef.path,
+            task,
+            project_root: ensuredProject.project_root,
+            ...(checkoutOverride !== undefined ? { checkoutOverride } : {}),
             ...(input.skipGates !== undefined ? { skipGates: input.skipGates } : {}),
             ...(input.gitSha !== undefined ? { gitSha: input.gitSha } : {}),
             ...(input.ciPrUrl !== undefined ? { ciPrUrl: input.ciPrUrl } : {}),
@@ -200,8 +265,15 @@ export async function runRunCommand(args, options = {}) {
     });
     const store = options.store ?? (parsed.includeStages ? httpStoreReader(base) : undefined);
     try {
+        const hasBindingOverride = parsed.repository !== undefined || parsed.ref !== undefined;
+        const taskInput = hasBindingOverride
+            ? await loadTaskWithBindingOverrides(parsed.task, cwd, {
+                repository: parsed.repository,
+                ref: parsed.ref,
+            })
+            : parsed.task;
         const started = await startRun({
-            task: parsed.task,
+            task: taskInput,
             pipeline: parsed.pipeline,
             checkoutOverride: parsed.checkout,
             ...(parsed.skipGates ? { skipGates: true } : {}),
@@ -210,6 +282,7 @@ export async function runRunCommand(args, options = {}) {
         if (!started.ok) {
             return reportCliRun({ kind: "start-failure", started }, { json: parsed.json, io: out });
         }
+        writeQueuedAdmissionLine(started, out);
         return completeCliRun(started, out, {
             json: parsed.json,
             includeStages: parsed.includeStages,
@@ -226,6 +299,15 @@ export async function runRunCommand(args, options = {}) {
             }
             return exitCodeForValidation(err.result);
         }
+        if (err instanceof PipelinePreflightError) {
+            if (parsed.json) {
+                out.log(JSON.stringify(err.toNetworkBody(), null, 2));
+            }
+            else {
+                out.error(err.message);
+            }
+            return 1;
+        }
         out.error(err instanceof Error ? err.message : String(err));
         return 1;
     }

package/dist/cli/runOutput.d.ts

@@ -14,6 +14,10 @@ export type CliRunReportEvent = {
     kind: "completion";
     result: PipelineRunResult;
 };
+/** Stderr line when start_run was admitted to the queue (origin transparency rule). */
+export declare function writeQueuedAdmissionLine(started: Extract<StartRunResult, {
+    ok: true;
+}>, io: Pick<CliRunReportIo, "error">): void;
 export declare function reportCliRun(event: CliRunReportEvent, options: {
     json?: boolean;
     io: CliRunReportIo;

package/dist/cli/runOutput.js

@@ -20,6 +20,12 @@ async function tryReadTotalCostUsd(store, runId) {
 function isBusyCode(code) {
     return code === "busy_capacity" || code === "busy_checkout";
 }
+/** Stderr line when start_run was admitted to the queue (origin transparency rule). */
+export function writeQueuedAdmissionLine(started, io) {
+    if (started.queued === true && started.queuePosition !== undefined) {
+        io.error(`queued at position ${started.queuePosition}`);
+    }
+}
 function formatRunBusyJson(started) {
     const payload = {
         ok: false,
@@ -52,6 +58,13 @@ function formatRunStartFailedJson(started) {
     };
     if (started.code !== undefined)
         payload.code = started.code;
+    if (started.freeBytes !== undefined)
+        payload.freeBytes = started.freeBytes;
+    if (started.minFreeBytes !== undefined) {
+        payload.minFreeBytes = started.minFreeBytes;
+    }
+    if (started.stderr !== undefined)
+        payload.stderr = started.stderr;
     return stringify(payload);
 }
 function formatStartFailureJson(started) {
@@ -75,13 +88,21 @@ function baseRunCompletionPayload(result) {
                 runId: result.runId,
                 runDir: result.runDir,
             }
-            : {
-                ok: false,
-                outcome: "failed",
-                runId: result.runId,
-                runDir: result.runDir,
-            };
-    if (result.outcome === "failed" && result.reason !== undefined) {
+            : result.outcome === "cancelled"
+                ? {
+                    ok: false,
+                    outcome: "cancelled",
+                    runId: result.runId,
+                    runDir: result.runDir,
+                }
+                : {
+                    ok: false,
+                    outcome: "failed",
+                    runId: result.runId,
+                    runDir: result.runDir,
+                };
+    if ((result.outcome === "failed" || result.outcome === "cancelled") &&
+        result.reason !== undefined) {
         payload.reason = result.reason;
     }
     if (Array.isArray(result.findings) && result.findings.length > 0) {
@@ -130,6 +151,10 @@ function writeCompletionHuman(result, io, totalCostUsd) {
             io.error(`Pipeline failed: ${result.reason}`);
             io.error(`Run folder: ${result.runDir}`);
             break;
+        case "cancelled":
+            io.error(`Pipeline cancelled${result.reason ? `: ${result.reason}` : ""}`);
+            io.error(`Run folder: ${result.runDir}`);
+            break;
         case "succeeded":
             io.log(`Pipeline succeeded. Run folder: ${result.runDir}`);
             break;
@@ -145,6 +170,7 @@ function exitCodeForRunOutcome(outcome) {
         case "waiting":
             return 2;
         case "failed":
+        case "cancelled":
             return 1;
     }
 }

package/dist/cli/runStageCommand.d.ts

@@ -0,0 +1,34 @@
+import { type EnsureGlobalServiceResult } from "../server/ensureGlobalService.js";
+export declare const RUN_STAGE_USAGE = "Usage:\n  sf run-stage (--stage <path> | --stage-inline '<json>') (--task <path> | --task-inline '<json>' | --envelope-ref <runId>:<stageId>[:<attempt>] [--envelope-ref ...]) [--checkout <path>] [--model <id>] [--blocking] [--timeout-ms <n>] [--json]\n\nRun a single stage directly against the shared Stageflow service, without authoring a pipeline file. Distinct from the internal-only, worker-process-only `sf internal run-stage`.\n  --stage <path>          Filesystem path to a catalog stage YAML file\n  --stage-inline <json>   Inline stage body object ({ id, system_prompt, io, ... } \u2014 no uses:/route/pipeline wrapper)\n  --task <path>           Filesystem path to a catalog task YAML file\n  --task-inline <json>    Inline task object ({ id, goal, ... })\n  --envelope-ref <ref>    Resolve a previously stored StageEnvelope as this stage's input instead of a task: <runId>:<stageId>[:<attempt>]. Repeat to pass more than one \u2014 each resolved payload is namespaced under its stageId in input (disambiguated by runId on a stageId collision), and summaries are combined into goal.\n  --checkout <path>       Optional checkout to use with --envelope-ref (--task/--task-inline carry their own checkout)\n  --model <id>            Override the model/backend for this call only, ahead of the stage's own declared model\n  --blocking              Wait for the run to reach a terminal or waiting state and print the result in this same call, instead of returning immediately with just the run id\n  --timeout-ms <n>        Wait budget in ms when --blocking is set\n  --json                  Machine-readable JSON output";
+export type RunStageEnvelopeRef = {
+    runId: string;
+    stageId: string;
+    attempt?: number;
+};
+export type RunStageToolArgs = {
+    stage: string | Record<string, unknown>;
+    project_root?: string;
+    task_path?: string;
+    task?: Record<string, unknown>;
+    envelope_ref?: RunStageEnvelopeRef | RunStageEnvelopeRef[];
+    checkout?: string;
+    model?: string;
+    blocking?: boolean;
+    timeout_ms?: number;
+};
+export type RunStageToolResult = {
+    isError: boolean;
+    payload: Record<string, unknown> | null;
+};
+export type RunStageCallFn = (args: RunStageToolArgs) => Promise<RunStageToolResult>;
+export type RunStageCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runRunStageCommand(args: string[], options?: {
+    cwd?: string;
+    io?: Partial<RunStageCommandIo>;
+    callTool?: RunStageCallFn;
+    hostBaseUrl?: string;
+    ensureService?: () => Promise<EnsureGlobalServiceResult>;
+}): Promise<number>;