@gavana.ai/cli 0.2.1 → 0.3.0

package/src/runner.mjs

@@ -12,7 +12,7 @@ import { GAVANA_CLI_GROUP_HELP, gavanaCommandActions, gavanaCommandGroupUsageLin
 import { agentConfigFilePath, listAgentProfiles, readAgentConfig, readAgentConfigMetadata, removeAgentProfile, setActiveAgentProfile, writeAgentConfig } from "./config.mjs";
 import { gavanaMcpClientDefinition } from "./mcp-targets.mjs";
 
-const BOOLEAN_OPTIONS = new Set(["help", "version", "pretty", "raw", "yes", "confirm", "rebase", "wait", "no-wait", "progress", "token-stdin", "no-verify", "no-browser", "audio", "no-audio", "read-only"]);
+const BOOLEAN_OPTIONS = new Set(["help", "version", "pretty", "raw", "yes", "confirm", "rebase", "wait", "no-wait", "progress", "preflight", "token-stdin", "no-verify", "no-browser", "audio", "no-audio", "read-only"]);
 const REPEATABLE_OPTIONS = new Set(["reference", "reference-role", "element", "input", "param", "target", "ratio", "approved", "field", "source-asset", "collection"]);
 const MAX_REFERENCE_IMAGES = 16;
 const MAX_VIDEO_REFERENCE_IMAGES = 9;
@@ -95,7 +95,7 @@ export async function runGavanaCli(argv = process.argv.slice(2), runtime = {}) {
         }
         if (!token && config.credentialState === "inaccessible") throw keychainInaccessibleError();
         const client = createCanvasAgentClient({ token, baseUrl, surface: "cli", fetchImpl: runtime.fetchImpl });
-        return await runTrackedRemoteCommand(client, `${group}.${String(action || "default").toLowerCase()}`, runtime.analyticsEnabled ?? !runtime.fetchImpl, async () => {
+        return await runTrackedRemoteCommand(client, analyticsCommandName(group, action), runtime.analyticsEnabled ?? !runtime.fetchImpl, async () => {
             if (group === "api") {
                 writeResult(stdout, await runApiCommand(client, action, positionals, parsed.options), parsed.options);
                 return 0;
@@ -156,6 +156,11 @@ async function runTrackedRemoteCommand(client, name, enabled, handler) {
     });
 }
 
+function analyticsCommandName(group, action) {
+    if (group === "api") return `api.${/^(get|post|put|patch|delete)$/i.test(action || "") ? action.toLowerCase() : "get"}`;
+    return `${group}.${String(action || "default").toLowerCase()}`;
+}
+
 export const runCraftboardAgentCli = runGavanaCli;
 
 function exitCodeForResult(group, action, result) {
@@ -504,11 +509,12 @@ async function executeCommand(client, group, action, args, options, runtime) {
     }
 
     if (group === "image" && (action === "generate" || action === "edit" || action === "variations")) {
+        if (options.wait === true && options["no-wait"] === true) throw usageError("--wait and --no-wait cannot be combined.");
         const prepared = await imageInput(client, action, args, options, runtime);
-        const { __destination, ...input } = prepared;
-        const queued = await client.startImage(action, input);
-        const shouldWait = options["no-wait"] !== true;
-        if (!shouldWait) return { ...queued, destination: __destination };
+        const { __destination, __preflight, ...input } = prepared;
+        const queued = __preflight ? await client.preflightImage(action, input) : await client.startImage(action, input);
+        if (__preflight) return { ...queued, destination: __destination };
+        if (options.wait !== true) return { ...queued, destination: __destination };
         const result = await client.waitForRun(queued.run || queued.id, {
             timeoutMs: secondsOption(options.timeout, 15 * 60) * 1000,
             intervalMs: secondsOption(options.interval, 1.5, true) * 1000,
@@ -1196,6 +1202,7 @@ async function imageInput(client, operation, args, options, runtime) {
     const targetNodeIds = supplied.targetNodeIds || repeatableStrings(options.target);
     const singleTarget = supplied.targetNodeId || firstString(options["target-node"]);
     const count = supplied.count !== undefined || options.count !== undefined ? (supplied.count ?? requiredNumber(options.count, "--count must be a number.")) : undefined;
+    const preflight = supplied.preflight === true || options.preflight === true;
     if (count !== undefined && (!Number.isInteger(Number(count)) || Number(count) < 1 || Number(count) > 4)) throw usageError("--count must be an integer between 1 and 4.");
     const referenceInputs = imageReferenceInputs(supplied.references, options.reference, supplied.referenceRoles, options["reference-role"]);
     const optionElements = repeatableStrings(options.element);
@@ -1204,14 +1211,58 @@ async function imageInput(client, operation, args, options, runtime) {
     if (elements.length > 8) throw usageError("An image job can use up to 8 Elements.");
     for (const entry of elements) {
         const typed = entry && typeof entry === "object" && !Array.isArray(entry) ? entry : null;
-        if (typed && Object.keys(typed).some((key) => key !== "handle" && key !== "role" && key !== "influence")) throw usageError('An Element reference may contain only "handle", "role", and "influence".');
+        if (typed && Object.keys(typed).some((key) => !["handle", "role", "influence", "applicationMode", "currentTurnUserModeOverride", "placements"].includes(key))) {
+            throw usageError('An Element reference may contain only "handle", "role", "influence", "applicationMode", "currentTurnUserModeOverride", and "placements".');
+        }
         const handle = typeof entry === "string" ? entry.trim() : typeof typed?.handle === "string" ? typed.handle.trim() : "";
         if (!/^element:[A-Za-z0-9_-]{1,160}@v[1-9][0-9]*$/.test(handle)) throw usageError("Each --element must be a version-pinned element:<id>@v<n> handle.");
         if (typed?.role !== undefined && !["identity", "construction", "texture", "fit", "style"].includes(typed.role)) throw usageError("Element roles must be identity, construction, texture, fit, or style.");
         if (typed?.influence !== undefined && (typeof typed.influence !== "number" || !Number.isFinite(typed.influence) || typed.influence < 0 || typed.influence > 1)) throw usageError("Element influence must be a number from 0 through 1.");
+        if (typed?.applicationMode !== undefined && !["creative", "identity", "exact"].includes(typed.applicationMode)) throw usageError("Element applicationMode must be creative, identity, or exact.");
+        if (typed?.currentTurnUserModeOverride !== undefined && typed.currentTurnUserModeOverride !== true) throw usageError("currentTurnUserModeOverride must be true when supplied.");
+        if (typed?.placements !== undefined) {
+            if (!Array.isArray(typed.placements) || !typed.placements.length || typed.placements.length > 16) throw usageError("Element placements must contain 1 through 16 normalized rectangles.");
+            for (const placement of typed.placements) {
+                if (!placement || typeof placement !== "object" || Array.isArray(placement) || Object.keys(placement).some((key) => !["x", "y", "width", "height"].includes(key))) throw usageError('Each Element placement must contain only "x", "y", "width", and "height".');
+                const { x, y, width, height } = placement;
+                if (![x, y, width, height].every((value) => typeof value === "number" && Number.isFinite(value)) || x < 0 || y < 0 || width <= 0 || height <= 0 || x + width > 1 || y + height > 1) {
+                    throw usageError("Element placements must stay within normalized output bounds.");
+                }
+            }
+        }
     }
     const elementHandles = elements.map((entry) => (typeof entry === "string" ? entry.trim() : entry.handle.trim()));
     if (new Set(elementHandles).size !== elementHandles.length) throw usageError("Element handles must be unique.");
+    const source = supplied.source || firstString(options.source);
+    const prompt = supplied.prompt || firstString(options.prompt);
+    if (preflight) {
+        if (destination === "agent-canvas" || destination === "new-canvas") throw usageError("--preflight requires an existing --destination canvas:<id>; it never creates a Canvas or target node.");
+        const preflightTargets = [...targetNodeIds, ...(singleTarget ? [singleTarget] : [])];
+        if (!preflightTargets.length) throw usageError("--preflight requires one or more explicit --target node:<id> handles.");
+        if (referenceInputs.some((reference) => !/^(?:node:|asset:)/.test(reference.value)) || (source && !/^(?:node:|asset:)/.test(source))) {
+            throw usageError("--preflight accepts only existing node: or asset: references; upload local images first.");
+        }
+        const canvasResult = await client.getCanvas(destination);
+        const references = referenceInputs.map((reference) => ({ handle: reference.value, ...(reference.role ? { role: reference.role } : {}) }));
+        return {
+            canvasId: canvasResult.canvas.handle,
+            baseRevision: supplied.baseRevision || firstString(options["base-revision"]) || canvasResult.canvas.revision,
+            idempotencyKey,
+            targetNodeIds: preflightTargets,
+            ...(prompt ? { prompt } : {}),
+            ...(supplied.promptNodeId || firstString(options["prompt-node"]) ? { promptNodeId: supplied.promptNodeId || firstString(options["prompt-node"]) } : {}),
+            ...(references.length ? { references: references.some((reference) => reference.role) ? references : references.map((reference) => reference.handle) } : {}),
+            ...(elements.length ? { elements } : {}),
+            ...(source ? { source } : {}),
+            ...(supplied.connectionId || firstString(options.connection) ? { connectionId: supplied.connectionId || firstString(options.connection) } : {}),
+            ...(supplied.model || firstString(options.model) ? { model: supplied.model || firstString(options.model) } : {}),
+            ...(supplied.size || firstString(options.size) ? { size: supplied.size || firstString(options.size) } : {}),
+            ...(supplied.quality || firstString(options.quality) ? { quality: supplied.quality || firstString(options.quality) } : {}),
+            count: count ?? preflightTargets.length,
+            __preflight: true,
+            __destination: { requested: String(destination), canvasId: canvasResult.canvas.handle, targetNodeIds: preflightTargets },
+        };
+    }
     const preparedReferences = await prepareReferenceInputs(referenceInputs.map((reference) => reference.value), runtime);
     const canvasResult = await client.resolveCanvasDestination(destination, {
         idempotencyKey,
@@ -1220,8 +1271,6 @@ async function imageInput(client, operation, args, options, runtime) {
     const canvasId = canvasResult.canvas.handle;
     const referenceHandles = await uploadLocalReferenceInputs(client, preparedReferences, canvasId);
     const references = referenceHandles.map((handle, index) => ({ handle, ...(referenceInputs[index]?.role ? { role: referenceInputs[index].role } : {}) }));
-    const source = supplied.source || firstString(options.source);
-    const prompt = supplied.prompt || firstString(options.prompt);
     const preparedDestination = await client.prepareImageDestination({
         canvasResult,
         destination,
@@ -1580,23 +1629,17 @@ function ensureUniqueVideoReferences(references) {
 }
 
 async function uploadLocalReferenceInputs(client, references, canvasReference) {
-    const handles = [];
     const uploads = new Map();
-    for (const reference of references) {
-        if (reference.kind === "handle") {
-            handles.push(reference.handle);
-            continue;
-        }
-        if (reference.kind === "url") {
-            handles.push(reference.url);
-            continue;
-        }
-        const fingerprint = crypto.createHash("sha256").update(reference.bytes).digest("base64url");
-        if (!uploads.has(fingerprint)) uploads.set(fingerprint, client.uploadAsset({ ...reference, canvasReference }));
-        const uploaded = await uploads.get(fingerprint);
-        handles.push(uploaded.asset.handle);
-    }
-    return handles;
+    return Promise.all(
+        references.map(async (reference) => {
+            if (reference.kind === "handle") return reference.handle;
+            if (reference.kind === "url") return reference.url;
+            const fingerprint = crypto.createHash("sha256").update(reference.bytes).digest("base64url");
+            if (!uploads.has(fingerprint)) uploads.set(fingerprint, client.uploadAsset({ ...reference, canvasReference }));
+            const uploaded = await uploads.get(fingerprint);
+            return uploaded.asset.handle;
+        }),
+    );
 }
 
 async function readMacClipboardImage() {
@@ -1938,6 +1981,7 @@ function elementInputFromOptions(options) {
         type: firstString(options.type),
         sourceAssetIds: repeatableStrings(options["source-asset"]),
         ...(firstString(options.guidelines) ? { guidelines: firstString(options.guidelines) } : {}),
+        ...(firstString(options["application-mode"]) ? { applicationMode: firstString(options["application-mode"]) } : {}),
         ...(repeatableStrings(options.collection).length ? { collectionIds: repeatableStrings(options.collection) } : {}),
     };
 }
@@ -2047,12 +2091,14 @@ Global options:
   --connection VALUE       Disambiguate a provider model id by connection
   --reference VALUE        Image reference; repeat for multiple visuals
   --reference-role ROLE    Optional role for the matching --reference: identity, construction, texture, fit, or style
+  --preflight              Compile an image reference plan without starting paid generation
   --input VALUE            Recipe KEY=VALUE or Action input; repeat as needed
   --param NAME=VALUE       Action parameter; repeat for multiple parameters
   --webhook-url URL        Send one signed callback when a Run finishes
   --webhook-secret-env VAR Read the signing secret from VAR (default: GAVANA_WEBHOOK_SECRET)
   --canvas-title VALUE     Title used when --destination is new-canvas
-  --no-wait                Return immediately after queueing Recipe, image, video, or Action work
+  --wait                   Wait for an image Run to finish instead of returning after queueing
+  --no-wait                Return immediately after queueing Recipe, video, or Action work (legacy image alias)
   --progress               Write Run or video Job state transitions to stderr
 
 Video options:
@@ -2074,6 +2120,11 @@ ports treat @path as text; upload a visual first and pass its asset: handle when
 that written port explicitly accepts an image reference. For image generation,
 repeat --reference-role in the same order as --reference to preserve each
 visual's identity, construction, texture, fit, or style role.
+Elements are version-pinned. creative permits visual reinterpretation; identity
+guides preservation but is not pixel-exact. exact Elements use JSON input with
+normalized placements and deterministic original-pixel composition. Use
+--preflight with an existing canvas and explicit --target handles to inspect the
+compiled reference plan before paid generation; it never creates a Canvas or target.
 Image and Action commands create target nodes automatically when --target is omitted.
 
 For history-safe token entry in zsh (macOS):

package/src/tools/definitions.mjs

@@ -26,6 +26,7 @@ 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 { defineRunList } from "./run_list.mjs";
 import { defineCanvasGet } from "./canvas_get.mjs";
 import { defineCanvasList } from "./canvas_list.mjs";
 import { defineCanvasValidate } from "./canvas_validate.mjs";
@@ -91,6 +92,7 @@ export const GAVANA_TOOL_DEFINITIONS = Object.freeze({
     campaign_start: defineCampaignStart,
     canvas_apply_batch: defineCanvasApplyBatch,
     canvas_create: defineCanvasCreate,
+    run_list: defineRunList,
     canvas_get: defineCanvasGet,
     canvas_list: defineCanvasList,
     canvas_validate: defineCanvasValidate,

package/src/tools/element_create.mjs

@@ -3,7 +3,7 @@ import { elementInput } from "./schemas.mjs";
 export function defineElementCreate(client) {
     return {
         title: "Create a Gavana Element",
-        description: "Create a reusable visual Element from 1-8 existing image assets, guidelines, or both.",
+        description: "Create a reusable visual Element. creative Elements inspire, identity Elements guide recognizable subjects, and exact Elements require one PNG source for deterministic composition.",
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         inputSchema: elementInput,
         handler: (input) => client.createElement(input),

package/src/tools/element_update.mjs

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { elementType, mutableElementReference, assetReference } from "./schemas.mjs";
+import { elementApplicationMode, elementType, mutableElementReference, assetReference } from "./schemas.mjs";
 
 export function defineElementUpdate(client) {
     return {
@@ -13,6 +13,7 @@ export function defineElementUpdate(client) {
                 type: elementType,
                 sourceAssetIds: z.array(assetReference).max(8).default([]),
                 guidelines: z.string().max(2_000).optional(),
+                applicationMode: elementApplicationMode.optional(),
             })
             .strict()
             .refine((value) => value.sourceAssetIds.length > 0 || Boolean(value.guidelines?.trim()), "Add at least one source asset or guideline."),

package/src/tools/guide_get.mjs

@@ -11,6 +11,6 @@ export function defineGuideGet(client) {
        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),
+       handler: ({ guideId }) => getCanvasGuide(guideId, "local"),
     };
 }

package/src/tools/guide_search.mjs

@@ -11,6 +11,6 @@ export function defineGuideSearch(client) {
        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),
+       handler: ({ query, limit }) => searchCanvasGuides(query, limit, "local"),
     };
 }

package/src/tools/image_tool.mjs

@@ -11,16 +11,21 @@ export function imageToolDefinition(operation, client) {
             title: `${operation === "generate" ? "Generate" : operation === "edit" ? "Edit" : "Vary"} canvas images`,
             description:
                 operation === "generate"
-                    ? "Queue image generation into existing target image nodes. Campaign work needs a visible reference-led concept before output; reuse existing Canvas node:/asset: handles for product identity, brand-world, and typography/layout references. For an exact product, logo, face, garment, or other visual identity, do not rely on prompt-only generation: use a user-provided local image (or an existing node:/asset: handle), then call image_edit with references."
+                    ? "Queue image generation into existing target image nodes. Campaign work needs a visible reference-led concept before output; reuse existing Canvas node:/asset: handles for product identity, brand-world, and typography/layout references. identity Elements guide preservation but do not guarantee identical pixels. exact Elements require normalized placements and are deterministically composited from original source pixels. Set preflight true to inspect the compiled reference plan before paid generation. For several images set count (1-4): Gavana writes one image node per output. Never describe multiple panels, frames, or a collage in one prompt, and when you pass targetNodeIds pass exactly one target node per output."
                     : operation === "edit"
-                      ? "Queue an image edit using stable node: or asset: references. Reuse a Canvas image by its existing handle rather than re-uploading it. Use this for exact product or visual identity work; call asset_upload first only when the user supplied a local image."
-                      : "Queue variations using an existing node: or asset: source.",
+                      ? "Queue an image edit using stable node: or asset: references. Reuse a Canvas image by its existing handle rather than re-uploading it. For a local image the user explicitly supplied, call asset_upload first. identity guidance is not pixel-exact; use an exact Element with placements for deterministic logo or wordmark composition. Set preflight true to inspect the compiled reference plan before paid generation. For several images set count (1-4): Gavana writes one image node per output. Never describe multiple panels, frames, or a collage in one prompt, and when you pass targetNodeIds pass exactly one target node per output."
+                      : "Queue variations using an existing node: or asset: source. For several images set count (1-4): Gavana writes one image node per output. Never describe multiple panels, frames, or a collage in one prompt, and when you pass targetNodeIds pass exactly one target node per output.",
             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;
+                if (input.preflight === true) {
+                    const { destination: _destination, canvasId: _canvasId, canvasTitle: _canvasTitle, preflight: _preflight, wait: _wait, timeoutSeconds: _timeoutSeconds, ...preflightInput } = input;
+                    const plan = await client.preflightImage(operation, { ...preflightInput, canvasId: destination });
+                    return { ...plan, destination: { requested: destination, canvasId: destination, targetNodeIds: input.targetNodeIds } };
+                }
                 const prepared = await client.prepareImageDestination({
                     ...input,
                     operation,
@@ -36,6 +41,7 @@ export function imageToolDefinition(operation, client) {
                     targetY: _targetY,
                     targetWidth: _targetWidth,
                     targetHeight: _targetHeight,
+                    preflight: _preflight,
                     wait: _wait,
                     timeoutSeconds: _timeoutSeconds,
                     ...jobInput
@@ -48,7 +54,7 @@ export function imageToolDefinition(operation, client) {
                     idempotencyKey: input.idempotencyKey,
                 });
                 const destinationResult = { requested: destination, canvasId: prepared.canvasId, targetNodeIds: prepared.targetNodeIds };
-                if (input.wait === false) return { ...queued, destination: destinationResult };
+                if (input.wait !== true) 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/registry.mjs

@@ -144,7 +144,11 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
     {
         name: "canvas_create",
         toolset: "canvas",
-        surfaces: ["local"],
+        surfaces: ["hosted","local"],
+        scopes: ["canvas:read","canvas:write"],
+        hostedOrder: 6,
+        hostedReadOnly: false,
+        hostedToolset: "canvas",
         localOrder: 15,
         annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false},
     },
@@ -260,6 +264,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         scopes: ["canvas:read","job:manage"],
         hostedOrder: 12,
         hostedReadOnly: false,
+        hostedCategory: "read",
         hostedToolset: "runs",
         embedImage: true,
         annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
@@ -284,7 +289,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 17,
+        hostedOrder: 18,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 48,
@@ -296,7 +301,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 18,
+        hostedOrder: 19,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 50,
@@ -307,7 +312,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 19,
+        hostedOrder: 20,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 53,
@@ -320,7 +325,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted","local"],
         scopes: ["element:read"],
         readOnlySurface: true,
-        hostedOrder: 20,
+        hostedOrder: 21,
         hostedReadOnly: true,
         hostedToolset: "elements",
         localOrder: 49,
@@ -331,7 +336,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 21,
+        hostedOrder: 22,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 52,
@@ -342,7 +347,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 22,
+        hostedOrder: 23,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 45,
@@ -354,7 +359,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted","local"],
         scopes: ["element:read"],
         readOnlySurface: true,
-        hostedOrder: 23,
+        hostedOrder: 24,
         hostedReadOnly: true,
         hostedToolset: "elements",
         localOrder: 43,
@@ -366,7 +371,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted","local"],
         scopes: ["element:read"],
         readOnlySurface: true,
-        hostedOrder: 24,
+        hostedOrder: 25,
         hostedReadOnly: true,
         hostedToolset: "elements",
         localOrder: 44,
@@ -378,7 +383,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted","local"],
         scopes: ["element:read"],
         readOnlySurface: true,
-        hostedOrder: 25,
+        hostedOrder: 26,
         hostedReadOnly: true,
         hostedToolset: "elements",
         localOrder: 42,
@@ -389,7 +394,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 26,
+        hostedOrder: 27,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 47,
@@ -400,7 +405,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 27,
+        hostedOrder: 28,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 46,
@@ -411,7 +416,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 28,
+        hostedOrder: 29,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 51,
@@ -455,7 +460,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         hostedAlias: "generate_image_in_canvas",
         scopes: ["canvas:read","canvas:write","asset:read","image:generate","job:manage"],
         conditionalScopes: { elements: ["element:read"] },
-        hostedOrder: 13,
+        hostedOrder: 14,
         paid: true,
         hostedReadOnly: false,
         hostedToolset: "images",
@@ -551,6 +556,18 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         localOrder: 20,
         annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
     },
+    {
+        name: "product_photoshoot_generate",
+        toolset: "images",
+        surfaces: ["hosted"],
+        hostedAlias: "generate_product_photoshoot_in_canvas",
+        scopes: ["canvas:read","canvas:write","asset:read","image:generate","job:manage"],
+        hostedOrder: 13,
+        paid: true,
+        hostedReadOnly: false,
+        hostedToolset: "images",
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
     {
         name: "product_reference_pack_import",
         toolset: "assets",
@@ -611,10 +628,30 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
     {
         name: "run_get",
         toolset: "runs",
-        surfaces: ["local"],
+        surfaces: ["hosted","local"],
+        hostedAlias: "get_image_run",
+        scopes: ["job:manage"],
+        embedImage: true,
+        hostedOrder: 35,
+        hostedReadOnly: false,
+        hostedCategory: "read",
+        hostedToolset: "runs",
         localOrder: 42,
         annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
     },
+    {
+        name: "run_list",
+        toolset: "jobs",
+        surfaces: ["hosted","local"],
+        scopes: ["job:manage"],
+        hostedAlias: "list_image_runs",
+        hostedOrder: 36,
+        hostedReadOnly: false,
+        hostedToolset: "jobs",
+        localOrder: 41,
+        readOnlySurface: true,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
     {
         name: "run_wait",
         toolset: "runs",
@@ -627,8 +664,8 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "videos",
         surfaces: ["hosted","local"],
         hostedAlias: "generate_video",
-        scopes: ["canvas:read","asset:read","video:generate","job:manage"],
-        hostedOrder: 15,
+        scopes: ["canvas:read","canvas:write","asset:read","video:generate","job:manage"],
+        hostedOrder: 16,
         paid: true,
         hostedReadOnly: false,
         hostedToolset: "videos",
@@ -641,8 +678,9 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted"],
         hostedAlias: "get_video_job",
         scopes: ["job:manage"],
-        hostedOrder: 16,
+        hostedOrder: 17,
         hostedReadOnly: false,
+        hostedCategory: "read",
         hostedToolset: "runs",
         annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
     },
@@ -652,8 +690,8 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted"],
         hostedAlias: "find_video_models",
         scopes: ["video:generate"],
-        hostedOrder: 14,
-        hostedReadOnly: true,
+        hostedOrder: 15,
+        hostedReadOnly: false,
         hostedToolset: "models",
         annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
     },
@@ -662,7 +700,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "canvas",
         surfaces: ["hosted","local"],
         scopes: ["canvas:read","canvas:write"],
-        hostedOrder: 31,
+        hostedOrder: 32,
         hostedReadOnly: false,
         hostedToolset: "canvas",
         localOrder: 56,
@@ -674,7 +712,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "canvas",
         surfaces: ["hosted","local"],
         scopes: ["canvas:read","canvas:write","asset:read","image:generate"],
-        hostedOrder: 32,
+        hostedOrder: 33,
         paid: true,
         hostedReadOnly: false,
         hostedToolset: "canvas",
@@ -688,7 +726,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted","local"],
         scopes: ["canvas:read"],
         readOnlySurface: true,
-        hostedOrder: 30,
+        hostedOrder: 31,
         hostedReadOnly: true,
         hostedToolset: "canvas",
         localOrder: 55,
@@ -700,7 +738,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "canvas",
         surfaces: ["hosted","local"],
         scopes: ["canvas:read","canvas:write","asset:read"],
-        hostedOrder: 29,
+        hostedOrder: 30,
         hostedReadOnly: false,
         hostedToolset: "canvas",
         localOrder: 54,
@@ -712,7 +750,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "canvas",
         surfaces: ["hosted","local"],
         scopes: ["canvas:read","canvas:write","image:generate"],
-        hostedOrder: 33,
+        hostedOrder: 34,
         hostedReadOnly: false,
         hostedToolset: "canvas",
         localOrder: 58,
@@ -744,8 +782,16 @@ export function gavanaToolsForSurface(surface, { includeLegacyCampaign = false,
     // each surface keeps the order it shipped with rather than falling out of the
     // registry's alphabetical layout.
     const key = surface === "hosted" ? "hostedOrder" : "localOrder";
+    // The two read-only flags are not the same question, and `run_list` is the
+    // first tool where they part. Local read-only serves whatever declares
+    // `readOnlyHint`, so a tool that only reads belongs there. Hosted read-only
+    // additionally has to grant the tool's OAuth scopes out of a read-only set
+    // that does not contain `job:manage`, so the same tool cannot be served
+    // there at all. Filtering both surfaces through the local flag advertised a
+    // hosted tool the hosted server would never serve.
+    const readOnlyKey = surface === "hosted" ? "hostedReadOnly" : "readOnlySurface";
     return GAVANA_TOOL_REGISTRY.filter(
-        (tool) => tool.surfaces.includes(surface) && (includeLegacyCampaign || !tool.legacyCampaign) && (!readOnly || tool.readOnlySurface),
+        (tool) => tool.surfaces.includes(surface) && (includeLegacyCampaign || !tool.legacyCampaign) && (!readOnly || tool[readOnlyKey]),
     )
         .slice()
         .sort((left, right) => (left[key] ?? 0) - (right[key] ?? 0));

package/src/tools/run_list.mjs

@@ -0,0 +1,20 @@
+// Tool definition: run_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";
+
+export function defineRunList(client) {
+    return {
+        title: "List Gavana image runs",
+        description:
+            "List image and Action runs this account has started, newest first, with their status and canvas. Use this to answer questions about work already in flight, to recover a run handle you no longer have, and to see which runs are holding the concurrent-job limit.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({
+            status: z.enum(["active", "all"]).default("active").describe("active returns only runs still queued or running; all includes finished and failed runs."),
+            canvasId: z.string().min(1).max(240).optional().describe("Restrict to runs targeting one canvas."),
+            limit: z.number().int().min(1).max(50).default(20),
+        }),
+        handler: (input) => client.listRuns(input),
+    };
+}