stageflow 0.25.0 → 0.30.0

package/dist/operatorAgent/docsRetrieval.js

@@ -0,0 +1,269 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const CORPUS = [
+    {
+        path: "docs/yaml-catalog.md",
+        kind: "doc",
+        title: "YAML catalog",
+        topics: [
+            "yaml",
+            "catalog",
+            "io",
+            "verify",
+            "on_verify_fail",
+            "route",
+            "entry",
+            "clone",
+            "clone-chain",
+            "feedback",
+            "loop",
+            "mcp",
+            "dag",
+            "linear",
+        ],
+    },
+    {
+        path: "docs/envelopes.md",
+        kind: "doc",
+        title: "Envelopes",
+        topics: ["envelope", "artifacts", "emit", "payload", "summary", "status"],
+    },
+    {
+        path: "docs/hitl.md",
+        kind: "doc",
+        title: "HITL",
+        topics: [
+            "hitl",
+            "ask_operator",
+            "gate",
+            "gate_kinds",
+            "confirm",
+            "free_text",
+            "artifact_backed",
+        ],
+    },
+    {
+        path: "docs/verified-stage-execution.md",
+        kind: "doc",
+        title: "Verified stage execution",
+        topics: [
+            "verify",
+            "vse",
+            "recovery",
+            "repair",
+            "manual",
+            "on_verify_fail",
+            "after",
+        ],
+    },
+    {
+        path: "docs/mcp.md",
+        kind: "doc",
+        title: "MCP",
+        topics: ["mcp", "tools", "stageflow", "server"],
+    },
+    {
+        path: "examples/README.md",
+        kind: "example",
+        title: "Examples index",
+        topics: ["examples", "walkthrough", "catalog"],
+    },
+    {
+        path: "examples/hello-world/README.md",
+        kind: "example",
+        title: "hello-world",
+        topics: ["hello", "linear", "task.input", "io"],
+    },
+    {
+        path: "examples/plan-review/README.md",
+        kind: "example",
+        title: "plan-review",
+        topics: ["plan", "review", "hitl", "gate", "multi-stage"],
+    },
+    {
+        path: "examples/conditional-fork/README.md",
+        kind: "example",
+        title: "conditional-fork",
+        topics: ["fork", "route", "if", "branch", "hitl"],
+    },
+    {
+        path: "examples/feedback-loop/README.md",
+        kind: "example",
+        title: "feedback-loop",
+        topics: ["feedback", "loop", "send_back", "continue", "replay"],
+    },
+    {
+        path: "examples/feature-loop/README.md",
+        kind: "example",
+        title: "feature-loop",
+        topics: ["clone", "clone-chain", "loop", "feature", "pr"],
+    },
+    {
+        path: "examples/stage-mcp/README.md",
+        kind: "example",
+        title: "stage-mcp",
+        topics: ["mcp", "stage", ".mcp.json"],
+    },
+    {
+        path: "examples/verify-tour/README.md",
+        kind: "example",
+        title: "verify-tour",
+        topics: ["verify", "artifact", "command", "checklist", "gate"],
+    },
+    {
+        path: "examples/retry-tour/README.md",
+        kind: "example",
+        title: "retry-tour",
+        topics: ["retry", "repair", "manual", "recover", "recovery"],
+    },
+    {
+        path: "skills/stageflow-author/assets/examples/linear-review/review-loop.pipeline.yaml",
+        kind: "example",
+        title: "linear-review (author skill)",
+        topics: ["linear", "review", "author", "skill"],
+    },
+    {
+        path: "skills/stageflow-author/assets/examples/branch-decision/release-gate.pipeline.yaml",
+        kind: "example",
+        title: "branch-decision (author skill)",
+        topics: ["branch", "decision", "route", "if", "author"],
+    },
+    {
+        path: "skills/stageflow-author/assets/examples/non-sdlc-digest/research-digest.pipeline.yaml",
+        kind: "example",
+        title: "non-sdlc-digest (author skill)",
+        topics: ["digest", "non-sdlc", "research", "author"],
+    },
+];
+const EXCERPT_MAX = 1200;
+export function resolveWorkshopCatalogRoot(explicit) {
+    if (explicit)
+        return explicit;
+    return fileURLToPath(new URL("../..", import.meta.url));
+}
+function tokenize(query) {
+    return query
+        .toLowerCase()
+        .split(/[^a-z0-9_./-]+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length >= 2);
+}
+function scoreEntry(entry, tokens) {
+    if (tokens.length === 0)
+        return 1;
+    let score = 0;
+    const hay = `${entry.path} ${entry.title} ${entry.topics.join(" ")}`.toLowerCase();
+    for (const token of tokens) {
+        if (entry.topics.includes(token))
+            score += 4;
+        else if (hay.includes(token))
+            score += 2;
+    }
+    return score;
+}
+async function readExcerpt(absPath) {
+    try {
+        const text = await readFile(absPath, "utf8");
+        const trimmed = text.trim();
+        if (!trimmed)
+            return null;
+        return trimmed.length > EXCERPT_MAX
+            ? `${trimmed.slice(0, EXCERPT_MAX)}…`
+            : trimmed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Filesystem retriever over public docs/ + examples/ (allowlisted).
+ * Read failures for individual paths are skipped; empty matches still ok:true.
+ * Thrown/unexpected errors surface as ok:false so the agent can fall back to
+ * the baked playbook.
+ */
+export function createFilesystemDocsRetriever(options = {}) {
+    const rootDir = resolveWorkshopCatalogRoot(options.rootDir);
+    return {
+        async retrieve(query, opts = {}) {
+            try {
+                const kind = opts.kind ?? "any";
+                const limit = Math.max(1, Math.min(opts.limit ?? 5, 10));
+                const tokens = tokenize(query);
+                const ranked = CORPUS.map((entry) => ({
+                    entry,
+                    score: scoreEntry(entry, tokens),
+                }))
+                    .filter(({ entry, score }) => {
+                    if (score <= 0)
+                        return false;
+                    if (kind === "docs")
+                        return entry.kind === "doc";
+                    if (kind === "examples")
+                        return entry.kind === "example";
+                    return true;
+                })
+                    .sort((a, b) => b.score - a.score || a.entry.path.localeCompare(b.entry.path));
+                const hits = [];
+                for (const { entry } of ranked) {
+                    if (hits.length >= limit)
+                        break;
+                    const abs = path.join(rootDir, entry.path);
+                    let excerpt = await readExcerpt(abs);
+                    if (excerpt === null && entry.path.endsWith("/README.md")) {
+                        const dir = path.dirname(entry.path);
+                        const fallback = path.join(rootDir, dir, "README.md");
+                        excerpt = await readExcerpt(fallback);
+                    }
+                    if (excerpt === null)
+                        continue;
+                    hits.push({
+                        path: entry.path,
+                        kind: entry.kind,
+                        title: entry.title,
+                        excerpt,
+                    });
+                }
+                return { ok: true, hits };
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    hits: [],
+                    error: err instanceof Error ? err.message : String(err),
+                };
+            }
+        },
+    };
+}
+export function createStubDocsRetriever(impl) {
+    if (typeof impl === "function") {
+        return {
+            async retrieve(query, options) {
+                try {
+                    return await impl(query, options);
+                }
+                catch (err) {
+                    return {
+                        ok: false,
+                        hits: [],
+                        error: err instanceof Error ? err.message : String(err),
+                    };
+                }
+            },
+        };
+    }
+    return {
+        async retrieve() {
+            return { ok: true, hits: impl };
+        },
+    };
+}
+export function createFailingDocsRetriever(error = "docs retrieval unavailable") {
+    return {
+        async retrieve() {
+            return { ok: false, hits: [], error };
+        },
+    };
+}
+export { CORPUS as WORKSHOP_DOCS_CORPUS };

package/dist/operatorAgent/draftContext.d.ts

@@ -0,0 +1,16 @@
+import type { DraftPackage } from "../config/draftPackage.js";
+import type { OperatorAgentContextAdapter, WorkshopDraftContext } from "./types.js";
+export declare const WORKSHOP_AUTHOR_GREETING = "What are we building? Tell me the workflow in your own words \u2014 I\u2019ll ask where it changes the draft.";
+export declare function emptyDraftPackage(id?: string): DraftPackage;
+export type WorkshopDraftContextExtras = Omit<WorkshopDraftContext, "draft">;
+export declare function createWorkshopDraftContext(draft?: DraftPackage, extras?: WorkshopDraftContextExtras): WorkshopDraftContext;
+export declare function isWorkshopDraftContext(value: unknown): value is WorkshopDraftContext;
+export declare function readDraftFromContext(context: unknown): DraftPackage;
+export declare function withDraft(context: unknown, draft: DraftPackage): WorkshopDraftContext;
+export declare function withDestination(context: unknown, destination: WorkshopDraftContext["destination"]): WorkshopDraftContext;
+export declare function withProjectRoot(context: unknown, projectRoot: string): WorkshopDraftContext;
+export declare const workshopDraftContextAdapter: OperatorAgentContextAdapter;
+export declare function draftTrackStages(draft: DraftPackage): Array<{
+    id: string;
+    label: string;
+}>;

package/dist/operatorAgent/draftContext.js

@@ -0,0 +1,68 @@
+export const WORKSHOP_AUTHOR_GREETING = "What are we building? Tell me the workflow in your own words — I’ll ask where it changes the draft.";
+export function emptyDraftPackage(id = "untitled") {
+    return {
+        pipeline: {
+            id,
+            stages: [],
+        },
+    };
+}
+export function createWorkshopDraftContext(draft = emptyDraftPackage(), extras = {}) {
+    return { draft, ...extras };
+}
+export function isWorkshopDraftContext(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        "draft" in value &&
+        value.draft !== null &&
+        typeof value.draft === "object");
+}
+export function readDraftFromContext(context) {
+    if (isWorkshopDraftContext(context))
+        return context.draft;
+    if (context !== null &&
+        typeof context === "object" &&
+        "pipeline" in context) {
+        return context;
+    }
+    return emptyDraftPackage();
+}
+export function withDraft(context, draft) {
+    if (isWorkshopDraftContext(context)) {
+        return { ...context, draft };
+    }
+    return { draft };
+}
+export function withDestination(context, destination) {
+    const base = isWorkshopDraftContext(context)
+        ? context
+        : { draft: readDraftFromContext(context) };
+    return { ...base, destination };
+}
+export function withProjectRoot(context, projectRoot) {
+    const base = isWorkshopDraftContext(context)
+        ? context
+        : { draft: readDraftFromContext(context) };
+    return { ...base, projectRoot };
+}
+export const workshopDraftContextAdapter = {
+    serialize(context) {
+        return readDraftFromContext(context);
+    },
+    applyProposal(context, proposal) {
+        const next = proposal.nextContext;
+        if (isWorkshopDraftContext(next)) {
+            return withDraft(context, next.draft);
+        }
+        if (next !== null && typeof next === "object" && "pipeline" in next) {
+            return withDraft(context, next);
+        }
+        return withDraft(context, readDraftFromContext(context));
+    },
+};
+export function draftTrackStages(draft) {
+    return draft.pipeline.stages.map((stage, index) => {
+        const id = typeof stage.id === "string" && stage.id ? stage.id : `stage-${index}`;
+        return { id, label: id };
+    });
+}

package/dist/operatorAgent/fakeHost.d.ts

@@ -0,0 +1,39 @@
+import { type OperatorAgentModel } from "./host.js";
+import type { DocsRetriever } from "./docsRetrieval.js";
+import { WORKSHOP_AUTHOR_PROFILE_ID, type WorkshopAuthorProfileOptions } from "./profiles/workshopAuthor.js";
+import type { OperatorAgentHost, OperatorAgentProposal, OperatorAgentSessionEvent } from "./types.js";
+export type FakeOperatorTurn = {
+    type: "echo";
+} | {
+    type: "propose_stage";
+} | {
+    type: "propose_task";
+} | {
+    type: "events";
+    events: OperatorAgentSessionEvent[];
+} | {
+    type: "propose";
+    proposal: OperatorAgentProposal;
+    message?: string;
+} | {
+    type: "call_tool";
+    name: string;
+    args?: Record<string, unknown>;
+    message?: string;
+};
+/**
+ * Deterministic Operator Agent Host for Workshop and tests.
+ * Does not call a live provider — scripted turns or auto stage/task mutations.
+ */
+export declare function createFakeOperatorAgentModel(script?: FakeOperatorTurn[]): OperatorAgentModel;
+export type WorkshopOperatorHostOptions = WorkshopAuthorProfileOptions & {
+    script?: FakeOperatorTurn[];
+    retriever?: DocsRetriever;
+    /**
+     * Inject a model (e.g. live Pi). When omitted, uses the fake scripted model
+     * — keep as the test / default path (R13).
+     */
+    model?: OperatorAgentModel;
+};
+export declare function createWorkshopOperatorHost(scriptOrOptions?: FakeOperatorTurn[] | WorkshopOperatorHostOptions): OperatorAgentHost;
+export { WORKSHOP_AUTHOR_PROFILE_ID };

package/dist/operatorAgent/fakeHost.js

@@ -0,0 +1,92 @@
+import { createOperatorAgentHost, invokeProfileTool, } from "./host.js";
+import { createWorkshopAuthorProfile, isTaskProposalIntent, proposeStageFromUserMessage, proposeTaskFromUserMessage, WORKSHOP_AUTHOR_PROFILE_ID, } from "./profiles/workshopAuthor.js";
+/**
+ * Deterministic Operator Agent Host for Workshop and tests.
+ * Does not call a live provider — scripted turns or auto stage/task mutations.
+ */
+export function createFakeOperatorAgentModel(script = [{ type: "propose_stage" }]) {
+    let index = 0;
+    return {
+        async complete({ profile, message, tools }) {
+            const turn = script[Math.min(index, script.length - 1)] ?? {
+                type: "propose_stage",
+            };
+            index += 1;
+            if (turn.type === "events") {
+                return { events: turn.events };
+            }
+            if (turn.type === "echo") {
+                return {
+                    events: [
+                        {
+                            type: "message",
+                            role: "assistant",
+                            text: `Got it: ${message}`,
+                        },
+                    ],
+                };
+            }
+            if (turn.type === "call_tool") {
+                const result = await invokeProfileTool(profile, turn.name, turn.args ?? {}, tools);
+                const events = [
+                    { type: "tool_result", name: turn.name, result },
+                ];
+                if (turn.message) {
+                    events.push({
+                        type: "message",
+                        role: "assistant",
+                        text: turn.message,
+                    });
+                }
+                else if (!result.ok) {
+                    events.push({
+                        type: "message",
+                        role: "assistant",
+                        text: `Retrieval unavailable (${result.error ?? "error"}). Continuing with the baked Workshop Author playbook.`,
+                    });
+                }
+                return { events };
+            }
+            if (turn.type === "propose") {
+                tools.emitProposal(turn.proposal);
+                return {
+                    events: [
+                        {
+                            type: "message",
+                            role: "assistant",
+                            text: turn.message ??
+                                `Applied to draft: ${turn.proposal.summary}. Accept confirms; Reject undoes when the draft is unchanged.`,
+                        },
+                        { type: "proposal", proposal: turn.proposal },
+                    ],
+                };
+            }
+            const proposal = turn.type === "propose_task" || isTaskProposalIntent(message)
+                ? proposeTaskFromUserMessage(tools, message)
+                : proposeStageFromUserMessage(tools, message);
+            return {
+                events: [
+                    {
+                        type: "message",
+                        role: "assistant",
+                        text: `Applied to draft: ${proposal.summary}. Accept confirms; Reject undoes when the draft is unchanged. Nothing was written to disk — Save when you are ready.`,
+                    },
+                    { type: "proposal", proposal },
+                ],
+            };
+        },
+    };
+}
+export function createWorkshopOperatorHost(scriptOrOptions) {
+    const options = Array.isArray(scriptOrOptions)
+        ? { script: scriptOrOptions }
+        : (scriptOrOptions ?? {});
+    const host = createOperatorAgentHost(options.model ?? createFakeOperatorAgentModel(options.script), [
+        createWorkshopAuthorProfile({
+            retriever: options.retriever,
+            projectRoot: options.projectRoot,
+        }),
+    ]);
+    return host;
+}
+export { WORKSHOP_AUTHOR_PROFILE_ID };

package/dist/operatorAgent/host.d.ts

@@ -0,0 +1,40 @@
+import type { OperatorAgentHost, OperatorAgentProfile, OperatorAgentSessionEvent, OperatorAgentToolContext, OperatorAgentToolResult, WorkshopToolActivityUpdate } from "./types.js";
+export type OperatorAgentModelTurn = {
+    events: OperatorAgentSessionEvent[];
+};
+export type OperatorAgentModelCompleteInput = {
+    profile: OperatorAgentProfile;
+    message: string;
+    contextSnapshot: unknown;
+    tools: OperatorAgentToolContext;
+    /**
+     * Optional mid-turn assistant text callback (Workshop progressive NDJSON).
+     * Invoked as Pi `text_delta` (or equivalent) arrives — before complete resolves.
+     */
+    onDelta?: (text: string) => void;
+    /** Mid-turn tool status for the Workshop chat column. */
+    onActivity?: (update: WorkshopToolActivityUpdate) => void;
+    /** Workshop composer model for this turn. Applied before the prompt. */
+    modelId?: string;
+};
+export type OperatorAgentModel = {
+    complete(input: OperatorAgentModelCompleteInput): Promise<OperatorAgentModelTurn>;
+    /**
+     * Optional restart seed (KTD7): inject prior transcript into a new backend
+     * session before the first complete for this host session.
+     */
+    prepareRestart?(input: {
+        tools: OperatorAgentToolContext;
+        profile: OperatorAgentProfile;
+        transcript: readonly {
+            role: string;
+            text: string;
+        }[];
+    }): Promise<void>;
+    /** Optional: dispose backend resources bound to this tool context. */
+    releaseTools?(tools: OperatorAgentToolContext): void | Promise<void>;
+    /** Interrupt the in-flight prompt for this tool context. */
+    abort?(tools: OperatorAgentToolContext): Promise<void>;
+};
+export declare function createOperatorAgentHost(model: OperatorAgentModel, seedProfiles?: OperatorAgentProfile[]): OperatorAgentHost;
+export declare function invokeProfileTool(profile: OperatorAgentProfile, name: string, args: Record<string, unknown>, ctx: OperatorAgentToolContext): Promise<OperatorAgentToolResult>;