@gavana.ai/cli 0.2.0

package/src/tools/guide_search.mjs

@@ -0,0 +1,16 @@
+// Tool definition: guide_search
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+import { z } from "zod";
+import { GAVANA_CANVAS_GUIDE_VERSION, searchCanvasGuides } from "../canvas-agent-guide.mjs";
+
+export function defineGuideSearch(client) {
+    return {
+       title: "Search the Canvas Agent Guide",
+       description: `Search the canonical Gavana Canvas Agent Guide v${GAVANA_CANVAS_GUIDE_VERSION}. Use this before the first canvas mutation in a session or whenever an operation is unfamiliar.`,
+       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({ query: z.string().max(240).default(""), limit: z.number().int().min(1).max(10).default(10) }),
+       handler: ({ query, limit }) => searchCanvasGuides(query, limit),
+    };
+}

package/src/tools/helpers.mjs

@@ -0,0 +1,66 @@
+// Helpers shared by the Gavana tool definitions.
+//
+// Moved out of scripts/gavana-agent-mcp.mjs with the tool schemas so tool
+// definitions can live outside the server. listOptions normalises the pagination
+// and filter options the list tools accept. readLocalReferenceImage reads a
+// user-supplied local file for asset_upload; it is the only tool helper that
+// touches the filesystem, so it and its validation helpers stay together and
+// deliberately narrow.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { MAX_LOCAL_REFERENCE_IMAGE_BYTES } from "./schemas.mjs";
+
+function listOptions(limit, cursor) {
+    return {
+        ...(limit !== undefined ? { limit } : {}),
+        ...(cursor ? { cursor } : {}),
+    };
+}
+
+async function readLocalReferenceImage(value) {
+    const filePath = path.resolve(value);
+    let stat;
+    try {
+        stat = await fs.stat(filePath);
+    } catch {
+        throw localImageInputError(`Local image path was not found: ${value}`);
+    }
+    if (!stat.isFile()) throw localImageInputError(`Local image path is not a file: ${value}`);
+    if (stat.size > MAX_LOCAL_REFERENCE_IMAGE_BYTES) throw localImageInputError(`Local image is too large (maximum 50 MiB): ${value}`);
+
+    let bytes;
+    try {
+        bytes = await fs.readFile(filePath);
+    } catch {
+        throw localImageInputError(`Local image could not be read: ${value}`);
+    }
+    if (!bytes.byteLength) throw localImageInputError(`Local image is empty: ${value}`);
+    if (bytes.byteLength > MAX_LOCAL_REFERENCE_IMAGE_BYTES) throw localImageInputError(`Local image is too large (maximum 50 MiB): ${value}`);
+    if (!sniffRasterImageContentType(bytes)) throw localImageInputError(`Local image must be a PNG, JPEG, WebP, or GIF: ${value}`);
+    return { bytes, fileName: cleanUploadFileName(path.basename(filePath)) };
+}
+
+function cleanUploadFileName(value) {
+    const name = path.basename(String(value || "reference-image"));
+    return name.replace(/[\r\n]/g, " ").slice(0, 160) || "reference-image";
+}
+
+function localImageInputError(message) {
+    return Object.assign(new Error(`Input validation error: ${message}`), { code: "invalid_local_image" });
+}
+
+function sniffRasterImageContentType(bytes) {
+    if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return "image/png";
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+    if (bytes.length >= 12 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP") return "image/webp";
+    if (bytes.length >= 6 && (bytes.toString("ascii", 0, 6) === "GIF87a" || bytes.toString("ascii", 0, 6) === "GIF89a")) return "image/gif";
+    return "";
+}
+
+export {
+    cleanUploadFileName,
+    listOptions,
+    localImageInputError,
+    readLocalReferenceImage,
+    sniffRasterImageContentType,
+};

package/src/tools/image_edit.mjs

@@ -0,0 +1,8 @@
+// Tool definition: image_edit
+//
+// One of three operations sharing ./image_tool.mjs.
+import { imageToolDefinition } from "./image_tool.mjs";
+
+export function defineImageEdit(client) {
+    return imageToolDefinition("edit", client);
+}

package/src/tools/image_generate.mjs

@@ -0,0 +1,8 @@
+// Tool definition: image_generate
+//
+// One of three operations sharing ./image_tool.mjs.
+import { imageToolDefinition } from "./image_tool.mjs";
+
+export function defineImageGenerate(client) {
+    return imageToolDefinition("generate", client);
+}

package/src/tools/image_tool.mjs

@@ -0,0 +1,56 @@
+// Shared definition for image_generate, image_edit and image_variations.
+//
+// The three differ only in the operation they queue and their description, so they
+// share one factory rather than three near-identical modules. ./registry.mjs still
+// lists them as three tools, which is what clients see.
+import { imageSchema, validateImageInput } from "./schemas.mjs";
+import { withProgress } from "./progress.mjs";
+
+export function imageToolDefinition(operation, client) {
+    return {
+            title: `${operation === "generate" ? "Generate" : operation === "edit" ? "Edit" : "Vary"} canvas images`,
+            description:
+                operation === "generate"
+                    ? "Queue image generation into existing target image nodes. For an exact product, logo, face, garment, or other visual identity, do not rely on prompt-only generation: use asset_upload for a user-provided local image (or an existing node:/asset: handle), then call image_edit with references."
+                    : operation === "edit"
+                      ? "Queue an image edit using stable node: or asset: references. Use this for exact product or visual identity work; call asset_upload first when the user supplied a local image."
+                      : "Queue variations using an existing node: or asset: source.",
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+            inputSchema: imageSchema(),
+            markdown: true,
+            handler: async (input, extra) => {
+                validateImageInput(operation, input);
+                const destination = input.destination || input.canvasId;
+                const prepared = await client.prepareImageDestination({
+                    ...input,
+                    operation,
+                    destination,
+                });
+                const {
+                    destination: _destination,
+                    canvasId: _canvasId,
+                    canvasTitle: _canvasTitle,
+                    targetNodeIds: _targetNodeIds,
+                    targetTitle: _targetTitle,
+                    targetX: _targetX,
+                    targetY: _targetY,
+                    targetWidth: _targetWidth,
+                    targetHeight: _targetHeight,
+                    wait: _wait,
+                    timeoutSeconds: _timeoutSeconds,
+                    ...jobInput
+                } = input;
+                const queued = await client.startImage(operation, {
+                    ...jobInput,
+                    canvasId: prepared.canvasId,
+                    targetNodeIds: prepared.targetNodeIds,
+                    baseRevision: prepared.baseRevision,
+                    idempotencyKey: input.idempotencyKey,
+                });
+                const destinationResult = { requested: destination, canvasId: prepared.canvasId, targetNodeIds: prepared.targetNodeIds };
+                if (input.wait === false) return { ...queued, destination: destinationResult };
+                const result = await client.waitForRun(queued.run || queued.id, withProgress({ timeoutMs: (input.timeoutSeconds || 900) * 1000 }, extra));
+                return { ...result, destination: destinationResult };
+            },
+    };
+}

package/src/tools/image_variations.mjs

@@ -0,0 +1,8 @@
+// Tool definition: image_variations
+//
+// One of three operations sharing ./image_tool.mjs.
+import { imageToolDefinition } from "./image_tool.mjs";
+
+export function defineImageVariations(client) {
+    return imageToolDefinition("variations", client);
+}

package/src/tools/job_cancel.mjs

@@ -0,0 +1,16 @@
+// Tool definition: job_cancel
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+import { z } from "zod";
+import { jobReference } from "./schemas.mjs";
+
+export function defineJobCancel(client) {
+    return {
+       title: "Cancel an image, video, or Action job",
+       description: "Cancel queued or running image, video, or Action work. Use only after explicit user intent.",
+       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({ jobId: jobReference }),
+       handler: ({ jobId }) => client.cancelJob(jobId),
+    };
+}

package/src/tools/job_get.mjs

@@ -0,0 +1,17 @@
+// Tool definition: job_get
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+import { z } from "zod";
+import { jobReference } from "./schemas.mjs";
+
+export function defineJobGet(client) {
+    return {
+       title: "Read an image, video, or Action job",
+       description: "Read or resume asynchronous image, video, or Action work. Successful image and Action results include durable asset handles and scoped preview links.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({ jobId: jobReference }),
+       markdown: true,
+       handler: ({ jobId }) => client.getJob(jobId),
+    };
+}

package/src/tools/job_wait.mjs

@@ -0,0 +1,18 @@
+// Tool definition: job_wait
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+import { z } from "zod";
+import { jobReference } from "./schemas.mjs";
+import { withProgress } from "./progress.mjs";
+
+export function defineJobWait(client) {
+    return {
+       title: "Wait for an image, video, or Action job",
+       description: "Wait for existing image, video, or Action work to finish. Image and Action work returns durable chat-renderable assets; video returns its authenticated output path.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({ jobId: jobReference, timeoutSeconds: z.number().min(1).max(3_600).default(900) }),
+       markdown: true,
+       handler: ({ jobId, timeoutSeconds }, extra) => client.waitForJob(jobId, withProgress({ timeoutMs: timeoutSeconds * 1000 }, extra)),
+    };
+}

package/src/tools/model_get.mjs

@@ -0,0 +1,16 @@
+// Tool definition: model_get
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+import { z } from "zod";
+import { modelReference } from "./schemas.mjs";
+
+export function defineModelGet(client) {
+    return {
+       title: "Read an image model schema",
+       description: "Inspect one model's exact capabilities, accepted parameters, connection, and duration estimate.",
+       annotations: { readOnlyHint: true, openWorldHint: false },
+       inputSchema: z.object({ modelId: modelReference }),
+       handler: ({ modelId }) => client.getModel(modelId),
+    };
+}

package/src/tools/model_list.mjs

@@ -0,0 +1,23 @@
+// Tool definition: model_list
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+import { z } from "zod";
+import { listOptions } from "./helpers.mjs";
+import { listCursor, listLimit } from "./schemas.mjs";
+
+export function defineModelList(client) {
+    return {
+       title: "List runnable AI models",
+       description: "Discover image or video models from saved connections with capabilities, typed parameters, and estimated duration.",
+       annotations: { readOnlyHint: true, openWorldHint: false },
+       inputSchema: z.object({
+           query: z.string().max(240).optional(),
+           provider: z.enum(["craftboard", "openai", "google/nano-banana", "black-forest-labs", "recraft", "ideogram", "qwen", "openrouter"]).optional(),
+           capability: z.enum(["image.generate", "image.edit", "image.variations", "video.generate", "video.generate.fromImage", "video.generate.fromFrames", "video.generate.fromReferences"]).optional(),
+           limit: listLimit(100),
+           cursor: listCursor,
+       }),
+       handler: ({ query, provider, capability, limit, cursor }) => client.listModels({ query, provider, capability }, listOptions(limit, cursor)),
+    };
+}

package/src/tools/node_create.mjs

@@ -0,0 +1,36 @@
+// Tool definition: node_create
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+// Graph mutation: resolves baseRevision, then applies one operation atomically.
+import { z } from "zod";
+import { canvasReference, revisionFields } from "./schemas.mjs";
+
+export function defineNodeCreate(client) {
+    const config = {
+       title: "Create a canvas node",
+       description: "Create a text, sticky, or empty image node. Image bytes must be attached through an image job.",
+       destructiveHint: false,
+       schema: z.object({
+           canvasId: canvasReference,
+           ...revisionFields,
+           clientId: z.string().min(1).max(100).optional(),
+           node: z.record(z.unknown()),
+       }),
+       operation: ({ clientId, node }) => ({ type: "node.create", ...(clientId ? { clientId } : {}), node }),
+    };
+    return {
+        title: config.title,
+        description: config.description,
+        annotations: { readOnlyHint: false, destructiveHint: config.destructiveHint, idempotentHint: true, openWorldHint: false },
+        inputSchema: config.schema,
+        handler: async (input) => {
+            const baseRevision = input.baseRevision || (await client.getCanvas(input.canvasId)).canvas.revision;
+            return client.applyOperations(input.canvasId, {
+                baseRevision,
+                idempotencyKey: input.idempotencyKey,
+                operations: [config.operation(input)],
+            });
+        },
+    };
+}

package/src/tools/node_delete.mjs

@@ -0,0 +1,31 @@
+// Tool definition: node_delete
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+// Graph mutation: resolves baseRevision, then applies one operation atomically.
+import { z } from "zod";
+import { canvasReference, nodeReference, revisionFields } from "./schemas.mjs";
+
+export function defineNodeDelete(client) {
+    const config = {
+       title: "Delete a canvas node",
+       description: "Delete a node and its attached connections. This is destructive and should follow explicit user intent.",
+       destructiveHint: true,
+       schema: z.object({ canvasId: canvasReference, ...revisionFields, nodeId: nodeReference }),
+       operation: ({ nodeId }) => ({ type: "node.delete", nodeId }),
+    };
+    return {
+        title: config.title,
+        description: config.description,
+        annotations: { readOnlyHint: false, destructiveHint: config.destructiveHint, idempotentHint: true, openWorldHint: false },
+        inputSchema: config.schema,
+        handler: async (input) => {
+            const baseRevision = input.baseRevision || (await client.getCanvas(input.canvasId)).canvas.revision;
+            return client.applyOperations(input.canvasId, {
+                baseRevision,
+                idempotencyKey: input.idempotencyKey,
+                operations: [config.operation(input)],
+            });
+        },
+    };
+}

package/src/tools/node_get.mjs

@@ -0,0 +1,16 @@
+// Tool definition: node_get
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+import { z } from "zod";
+import { canvasReference, nodeReference } from "./schemas.mjs";
+
+export function defineNodeGet(client) {
+    return {
+       title: "Read a canvas node",
+       description: "Read one node with incoming and outgoing connections.",
+       annotations: { readOnlyHint: true, openWorldHint: false },
+       inputSchema: z.object({ canvasId: canvasReference, nodeId: nodeReference }),
+       handler: ({ canvasId, nodeId }) => client.getNode(canvasId, nodeId),
+    };
+}

package/src/tools/node_move.mjs

@@ -0,0 +1,37 @@
+// Tool definition: node_move
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+// Graph mutation: resolves baseRevision, then applies one operation atomically.
+import { z } from "zod";
+import { canvasReference, nodeReference, revisionFields } from "./schemas.mjs";
+
+export function defineNodeMove(client) {
+    const config = {
+       title: "Move a canvas node",
+       description: "Move one node to an exact canvas position.",
+       destructiveHint: false,
+       schema: z.object({
+           canvasId: canvasReference,
+           ...revisionFields,
+           nodeId: nodeReference,
+           x: z.number().finite(),
+           y: z.number().finite(),
+       }),
+       operation: ({ nodeId, x, y }) => ({ type: "node.move", nodeId, position: { x, y } }),
+    };
+    return {
+        title: config.title,
+        description: config.description,
+        annotations: { readOnlyHint: false, destructiveHint: config.destructiveHint, idempotentHint: true, openWorldHint: false },
+        inputSchema: config.schema,
+        handler: async (input) => {
+            const baseRevision = input.baseRevision || (await client.getCanvas(input.canvasId)).canvas.revision;
+            return client.applyOperations(input.canvasId, {
+                baseRevision,
+                idempotencyKey: input.idempotencyKey,
+                operations: [config.operation(input)],
+            });
+        },
+    };
+}

package/src/tools/node_resize.mjs

@@ -0,0 +1,37 @@
+// Tool definition: node_resize
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+// Graph mutation: resolves baseRevision, then applies one operation atomically.
+import { z } from "zod";
+import { canvasReference, nodeReference, revisionFields } from "./schemas.mjs";
+
+export function defineNodeResize(client) {
+    const config = {
+       title: "Resize a canvas node",
+       description: "Resize one node to exact dimensions.",
+       destructiveHint: false,
+       schema: z.object({
+           canvasId: canvasReference,
+           ...revisionFields,
+           nodeId: nodeReference,
+           width: z.number().min(40).max(10_000),
+           height: z.number().min(40).max(10_000),
+       }),
+       operation: ({ nodeId, width, height }) => ({ type: "node.resize", nodeId, width, height }),
+    };
+    return {
+        title: config.title,
+        description: config.description,
+        annotations: { readOnlyHint: false, destructiveHint: config.destructiveHint, idempotentHint: true, openWorldHint: false },
+        inputSchema: config.schema,
+        handler: async (input) => {
+            const baseRevision = input.baseRevision || (await client.getCanvas(input.canvasId)).canvas.revision;
+            return client.applyOperations(input.canvasId, {
+                baseRevision,
+                idempotencyKey: input.idempotencyKey,
+                operations: [config.operation(input)],
+            });
+        },
+    };
+}

package/src/tools/node_update.mjs

@@ -0,0 +1,36 @@
+// Tool definition: node_update
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+// Graph mutation: resolves baseRevision, then applies one operation atomically.
+import { z } from "zod";
+import { canvasReference, nodeReference, revisionFields } from "./schemas.mjs";
+
+export function defineNodeUpdate(client) {
+    const config = {
+       title: "Update a canvas node",
+       description: "Update supported node title, position, size, or semantic metadata while preserving server-owned image fields.",
+       destructiveHint: false,
+       schema: z.object({
+           canvasId: canvasReference,
+           ...revisionFields,
+           nodeId: nodeReference,
+           patch: z.record(z.unknown()),
+       }),
+       operation: ({ nodeId, patch }) => ({ type: "node.update", nodeId, patch }),
+    };
+    return {
+        title: config.title,
+        description: config.description,
+        annotations: { readOnlyHint: false, destructiveHint: config.destructiveHint, idempotentHint: true, openWorldHint: false },
+        inputSchema: config.schema,
+        handler: async (input) => {
+            const baseRevision = input.baseRevision || (await client.getCanvas(input.canvasId)).canvas.revision;
+            return client.applyOperations(input.canvasId, {
+                baseRevision,
+                idempotencyKey: input.idempotencyKey,
+                operations: [config.operation(input)],
+            });
+        },
+    };
+}

package/src/tools/progress.mjs

@@ -0,0 +1,101 @@
+// Progress notifications for the tools that wait on a job or Run.
+//
+// image_generate, image_edit, image_variations, video_generate, recipe_run,
+// action_run, job_wait, and run_wait can each block for minutes. Without progress
+// the caller sees a single silent pause and cannot tell a queued job from a stuck
+// one. The polling loops in client.mjs already fire onProgress on every status
+// change; this turns that into an MCP notifications/progress message.
+//
+// Two rules shape everything below.
+//
+// A client that sent no progressToken must observe zero new messages. The MCP spec
+// makes progress opt-in per request, and an unsolicited notification is a protocol
+// violation the client is entitled to drop or error on.
+//
+// The payload carries a status word and nothing else. Run and job records hold
+// signed URLs, storage keys, prompts, and output sizes; a notification is the
+// easiest place to leak one by accident, because it looks like a log line rather
+// than a response.
+
+/**
+ * Status words safe to repeat back. Statuses come from the server, so an
+ * allowlist — rather than a filter — is what keeps an unexpected value (an error
+ * string, a provider message) out of the payload.
+ */
+export const REPORTABLE_STATUSES = new Set([
+    "canceled",
+    "canceling",
+    "expired",
+    "failed",
+    "finalizing",
+    "pending",
+    "preparing",
+    "queued",
+    "review_required",
+    "running",
+    "succeeded",
+]);
+
+/** The one line a progress notification is allowed to say. */
+export function progressMessage(result) {
+    const status = String(result?.status || "").toLowerCase();
+    return REPORTABLE_STATUSES.has(status) ? `Status: ${status}` : "Working";
+}
+
+
+/**
+ * How long to wait for one notification before giving up on it.
+ *
+ * Delivery is awaited so notifications stay ordered, but the await has to be
+ * bounded: stdout writes wait on drain, and a client that has stopped reading
+ * would otherwise stall the polling loop forever, holding back the terminal
+ * result the caller actually needs. Dropping a status line is the cheaper loss.
+ */
+const NOTIFICATION_SEND_TIMEOUT_MS = 5_000;
+
+/** Await a send for at most NOTIFICATION_SEND_TIMEOUT_MS, and never throw. */
+function deliver(sent) {
+    // A rejection after the race has moved on would otherwise be unhandled.
+    const settled = Promise.resolve(sent).catch(() => undefined);
+    let timer;
+    return Promise.race([
+        settled.finally(() => clearTimeout(timer)),
+        new Promise((resolve) => {
+            timer = setTimeout(resolve, NOTIFICATION_SEND_TIMEOUT_MS);
+            timer.unref?.();
+        }),
+    ]).then(() => undefined);
+}
+
+/**
+ * An onProgress callback for client.waitForJob / client.waitForRun, or undefined
+ * when the caller did not ask for progress.
+ *
+ * Returning undefined rather than a no-op function is deliberate: the wait options
+ * spread it, so undefined means the polling loop never calls anything, and a client
+ * that sent no progressToken cannot receive a message even by mistake.
+ *
+ * @param extra The second argument the MCP SDK hands a tool handler.
+ */
+export function createProgressReporter(extra) {
+    const progressToken = extra?._meta?.progressToken;
+    if (progressToken === undefined || progressToken === null) return undefined;
+    if (typeof extra?.sendNotification !== "function") return undefined;
+
+    let progress = 0;
+    return async (result) => {
+        // The spec requires progress to increase on every notification for a token.
+        // Duration is genuinely unknown here, so total is omitted rather than guessed.
+        progress += 1;
+        await deliver(extra.sendNotification({
+            method: "notifications/progress",
+            params: { progressToken, progress, message: progressMessage(result) },
+        }));
+    };
+}
+
+/** Wait options for a polling call, carrying a reporter only when one was requested. */
+export function withProgress(waitOptions, extra) {
+    const onProgress = createProgressReporter(extra);
+    return onProgress ? { ...waitOptions, onProgress } : waitOptions;
+}

package/src/tools/provider_list.mjs

@@ -0,0 +1,17 @@
+// Tool definition: provider_list
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+import { z } from "zod";
+import { listOptions } from "./helpers.mjs";
+import { listCursor, listLimit } from "./schemas.mjs";
+
+export function defineProviderList(client) {
+    return {
+       title: "List AI providers",
+       description: "List the actor's saved AI connections and available image or video models without exposing provider secrets.",
+       annotations: { readOnlyHint: true, openWorldHint: false },
+       inputSchema: z.object({ limit: listLimit(100), cursor: listCursor }),
+       handler: ({ limit, cursor }) => client.listConnections(listOptions(limit, cursor)),
+    };
+}

package/src/tools/recipe_fork.mjs

@@ -0,0 +1,32 @@
+// Tool definition: recipe_fork
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+import { z } from "zod";
+import { exactCanvasReference, recipeForkIdempotencyKey, recipeReference, revisionFields } from "./schemas.mjs";
+
+export function defineRecipeFork(client) {
+    return {
+       title: "Add a compact Recipe workflow",
+       description: "Copy one approved Recipe into a canvas as one compact workflow node with a private internal graph. This never starts a job or generation.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({
+           recipeId: recipeReference,
+           canvasId: exactCanvasReference,
+           version: z.string().min(1).max(80).optional(),
+           baseRevision: revisionFields.baseRevision,
+           x: z.number().finite().min(-100_000).max(100_000).optional().describe("Optional fork anchor X coordinate."),
+           y: z.number().finite().min(-100_000).max(100_000).optional().describe("Optional fork anchor Y coordinate."),
+           idempotencyKey: recipeForkIdempotencyKey,
+       }),
+       handler: async ({ recipeId, canvasId, version, baseRevision, x, y, idempotencyKey }) =>
+           client.forkRecipe(recipeId, {
+               canvasId,
+               ...(version ? { version } : {}),
+               ...(baseRevision ? { baseRevision } : {}),
+               ...(x !== undefined ? { x } : {}),
+               ...(y !== undefined ? { y } : {}),
+               idempotencyKey,
+           }),
+    };
+}

package/src/tools/recipe_get.mjs

@@ -0,0 +1,19 @@
+// Tool definition: recipe_get
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+import { z } from "zod";
+import { recipeReference } from "./schemas.mjs";
+
+export function defineRecipeGet(client) {
+    return {
+       title: "Read a Recipe",
+       description: "Inspect an approved Recipe's graph, inputs, outputs, author, and version before deciding whether to fork it.",
+       annotations: { readOnlyHint: true, openWorldHint: false },
+       inputSchema: z.object({
+           recipeId: recipeReference,
+           version: z.string().min(1).max(80).optional(),
+       }),
+       handler: ({ recipeId, version }) => client.getRecipe(recipeId, version),
+    };
+}