@gavana.ai/cli 0.2.0

package/src/tools/action_get.mjs

@@ -0,0 +1,16 @@
+// Tool definition: action_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 { actionReference } from "./schemas.mjs";
+
+export function defineActionGet(client) {
+    return {
+       title: "Read an image Action schema",
+       description: "Inspect one deterministic Action's exact input order and accepted parameters before running it.",
+       annotations: { readOnlyHint: true, openWorldHint: false },
+       inputSchema: z.object({ actionId: actionReference }),
+       handler: ({ actionId }) => client.getAction(actionId),
+    };
+}

package/src/tools/action_list.mjs

@@ -0,0 +1,21 @@
+// Tool definition: action_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 defineActionList(client) {
+    return {
+       title: "List deterministic image Actions",
+       description: "Discover the available credit-free image transforms and their typed inputs and parameters.",
+       annotations: { readOnlyHint: true, openWorldHint: false },
+       inputSchema: z.object({
+           query: z.string().max(240).optional(),
+           limit: listLimit(100),
+           cursor: listCursor,
+       }),
+       handler: ({ query, limit, cursor }) => client.listActions(query, listOptions(limit, cursor)),
+    };
+}

package/src/tools/action_run.mjs

@@ -0,0 +1,60 @@
+// Tool definition: action_run
+//
+// 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 { actionReference, assetReference, canvasReference, imageDestination, nodeReference, revisionFields } from "./schemas.mjs";
+import { withProgress } from "./progress.mjs";
+
+export function defineActionRun(client) {
+    return {
+       title: "Run a deterministic image Action",
+       description: "Queue one credit-free transform into a durable canvas image target. Inputs must follow the order declared by action_get.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({
+           actionId: actionReference,
+           canvasId: canvasReference.optional(),
+           destination: imageDestination.optional(),
+           canvasTitle: z.string().min(1).max(160).optional(),
+           targetNodeId: nodeReference.optional(),
+           inputs: z
+               .array(z.union([nodeReference, assetReference]))
+               .min(1)
+               .max(2),
+           params: z.record(z.union([z.string(), z.number().finite(), z.boolean()])).default({}),
+           ...revisionFields,
+           wait: z.boolean().default(true),
+           timeoutSeconds: z.number().min(1).max(3_600).default(900),
+       }),
+       markdown: true,
+       handler: async (input, extra) => {
+           const destination = input.destination || input.canvasId;
+           if (!destination) throw Object.assign(new Error("Input validation error: Provide destination or canvasId."), { code: "invalid_action_input" });
+           if (destination === "new-canvas" && !input.canvasTitle) throw Object.assign(new Error("Input validation error: new-canvas requires canvasTitle."), { code: "invalid_action_input" });
+           const definition = (await client.getAction(input.actionId)).action;
+           const prepared = await client.prepareImageDestination({
+               destination,
+               canvasId: input.canvasId,
+               canvasTitle: input.canvasTitle,
+               targetNodeId: input.targetNodeId,
+               baseRevision: input.baseRevision,
+               idempotencyKey: input.idempotencyKey,
+               operation: "action",
+               count: 1,
+               targetTitle: `${definition.title} result`,
+           });
+           const queued = await client.startAction(input.actionId, {
+               canvasId: prepared.canvasId,
+               baseRevision: prepared.baseRevision,
+               idempotencyKey: input.idempotencyKey,
+               targetNodeId: prepared.targetNodeIds[0],
+               inputs: input.inputs,
+               params: input.params,
+           });
+           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/agent_canvas_get.mjs

@@ -0,0 +1,15 @@
+// Tool definition: agent_canvas_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";
+
+export function defineAgentCanvasGet(client) {
+    return {
+       title: "Open Agent Canvas",
+       description: "Get or create this user's persistent Agent Canvas and return its stable handle and current revision.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({}),
+       handler: () => client.getOrCreateAgentCanvas(),
+    };
+}

package/src/tools/asset_get.mjs

@@ -0,0 +1,16 @@
+// Tool definition: asset_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 { assetReference } from "./schemas.mjs";
+
+export function defineAssetGet(client) {
+    return {
+       title: "Read a Gavana asset",
+       description: "Read asset metadata and receive a scoped expiring preview link for an image.",
+       annotations: { readOnlyHint: true, openWorldHint: false },
+       inputSchema: z.object({ assetId: assetReference }),
+       handler: ({ assetId }) => client.getAsset(assetId),
+    };
+}

package/src/tools/asset_list.mjs

@@ -0,0 +1,17 @@
+// Tool definition: asset_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 { canvasReference, listCursor, listLimit } from "./schemas.mjs";
+
+export function defineAssetList(client) {
+    return {
+       title: "List Gavana assets",
+       description: "List durable assets, optionally limited to one canvas.",
+       annotations: { readOnlyHint: true, openWorldHint: false },
+       inputSchema: z.object({ canvasId: canvasReference.optional(), limit: listLimit(200), cursor: listCursor }),
+       handler: ({ canvasId, limit, cursor }) => client.listAssets(canvasId, listOptions(limit, cursor)),
+    };
+}

package/src/tools/asset_upload.mjs

@@ -0,0 +1,24 @@
+// Tool definition: asset_upload
+//
+// 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 { readLocalReferenceImage } from "./helpers.mjs";
+import { canvasReference } from "./schemas.mjs";
+
+export function defineAssetUpload(client) {
+    return {
+       title: "Upload a user-provided local image",
+       description:
+           "Upload one local PNG, JPEG, WebP, or GIF that the user explicitly supplied or selected. This local stdio tool reads that file from this machine and returns a durable asset: handle for image_edit; never use it to inspect unrelated local files.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+       inputSchema: z.object({
+           filePath: z.string().min(1).max(4_096).describe("Absolute or relative path to a local image explicitly supplied or selected by the user."),
+           canvasId: canvasReference.optional().describe("Optional canvas:<id> handle to associate with the uploaded reference."),
+       }),
+       handler: async ({ filePath, canvasId }) => {
+           const reference = await readLocalReferenceImage(filePath);
+           return client.uploadAsset({ ...reference, ...(canvasId ? { canvasReference: canvasId } : {}) });
+       },
+    };
+}

package/src/tools/campaign_cancel.mjs

@@ -0,0 +1,16 @@
+// Tool definition: campaign_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 { runReference } from "./schemas.mjs";
+
+export function defineCampaignCancel(client) {
+    return {
+       title: "Cancel a legacy campaign run",
+       description: "Compatibility operation for an existing campaign run. Use only after explicit user intent.",
+       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({ runId: runReference }),
+       handler: ({ runId }) => client.cancelCampaign(runId),
+        };
+}

package/src/tools/campaign_get.mjs

@@ -0,0 +1,16 @@
+// Tool definition: campaign_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 { runReference } from "./schemas.mjs";
+
+export function defineCampaignGet(client) {
+    return {
+       title: "Read legacy campaign run state",
+       description: "Compatibility read for a legacy campaign record. This may reconcile durable historical runner state.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+       inputSchema: z.object({ runId: runReference }),
+       handler: ({ runId }) => client.getCampaign(runId),
+        };
+}

package/src/tools/campaign_plan.mjs

@@ -0,0 +1,31 @@
+// Tool definition: campaign_plan
+//
+// 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 { campaignAspectRatio, campaignIdempotencyKey, campaignProductReference, exactCanvasReference, recipeReference } from "./schemas.mjs";
+
+export function defineCampaignPlan(client) {
+    return {
+        title: "Legacy campaign plan",
+        description: "Compatibility operation for an existing campaign integration. Do not use it for new work; use editable canvas blocks and explicit image jobs instead.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({
+            canvasId: exactCanvasReference,
+            recipeId: recipeReference,
+            recipeVersion: z.string().min(1).max(80).optional().describe("Exact published Recipe version. Omit only to use the Recipe's current version."),
+            product: campaignProductReference.optional(),
+            brandKitId: z
+                .string()
+                .regex(/^[A-Za-z0-9_-]{1,180}$/)
+                .optional()
+                .describe("Exact Brand Kit ID selected by the user."),
+            brandKitRevision: z.number().int().min(1).optional().describe("Exact approved Brand Kit revision. Never substitute the latest revision."),
+            brief: z.string().max(8_000).optional().describe("Plain-language campaign concept, audience, tone, and visual direction."),
+            finalOutputCount: z.number().int().min(1).max(4).optional().describe("Number of final campaign images to create after review."),
+            aspectRatios: z.array(campaignAspectRatio).length(1).optional().describe("Optional one-item array containing the V1 final output ratio. Defaults to 1:1."),
+            idempotencyKey: campaignIdempotencyKey,
+        }),
+        handler: (input) => client.planCampaign(input),
+    };
+}

package/src/tools/campaign_review.mjs

@@ -0,0 +1,24 @@
+// Tool definition: campaign_review
+//
+// 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 { approvedOutputReferences, campaignIdempotencyKey, runReference } from "./schemas.mjs";
+
+export function defineCampaignReview(client) {
+    return {
+       title: "Legacy campaign review",
+       description: "Compatibility operation for an existing campaign record. New work should remain editable on the canvas.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+       inputSchema: z.object({
+           runId: runReference,
+           approvedOutputNodeIds: approvedOutputReferences,
+           idempotencyKey: campaignIdempotencyKey,
+       }),
+       handler: ({ runId, approvedOutputNodeIds, idempotencyKey }) =>
+           client.reviewCampaign(runId, {
+               approvedOutputNodeIds,
+               idempotencyKey,
+           }),
+        };
+}

package/src/tools/campaign_start.mjs

@@ -0,0 +1,19 @@
+// Tool definition: campaign_start
+//
+// 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 { campaignIdempotencyKey, campaignReference } from "./schemas.mjs";
+
+export function defineCampaignStart(client) {
+    return {
+       title: "Legacy campaign start",
+       description: "Compatibility operation for an existing campaign record. Do not use it as a new-work workflow.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+       inputSchema: z.object({
+           campaignId: campaignReference,
+           idempotencyKey: campaignIdempotencyKey,
+       }),
+       handler: (input) => client.startCampaign(input),
+        };
+}

package/src/tools/canvas_apply_batch.mjs

@@ -0,0 +1,35 @@
+// Tool definition: canvas_apply_batch
+//
+// 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 { validateCanvasGraph } from "../canvas-agent-validation.mjs";
+import { canvasReference, revisionFields } from "./schemas.mjs";
+
+export function defineCanvasApplyBatch(client) {
+    return {
+       title: "Apply an atomic canvas batch",
+       description:
+           "Atomically validate and apply related canvas, node, and connection operations. Batch-local client:<id> references resolve in the response. New agent-owned overlap or full-frame Section overflow is rejected without writing; historical user-canvas warnings remain advisory. Fix blocking findings, or pass force only when the user explicitly accepts them.",
+       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({
+           canvasId: canvasReference,
+           ...revisionFields,
+           operations: z.array(z.record(z.unknown())).min(1).max(200),
+           force: z.boolean().default(false).describe("Apply even when the projected graph has error-severity validation findings. Use only after canvas_validate, and only when the user explicitly accepts the listed findings."),
+       }),
+       handler: async ({ canvasId, baseRevision, idempotencyKey, operations, force }) => {
+           const current = baseRevision ? null : await client.getCanvas(canvasId);
+           const result = await client.applyOperations(canvasId, {
+               baseRevision: baseRevision || current?.canvas.revision,
+               idempotencyKey,
+               operations,
+               ...(force ? { force: true } : {}),
+           });
+           return {
+               ...result,
+               validation: validateCanvasGraph(result.canvas),
+           };
+       },
+    };
+}

package/src/tools/canvas_create.mjs

@@ -0,0 +1,15 @@
+// Tool definition: canvas_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.
+import { z } from "zod";
+
+export function defineCanvasCreate(client) {
+    return {
+       title: "Create a Gavana canvas",
+       description: "Create an empty canvas and return its stable handle and initial revision.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+       inputSchema: z.object({ title: z.string().min(1).max(160), id: z.string().min(1).max(180).optional() }),
+       handler: (input) => client.createCanvas(input),
+    };
+}

package/src/tools/canvas_get.mjs

@@ -0,0 +1,16 @@
+// Tool definition: canvas_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 } from "./schemas.mjs";
+
+export function defineCanvasGet(client) {
+    return {
+       title: "Read a Gavana canvas",
+       description: "Read the complete canvas graph, node metadata, connections, permissions, activity, and current revision.",
+       annotations: { readOnlyHint: true, openWorldHint: false },
+       inputSchema: z.object({ canvasId: canvasReference }),
+       handler: ({ canvasId }) => client.getCanvas(canvasId),
+    };
+}

package/src/tools/canvas_list.mjs

@@ -0,0 +1,17 @@
+// Tool definition: canvas_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 defineCanvasList(client) {
+    return {
+       title: "List Gavana canvases",
+       description: "List canvases this actor owns or can access, including stable handles, revisions, roles, and graph counts.",
+       annotations: { readOnlyHint: true, openWorldHint: false },
+       inputSchema: z.object({ limit: listLimit(25), cursor: listCursor }),
+       handler: ({ limit, cursor }) => client.listCanvases(listOptions(limit, cursor)),
+    };
+}

package/src/tools/canvas_render.mjs

@@ -0,0 +1,34 @@
+// Tool definition: canvas_render
+//
+// Registered through ./definitions.mjs. Unlike every other tool it returns an MCP
+// resource (an SVG) rather than a JSON result, so it sets rawResult and the server
+// passes its output through untouched.
+import { z } from "zod";
+
+import { canvasReference } from "./schemas.mjs";
+
+export function defineCanvasRender(client) {
+    return {
+        rawResult: true,
+        title: "Render a Gavana canvas",
+        description: "Render the current canvas as an SVG resource for multimodal or spatial inspection.",
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        inputSchema: z.object({ canvasId: canvasReference }),
+        handler: async ({ canvasId }) => {
+            const svg = await client.renderCanvas(canvasId);
+            return {
+                content: [
+                    {
+                        type: "resource",
+                        resource: {
+                            uri: `gavana://canvas/${encodeURIComponent(canvasId)}/render.svg`,
+                            mimeType: "image/svg+xml",
+                            text: svg,
+                        },
+                    },
+                ],
+                structuredContent: { canvasId, mediaType: "image/svg+xml", bytes: Buffer.byteLength(svg) },
+            };
+        },
+    };
+}

package/src/tools/canvas_validate.mjs

@@ -0,0 +1,34 @@
+// Tool definition: canvas_validate
+//
+// 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 { validateCanvasGraph } from "../canvas-agent-validation.mjs";
+import { canvasReference } from "./schemas.mjs";
+
+export function defineCanvasValidate(client) {
+    return {
+       title: "Validate a Gavana canvas",
+       description:
+           "Read and lint the current canvas, or run a canonical server-side dry-run of a proposed atomic batch without mutating it. Checks overlap, full-frame Section containment, generated lineage, connection semantics, destructive impact, and completionReview. Do not claim Done while completionReview.doneClaimAllowed is false.",
+       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({
+           canvasId: canvasReference,
+           baseRevision: z.string().min(1).max(200).optional().describe("Optional revision returned by canvas_get for proposed operations. Validation returns 409 if the canvas has changed."),
+           operations: z.array(z.record(z.unknown())).max(200).optional().describe("Optional proposed canvas_apply_batch operations for a canonical dry-run. Validation never applies them."),
+       }),
+       handler: async ({ canvasId, baseRevision, operations }) => {
+           if (operations?.length) {
+               const result = await client.validateOperations(canvasId, { ...(baseRevision ? { baseRevision } : {}), operations });
+               return {
+                   ...result.validation,
+                   currentCanvas: result.canvas,
+                   proposal: result.proposal,
+                   destructiveImpact: result.destructiveImpact,
+               };
+           }
+           const current = await client.getCanvas(canvasId);
+           return validateCanvasGraph(current.canvas);
+       },
+    };
+}

package/src/tools/connection_create.mjs

@@ -0,0 +1,38 @@
+// Tool definition: connection_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, nodeReference, revisionFields } from "./schemas.mjs";
+
+export function defineConnectionCreate(client) {
+    const config = {
+       title: "Connect canvas nodes",
+       description: "Create a directed connection between two stable node handles.",
+       destructiveHint: false,
+       schema: z.object({
+           canvasId: canvasReference,
+           ...revisionFields,
+           from: nodeReference,
+           to: nodeReference,
+           mode: z.enum(["list", "reference", "first-frame", "last-frame", "prompt"]).optional(),
+           clientId: z.string().min(1).max(100).optional(),
+       }),
+       operation: ({ from, to, mode, clientId }) => ({ type: "connection.create", from, to, ...(mode ? { mode } : {}), ...(clientId ? { clientId } : {}) }),
+    };
+    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/connection_delete.mjs

@@ -0,0 +1,31 @@
+// Tool definition: connection_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, connectionReference, revisionFields } from "./schemas.mjs";
+
+export function defineConnectionDelete(client) {
+    const config = {
+       title: "Disconnect canvas nodes",
+       description: "Delete one connection. This is destructive and should follow explicit user intent.",
+       destructiveHint: true,
+       schema: z.object({ canvasId: canvasReference, ...revisionFields, connectionId: connectionReference }),
+       operation: ({ connectionId }) => ({ type: "connection.delete", connectionId }),
+    };
+    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/definitions.mjs

@@ -0,0 +1,111 @@
+// Tool behaviour, keyed by canonical name.
+//
+// ./registry.mjs declares which tools exist and which surfaces advertise them.
+// This module binds each name to the factory that builds its config for a given
+// client. Keeping the two apart is what lets the catalog be asserted against a
+// server without importing every handler.
+//
+// scripts/canvas-agent-tool-registry.test.ts asserts this map and the registry
+// cover exactly the same local tools, so adding one without the other fails.
+
+import { defineCanvasRender } from "./canvas_render.mjs";
+import { defineImageEdit } from "./image_edit.mjs";
+import { defineImageGenerate } from "./image_generate.mjs";
+import { defineImageVariations } from "./image_variations.mjs";
+import { defineActionGet } from "./action_get.mjs";
+import { defineActionList } from "./action_list.mjs";
+import { defineActionRun } from "./action_run.mjs";
+import { defineAgentCanvasGet } from "./agent_canvas_get.mjs";
+import { defineAssetGet } from "./asset_get.mjs";
+import { defineAssetList } from "./asset_list.mjs";
+import { defineAssetUpload } from "./asset_upload.mjs";
+import { defineCampaignCancel } from "./campaign_cancel.mjs";
+import { defineCampaignGet } from "./campaign_get.mjs";
+import { defineCampaignPlan } from "./campaign_plan.mjs";
+import { defineCampaignReview } from "./campaign_review.mjs";
+import { defineCampaignStart } from "./campaign_start.mjs";
+import { defineCanvasApplyBatch } from "./canvas_apply_batch.mjs";
+import { defineCanvasCreate } from "./canvas_create.mjs";
+import { defineCanvasGet } from "./canvas_get.mjs";
+import { defineCanvasList } from "./canvas_list.mjs";
+import { defineCanvasValidate } from "./canvas_validate.mjs";
+import { defineConnectionCreate } from "./connection_create.mjs";
+import { defineConnectionDelete } from "./connection_delete.mjs";
+import { defineGuideGet } from "./guide_get.mjs";
+import { defineGuideSearch } from "./guide_search.mjs";
+import { defineJobCancel } from "./job_cancel.mjs";
+import { defineJobGet } from "./job_get.mjs";
+import { defineJobWait } from "./job_wait.mjs";
+import { defineModelGet } from "./model_get.mjs";
+import { defineModelList } from "./model_list.mjs";
+import { defineNodeCreate } from "./node_create.mjs";
+import { defineNodeDelete } from "./node_delete.mjs";
+import { defineNodeGet } from "./node_get.mjs";
+import { defineNodeMove } from "./node_move.mjs";
+import { defineNodeResize } from "./node_resize.mjs";
+import { defineNodeUpdate } from "./node_update.mjs";
+import { defineProviderList } from "./provider_list.mjs";
+import { defineRecipeFork } from "./recipe_fork.mjs";
+import { defineRecipeGet } from "./recipe_get.mjs";
+import { defineRecipeRun } from "./recipe_run.mjs";
+import { defineRecipeSearch } from "./recipe_search.mjs";
+import { defineRunCancel } from "./run_cancel.mjs";
+import { defineRunGet } from "./run_get.mjs";
+import { defineRunWait } from "./run_wait.mjs";
+import { defineVideoGenerate } from "./video_generate.mjs";
+
+/** @type {Record<string, (client: unknown) => object>} */
+export const GAVANA_TOOL_DEFINITIONS = Object.freeze({
+    image_variations: defineImageVariations,
+    image_generate: defineImageGenerate,
+    image_edit: defineImageEdit,
+    canvas_render: defineCanvasRender,
+    action_get: defineActionGet,
+    action_list: defineActionList,
+    action_run: defineActionRun,
+    agent_canvas_get: defineAgentCanvasGet,
+    asset_get: defineAssetGet,
+    asset_list: defineAssetList,
+    asset_upload: defineAssetUpload,
+    campaign_cancel: defineCampaignCancel,
+    campaign_get: defineCampaignGet,
+    campaign_plan: defineCampaignPlan,
+    campaign_review: defineCampaignReview,
+    campaign_start: defineCampaignStart,
+    canvas_apply_batch: defineCanvasApplyBatch,
+    canvas_create: defineCanvasCreate,
+    canvas_get: defineCanvasGet,
+    canvas_list: defineCanvasList,
+    canvas_validate: defineCanvasValidate,
+    connection_create: defineConnectionCreate,
+    connection_delete: defineConnectionDelete,
+    guide_get: defineGuideGet,
+    guide_search: defineGuideSearch,
+    job_cancel: defineJobCancel,
+    job_get: defineJobGet,
+    job_wait: defineJobWait,
+    model_get: defineModelGet,
+    model_list: defineModelList,
+    node_create: defineNodeCreate,
+    node_delete: defineNodeDelete,
+    node_get: defineNodeGet,
+    node_move: defineNodeMove,
+    node_resize: defineNodeResize,
+    node_update: defineNodeUpdate,
+    provider_list: defineProviderList,
+    recipe_fork: defineRecipeFork,
+    recipe_get: defineRecipeGet,
+    recipe_run: defineRecipeRun,
+    recipe_search: defineRecipeSearch,
+    run_cancel: defineRunCancel,
+    run_get: defineRunGet,
+    run_wait: defineRunWait,
+    video_generate: defineVideoGenerate,
+});
+
+/** Build every local tool config for a client, in registry order. */
+export function gavanaToolConfig(name, client) {
+    const factory = GAVANA_TOOL_DEFINITIONS[name];
+    if (!factory) throw new Error(`No Gavana tool definition for ${name}`);
+    return factory(client);
+}

package/src/tools/guide_get.mjs

@@ -0,0 +1,16 @@
+// Tool definition: guide_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 { GAVANA_CANVAS_GUIDE_INDEX_URI, getCanvasGuide } from "../canvas-agent-guide.mjs";
+
+export function defineGuideGet(client) {
+    return {
+       title: "Read a Canvas Agent Guide",
+       description: `Read one canonical Gavana Canvas Agent Guide topic. Start at ${GAVANA_CANVAS_GUIDE_INDEX_URI} or use guide_search to find an exact topic ID.`,
+       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({ guideId: z.string().min(1).max(600).describe("Guide topic ID or exact gavana:// guide URI returned by guide_search or resources/list.") }),
+       handler: ({ guideId }) => getCanvasGuide(guideId),
+    };
+}