@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/mcp/resources/recipes.js

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * MCP resources for the recipe kinds that have non-trivial runtime
+ * behavior (currently: workflow + webhook-authorization). Agents call
+ * `resources/read` to fetch these when composing or troubleshooting a
+ * recipe.
+ *
+ * Hand-authored summaries — kept in sync with `docs/recipes/workflow.md`
+ * which is the source of truth for repo readers. Why duplicate: the
+ * `docs/` tree isn't shipped in the npm package, so reading it from
+ * disk at fetch time doesn't work in production installs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRecipeResources = void 0;
+const WORKFLOW_RECIPE_REFERENCE_TEXT = `# Workflow recipes — MCP reference
+
+Two recipe kinds let an agent define a complete Sitecore workflow as
+data: \`workflow\` (the workflow itself + states + commands + webhook
+actions) and \`webhook-authorization\` (reusable Authorization items).
+
+## Runtime model
+
+A command execution runs in this order:
+
+1. Validation actions attached to the **command** are POSTed in order.
+   Each must return \`{ IsValid: boolean, Message: string }\`. The first
+   \`IsValid: false\` aborts the transition.
+2. The item's \`__Workflow state\` field is updated to the target state.
+3. Submit actions attached to the **new state** are POSTed (fire-and-
+   forget; their response is logged but doesn't roll back).
+
+| Recipe field | Attaches at | Kind | Fires when |
+| --- | --- | --- | --- |
+| \`state.actions[]\` | A workflow state | submit OR validation | Item enters the state (post-transition) |
+| \`state.commands[].validations[]\` | A workflow command | validation only | Command invoked, before transition completes |
+
+Common pattern: validations on commands (synchronous gates), submit
+actions on states (fire-and-forget notifications).
+
+## Endpoint contract
+
+### Submit action
+
+POST to the URL with JSON body. Response not inspected. Non-2xx logged
+but transition has already happened. No automatic retry.
+
+### Validation action
+
+POST to the URL with same JSON body. Response **must** be JSON with
+\`IsValid\` + \`Message\` (PascalCase). Anything else (timeout, HTTP
+error, missing field) is treated as \`IsValid: false\` — the gate fails
+closed. Default timeout 15s.
+
+### Payload shape (verify against your tenant)
+
+\`\`\`jsonc
+{
+  "EventName": "workflow:command:executed",
+  "ItemId": "{...}",
+  "ItemPath": "/sitecore/content/...",
+  "ItemLanguage": "en",
+  "ItemVersion": 3,
+  "TemplateId": "{...}",
+  "TemplateName": "Article",
+  "WorkflowId": "{...}",
+  "WorkflowName": "Editorial",
+  "PreviousStateId": "{...}", "PreviousStateName": "Draft",
+  "NewStateId": "{...}", "NewStateName": "In Review",
+  "CommandId": "{...}", "CommandName": "Submit",
+  "Comments": "...",
+  "User": { "Name": "sitecore\\\\admin", "Email": "..." },
+  "Timestamp": "2026-05-14T12:34:56Z"
+}
+\`\`\`
+
+Field names + casing have shifted between Sitecore versions. Log the
+first real call your endpoint receives and pin schema validators
+accordingly.
+
+## Authorization types
+
+Three auth types ship with Sitecore. Recipe shape and wire behavior:
+
+| Type | Recipe \`auth\` object | Wire behavior |
+| --- | --- | --- |
+| \`ApiKey\` | \`{ type, headerName, key: "$ENV:VAR" }\` | Adds a custom header per the configured name. |
+| \`Basic\` | \`{ type, username, password: "$ENV:VAR" }\` | Adds \`Authorization: Basic <base64>\`. |
+| \`OAuth2ClientCredentialsGrant\` | \`{ type, tokenEndpoint, clientId, clientSecret: "$ENV:VAR", scope?, audience? }\` | Mints a token; sets \`Authorization: Bearer\`. Sitecore-side caching is undocumented — assume per-fire mint. |
+
+Secrets are always \`$ENV:VAR_NAME\` references. The recipe file never
+carries plaintext credentials; the executor resolves at apply time.
+Missing env vars surface as a plan-phase error.
+
+Actions reference an Authorization via either \`authorizationRef\`
+(handle of a webhook-authorization recipe pushed in the same set) OR
+\`authorizationPath\` (absolute path to an existing tenant item). Use
+exactly one per action.
+
+## Recipe shapes
+
+### \`workflow\`
+
+\`\`\`ts
+{
+  kind: "workflow",
+  schemaVersion: "1",
+  handle: "blog-article-approval@1",
+  name: "BlogArticleApproval",
+  displayName: "Blog Article Approval",
+  description?: "...",
+  meta?: { tax?: { group?: "Editorial" } },  // → /sitecore/system/Workflows/Editorial/<name>
+  initialState: "draft",                     // must match a state.key
+  states: [
+    {
+      key: "draft",                          // kebab-case; seeds GUID
+      name: "Draft",
+      displayName: "Draft",
+      final?: false,                         // workflow terminates here
+      preview?: false,                       // appears in preview DB
+      actions?: [                            // state-entry
+        {
+          kind: "webhook-submit" | "webhook-validation",
+          key: "notify-reviewer",
+          url: "https://...",
+          displayName?, description?, enabled?,
+          serializationType?: "JSON" | "XML",
+          authorizationRef?: "ci-bearer@1",  // OR
+          authorizationPath?: "/sitecore/...", // exactly one
+        }
+      ],
+      commands?: [
+        {
+          key: "submit",
+          name: "Submit",
+          displayName: "Submit for Review",
+          nextState: "in-review",            // must match another state.key
+          autoPublish?: false,
+          suppressComment?: false,
+          appearanceEvaluator?: "default" | "lock" | "unlock",
+          secured?: false,                   // reserved; no-op today
+          validations?: [                    // synchronous gates
+            { kind: "webhook-validation", key, url, authorizationRef? }
+          ]
+        }
+      ]
+    }
+  ],
+  bindings?: { templates: [] }               // reserved; INPUT_INVALID if non-empty
+}
+\`\`\`
+
+### \`webhook-authorization\`
+
+\`\`\`ts
+{
+  kind: "webhook-authorization",
+  schemaVersion: "1",
+  handle: "ci-bearer@1",
+  name: "CI Bearer",
+  displayName: "CI Bearer Token",
+  description?: "...",
+  auth: { type: "ApiKey" | "Basic" | "OAuth2ClientCredentialsGrant", ... }
+}
+\`\`\`
+
+## Recipe → Sitecore content-tree mapping
+
+| Recipe field | Sitecore path | Template |
+| --- | --- | --- |
+| \`meta.tax.group\` | \`/sitecore/system/Workflows/<group>/\` | Workflow Folder (CreateOnly) |
+| \`name\` | \`/sitecore/system/Workflows/[<group>/]<name>\` | Workflow |
+| \`states[].name\` | \`.../<state.name>\` | State |
+| \`commands[].name\` | \`.../<state.name>/<cmd.name>\` | Command |
+| \`actions[].key\` | \`.../<state.name>/<action.key>\` | Webhook Submit/Validation Action |
+| \`validations[].key\` | \`.../<cmd.name>/<val.key>\` | Webhook Validation Action |
+| webhook-authorization | \`/sitecore/system/Settings/Webhooks/Authorizations/<name>\` | Api Key / Basic / OAuth2 Client Credentials Grant |
+
+State/command/action children are direct children — no \`Actions/\`
+subfolder. \`key\` and \`name\` must be unique among siblings.
+
+## Failure modes
+
+| Scenario | What happens |
+| --- | --- |
+| Validation returns \`IsValid: false\` | Transition aborts; Message surfaces. Item stays in current state. |
+| Validation returns non-JSON / 4xx-5xx / timeout | Same — fails closed. Default 15s timeout (not configurable from recipe). |
+| Submit returns non-2xx | Logged. Transition already complete; no rollback. |
+| Submit times out | Same — log + continue. No retries. |
+| Missing \`$ENV:VAR\` at push | Plan-phase error before any write. |
+| Authorization deleted post-bind | Action fires unauthenticated; endpoint rejects. Silent for submit, blocks transition for validation. |
+
+No built-in retry queue. For at-least-once submit delivery, set up an
+idempotent receiver and external reconciliation.
+
+## Troubleshooting
+
+**templateOf path '/sitecore/templates/System/Workflow/Webhook Submit Action' did not resolve**
+
+Tenant either pre-dates the webhook-actions templates or has a custom
+layout. Run \`scai content workflow inspect "Sample Workflow"\` — if its
+actions are templated \`Webhook Submit Action\`, the templates exist
+somewhere else; PR an update to \`TEMPLATE_PATHS\` in
+\`src/recipe/compile/workflow.ts\`. Otherwise strip \`actions\` /
+\`validations\` from the recipe.
+
+**Validation always blocks**
+
+Endpoint response shape wrong. \`IsValid\` / \`Message\` (PascalCase)
+required. Anything else → fail closed.
+
+**Plan-mode skip "Target item (refKey X) not yet captured/created"**
+
+Plan-mode-only artifact for SetField ops pointing at items the recipe
+will create later. In apply mode the executor captures the itemId
+before the SetField runs. Not a real blocker.
+
+**Workflow lookup by name returns "No workflow definition matched"**
+
+Name matching is case-insensitive against \`name\` (item name) and
+\`displayName\`. Use \`workflow_inspect verb=list-defs\` to enumerate.
+
+## Verifying a push
+
+\`\`\`bash
+# Plan first
+scai provision recipe push -i your-workflow.recipe.ts --what-if
+
+# Apply (requires allowWrite on env or --allow-write flag)
+scai provision recipe push -i your-workflow.recipe.ts
+
+# Verify
+scai content workflow inspect "Your Workflow Name"      # full definition tree
+scai content workflow list-defs                          # confirm it's there
+\`\`\`
+
+## Caveats
+
+- \`bindings.templates\` accepted by schema but NOT compiled today —
+  throws INPUT_INVALID. Set \`__Default workflow\` on template
+  Standard Values manually until cross-recipe seeding lands.
+- \`secured: true\` reserved; no security ACL emitted today.
+- Per-tenant template path overrides not supported. Compiler hardcodes
+  paths under \`/sitecore/templates/System/\`.
+
+## Related
+
+- Full reference (in-repo): \`docs/recipes/workflow.md\`
+- Sitecore docs: https://doc.sitecore.com/xmc/en/developers/xm-cloud/webhooks.html
+- Schemas: \`WorkflowRecipeSchema\`, \`WebhookAuthorizationRecipeSchema\` in \`src/recipe/schema/recipe.ts\`
+- Compilers: \`src/recipe/compile/workflow.ts\`, \`src/recipe/compile/webhook-authorization.ts\`
+- Example recipes: \`example/recipes/blog-article-approval.recipe.ts\`, \`example/recipes/ci-bearer.recipe.ts\`
+`;
+const registerRecipeResources = (registry) => {
+    registry.registerResource({
+        uri: "scai://help/recipes-workflow",
+        name: "Workflow + webhook-authorization recipe reference",
+        description: "Reference for the `workflow` and `webhook-authorization` recipe kinds — runtime model, endpoint contract, authorization types, recipe shapes, content-tree mapping, failure modes, and troubleshooting. Read this before composing a workflow recipe or diagnosing a push failure.",
+        mimeType: "text/markdown",
+        handler: async () => ({
+            contents: [
+                {
+                    uri: "scai://help/recipes-workflow",
+                    mimeType: "text/markdown",
+                    text: WORKFLOW_RECIPE_REFERENCE_TEXT,
+                },
+            ],
+        }),
+    });
+};
+exports.registerRecipeResources = registerRecipeResources;

package/dist/mcp/schemas/common.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared Zod schemas reused across MCP tool input shapes.
+ *
+ * Every shape exported here is composable as a `ZodRawShape` (record of
+ * Zod schemas) so it can be spread into a tool's `inputSchema` config
+ * object passed to `McpServer.registerTool`.
+ */
+import { z } from "zod";
+export declare const allowWriteShape: {
+    readonly allowWrite: z.ZodDefault<z.ZodBoolean>;
+};
+export declare const whatIfShape: {
+    readonly whatIf: z.ZodDefault<z.ZodBoolean>;
+};
+export declare const paginationShape: {
+    readonly limit: z.ZodDefault<z.ZodNumber>;
+    readonly cursor: z.ZodOptional<z.ZodString>;
+};
+export declare const environmentBindingShape: {
+    readonly environmentName: z.ZodOptional<z.ZodString>;
+};
+export declare const ALLOW_WRITE_ERROR_HINT = "Re-invoke the same tool with `allowWrite: true` after the user has authorized this change. Reads are always free; writes require explicit consent.";

package/dist/mcp/schemas/common.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Shared Zod schemas reused across MCP tool input shapes.
+ *
+ * Every shape exported here is composable as a `ZodRawShape` (record of
+ * Zod schemas) so it can be spread into a tool's `inputSchema` config
+ * object passed to `McpServer.registerTool`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOW_WRITE_ERROR_HINT = exports.environmentBindingShape = exports.paginationShape = exports.whatIfShape = exports.allowWriteShape = void 0;
+const zod_1 = require("zod");
+exports.allowWriteShape = {
+    allowWrite: zod_1.z
+        .boolean()
+        .default(false)
+        .describe("Required to be true for any mutating call. Per-call gate — never persisted. Set true only after the user has explicitly approved the change."),
+};
+exports.whatIfShape = {
+    whatIf: zod_1.z
+        .boolean()
+        .default(false)
+        .describe("Dry-run flag. When true, the underlying operation plans the work and reports the outcome without applying mutations."),
+};
+exports.paginationShape = {
+    limit: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .default(25)
+        .describe("Maximum number of items to return for paginated listings (max 100, default 25)."),
+    cursor: zod_1.z
+        .string()
+        .optional()
+        .describe("Opaque pagination cursor from a previous response's `nextCursor`."),
+};
+exports.environmentBindingShape = {
+    environmentName: zod_1.z
+        .string()
+        .optional()
+        .describe("Target environment; defaults to the server's bound environment. When set, the call is resolved against the named environment (config, deploy token, and allowWrite are all derived from it). Use `scai_overview` to list configured environments."),
+};
+exports.ALLOW_WRITE_ERROR_HINT = "Re-invoke the same tool with `allowWrite: true` after the user has authorized this change. Reads are always free; writes require explicit consent.";

package/dist/mcp/server.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Wires the in-house `McpRegistry` to the MCP SDK's `McpServer` and
+ * starts the stdio transport.
+ *
+ * Why a separate registry first? See `registry.ts` — we need to gate
+ * writes (allowWrite), serialize calls, and shape error envelopes
+ * before the SDK sees the handler. Here the bridge is intentionally
+ * thin: every registered tool becomes a forwarder that delegates to
+ * `dispatchTool`, every resource becomes a single-URI ReadCallback,
+ * every prompt forwards its args object through unchanged.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpContextProvider } from "./auth";
+import type { McpRegistry } from "./registry";
+export interface McpServerOptions {
+    /**
+     * Lazy provider for the bound `McpContext`. Resolves on first tool /
+     * resource / prompt invocation so the stdio transport can complete
+     * the MCP `initialize` handshake before any keychain access happens.
+     * See `createMcpContextProvider` for the memoization + retry shape.
+     */
+    getContext: McpContextProvider;
+    registry: McpRegistry;
+}
+export declare const buildMcpServer: (options: McpServerOptions) => McpServer;
+export declare const startStdioTransport: (server: McpServer) => Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Wires the in-house `McpRegistry` to the MCP SDK's `McpServer` and
+ * starts the stdio transport.
+ *
+ * Why a separate registry first? See `registry.ts` — we need to gate
+ * writes (allowWrite), serialize calls, and shape error envelopes
+ * before the SDK sees the handler. Here the bridge is intentionally
+ * thin: every registered tool becomes a forwarder that delegates to
+ * `dispatchTool`, every resource becomes a single-URI ReadCallback,
+ * every prompt forwards its args object through unchanged.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startStdioTransport = exports.buildMcpServer = void 0;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const dispatch_1 = require("./dispatch");
+const package_json_1 = __importDefault(require("../../package.json"));
+const buildToolExtra = (sdkExtra) => {
+    const progressToken = sdkExtra._meta?.progressToken;
+    return {
+        signal: sdkExtra.signal,
+        progressToken,
+        sendNotification: (notification) => sdkExtra.sendNotification(notification),
+        sendProgress: async (progress, total, message) => {
+            if (progressToken === undefined) {
+                return;
+            }
+            try {
+                await sdkExtra.sendNotification({
+                    method: "notifications/progress",
+                    params: { progressToken, progress, total, message },
+                });
+            }
+            catch (error) {
+                // Progress is advisory — never let a failed notification
+                // bubble out and corrupt the tool's primary result. Trace to
+                // stderr only.
+                process.stderr.write(`scai mcp: progress notification dropped (${error instanceof Error ? error.message : String(error)})\n`);
+            }
+        },
+    };
+};
+const buildMcpServer = (options) => {
+    const { getContext, registry } = options;
+    const server = new mcp_js_1.McpServer({
+        name: "scai",
+        version: package_json_1.default.version,
+    });
+    for (const tool of registry.listTools()) {
+        server.registerTool(tool.name, {
+            title: tool.annotations.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: tool.annotations,
+        }, async (args, sdkExtra) => {
+            const context = await getContext();
+            return (0, dispatch_1.dispatchTool)(tool, args ?? {}, {
+                context,
+                extra: buildToolExtra(sdkExtra),
+            });
+        });
+    }
+    for (const resource of registry.listResources()) {
+        server.registerResource(resource.name, resource.uri, {
+            title: resource.name,
+            description: resource.description,
+            mimeType: resource.mimeType,
+        }, async () => resource.handler(await getContext()));
+    }
+    for (const prompt of registry.listPrompts()) {
+        server.registerPrompt(prompt.name, {
+            title: prompt.name,
+            description: prompt.description,
+            argsSchema: prompt.argsSchema,
+        }, async (args) => prompt.handler(args, await getContext()));
+    }
+    return server;
+};
+exports.buildMcpServer = buildMcpServer;
+const startStdioTransport = async (server) => {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+};
+exports.startStdioTransport = startStdioTransport;

package/dist/mcp/tools/access-check.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `access_check` — the access preflight tool.
+ *
+ * Read-only and offline. Given an environment, returns every access
+ * gate (config, workspace policy, credentials) at once, each with a
+ * structured remediation, so an agent learns all blockers in one call
+ * instead of one failed call at a time. The thin MCP wrapper over
+ * `checkAccess` (`@/policy/access-check`).
+ */
+import type { McpRegistry } from "../registry";
+export declare const registerAccessCheckTools: (registry: McpRegistry) => void;

package/dist/mcp/tools/access-check.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * `access_check` — the access preflight tool.
+ *
+ * Read-only and offline. Given an environment, returns every access
+ * gate (config, workspace policy, credentials) at once, each with a
+ * structured remediation, so an agent learns all blockers in one call
+ * instead of one failed call at a time. The thin MCP wrapper over
+ * `checkAccess` (`@/policy/access-check`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAccessCheckTools = void 0;
+const access_check_1 = require("../../policy/access-check");
+const descriptions_1 = require("../descriptions");
+const common_1 = require("../schemas/common");
+const registerAccessCheckTools = (registry) => {
+    registry.registerTool({
+        name: "access_check",
+        description: descriptions_1.TOOL_DESCRIPTIONS.access_check,
+        auth: "read",
+        annotations: {
+            title: "Preflight environment access",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+        inputSchema: { ...common_1.environmentBindingShape },
+        handler: async (input, context) => {
+            const envName = input.environmentName ?? context.envName;
+            const report = await (0, access_check_1.checkAccess)({
+                configPath: context.configPath,
+                environmentName: envName,
+            });
+            const blocked = report.gates.filter((gate) => gate.status === "blocked");
+            const text = report.ready
+                ? `Environment '${envName}' is ready — config, policy, and credential gates all pass.`
+                : `Environment '${envName}' is NOT ready. Blocked: ${blocked
+                    .map((gate) => gate.id)
+                    .join(", ")}. Next: ${report.nextStep ? `${report.nextStep.fix} [${report.nextStep.actor}]` : "see gates"}.`;
+            return {
+                content: [{ type: "text", text }],
+                structuredContent: report,
+            };
+        },
+    });
+};
+exports.registerAccessCheckTools = registerAccessCheckTools;

package/dist/mcp/tools/agents-recipe.d.ts

@@ -0,0 +1,2 @@
+import type { McpRegistry } from "../registry";
+export declare const registerAgentsRecipeTools: (registry: McpRegistry) => void;

package/dist/mcp/tools/agents-recipe.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAgentsRecipeTools = void 0;
+/**
+ * Agentic Studio recipe surface — the MCP projection of the area's
+ * recipe kinds. Two workflow-shaped tools, each discriminating on `kind`
+ * (agent | skill | widget | custom-mcp | schema | html-template):
+ *
+ *   - `agents_recipe_inspect` — read. `verb=pull` captures a live
+ *     resource as a recipe; `verb=diff` plans convergence onto `recipe`.
+ *   - `agents_recipe_push` — write. Converges a resource onto a recipe,
+ *     gated by `allowWrite`; `whatIf` returns the plan without writing.
+ *
+ * `recipe` is a loose object validated against the chosen kind's schema
+ * in the handler — one tool covers every kind.
+ */
+const zod_1 = require("zod");
+const recipe_1 = require("../../agents/recipe");
+const errors_1 = require("../../shared/errors");
+const sync_1 = require("../../sync");
+const descriptions_1 = require("../descriptions");
+const common_1 = require("../schemas/common");
+const KIND_NAMES = ["agent", "skill", "widget", "custom-mcp", "schema", "html-template"];
+const syncContextFrom = (context, signal) => ({
+    environmentName: context.envName,
+    configPath: context.configPath,
+    signal,
+});
+const planSummaryText = (plan) => {
+    const tally = (0, sync_1.summarizePlan)(plan);
+    return `Plan: ${tally.create} create, ${tally.update} update, ${tally.delete} delete, ${tally.noop} unchanged.`;
+};
+/** Extract a recipe's identifying `name`. */
+const recipeName = (recipe) => {
+    const name = recipe.name;
+    if (typeof name !== "string" || !name) {
+        throw (0, errors_1.createScaiError)("Recipe is missing a `name`.", "INPUT_INVALID");
+    }
+    return name;
+};
+const registerAgentsRecipeTools = (registry) => {
+    registry.registerTool({
+        name: "agents_recipe_inspect",
+        description: descriptions_1.TOOL_DESCRIPTIONS.agents_recipe_inspect,
+        auth: "read",
+        annotations: {
+            title: "Pull or diff an Agentic Studio resource as a recipe",
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            kind: zod_1.z.enum(KIND_NAMES).describe("Which Agentic Studio resource kind the recipe describes."),
+            verb: zod_1.z
+                .enum(["pull", "diff"])
+                .describe("pull: capture the resource named `name` as a recipe. diff: plan the convergence of `recipe` onto live state."),
+            name: zod_1.z.string().optional().describe("Resource display name. Required for verb='pull'."),
+            recipe: zod_1.z
+                .record(zod_1.z.string(), zod_1.z.unknown())
+                .optional()
+                .describe("A recipe object. Required for verb='diff'; validated against the chosen kind."),
+        },
+        handler: async (input, context) => {
+            const kind = recipe_1.agentRecipeKindByName[input.kind];
+            const ctx = syncContextFrom(context);
+            if (input.verb === "pull") {
+                if (!input.name) {
+                    throw (0, errors_1.createScaiError)("verb='pull' requires `name`.", "INPUT_INVALID");
+                }
+                const recipe = await (0, sync_1.syncPull)(kind, { kind: kind.name, id: input.name }, ctx);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: recipe
+                                ? `Captured "${input.name}" as a ${input.kind} recipe.`
+                                : `No ${input.kind} named "${input.name}".`,
+                        },
+                    ],
+                    structuredContent: { kind: input.kind, verb: input.verb, found: recipe !== null, recipe },
+                };
+            }
+            if (!input.recipe) {
+                throw (0, errors_1.createScaiError)("verb='diff' requires `recipe`.", "INPUT_INVALID");
+            }
+            const recipe = kind.schema.parse(input.recipe);
+            const plan = await (0, sync_1.syncDiff)(kind, recipe, { kind: kind.name, id: recipeName(recipe) }, ctx);
+            return {
+                content: [{ type: "text", text: planSummaryText(plan) }],
+                structuredContent: {
+                    kind: input.kind,
+                    verb: input.verb,
+                    plan,
+                    summary: (0, sync_1.summarizePlan)(plan),
+                },
+            };
+        },
+    });
+    registry.registerTool({
+        name: "agents_recipe_push",
+        description: descriptions_1.TOOL_DESCRIPTIONS.agents_recipe_push,
+        auth: "write",
+        annotations: {
+            title: "Push an Agentic Studio recipe — converge the resource onto it",
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            kind: zod_1.z.enum(KIND_NAMES).describe("Which Agentic Studio resource kind the recipe describes."),
+            recipe: zod_1.z
+                .record(zod_1.z.string(), zod_1.z.unknown())
+                .describe("The recipe to converge onto. Validated against the chosen kind; the resource is identified by `recipe.name`."),
+            ...common_1.whatIfShape,
+            ...common_1.allowWriteShape,
+        },
+        handler: async (input, context, extra) => {
+            const kind = recipe_1.agentRecipeKindByName[input.kind];
+            const ctx = syncContextFrom(context, extra.signal);
+            const recipe = kind.schema.parse(input.recipe);
+            const mode = input.whatIf ? "what-if" : "apply";
+            const outcome = await (0, sync_1.syncPush)(kind, recipe, { kind: kind.name, id: recipeName(recipe) }, ctx, { mode });
+            const text = outcome.result
+                ? `Applied ${outcome.result.applied.length} change(s); ${outcome.result.skipped.length} skipped.`
+                : planSummaryText(outcome.plan);
+            return {
+                content: [{ type: "text", text }],
+                structuredContent: {
+                    kind: input.kind,
+                    mode,
+                    plan: outcome.plan,
+                    summary: (0, sync_1.summarizePlan)(outcome.plan),
+                    result: outcome.result,
+                },
+            };
+        },
+    });
+};
+exports.registerAgentsRecipeTools = registerAgentsRecipeTools;

package/dist/mcp/tools/agents.d.ts

@@ -0,0 +1,2 @@
+import type { McpRegistry } from "../registry";
+export declare const registerAgentsTools: (registry: McpRegistry) => void;