stageflow 0.1.0

package/dist/envelope/payloadSchema.d.ts

@@ -0,0 +1,10 @@
+import type { TSchema } from "typebox/type";
+import { type StageEnvelope } from "../types/envelope.js";
+export type CompiledPayloadSchema = TSchema;
+/**
+ * Compile a JSON Schema subset used for stage payload_schema.
+ * Supported: type object/string/number/integer/boolean/array,
+ * properties, required, items, additionalProperties (boolean).
+ */
+export declare function compilePayloadSchema(raw: unknown): CompiledPayloadSchema;
+export declare function assertEnvelopePayload(envelope: StageEnvelope, payloadSchema: unknown | undefined): void;

package/dist/envelope/payloadSchema.js

@@ -0,0 +1,91 @@
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { EnvelopeError } from "../types/envelope.js";
+function compileNode(node, path) {
+    if (node === null || typeof node !== "object" || Array.isArray(node)) {
+        throw new Error(`${path}: schema must be an object`);
+    }
+    const schema = node;
+    if (typeof schema.type !== "string") {
+        throw new Error(`${path}: type is required`);
+    }
+    switch (schema.type) {
+        case "string":
+            return Type.String();
+        case "number":
+            return Type.Number();
+        case "integer":
+            return Type.Integer();
+        case "boolean":
+            return Type.Boolean();
+        case "array": {
+            if (schema.items === undefined) {
+                throw new Error(`${path}: array requires items`);
+            }
+            return Type.Array(compileNode(schema.items, `${path}.items`));
+        }
+        case "object": {
+            const properties = schema.properties ?? {};
+            if (properties === null ||
+                typeof properties !== "object" ||
+                Array.isArray(properties)) {
+                throw new Error(`${path}: properties must be an object when present`);
+            }
+            const requiredList = schema.required ?? [];
+            if (!Array.isArray(requiredList) ||
+                !requiredList.every((k) => typeof k === "string")) {
+                throw new Error(`${path}: required must be an array of strings when present`);
+            }
+            const required = new Set(requiredList);
+            if (schema.additionalProperties !== undefined &&
+                typeof schema.additionalProperties !== "boolean") {
+                throw new Error(`${path}: additionalProperties must be a boolean when present`);
+            }
+            const compiledProps = {};
+            for (const [key, value] of Object.entries(properties)) {
+                const propSchema = compileNode(value, `${path}.properties.${key}`);
+                compiledProps[key] = required.has(key)
+                    ? propSchema
+                    : Type.Optional(propSchema);
+            }
+            const options = schema.additionalProperties === false
+                ? { additionalProperties: false }
+                : undefined;
+            return Type.Object(compiledProps, options);
+        }
+        default:
+            throw new Error(`${path}: unsupported type "${schema.type}" (supported: object, string, number, integer, boolean, array)`);
+    }
+}
+/**
+ * Compile a JSON Schema subset used for stage payload_schema.
+ * Supported: type object/string/number/integer/boolean/array,
+ * properties, required, items, additionalProperties (boolean).
+ */
+export function compilePayloadSchema(raw) {
+    const compiled = compileNode(raw, "payload_schema");
+    if (!Type.IsObject(compiled)) {
+        throw new Error("payload_schema: root type must be object");
+    }
+    return compiled;
+}
+export function assertEnvelopePayload(envelope, payloadSchema) {
+    if (payloadSchema === undefined) {
+        return;
+    }
+    if (envelope.status !== "success") {
+        return;
+    }
+    const schema = compilePayloadSchema(payloadSchema);
+    if (envelope.payload === undefined) {
+        throw new EnvelopeError("payload is required by stage payload_schema");
+    }
+    if (!Value.Check(schema, envelope.payload)) {
+        const details = [...Value.Errors(schema, envelope.payload)]
+            .map((err) => `${err.instancePath || "/"} ${err.message}`)
+            .join("; ");
+        throw new EnvelopeError(details
+            ? `payload does not match payload_schema: ${details}`
+            : "payload does not match payload_schema");
+    }
+}

package/dist/hitl/qaTrail.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Durable Q&A trail — public entry for operator prompt/answer activity events.
+ *
+ * Event shapes live on StageActivityEvent; this module re-exports them,
+ * provides narrow guards, append helpers, and pure pending/history derivation.
+ */
+import type { OperatorAnswerActivityEvent, OperatorPromptActivityEvent, StageActivityEvent, StageLogLine } from "../agent/activity.js";
+import type { RunStore, StageLogEvent } from "../runstore/port.js";
+import type { AskOperatorAnswer, AskOperatorPrompt } from "../tools/askOperator.js";
+export type { OperatorAnswerActivityEvent, OperatorPromptActivityEvent, } from "../agent/activity.js";
+export type { AskOperatorAnswer, AskOperatorPrompt } from "../tools/askOperator.js";
+export type QaExchange = {
+    prompt: AskOperatorPrompt;
+    answer: AskOperatorAnswer | null;
+};
+export declare class QaTrailInvariantError extends Error {
+    readonly code: "R8_MULTIPLE_PENDING_PROMPTS";
+    constructor(message?: string);
+}
+export declare function isOperatorPromptEvent(event: StageLogLine | StageActivityEvent): event is OperatorPromptActivityEvent;
+export declare function isOperatorAnswerEvent(event: StageLogLine | StageActivityEvent): event is OperatorAnswerActivityEvent;
+export declare function operatorPromptEvent(prompt: AskOperatorPrompt): OperatorPromptActivityEvent;
+export declare function operatorAnswerEvent(answer: AskOperatorAnswer): OperatorAnswerActivityEvent;
+export declare function appendOperatorPrompt(store: RunStore, runId: string, stageId: string, prompt: AskOperatorPrompt, options?: {
+    attempt?: number;
+}): Promise<void>;
+export declare function appendOperatorAnswer(store: RunStore, runId: string, stageId: string, answer: AskOperatorAnswer, options?: {
+    attempt?: number;
+}): Promise<void>;
+export declare function listQaExchanges(events: readonly StageLogEvent[]): QaExchange[];
+export declare function derivePendingPrompt(events: readonly StageLogEvent[]): AskOperatorPrompt | null;

package/dist/hitl/qaTrail.js

@@ -0,0 +1,65 @@
+/**
+ * Durable Q&A trail — public entry for operator prompt/answer activity events.
+ *
+ * Event shapes live on StageActivityEvent; this module re-exports them,
+ * provides narrow guards, append helpers, and pure pending/history derivation.
+ */
+export class QaTrailInvariantError extends Error {
+    code = "R8_MULTIPLE_PENDING_PROMPTS";
+    constructor(message = "Q&A trail has more than one pending operator prompt (R8)") {
+        super(message);
+        this.name = "QaTrailInvariantError";
+    }
+}
+export function isOperatorPromptEvent(event) {
+    return event.event === "operator_prompt";
+}
+export function isOperatorAnswerEvent(event) {
+    return event.event === "operator_answer";
+}
+export function operatorPromptEvent(prompt) {
+    return { event: "operator_prompt", prompt };
+}
+export function operatorAnswerEvent(answer) {
+    return {
+        event: "operator_answer",
+        promptId: answer.promptId,
+        answer,
+    };
+}
+export async function appendOperatorPrompt(store, runId, stageId, prompt, options) {
+    await store.appendStageEvent(runId, stageId, operatorPromptEvent(prompt), options);
+}
+export async function appendOperatorAnswer(store, runId, stageId, answer, options) {
+    await store.appendStageEvent(runId, stageId, operatorAnswerEvent(answer), options);
+}
+function collectQaExchanges(events) {
+    const exchanges = [];
+    for (const event of events) {
+        if (isOperatorPromptEvent(event)) {
+            exchanges.push({ prompt: event.prompt, answer: null });
+            continue;
+        }
+        if (isOperatorAnswerEvent(event)) {
+            const open = exchanges.find((ex) => ex.answer === null && ex.prompt.id === event.promptId);
+            if (open)
+                open.answer = event.answer;
+        }
+    }
+    return exchanges;
+}
+function assertAtMostOnePending(exchanges) {
+    const pendingCount = exchanges.reduce((n, ex) => n + (ex.answer === null ? 1 : 0), 0);
+    if (pendingCount > 1) {
+        throw new QaTrailInvariantError();
+    }
+}
+export function listQaExchanges(events) {
+    const exchanges = collectQaExchanges(events);
+    assertAtMostOnePending(exchanges);
+    return exchanges;
+}
+export function derivePendingPrompt(events) {
+    const pending = listQaExchanges(events).find((ex) => ex.answer === null);
+    return pending?.prompt ?? null;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { PACKAGE_NAME } 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 { StageActivityEvent, StageLogLine } from "./agent/activity.js";
+export type { StageRoots } from "./runtime/stageRoots.js";
+export { runPipeline, startPipeline } from "./runtime/pipelineRunner.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";
+export { deriveStatusFromStages } from "./runstore/port.js";
+export { RunManager } from "./runtime/runManager.js";
+export { startUiServer } from "./server/http.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { PACKAGE_NAME } from "./package-meta.js";
+export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
+export { runPipeline, startPipeline } from "./runtime/pipelineRunner.js";
+export { createRunStore } from "./runstore/createStore.js";
+export { deriveStatusFromStages } from "./runstore/port.js";
+export { RunManager } from "./runtime/runManager.js";
+export { startUiServer } from "./server/http.js";

package/dist/mcp/projectRun.d.ts

@@ -0,0 +1,37 @@
+import type { RunDetail, StageSnapshot } from "../runstore/port.js";
+import type { PipelineTrackProjection, RunSummary } from "../runstore/port.js";
+import type { AskOperatorPrompt } from "../tools/askOperator.js";
+import type { StageEnvelope } from "../types/envelope.js";
+export type McpStageProjection = {
+    stage_id: string;
+    status: StageSnapshot["status"];
+    envelope: {
+        status: StageEnvelope["status"];
+        summary: string;
+        artifacts: string[];
+        payload?: Record<string, unknown>;
+    } | null;
+    artifacts: string[];
+    last_at?: string;
+    pending_prompt?: AskOperatorPrompt;
+};
+export type McpRunProjection = {
+    run_id: string;
+    pipeline_id: string;
+    task_id?: string;
+    status: RunDetail["status"];
+    created_at: string;
+    updated_at?: string;
+    stages: McpStageProjection[];
+    pipeline_track: PipelineTrackProjection;
+    waiting_stage_id?: RunSummary["waiting_stage_id"];
+    waiting_stage_ids?: RunSummary["waiting_stage_ids"];
+    waiting_summary?: RunSummary["waiting_summary"];
+    waiting_kind?: RunSummary["waiting_kind"];
+    waiting_prompt_id?: RunSummary["waiting_prompt_id"];
+    waiting_artifacts?: RunSummary["waiting_artifacts"];
+    waiting_questions?: RunSummary["waiting_questions"];
+    failed_stage_id?: RunSummary["failed_stage_id"];
+    failed_reason?: RunSummary["failed_reason"];
+};
+export declare function projectRunForMcp(detail: RunDetail): McpRunProjection;

package/dist/mcp/projectRun.js

@@ -0,0 +1,57 @@
+export function projectRunForMcp(detail) {
+    return {
+        run_id: detail.run_id,
+        pipeline_id: detail.pipeline_id,
+        task_id: detail.task_id,
+        status: detail.status,
+        created_at: detail.created_at,
+        updated_at: detail.updated_at,
+        pipeline_track: detail.pipeline_track,
+        ...(detail.waiting_stage_id !== undefined
+            ? { waiting_stage_id: detail.waiting_stage_id }
+            : {}),
+        ...(detail.waiting_stage_ids !== undefined
+            ? { waiting_stage_ids: detail.waiting_stage_ids }
+            : {}),
+        ...(detail.waiting_summary !== undefined
+            ? { waiting_summary: detail.waiting_summary }
+            : {}),
+        ...(detail.waiting_kind !== undefined
+            ? { waiting_kind: detail.waiting_kind }
+            : {}),
+        ...(detail.waiting_prompt_id !== undefined
+            ? { waiting_prompt_id: detail.waiting_prompt_id }
+            : {}),
+        ...(detail.waiting_artifacts !== undefined
+            ? { waiting_artifacts: detail.waiting_artifacts }
+            : {}),
+        ...(detail.waiting_questions !== undefined
+            ? { waiting_questions: detail.waiting_questions }
+            : {}),
+        ...(detail.failed_stage_id !== undefined
+            ? { failed_stage_id: detail.failed_stage_id }
+            : {}),
+        ...(detail.failed_reason !== undefined
+            ? { failed_reason: detail.failed_reason }
+            : {}),
+        stages: detail.stages.map((stage) => ({
+            stage_id: stage.stage_id,
+            status: stage.status,
+            envelope: stage.envelope
+                ? {
+                    status: stage.envelope.status,
+                    summary: stage.envelope.summary,
+                    artifacts: stage.envelope.artifacts,
+                    ...(stage.envelope.payload !== undefined
+                        ? { payload: stage.envelope.payload }
+                        : {}),
+                }
+                : null,
+            artifacts: stage.artifacts,
+            last_at: stage.last_at,
+            ...(stage.pending_prompt
+                ? { pending_prompt: stage.pending_prompt }
+                : {}),
+        })),
+    };
+}

package/dist/mcp/readArtifact.d.ts

@@ -0,0 +1,2 @@
+import type { RunStore } from "../runstore/port.js";
+export declare function readRunArtifact(store: RunStore, runId: string, relativePath: string): Promise<string>;

package/dist/mcp/readArtifact.js

@@ -0,0 +1,46 @@
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { isInsideDir } from "../runstore/workspaceLayout.js";
+function assertSafeRunId(runId) {
+    if (typeof runId !== "string" || runId.trim().length === 0) {
+        throw new Error("runId must be a non-empty string");
+    }
+    if (runId.includes("..") ||
+        runId.includes("/") ||
+        runId.includes("\\") ||
+        path.isAbsolute(runId)) {
+        throw new Error("runId must not contain path separators or ..");
+    }
+}
+export async function readRunArtifact(store, runId, relativePath) {
+    assertSafeRunId(runId);
+    if (typeof relativePath !== "string" || relativePath.trim().length === 0) {
+        throw new Error("path must be a non-empty string");
+    }
+    if (path.isAbsolute(relativePath)) {
+        throw new Error("path must be relative to the run workspace");
+    }
+    const segments = relativePath.split(/[/\\]/);
+    if (segments.some((segment) => segment === "..")) {
+        throw new Error("path must not contain .. segments");
+    }
+    if (segments.some((segment) => segment === ".pi-agent") ||
+        path.basename(relativePath) === "auth.json") {
+        throw new Error("Artifact path denied");
+    }
+    await store.readRunMeta(runId);
+    const workspaceDir = store.getWorkspaceDir(runId);
+    const workspaceReal = await realpath(workspaceDir);
+    const candidate = path.resolve(workspaceDir, relativePath);
+    let fileReal;
+    try {
+        fileReal = await realpath(candidate);
+    }
+    catch {
+        throw new Error(`Artifact not found: ${relativePath}`);
+    }
+    if (!isInsideDir(fileReal, workspaceReal)) {
+        throw new Error("path escapes the run workspace");
+    }
+    return readFile(fileReal, "utf8");
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,7 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { McpServer } from "@modelcontextprotocol/server";
+import { type McpToolDeps } from "./tools.js";
+export type { McpToolDeps };
+export declare function createStageflowMcpServer(deps: McpToolDeps): McpServer;
+/** Stateless Streamable HTTP: new server + transport per request. */
+export declare function handleMcpHttpRequest(req: IncomingMessage, res: ServerResponse, deps: McpToolDeps): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,26 @@
+import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
+import { McpServer } from "@modelcontextprotocol/server";
+import { registerMcpTools } from "./tools.js";
+export function createStageflowMcpServer(deps) {
+    const server = new McpServer({
+        name: "stageflow",
+        version: "0.1.0",
+    });
+    registerMcpTools(server, deps);
+    return server;
+}
+/** Stateless Streamable HTTP: new server + transport per request. */
+export async function handleMcpHttpRequest(req, res, deps) {
+    const server = createStageflowMcpServer(deps);
+    const transport = new NodeStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+    });
+    try {
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+    }
+    finally {
+        await transport.close().catch(() => undefined);
+        await server.close().catch(() => undefined);
+    }
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { RunStore } from "../runstore/port.js";
+import type { RunManager } from "../runtime/runManager.js";
+export type McpToolDeps = {
+    manager: RunManager;
+    store: RunStore;
+    cwd: string;
+};
+export declare function registerMcpTools(server: McpServer, deps: McpToolDeps): void;

package/dist/mcp/tools.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { listPipelines } from "../config/listConfig.js";
+import { projectRunForMcp } from "./projectRun.js";
+import { readRunArtifact } from "./readArtifact.js";
+const taskFileSchema = z.object({
+    id: z.string(),
+    goal: z.string(),
+    context: z.string().optional(),
+    constraints: z.string().optional(),
+    checkout: z.string().optional(),
+});
+function textResult(data, isError = false) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+export function registerMcpTools(server, deps) {
+    const { manager, store, cwd } = deps;
+    server.registerTool("list_pipelines", {
+        description: "List runnable pipeline ids from the factory cwd",
+        inputSchema: z.object({}),
+    }, async () => {
+        const pipelines = await listPipelines(cwd);
+        return textResult({ pipelines });
+    });
+    server.registerTool("list_runs", {
+        description: "List known pipeline runs",
+        inputSchema: z.object({}),
+    }, async () => {
+        const runs = await store.listRuns();
+        return textResult({ runs });
+    });
+    server.registerTool("get_health", {
+        description: "Server health and soft-max run capacity: activeRunIds, activeCount, maxConcurrent, slotsAvailable. Start until slotsAvailable is 0; then wait for a run to finish or raise STAGEFLOW_MAX_CONCURRENT_RUNS.",
+        inputSchema: z.object({}),
+    }, async () => textResult(manager.getHealth()));
+    server.registerTool("start_run", {
+        description: "Start a pipeline with an inline TaskFile (not written under tasks/). Returns { runId }. On conflict returns isError with code busy_capacity (soft max full) or busy_checkout (same checkout leased), plus activeCount/maxConcurrent/activeRunIds and optional conflictingRunId/conflictingCheckout.",
+        inputSchema: z.object({
+            pipeline: z.string(),
+            task: taskFileSchema,
+        }),
+    }, async ({ pipeline, task }) => {
+        if (!pipeline.trim()) {
+            return textResult({ error: "pipeline is required" }, true);
+        }
+        const result = await manager.startRun({ pipeline, task });
+        if (!result.ok) {
+            const { ok: _ok, reason, ...rest } = result;
+            return textResult({ error: reason, ...rest }, true);
+        }
+        return textResult({ runId: result.runId });
+    });
+    server.registerTool("get_run", {
+        description: "Poll a run: status, stage statuses, and envelope summary/payload/artifact paths (no events).",
+        inputSchema: z.object({
+            runId: z.string(),
+        }),
+    }, async ({ runId }) => {
+        try {
+            const detail = await store.readRun(runId);
+            return textResult(projectRunForMcp(detail));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const notFound = /not found|no such|unknown run/i.test(message);
+            return textResult({
+                error: message,
+                status: notFound ? 404 : 500,
+            }, true);
+        }
+    });
+    server.registerTool("read_artifact", {
+        description: "Read a text artifact from a run workspace by relative path (contained under the run workspace).",
+        inputSchema: z.object({
+            runId: z.string(),
+            path: z.string(),
+        }),
+    }, async ({ runId, path: artifactPath }) => {
+        try {
+            const content = await readRunArtifact(store, runId, artifactPath);
+            return textResult({ runId, path: artifactPath, content });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const notFound = message.startsWith("Run not found") ||
+                message.startsWith("Artifact not found") ||
+                /no such|not found/i.test(message);
+            return textResult({
+                error: message,
+                status: notFound ? 404 : 400,
+            }, true);
+        }
+    });
+}

package/dist/package-meta.d.ts

@@ -0,0 +1 @@
+export declare const PACKAGE_NAME = "stageflow";

package/dist/package-meta.js

@@ -0,0 +1 @@
+export const PACKAGE_NAME = "stageflow";

package/dist/prompt/priorEnvelope.d.ts

@@ -0,0 +1,2 @@
+import type { StageEnvelope } from "../types/envelope.js";
+export declare function formatPriorEnvelope(priorEnvelope: StageEnvelope | null): string;

package/dist/prompt/priorEnvelope.js

@@ -0,0 +1,5 @@
+export function formatPriorEnvelope(priorEnvelope) {
+    return priorEnvelope === null
+        ? "No prior envelope (first stage)."
+        : `Prior envelope JSON:\n${JSON.stringify(priorEnvelope, null, 2)}`;
+}

package/dist/runstore/catalog.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @deprecated Prefer RunStore.listRuns / readRun via createRunStore.
+ */
+export { deriveStatusFromStages, type StageLogEvent, type StageSnapshot, type RunSummary, type RunDetail, } from "./port.js";
+import type { RunDetail, RunSummary, StageLogEvent } from "./port.js";
+export declare function listRuns(rootDir: string): Promise<RunSummary[]>;
+export declare function readRun(rootDir: string, runId: string): Promise<RunDetail>;
+export declare function readStageLog(runDir: string, stageId: string): Promise<StageLogEvent[]>;

package/dist/runstore/catalog.js

@@ -0,0 +1,16 @@
+/**
+ * @deprecated Prefer RunStore.listRuns / readRun via createRunStore.
+ */
+export { deriveStatusFromStages, } from "./port.js";
+import { DiskRunStore } from "./disk/DiskRunStore.js";
+import { storeRootFor } from "./paths.js";
+import { readStageLogFromDisk } from "./disk/catalogHelpers.js";
+export async function listRuns(rootDir) {
+    return new DiskRunStore(storeRootFor(rootDir)).listRuns();
+}
+export async function readRun(rootDir, runId) {
+    return new DiskRunStore(storeRootFor(rootDir)).readRun(runId);
+}
+export async function readStageLog(runDir, stageId) {
+    return readStageLogFromDisk(runDir, stageId);
+}

package/dist/runstore/createStore.d.ts

@@ -0,0 +1,15 @@
+import type { RunStore } from "./port.js";
+export type RunStoreKind = "sqlite";
+export type RunStoreConfig = {
+    /** Project / factory root. Store data lives under `<rootDir>/.stageflow`. */
+    rootDir: string;
+    /** Defaults to `SF_STORE` env or `"sqlite"`. */
+    kind?: RunStoreKind | "disk";
+};
+export declare const DISK_STORE_REJECTED = "SF_STORE=disk is no longer a live RunStore. SQLite is the only adapter. Disk-era .stageflow/runs trees import automatically when the SQLite store is empty.";
+/**
+ * Factory at the application edge. Call sites should receive the returned `RunStore`
+ * and must not branch on backend kind.
+ */
+export declare function createRunStore(config: RunStoreConfig): RunStore;
+export type { RunStore };

package/dist/runstore/createStore.js

@@ -0,0 +1,23 @@
+import { mkdirSync } from "node:fs";
+import { migrateLegacyStoreRoot, storeRootFor } from "./paths.js";
+import { SqliteRunStore } from "./sqlite/SqliteRunStore.js";
+export const DISK_STORE_REJECTED = "SF_STORE=disk is no longer a live RunStore. SQLite is the only adapter. Disk-era .stageflow/runs trees import automatically when the SQLite store is empty.";
+function resolveKind(kind) {
+    const raw = kind ?? process.env.SF_STORE?.trim().toLowerCase();
+    if (raw === "disk") {
+        console.error(DISK_STORE_REJECTED);
+        throw new Error(DISK_STORE_REJECTED);
+    }
+    return "sqlite";
+}
+/**
+ * Factory at the application edge. Call sites should receive the returned `RunStore`
+ * and must not branch on backend kind.
+ */
+export function createRunStore(config) {
+    resolveKind(config.kind);
+    migrateLegacyStoreRoot(config.rootDir);
+    const storeRoot = storeRootFor(config.rootDir);
+    mkdirSync(storeRoot, { recursive: true });
+    return new SqliteRunStore(storeRoot);
+}

package/dist/runstore/disk/DiskRunStore.d.ts

@@ -0,0 +1,30 @@
+import type { StageEnvelope } from "../../types/envelope.js";
+import type { StageLogLine } from "../../agent/activity.js";
+import type { CreateRunInput, CreatedRun, RunMeta, RunStatus, RunStore, StageExecution, StageExecutionPatch, StageLogEvent } from "../port.js";
+export declare class DiskRunStore implements RunStore {
+    private readonly storeRoot;
+    constructor(storeRoot: string);
+    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>;
+    appendStageEvent(runId: string, stageId: string, event: StageLogLine, options?: {
+        attempt?: number;
+    }): Promise<void>;
+    listStageEvents(runId: string, stageId: string, attempt?: number): Promise<StageLogEvent[]>;
+    listRuns(): Promise<import("../port.js").RunSummary[]>;
+    readRun(runId: string): Promise<import("../port.js").RunDetail>;
+}