stageflow 0.25.0 → 0.30.0

package/dist/mcp/getStartedTool.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { PACKAGE_VERSION } from "../package-meta.js";
+import { listPipelinesMultiProject, listTasksMultiProject } from "../config/multiProjectCatalog.js";
+import { resolveCatalogRoots } from "../config/resolveCatalogRoots.js";
+import { textResult } from "./toolResults.js";
+import { toolchainHealthMap } from "../preflight/toolchain.js";
+export function registerGetStartedTool(server, deps) {
+    server.registerTool("get_started", {
+        description: "First-run orientation for remote harnesses: host version, providers, toolchain hints, catalog roots with counts, and a three-call next_steps list. No arguments.",
+        inputSchema: z.object({}),
+    }, async () => {
+        const roots = await resolveCatalogRoots({
+            store: deps.store,
+            bootCwd: deps.cwd,
+        });
+        const pipelines = await listPipelinesMultiProject({
+            store: deps.store,
+            bootCwd: deps.cwd,
+        });
+        const tasks = await listTasksMultiProject({
+            store: deps.store,
+            bootCwd: deps.cwd,
+        });
+        const catalog_roots = roots.map((root) => ({
+            project_root: root.project_root,
+            kind: root.kind,
+            read_only: root.read_only,
+            pipeline_count: pipelines.items.filter((p) => p.project_root === root.project_root).length,
+            task_count: tasks.items.filter((t) => t.project_root === root.project_root)
+                .length,
+        }));
+        const firstRoot = catalog_roots.find((r) => r.kind === "seeded") ?? catalog_roots[0];
+        const samplePipeline = pipelines.items.find((p) => p.project_root === firstRoot?.project_root);
+        const sampleTask = tasks.items.find((t) => t.project_root === firstRoot?.project_root);
+        return textResult({
+            host: { version: PACKAGE_VERSION },
+            providers: deps.providerAuthContext
+                ? { note: "Use list_providers for status" }
+                : { configured: [] },
+            toolchain: toolchainHealthMap(),
+            catalog_roots,
+            next_steps: [
+                {
+                    tool: "list_pipelines",
+                    args: firstRoot ? { project_root: firstRoot.project_root } : {},
+                },
+                {
+                    tool: "list_tasks",
+                    args: firstRoot ? { project_root: firstRoot.project_root } : {},
+                },
+                {
+                    tool: "start_run",
+                    args: {
+                        ...(firstRoot ? { project_root: firstRoot.project_root } : {}),
+                        pipeline: samplePipeline?.path ?? "pipelines/demo.pipeline.yaml",
+                        task_path: sampleTask?.path ?? "tasks/demo.task.yaml",
+                    },
+                },
+            ],
+        });
+    });
+}

package/dist/mcp/readArtifact.d.ts

@@ -1,4 +1,15 @@
 import type { RunStore } from "../runstore/port.js";
+export declare function assertSafeRunId(runId: string): void;
+export declare const PATH_DENIED_MESSAGE = "Artifact path denied";
+export type ContainedPathMessages = {
+    relativeRequired: string;
+    escapes: string;
+    notFound: (relativePath: string) => string;
+    denied?: string;
+};
+export declare const CHECKOUT_PATH_MESSAGES: ContainedPathMessages;
+export declare function assertSafeRelativePath(relativePath: string, messages: ContainedPathMessages): string[];
+export declare function resolveContainedRelativePath(containerDir: string, relativePath: string, messages: ContainedPathMessages): Promise<string>;
 export declare function artifactMediaType(relativePath: string): string | undefined;
 export type ClassifiedArtifactContent = {
     kind: "image";

package/dist/mcp/readArtifact.js

@@ -1,8 +1,8 @@
 import { isUtf8 } from "node:buffer";
-import { readFile, realpath } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { isInsideDir } from "../runstore/workspaceLayout.js";
-function assertSafeRunId(runId) {
+import { classifyRealPathContainment } from "../runstore/workspaceLayout.js";
+export function assertSafeRunId(runId) {
     if (typeof runId !== "string" || runId.trim().length === 0) {
         throw new Error("runId must be a non-empty string");
     }
@@ -13,6 +13,48 @@ function assertSafeRunId(runId) {
         throw new Error("runId must not contain path separators or ..");
     }
 }
+export const PATH_DENIED_MESSAGE = "Artifact path denied";
+const ARTIFACT_MESSAGES = {
+    relativeRequired: "path must be relative to the run workspace",
+    escapes: "path escapes the run workspace",
+    notFound: (relativePath) => `Artifact not found: ${relativePath}`,
+    denied: PATH_DENIED_MESSAGE,
+};
+export const CHECKOUT_PATH_MESSAGES = {
+    relativeRequired: "path must be relative to the checkout",
+    escapes: "path escapes the checkout",
+    notFound: (relativePath) => `Checkout file not found: ${relativePath}`,
+    denied: PATH_DENIED_MESSAGE,
+};
+export function assertSafeRelativePath(relativePath, messages) {
+    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(messages.relativeRequired);
+    }
+    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(messages.denied ?? PATH_DENIED_MESSAGE);
+    }
+    return segments;
+}
+export async function resolveContainedRelativePath(containerDir, relativePath, messages) {
+    assertSafeRelativePath(relativePath, messages);
+    const candidate = path.resolve(containerDir, relativePath);
+    const containment = await classifyRealPathContainment(candidate, containerDir);
+    if (containment.status === "missing") {
+        throw new Error(messages.notFound(relativePath));
+    }
+    if (containment.status === "outside") {
+        throw new Error(messages.escapes);
+    }
+    return containment.realPath;
+}
 export function artifactMediaType(relativePath) {
     const ext = path.extname(relativePath).toLowerCase();
     switch (ext) {
@@ -41,35 +83,9 @@ export function classifyArtifactContent(relativePath, bytes) {
 }
 async function resolveRunArtifactFile(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 fileReal;
+    return resolveContainedRelativePath(workspaceDir, relativePath, ARTIFACT_MESSAGES);
 }
 export async function readRunArtifact(store, runId, relativePath) {
     const fileReal = await resolveRunArtifactFile(store, runId, relativePath);

package/dist/mcp/server.js

@@ -38,10 +38,12 @@ function toolDepsFrom(deps) {
         manager: deps.manager,
         store: deps.store,
         cwd: deps.cwd,
+        ...(deps.agentDir !== undefined ? { agentDir: deps.agentDir } : {}),
         ...(deps.providerAuthContext !== undefined
             ? { providerAuthContext: deps.providerAuthContext }
             : {}),
         ...(deps.projectRoot !== undefined ? { projectRoot: deps.projectRoot } : {}),
+        ...(deps.providerBoot !== undefined ? { providerBoot: deps.providerBoot } : {}),
     };
 }
 function attachBusNotifications(server, bus) {

package/dist/mcp/tools.js

@@ -1,16 +1,22 @@
 import { z } from "zod";
 import { registerCatalogTools } from "./catalogTools.js";
+import { registerCheckoutTools } from "./checkoutTools.js";
 import { registerControlTools } from "./controlTools.js";
 import { registerProjectMcpTools } from "./projectMcpTools.js";
 import { registerProviderTools } from "./providerTools.js";
+import { registerTriggerTools } from "./triggerTools.js";
 import { textResult } from "./toolResults.js";
 import { DEFAULT_TIMEOUT_MS, waitRun } from "./waitRun.js";
+import { registerGetStartedTool } from "./getStartedTool.js";
 export function registerMcpTools(server, deps) {
     const { store } = deps;
+    registerGetStartedTool(server, deps);
     registerCatalogTools(server, deps);
     registerControlTools(server, deps);
+    registerCheckoutTools(server, deps);
     registerProviderTools(server, deps);
     registerProjectMcpTools(server, deps);
+    registerTriggerTools(server, deps);
     server.registerTool("wait_run", {
         description: "Long-poll until a run is waiting for HITL input and/or terminal (succeeded/failed), or until timeout_ms. Default until=any wakes on waiting OR terminal. Abort cancels only this wait (not the run). Optional notifications/progress when the client supplies _meta.progressToken. Compose: wait_run → answer_gate → wait_run.",
         inputSchema: z.object({

package/dist/mcp/triggerTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { McpToolDeps } from "./deps.js";
+export declare function registerTriggerTools(server: McpServer, deps: McpToolDeps): void;

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/net/proxy.d.ts

@@ -0,0 +1,14 @@
+export type ProxyInstallResult = {
+    installed: boolean;
+    httpProxyHost?: string;
+    httpsProxyHost?: string;
+    noProxy: string;
+};
+export declare function effectiveNoProxy(env: NodeJS.ProcessEnv, bindHosts?: readonly string[]): string;
+export declare function installProxyDispatcher(env?: NodeJS.ProcessEnv, options?: {
+    bindHosts?: readonly string[];
+    log?: (msg: string) => void;
+}): ProxyInstallResult;
+export declare function resetProxyDispatcherForTests(): void;
+export declare function buildEgressHealth(env?: NodeJS.ProcessEnv): Record<string, unknown>;
+export declare function proxyHealthFields(env?: NodeJS.ProcessEnv): Record<string, unknown>;

package/dist/net/proxy.js

@@ -0,0 +1,78 @@
+import { EnvHttpProxyAgent, setGlobalDispatcher } from "undici";
+import { stripUrlUserinfo } from "../logging/redact.js";
+let installed = false;
+function firstProxy(env) {
+    return (env.HTTPS_PROXY ||
+        env.https_proxy ||
+        env.HTTP_PROXY ||
+        env.http_proxy ||
+        undefined);
+}
+function parseProxyHost(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        const u = new URL(raw);
+        return u.host;
+    }
+    catch {
+        return stripUrlUserinfo(raw);
+    }
+}
+export function effectiveNoProxy(env, bindHosts = ["127.0.0.1", "::1", "localhost"]) {
+    const existing = env.NO_PROXY ?? env.no_proxy ?? "";
+    const parts = existing
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const set = new Set(parts.map((p) => p.toLowerCase()));
+    for (const host of bindHosts) {
+        if (!set.has(host.toLowerCase())) {
+            parts.push(host);
+            set.add(host.toLowerCase());
+        }
+    }
+    return parts.join(",");
+}
+export function installProxyDispatcher(env = process.env, options = {}) {
+    const proxy = firstProxy(env);
+    if (!proxy) {
+        return { installed: false, noProxy: env.NO_PROXY ?? env.no_proxy ?? "" };
+    }
+    const noProxy = effectiveNoProxy(env, options.bindHosts);
+    process.env.NO_PROXY = noProxy;
+    if (!installed) {
+        setGlobalDispatcher(new EnvHttpProxyAgent({ noProxy }));
+        installed = true;
+        options.log?.(`Installed EnvHttpProxyAgent; appended loopback to NO_PROXY (${noProxy})`);
+    }
+    return {
+        installed: true,
+        httpProxyHost: parseProxyHost(env.HTTP_PROXY ?? env.http_proxy),
+        httpsProxyHost: parseProxyHost(env.HTTPS_PROXY ?? env.https_proxy),
+        noProxy,
+    };
+}
+export function resetProxyDispatcherForTests() {
+    installed = false;
+}
+export function buildEgressHealth(env = process.env) {
+    const httpSet = Boolean(env.HTTP_PROXY || env.http_proxy);
+    const httpsSet = Boolean(env.HTTPS_PROXY || env.https_proxy);
+    const noProxySet = Boolean(env.NO_PROXY || env.no_proxy);
+    const caSet = Boolean(env.NODE_EXTRA_CA_CERTS || env.SSL_CERT_FILE || env.REQUESTS_CA_BUNDLE);
+    const proxyHost = parseProxyHost(env.HTTPS_PROXY ?? env.https_proxy) ??
+        parseProxyHost(env.HTTP_PROXY ?? env.http_proxy) ??
+        null;
+    return {
+        http_proxy: httpSet ? "set" : "unset",
+        https_proxy: httpsSet ? "set" : "unset",
+        no_proxy: noProxySet ? "set" : "unset",
+        proxy_host: proxyHost,
+        extra_ca_certs: caSet ? "set" : "unset",
+        dispatcher_installed: installed,
+    };
+}
+export function proxyHealthFields(env = process.env) {
+    return buildEgressHealth(env);
+}

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