stageflow 0.25.0 → 0.30.0

package/dist/config/loadPipeline.js

@@ -12,6 +12,8 @@ import { recoveryRequiresCompletionIssue } from "./parseCompletionContract.js";
 import { validateCompletionContractForStage } from "./validateCompletionContract.js";
 import { applyCloneChains } from "./cloneChain.js";
 import { collectRouteIfSchemaIssues, collectRouteIfIllegalCombos, collectRouteAllGatedWarnings, } from "./routeIf.js";
+import { mergeToolRequires } from "./toolRequires.js";
+import { withBrowserRequires } from "./stageBrowser.js";
 function schemaCompileIssue(stageId, field, err, pipelineId) {
     const message = err instanceof Error ? err.message : String(err);
     if (err instanceof UnresolvedSchemaRefError) {
@@ -128,7 +130,7 @@ export async function loadPipelineFromObject(raw, options = {}) {
 }
 async function buildLoadedPipelineFromMerge(merge, options) {
     const { projectRoot, requireIo, pipelinePath } = options;
-    const { entries: rawEntries, pipelineId, agent: pipelineAgent, model: pipelineModel, schemas: pipelineSchemas, warnings: mergeWarnings, } = merge;
+    const { entries: rawEntries, pipelineId, agent: pipelineAgent, model: pipelineModel, schemas: pipelineSchemas, requires: pipelineRequires, warnings: mergeWarnings, } = merge;
     const ctx = { pipelineId, path: pipelinePath };
     const warnings = [...mergeWarnings];
     const normalizeOutcome = normalizePipelineStageEntries(rawEntries, ctx);
@@ -181,7 +183,23 @@ async function buildLoadedPipelineFromMerge(merge, options) {
             if (!inlineOutcome.ok) {
                 return loadFailure(inlineOutcome.issues);
             }
-            stages.push(inlineOutcome.value);
+            let stage = inlineOutcome.value;
+            if (entry.requires !== undefined) {
+                const merged = mergeToolRequires([stage.requires, entry.requires], { pipelineId, label: `stage "${entry.id}"` });
+                if (!merged.ok)
+                    return loadFailure(merged.issues);
+                stage = { ...stage, requires: merged.value };
+            }
+            const inlineRequires = withBrowserRequires(stage, {
+                pipelineId,
+                stageId: entry.id,
+            });
+            if (!inlineRequires.ok)
+                return loadFailure(inlineRequires.issues);
+            if (inlineRequires.value !== undefined) {
+                stage = { ...stage, requires: inlineRequires.value };
+            }
+            stages.push(stage);
             stageSources[stageId] = { kind: "inline" };
             continue;
         }
@@ -229,10 +247,25 @@ async function buildLoadedPipelineFromMerge(merge, options) {
                 },
             ]);
         }
+        let stageRequires = stageOutcome.value.requires;
+        if (entry.requires !== undefined) {
+            const merged = mergeToolRequires([stageRequires, entry.requires], { pipelineId, label: `stage "${entry.id}"` });
+            if (!merged.ok)
+                return loadFailure(merged.issues);
+            stageRequires = merged.value;
+        }
+        const browser = entry.browser ?? stageOutcome.value.browser;
+        const fileRequires = withBrowserRequires({ browser, requires: stageRequires }, { pipelineId, stageId: entry.id });
+        if (!fileRequires.ok)
+            return loadFailure(fileRequires.issues);
+        stageRequires = fileRequires.value;
         const stage = {
             ...stageOutcome.value,
+            ...(browser !== undefined ? { browser } : {}),
             ...(entry.skill !== undefined ? { skill: entry.skill } : {}),
             ...(entry.mcp !== undefined ? { mcp: entry.mcp } : {}),
+            ...(entry.secrets !== undefined ? { secrets: entry.secrets } : {}),
+            ...(stageRequires !== undefined ? { requires: stageRequires } : {}),
         };
         stages.push(stage);
         stageSources[stageId] = { kind: "file", path: entry.body.absolutePath };
@@ -282,7 +315,11 @@ async function buildLoadedPipelineFromMerge(merge, options) {
         ...(pipelineAgent !== undefined ? { agent: pipelineAgent } : {}),
         ...(pipelineModel !== undefined ? { model: pipelineModel } : {}),
         ...(pipelineSchemas !== undefined ? { schemas: pipelineSchemas } : {}),
+        ...(pipelineRequires !== undefined ? { requires: pipelineRequires } : {}),
     };
+    const effectiveRequires = mergeToolRequires([pipelineRequires, ...loadedStages.map((s) => s.requires)], { pipelineId });
+    if (!effectiveRequires.ok)
+        return loadFailure(effectiveRequires.issues);
     const nodeById = new Map(dag.nodes.map((node) => [node.id, node]));
     for (const [stageId, after] of fileAfterById) {
         const node = nodeById.get(stageId);

package/dist/config/loadStage.js

@@ -7,6 +7,9 @@ import { parseModelField } from "./modelField.js";
 import { allowLegacyYamlAuthoring, dialectWarningForDocument, legacyAuthoringRejected, presentLegacyKeys, } from "./legacyYaml.js";
 import { parsePreEmitChecks } from "./parsePreEmitChecks.js";
 import { readYamlObject } from "./readYamlObject.js";
+import { parseStageSecrets } from "../runtime/stageSecretDecl.js";
+import { parseToolRequires } from "./toolRequires.js";
+import { parseStageBrowser } from "./stageBrowser.js";
 import { classifyYamlDocument, compileTargetContract, dialectFromKeys, mixedDialectIssue, STAGE_FILE_WIRING_KEYS, } from "./yamlDialect.js";
 const afterCompletionByStage = new WeakMap();
 /** After-phase IR from target `verify` (`when` includes after). Stamped onto DAG `completion`. */
@@ -348,6 +351,28 @@ function parseStageFields(raw, label, entryId, deferSchemaRefs, requireIo, compi
     if (mcpOutcome.value !== undefined) {
         stage.mcp = mcpOutcome.value;
     }
+    const secretsOutcome = parseStageSecrets(raw.secrets, label, entryId);
+    if (!secretsOutcome.ok)
+        return secretsOutcome;
+    if (secretsOutcome.value !== undefined) {
+        stage.secrets = secretsOutcome.value;
+    }
+    const requiresOutcome = parseToolRequires(raw.requires, `stage ${label}`, {
+        code: "stage.invalid_requires",
+        category: "stage",
+        stageId: entryId,
+    });
+    if (!requiresOutcome.ok)
+        return requiresOutcome;
+    if (requiresOutcome.value !== undefined) {
+        stage.requires = requiresOutcome.value;
+    }
+    const browserOutcome = parseStageBrowser(raw.browser, label, entryId);
+    if (!browserOutcome.ok)
+        return browserOutcome;
+    if (browserOutcome.value !== undefined) {
+        stage.browser = browserOutcome.value;
+    }
     const agentField = parseAgentField(raw.agent);
     if (!agentField.ok) {
         return loadFailure([

package/dist/config/loadStageflowManifest.js

@@ -6,6 +6,7 @@ import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { parseModelField } from "./modelField.js";
 const DEFAULT_PIPELINE_PATTERN = "*.pipeline.yaml";
 const DEFAULT_TASK_PATTERN = "*.task.yaml";
+const DEFAULT_TRIGGER_PATTERN = "*.trigger.yaml";
 export function manifestPathForProject(projectRoot) {
     return path.join(projectRoot, "stageflow.yaml");
 }
@@ -39,6 +40,7 @@ function parsePatterns(raw, issues) {
     const defaults = {
         pipeline: DEFAULT_PIPELINE_PATTERN,
         task: DEFAULT_TASK_PATTERN,
+        trigger: DEFAULT_TRIGGER_PATTERN,
     };
     if (raw === undefined || raw === null) {
         return defaults;
@@ -58,15 +60,24 @@ function parsePatterns(raw, issues) {
         : typeof record.task === "string" && record.task.trim().length > 0
             ? record.task.trim()
             : null;
+    const trigger = record.trigger === undefined
+        ? defaults.trigger
+        : typeof record.trigger === "string" && record.trigger.trim().length > 0
+            ? record.trigger.trim()
+            : null;
     if (pipeline === null) {
         issues.push(catalogIssue("catalog.manifest_invalid", "catalog.patterns.pipeline must be a string"));
     }
     if (task === null) {
         issues.push(catalogIssue("catalog.manifest_invalid", "catalog.patterns.task must be a string"));
     }
+    if (trigger === null) {
+        issues.push(catalogIssue("catalog.manifest_invalid", "catalog.patterns.trigger must be a string"));
+    }
     return {
         pipeline: pipeline ?? defaults.pipeline,
         task: task ?? defaults.task,
+        trigger: trigger ?? defaults.trigger,
     };
 }
 export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoot) {
@@ -109,6 +120,14 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
             exclude = parsed;
         }
     }
+    const triggersRaw = catalogRecord.triggers;
+    let triggers;
+    if (triggersRaw !== undefined) {
+        const parsed = parseStringArray(triggersRaw, "triggers", issues);
+        if (parsed !== null) {
+            triggers = parsed;
+        }
+    }
     const patterns = parsePatterns(catalogRecord.patterns, issues);
     let agent;
     const agentField = parseAgentField(record.agent);
@@ -136,6 +155,9 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
     if (exclude !== undefined) {
         catalog.exclude = exclude;
     }
+    if (triggers !== undefined) {
+        catalog.triggers = triggers;
+    }
     if (catalogRecord.patterns !== undefined) {
         catalog.patterns = {};
         if (typeof catalogRecord.patterns.pipeline === "string") {
@@ -144,6 +166,9 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
         if (typeof catalogRecord.patterns.task === "string") {
             catalog.patterns.task = patterns.task;
         }
+        if (typeof catalogRecord.patterns.trigger === "string") {
+            catalog.patterns.trigger = patterns.trigger;
+        }
     }
     const manifest = {
         version: 1,

package/dist/config/loadTask.d.ts

@@ -1,5 +1,7 @@
 import type { TaskFile } from "../types/task.js";
 import { type LoadOutcome } from "./loadOutcome.js";
+/** Structural TaskFile shape only — does not enforce workspace binding XOR. */
+export declare function coerceTaskFile(raw: unknown): TaskFile | undefined;
 export declare function parseTaskFile(raw: unknown, source?: string): LoadOutcome<TaskFile>;
 export declare function loadTaskFromYamlOutcome(yamlText: string, source?: string): LoadOutcome<TaskFile>;
 export declare function loadTaskOutcome(filePath: string): Promise<LoadOutcome<TaskFile>>;

package/dist/config/loadTask.js

@@ -1,12 +1,60 @@
 import { readFile } from "node:fs/promises";
 import { parse as parseYaml } from "yaml";
+import { resolveWorkspaceBinding } from "../runtime/workspaceBinding.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-export function parseTaskFile(raw, source = "task") {
+function parseGitIdentity(raw) {
+    if (!isPlainObject(raw))
+        return undefined;
+    const identity = {};
+    if (typeof raw.name === "string")
+        identity.name = raw.name;
+    if (typeof raw.email === "string")
+        identity.email = raw.email;
+    return identity;
+}
+/** Structural TaskFile shape only — does not enforce workspace binding XOR. */
+export function coerceTaskFile(raw) {
     const record = raw;
     if (typeof record?.id !== "string" || typeof record?.goal !== "string") {
+        return undefined;
+    }
+    if (record.input !== undefined && !isPlainObject(record.input)) {
+        return undefined;
+    }
+    return {
+        id: record.id,
+        goal: record.goal,
+        context: typeof record.context === "string" ? record.context : undefined,
+        constraints: typeof record.constraints === "string" ? record.constraints : undefined,
+        checkout: typeof record.checkout === "string" ? record.checkout : undefined,
+        ...(typeof record.repository === "string" ? { repository: record.repository } : {}),
+        ...(typeof record.ref === "string" ? { ref: record.ref } : {}),
+        ...(typeof record.run_branch_template === "string"
+            ? { run_branch_template: record.run_branch_template }
+            : {}),
+        ...(isPlainObject(record.git_identity)
+            ? { git_identity: parseGitIdentity(record.git_identity) }
+            : {}),
+        ...(record.input !== undefined ? { input: record.input } : {}),
+    };
+}
+export function parseTaskFile(raw, source = "task") {
+    const record = raw;
+    const task = coerceTaskFile(raw);
+    if (task === undefined) {
+        if (typeof record?.id === "string" && typeof record?.goal === "string") {
+            return loadFailure([
+                {
+                    code: "task.invalid_shape",
+                    message: `Invalid ${source}: input must be an object`,
+                    category: "task",
+                    taskId: record.id,
+                },
+            ]);
+        }
         return loadFailure([
             {
                 code: "task.invalid_shape",
@@ -16,24 +64,15 @@ export function parseTaskFile(raw, source = "task") {
             },
         ]);
     }
-    if (record.input !== undefined && !isPlainObject(record.input)) {
-        return loadFailure([
-            {
-                code: "task.invalid_shape",
-                message: `Invalid ${source}: input must be an object`,
-                category: "task",
-                taskId: record.id,
-            },
-        ]);
+    const binding = resolveWorkspaceBinding(task);
+    if (!binding.ok) {
+        return loadFailure(binding.issues.map((issue) => {
+            if (issue.category !== "task")
+                return issue;
+            return { ...issue, taskId: task.id };
+        }));
     }
-    return loadSuccess({
-        id: record.id,
-        goal: record.goal,
-        context: typeof record.context === "string" ? record.context : undefined,
-        constraints: typeof record.constraints === "string" ? record.constraints : undefined,
-        checkout: typeof record.checkout === "string" ? record.checkout : undefined,
-        ...(record.input !== undefined ? { input: record.input } : {}),
-    });
+    return loadSuccess(task);
 }
 export function loadTaskFromYamlOutcome(yamlText, source = "task yaml") {
     let raw;

package/dist/config/loadTrigger.d.ts

@@ -0,0 +1,9 @@
+import type { TriggerFile } from "../types/trigger.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+/** Structural TriggerFile shape only. */
+export declare function coerceTriggerFile(raw: unknown): TriggerFile | undefined;
+export declare function parseTriggerFile(raw: unknown, source?: string): LoadOutcome<TriggerFile>;
+export declare function loadTriggerFromYamlOutcome(yamlText: string, source?: string): LoadOutcome<TriggerFile>;
+export declare function loadTriggerOutcome(filePath: string): Promise<LoadOutcome<TriggerFile>>;
+export declare function loadTriggerFromYaml(yamlText: string, source?: string): TriggerFile;
+export declare function loadTrigger(filePath: string): Promise<TriggerFile>;

package/dist/config/loadTrigger.js

@@ -0,0 +1,120 @@
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseSchedule(raw) {
+    if (!isPlainObject(raw) || typeof raw.cron !== "string")
+        return undefined;
+    return {
+        cron: raw.cron,
+        ...(typeof raw.timezone === "string" ? { timezone: raw.timezone } : {}),
+    };
+}
+function parseEvent(raw) {
+    if (!isPlainObject(raw) || typeof raw.source !== "string")
+        return undefined;
+    return {
+        source: raw.source,
+        ...(isPlainObject(raw.match) ? { match: raw.match } : {}),
+        ...(isPlainObject(raw.config) ? { config: raw.config } : {}),
+    };
+}
+/** Structural TriggerFile shape only. */
+export function coerceTriggerFile(raw) {
+    const record = raw;
+    if (typeof record?.id !== "string" ||
+        typeof record?.pipeline !== "string" ||
+        typeof record?.enabled !== "boolean") {
+        return undefined;
+    }
+    if (record.task !== undefined && typeof record.task !== "string") {
+        return undefined;
+    }
+    if (record.kind !== "manual" && record.kind !== "schedule" && record.kind !== "event") {
+        return undefined;
+    }
+    let schedule;
+    if (record.schedule !== undefined) {
+        schedule = parseSchedule(record.schedule);
+        if (schedule === undefined)
+            return undefined;
+    }
+    let event;
+    if (record.event !== undefined) {
+        event = parseEvent(record.event);
+        if (event === undefined)
+            return undefined;
+    }
+    return {
+        id: record.id,
+        pipeline: record.pipeline,
+        kind: record.kind,
+        enabled: record.enabled,
+        ...(typeof record.task === "string" ? { task: record.task } : {}),
+        ...(schedule !== undefined ? { schedule } : {}),
+        ...(event !== undefined ? { event } : {}),
+    };
+}
+export function parseTriggerFile(raw, source = "trigger") {
+    const record = raw;
+    const trigger = coerceTriggerFile(raw);
+    if (trigger === undefined) {
+        return loadFailure([
+            {
+                code: "trigger.invalid_shape",
+                message: `Invalid ${source}: id, pipeline, kind, and enabled are required`,
+                category: "trigger",
+                triggerId: typeof record?.id === "string" ? record.id : undefined,
+            },
+        ]);
+    }
+    return loadSuccess(trigger);
+}
+export function loadTriggerFromYamlOutcome(yamlText, source = "trigger yaml") {
+    let raw;
+    try {
+        raw = parseYaml(yamlText);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return loadFailure([
+            {
+                code: "trigger.load_error",
+                message,
+                category: "trigger",
+            },
+        ]);
+    }
+    return parseTriggerFile(raw, source);
+}
+export async function loadTriggerOutcome(filePath) {
+    let yamlText;
+    try {
+        yamlText = await readFile(filePath, "utf8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return loadFailure([
+            {
+                code: "trigger.load_error",
+                message,
+                category: "trigger",
+            },
+        ]);
+    }
+    return loadTriggerFromYamlOutcome(yamlText, `trigger file ${filePath}`);
+}
+export function loadTriggerFromYaml(yamlText, source = "trigger yaml") {
+    const outcome = loadTriggerFromYamlOutcome(yamlText, source);
+    if (!outcome.ok)
+        throw new Error(outcome.issues[0].message);
+    return outcome.value;
+}
+export async function loadTrigger(filePath) {
+    const outcome = await loadTriggerOutcome(filePath);
+    if (!outcome.ok)
+        throw new Error(outcome.issues[0].message);
+    return outcome.value;
+}

package/dist/config/materializeStageModels.js

@@ -29,7 +29,11 @@ export async function materializeStageModels(stages, options) {
         if (!modelOutcome.ok) {
             return loadFailure(modelOutcome.issues);
         }
-        materialized.push({ ...stage, model: modelOutcome.value });
+        materialized.push({
+            ...stage,
+            model: modelOutcome.value.model,
+            model_tier: modelOutcome.value.tier,
+        });
     }
     return loadSuccess(materialized);
 }

package/dist/config/mergePipelineIncludes.d.ts

@@ -1,6 +1,7 @@
 import type { PayloadSchemaMap } from "../envelope/payloadSchema.js";
 import type { InlinePipelineDefinition } from "../types/pipeline.js";
 import { type LoadIssue, type LoadOutcome } from "./loadOutcome.js";
+import { type ToolRequirement } from "./toolRequires.js";
 export type RawMergedEntry = {
     raw: unknown;
     declaringPath: string;
@@ -11,6 +12,7 @@ export declare function mergePipelineStages(rootPath: string): Promise<LoadOutco
     agent?: string;
     model?: string;
     schemas?: PayloadSchemaMap;
+    requires?: ToolRequirement[];
     warnings: LoadIssue[];
 }>>;
 /** Synthetic `declaringPath` for stage entries with no backing file. */
@@ -21,5 +23,6 @@ export declare function mergeInlinePipelineStages(raw: InlinePipelineDefinition)
     agent?: string;
     model?: string;
     schemas?: PayloadSchemaMap;
+    requires?: ToolRequirement[];
     warnings: LoadIssue[];
 }>>;

package/dist/config/mergePipelineIncludes.js

@@ -4,6 +4,7 @@ import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { allowLegacyYamlAuthoring, dialectWarningForDocument, legacyAuthoringRejected, presentLegacyKeys, } from "./legacyYaml.js";
 import { parseModelField } from "./modelField.js";
 import { readYamlObject } from "./readYamlObject.js";
+import { parseToolRequires } from "./toolRequires.js";
 import { classifyYamlDocument, collectDocumentKeys, mixedDialectIssue, } from "./yamlDialect.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -177,6 +178,14 @@ export async function mergePipelineStages(rootPath) {
     if (!schemasOutcome.ok)
         return schemasOutcome;
     const schemas = schemasOutcome.value;
+    const requiresOutcome = parseToolRequires(raw.requires, `pipeline ${absRoot}`, {
+        code: "pipeline.invalid_requires",
+        category: "pipeline",
+        pipelineId,
+    });
+    if (!requiresOutcome.ok)
+        return requiresOutcome;
+    const requires = requiresOutcome.value;
     const idLocations = new Map();
     const entries = [];
     const warnings = [];
@@ -198,6 +207,7 @@ export async function mergePipelineStages(rootPath) {
         ...(agent !== undefined ? { agent } : {}),
         ...(model !== undefined ? { model } : {}),
         ...(schemas !== undefined ? { schemas } : {}),
+        ...(requires !== undefined ? { requires } : {}),
         warnings,
     });
 }
@@ -252,6 +262,14 @@ export async function mergeInlinePipelineStages(raw) {
     if (!schemasOutcome.ok)
         return schemasOutcome;
     const schemas = schemasOutcome.value;
+    const requiresOutcome = parseToolRequires(raw.requires, `inline pipeline ${pipelineId}`, {
+        code: "pipeline.invalid_requires",
+        category: "pipeline",
+        pipelineId,
+    });
+    if (!requiresOutcome.ok)
+        return requiresOutcome;
+    const requires = requiresOutcome.value;
     const entries = [];
     for (let index = 0; index < raw.stages.length; index++) {
         const entry = raw.stages[index];
@@ -273,6 +291,7 @@ export async function mergeInlinePipelineStages(raw) {
         ...(agent !== undefined ? { agent } : {}),
         ...(model !== undefined ? { model } : {}),
         ...(schemas !== undefined ? { schemas } : {}),
+        ...(requires !== undefined ? { requires } : {}),
         warnings: [],
     });
 }

package/dist/config/migrateYaml.js

@@ -1,7 +1,8 @@
-import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { runGitSync } from "../git/exec.js";
+import { statusPorcelain } from "../git/operations.js";
 import { loadPipelineOutcome } from "./loadPipeline.js";
 import { afterCompletionForStage, loadStageOutcome } from "./loadStage.js";
 import { withLegacyYamlAllowedAsync } from "./legacyYaml.js";
@@ -104,11 +105,10 @@ function verifyFingerprint(items) {
 }
 function gitToplevel(cwd) {
     try {
-        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        return runGitSync({
             cwd,
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
+            args: ["rev-parse", "--show-toplevel"],
+        }).stdout.trim();
     }
     catch {
         return null;
@@ -119,12 +119,7 @@ export function fileDirtyVsHead(absPath) {
     if (top === null)
         return true;
     try {
-        const status = execFileSync("git", ["status", "--porcelain", "--", absPath], {
-            cwd: top,
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        return status.trim().length > 0;
+        return statusPorcelain(top, absPath).trim().length > 0;
     }
     catch {
         return true;

package/dist/config/multiProjectCatalog.d.ts

@@ -0,0 +1,32 @@
+import { type PipelineListing, type TaskListing } from "./browseCatalog.js";
+import { type CatalogRoot, type ResolveCatalogRootsOptions } from "./resolveCatalogRoots.js";
+export type CatalogRootError = {
+    project_root: string;
+    code: "catalog_root_unreadable" | "unknown_project_root";
+    message: string;
+};
+export type MultiProjectListResult<T> = {
+    items: T[];
+    root_errors: CatalogRootError[];
+    roots: CatalogRoot[];
+    tip?: string;
+};
+export declare const EMPTY_CATALOG_LIST_TIP = "No catalog entries listed. Register a project root (POST /api/projects or local sf run / ensure), ensure stageflow.yaml exists at that root, then retry list_pipelines / list_tasks. Packaged examples use project_root \"examples\" when present. Git is not required for discovery.";
+export declare function listPipelinesMultiProject(options: ResolveCatalogRootsOptions & {
+    projectRootFilter?: string;
+}): Promise<MultiProjectListResult<PipelineListing & {
+    project_root: string;
+}>>;
+export declare function listTasksMultiProject(options: ResolveCatalogRootsOptions & {
+    projectRootFilter?: string;
+}): Promise<MultiProjectListResult<TaskListing & {
+    project_root: string;
+}>>;
+export declare function listModelsMultiProject(options: ResolveCatalogRootsOptions & {
+    projectRootFilter?: string;
+}): Promise<MultiProjectListResult<{
+    id: string;
+    project_root: string;
+}> & {
+    models: string[];
+}>;