stageflow 0.42.0 → 0.44.0

package/dist/guide/threadStore.js

@@ -0,0 +1,189 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+function guardThreadId(threadId) {
+    const trimmed = threadId.trim();
+    if (!trimmed || trimmed.includes("/") || trimmed.includes("\\") || trimmed.includes("..") || trimmed === ".") {
+        throw new Error("guide.invalid");
+    }
+    return trimmed;
+}
+export function guideThreadsDir(storeRoot = globalStageflowHome()) {
+    return path.join(storeRoot, "guide", "threads");
+}
+export function guideThreadFilePath(threadId, storeRoot = globalStageflowHome()) {
+    return path.join(guideThreadsDir(storeRoot), guardThreadId(threadId), "thread.json");
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseMessage(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (typeof value.id !== "string" || !value.id)
+        return null;
+    if (value.role !== "user" && value.role !== "assistant")
+        return null;
+    if (typeof value.text !== "string")
+        return null;
+    if (typeof value.createdAt !== "string" || !value.createdAt)
+        return null;
+    const attachments = attachmentMeta(value.attachments);
+    const parts = guideParts(value.parts);
+    return {
+        id: value.id,
+        role: value.role,
+        text: value.text,
+        createdAt: value.createdAt,
+        ...(attachments.length > 0 ? { attachments } : {}),
+        ...(parts.length > 0 ? { parts } : {}),
+    };
+}
+function guideParts(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        if (!isPlainObject(entry))
+            continue;
+        if (entry.type === "text" && typeof entry.text === "string") {
+            out.push({ type: "text", text: entry.text });
+            continue;
+        }
+        if (entry.type !== "tool" || typeof entry.id !== "string" || typeof entry.name !== "string")
+            continue;
+        if (entry.status !== "complete" && entry.status !== "error")
+            continue;
+        out.push({
+            type: "tool",
+            id: entry.id,
+            name: entry.name,
+            status: entry.status,
+            ...(isPlainObject(entry.args) ? { args: entry.args } : {}),
+            ...(entry.result !== undefined ? { result: entry.result } : {}),
+            ...(typeof entry.error === "string" ? { error: entry.error } : {}),
+        });
+    }
+    return out;
+}
+function attachmentMeta(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        if (!isPlainObject(entry) || typeof entry.name !== "string" || !entry.name)
+            continue;
+        out.push({
+            name: entry.name,
+            size: typeof entry.size === "number" ? entry.size : 0,
+            mediaType: typeof entry.mediaType === "string" && entry.mediaType ? entry.mediaType : "text/plain",
+        });
+    }
+    return out;
+}
+export function parseGuideThread(value) {
+    if (!isPlainObject(value) || value.version !== 1)
+        return null;
+    if (typeof value.id !== "string" || !value.id)
+        return null;
+    if (typeof value.title !== "string")
+        return null;
+    if (typeof value.createdAt !== "string" || typeof value.updatedAt !== "string")
+        return null;
+    if (!Array.isArray(value.messages))
+        return null;
+    const messages = [];
+    for (const entry of value.messages) {
+        const message = parseMessage(entry);
+        if (!message)
+            return null;
+        messages.push(message);
+    }
+    const model = typeof value.model === "string" && value.model.trim() ? value.model.trim() : undefined;
+    return {
+        version: 1,
+        id: value.id,
+        title: value.title,
+        createdAt: value.createdAt,
+        updatedAt: value.updatedAt,
+        messages,
+        ...(model ? { model } : {}),
+    };
+}
+function writeRecord(record, storeRoot) {
+    const file = guideThreadFilePath(record.id, storeRoot);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(record));
+}
+export function createGuideThread(storeRoot) {
+    const now = new Date().toISOString();
+    const record = {
+        version: 1,
+        id: randomUUID(),
+        title: "",
+        createdAt: now,
+        updatedAt: now,
+        messages: [],
+    };
+    writeRecord(record, storeRoot);
+    return record;
+}
+export function readGuideThread(threadId, storeRoot) {
+    let file;
+    try {
+        file = guideThreadFilePath(threadId, storeRoot);
+    }
+    catch {
+        return null;
+    }
+    if (!existsSync(file))
+        return null;
+    try {
+        return parseGuideThread(JSON.parse(readFileSync(file, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveGuideThread(record, storeRoot) {
+    writeRecord(record, storeRoot);
+    return record;
+}
+export function setGuideThreadModel(threadId, model, storeRoot) {
+    const record = readGuideThread(threadId, storeRoot);
+    if (!record)
+        return null;
+    const trimmed = typeof model === "string" ? model.trim() : "";
+    const next = {
+        version: 1,
+        id: record.id,
+        title: record.title,
+        createdAt: record.createdAt,
+        updatedAt: new Date().toISOString(),
+        messages: record.messages,
+        ...(trimmed ? { model: trimmed } : {}),
+    };
+    writeRecord(next, storeRoot);
+    return next;
+}
+export function listGuideThreads(storeRoot) {
+    const dir = guideThreadsDir(storeRoot);
+    if (!existsSync(dir))
+        return [];
+    const summaries = [];
+    for (const entry of readdirSync(dir)) {
+        const record = readGuideThread(entry, storeRoot);
+        if (!record)
+            continue;
+        summaries.push({ id: record.id, title: record.title, updatedAt: record.updatedAt });
+    }
+    summaries.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : 0));
+    return summaries;
+}
+export function guideTitleFrom(text) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    if (!flat)
+        return "New chat";
+    return flat.length > 48 ? `${flat.slice(0, 47).trimEnd()}…` : flat;
+}

package/dist/guide/writeRoot.d.ts

@@ -0,0 +1,11 @@
+/** Where the Guide saves. A project with stageflow.yaml keeps its own catalog. Otherwise the workspace catalog, which Pipelines and Catalog list. */
+export declare function guideWriteRoot(hostProjectRoot: string): string;
+/** One folder per pipeline. Stage files are written beside the pipeline file. */
+export declare function guidePipelineDirectory(id: string): string;
+export declare function guidePipelineFile(id: string): string;
+/**
+ * Pipeline and stage files always land in pipelines/<id>/.
+ * A path that already exists under the catalog is left alone so an edit keeps that package.
+ * Any other path, including one the person named, is rewritten.
+ */
+export declare function placeGuideWriteArgs(name: string, args: Record<string, unknown>, fileExists?: (relPath: string) => boolean): Record<string, unknown>;

package/dist/guide/writeRoot.js

@@ -0,0 +1,70 @@
+import { accessSync } from "node:fs";
+import path from "node:path";
+import { GUIDE_PIPELINES_ROOT } from "../config/ensureCatalogScanRoot.js";
+import { STAGE_ID_PATTERN } from "../config/createStage.js";
+import { ensureWorkspaceCatalog, workspaceCatalogPath } from "../project/workspaceCatalog.js";
+/** Where the Guide saves. A project with stageflow.yaml keeps its own catalog. Otherwise the workspace catalog, which Pipelines and Catalog list. */
+export function guideWriteRoot(hostProjectRoot) {
+    try {
+        accessSync(path.join(hostProjectRoot, "stageflow.yaml"));
+        return hostProjectRoot;
+    }
+    catch {
+        ensureWorkspaceCatalog();
+        return workspaceCatalogPath();
+    }
+}
+/** One folder per pipeline. Stage files are written beside the pipeline file. */
+export function guidePipelineDirectory(id) {
+    return `${GUIDE_PIPELINES_ROOT}/${id}`;
+}
+export function guidePipelineFile(id) {
+    return `${guidePipelineDirectory(id)}/${id}.pipeline.yaml`;
+}
+const PACKAGE_PATH_TOOLS = new Set([
+    "create_stage",
+    "edit_stage",
+    "edit_pipeline",
+    "create_task",
+    "edit_task",
+    "read_pipeline",
+]);
+function pipelineIdFromFile(relPath) {
+    const base = relPath.replace(/\\/g, "/").split("/").pop() ?? "";
+    if (!base.endsWith(".pipeline.yaml"))
+        return undefined;
+    const id = base.slice(0, -".pipeline.yaml".length);
+    return STAGE_ID_PATTERN.test(id) ? id : undefined;
+}
+function escapesProject(relPath) {
+    const norm = relPath.replace(/\\/g, "/");
+    return path.isAbsolute(relPath) || norm.startsWith("/") || norm.split("/").includes("..");
+}
+/**
+ * Pipeline and stage files always land in pipelines/<id>/.
+ * A path that already exists under the catalog is left alone so an edit keeps that package.
+ * Any other path, including one the person named, is rewritten.
+ */
+export function placeGuideWriteArgs(name, args, fileExists = () => false) {
+    const next = { ...args };
+    delete next.project_root;
+    const id = typeof next.id === "string" ? next.id.trim() : "";
+    if (STAGE_ID_PATTERN.test(id)) {
+        if (name === "create_pipeline")
+            next.directory = guidePipelineDirectory(id);
+        if (name === "create_stage_file")
+            next.pipeline_directory = guidePipelineDirectory(id);
+    }
+    if (!PACKAGE_PATH_TOOLS.has(name) || typeof next.path !== "string")
+        return next;
+    const given = next.path.trim();
+    const pipelineId = pipelineIdFromFile(given);
+    if (!pipelineId)
+        return next;
+    const canonical = guidePipelineFile(pipelineId);
+    if (given.replace(/\\/g, "/") === canonical)
+        return next;
+    if (escapesProject(given) || !fileExists(given))
+        next.path = canonical;
+    return next;
+}

package/dist/hosted/translate.js

@@ -6,6 +6,8 @@ const ACTIVITY_EVENTS = new Set([
     "tool_start",
     "tool_end",
     "tool_progress",
+    "context_usage",
+    "context_compacted",
     "message",
     "operator_prompt",
     "operator_answer",

package/dist/mcp/agentTools.js

@@ -67,6 +67,18 @@ export function registerAgentTools(server, deps) {
         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("get_agent_revision", {
+        description: "Get one revision of an agent, including its definition and canonical YAML.",
+        inputSchema: z.object({ id: agentId, revision: z.number().int().positive() }),
+    }, ({ id, revision }) => call(() => service().getRevision(root(), id, revision)));
+    server.registerTool("diff_agent_revisions", {
+        description: "Diff two revisions of an agent, from one revision number to another.",
+        inputSchema: z.object({
+            id: agentId,
+            from: z.number().int().positive(),
+            to: z.number().int().positive(),
+        }),
+    }, ({ id, from, to }) => call(() => service().diffRevisions(root(), id, from, to)));
     server.registerTool("restore_agent_revision", {
         description: "Save an earlier revision's definition as the newest revision.",
         inputSchema: z.object({

package/dist/mcp/catalogTools.js

@@ -77,13 +77,10 @@ const inlinePipelineSchema = z
     channels: z.unknown().optional(),
 })
     .strict();
-const startRunSchema = z
-    .object({
+const startRunCommon = {
     pipeline: z
         .union([z.string(), inlinePipelineSchema])
         .describe("Catalog-relative pipeline path, or an inline pipeline definition object ({ id, stages: [...] }) authored directly in this call"),
-    task_path: z.string().optional(),
-    task: taskFileSchema.optional(),
     project_root: z.string().optional(),
     checkout: z
         .string()
@@ -101,11 +98,11 @@ const startRunSchema = z
         .record(z.string(), z.record(z.string(), z.string()))
         .optional()
         .describe("Run-scoped skills: name → { relativePath: utf-8 contents }. Requires SKILL.md per name; materialised under the run workspace skills dir (never the worktree)"),
-})
-    .passthrough()
-    .refine((data) => Boolean(data.task_path) !== Boolean(data.task), {
-    message: "Exactly one of task_path or task is required",
-});
+};
+const startRunSchema = z.union([
+    z.strictObject({ ...startRunCommon, task_path: z.string() }),
+    z.strictObject({ ...startRunCommon, task: taskFileSchema }),
+]);
 /**
  * Deliberately thin, same reasoning as inlinePipelineSchema above: real
  * structural validation of the stage body happens downstream through the
@@ -116,8 +113,7 @@ const envelopeRefSchema = z.object({
     stageId: z.string(),
     attempt: z.number().int().positive().optional(),
 });
-const runStageSchema = z
-    .object({
+const runStageCommon = {
     stage: z
         .union([z.string(), z.record(z.string(), z.unknown())])
         .describe("Catalog-relative path to a stage YAML file (same path contract as start_run — absolute paths rejected, must be inside a registered project_root), or a bare inline stage body object ({ id, system_prompt, io, model?, gate_kinds?, mcp?, verify?, timeout_ms? } — no uses:/route/pipeline wrapper) authored directly in this call"),
@@ -125,12 +121,6 @@ const runStageSchema = z
         .string()
         .optional()
         .describe("Catalog project root to resolve a string stage path against; required when multiple catalog roots are configured and no sole non-seeded root exists"),
-    task_path: z.string().optional(),
-    task: taskFileSchema.optional(),
-    envelope_ref: z
-        .union([envelopeRefSchema, z.array(envelopeRefSchema).min(1)])
-        .optional()
-        .describe("Resolve one or more previously stored StageEnvelopes (from another run_stage call or from any stage inside a full pipeline run) and use them as this stage's input, instead of an inline task/task_path. A single ref: its payload becomes input, its summary becomes goal. Multiple refs (an array): each resolved payload is namespaced under its stageId in input (disambiguated by runId on a stageId collision), and summaries are combined into goal."),
     checkout: z
         .string()
         .optional()
@@ -147,8 +137,15 @@ const runStageSchema = z
         .number()
         .optional()
         .describe("Wait budget in ms when blocking is true (same bounds as wait_run)"),
-})
-    .refine((data) => [data.task_path, data.task, data.envelope_ref].filter(Boolean).length === 1, { message: "Exactly one of task_path, task, or envelope_ref is required" });
+};
+const envelopeRefField = z
+    .union([envelopeRefSchema, z.array(envelopeRefSchema).min(1)])
+    .describe("Resolve one or more previously stored StageEnvelopes (from another run_stage call or from any stage inside a full pipeline run) and use them as this stage's input, instead of an inline task/task_path. A single ref: its payload becomes input, its summary becomes goal. Multiple refs (an array): each resolved payload is namespaced under its stageId in input (disambiguated by runId on a stageId collision), and summaries are combined into goal.");
+const runStageSchema = z.union([
+    z.strictObject({ ...runStageCommon, task_path: z.string() }),
+    z.strictObject({ ...runStageCommon, task: taskFileSchema }),
+    z.strictObject({ ...runStageCommon, envelope_ref: envelopeRefField }),
+]);
 const runStatusSchema = z.enum([
     "created",
     "queued",
@@ -545,7 +542,8 @@ export function registerCatalogTools(server, deps) {
     server.registerTool("run_stage", {
         description: "Run a single stage directly, without authoring a pipeline. `stage` is a filesystem path to a stage YAML file, or a bare inline stage body ({ id, system_prompt, io, model?, gate_kinds?, mcp?, verify?, timeout_ms? } — no uses:/route/pipeline wrapper), and exactly one of task_path, an inline task, or envelope_ref ({ runId, stageId, attempt? }) to resolve a previously stored envelope — from another run_stage call or any stage in a full pipeline run — as this stage's input. Internally this synthesizes a one-stage pipeline and executes it through the normal run path, so it shows up in list_runs/get_run and is polled with wait_run / get_envelope exactly like any other run. By default returns { runId, stageId } immediately (async); pass blocking:true to wait in this same call and get back { runId, stageId, status: \"completed\"|\"needs_input\"|\"timeout\", envelope? , pending_prompt? }.",
         inputSchema: runStageSchema,
-    }, async ({ stage, project_root, task_path, task, envelope_ref, checkout, model, blocking, timeout_ms }) => {
+    }, async (args) => {
+        const { stage, project_root, task_path, task, envelope_ref, checkout, model, blocking, timeout_ms } = args;
         let taskInput = task_path ?? task;
         if (envelope_ref) {
             try {

package/dist/mcp/catalogWriteTools.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { type IssueFetch } from "../config/importTask.js";
+import type { McpToolDeps } from "./deps.js";
+type CatalogWriteDeps = McpToolDeps & {
+    issueFetch?: IssueFetch;
+};
+export declare function registerCatalogWriteTools(server: McpServer, deps: CatalogWriteDeps): void;
+export {};

package/dist/mcp/catalogWriteTools.js

@@ -0,0 +1,225 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { CatalogPathError, catalogPathErrorBody, } from "../config/catalogRelativePath.js";
+import { createStage, parseCreateStageBody } from "../config/createStage.js";
+import { createTask, parseCreateTaskBody } from "../config/createTask.js";
+import { parseDraftPackageBody, validateDraftPackage } from "../config/draftPackage.js";
+import { importTaskFromIssue, parseImportTaskBody, } from "../config/importTask.js";
+import { parseUpdateTaskBody, updateTask } from "../config/updateTask.js";
+import { writeCatalogFileForHttp } from "../server/readCatalogFile.js";
+import { STAGE_GATE_KINDS } from "../types/stage.js";
+import { textResult } from "./toolResults.js";
+const projectRootField = z
+    .string()
+    .optional()
+    .describe("Catalog project root. When omitted, the server project root is used, then the process cwd.");
+const record = z.record(z.string(), z.unknown());
+const draftPipelineSchema = z.object({
+    id: z.string(),
+    stages: z.array(record),
+    agent: z.unknown().optional(),
+    model: z.unknown().optional(),
+    schemas: z.unknown().optional(),
+    requires: z.unknown().optional(),
+    channels: z.unknown().optional(),
+    memories: z.unknown().optional(),
+});
+const draftStageSchema = z.object({
+    path: z.string(),
+    body: record,
+});
+const draftTaskSchema = z.object({
+    filename: z.string(),
+    body: record,
+});
+const optionalTaskString = z
+    .string()
+    .nullable()
+    .optional()
+    .describe("String value, or null or empty string to remove the field");
+function rejected(result) {
+    return textResult({
+        error: result.error,
+        status: result.status,
+        ...(result.code !== undefined ? { code: result.code } : {}),
+        ...(result.findings !== undefined ? { findings: result.findings } : {}),
+        ...(result.project_roots !== undefined ? { project_roots: result.project_roots } : {}),
+        ...(result.registered_roots !== undefined ? { registered_roots: result.registered_roots } : {}),
+        ...(result.hint !== undefined ? { hint: result.hint } : {}),
+    }, true);
+}
+async function projectRootOf(deps, projectRoot) {
+    const resolved = path.resolve(projectRoot ?? deps.projectRoot ?? deps.cwd);
+    return realpath(resolved).catch(() => resolved);
+}
+export function registerCatalogWriteTools(server, deps) {
+    server.registerTool("create_task_file", {
+        description: "Create a standalone catalog task file (POST /api/tasks). The task is not attached to a pipeline; use create_task to add one beside a pipeline package.",
+        inputSchema: z.object({
+            project_root: projectRootField,
+            directory: z.string().describe("Directory relative to the project root, e.g. tasks"),
+            id: z.string().describe("Lowercase kebab-case task id, 1-64 characters"),
+            goal: z.string(),
+            context: z.string().optional(),
+            constraints: z.string().optional(),
+            checkout: z.string().optional(),
+            repository: z.string().optional(),
+            ref: z.string().optional(),
+        }),
+    }, async ({ project_root, ...body }) => {
+        const parsed = parseCreateTaskBody(body);
+        if ("ok" in parsed)
+            return rejected(parsed);
+        const result = await createTask(await projectRootOf(deps, project_root), parsed);
+        if (!result.ok)
+            return rejected(result);
+        return textResult({ task: result.task });
+    });
+    server.registerTool("update_task_file", {
+        description: "Update a standalone catalog task by id (PUT /api/tasks/:id). goal is required. Pass null or an empty string for context, constraints, checkout, repository, or ref to remove that field.",
+        inputSchema: z.object({
+            project_root: projectRootField,
+            id: z.string().describe("Task id"),
+            goal: z.string(),
+            context: optionalTaskString,
+            constraints: optionalTaskString,
+            checkout: optionalTaskString,
+            repository: optionalTaskString,
+            ref: optionalTaskString,
+        }),
+    }, async ({ project_root, id, ...body }) => {
+        const parsed = parseUpdateTaskBody(body);
+        if ("ok" in parsed)
+            return rejected(parsed);
+        const result = await updateTask({
+            store: deps.store,
+            bootCwd: deps.cwd,
+            taskId: id,
+            input: parsed,
+            projectRootFilter: await projectRootOf(deps, project_root),
+        });
+        if (!result.ok)
+            return rejected(result);
+        return textResult({ task: result.task });
+    });
+    server.registerTool("import_task_file", {
+        description: "Import a GitHub issue as a standalone catalog task file (POST /api/tasks/import). The issue title becomes the goal and the task id.",
+        inputSchema: z.object({
+            project_root: projectRootField,
+            repo: z.string().describe("GitHub owner/repo"),
+            number: z.number().describe("Positive GitHub issue number"),
+            directory: z.string().describe("Directory relative to the project root, e.g. tasks"),
+        }),
+    }, async ({ project_root, ...body }) => {
+        const parsed = parseImportTaskBody(body);
+        if ("ok" in parsed)
+            return rejected(parsed);
+        const result = await importTaskFromIssue(await projectRootOf(deps, project_root), parsed, deps.issueFetch);
+        if (!result.ok)
+            return rejected(result);
+        return textResult({ task: result.task });
+    });
+    server.registerTool("create_stage_file", {
+        description: "Create an orphan stage YAML file that is not wired into a pipeline (POST /api/stages). Use create_stage to add a stage to a pipeline package.",
+        inputSchema: z.object({
+            project_root: projectRootField,
+            pipeline_directory: z.string().describe("Directory relative to the project root"),
+            filename: z.string().describe("Stage filename ending in .yaml or .yml"),
+            id: z.string().describe("Lowercase kebab-case stage id, 1-64 characters"),
+            system_prompt: z.string(),
+            model: z.string().optional(),
+            gate_kinds: z
+                .array(z.string())
+                .optional()
+                .describe(`Stage gate kinds. Each entry must be one of: ${STAGE_GATE_KINDS.join(", ")}`),
+            skill: z.string().optional(),
+        }),
+    }, async ({ project_root, ...body }) => {
+        const parsed = parseCreateStageBody(body);
+        if ("ok" in parsed)
+            return rejected(parsed);
+        const result = await createStage(await projectRootOf(deps, project_root), parsed);
+        if (!result.ok)
+            return rejected(result);
+        return textResult(result.stage);
+    });
+    server.registerTool("write_catalog_file", {
+        description: "Overwrite an existing stage catalog file (PUT /api/catalog/file). The file must already exist and remain valid stage YAML; an invalid write is restored.",
+        inputSchema: z.object({
+            project_root: projectRootField,
+            path: z.string().describe("Catalog-relative .yaml or .yml path"),
+            content: z.string().describe("Full stage YAML contents"),
+        }),
+    }, async ({ project_root, path: relPath, content }) => {
+        if (typeof relPath !== "string" || relPath.trim().length === 0) {
+            return rejected({ error: "path is required", status: 400 });
+        }
+        if (typeof content !== "string") {
+            return rejected({ error: "content must be a string", status: 400 });
+        }
+        const root = await projectRootOf(deps, project_root);
+        const roots = [
+            {
+                project_root: root,
+                path: root,
+                kind: "registered",
+                read_only: false,
+            },
+        ];
+        try {
+            const result = await writeCatalogFileForHttp({
+                inputPath: relPath.trim(),
+                content,
+                projectRoot: root,
+                roots,
+                fieldName: "path",
+            });
+            if (!result.ok)
+                return rejected(result);
+            return textResult({ path: result.path, content: result.content });
+        }
+        catch (err) {
+            if (err instanceof CatalogPathError) {
+                return rejected({
+                    ...catalogPathErrorBody(err),
+                    status: err.code === "catalog_root_read_only" ? 403 : 400,
+                });
+            }
+            throw err;
+        }
+    });
+    server.registerTool("validate_catalog_draft", {
+        description: "Validate an in-memory pipeline draft package (POST /api/drafts/validate). Nothing is written. Pass the package as draft, or as top-level pipeline, stages, and task.",
+        inputSchema: z.union([
+            z.object({
+                project_root: projectRootField,
+                draft: z
+                    .object({
+                    pipeline: draftPipelineSchema,
+                    stages: z.array(draftStageSchema).optional(),
+                    task: draftTaskSchema.optional(),
+                })
+                    .describe("Draft package."),
+            }),
+            z.object({
+                project_root: projectRootField,
+                pipeline: draftPipelineSchema,
+                stages: z.array(draftStageSchema).optional(),
+                task: draftTaskSchema.optional(),
+            }),
+        ]),
+        annotations: { readOnlyHint: true },
+    }, async (body) => {
+        const parsed = parseDraftPackageBody(body);
+        if ("ok" in parsed)
+            return rejected(parsed);
+        const root = await projectRootOf(deps, body.project_root);
+        const result = await validateDraftPackage(parsed, {
+            cwd: root,
+            projectRoot: root,
+            strict: true,
+        });
+        return textResult(result);
+    });
+}

package/dist/mcp/connectionTools.d.ts

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