stageflow 0.1.0

package/dist/runstore/port.d.ts

@@ -0,0 +1,146 @@
+import type { StageLogLine } from "../agent/activity.js";
+import type { AskOperatorPrompt } from "../tools/askOperator.js";
+import type { StageEnvelope } from "../types/envelope.js";
+import type { ResolvedPipelineDag } from "../types/pipeline.js";
+import type { StageGateKind } from "../types/stage.js";
+export type RunStatus = "created" | "running" | "succeeded" | "failed";
+export type RunPipelineDagSnapshot = ResolvedPipelineDag & {
+    stage_ids: string[];
+    gate_kinds?: Record<string, StageGateKind[]>;
+};
+export type StageReadiness = "blocked" | "ready" | "running" | "waiting" | "succeeded" | "failed" | "skipped";
+export type PipelineTrackNode = {
+    stage_id: string;
+    status: StageSnapshot["status"];
+    readiness: StageReadiness;
+    layer: number;
+    layer_order: number;
+    blocked_by?: string[];
+    gate_kinds?: StageGateKind[];
+    attempt_count?: number;
+};
+export type PipelineTrackEdge = {
+    from: string;
+    to: string;
+    envelope_summary?: string;
+};
+export type PipelineTrackProjection = {
+    nodes: PipelineTrackNode[];
+    edges: PipelineTrackEdge[];
+};
+export type RunMeta = {
+    run_id: string;
+    pipeline_id: string;
+    created_at: string;
+    status?: RunStatus;
+    task_id?: string;
+    updated_at?: string;
+    checkout_root?: string;
+    pipeline_dag?: RunPipelineDagSnapshot;
+};
+export type CreatedRun = {
+    runId: string;
+    /** Opaque agent workspace path (artifacts live under this tree). */
+    workspaceDir: string;
+};
+/** Persisted stage log line (activity or lifecycle) with optional timestamp. */
+export type StageLogEvent = StageLogLine & {
+    at?: string;
+};
+export type StageSnapshot = {
+    stage_id: string;
+    status: "pending" | "running" | "waiting_for_input" | "succeeded" | "failed";
+    events: StageLogEvent[];
+    envelope: StageEnvelope | null;
+    artifacts: string[];
+    last_at?: string;
+    pending_prompt?: AskOperatorPrompt;
+    attempt_count: number;
+};
+export type StageExecution = {
+    run_id: string;
+    stage_id: string;
+    attempt: number;
+    status: StageSnapshot["status"];
+    started_at?: string;
+    finished_at?: string;
+    envelope: StageEnvelope | null;
+};
+export type StageExecutionPatch = {
+    status?: StageSnapshot["status"];
+    started_at?: string;
+    finished_at?: string;
+    envelope?: StageEnvelope | null;
+};
+export type CompactStage = {
+    id: string;
+    status: StageSnapshot["status"];
+    attempt_count: number;
+};
+export type RunSummary = {
+    run_id: string;
+    pipeline_id: string;
+    task_id?: string;
+    status: RunStatus;
+    created_at: string;
+    updated_at?: string;
+    stages: CompactStage[];
+    /** Present when a stage is waiting_for_input (first such stage). */
+    waiting_stage_id?: string;
+    /** All stages waiting_for_input in declaration order; omitted when none. */
+    waiting_stage_ids?: string[];
+    /** Short prompt text for Today triage; omitted when not waiting. */
+    waiting_summary?: string;
+    waiting_kind?: AskOperatorPrompt["kind"];
+    waiting_prompt_id?: string;
+    waiting_artifacts?: string[];
+    waiting_questions?: string[];
+    failed_stage_id?: string;
+    failed_reason?: string;
+};
+export type RunDetail = Omit<RunSummary, "stages"> & {
+    task_yaml: string;
+    stages: StageSnapshot[];
+    pipeline_track: PipelineTrackProjection;
+};
+export type CreateRunInput = {
+    pipelineId: string;
+    taskYaml: string;
+    taskId?: string;
+    checkoutRoot?: string;
+    pipelineDag?: RunPipelineDagSnapshot;
+};
+/**
+ * Persistence port for pipeline run state.
+ * Call sites should prefer CreatedRun.workspaceDir from createRun over
+ * getWorkspaceDir; the latter returns the opaque run workspace root when a
+ * run id is all you have (catalog / rehydrate).
+ */
+export interface RunStore {
+    createRun(input: CreateRunInput): Promise<CreatedRun>;
+    updateRunStatus(runId: string, status: RunStatus): Promise<void>;
+    readRunMeta(runId: string): Promise<RunMeta>;
+    readTaskYaml(runId: string): Promise<string>;
+    /** Opaque run workspace root for agents and artifact tools. */
+    getWorkspaceDir(runId: string): string;
+    ensureStageWorkspace(runId: string, stageId: string): Promise<void>;
+    ensureAttemptWorkspace(runId: string, stageId: string, attempt: number): Promise<void>;
+    createStageExecution(runId: string, stageId: string): Promise<StageExecution>;
+    listStageExecutions(runId: string, stageId: string): Promise<StageExecution[]>;
+    getLatestStageExecution(runId: string, stageId: string): Promise<StageExecution | null>;
+    countStageAttempts(runId: string, stageId: string): Promise<number>;
+    getStageExecution(runId: string, stageId: string, attempt: number): Promise<StageExecution>;
+    updateStageExecution(runId: string, stageId: string, attempt: number, patch: StageExecutionPatch): Promise<void>;
+    writeEnvelope(runId: string, stageId: string, envelope: StageEnvelope, options?: {
+        attempt?: number;
+    }): Promise<void>;
+    readEnvelope(runId: string, stageId: string): Promise<StageEnvelope>;
+    appendStageEvent(runId: string, stageId: string, event: StageLogLine, options?: {
+        attempt?: number;
+    }): Promise<void>;
+    listStageEvents(runId: string, stageId: string, attempt?: number): Promise<StageLogEvent[]>;
+    listRuns(): Promise<RunSummary[]>;
+    readRun(runId: string): Promise<RunDetail>;
+}
+export declare function stageStatusFromEvents(events: StageLogEvent[]): StageSnapshot["status"];
+export declare function deriveStatusFromStages(stages: StageSnapshot[]): RunStatus;

package/dist/runstore/port.js

@@ -0,0 +1,28 @@
+export function stageStatusFromEvents(events) {
+    let status = "pending";
+    for (const ev of events) {
+        if (ev.event === "started" || ev.event === "resumed")
+            status = "running";
+        if (ev.event === "waiting_for_input")
+            status = "waiting_for_input";
+        if (ev.event === "succeeded")
+            status = "succeeded";
+        if (ev.event === "failed")
+            status = "failed";
+    }
+    return status;
+}
+export function deriveStatusFromStages(stages) {
+    if (stages.length === 0)
+        return "created";
+    if (stages.some((s) => s.status === "failed"))
+        return "failed";
+    if (stages.every((s) => s.status === "succeeded"))
+        return "succeeded";
+    if (stages.some((s) => s.status === "running" ||
+        s.status === "waiting_for_input" ||
+        s.status === "succeeded")) {
+        return "running";
+    }
+    return "created";
+}

package/dist/runstore/runProjection.d.ts

@@ -0,0 +1,6 @@
+import type { RunDetail, RunMeta, RunPipelineDagSnapshot, RunSummary, StageSnapshot } from "./port.js";
+export { syntheticPendingSnapshot } from "./syntheticStageSnapshot.js";
+export declare function overlayPlannedStages(stageIds: string[], snapshots: StageSnapshot[]): StageSnapshot[];
+export declare function orderStageSnapshots(stageIds: string[], snapshots: StageSnapshot[]): StageSnapshot[];
+export declare function projectRunSummary(meta: RunMeta, stages: StageSnapshot[]): RunSummary;
+export declare function projectRunDetail(meta: RunMeta, stages: StageSnapshot[], task_yaml: string, dagSnapshot?: RunPipelineDagSnapshot | null): RunDetail;

package/dist/runstore/runProjection.js

@@ -0,0 +1,102 @@
+import { deriveStatusFromStages } from "./port.js";
+import { linearCompatDagSnapshot } from "./pipelineDagSnapshot.js";
+import { syntheticPendingSnapshot } from "./syntheticStageSnapshot.js";
+import { buildPipelineTrack } from "./trackProjection.js";
+export { syntheticPendingSnapshot } from "./syntheticStageSnapshot.js";
+export function overlayPlannedStages(stageIds, snapshots) {
+    const byId = new Map(snapshots.map((s) => [s.stage_id, s]));
+    return stageIds.map((id) => byId.get(id) ?? syntheticPendingSnapshot(id));
+}
+export function orderStageSnapshots(stageIds, snapshots) {
+    return overlayPlannedStages(stageIds, snapshots);
+}
+function compactStages(stages) {
+    return stages.map((s) => ({
+        id: s.stage_id,
+        status: s.status,
+        attempt_count: s.attempt_count,
+    }));
+}
+function waitingSummaryFromPrompt(prompt) {
+    if (!prompt)
+        return "Waiting for input";
+    if (prompt.kind === "multi_question") {
+        const first = prompt.questions[0]?.message?.trim();
+        return first || "Waiting for input";
+    }
+    const message = prompt.message?.trim();
+    return message || "Waiting for input";
+}
+function waitingFieldsFromStages(stages) {
+    const waitingStages = stages.filter((s) => s.status === "waiting_for_input");
+    if (waitingStages.length === 0)
+        return {};
+    const waiting = waitingStages[0];
+    const prompt = waiting.pending_prompt;
+    const fields = {
+        waiting_stage_id: waiting.stage_id,
+        waiting_stage_ids: waitingStages.map((s) => s.stage_id),
+        waiting_summary: waitingSummaryFromPrompt(prompt),
+    };
+    if (prompt) {
+        fields.waiting_kind = prompt.kind;
+        fields.waiting_prompt_id = prompt.id;
+        if (prompt.kind === "artifact_backed") {
+            fields.waiting_artifacts = prompt.artifacts;
+        }
+        if (prompt.kind === "multi_question") {
+            fields.waiting_questions = prompt.questions.map((q) => q.message);
+        }
+    }
+    return fields;
+}
+function failedFieldsFromStages(stages) {
+    const failed = stages.find((s) => s.status === "failed");
+    if (!failed)
+        return {};
+    let failed_reason;
+    for (const ev of failed.events) {
+        if (ev.event === "failed")
+            failed_reason = ev.reason;
+    }
+    return {
+        failed_stage_id: failed.stage_id,
+        ...(failed_reason !== undefined ? { failed_reason } : {}),
+    };
+}
+function resolveListedStatus(stages, meta) {
+    const derived = deriveStatusFromStages(stages);
+    return stages.length > 0 ? derived : (meta.status ?? derived);
+}
+export function projectRunSummary(meta, stages) {
+    return {
+        run_id: meta.run_id,
+        pipeline_id: meta.pipeline_id,
+        task_id: meta.task_id,
+        status: resolveListedStatus(stages, meta),
+        created_at: meta.created_at,
+        updated_at: meta.updated_at,
+        stages: compactStages(stages),
+        ...waitingFieldsFromStages(stages),
+        ...failedFieldsFromStages(stages),
+    };
+}
+export function projectRunDetail(meta, stages, task_yaml, dagSnapshot) {
+    const ordered = dagSnapshot
+        ? overlayPlannedStages(dagSnapshot.stage_ids, stages)
+        : stages;
+    const summary = projectRunSummary(meta, ordered);
+    const snapshot = dagSnapshot ??
+        linearCompatDagSnapshot(ordered.map((s) => s.stage_id));
+    const pipeline_track = buildPipelineTrack({
+        dagSnapshot: snapshot,
+        stages: ordered,
+        runStatus: summary.status,
+    });
+    return {
+        ...summary,
+        task_yaml,
+        stages: ordered,
+        pipeline_track,
+    };
+}

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

@@ -0,0 +1,48 @@
+import type { StageEnvelope } from "../../types/envelope.js";
+import type { StageLogLine } from "../../agent/activity.js";
+import { type CreateRunInput, type CreatedRun, type RunDetail, type RunMeta, type RunStatus, type RunStore, type RunSummary, type StageExecution, type StageExecutionPatch, type StageLogEvent } from "../port.js";
+export declare class SqliteRunStore implements RunStore {
+    private readonly storeRoot;
+    private readonly db;
+    private migratePromise;
+    constructor(storeRoot: string);
+    /** Await one-shot disk import before catalog reads (create paths also wait). */
+    ready(): Promise<void>;
+    getWorkspaceDir(runId: string): string;
+    createRun(input: CreateRunInput): Promise<CreatedRun>;
+    updateRunStatus(runId: string, status: RunStatus): Promise<void>;
+    readRunMeta(runId: string): Promise<RunMeta>;
+    readTaskYaml(runId: string): Promise<string>;
+    ensureStageWorkspace(runId: string, stageId: string): Promise<void>;
+    ensureAttemptWorkspace(runId: string, stageId: string, attempt: number): Promise<void>;
+    createStageExecution(runId: string, stageId: string): Promise<StageExecution>;
+    listStageExecutions(runId: string, stageId: string): Promise<StageExecution[]>;
+    getLatestStageExecution(runId: string, stageId: string): Promise<StageExecution | null>;
+    countStageAttempts(runId: string, stageId: string): Promise<number>;
+    getStageExecution(runId: string, stageId: string, attempt: number): Promise<StageExecution>;
+    updateStageExecution(runId: string, stageId: string, attempt: number, patch: StageExecutionPatch): Promise<void>;
+    writeEnvelope(runId: string, stageId: string, envelope: StageEnvelope, options?: {
+        attempt?: number;
+    }): Promise<void>;
+    readEnvelope(runId: string, stageId: string): Promise<StageEnvelope>;
+    private readEnvelopeFromDb;
+    appendStageEvent(runId: string, stageId: string, event: StageLogLine, options?: {
+        attempt?: number;
+    }): Promise<void>;
+    /**
+     * @remarks Intentional denormalization: mirrors lifecycle events into
+     * `stages.status` for legacy compatibility. This column is not the
+     * authoritative source for snapshot projection; status is event-derived
+     * in `buildStageSnapshotFromStore`.
+     */
+    private updateStageStatusDenorm;
+    listStageEvents(runId: string, stageId: string, attempt?: number): Promise<StageLogEvent[]>;
+    listRuns(): Promise<RunSummary[]>;
+    readRun(runId: string): Promise<RunDetail>;
+    private readPipelineDagSnapshotFromRow;
+    private runMetaFromRow;
+    private getRunRow;
+    private loadEvents;
+    private loadStageSnapshots;
+}
+export declare function openSqliteRunStore(storeRoot: string): SqliteRunStore;