@gavana.ai/cli 0.2.1 → 0.3.0

package/src/tools/schemas.mjs

@@ -26,13 +26,17 @@ const elementCollectionReference = z
     .string()
     .regex(/^element-collection:[A-Za-z0-9_-]{1,180}$/)
     .describe("Stable Element collection handle element-collection:<id>.");
-const elementType = z.enum(["character", "product/object", "environment", "style", "material/texture", "lighting"]);
+const elementType = z.enum(["character", "product/object", "environment", "style", "material/texture", "lighting", "brand/mark"]);
+const elementApplicationMode = z
+    .enum(["creative", "identity", "exact"])
+    .describe("creative permits visual reinterpretation; identity guides preservation but is not pixel-exact; exact composites original Element pixels after generation.");
 const elementInput = z
     .object({
         name: z.string().min(1).max(160),
         type: elementType,
         sourceAssetIds: z.array(assetReference).max(8).default([]),
         guidelines: z.string().max(2_000).optional(),
+        applicationMode: elementApplicationMode.optional().describe("creative uses an Element as inspiration; identity guides recognizable subjects; exact preserves an original PNG through deterministic composition."),
         collectionIds: z.array(elementCollectionReference).max(24).optional(),
     })
     .strict()
@@ -119,6 +123,15 @@ const approvedOutputReferences = z
 const campaignIdempotencyKey = z.string().min(8).max(200).describe("Required caller-stable retry key. Reuse it only for the exact same campaign action.");
 const recipeForkIdempotencyKey = z.string().min(8).max(200).describe("Required caller-stable retry key. Reuse it only for the exact same Recipe fork.");
 const campaignAspectRatio = z.enum(["1:1", "4:5", "3:4", "16:9", "9:16"]);
+const exactElementPlacement = z
+    .object({
+        x: z.number().min(0).max(1).describe("Normalized left coordinate in the output, from 0 through 1."),
+        y: z.number().min(0).max(1).describe("Normalized top coordinate in the output, from 0 through 1."),
+        width: z.number().gt(0).max(1).describe("Normalized width in the output, greater than 0 through 1."),
+        height: z.number().gt(0).max(1).describe("Normalized height in the output, greater than 0 through 1."),
+    })
+    .strict()
+    .refine((placement) => placement.x + placement.width <= 1 && placement.y + placement.height <= 1, "Exact Element placement must remain inside the normalized output bounds.");
 const elementGenerationInput = z
     .union([
         pinnedElementReference,
@@ -127,10 +140,16 @@ const elementGenerationInput = z
                 handle: pinnedElementReference,
                 role: z.enum(["identity", "construction", "texture", "fit", "style"]).optional(),
                 influence: z.number().min(0).max(1).optional(),
+                applicationMode: elementApplicationMode.optional(),
+                currentTurnUserModeOverride: z
+                    .literal(true)
+                    .optional()
+                    .describe("Required only when the current user explicitly asks to override this Element version's stored application mode."),
+                placements: z.array(exactElementPlacement).min(1).max(16).optional().describe("Required for exact Elements. Repeat placements to composite unchanged source pixels more than once."),
             })
             .strict(),
     ])
-    .describe("A version-pinned Element, optionally with the visual role and influence to apply.");
+    .describe("A version-pinned Element. identity is guided preservation, not pixel-exact. exact requires placements and returns exact-composed only when original Element pixels are deterministically composited.");
 const MAX_LOCAL_REFERENCE_IMAGE_BYTES = 50 * 1024 * 1024;
 const revisionFields = {
     baseRevision: z.string().min(1).optional().describe("Revision returned by canvas_get. Omit to read the latest revision immediately before the write."),
@@ -165,8 +184,17 @@ function imageSchema() {
         model: z.union([modelReference, rawModelId]).optional(),
         size: z.string().max(80).optional(),
         quality: z.string().max(80).optional(),
-        count: z.number().int().min(1).max(4).optional(),
-        wait: z.boolean().default(true),
+        count: z
+            .number()
+            .int()
+            .min(1)
+            .max(4)
+            .optional()
+            .describe(
+                "Number of separate images to generate, 1-4. Gavana creates one image node per output, and this is the only way to produce more than one image. Never ask for several panels, frames, or a collage inside one prompt. When you pass targetNodeIds, count must equal the number of targetNodeIds; when you omit count, Gavana uses the number of targets.",
+            ),
+        preflight: z.boolean().optional().describe("Compile and validate the final reference plan without creating targets, starting a provider request, or consuming generation credits. Requires an existing canvas and explicit targetNodeIds."),
+        wait: z.boolean().default(false).describe("Return after queueing by default. Set true to wait for the completed Run."),
         timeoutSeconds: z.number().min(1).max(3_600).default(900),
     });
 }
@@ -182,6 +210,11 @@ function validateImageInput(operation, value) {
     // the job, and the blank node would be left behind as an orphan.
     if (operation !== "variations" && !value.prompt && !value.promptNodeId && !value.targetNodeIds?.length) issues.push("Provide prompt or promptNodeId, or pass targetNodeIds whose nodes have a prompt connection.");
     if (operation !== "generate" && !value.source && !value.references?.length) issues.push(`${operation} requires source or references.`);
+    if (value.preflight) {
+        const destination = value.destination || value.canvasId;
+        if (destination === "agent-canvas" || destination === "new-canvas") issues.push("preflight requires an existing canvas handle, not agent-canvas or new-canvas.");
+        if (!value.targetNodeIds?.length) issues.push("preflight requires explicit targetNodeIds; it never creates target nodes.");
+    }
     if (!issues.length) return;
     const error = new Error(`Input validation error: ${issues.join(" ")}`);
     error.code = "invalid_image_input";
@@ -195,6 +228,7 @@ export {
     assetReference,
     elementCollectionReference,
     elementGenerationInput,
+    elementApplicationMode,
     elementInput,
     elementType,
     campaignAspectRatio,

package/src/tools/surface-names.mjs

@@ -0,0 +1,120 @@
+// Tool vocabulary per surface.
+//
+// The hosted and local servers advertise different catalogs under different
+// naming conventions (see ./registry.mjs). The Canvas Agent Guide is shared
+// prose, so a sentence written in one surface's vocabulary reaches agents on
+// the other surface naming a tool they cannot call. That is not a hypothetical:
+// the guide told every agent to "call `model_list` before image or video
+// generation", and `model_list` is local-only, so hosted agents either guessed
+// a substitute or gave up on a mandatory pre-flight step.
+//
+// This module is the one place that answers "what is this tool called here, and
+// does it exist here at all". scripts/canvas-agent-guide.test.mjs asserts that
+// no served guide text names a tool the reading surface cannot call, so the
+// drift fails the build instead of reaching an agent.
+
+import { GAVANA_TOOL_REGISTRY } from "./registry.mjs";
+
+export const GAVANA_TOOL_SURFACES = Object.freeze(["hosted", "local"]);
+
+/** Name a surface advertises for one registry entry, or undefined when it does not advertise it. */
+function advertisedNameFor(tool, surface) {
+    if (!tool.surfaces.includes(surface)) return undefined;
+    return surface === "hosted" ? (tool.hostedAlias ?? tool.name) : tool.name;
+}
+
+/**
+ * Every spelling of every tool, mapped to what `surface` calls it.
+ *
+ * `rename` covers both directions: a canonical name written in the guide maps to
+ * the hosted alias when hosted advertises it, and a hosted alias maps back to the
+ * canonical name for the local surface. `absent` holds tools no spelling of which
+ * the surface can call.
+ */
+export function surfaceToolVocabulary(surface) {
+    if (!GAVANA_TOOL_SURFACES.includes(surface)) {
+        throw new Error(`Unknown tool surface: ${surface}. Expected one of ${GAVANA_TOOL_SURFACES.join(", ")}.`);
+    }
+    const advertised = new Set();
+    const rename = new Map();
+    const absent = new Set();
+
+    for (const tool of GAVANA_TOOL_REGISTRY) {
+        const spellings = [tool.name, tool.hostedAlias].filter(Boolean);
+        const here = advertisedNameFor(tool, surface);
+        if (!here) {
+            for (const spelling of spellings) absent.add(spelling);
+            continue;
+        }
+        advertised.add(here);
+        for (const spelling of spellings) {
+            if (spelling !== here) rename.set(spelling, here);
+        }
+    }
+
+    // A spelling this surface advertises is never "absent", even when another
+    // registry entry shares the word. Advertised always wins.
+    for (const name of advertised) absent.delete(name);
+    for (const spelling of rename.keys()) absent.delete(spelling);
+
+    return { surface, advertised, rename, absent };
+}
+
+const VOCABULARIES = new Map(GAVANA_TOOL_SURFACES.map((surface) => [surface, surfaceToolVocabulary(surface)]));
+
+/** Cached vocabulary. Callers must not mutate the returned sets. */
+export function toolVocabulary(surface) {
+    const vocabulary = VOCABULARIES.get(surface);
+    if (!vocabulary) throw new Error(`Unknown tool surface: ${surface}. Expected one of ${GAVANA_TOOL_SURFACES.join(", ")}.`);
+    return vocabulary;
+}
+
+// Word boundary that keeps `run_get` from matching inside `canvas_workflow_run_get`.
+const identifier = (name) => new RegExp(`(?<![A-Za-z0-9_])${name}(?![A-Za-z0-9_])`, "g");
+
+const CONDITIONAL = /\{\{#(hosted|local)\}\}([\s\S]*?)\{\{\/\1\}\}/g;
+
+/**
+ * Resolve `{{#hosted}}…{{/hosted}}` / `{{#local}}…{{/local}}` spans for one surface.
+ *
+ * Guide prose uses these where the two surfaces genuinely differ in capability
+ * rather than only in spelling — an instruction that cannot be satisfied at all
+ * on one surface must not merely be renamed there.
+ */
+export function resolveSurfaceConditionals(text, surface) {
+    return String(text ?? "").replace(CONDITIONAL, (_match, branch, body) => (branch === surface ? body : ""));
+}
+
+/** Rewrite every tool name in `text` to the spelling `surface` advertises. */
+export function renameToolsForSurface(text, surface) {
+    const { rename } = toolVocabulary(surface);
+    let output = String(text ?? "");
+    for (const [from, to] of rename) output = output.replace(identifier(from), to);
+    return output;
+}
+
+/**
+ * Guide prose as one surface should read it: conditionals resolved, then names
+ * translated. Order matters — a conditional branch may name a tool that only
+ * exists on its own surface, so the other branch must be dropped before renaming.
+ */
+export function renderForSurface(text, surface) {
+    return renameToolsForSurface(resolveSurfaceConditionals(text, surface), surface);
+}
+
+/**
+ * Tool names `text` mentions that `surface` cannot call. Empty is the contract.
+ *
+ * Only registry-known spellings count, so ordinary prose is never flagged. Call
+ * this on already-rendered text: an unresolved conditional would report its
+ * other branch as a violation.
+ */
+export function unavailableToolMentions(text, surface) {
+    const { absent } = toolVocabulary(surface);
+    const value = String(text ?? "");
+    const found = new Set();
+    for (const name of absent) {
+        if (identifier(name).test(value)) found.add(name);
+    }
+    return Array.from(found).sort();
+}

package/src/version.mjs

@@ -7,4 +7,4 @@
 //
 // scripts/gavana-mcp-tool-contract.test.mjs asserts this equals
 // packages/cli/package.json, so the two cannot drift.
-export const GAVANA_CLI_VERSION = "0.2.1";
+export const GAVANA_CLI_VERSION = "0.3.0";