@gavana.ai/cli 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog — @gavana.ai/cli
 
+## 0.2.2
+
+### Changed
+
+- Image commands and MCP tools now return immediately after the durable Canvas
+  targets and Run are queued. Use `--wait` in the CLI or `wait: true` in an MCP
+  call when the completed image is required in the same interaction.
+- Distinct local image references upload concurrently while their original
+  reference order and duplicate-upload reuse remain stable.
+
 ## 0.2.1
 
 ### Fixed

package/README.md

@@ -114,6 +114,7 @@ gavana action list
 gavana action get action:resize
 gavana action run action:resize --input ./product.png --destination agent-canvas --width 1080 --height 1350
 gavana image generate --destination agent-canvas --model model:OPAQUE_MODEL_KEY --prompt "A studio product photograph"
+gavana image generate --destination agent-canvas --prompt "A studio product photograph" --wait
 gavana model list --capability video.generate
 gavana video generate --model model:OPAQUE_MODEL_KEY --prompt "A slow product turntable" --duration 15 --aspect-ratio 9:16 --download ./turntable.mp4
 gavana video generate --model model:OPAQUE_MODEL_KEY --prompt "Animate the fabric naturally" --first-frame ./product.png --no-wait
@@ -179,8 +180,13 @@ text-only Recipes.
 
 Recipe, image, and Action work returns a shared `run:` handle with typed outputs,
 duration estimates, observed queue/execution timing, and stable retry guidance.
-Default waiting and `run get|wait|cancel` require `job:manage`; a start-only
-token can use `--no-wait` with a signed webhook.
+Image commands return as soon as Gavana has created the durable Canvas targets
+and queued the Run, so the caller can continue while generation proceeds. Add
+`--wait` only when the completed image is needed in the same command. `--no-wait`
+remains accepted for existing image scripts. Recipe and Action commands retain
+their existing wait-by-default behavior. Waiting and `run get|wait|cancel`
+require `job:manage`; a start-only token can queue image work directly or use
+`--no-wait` with a signed webhook.
 The legacy `job:` handle remains an image and Action compatibility alias; it is
 never used for Recipes. Image and Action `run:` and `job:` handles point to the
 same temporary record and expire together:

package/guides/generated-assets.md

@@ -25,7 +25,7 @@ order: 6
 
 ## Paid execution
 
-Generation is allowed only after explicit current-turn user intent. Start one run with one caller-stable idempotency key. Poll the returned Run or Job; do not start another run while waiting. A terminal failure must be reported without automatic retry.
+Generation is allowed only after explicit current-turn user intent. Start one run with one caller-stable idempotency key. Image tools return durable queued progress by default; report that progress immediately and do not automatically call `run_wait`. Call `run_wait` only when the current user explicitly needs the completed asset in this same interaction. Otherwise, a later `run_get` or Canvas read can observe progress and the durable output. Do not start another run while one is pending. A terminal failure must be reported without automatic retry.
 
 ## Completion
 

package/guides/paid-action-safety.md

@@ -15,7 +15,7 @@ Start paid work only when the current user message explicitly asks to run or gen
 ## Retry boundary
 
 - Use one stable idempotency key for one intended paid operation.
-- Poll the returned handle with status tools.
+- Return an image Run's durable queued progress immediately. Do not call `run_wait` unless the current user explicitly needs the completed asset in this same interaction; otherwise observe it later with `run_get` or a Canvas read.
 - Never automatically retry a terminal failure, timeout, disconnect, or ambiguous provider response with a new key.
 - Ask for new user intent before any new paid attempt.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gavana.ai/cli",
-    "version": "0.2.1",
+    "version": "0.2.2",
     "description": "JSON-first command-line client for the Gavana Canvas API",
     "type": "module",
     "bin": {

package/src/canvas-agent-guide.mjs

@@ -4,10 +4,10 @@
 // ./canvas-agent-validation.mjs in guide version 1.5.0.
 import { GAVANA_CANVAS_GUIDE_SOURCES } from "./guide-sources.mjs";
 
-export const GAVANA_CANVAS_GUIDE_VERSION = "1.5.0";
+export const GAVANA_CANVAS_GUIDE_VERSION = "1.5.1";
 export const GAVANA_CANVAS_GUIDE_INDEX_URI = `gavana://guides/canvas/v${GAVANA_CANVAS_GUIDE_VERSION.split(".")[0]}/index`;
 export const GAVANA_CANVAS_GUIDE_WORKFLOW_INSTRUCTION =
-    "For the first canvas task in a session, and before any unfamiliar canvas operation, inspect the relevant guide through MCP resources or call guide_search then guide_get. Before changing an existing canvas, call canvas_get. For spatial, multi-node, or destructive work, call canvas_validate with the proposed operations, apply one revision-safe atomic batch, then call canvas_validate again. Campaign work must read creative-canvas and use a reference-led concept before image output. Before image or video generation, call model_list for the required capability and use its exact model: handle; a bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access the connection instead of asking the user to add a key again. When a standalone image fallback uses visual references, forward every exact node:/asset: handle (and each known role) in the image request; never reduce that work to a prompt-only generation. After an image or workflow finishes, read completionReview. Never claim Done while completionReview.doneClaimAllowed is false, delivery is pending, failed, or non-durable, or blocking findings remain. Render campaign compositions for visual inspection. Treat legacy warnings as review items, not permission to rewrite unrelated work.";
+    "For the first canvas task in a session, and before any unfamiliar canvas operation, inspect the relevant guide through MCP resources or call guide_search then guide_get. Before changing an existing canvas, call canvas_get. For spatial, multi-node, or destructive work, call canvas_validate with the proposed operations, apply one revision-safe atomic batch, then call canvas_validate again. Campaign work must read creative-canvas and use a reference-led concept before image output. Before image or video generation, call model_list for the required capability and use its exact model: handle; a bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access the connection instead of asking the user to add a key again. When a standalone image fallback uses visual references, forward every exact node:/asset: handle (and each known role) in the image request; never reduce that work to a prompt-only generation. Image tools return durable queued progress by default; report it immediately and call run_wait only when the current user explicitly needs the completed asset in the same interaction. A later run_get or Canvas read can observe progress. After an image or workflow finishes, read completionReview. Never claim Done while completionReview.doneClaimAllowed is false, delivery is pending, failed, or non-durable, or blocking findings remain. Render campaign compositions for visual inspection. Treat legacy warnings as review items, not permission to rewrite unrelated work.";
 export const GAVANA_CANVAS_GUIDE_READ_ONLY_INSTRUCTION =
     "For the first canvas task in a session, and before any unfamiliar canvas review, inspect the relevant guide through MCP resources or call guide_search then guide_get. Call canvas_get before reasoning about an existing canvas, and use canvas_validate to audit its current graph. Treat validation warnings as review items and never claim to mutate the canvas.";
 

package/src/commands.mjs

@@ -144,9 +144,9 @@ export const GAVANA_CLI_COMMANDS = Object.freeze([
             "gavana action run action:side-by-side-composite --input node:<id> --input asset:<id> --destination canvas:<id>",
         ],
     },
-    { group: "image", action: "generate", usage: ["gavana image generate --destination agent-canvas --prompt \"...\" [--element element:<id>@v<n>]"] },
-    { group: "image", action: "edit", usage: ["gavana image edit --destination canvas:<id> --reference path/to/image.png --prompt \"...\""] },
-    { group: "image", action: "variations", usage: ["gavana image variations --destination new-canvas --canvas-title \"Variations\" --reference path/to/source.png --prompt \"...\""] },
+    { group: "image", action: "generate", usage: ["gavana image generate --destination agent-canvas --prompt \"...\" [--element element:<id>@v<n>] [--wait]"] },
+    { group: "image", action: "edit", usage: ["gavana image edit --destination canvas:<id> --reference path/to/image.png --prompt \"...\" [--wait]"] },
+    { group: "image", action: "variations", usage: ["gavana image variations --destination new-canvas --canvas-title \"Variations\" --reference path/to/source.png --prompt \"...\" [--wait]"] },
     { group: "video", action: "generate", usage: ["gavana video generate --model model:<id> --prompt \"...\" --duration 15", "gavana video generate --model model:<id> --prompt \"...\" --first-frame path/to/start.png --no-wait", "gavana video generate --model model:<id> --prompt \"...\" --download output.mp4"] },
     { group: "video", action: "download", usage: ["gavana video download job:<id> --file output.mp4 [--yes]"] },
     { group: "job", action: "get", usage: ["gavana job get job:<id>"] },

package/src/guide-sources.mjs

@@ -49,7 +49,7 @@ export const GAVANA_CANVAS_GUIDE_SOURCES = Object.freeze([
         description: "Prepare media nodes, start only explicit generation, and preserve output lineage.",
         keywords: Object.freeze(["generated","generation","image","video","output","asset","durable","lineage","placeholder","job"]),
         order: 6,
-        markdown: "\n## Before generation\n\n- Read the destination canvas and relevant source nodes.\n- Use exact source `node:` or `asset:` handles.\n- Before image or video generation, call `model_list` for the required capability and pass its exact `model:` handle. A bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access that connection; do not ask the user to add a key again.\n- For a standalone image request, pass every visual source in `references`.\n  Use `{ \"handle\": \"node:...\", \"role\": \"identity\" }` when its\n  responsibility is known; valid roles are `identity`, `construction`,\n  `texture`, `fit`, and `style`. Do not flatten multi-reference work\n  into prompt prose or omit a source during fallback.\n- Reuse existing Canvas `node:` or `asset:` handles directly. Do not download\n  and re-upload a generated Canvas image merely to use it as the next\n  generation's reference. State whether a style reference establishes the\n  brand-world or typography/layout direction in the prompt.\n- Create an empty image or video target only through supported operations. Do not write media bytes, storage keys, or arbitrary output URLs into metadata.\n- Connect prompts, products, references, Lists, and frame inputs to their target with the correct direction and mode.\n\n## Paid execution\n\nGeneration is allowed only after explicit current-turn user intent. Start one run with one caller-stable idempotency key. Poll the returned Run or Job; do not start another run while waiting. A terminal failure must be reported without automatic retry.\n\n## Completion\n\nDo not claim a generated image is durable until the result returns a target `node:`, durable `asset:`, and the final canvas read shows server-owned media fields. A video Job may return a protected download without materializing a native video node; report exactly what the server returned and do not invent durability.\n\nKeep generated output spatially near its input stage and connected to its source, prompt, List, or workflow. After finalization, run `canvas_validate` and read `completionReview`: it reports overlap, full-frame Section containment, reference lineage, and delivery state. Do not claim Done while it says `doneClaimAllowed: false`, including when delivery is pending, failed, or non-durable. Render the Canvas for visual inspection when the request includes a campaign, poster, banner, or multi-direction composition. Reference provenance is not a user workflow state and never requires a Keep action. Never create another paid provider call automatically.\n",
+        markdown: "\n## Before generation\n\n- Read the destination canvas and relevant source nodes.\n- Use exact source `node:` or `asset:` handles.\n- Before image or video generation, call `model_list` for the required capability and pass its exact `model:` handle. A bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access that connection; do not ask the user to add a key again.\n- For a standalone image request, pass every visual source in `references`.\n  Use `{ \"handle\": \"node:...\", \"role\": \"identity\" }` when its\n  responsibility is known; valid roles are `identity`, `construction`,\n  `texture`, `fit`, and `style`. Do not flatten multi-reference work\n  into prompt prose or omit a source during fallback.\n- Reuse existing Canvas `node:` or `asset:` handles directly. Do not download\n  and re-upload a generated Canvas image merely to use it as the next\n  generation's reference. State whether a style reference establishes the\n  brand-world or typography/layout direction in the prompt.\n- Create an empty image or video target only through supported operations. Do not write media bytes, storage keys, or arbitrary output URLs into metadata.\n- Connect prompts, products, references, Lists, and frame inputs to their target with the correct direction and mode.\n\n## Paid execution\n\nGeneration is allowed only after explicit current-turn user intent. Start one run with one caller-stable idempotency key. Image tools return durable queued progress by default; report that progress immediately and do not automatically call `run_wait`. Call `run_wait` only when the current user explicitly needs the completed asset in this same interaction. Otherwise, a later `run_get` or Canvas read can observe progress and the durable output. Do not start another run while one is pending. A terminal failure must be reported without automatic retry.\n\n## Completion\n\nDo not claim a generated image is durable until the result returns a target `node:`, durable `asset:`, and the final canvas read shows server-owned media fields. A video Job may return a protected download without materializing a native video node; report exactly what the server returned and do not invent durability.\n\nKeep generated output spatially near its input stage and connected to its source, prompt, List, or workflow. After finalization, run `canvas_validate` and read `completionReview`: it reports overlap, full-frame Section containment, reference lineage, and delivery state. Do not claim Done while it says `doneClaimAllowed: false`, including when delivery is pending, failed, or non-durable. Render the Canvas for visual inspection when the request includes a campaign, poster, banner, or multi-direction composition. Reference provenance is not a user workflow state and never requires a Keep action. Never create another paid provider call automatically.\n",
     }),
     Object.freeze({
         id: "existing-canvases",
@@ -65,7 +65,7 @@ export const GAVANA_CANVAS_GUIDE_SOURCES = Object.freeze([
         description: "Separate preparation from execution and prevent accidental or repeated provider charges.",
         keywords: Object.freeze(["paid","credits","cost","generate","run","retry","failure","prepare","setup","explicit"]),
         order: 8,
-        markdown: "\n## Intent boundary\n\n\"Build\", \"prepare\", \"set up\", \"connect\", \"draft\", and \"make ready\" authorize graph edits only. They do not authorize Recipe, image, video, or Action execution.\n\nStart paid work only when the current user message explicitly asks to run or generate it. Do not infer authorization from an older message, a node label, an unfinished placeholder, or nearby content.\n\n## Retry boundary\n\n- Use one stable idempotency key for one intended paid operation.\n- Poll the returned handle with status tools.\n- Never automatically retry a terminal failure, timeout, disconnect, or ambiguous provider response with a new key.\n- Ask for new user intent before any new paid attempt.\n\nDeterministic Actions may be described as credit-free only when `action_get` confirms that contract. Inspect an Action before running it.\n",
+        markdown: "\n## Intent boundary\n\n\"Build\", \"prepare\", \"set up\", \"connect\", \"draft\", and \"make ready\" authorize graph edits only. They do not authorize Recipe, image, video, or Action execution.\n\nStart paid work only when the current user message explicitly asks to run or generate it. Do not infer authorization from an older message, a node label, an unfinished placeholder, or nearby content.\n\n## Retry boundary\n\n- Use one stable idempotency key for one intended paid operation.\n- Return an image Run's durable queued progress immediately. Do not call `run_wait` unless the current user explicitly needs the completed asset in this same interaction; otherwise observe it later with `run_get` or a Canvas read.\n- Never automatically retry a terminal failure, timeout, disconnect, or ambiguous provider response with a new key.\n- Ask for new user intent before any new paid attempt.\n\nDeterministic Actions may be described as credit-free only when `action_get` confirms that contract. Inspect an Action before running it.\n",
     }),
     Object.freeze({
         id: "validation-recovery",

package/src/mcp-targets.mjs

@@ -49,7 +49,7 @@ export function gavanaMcpClientDefinition(clientName, baseUrl, readOnly = false)
             transport: "stdio",
             serverName,
             command: "npx",
-            args: ["-y", "@gavana.ai/mcp@0.2.0"],
+            args: ["-y", "@gavana.ai/mcp@0.2.1"],
             env: readOnly ? { GAVANA_MCP_READ_ONLY: "true" } : {},
             credentialSource: "Reads the active Gavana CLI profile or inherited GAVANA_BASE_URL and GAVANA_AGENT_TOKEN environment variables.",
         };

package/src/runner.mjs

@@ -504,11 +504,11 @@ 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 };
+        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,
@@ -1580,23 +1580,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() {
@@ -2052,7 +2046,8 @@ Global options:
   --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:

package/src/tools/image_tool.mjs

@@ -48,7 +48,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/schemas.mjs

@@ -166,7 +166,7 @@ function imageSchema() {
         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),
+        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),
     });
 }

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.2.2";