stageflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tejas G
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# Stageflow
+
+CLI pipeline runtime for configurable SDLC stages on [Pi](https://github.com/badlogic/pi-mono), plus a local operator console.
+
+Author YAML pipelines, stages, and tasks in a project directory. Stageflow runs each stage in a fresh Pi agent session, writes a structured handoff envelope, and keeps run state under `.stageflow/`. Bins: **`sf`** and **`stageflow`**.
+
+Requires **Node.js ≥ 20**.
+
+## Install
+
+```bash
+npm i -g stageflow
+# or
+npx stageflow
+```
+
+`better-sqlite3` ships prebuilds for common platforms. `--ignore-scripts` is fine when a prebuild exists. Benign `node-gyp` warnings during install can be ignored if `require("better-sqlite3")` works.
+
+## Quick start
+
+In a project directory, author:
+
+- `pipelines/` — ordered stage lists
+- `stages/` — stage definitions (instructions, model, optional human gates)
+- `tasks/` — work items (goal, pipeline, optional checkout)
+
+```bash
+sf ui                          # operator console at http://127.0.0.1:3847
+sf run --task tasks/foo.yaml --pipeline <pipeline-id>
+```
+
+Connect model providers in the console (Settings → Providers) or via `sf providers …`. Stageflow is a thin Pi shell: reuse an existing Pi login (`pi_home`) or store credentials in an SF-owned file (`sf_owned`). You do not need Pi CLI `/login` as a hard prerequisite.
+
+## State
+
+Runtime state lives in **`.stageflow/`** (SQLite + per-run workspaces under `.stageflow/runs/`). If `.stageflow` is missing and `.software-factory` exists from an older install, the next store open renames it to `.stageflow` once.
+
+## MCP
+
+`sf ui` also serves a Streamable HTTP MCP endpoint at `http://127.0.0.1:3847/mcp` (URL printed on boot). Point a Cursor (or other) MCP client at that URL for tools like `list_pipelines`, `start_run`, and `get_run`.
+
+## Develop from source
+
+```bash
+git clone https://github.com/tejasghutukade/stageflow.git
+cd stageflow
+npm i
+npm run build && npm run ui:build   # ui:build builds the UI and copies assets into dist/ui
+sf ui
+```
+
+## License
+
+MIT © Tejas G
+
+Issues: https://github.com/tejasghutukade/stageflow/issues

package/dist/agent/activity.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Pi-agnostic stage activity events.
+ *
+ * Adapters map provider/SDK events into this vocabulary. Disk, API, UI, and
+ * HITL control planes should speak these types — not Pi's AgentEvent.
+ * Lifecycle `waiting_for_input` / `resumed` are owned by stageRunner (not
+ * adapters).
+ *
+ * `operator_prompt` / `operator_answer` carry full T2 ask-operator payloads.
+ * ACTIVITY_TEXT_LIMIT applies only to tool/message *previews* — never to
+ * those Q&A bodies.
+ */
+import type { AskOperatorAnswer, AskOperatorPrompt } from "../tools/askOperator.js";
+export declare const ACTIVITY_TEXT_LIMIT = 500;
+export type StageActivityEvent = {
+    event: "agent_start";
+} | {
+    event: "agent_end";
+} | {
+    event: "turn_start";
+} | {
+    event: "tool_start";
+    toolName: string;
+    toolCallId?: string;
+    argsPreview?: string;
+} | {
+    event: "tool_end";
+    toolName: string;
+    toolCallId?: string;
+    isError?: boolean;
+    resultPreview?: string;
+} | {
+    event: "message";
+    role: string;
+    text?: string;
+} | {
+    event: "operator_prompt";
+    prompt: AskOperatorPrompt;
+} | {
+    event: "operator_answer";
+    promptId: string;
+    answer: AskOperatorAnswer;
+};
+export type OperatorPromptActivityEvent = Extract<StageActivityEvent, {
+    event: "operator_prompt";
+}>;
+export type OperatorAnswerActivityEvent = Extract<StageActivityEvent, {
+    event: "operator_answer";
+}>;
+/** Lifecycle lines written by stageRunner (not the adapter). */
+export type StageLifecycleEvent = {
+    event: "started";
+} | {
+    event: "waiting_for_input";
+} | {
+    event: "resumed";
+} | {
+    event: "succeeded";
+} | {
+    event: "failed";
+    reason: string;
+};
+export type StageLogLine = StageActivityEvent | StageLifecycleEvent;
+export declare function truncateActivityText(value: unknown, limit?: number): string | undefined;
+export declare function extractMessageText(message: {
+    role?: string;
+    content?: unknown;
+}): {
+    role: string;
+    text?: string;
+};
+/**
+ * Map a loose Pi/session event object into a StageActivityEvent.
+ * Returns null for events we intentionally ignore (e.g. text_delta streams).
+ */
+export declare function mapSessionEventToActivity(event: Record<string, unknown>): StageActivityEvent | null;

package/dist/agent/activity.js

@@ -0,0 +1,89 @@
+/**
+ * Pi-agnostic stage activity events.
+ *
+ * Adapters map provider/SDK events into this vocabulary. Disk, API, UI, and
+ * HITL control planes should speak these types — not Pi's AgentEvent.
+ * Lifecycle `waiting_for_input` / `resumed` are owned by stageRunner (not
+ * adapters).
+ *
+ * `operator_prompt` / `operator_answer` carry full T2 ask-operator payloads.
+ * ACTIVITY_TEXT_LIMIT applies only to tool/message *previews* — never to
+ * those Q&A bodies.
+ */
+export const ACTIVITY_TEXT_LIMIT = 500;
+export function truncateActivityText(value, limit = ACTIVITY_TEXT_LIMIT) {
+    if (value === undefined || value === null)
+        return undefined;
+    let text;
+    if (typeof value === "string") {
+        text = value;
+    }
+    else {
+        try {
+            text = JSON.stringify(value);
+        }
+        catch {
+            text = String(value);
+        }
+    }
+    if (text.length <= limit)
+        return text;
+    return `${text.slice(0, limit)}…`;
+}
+export function extractMessageText(message) {
+    const role = typeof message.role === "string" ? message.role : "unknown";
+    const content = message.content;
+    if (typeof content === "string") {
+        return { role, text: truncateActivityText(content) };
+    }
+    if (!Array.isArray(content)) {
+        return { role };
+    }
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const b = block;
+        if (b.type === "text" && typeof b.text === "string") {
+            parts.push(b.text);
+        }
+    }
+    if (parts.length === 0)
+        return { role };
+    return { role, text: truncateActivityText(parts.join("")) };
+}
+/**
+ * Map a loose Pi/session event object into a StageActivityEvent.
+ * Returns null for events we intentionally ignore (e.g. text_delta streams).
+ */
+export function mapSessionEventToActivity(event) {
+    const type = event.type;
+    if (type === "agent_start")
+        return { event: "agent_start" };
+    if (type === "agent_end")
+        return { event: "agent_end" };
+    if (type === "turn_start")
+        return { event: "turn_start" };
+    if (type === "tool_execution_start") {
+        return {
+            event: "tool_start",
+            toolName: String(event.toolName ?? "unknown"),
+            toolCallId: typeof event.toolCallId === "string" ? event.toolCallId : undefined,
+            argsPreview: truncateActivityText(event.args),
+        };
+    }
+    if (type === "tool_execution_end") {
+        return {
+            event: "tool_end",
+            toolName: String(event.toolName ?? "unknown"),
+            toolCallId: typeof event.toolCallId === "string" ? event.toolCallId : undefined,
+            isError: Boolean(event.isError),
+            resultPreview: truncateActivityText(event.result),
+        };
+    }
+    if (type === "message_end" && event.message && typeof event.message === "object") {
+        const { role, text } = extractMessageText(event.message);
+        return { event: "message", role, text };
+    }
+    return null;
+}

package/dist/agent/activityObserver.d.ts

@@ -0,0 +1,17 @@
+import type { StageActivityEvent } from "./activity.js";
+export type StageActivityObserver = {
+    onAssistantTextDelta(delta: string): void;
+    onStreamBoundary(): void;
+    onActivity(activity: StageActivityEvent): void;
+    dispose(): void;
+};
+export type CreateStageActivityObserverOptions = {
+    onActivity?: (event: StageActivityEvent) => void;
+    writeStderr?: boolean;
+};
+/**
+ * Observe StageActivityEvent milestones and optional assistant text deltas.
+ * Pi (or any adapter) maps provider events to StageActivityEvent before calling
+ * onActivity — Record-shaped SDK events never enter this module.
+ */
+export declare function createStageActivityObserver(options?: CreateStageActivityObserverOptions): StageActivityObserver;

package/dist/agent/activityObserver.js

@@ -0,0 +1,66 @@
+function writeActivityStderr(activity) {
+    switch (activity.event) {
+        case "agent_start":
+            process.stderr.write("  … agent started\n");
+            return;
+        case "agent_end":
+            process.stderr.write("  … agent settled\n");
+            return;
+        case "turn_start":
+            process.stderr.write("  … turn\n");
+            return;
+        case "tool_start":
+            process.stderr.write(`  → ${activity.toolName}\n`);
+            return;
+        case "tool_end":
+            if (activity.isError) {
+                process.stderr.write(`  ✕ ${activity.toolName}\n`);
+            }
+            return;
+        case "message":
+            return;
+    }
+}
+/**
+ * Observe StageActivityEvent milestones and optional assistant text deltas.
+ * Pi (or any adapter) maps provider events to StageActivityEvent before calling
+ * onActivity — Record-shaped SDK events never enter this module.
+ */
+export function createStageActivityObserver(options = {}) {
+    const writeStderr = options.writeStderr !== false;
+    let inAssistantText = false;
+    const endTextLine = () => {
+        if (!inAssistantText) {
+            return;
+        }
+        if (writeStderr) {
+            process.stderr.write("\n");
+        }
+        inAssistantText = false;
+    };
+    return {
+        onAssistantTextDelta(delta) {
+            if (!writeStderr || !delta) {
+                return;
+            }
+            if (!inAssistantText) {
+                process.stderr.write("  ");
+                inAssistantText = true;
+            }
+            process.stderr.write(delta);
+        },
+        onStreamBoundary() {
+            endTextLine();
+        },
+        onActivity(activity) {
+            endTextLine();
+            options.onActivity?.(activity);
+            if (writeStderr) {
+                writeActivityStderr(activity);
+            }
+        },
+        dispose() {
+            endTextLine();
+        },
+    };
+}

package/dist/agent/cursorExtension.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Locate the pi-cursor-sdk extension entry without opening full global package
+ * discovery. Stages stay sealed; only this allowlisted path is loaded.
+ *
+ * Resolution order:
+ * 1. SOFTWARE_FACTORY_CURSOR_EXTENSION (absolute path to the extension .ts/.js)
+ * 2. Path package from ~/.pi/agent/settings.json (same source interactive pi uses)
+ * 3. npm install under ~/.pi/agent/npm/node_modules/pi-cursor-sdk
+ * 4. Sibling checkout at ../pi-cursor-sdk relative to this repo
+ */
+export declare function resolveCursorExtensionPath(): string | undefined;
+export declare function isCursorModelRef(modelRef: string): boolean;

package/dist/agent/cursorExtension.js

@@ -0,0 +1,88 @@
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Locate the pi-cursor-sdk extension entry without opening full global package
+ * discovery. Stages stay sealed; only this allowlisted path is loaded.
+ *
+ * Resolution order:
+ * 1. SOFTWARE_FACTORY_CURSOR_EXTENSION (absolute path to the extension .ts/.js)
+ * 2. Path package from ~/.pi/agent/settings.json (same source interactive pi uses)
+ * 3. npm install under ~/.pi/agent/npm/node_modules/pi-cursor-sdk
+ * 4. Sibling checkout at ../pi-cursor-sdk relative to this repo
+ */
+export function resolveCursorExtensionPath() {
+    const fromEnv = process.env.SOFTWARE_FACTORY_CURSOR_EXTENSION?.trim();
+    if (fromEnv && existsSync(fromEnv)) {
+        return path.resolve(fromEnv);
+    }
+    const fromSettings = resolveFromPiSettings();
+    if (fromSettings) {
+        return fromSettings;
+    }
+    const npmEntry = path.join(os.homedir(), ".pi", "agent", "npm", "node_modules", "pi-cursor-sdk", "src", "index.ts");
+    if (existsSync(npmEntry)) {
+        return npmEntry;
+    }
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const sibling = path.resolve(here, "../../../pi-cursor-sdk/src/index.ts");
+    if (existsSync(sibling)) {
+        return sibling;
+    }
+    return undefined;
+}
+export function isCursorModelRef(modelRef) {
+    const slash = modelRef.indexOf("/");
+    if (slash <= 0) {
+        return false;
+    }
+    return modelRef.slice(0, slash).toLowerCase() === "cursor";
+}
+function resolveFromPiSettings() {
+    const settingsPath = path.join(os.homedir(), ".pi", "agent", "settings.json");
+    if (!existsSync(settingsPath)) {
+        return undefined;
+    }
+    let settings;
+    try {
+        settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(settings.packages)) {
+        return undefined;
+    }
+    const agentDir = path.join(os.homedir(), ".pi", "agent");
+    for (const entry of settings.packages) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            continue;
+        }
+        const pkg = entry;
+        if (typeof pkg.source !== "string") {
+            continue;
+        }
+        if (!pkg.source.includes("pi-cursor-sdk")) {
+            continue;
+        }
+        const packageRoot = path.resolve(agentDir, pkg.source);
+        if (Array.isArray(pkg.extensions)) {
+            for (const ext of pkg.extensions) {
+                if (typeof ext !== "string") {
+                    continue;
+                }
+                const rel = ext.replace(/^\+/, "");
+                const full = path.resolve(packageRoot, rel);
+                if (existsSync(full)) {
+                    return full;
+                }
+            }
+        }
+        const declared = path.join(packageRoot, "src", "index.ts");
+        if (existsSync(declared)) {
+            return declared;
+        }
+    }
+    return undefined;
+}

package/dist/agent/cursorProvider.d.ts

@@ -0,0 +1,14 @@
+import { type StageProviderSupport } from "./providerSupport.js";
+/**
+ * Locate the pi-cursor-sdk extension entry without opening full global package
+ * discovery. Stages stay sealed; only this allowlisted path is loaded.
+ *
+ * Resolution order:
+ * 1. STAGEFLOW_CURSOR_EXTENSION (absolute path to the extension .ts/.js)
+ * 2. Path package from ~/.pi/agent/settings.json (same source interactive pi uses)
+ * 3. npm install under ~/.pi/agent/npm/node_modules/pi-cursor-sdk
+ * 4. Sibling checkout at ../pi-cursor-sdk relative to this repo
+ */
+export declare function resolveCursorExtensionPath(): string | undefined;
+export declare function isCursorModelRef(modelRef: string): boolean;
+export declare const cursorProviderSupport: StageProviderSupport;

package/dist/agent/cursorProvider.js

@@ -0,0 +1,139 @@
+/**
+ * Cursor-only StageProviderSupport for pi-cursor-sdk.
+ *
+ * Loaded only when stage.model is `cursor/...`. Other providers never hit this
+ * module's prepare()/env sealing path.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { registerProviderSupport, } from "./providerSupport.js";
+const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
+/**
+ * Locate the pi-cursor-sdk extension entry without opening full global package
+ * discovery. Stages stay sealed; only this allowlisted path is loaded.
+ *
+ * Resolution order:
+ * 1. STAGEFLOW_CURSOR_EXTENSION (absolute path to the extension .ts/.js)
+ * 2. Path package from ~/.pi/agent/settings.json (same source interactive pi uses)
+ * 3. npm install under ~/.pi/agent/npm/node_modules/pi-cursor-sdk
+ * 4. Sibling checkout at ../pi-cursor-sdk relative to this repo
+ */
+export function resolveCursorExtensionPath() {
+    const fromEnv = process.env.STAGEFLOW_CURSOR_EXTENSION?.trim();
+    if (fromEnv && existsSync(fromEnv)) {
+        return path.resolve(fromEnv);
+    }
+    const fromSettings = resolveFromPiSettings();
+    if (fromSettings) {
+        return fromSettings;
+    }
+    const npmEntry = path.join(os.homedir(), ".pi", "agent", "npm", "node_modules", "pi-cursor-sdk", "src", "index.ts");
+    if (existsSync(npmEntry)) {
+        return npmEntry;
+    }
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const sibling = path.resolve(here, "../../../pi-cursor-sdk/src/index.ts");
+    if (existsSync(sibling)) {
+        return sibling;
+    }
+    return undefined;
+}
+export function isCursorModelRef(modelRef) {
+    const slash = modelRef.indexOf("/");
+    if (slash <= 0) {
+        return false;
+    }
+    return modelRef.slice(0, slash).toLowerCase() === "cursor";
+}
+function sealCursorSettingSources() {
+    if (process.env[CURSOR_SETTING_SOURCES_ENV] !== undefined) {
+        return undefined;
+    }
+    process.env[CURSOR_SETTING_SOURCES_ENV] = "none";
+    return () => {
+        delete process.env[CURSOR_SETTING_SOURCES_ENV];
+    };
+}
+function missingExtensionReason(modelRef) {
+    return [
+        `Model "${modelRef}" requires pi-cursor-sdk, but no extension entry was found.`,
+        "Install with `pi install npm:pi-cursor-sdk`, or set STAGEFLOW_CURSOR_EXTENSION",
+        "to the absolute path of pi-cursor-sdk/src/index.ts.",
+        "Also ensure a Cursor SDK API key is available via Pi /login or CURSOR_API_KEY.",
+    ].join(" ");
+}
+function prepareCursor(modelRef) {
+    const extensionPath = resolveCursorExtensionPath();
+    if (!extensionPath) {
+        return { extensionPaths: [], error: missingExtensionReason(modelRef) };
+    }
+    return {
+        extensionPaths: [extensionPath],
+        // pi-cursor-sdk defaults to settingSources ["all"]. Seal ambient Cursor
+        // rules/plugins/MCP for isolated stages unless the operator already set it.
+        restore: sealCursorSettingSources(),
+    };
+}
+export const cursorProviderSupport = {
+    id: "cursor",
+    matches: isCursorModelRef,
+    prepare: prepareCursor,
+    emitToolHint(toolName) {
+        return [
+            `Required final action: call the MCP tool pi__${toolName} exactly once`,
+            `(pi name: ${toolName}) with status, summary, and artifacts (run-relative paths)`,
+            "and a payload matching the stage payload_schema when one is defined.",
+            "Do not stop after writing files — the stage only completes when that tool returns.",
+        ].join(" ");
+    },
+};
+registerProviderSupport(cursorProviderSupport);
+function resolveFromPiSettings() {
+    const settingsPath = path.join(os.homedir(), ".pi", "agent", "settings.json");
+    if (!existsSync(settingsPath)) {
+        return undefined;
+    }
+    let settings;
+    try {
+        settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(settings.packages)) {
+        return undefined;
+    }
+    const agentDir = path.join(os.homedir(), ".pi", "agent");
+    for (const entry of settings.packages) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            continue;
+        }
+        const pkg = entry;
+        if (typeof pkg.source !== "string") {
+            continue;
+        }
+        if (!pkg.source.includes("pi-cursor-sdk")) {
+            continue;
+        }
+        const packageRoot = path.resolve(agentDir, pkg.source);
+        if (Array.isArray(pkg.extensions)) {
+            for (const ext of pkg.extensions) {
+                if (typeof ext !== "string") {
+                    continue;
+                }
+                const rel = ext.replace(/^\+/, "");
+                const full = path.resolve(packageRoot, rel);
+                if (existsSync(full)) {
+                    return full;
+                }
+            }
+        }
+        const declared = path.join(packageRoot, "src", "index.ts");
+        if (existsSync(declared)) {
+            return declared;
+        }
+    }
+    return undefined;
+}

package/dist/agent/fakeAgent.d.ts

@@ -0,0 +1,29 @@
+import type { StageRoots } from "../runtime/stageRoots.js";
+import type { AgentPort, OpaqueAnswer, OpaqueWaitRequest, StageHandle, StageRunInput, StageRunResult } from "./port.js";
+export type FakeAgentBehavior = {
+    type: "emit";
+    envelope: unknown;
+} | {
+    type: "never_emit";
+} | {
+    type: "throw";
+    message: string;
+} | {
+    type: "wait_then_emit";
+    waitRequests: OpaqueWaitRequest[];
+    expectedAnswers?: OpaqueAnswer[];
+    envelope: unknown;
+};
+export type RecordedStageRoots = StageRoots;
+export declare function fakeHitlResumePath(roots: Pick<StageRoots, "runWorkspaceDir">, stageId: string): string;
+export declare class FakeAgent implements AgentPort {
+    private readonly behavior;
+    lastRoots?: RecordedStageRoots;
+    receivedAnswers: OpaqueAnswer[];
+    constructor(behavior: FakeAgentBehavior);
+    openStage(input: StageRunInput): StageHandle;
+    runStage(input: StageRunInput): Promise<StageRunResult>;
+}
+export declare function scriptedFakeAgent(behaviors: FakeAgentBehavior[]): AgentPort & {
+    recorded: RecordedStageRoots[];
+};