@gavana.ai/cli 0.2.0

package/src/tools/schemas.mjs

@@ -0,0 +1,165 @@
+// Shared input-schema primitives for the Gavana tool definitions.
+//
+// Extracted from scripts/gavana-agent-mcp.mjs so tool definitions can live outside
+// the server. The handle shapes (canvas:, node:, asset:, model:, action:, job:) and
+// the revision/idempotency contract are part of the published tool schemas, so these
+// describe() strings are user-visible — edit them as carefully as a tool description.
+import { z } from "zod";
+
+const canvasReference = z.string().min(1).describe("Stable canvas:<id> or canvas:<ownerUid>:<id> handle. Agent Canvas may also be addressed as agent-canvas.");
+const imageDestination = z.string().min(1).describe("agent-canvas, new-canvas, or a stable existing canvas handle.");
+const nodeReference = z.string().min(1).describe("Stable node:<id> handle.");
+const connectionReference = z.string().min(1).describe("Stable connection:<id> handle.");
+const assetReference = z
+    .string()
+    .regex(/^asset:(?:[A-Za-z0-9_-]{1,180}:)?[A-Za-z0-9_-]{1,180}$/)
+    .describe("Stable asset:<id> or shared asset:<ownerUid>:<id> handle.");
+const imageReferenceInput = z
+    .union([
+        z.union([nodeReference, assetReference]),
+        z
+            .object({
+                handle: z.union([nodeReference, assetReference]),
+                role: z.enum(["identity", "construction", "texture", "fit", "style"]).optional(),
+            })
+            .strict(),
+    ])
+    .describe("A durable image handle, optionally with the visual role it must preserve.");
+const jobReference = z.string().min(1).describe("Temporary opaque job:<id> compatibility handle for image and Action work.");
+const modelReference = z
+    .string()
+    .regex(/^model:[A-Za-z0-9_-]{8,600}$/)
+    .describe("Stable opaque model:<id> handle returned by model_list.");
+const actionReference = z
+    .string()
+    .regex(/^action:[a-z0-9]+(?:-[a-z0-9]+)*$/)
+    .describe("Stable action:<slug> handle returned by action_list.");
+const videoImageReference = z
+    .union([
+        nodeReference,
+        assetReference,
+        z
+            .string()
+            .url()
+            .regex(/^https:\/\//i, "Use a public HTTPS image URL."),
+    ])
+    .describe("Stable node:/asset: image handle or public HTTPS image URL.");
+const rawModelId = z
+    .string()
+    .min(1)
+    .max(240)
+    .refine((value) => !value.startsWith("model:"), "Use the exact model: handle returned by model_list.")
+    .describe("Provider model id. Prefer an opaque model: handle returned by model_list.");
+const exactCanvasReference = z
+    .string()
+    .regex(/^canvas:[A-Za-z0-9_-]{1,180}(?::[A-Za-z0-9_-]{1,180})?$/)
+    .describe("Exact stable canvas:<id> or canvas:<ownerUid>:<id> handle.");
+const recipeReference = z
+    .string()
+    .regex(/^recipe:[A-Za-z0-9_-]{1,180}$/)
+    .describe("Stable recipe:<id> handle.");
+const campaignReference = z
+    .string()
+    .regex(/^campaign:[A-Za-z0-9_-]{1,180}$/)
+    .describe("Stable campaign:<id> handle returned by campaign_plan.");
+const runReference = z
+    .string()
+    .regex(/^run:[A-Za-z0-9_-]{1,180}$/)
+    .describe("Opaque run:<id> handle. Image and Action Runs are temporary; Recipe Runs currently persist.");
+const campaignProductReference = z
+    .string()
+    .max(400)
+    .describe("Prefer one exact product image node:<id>, asset:<id>, or shared asset:<ownerUid>:<id> handle. A human-readable title is forwarded only so the server can return ambiguity candidates; it is never guessed.");
+const listCursor = z.string().min(1).max(8_192).optional().describe("Opaque page.nextCursor returned by the previous call with the same filters.");
+const listLimit = (maximum) => z.number().int().min(1).max(maximum).optional().describe(`Maximum items in this page (1-${maximum}).`);
+const approvedOutputReferences = z
+    .array(
+        z
+            .string()
+            .regex(/^node:[A-Za-z0-9_-]{1,180}$/)
+            .describe("One exact generated direction node:<id> handle."),
+    )
+    .length(2)
+    .refine((handles) => new Set(handles).size === handles.length, "Approve two different output nodes.");
+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 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."),
+    idempotencyKey: z.string().min(8).describe("Required caller-stable retry key. Reuse it only when retrying the same intended mutation."),
+};
+function imageSchema() {
+    return z.object({
+        canvasId: canvasReference.optional(),
+        destination: imageDestination.optional(),
+        canvasTitle: z.string().min(1).max(160).optional(),
+        ...revisionFields,
+        targetNodeIds: z.array(nodeReference).min(1).max(4).optional(),
+        targetTitle: z.string().min(1).max(160).optional(),
+        targetX: z.number().finite().optional(),
+        targetY: z.number().finite().optional(),
+        targetWidth: z.number().min(40).max(10_000).optional(),
+        targetHeight: z.number().min(40).max(10_000).optional(),
+        prompt: z.string().max(8_000).optional(),
+        promptNodeId: nodeReference.optional(),
+        references: z
+            .array(imageReferenceInput)
+            .max(16)
+            .optional(),
+        source: z.union([nodeReference, assetReference]).optional(),
+        connectionId: z.string().max(180).optional(),
+        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),
+        timeoutSeconds: z.number().min(1).max(3_600).default(900),
+    });
+}
+
+function validateImageInput(operation, value) {
+    const issues = [];
+    if (!value.destination && !value.canvasId) issues.push("Provide destination or canvasId.");
+    if (value.destination === "new-canvas" && !value.canvasTitle) issues.push("new-canvas requires canvasTitle.");
+    // prompt and promptNodeId may both be omitted only when explicit targets
+    // are supplied — an existing target can carry a visible prompt-mode
+    // connection that supplies the prompt. Without a target the tool would
+    // mint a blank auto-target no edge can point at, the server would reject
+    // 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 (!issues.length) return;
+    const error = new Error(`Input validation error: ${issues.join(" ")}`);
+    error.code = "invalid_image_input";
+    throw error;
+}
+
+export {
+    MAX_LOCAL_REFERENCE_IMAGE_BYTES,
+    actionReference,
+    approvedOutputReferences,
+    assetReference,
+    campaignAspectRatio,
+    campaignIdempotencyKey,
+    campaignProductReference,
+    campaignReference,
+    canvasReference,
+    connectionReference,
+    exactCanvasReference,
+    imageDestination,
+    imageReferenceInput,
+    imageSchema,
+    jobReference,
+    listCursor,
+    listLimit,
+    modelReference,
+    nodeReference,
+    rawModelId,
+    recipeForkIdempotencyKey,
+    recipeReference,
+    revisionFields,
+    runReference,
+    validateImageInput,
+    videoImageReference,
+};

package/src/tools/video_generate.mjs

@@ -0,0 +1,37 @@
+// Tool definition: video_generate
+//
+// 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, modelReference, rawModelId, videoImageReference } from "./schemas.mjs";
+import { withProgress } from "./progress.mjs";
+
+export function defineVideoGenerate(client) {
+    return {
+       title: "Generate video",
+       description: "Queue model-aware video generation with optional durable canvas frames, asset references, or public HTTPS image references.",
+       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+       inputSchema: z.object({
+           model: z.union([modelReference, rawModelId]),
+           connectionId: z.string().min(1).max(180).optional(),
+           prompt: z.string().min(1).max(8_000),
+           idempotencyKey: z.string().min(8).max(200),
+           canvasId: canvasReference.optional().describe("Required when a frame or reference uses a node: handle."),
+           ownerUid: z.string().min(1).max(180).optional(),
+           aspectRatio: z.string().min(1).max(40).optional(),
+           durationSeconds: z.number().int().min(1).max(120).optional(),
+           resolution: z.string().min(1).max(40).optional(),
+           generateAudio: z.boolean().optional(),
+           firstFrame: videoImageReference.optional(),
+           lastFrame: videoImageReference.optional(),
+           references: z.array(videoImageReference).max(9).optional(),
+           wait: z.boolean().default(true),
+           timeoutSeconds: z.number().min(1).max(3_600).default(1_800),
+       }),
+       handler: async ({ wait, timeoutSeconds, ...input }, extra) => {
+           const queued = await client.startVideo(input);
+           if (wait === false) return queued;
+           return client.waitForJob(queued.id, withProgress({ timeoutMs: timeoutSeconds * 1000 }, extra));
+       },
+    };
+}

package/src/version.mjs

@@ -0,0 +1,12 @@
+// The single source of the CLI package version.
+//
+// Its own module because three things need it and two of them must not drag in
+// the tool registry: client.mjs stamps every request's User-Agent, the stdio MCP
+// server advertises it as its server version, and capabilities.mjs re-exports it
+// for `gavana version`. Reading it from a literal is what let the User-Agent
+// report 0.1.0 for the whole life of 0.1.1, and let the MCP server advertise
+// 0.1.0 while packaged as 0.1.1.
+//
+// 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.0";