stageflow 0.27.0 → 0.31.0

package/dist/mcp/triggerTools.js

@@ -0,0 +1,176 @@
+import { z } from "zod";
+import { CatalogPathError, catalogPathErrorBody, resolveWritableCatalogRoot, } from "../config/catalogRelativePath.js";
+import { createTrigger, parseCreateTriggerBody } from "../config/createTrigger.js";
+import { loadCatalogTriggers } from "../config/triggerCatalog.js";
+import { writeAudit } from "../logging/audit.js";
+import { logger as rootLogger } from "../logging/logger.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { fireTrigger } from "../runtime/triggerRunner.js";
+import { mapStartFailure } from "../server/operatorResults.js";
+import { callerIdFromRequestAuth, getRequestAuth, } from "../server/requestAuthContext.js";
+import { textResult } from "./toolResults.js";
+const auditLog = rootLogger.child({ component: "audit" });
+const triggerScheduleSchema = z.object({
+    cron: z.string(),
+    timezone: z.string().optional(),
+});
+const gitIdentitySchema = z.object({
+    name: z.string().optional(),
+    email: z.string().optional(),
+});
+/**
+ * Same shape as TaskFile (src/types/task.ts), duplicated locally the same way
+ * src/mcp/catalogTools.ts's own taskFileSchema is: deliberately not shared
+ * across module boundaries for a schema this small.
+ */
+const taskFileSchema = z.object({
+    id: z.string(),
+    goal: z.string(),
+    context: z.string().optional(),
+    constraints: z.string().optional(),
+    checkout: z.string().optional(),
+    repository: z.string().optional(),
+    ref: z.string().optional(),
+    run_branch_template: z.string().optional(),
+    git_identity: gitIdentitySchema.optional(),
+    input: z.record(z.string(), z.unknown()).optional(),
+});
+const triggerEventSchema = z.object({
+    source: z.string(),
+    match: z.record(z.string(), z.unknown()).optional(),
+    config: z.record(z.string(), z.unknown()).optional(),
+});
+const createTriggerSchema = z.object({
+    project_root: z
+        .string()
+        .optional()
+        .describe("Catalog project root to write into; required when multiple catalog roots are configured and no sole non-seeded root exists"),
+    directory: z.string(),
+    id: z.string(),
+    pipeline: z.string(),
+    task: z
+        .string()
+        .optional()
+        .describe("Catalog task id; omit to create a dynamic-mode trigger whose task is supplied at fire time"),
+    kind: z.enum(["manual", "schedule", "event"]),
+    schedule: triggerScheduleSchema.optional(),
+    event: triggerEventSchema.optional(),
+    enabled: z.boolean().optional(),
+});
+export function registerTriggerTools(server, deps) {
+    const { store, cwd, manager } = deps;
+    server.registerTool("list_triggers", {
+        description: "List catalog-declared triggers (same source as GET /api/triggers): manual/schedule/event kind, enabled, and store-recorded last_fired_at/last_run_id/next_run_at when present.",
+        inputSchema: z.object({}),
+    }, async () => {
+        const items = await loadCatalogTriggers(cwd, store);
+        if (items === undefined) {
+            return textResult({ error: "No Stageflow catalog found", status: 404 }, true);
+        }
+        return textResult({ triggers: items });
+    });
+    server.registerTool("get_trigger", {
+        description: "Look up one catalog trigger by id (same source as GET /api/triggers/:id).",
+        inputSchema: z.object({
+            id: z.string(),
+        }),
+    }, async ({ id }) => {
+        const items = await loadCatalogTriggers(cwd, store);
+        if (items === undefined) {
+            return textResult({ error: "No Stageflow catalog found", status: 404 }, true);
+        }
+        const found = items.find((item) => item.id === id);
+        if (!found) {
+            return textResult({ error: `Trigger not found: ${id}`, status: 404 }, true);
+        }
+        return textResult(found);
+    });
+    server.registerTool("fire_trigger", {
+        description: "Fire a catalog trigger by id: resolves its pipeline/task refs and starts a run through the same RunManager.startRun path as start_run (same as POST /api/triggers/:id/fire). Returns { runId } or { runId, queued: true, queuePosition }. Fails not_found (404) for an unknown id, or 409 when the trigger is disabled.",
+        inputSchema: z.object({
+            id: z.string(),
+            task: taskFileSchema
+                .optional()
+                .describe("Inline TaskFile, required to fire a dynamic-mode trigger (no catalog task) and rejected for a catalog-mode trigger"),
+        }),
+    }, async ({ id, task }) => {
+        const callerId = callerIdFromRequestAuth();
+        const result = await fireTrigger(id, store, manager, { cwd, task });
+        if (!result.ok) {
+            writeAudit(auditLog, {
+                caller_id: callerId,
+                surface: getRequestAuth()?.surface ?? "mcp",
+                action: "trigger_fire",
+                outcome: "error",
+                error_code: result.code,
+            });
+            return textResult({
+                ...mapStartFailure(result),
+                ...(result.status !== undefined ? { status: result.status } : {}),
+            }, true);
+        }
+        writeAudit(auditLog, {
+            caller_id: callerId,
+            surface: getRequestAuth()?.surface ?? "mcp",
+            action: "trigger_fire",
+            target_run_id: result.runId,
+            outcome: "ok",
+        });
+        return textResult({
+            runId: result.runId,
+            ...(result.queued === true
+                ? {
+                    queued: true,
+                    queuePosition: result.queuePosition,
+                    ...(result.queuedCode !== undefined
+                        ? { queuedCode: result.queuedCode }
+                        : {}),
+                }
+                : {}),
+        });
+    });
+    server.registerTool("create_trigger", {
+        description: "Create a new *.trigger.yaml in the catalog (same validation/write path as POST /api/triggers): validates id format/uniqueness, pipeline/task refs, and kind-specific shape (schedule.cron parses via croner; event.source is required), writes the file, and re-loads it to confirm it round-trips. Returns the created trigger.",
+        inputSchema: createTriggerSchema,
+    }, async ({ project_root, ...body }) => {
+        const callerId = callerIdFromRequestAuth();
+        let wireRoot;
+        try {
+            ({ wireRoot } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, project_root));
+        }
+        catch (err) {
+            if (err instanceof CatalogPathError) {
+                return textResult(catalogPathErrorBody(err), true);
+            }
+            throw err;
+        }
+        const parsed = parseCreateTriggerBody(body);
+        if ("ok" in parsed) {
+            return textResult({ error: parsed.error, status: parsed.status }, true);
+        }
+        const stageflowCtx = await resolveStageflowContext(wireRoot.path);
+        if (stageflowCtx.manifestStatus !== "ok") {
+            return textResult({
+                error: "Project root not found; initialize stageflow.yaml",
+                status: 400,
+            }, true);
+        }
+        const result = await createTrigger(stageflowCtx.projectRoot, parsed);
+        if (!result.ok) {
+            writeAudit(auditLog, {
+                caller_id: callerId,
+                surface: getRequestAuth()?.surface ?? "mcp",
+                action: "trigger_create",
+                outcome: "error",
+            });
+            return textResult({ error: result.error, status: result.status }, true);
+        }
+        writeAudit(auditLog, {
+            caller_id: callerId,
+            surface: getRequestAuth()?.surface ?? "mcp",
+            action: "trigger_create",
+            outcome: "ok",
+        });
+        return textResult(result.trigger);
+    });
+}

package/dist/operatorAgent/docsRetrieval.d.ts

@@ -0,0 +1,40 @@
+export type DocsRetrievalHit = {
+    path: string;
+    kind: "doc" | "example";
+    title: string;
+    excerpt: string;
+};
+export type DocsRetrievalResult = {
+    ok: boolean;
+    hits: DocsRetrievalHit[];
+    error?: string;
+};
+export type DocsRetriever = {
+    retrieve(query: string, options?: {
+        kind?: "docs" | "examples" | "any";
+        limit?: number;
+    }): Promise<DocsRetrievalResult>;
+};
+type CorpusEntry = {
+    path: string;
+    kind: "doc" | "example";
+    title: string;
+    topics: string[];
+};
+declare const CORPUS: CorpusEntry[];
+export declare function resolveWorkshopCatalogRoot(explicit?: string): string;
+/**
+ * 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 declare function createFilesystemDocsRetriever(options?: {
+    rootDir?: string;
+}): DocsRetriever;
+export declare function createStubDocsRetriever(impl: DocsRetrievalHit[] | ((query: string, options?: {
+    kind?: "docs" | "examples" | "any";
+    limit?: number;
+}) => DocsRetrievalResult | Promise<DocsRetrievalResult>)): DocsRetriever;
+export declare function createFailingDocsRetriever(error?: string): DocsRetriever;
+export { CORPUS as WORKSHOP_DOCS_CORPUS };

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 };