stageflow 0.36.0 → 0.40.0

package/dist/config/mergePipelineIncludes.d.ts

@@ -15,6 +15,7 @@ export declare function mergePipelineStages(rootPath: string): Promise<LoadOutco
     schemas?: PayloadSchemaMap;
     requires?: ToolRequirement[];
     channels?: StageChannel[];
+    memories?: string[];
     warnings: LoadIssue[];
 }>>;
 /** Synthetic `declaringPath` for stage entries with no backing file. */
@@ -27,5 +28,6 @@ export declare function mergeInlinePipelineStages(raw: InlinePipelineDefinition)
     schemas?: PayloadSchemaMap;
     requires?: ToolRequirement[];
     channels?: StageChannel[];
+    memories?: string[];
     warnings: LoadIssue[];
 }>>;

package/dist/config/mergePipelineIncludes.js

@@ -7,6 +7,7 @@ import { readYamlObject } from "./readYamlObject.js";
 import { yamlParsePosition } from "./yamlParsePosition.js";
 import { parseToolRequires } from "./toolRequires.js";
 import { parseChannels } from "../channels/stageChannels.js";
+import { parseMemoryIdList } from "../memory/ids.js";
 import { classifyYamlDocument, collectDocumentKeys, mixedDialectIssue, } from "./yamlDialect.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -194,6 +195,10 @@ export async function mergePipelineStages(rootPath) {
     if (!channelsOutcome.ok)
         return channelsOutcome;
     const channels = channelsOutcome.value;
+    const memoriesOutcome = parsePipelineMemories(raw.memories, `pipeline ${absRoot}`, pipelineId);
+    if (!memoriesOutcome.ok)
+        return memoriesOutcome;
+    const memories = memoriesOutcome.value;
     const idLocations = new Map();
     const entries = [];
     const warnings = [];
@@ -217,6 +222,7 @@ export async function mergePipelineStages(rootPath) {
         ...(schemas !== undefined ? { schemas } : {}),
         ...(requires !== undefined ? { requires } : {}),
         ...(channels !== undefined ? { channels } : {}),
+        ...(memories !== undefined ? { memories } : {}),
         warnings,
     });
 }
@@ -283,6 +289,10 @@ export async function mergeInlinePipelineStages(raw) {
     if (!channelsOutcome.ok)
         return channelsOutcome;
     const channels = channelsOutcome.value;
+    const memoriesOutcome = parsePipelineMemories(raw.memories, `inline pipeline ${pipelineId}`, pipelineId);
+    if (!memoriesOutcome.ok)
+        return memoriesOutcome;
+    const memories = memoriesOutcome.value;
     const entries = [];
     for (let index = 0; index < raw.stages.length; index++) {
         const entry = raw.stages[index];
@@ -306,9 +316,24 @@ export async function mergeInlinePipelineStages(raw) {
         ...(schemas !== undefined ? { schemas } : {}),
         ...(requires !== undefined ? { requires } : {}),
         ...(channels !== undefined ? { channels } : {}),
+        ...(memories !== undefined ? { memories } : {}),
         warnings: [],
     });
 }
+function parsePipelineMemories(raw, label, pipelineId) {
+    const parsed = parseMemoryIdList(raw);
+    if (!parsed.ok) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_memories",
+                message: `Invalid ${label}: ${parsed.message}`,
+                category: "pipeline",
+                pipelineId,
+            },
+        ]);
+    }
+    return loadSuccess(parsed.value);
+}
 function parsePipelineChannels(raw, label, pipelineId) {
     if (raw === undefined)
         return loadSuccess(undefined);

package/dist/config/resolveStageMcpServers.d.ts

@@ -1,4 +1,4 @@
-export type StageMcpErrorCode = "missing_catalog" | "unknown_server" | "reserved_name" | "unresolved_var" | "invalid_config" | "untrusted_config_origin" | "connect_failed";
+export type StageMcpErrorCode = "missing_catalog" | "unknown_server" | "reserved_name" | "unresolved_var" | "invalid_config" | "untrusted_config_origin" | "connect_failed" | "host_state_corrupt";
 export declare class StageMcpError extends Error {
     readonly code: StageMcpErrorCode;
     constructor(message: string, code: StageMcpErrorCode);
@@ -9,18 +9,45 @@ export declare const MCP_CATALOG_FILENAME = ".mcp.json";
 export declare const STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV = "STAGEFLOW_STAGE_ARTIFACTS_DIR";
 export declare function stampStagePromptArtifactsDir(prompt: string, artifactsDir: string): string;
 export type McpCatalogServers = Record<string, Record<string, unknown>>;
+export type McpServerOrigin = "project" | "console";
 export type InspectedMcpCatalog = {
     path: string;
     servers: McpCatalogServers;
+    /** Where each server came from; `console` = saved from the UI under $STAGEFLOW_HOME. */
+    origins: Record<string, McpServerOrigin>;
+};
+/**
+ * Who is asking. Without a scope only the project `.mcp.json` is visible; with one, servers saved
+ * from the console are merged in (console entry wins on a name clash) and secrets are filled by
+ * the rules of that scope:
+ * - stage:    console secrets whose names the stage declared in `secrets:`, plus the stage env
+ * - agent:    console secrets plus Host env names listed in STAGEFLOW_MCP_ENV_ALLOW
+ * - probe:    same as agent, so a probe and an agent run resolve one config identically
+ * - validate: placeholders are checked but no secret value is ever read into the output
+ * Console secrets always win over Host env for the same name.
+ */
+export type McpResolveScope = {
+    kind: "stage";
+    secrets: readonly string[];
+} | {
+    kind: "agent";
+} | {
+    kind: "probe";
+} | {
+    kind: "validate";
+};
+export type McpCatalogLoadOptions = {
+    scope?: McpResolveScope;
 };
 export declare function mcpCatalogPath(projectRoot: string): string;
 export declare function parseMcpCatalog(raw: string, catalogPath?: string): McpCatalogServers;
-export declare function mcpCatalogExists(projectRoot: string): Promise<boolean>;
-export declare function loadMcpCatalog(projectRoot: string): Promise<InspectedMcpCatalog>;
+export declare function mcpCatalogExists(projectRoot: string, options?: McpCatalogLoadOptions): Promise<boolean>;
+export declare function loadMcpCatalog(projectRoot: string, options?: McpCatalogLoadOptions): Promise<InspectedMcpCatalog>;
 export type ProjectMcpCatalogTransport = "stdio" | "http";
 export type ProjectMcpCatalogEntry = {
     name: string;
     transport: ProjectMcpCatalogTransport;
+    origin: McpServerOrigin;
 };
 export type ProjectMcpCatalogListStatus = "ok" | "missing_catalog" | "invalid_config";
 export type ProjectMcpCatalogList = {
@@ -32,7 +59,10 @@ export declare function assertMcpAllowlistKnown(servers: McpCatalogServers, allo
 export declare function resolveStageMcpServers(options: {
     projectRoot: string;
     allowlist?: readonly string[];
+    /** Stage env for the project-only and stage scopes; agent/probe/validate do not read it as a secret source. */
     env: NodeJS.ProcessEnv;
+    /** Host env that STAGEFLOW_MCP_ENV_ALLOW may draw from (agent/probe scopes). Defaults to process.env. */
+    hostEnv?: NodeJS.ProcessEnv;
     stageId?: string;
     bindingKind?: "repository" | "checkout" | "none";
     trustWorkspaceConfig?: string[];
@@ -40,4 +70,6 @@ export declare function resolveStageMcpServers(options: {
     trustProjectRoot?: string;
     /** When true, .mcp.json is treated as workspace-sourced. */
     workspaceSourced?: boolean;
+    /** Merge console-saved servers and fill `${VAR}` by the scope's rules. Omit for project-only. */
+    scope?: McpResolveScope;
 }): Promise<ResolvedMcpServers>;

package/dist/config/resolveStageMcpServers.js

@@ -1,6 +1,8 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { STAGEFLOW_MCP_SERVER_NAME } from "../agent/claudeTools.js";
+import { isMcpHostStateError, mcpEnvAllowNames, readHostMcpServers, readMcpSecrets, } from "./mcpHostCatalog.js";
+import { assertSafeMcpUrl, McpUrlPolicyError } from "./mcpRedaction.js";
 export class StageMcpError extends Error {
     code;
     constructor(message, code) {
@@ -51,7 +53,31 @@ export function parseMcpCatalog(raw, catalogPath = MCP_CATALOG_FILENAME) {
     }
     return servers;
 }
-export async function mcpCatalogExists(projectRoot) {
+/** Console servers; a corrupt host file surfaces as a StageMcpError instead of reading as empty. */
+function hostServersOrThrow() {
+    try {
+        return readHostMcpServers();
+    }
+    catch (err) {
+        if (isMcpHostStateError(err))
+            throw new StageMcpError(err.message, "host_state_corrupt");
+        throw err;
+    }
+}
+function hostSecretsOrThrow() {
+    try {
+        return readMcpSecrets();
+    }
+    catch (err) {
+        if (isMcpHostStateError(err))
+            throw new StageMcpError(err.message, "host_state_corrupt");
+        throw err;
+    }
+}
+export async function mcpCatalogExists(projectRoot, options = {}) {
+    if (options.scope !== undefined && Object.keys(hostServersOrThrow()).length > 0) {
+        return true;
+    }
     try {
         await readFile(mcpCatalogPath(projectRoot), "utf8");
         return true;
@@ -63,20 +89,31 @@ export async function mcpCatalogExists(projectRoot) {
         throw err;
     }
 }
-export async function loadMcpCatalog(projectRoot) {
+export async function loadMcpCatalog(projectRoot, options = {}) {
     const catalogPath = mcpCatalogPath(projectRoot);
+    const hostServers = options.scope !== undefined ? hostServersOrThrow() : {};
     let raw;
     try {
         raw = await readFile(catalogPath, "utf8");
     }
     catch (err) {
         const code = err.code;
-        if (code === "ENOENT") {
+        if (code !== "ENOENT") {
+            throw new StageMcpError(`MCP catalog "${MCP_CATALOG_FILENAME}" could not be read`, "invalid_config");
+        }
+        if (Object.keys(hostServers).length === 0) {
             throw new StageMcpError(`MCP catalog "${MCP_CATALOG_FILENAME}" is missing`, "missing_catalog");
         }
-        throw new StageMcpError(`MCP catalog "${MCP_CATALOG_FILENAME}" could not be read`, "invalid_config");
     }
-    return { path: catalogPath, servers: parseMcpCatalog(raw, catalogPath) };
+    const servers = raw !== undefined ? parseMcpCatalog(raw, catalogPath) : {};
+    const origins = {};
+    for (const name of Object.keys(servers))
+        origins[name] = "project";
+    for (const [name, entry] of Object.entries(hostServers)) {
+        servers[name] = entry;
+        origins[name] = "console";
+    }
+    return { path: catalogPath, servers, origins };
 }
 function coarseMcpTransport(entry) {
     if (Object.hasOwn(entry, "command")) {
@@ -89,14 +126,20 @@ function coarseMcpTransport(entry) {
 }
 export async function listProjectMcpCatalog(projectRoot) {
     try {
-        const catalog = await loadMcpCatalog(projectRoot);
+        const catalog = await loadMcpCatalog(projectRoot, {
+            scope: { kind: "validate" },
+        });
         const servers = [];
         for (const [name, entry] of Object.entries(catalog.servers)) {
             const transport = coarseMcpTransport(entry);
             if (transport === undefined) {
                 return { status: "invalid_config", servers: [] };
             }
-            servers.push({ name, transport });
+            servers.push({
+                name,
+                transport,
+                origin: catalog.origins[name] ?? "project",
+            });
         }
         return { status: "ok", servers };
     }
@@ -207,6 +250,69 @@ function interpolateServer(entry, env, serverName, projectRoot, stageId) {
     }
     return stampSpawnRoot(resolved, projectRoot, serverName);
 }
+function bagOfStrings(value) {
+    return isPlainObject(value) && Object.values(value).every((v) => typeof v === "string");
+}
+/** Shape check for any entry about to be used (project or console). */
+function assertEntryShape(name, entry) {
+    const bad = (what) => {
+        throw new StageMcpError(`MCP catalog server "${name}" ${what}`, "invalid_config");
+    };
+    const hasCommand = Object.hasOwn(entry, "command");
+    const hasUrl = Object.hasOwn(entry, "url");
+    if (hasCommand === hasUrl)
+        bad('needs exactly one of "command" or "url"');
+    if (hasCommand && (typeof entry.command !== "string" || entry.command.length === 0)) {
+        bad('"command" must be a non-empty string');
+    }
+    if (hasUrl && (typeof entry.url !== "string" || entry.url.length === 0)) {
+        bad('"url" must be a non-empty string');
+    }
+    if (entry.args !== undefined &&
+        (!Array.isArray(entry.args) || entry.args.some((a) => typeof a !== "string"))) {
+        bad('"args" must be an array of strings');
+    }
+    for (const key of ["env", "headers"]) {
+        if (entry[key] !== undefined && !bagOfStrings(entry[key]))
+            bad(`"${key}" must map names to strings`);
+    }
+    if (entry.cwd !== undefined && typeof entry.cwd !== "string")
+        bad('"cwd" must be a string');
+}
+function assertResolvedUrlSafe(name, resolved) {
+    if (typeof resolved.url !== "string")
+        return;
+    try {
+        assertSafeMcpUrl(resolved.url);
+    }
+    catch (err) {
+        if (err instanceof McpUrlPolicyError) {
+            throw new StageMcpError(`MCP catalog server "${name}": ${err.message}`, "invalid_config");
+        }
+        throw err;
+    }
+}
+const VALIDATE_PLACEHOLDER = "<redacted>";
+/** The values `${NAME}` may be filled from, by scope. Console secrets win over Host env. */
+function envForScope(scope, stageEnv, hostEnv) {
+    const secrets = hostSecretsOrThrow();
+    if (scope.kind === "stage") {
+        const declared = new Set(scope.secrets);
+        const own = Object.fromEntries(Object.entries(secrets).filter(([n]) => declared.has(n)));
+        return { ...stageEnv, ...own };
+    }
+    const allowed = {};
+    for (const n of mcpEnvAllowNames(hostEnv)) {
+        if (hostEnv[n] !== undefined)
+            allowed[n] = hostEnv[n];
+    }
+    if (scope.kind === "validate") {
+        const names = new Set([...Object.keys(secrets), ...Object.keys(allowed), ...Object.keys(stageEnv)]);
+        return Object.fromEntries([...names].map((n) => [n, VALIDATE_PLACEHOLDER]));
+    }
+    // agent and probe: one rule, so the same config resolves the same way in both.
+    return { ...allowed, ...secrets };
+}
 export async function resolveStageMcpServers(options) {
     const allowlist = options.allowlist ?? [];
     if (allowlist.length === 0) {
@@ -224,11 +330,20 @@ export async function resolveStageMcpServers(options) {
             throw new StageMcpError(decision.message ?? "untrusted_config_origin", "untrusted_config_origin");
         }
     }
-    const catalog = await loadMcpCatalog(options.projectRoot);
+    // Workspace-sourced catalogs never see console servers or secrets.
+    const scope = options.workspaceSourced === true ? undefined : options.scope;
+    const catalog = await loadMcpCatalog(options.projectRoot, scope ? { scope } : {});
     assertMcpAllowlistKnown(catalog.servers, allowlist);
+    const env = scope
+        ? envForScope(scope, options.env, options.hostEnv ?? process.env)
+        : options.env;
     const resolved = {};
     for (const name of allowlist) {
-        resolved[name] = interpolateServer(catalog.servers[name], options.env, name, options.projectRoot, options.stageId);
+        const entry = catalog.servers[name];
+        assertEntryShape(name, entry);
+        resolved[name] = interpolateServer(entry, env, name, options.projectRoot, options.stageId);
+        if (scope?.kind !== "validate")
+            assertResolvedUrlSafe(name, resolved[name]);
     }
     return resolved;
 }

package/dist/config/validateCatalog.d.ts

@@ -4,7 +4,7 @@ import type { LoadIssue } from "./loadOutcome.js";
 import type { AnyChannelProvider } from "../channels/types.js";
 export type ValidationSeverity = "error" | "warning";
 export type ValidationCategory = "pipeline" | "stage" | "catalog" | "task" | "trigger";
-export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.stage_wrapper_skill_rejected" | "pipeline.invalid_completion" | "catalog.path_case_mismatch" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "pipeline.invalid_model" | "pipeline.invalid_verify" | "pipeline.io_incompatible" | "pipeline.model_applies" | "pipeline.route_if_invalid" | "pipeline.route_all_gated" | "pipeline.invalid_requires" | "pipeline.requires_conflict" | "pipeline.invalid_channels" | "stage.invalid_shape" | "stage.invalid_model" | "stage.missing_model" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.unresolved_schema_ref" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_channels" | "stage.channel_unavailable" | "stage.invalid_browser" | "stage.invalid_secrets" | "stage.unknown_secret" | "stage.denied_secret" | "stage.invalid_requires" | "stage.invalid_agent" | "stage.invalid_io" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "task.entry_input_unmet" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid" | "trigger.invalid_shape" | "trigger.load_error" | "trigger.unknown_pipeline" | "trigger.unknown_task" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp" | "catalog.mcp_command_missing" | "catalog.mixed_yaml_dialect" | "catalog.legacy_yaml" | "catalog.stageflow_home_absolute_path";
+export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.stage_wrapper_skill_rejected" | "pipeline.invalid_completion" | "catalog.path_case_mismatch" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "pipeline.invalid_model" | "pipeline.invalid_verify" | "pipeline.io_incompatible" | "pipeline.model_applies" | "pipeline.route_if_invalid" | "pipeline.route_all_gated" | "pipeline.invalid_requires" | "pipeline.requires_conflict" | "pipeline.invalid_channels" | "pipeline.invalid_memories" | "pipeline.memory_unavailable" | "stage.invalid_shape" | "stage.invalid_model" | "stage.missing_model" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.unresolved_schema_ref" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_channels" | "stage.channel_unavailable" | "stage.invalid_browser" | "stage.invalid_secrets" | "stage.unknown_secret" | "stage.denied_secret" | "stage.invalid_requires" | "stage.invalid_agent" | "stage.invalid_io" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "task.entry_input_unmet" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid" | "trigger.invalid_shape" | "trigger.load_error" | "trigger.unknown_pipeline" | "trigger.unknown_task" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp" | "catalog.mcp_command_missing" | "catalog.mixed_yaml_dialect" | "catalog.legacy_yaml" | "catalog.stageflow_home_absolute_path";
 export type ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;

package/dist/config/validateCatalog.js

@@ -17,6 +17,7 @@ import { findMissingMcpCommands } from "../preflight/mcpCommands.js";
 import { ChannelError } from "../channels/errors.js";
 import { ChannelRegistry } from "../channels/registry.js";
 import { validateStageChannels } from "../channels/stageChannels.js";
+import { inspectMemorySync, memoryHome } from "../memory/host.js";
 export function relPath(cwd, absPath) {
     return path.relative(cwd, absPath).replace(/\\/g, "/");
 }
@@ -276,6 +277,25 @@ function findingsForStageChannels(cwd, pipelinePath, loaded, projectRoot, provid
     }
     return users.flatMap((stage) => validateStageChannels(registry, stage).map((issue) => findingStageError(cwd, pipelinePath, issue.message, "stage.channel_unavailable", issue.stageId)));
 }
+const MEMORY_FINDING = {
+    MEMORY_NOT_FOUND: (id) => `Memory "${id}" does not exist. Create it before attaching it.`,
+    MEMORY_MISMATCH: (id) => `Memory "${id}" does not match the id in its file.`,
+    MEMORY_UNREADABLE: (id) => `Memory "${id}" could not be read.`,
+    MEMORY_INVALID_ID: (id) => `Memory "${id}" is not a valid id.`,
+};
+function findingsForMemories(cwd, pipelinePath, loaded) {
+    const ids = loaded.pipeline.memories;
+    if (!ids?.length)
+        return [];
+    const home = memoryHome();
+    return ids.flatMap((id) => {
+        const inspected = inspectMemorySync(home, id);
+        if (inspected.ok)
+            return [];
+        const message = (MEMORY_FINDING[inspected.code] ?? MEMORY_FINDING.MEMORY_UNREADABLE)(id);
+        return [findingPipelineError(cwd, pipelinePath, message, "pipeline.memory_unavailable", loaded.pipeline.id)];
+    });
+}
 function findingsForStageSecrets(cwd, pipelinePath, loaded) {
     const registry = loadSecretRegistry(process.env);
     const findings = [];
@@ -386,7 +406,7 @@ async function findingsForStageMcpCatalog(cwd, loaded) {
     }
     let catalog;
     try {
-        catalog = await loadMcpCatalog(projectRoot);
+        catalog = await loadMcpCatalog(projectRoot, { scope: { kind: "validate" } });
     }
     catch (err) {
         if (!(err instanceof StageMcpError))
@@ -459,6 +479,7 @@ async function runPipelineValidation(nameOrPath, options) {
     findings.push(...(await findingsForStageMcpCatalog(cwd, outcome.value)));
     findings.push(...findingsForStageSecrets(cwd, pipelinePath, outcome.value));
     findings.push(...findingsForStageChannels(cwd, pipelinePath, outcome.value, projectRoot, options.channelProviders));
+    findings.push(...findingsForMemories(cwd, pipelinePath, outcome.value));
     findings.push(...findingsForStageflowHomeAbsolutePaths(cwd, outcome.value));
     if (validateStages && outcome.value.stageSources) {
         for (const source of Object.values(outcome.value.stageSources)) {

package/dist/mcp/agentTools.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { McpToolDeps } from "./deps.js";
+/**
+ * Agent management for operators driving Stageflow over MCP. A running agent reaches these
+ * only through the Stageflow tool groups it is granted (`agents.*`); the guard in
+ * `toolkit/guard.ts` stops it acting on its own sessions.
+ */
+export declare function registerAgentTools(server: McpServer, deps: McpToolDeps): void;

package/dist/mcp/agentTools.js

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { defaultAgentProjectRoot } from "../agents/projectRoot.js";
+import { AGENT_ID_PATTERN } from "../config/loadAgent.js";
+import { AgentError, isAgentError } from "../agents/errors.js";
+import { SESSION_STATUSES } from "../agents/store.js";
+import { textResult } from "./toolResults.js";
+const agentId = z.string().regex(AGENT_ID_PATTERN);
+const MCP_ACTOR = { source: "api", author: "mcp" };
+function required(value, what) {
+    if (value === undefined)
+        throw new Error(`MCP agent tools require ${what} from host bootstrap`);
+    return value;
+}
+/** Run a service call and turn domain failures into tool errors with their code and field issues. */
+async function call(work) {
+    try {
+        return textResult(await work());
+    }
+    catch (error) {
+        if (isAgentError(error)) {
+            return textResult({ code: error.code, message: error.message, ...(error.issues.length ? { issues: error.issues } : {}) }, true);
+        }
+        throw error;
+    }
+}
+/**
+ * Agent management for operators driving Stageflow over MCP. A running agent reaches these
+ * only through the Stageflow tool groups it is granted (`agents.*`); the guard in
+ * `toolkit/guard.ts` stops it acting on its own sessions.
+ */
+export function registerAgentTools(server, deps) {
+    const service = () => required(deps.agentService, "agentService");
+    const chat = () => required(deps.agentChat, "agentChat");
+    const root = () => defaultAgentProjectRoot(deps.cwd);
+    /** A session must belong to the agent named in the call, or it is not found (as in the HTTP routes). */
+    const sessionFor = async (id, sessionId) => {
+        const detail = await service().getSession(root(), sessionId);
+        if (detail.session.agentId !== id)
+            throw new AgentError("agent.session_not_found");
+        return detail;
+    };
+    server.registerTool("list_agents", { description: "List project agents (agents/*.agent.yaml) with status and session stats.", inputSchema: z.object({}) }, () => call(async () => ({ agents: await service().list(root()) })));
+    server.registerTool("get_agent", {
+        description: "Get one agent: summary, full definition, canonical YAML, and warnings.",
+        inputSchema: z.object({ id: agentId }),
+    }, ({ id }) => call(() => service().get(root(), id)));
+    server.registerTool("validate_agent", {
+        description: "Validate an agent definition without saving. Returns field issues, warnings, and canonical YAML.",
+        inputSchema: z.object({ definition: z.record(z.string(), z.unknown()) }),
+    }, ({ definition }) => call(() => service().validate(root(), definition)));
+    server.registerTool("create_agent", {
+        description: "Create an agent. It always starts disabled; enable it with enable_agent.",
+        inputSchema: z.object({ definition: z.record(z.string(), z.unknown()) }),
+    }, ({ definition }) => call(() => service().create(root(), definition, MCP_ACTOR)));
+    server.registerTool("save_agent", {
+        description: "Save a full agent definition as a new revision. baseRevision must be the current revision (optimistic lock).",
+        inputSchema: z.object({
+            id: agentId,
+            baseRevision: z.number().int().nonnegative(),
+            definition: z.record(z.string(), z.unknown()),
+            summary: z.string().max(200).optional(),
+        }),
+    }, ({ id, baseRevision, definition, summary }) => call(() => service().save(root(), id, { baseRevision, definition, summary: summary ?? null }, MCP_ACTOR)));
+    server.registerTool("enable_agent", { description: "Enable an agent for new sessions and turns.", inputSchema: z.object({ id: agentId }) }, ({ id }) => call(() => service().setEnabled(root(), id, true, MCP_ACTOR)));
+    server.registerTool("disable_agent", {
+        description: "Disable an agent. New sessions and turns are refused; a running turn finishes.",
+        inputSchema: z.object({ id: agentId }),
+    }, ({ id }) => call(() => service().setEnabled(root(), id, false, MCP_ACTOR)));
+    server.registerTool("list_agent_revisions", { description: "List an agent's revisions, newest first.", inputSchema: z.object({ id: agentId }) }, ({ id }) => call(async () => ({ revisions: await service().listRevisions(root(), id) })));
+    server.registerTool("restore_agent_revision", {
+        description: "Save an earlier revision's definition as the newest revision.",
+        inputSchema: z.object({
+            id: agentId,
+            revision: z.number().int().positive(),
+            baseRevision: z.number().int().nonnegative(),
+        }),
+    }, ({ id, revision, baseRevision }) => call(() => service().restore(root(), id, { revision, baseRevision }, MCP_ACTOR)));
+    server.registerTool("agent_chat", {
+        description: "Send one message to an agent and wait for its reply. Omit sessionId to start a new session.",
+        inputSchema: z.object({ id: agentId, message: z.string().min(1), sessionId: z.string().optional() }),
+    }, ({ id, message, sessionId }) => call(() => chat().send({
+        projectRoot: root(),
+        agentId: id,
+        text: message,
+        source: "mcp",
+        ...(sessionId ? { sessionId } : {}),
+    })));
+    server.registerTool("get_agent_session", {
+        description: "Fetch a session of an agent: transcript, turns, approvals.",
+        inputSchema: z.object({ id: agentId, sessionId: z.string() }),
+    }, ({ id, sessionId }) => call(() => sessionFor(id, sessionId)));
+    server.registerTool("list_agent_sessions", {
+        description: "List an agent's sessions, newest first, with turn counts, tokens and cost.",
+        inputSchema: z.object({
+            id: agentId,
+            status: z.enum(SESSION_STATUSES).optional(),
+            search: z.string().optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+            cursor: z.string().optional(),
+        }),
+    }, ({ id, status, search, limit, cursor }) => call(() => service().listSessions(root(), id, {
+        limit: limit ?? 25,
+        ...(status ? { status } : {}),
+        ...(search ? { search } : {}),
+        ...(cursor ? { cursor } : {}),
+    })));
+    server.registerTool("stop_agent_session", {
+        description: "Stop the turn currently running in a session. The session stays open.",
+        inputSchema: z.object({ id: agentId, sessionId: z.string() }),
+    }, ({ id, sessionId }) => call(async () => {
+        await sessionFor(id, sessionId);
+        return { stopped: chat().stop(sessionId) };
+    }));
+    server.registerTool("archive_agent", {
+        description: "Archive an agent: its definition leaves the project and new sessions are refused. Past sessions are kept.",
+        inputSchema: z.object({ id: agentId }),
+    }, ({ id }) => call(async () => { await service().archive(root(), id); return { archived: true }; }));
+    server.registerTool("approve_agent_action", {
+        description: "Approve the pending ask-first action on a session of an agent, as an operator.",
+        inputSchema: z.object({ id: agentId, sessionId: z.string() }),
+    }, ({ id, sessionId }) => call(async () => {
+        await sessionFor(id, sessionId);
+        return service().decideApproval(root(), sessionId, "approve", { kind: "operator" });
+    }));
+    server.registerTool("deny_agent_action", {
+        description: "Deny the pending ask-first action on a session of an agent. The agent is told it was refused.",
+        inputSchema: z.object({ id: agentId, sessionId: z.string() }),
+    }, ({ id, sessionId }) => call(async () => {
+        await sessionFor(id, sessionId);
+        return service().decideApproval(root(), sessionId, "deny", { kind: "operator" });
+    }));
+}

package/dist/mcp/catalogTools.js

@@ -1,6 +1,7 @@
+import { buildModelsResponse } from "../models/response.js";
 import { z } from "zod";
 import { catalogPathErrorBody, CatalogPathError, resolveCatalogRelativePath, resolveCatalogStartInput, selectCatalogRootForStart, } from "../config/catalogRelativePath.js";
-import { listModelsMultiProject, listPipelinesMultiProject, listTasksMultiProject, } from "../config/multiProjectCatalog.js";
+import { listPipelinesMultiProject, listTasksMultiProject, } from "../config/multiProjectCatalog.js";
 import { resolveCatalogRoots } from "../config/resolveCatalogRoots.js";
 import { describePipeline } from "../config/describePipeline.js";
 import { loadPipeline } from "../config/loadPipeline.js";
@@ -41,7 +42,17 @@ const taskFileSchema = z.object({
     goal: z.string(),
     context: z.string().optional(),
     constraints: z.string().optional(),
-    checkout: z.string().optional(),
+    checkout: z
+        .union([
+        z.string(),
+        z
+            .object({
+            branch: z.string().optional(),
+            base: z.string().optional(),
+        })
+            .strict(),
+    ])
+        .optional(),
     repository: z.string().optional(),
     ref: z.string().optional(),
     run_branch_template: z.string().optional(),
@@ -233,14 +244,14 @@ export function registerCatalogTools(server, deps) {
         });
     });
     server.registerTool("list_models", {
-        description: "List catalog model ids across every project this host knows about (same multi-root source as GET /api/models). Optional project_root filter narrows.",
+        description: "List model ids from the providers connected on this host, plus ids pipelines use (same source as GET /api/models). Returns models, providers (grouped), the default model and unlisted ids. Optional project_root filter narrows the pipeline-used ids.",
         inputSchema: z.object({
             project_root: z.string().optional(),
         }),
     }, async ({ project_root }) => {
-        const result = await listModelsMultiProject({
+        const { response, used: result } = await buildModelsResponse({
             store,
-            bootCwd: cwd,
+            cwd,
             projectRootFilter: project_root,
         });
         if (result.root_errors.some((e) => e.code === "unknown_project_root") &&
@@ -251,11 +262,7 @@ export function registerCatalogTools(server, deps) {
                 root_errors: result.root_errors,
             }, true);
         }
-        return textResult({
-            models: result.models,
-            entries: result.items,
-            root_errors: result.root_errors,
-        });
+        return textResult(response);
     });
     server.registerTool("list_runs", {
         description: "List known pipeline runs. Optional filters: status, since (ISO created_at lower bound), pipeline (id or path), caller_id.",

package/dist/mcp/deps.d.ts

@@ -1,5 +1,8 @@
 import type { BootProviderResult } from "../agent/bootProviderConfig.js";
 import type { ProviderAuthContext } from "../agent/providerAuth.js";
+import type { AgentChatController } from "../agents/chatTurn.js";
+import type { ConversationBackend } from "../agents/sessions.js";
+import type { AgentService } from "../agents/service.js";
 import type { RunStore } from "../runstore/port.js";
 import type { RunChangeBus } from "../runtime/runChangeBus.js";
 import type { RunManager } from "../runtime/runManager.js";
@@ -11,6 +14,9 @@ export type McpToolDeps = {
     providerAuthContext?: ProviderAuthContext;
     projectRoot?: string;
     providerBoot?: BootProviderResult;
+    agentService?: AgentService;
+    agentChat?: AgentChatController;
+    agentConversationBackend?: ConversationBackend;
 };
 export type McpHttpDeps = McpToolDeps & {
     runChangeBus: RunChangeBus;

package/dist/mcp/pipelineAuthorSupport.d.ts

@@ -0,0 +1,19 @@
+import { loadDraftPackage, validateDraftPackage, type DraftPackage } from "../config/draftPackage.js";
+export { loadDraftPackage, validateDraftPackage, type DraftPackage };
+export type PublishFacadeResult = {
+    ok: true;
+    pipelinePath: string;
+    stagePaths: string[];
+    taskPath?: string;
+} | {
+    ok: false;
+    error: string;
+    status: number;
+};
+/** Write a package the way the Workshop's save does, flattening its result shape. */
+export declare function publishDraftPackageFacade(projectRoot: string, input: {
+    directory: string;
+    draft: DraftPackage;
+    pipelineFilename: string;
+    allowInvalid?: boolean;
+}, mode: "create" | "overwrite"): Promise<PublishFacadeResult>;