@gavana.ai/cli 0.2.0

package/src/tools/recipe_run.mjs

@@ -0,0 +1,61 @@
+// Tool definition: recipe_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 { canvasReference, imageDestination, modelReference, nodeReference, rawModelId, recipeReference, revisionFields } from "./schemas.mjs";
+import { withProgress } from "./progress.mjs";
+
+export function defineRecipeRun(client) {
+    return {
+       title: "Run a Recipe explicitly",
+       description: "Start one approved Recipe or connected private Recipe instance as a durable asynchronous Run. This is the only Recipe operation that executes text or image work.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+       inputSchema: z.object({
+           recipeId: recipeReference,
+           canvasId: canvasReference.optional(),
+           destination: imageDestination.optional(),
+           canvasTitle: z.string().min(1).max(160).optional(),
+           version: z.string().min(1).max(80).optional(),
+           instanceNodeId: nodeReference.optional().describe("Optional private Recipe instance already connected on the destination canvas."),
+           inputs: z
+               .record(z.string().min(1).max(8_000))
+               .refine((value) => Object.keys(value).length <= 16, "A Recipe run accepts at most 16 typed inputs.")
+               .default({})
+               .describe("Map each Recipe input key to a node:, asset:, or plain text value."),
+           model: z.union([modelReference, rawModelId]).optional(),
+           size: z.string().max(80).optional(),
+           quality: z.string().max(80).optional(),
+           ...revisionFields,
+           wait: z.boolean().default(true),
+           timeoutSeconds: z.number().min(1).max(3_600).default(900),
+       }),
+       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_recipe_input" });
+           if (destination === "new-canvas" && !input.canvasTitle) throw Object.assign(new Error("Input validation error: new-canvas requires canvasTitle."), { code: "invalid_recipe_input" });
+           if (!Object.keys(input.inputs).length && !input.instanceNodeId) {
+               throw Object.assign(new Error("Input validation error: Provide typed inputs or an already connected instanceNodeId."), { code: "invalid_recipe_input" });
+           }
+           const canvasResult = await client.resolveCanvasDestination(destination, {
+               idempotencyKey: input.idempotencyKey,
+               title: input.canvasTitle,
+           });
+           const queued = await client.startRecipeRun(input.recipeId, {
+               canvasId: canvasResult.canvas.handle,
+               baseRevision: input.baseRevision || canvasResult.canvas.revision,
+               idempotencyKey: input.idempotencyKey,
+               ...(input.version ? { version: input.version } : {}),
+               ...(input.instanceNodeId ? { instanceNodeId: input.instanceNodeId } : {}),
+               ...(Object.keys(input.inputs).length ? { inputs: input.inputs } : {}),
+               ...(input.model ? { model: input.model } : {}),
+               ...(input.size ? { size: input.size } : {}),
+               ...(input.quality ? { quality: input.quality } : {}),
+           });
+           const destinationResult = { requested: destination, canvasId: canvasResult.canvas.handle };
+           if (input.wait === false) return { ...queued, destination: destinationResult };
+           const result = await client.waitForRun(queued.run || queued.handle || queued.id, withProgress({ timeoutMs: input.timeoutSeconds * 1000 }, extra));
+           return { ...result, destination: destinationResult };
+       },
+    };
+}

package/src/tools/recipe_search.mjs

@@ -0,0 +1,17 @@
+// Tool definition: recipe_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 { listOptions } from "./helpers.mjs";
+import { listCursor, listLimit } from "./schemas.mjs";
+
+export function defineRecipeSearch(client) {
+    return {
+       title: "Search Recipe Library",
+       description: "Search approved reusable visual Recipes. Discovery is read-only and does not create canvas blocks or image jobs.",
+       annotations: { readOnlyHint: true, openWorldHint: false },
+       inputSchema: z.object({ query: z.string().max(240).default(""), limit: listLimit(100), cursor: listCursor }),
+       handler: ({ query, limit, cursor }) => client.searchRecipes(query, listOptions(limit, cursor)),
+    };
+}

package/src/tools/registry.mjs

@@ -0,0 +1,550 @@
+// The single catalog both MCP servers are views of.
+//
+// Before this module the hosted server (src/lib/chatgpt-mcp.ts) and the local stdio
+// server (scripts/gavana-agent-mcp.mjs) each hand-maintained their own tool list, in
+// different naming conventions, with nothing to stop them drifting. Every entry here
+// is the canonical noun_verb name; a hosted verb-object name survives as
+// `hostedAlias` and stays callable, because @gavana.ai/mcp@0.1.1 is published and
+// those names are a compatibility contract.
+//
+// Generated once from the live catalogs of both servers, then maintained by hand.
+// scripts/canvas-agent-tool-registry.test.ts asserts each server's advertised
+// catalog still matches this file, so drift fails the build rather than shipping.
+
+/**
+ * @typedef {object} GavanaToolDefinition
+ * @property {string} name Canonical noun_verb name.
+ * @property {string} toolset Gating group (see GAVANA_MCP_TOOLSETS).
+ * @property {("local"|"hosted")[]} surfaces Which servers advertise it.
+ * @property {string} [hostedAlias] Deprecated verb-object name the hosted server still accepts.
+ * @property {string[]} [scopes] OAuth scopes the hosted surface requires.
+ * @property {boolean} [embedImage] Hosted surface inlines an image into the result.
+ * @property {boolean} [legacyCampaign] Deprecated campaign tool, hidden unless explicitly enabled.
+ * @property {boolean} [readOnlySurface] Advertised on the read-only surface.
+ * @property {false} [hermesDefault] Excluded from the Hermes default selection.
+ *   Hermes enables a safe subset out of the box: destructive deletes and cancels,
+ *   the filesystem-reading asset_upload, and the deprecated campaign_* tools are
+ *   opt-in via `hermes mcp configure gavana`.
+ * @property {object|null} annotations MCP tool annotations.
+ */
+
+/** @type {readonly GavanaToolDefinition[]} */
+export const GAVANA_TOOL_REGISTRY = Object.freeze([
+    {
+        name: "action_get",
+        toolset: "actions",
+        surfaces: ["local"],
+        readOnlySurface: true,
+        localOrder: 33,
+        annotations: {"readOnlyHint":true,"openWorldHint":false},
+    },
+    {
+        name: "action_list",
+        toolset: "actions",
+        surfaces: ["local"],
+        readOnlySurface: true,
+        localOrder: 32,
+        annotations: {"readOnlyHint":true,"openWorldHint":false},
+    },
+    {
+        name: "action_run",
+        toolset: "actions",
+        surfaces: ["local"],
+        localOrder: 34,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "agent_canvas_get",
+        toolset: "canvas",
+        surfaces: ["local"],
+        localOrder: 16,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "asset_get",
+        toolset: "assets",
+        surfaces: ["local"],
+        readOnlySurface: true,
+        localOrder: 27,
+        annotations: {"readOnlyHint":true,"openWorldHint":false},
+    },
+    {
+        name: "asset_list",
+        toolset: "assets",
+        surfaces: ["local"],
+        readOnlySurface: true,
+        localOrder: 26,
+        annotations: {"readOnlyHint":true,"openWorldHint":false},
+    },
+    {
+        name: "asset_upload",
+        toolset: "assets",
+        surfaces: ["local"],
+        localOrder: 28,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false},
+    },
+    {
+        name: "campaign_cancel",
+        toolset: "campaigns",
+        surfaces: ["local"],
+        legacyCampaign: true,
+        localOrder: 10,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "campaign_get",
+        toolset: "campaigns",
+        surfaces: ["local"],
+        legacyCampaign: true,
+        localOrder: 8,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
+    {
+        name: "campaign_plan",
+        toolset: "campaigns",
+        surfaces: ["local"],
+        legacyCampaign: true,
+        localOrder: 6,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "campaign_review",
+        toolset: "campaigns",
+        surfaces: ["local"],
+        legacyCampaign: true,
+        localOrder: 9,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
+    {
+        name: "campaign_start",
+        toolset: "campaigns",
+        surfaces: ["local"],
+        legacyCampaign: true,
+        localOrder: 7,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
+    {
+        name: "canvas_apply_batch",
+        toolset: "canvas",
+        surfaces: ["hosted","local"],
+        scopes: ["canvas:read","canvas:write"],
+        hostedOrder: 5,
+        hostedReadOnly: false,
+        hostedToolset: "canvas",
+        localOrder: 17,
+        annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "canvas_create",
+        toolset: "canvas",
+        surfaces: ["local"],
+        localOrder: 15,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false},
+    },
+    {
+        name: "canvas_get",
+        toolset: "canvas",
+        surfaces: ["hosted","local"],
+        scopes: ["canvas:read"],
+        readOnlySurface: true,
+        hostedOrder: 3,
+        hostedReadOnly: true,
+        hostedToolset: "canvas",
+        localOrder: 12,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "canvas_image_get",
+        toolset: "canvas",
+        surfaces: ["hosted"],
+        hostedAlias: "get_canvas_image",
+        scopes: ["canvas:read"],
+        readOnlySurface: true,
+        hostedOrder: 6,
+        hostedReadOnly: true,
+        hostedToolset: "assets",
+        embedImage: true,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "canvas_image_save",
+        toolset: "canvas",
+        surfaces: ["hosted"],
+        hostedAlias: "save_image_to_canvas",
+        scopes: ["canvas:read","canvas:write","asset:read","image:generate"],
+        hostedOrder: 8,
+        hostedReadOnly: false,
+        hostedToolset: "assets",
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
+    {
+        name: "canvas_list",
+        toolset: "canvas",
+        surfaces: ["hosted","local"],
+        scopes: ["canvas:read"],
+        readOnlySurface: true,
+        hostedOrder: 2,
+        hostedReadOnly: true,
+        hostedToolset: "canvas",
+        localOrder: 11,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "canvas_open",
+        toolset: "canvas",
+        surfaces: ["hosted"],
+        hostedAlias: "open_canvas",
+        scopes: ["canvas:read"],
+        readOnlySurface: true,
+        hostedOrder: 7,
+        hostedReadOnly: true,
+        hostedToolset: "canvas",
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "canvas_render",
+        toolset: "canvas",
+        surfaces: ["local"],
+        readOnlySurface: true,
+        localOrder: 14,
+        annotations: {"readOnlyHint":true,"openWorldHint":false},
+    },
+    {
+        name: "canvas_validate",
+        toolset: "canvas",
+        surfaces: ["hosted","local"],
+        scopes: ["canvas:read"],
+        readOnlySurface: true,
+        hostedOrder: 4,
+        hostedReadOnly: true,
+        hostedToolset: "canvas",
+        localOrder: 13,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "canvas_workflow_create",
+        toolset: "canvas",
+        surfaces: ["hosted"],
+        hostedAlias: "create_canvas_workflow",
+        scopes: ["canvas:read","canvas:write"],
+        hostedOrder: 10,
+        hostedReadOnly: false,
+        hostedToolset: "recipes",
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "canvas_workflow_run",
+        toolset: "canvas",
+        surfaces: ["hosted"],
+        hostedAlias: "run_canvas_workflow",
+        scopes: ["canvas:read","canvas:write","asset:read","image:generate","job:manage"],
+        hostedOrder: 11,
+        paid: true,
+        hostedReadOnly: false,
+        hostedToolset: "recipes",
+        embedImage: true,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
+    {
+        name: "canvas_workflow_run_get",
+        toolset: "canvas",
+        surfaces: ["hosted"],
+        hostedAlias: "get_canvas_workflow_run",
+        scopes: ["canvas:read","job:manage"],
+        hostedOrder: 12,
+        hostedReadOnly: false,
+        hostedToolset: "runs",
+        embedImage: true,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "connection_create",
+        toolset: "canvas",
+        surfaces: ["local"],
+        localOrder: 24,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "connection_delete",
+        toolset: "canvas",
+        surfaces: ["local"],
+        localOrder: 25,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "guide_get",
+        toolset: "canvas",
+        surfaces: ["hosted","local"],
+        scopes: [],
+        readOnlySurface: true,
+        hostedOrder: 1,
+        hostedReadOnly: true,
+        hostedToolset: "canvas",
+        localOrder: 1,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "guide_search",
+        toolset: "canvas",
+        surfaces: ["hosted","local"],
+        scopes: [],
+        readOnlySurface: true,
+        hostedOrder: 0,
+        hostedReadOnly: true,
+        hostedToolset: "canvas",
+        localOrder: 0,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "image_edit",
+        toolset: "images",
+        surfaces: ["local"],
+        localOrder: 36,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
+    {
+        name: "image_generate",
+        toolset: "images",
+        surfaces: ["hosted","local"],
+        hostedAlias: "generate_image_in_canvas",
+        scopes: ["canvas:read","canvas:write","asset:read","image:generate","job:manage"],
+        hostedOrder: 13,
+        paid: true,
+        hostedReadOnly: false,
+        hostedToolset: "images",
+        localOrder: 35,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
+    {
+        name: "image_variations",
+        toolset: "images",
+        surfaces: ["local"],
+        localOrder: 37,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
+    {
+        name: "job_cancel",
+        toolset: "runs",
+        surfaces: ["local"],
+        localOrder: 41,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "job_get",
+        toolset: "runs",
+        surfaces: ["local"],
+        localOrder: 39,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "job_wait",
+        toolset: "runs",
+        surfaces: ["local"],
+        localOrder: 40,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "model_get",
+        toolset: "models",
+        surfaces: ["local"],
+        readOnlySurface: true,
+        localOrder: 31,
+        annotations: {"readOnlyHint":true,"openWorldHint":false},
+    },
+    {
+        name: "model_list",
+        toolset: "models",
+        surfaces: ["local"],
+        readOnlySurface: true,
+        localOrder: 30,
+        annotations: {"readOnlyHint":true,"openWorldHint":false},
+    },
+    {
+        name: "node_create",
+        toolset: "canvas",
+        surfaces: ["local"],
+        localOrder: 19,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "node_delete",
+        toolset: "canvas",
+        surfaces: ["local"],
+        localOrder: 23,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "node_get",
+        toolset: "canvas",
+        surfaces: ["local"],
+        readOnlySurface: true,
+        localOrder: 18,
+        annotations: {"readOnlyHint":true,"openWorldHint":false},
+    },
+    {
+        name: "node_move",
+        toolset: "canvas",
+        surfaces: ["local"],
+        localOrder: 21,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "node_resize",
+        toolset: "canvas",
+        surfaces: ["local"],
+        localOrder: 22,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "node_update",
+        toolset: "canvas",
+        surfaces: ["local"],
+        localOrder: 20,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "product_reference_pack_import",
+        toolset: "assets",
+        surfaces: ["hosted"],
+        hostedAlias: "import_product_reference_pack",
+        scopes: ["canvas:read","canvas:write","asset:read"],
+        hostedOrder: 9,
+        hostedReadOnly: false,
+        hostedToolset: "assets",
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
+    {
+        name: "provider_list",
+        toolset: "models",
+        surfaces: ["local"],
+        readOnlySurface: true,
+        localOrder: 29,
+        annotations: {"readOnlyHint":true,"openWorldHint":false},
+    },
+    {
+        name: "recipe_fork",
+        toolset: "recipes",
+        surfaces: ["local"],
+        localOrder: 4,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "recipe_get",
+        toolset: "recipes",
+        surfaces: ["local"],
+        readOnlySurface: true,
+        localOrder: 3,
+        annotations: {"readOnlyHint":true,"openWorldHint":false},
+    },
+    {
+        name: "recipe_run",
+        toolset: "recipes",
+        surfaces: ["local"],
+        localOrder: 5,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
+    {
+        name: "recipe_search",
+        toolset: "recipes",
+        surfaces: ["local"],
+        readOnlySurface: true,
+        localOrder: 2,
+        annotations: {"readOnlyHint":true,"openWorldHint":false},
+    },
+    {
+        name: "run_cancel",
+        toolset: "runs",
+        surfaces: ["local"],
+        localOrder: 44,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "run_get",
+        toolset: "runs",
+        surfaces: ["local"],
+        localOrder: 42,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "run_wait",
+        toolset: "runs",
+        surfaces: ["local"],
+        localOrder: 43,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "video_generate",
+        toolset: "videos",
+        surfaces: ["hosted","local"],
+        hostedAlias: "generate_video",
+        scopes: ["canvas:read","asset:read","video:generate","job:manage"],
+        hostedOrder: 15,
+        paid: true,
+        hostedReadOnly: false,
+        hostedToolset: "videos",
+        localOrder: 38,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
+    {
+        name: "video_job_get",
+        toolset: "videos",
+        surfaces: ["hosted"],
+        hostedAlias: "get_video_job",
+        scopes: ["job:manage"],
+        hostedOrder: 16,
+        hostedReadOnly: false,
+        hostedToolset: "runs",
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "video_model_find",
+        toolset: "videos",
+        surfaces: ["hosted"],
+        hostedAlias: "find_video_models",
+        scopes: ["video:generate"],
+        hostedOrder: 14,
+        hostedReadOnly: true,
+        hostedToolset: "models",
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+]);
+
+/** Canonical name for a tool name or deprecated hosted alias. */
+export function gavanaCanonicalToolName(name) {
+    const value = String(name || "");
+    if (GAVANA_TOOL_REGISTRY.some((tool) => tool.name === value)) return value;
+    return GAVANA_TOOL_REGISTRY.find((tool) => tool.hostedAlias === value)?.name;
+}
+
+/** Every deprecated hosted alias, as alias -> canonical. */
+export const GAVANA_TOOL_ALIASES = Object.freeze(
+    Object.fromEntries(GAVANA_TOOL_REGISTRY.filter((tool) => tool.hostedAlias).map((tool) => [tool.hostedAlias, tool.name])),
+);
+
+/** Tools Hermes enables by default: every local tool except the opt-in ones. */
+export function gavanaHermesDefaultTools() {
+    return GAVANA_TOOL_REGISTRY.filter((tool) => tool.surfaces.includes("local") && tool.hermesDefault !== false);
+}
+
+/** Tools a surface advertises. Campaign tools stay hidden unless explicitly included. */
+export function gavanaToolsForSurface(surface, { includeLegacyCampaign = false, readOnly = false } = {}) {
+    // Advertised order is observable to clients and asserted by the server tests, so
+    // each surface keeps the order it shipped with rather than falling out of the
+    // registry's alphabetical layout.
+    const key = surface === "hosted" ? "hostedOrder" : "localOrder";
+    return GAVANA_TOOL_REGISTRY.filter(
+        (tool) => tool.surfaces.includes(surface) && (includeLegacyCampaign || !tool.legacyCampaign) && (!readOnly || tool.readOnlySurface),
+    )
+        .slice()
+        .sort((left, right) => (left[key] ?? 0) - (right[key] ?? 0));
+}

package/src/tools/run_cancel.mjs

@@ -0,0 +1,16 @@
+// Tool definition: run_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 defineRunCancel(client) {
+    return {
+       title: "Cancel a shared Run",
+       description: "Cancel queued or running Recipe, image, or Action work. Use only after explicit user intent.",
+       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({ runId: runReference }),
+       handler: ({ runId }) => client.cancelRun(runId),
+    };
+}

package/src/tools/run_get.mjs

@@ -0,0 +1,17 @@
+// Tool definition: run_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 defineRunGet(client) {
+    return {
+       title: "Read a shared Run",
+       description: "Read or resume Recipe, image, or Action work through one shared Run resource.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({ runId: runReference }),
+       markdown: true,
+       handler: ({ runId }) => client.getRun(runId),
+    };
+}

package/src/tools/run_wait.mjs

@@ -0,0 +1,18 @@
+// Tool definition: run_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 { runReference } from "./schemas.mjs";
+import { withProgress } from "./progress.mjs";
+
+export function defineRunWait(client) {
+    return {
+       title: "Wait for a shared Run",
+       description: "Wait for a Recipe, image, or Action Run to reach a terminal state and return its durable outputs.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+       inputSchema: z.object({ runId: runReference, timeoutSeconds: z.number().min(1).max(3_600).default(900) }),
+       markdown: true,
+       handler: ({ runId, timeoutSeconds }, extra) => client.waitForRun(runId, withProgress({ timeoutMs: timeoutSeconds * 1000 }, extra)),
+    };
+}