stageflow 0.8.0 → 0.12.0

package/dist/agent/port.d.ts

@@ -1,11 +1,47 @@
-import type { StageEnvelope } from "../types/envelope.js";
+import type { StageEnvelope, TerminalEnvelope } from "../types/envelope.js";
+import type { CompletionContract } from "../types/completion.js";
 import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
 import type { StageConfig } from "../types/stage.js";
+import type { FeedbackLoopConfig } from "../types/pipeline.js";
 import type { TaskFile } from "../types/task.js";
 import type { StageActivityEvent } from "./activity.js";
 import type { StageRoots } from "../runtime/stageRoots.js";
+import type { QaExchange } from "../hitl/qaTrail.js";
 /** Opaque to runtime; adapters interpret. */
 export type StageResumeToken = string;
+export type StageSessionMode = "fresh" | "waiting_resume" | "feedback_resume" | "new_session";
+export type StageRepairContext = {
+    prior_attempt: number;
+    /** Operator-authored instructions for an explicitly approved manual retry. */
+    operator_guidance?: string;
+    failed_checks?: Array<{
+        id: string;
+        type: string;
+        evidence_preview?: string;
+    }>;
+};
+export type FeedbackLoopContext = {
+    loop_id: string;
+    replay_id: string;
+    source_stage_id: string;
+    target_stage_id: string;
+    /** Original send-back envelope from the source (feedback + artifacts). */
+    feedback_envelope: StageEnvelope;
+    /** One-based replay number for this send-back. */
+    replay_number: number;
+    max_replays: number;
+    remaining_replays: number;
+    is_final_replay: boolean;
+    replay_session: "resume" | "new_session";
+    /** Persistent stages on the active target→source route, forward order. */
+    route_stage_ids: string[];
+    /** Prior pass/session identity for THIS stage when resuming, if any. */
+    prior_stage_attempt?: number;
+    prior_pass_status?: string;
+    /** Active fork generation for this stage's parent fan-out, if any. */
+    active_fork_generation_id?: string;
+    active_fork_clone_stage_ids?: string[];
+};
 export type StageRunInput = {
     roots: StageRoots;
     stage: StageConfig;
@@ -14,13 +50,26 @@ export type StageRunInput = {
     task: TaskFile;
     priorEnvelope: StageEnvelope | null;
     priorEnvelopes?: StageEnvelope[];
+    priorEnvelopesByStage?: Record<string, TerminalEnvelope | TerminalEnvelope[]>;
     timeoutMs?: number;
     resumeToken?: StageResumeToken;
+    /** Launch/session mode; omitted is treated as `"fresh"`. */
+    sessionMode?: StageSessionMode;
     /** Optional observe hook; HITL wait/answer uses openStage beside this. */
     onActivity?: (event: StageActivityEvent) => void;
     skillFilePath?: string;
     forkEmitContext?: ForkEmitContext;
     cloneEmitContext?: CloneEmitContext;
+    /** Declared source policy; successful emits must continue or send work back. */
+    feedbackLoopEmitContext?: FeedbackLoopConfig;
+    /** Replay context for stages being replayed (and typically the source on send-back). */
+    feedbackLoopContext?: FeedbackLoopContext;
+    /** Frozen pipeline-owned checks that must pass before Stageflow advances. */
+    completionContract?: CompletionContract;
+    /** Compact evidence from the failed verification that triggered this repair. */
+    repairContext?: StageRepairContext;
+    /** Live attempt-scoped QA trail; read at emit execute time, not bootstrap time. */
+    readQaTrail?: () => QaExchange[] | Promise<QaExchange[]>;
 };
 export declare function runtimeStageId(input: Pick<StageRunInput, "stage" | "stageId">): string;
 export type StageRunResult = {

package/dist/agent/resolveAgentPort.d.ts

@@ -0,0 +1,26 @@
+import { type AgentBackendId } from "./agentBackend.js";
+import type { AgentPort } from "./port.js";
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+export type AgentSelection = {
+    /** stageflow.yaml top-level `agent`. */
+    global?: AgentBackendId;
+    /** Pipeline yaml top-level `agent`; overrides global. */
+    pipeline?: AgentBackendId;
+    /** Stage yaml `agent`; would override pipeline/global once enabled. */
+    stage?: AgentBackendId;
+};
+/** stage > pipeline > global > "pi", with stage gated off for now. */
+export declare function resolveAgentBackend(selection?: AgentSelection): AgentBackendId;
+export declare function resolveAgentPort(selection?: AgentSelection): AgentPort;
+/** The global tier's backend id from an already-loaded manifest, or undefined for missing/invalid/unset. */
+export declare function globalAgentBackendFromManifest(manifest: LoadedManifest | null): AgentBackendId | undefined;
+/**
+ * Resolves an AgentPort using only the global (stageflow.yaml) tier — for
+ * the three call sites that construct an agent before any pipeline is
+ * known (`cli.ts`'s ui/mcp servers, `runCommand.ts`, `runsCommand.ts`).
+ * Named explicitly so it's clear these sites are scoped to the global tier
+ * on purpose, not by omission: production stage execution always goes
+ * through `stageWorker.ts`, which resolves the full stage > pipeline >
+ * global chain once it has loaded the specific pipeline and stage.
+ */
+export declare function resolveGlobalOnlyAgentPort(projectRoot: string): Promise<AgentPort>;

package/dist/agent/resolveAgentPort.js

@@ -0,0 +1,39 @@
+import { asAgentBackendId, STAGE_LEVEL_AGENT_OVERRIDE_ENABLED, } from "./agentBackend.js";
+import { PiAgentAdapter } from "./piAdapter.js";
+import { ClaudeAgentAdapter } from "./claudeAdapter.js";
+import { loadStageflowManifestOutcome } from "../config/loadStageflowManifest.js";
+/** stage > pipeline > global > "pi", with stage gated off for now. */
+export function resolveAgentBackend(selection = {}) {
+    if (STAGE_LEVEL_AGENT_OVERRIDE_ENABLED && selection.stage !== undefined) {
+        return selection.stage;
+    }
+    return selection.pipeline ?? selection.global ?? "pi";
+}
+export function resolveAgentPort(selection = {}) {
+    const backend = resolveAgentBackend(selection);
+    switch (backend) {
+        case "pi":
+            return new PiAgentAdapter();
+        case "claude":
+            return new ClaudeAgentAdapter();
+    }
+}
+/** The global tier's backend id from an already-loaded manifest, or undefined for missing/invalid/unset. */
+export function globalAgentBackendFromManifest(manifest) {
+    return manifest ? asAgentBackendId(manifest.manifest.agent) : undefined;
+}
+/**
+ * Resolves an AgentPort using only the global (stageflow.yaml) tier — for
+ * the three call sites that construct an agent before any pipeline is
+ * known (`cli.ts`'s ui/mcp servers, `runCommand.ts`, `runsCommand.ts`).
+ * Named explicitly so it's clear these sites are scoped to the global tier
+ * on purpose, not by omission: production stage execution always goes
+ * through `stageWorker.ts`, which resolves the full stage > pipeline >
+ * global chain once it has loaded the specific pipeline and stage.
+ */
+export async function resolveGlobalOnlyAgentPort(projectRoot) {
+    const outcome = await loadStageflowManifestOutcome(projectRoot);
+    return resolveAgentPort({
+        global: outcome.ok ? globalAgentBackendFromManifest(outcome.value) : undefined,
+    });
+}

package/dist/cli/runCommand.js

@@ -1,4 +1,4 @@
-import { PiAgentAdapter } from "../agent/piAdapter.js";
+import { resolveGlobalOnlyAgentPort } from "../agent/resolveAgentPort.js";
 import { createRunStore } from "../runstore/createStore.js";
 import { PipelineValidationError } from "../runtime/pipelineRunner.js";
 import { RunManager } from "../runtime/runManager.js";
@@ -137,7 +137,7 @@ function defaultStartRun(cwd, projectRoot, isGitProject, operatorCatalog) {
     return async (input) => {
         const store = createRunStore({ rootDir: projectRoot });
         const manager = new RunManager({
-            agent: new PiAgentAdapter(),
+            agent: await resolveGlobalOnlyAgentPort(projectRoot),
             store,
             cwd,
             projectRoot,

package/dist/cli/runsCommand.d.ts

@@ -0,0 +1,22 @@
+import type { RunStore } from "../runstore/port.js";
+import { RunManager } from "../runtime/runManager.js";
+export declare const RUNS_USAGE = "Usage:\n  sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]\n  sf runs show --run <runId> [--from <sf-run.json>] [--json]\n  sf runs verify --run <runId> --stage <stageId> [--json]\n  sf runs recover --run <runId> --stage <stageId> [--guidance <text>] [--stop] [--json]\n  sf runs waiting [--run <runId>] [--json]\n  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]\n  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]\n  sf runs feedback-decide --run <runId> --stage <sourceStageId> [--loop <loopId>] --decision extend|continue|abandon [--reason <text>] [--json]\n  sf runs retry --run <runId> --stage <stageId> [--json]\n  sf runs abandon --run <runId> --stage <stageId> [--json]\n  sf runs rerun --run <runId> [--json]";
+export type RunsCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export type HostProbeResult = "up" | "down";
+export declare function defaultProbeHost(): Promise<HostProbeResult>;
+export declare function runRunsCommand(args: string[], options?: {
+    cwd?: string;
+    projectRoot?: string;
+    isGitProject?: boolean;
+    io?: Partial<RunsCommandIo>;
+    store?: RunStore;
+    probeHost?: () => Promise<HostProbeResult>;
+    stdinIsTTY?: boolean;
+    readStdin?: () => string;
+    waitSignal?: AbortSignal;
+    env?: NodeJS.ProcessEnv;
+    createManager?: (store: RunStore) => RunManager;
+}): Promise<number>;