@gavana.ai/cli 0.2.0

package/src/client.mjs

@@ -0,0 +1,1141 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash, randomUUID } from "node:crypto";
+
+import { allocateCanvasRow, CANVAS_COORDINATE_LIMIT, CANVAS_SECTION_PADDING, CANVAS_SIBLING_SPACING } from "./canvas-layout.mjs";
+import { GAVANA_CLI_VERSION } from "./version.mjs";
+
+const API_PREFIX = "/api/canvas-agent/v1";
+// Matches the server's generated-image reframe ceiling (fitGeneratedImageNodeSize).
+const GROWN_FRAME_LIMIT = 640;
+// Matches the server-side maximum node width/height.
+const MAX_NODE_DIMENSION = 10_000;
+const TERMINAL_RUN_STATUSES = new Set(["succeeded", "failed", "canceled", "expired"]);
+const AGENT_CANVAS_DESTINATION = "agent-canvas";
+const NEW_CANVAS_DESTINATION = "new-canvas";
+const SUPPORTED_CAMPAIGN_ASPECT_RATIOS = new Set(["1:1", "4:5", "3:4", "16:9", "9:16"]);
+
+export class CanvasAgentApiError extends Error {
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "CanvasAgentApiError";
+        this.status = Number(options.status || 0);
+        this.details = options.details;
+        this.fields = options.fields;
+        this.requestId = options.requestId;
+        this.code = options.code || errorCodeForStatus(this.status);
+        this.cause = options.cause;
+    }
+}
+
+export function createCanvasAgentClient(options = {}) {
+    const baseUrl = normalizeBaseUrl(options.baseUrl);
+    const token = cleanToken(options.token);
+    const fetchImpl = options.fetchImpl || globalThis.fetch;
+    const surface = options.surface === "mcp" ? "mcp" : options.surface === "api" ? "api" : "cli";
+    const sleep = options.sleep || ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    // Read from the manifest-backed constant, never a literal. It sat at
+    // "gavana-cli/0.1.0" through the 0.1.1 release, so every API request and
+    // every analytics event from both the CLI and the local MCP server reported a
+    // version that had not shipped for months.
+    const userAgent = String(options.userAgent || `gavana-cli/${GAVANA_CLI_VERSION}`)
+        .trim()
+        .slice(0, 200);
+    const analyticsContext = new AsyncLocalStorage();
+
+    if (typeof fetchImpl !== "function") throw new CanvasAgentApiError("This runtime does not provide fetch.", { code: "configuration" });
+
+    const request = async (pathname, requestOptions = {}) => {
+        const url = new URL(`${API_PREFIX}${pathname}`, `${baseUrl}/`);
+        for (const [key, value] of Object.entries(requestOptions.query || {})) {
+            if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
+        }
+        const headers = new Headers(requestOptions.headers || {});
+        headers.set("Authorization", `Bearer ${token}`);
+        headers.set("Accept", requestOptions.responseType === "text" ? "image/svg+xml, text/plain;q=0.9, application/json;q=0.8" : requestOptions.responseType === "response" ? "video/*" : "application/json");
+        headers.set("X-Gavana-Agent-Surface", surface);
+        const activeAnalytics = analyticsContext.getStore();
+        if (activeAnalytics?.traceId) headers.set("X-Gavana-Trace-Id", activeAnalytics.traceId);
+        if (activeAnalytics?.parentEventId) headers.set("X-Gavana-Parent-Event-Id", activeAnalytics.parentEventId);
+        if (activeAnalytics?.invocationId) headers.set("X-Gavana-Invocation-Id", activeAnalytics.invocationId);
+        if (userAgent) headers.set("User-Agent", userAgent);
+        let body;
+        if (requestOptions.body !== undefined) {
+            headers.set("Content-Type", "application/json");
+            body = JSON.stringify(requestOptions.body);
+        } else if (requestOptions.bytes !== undefined) {
+            const bytes = Buffer.from(requestOptions.bytes);
+            headers.set("Content-Type", "application/octet-stream");
+            if (requestOptions.fileName) headers.set("X-Gavana-File-Name", String(requestOptions.fileName));
+            body = bytes;
+        }
+
+        const method = requestOptions.method || "GET";
+        let response;
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                response = await fetchImpl(url, {
+                    method,
+                    headers,
+                    body,
+                    cache: "no-store",
+                    signal: requestOptions.signal,
+                });
+            } catch (error) {
+                if (error?.name === "AbortError" || error?.name === "TimeoutError") {
+                    throw new CanvasAgentApiError("Gavana request timed out.", { code: "timeout", cause: error });
+                }
+                if (method === "GET" && attempt < 2) {
+                    await sleep(250 * 2 ** attempt);
+                    continue;
+                }
+                throw new CanvasAgentApiError(`Could not reach Gavana at ${baseUrl}.`, { code: "network", cause: error });
+            }
+            if (method === "GET" && attempt < 2 && [429, 502, 503, 504].includes(response.status)) {
+                await sleep(retryDelayMs(response.headers.get("retry-after"), attempt));
+                continue;
+            }
+            break;
+        }
+        if (!response) throw new CanvasAgentApiError(`Could not reach Gavana at ${baseUrl}.`, { code: "network" });
+        const requestId = response.headers.get("x-request-id") || response.headers.get("request-id") || undefined;
+
+        if (!response.ok) {
+            const text = await response.text().catch(() => "");
+            let payload;
+            try {
+                payload = text ? JSON.parse(text) : undefined;
+            } catch {
+                payload = undefined;
+            }
+            const message = payload?.error?.message || payload?.message || response.statusText || `Gavana request failed (${response.status}).`;
+            throw new CanvasAgentApiError(message, {
+                status: response.status,
+                code: payload?.error?.code || payload?.code || errorCodeForStatus(response.status),
+                details: payload?.error?.details || payload?.details,
+                fields: payload?.error?.fields || payload?.fields,
+                requestId,
+            });
+        }
+
+        if (requestOptions.responseType === "text") return response.text();
+        if (requestOptions.responseType === "response") return response;
+        if (response.status === 204) return null;
+        const text = await response.text();
+        if (!text) return null;
+        try {
+            const payload = JSON.parse(text);
+            return requestId && payload && typeof payload === "object" && !Array.isArray(payload) && payload.requestId === undefined ? { ...payload, requestId } : payload;
+        } catch (error) {
+            throw new CanvasAgentApiError("Gavana returned invalid JSON.", { status: 502, code: "invalid_response", requestId, cause: error });
+        }
+    };
+
+    const runWithAnalyticsContext = (context, handler) => analyticsContext.run(normalizeAnalyticsContext(context), handler);
+    const reportAnalyticsEvent = async (input = {}) => {
+        try {
+            const context = analyticsContext.getStore() || {};
+            const response = await fetchImpl(new URL("/api/agent-analytics/events", `${baseUrl}/`), {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    "X-Gavana-Agent-Surface": surface,
+                    ...(userAgent ? { "User-Agent": userAgent } : {}),
+                },
+                body: JSON.stringify({
+                    ...input,
+                    kind: input.kind || (surface === "mcp" ? "mcp_tool" : "cli_command"),
+                    traceId: input.traceId || context.traceId || randomUUID(),
+                    parentEventId: input.parentEventId || context.parentEventId,
+                    invocationId: input.invocationId || context.invocationId || randomUUID(),
+                }),
+                cache: "no-store",
+                keepalive: true,
+                signal: AbortSignal.timeout(750),
+            });
+            if (!response.ok) return null;
+            return await response.json().catch(() => null);
+        } catch {
+            return null;
+        }
+    };
+
+    const applyOperations = async (canvasReference, input, requestOptions = {}) => {
+        const canvas = parseStableHandle(canvasReference, "canvas");
+        return request(`/canvases/${encodeURIComponent(canvas.id)}/operations`, {
+            method: "POST",
+            query: { ownerUid: canvas.ownerUid },
+            body: input,
+            signal: requestOptions.signal,
+        });
+    };
+
+    const validateOperations = async (canvasReference, input, requestOptions = {}) => {
+        const canvas = parseStableHandle(canvasReference, "canvas");
+        return request(`/canvases/${encodeURIComponent(canvas.id)}/operations`, {
+            method: "POST",
+            query: { ownerUid: canvas.ownerUid },
+            body: { ...input, validateOnly: true },
+            signal: requestOptions.signal,
+        });
+    };
+
+    const createWorkflow = async (canvasReference, input, requestOptions = {}) => {
+        const canvas = parseStableHandle(canvasReference, "canvas");
+        return request(`/canvases/${encodeURIComponent(canvas.id)}/workflows`, {
+            method: "POST",
+            query: { ownerUid: canvas.ownerUid },
+            body: input,
+            signal: requestOptions.signal,
+        });
+    };
+
+    const createCanvas = (input, requestOptions = {}) => request("/canvases", { method: "POST", body: input, signal: requestOptions.signal });
+
+    const getCanvas = (canvasReference, requestOptions = {}) => {
+        const canvas = parseStableHandle(canvasReference, "canvas");
+        return request(`/canvases/${encodeURIComponent(canvas.id)}`, {
+            query: { ownerUid: canvas.ownerUid },
+            signal: requestOptions.signal,
+        });
+    };
+
+    const getOrCreateAgentCanvas = (requestOptions = {}) =>
+        request("/canvases", {
+            method: "POST",
+            body: { canvasType: "agent", destination: AGENT_CANVAS_DESTINATION },
+            signal: requestOptions.signal,
+        });
+
+    const resolveCanvasDestination = async (destination, destinationOptions = {}) => {
+        const reference = String(destination || "").trim();
+        if (!reference) throw new CanvasAgentApiError("Image destination is required.", { code: "usage" });
+        if (reference === AGENT_CANVAS_DESTINATION) return getOrCreateAgentCanvas(destinationOptions);
+        if (reference !== NEW_CANVAS_DESTINATION) return getCanvas(reference, destinationOptions);
+
+        const idempotencyKey = String(destinationOptions.idempotencyKey || "").trim();
+        if (idempotencyKey.length < 8 || idempotencyKey.length > 200) throw new CanvasAgentApiError("A retry-safe 8-200 character idempotency key is required when destination is new-canvas.", { code: "usage" });
+        const digest = createHash("sha256").update(idempotencyKey).digest("hex").slice(0, 24);
+        const canvasId = `agent-output-${digest}`;
+        try {
+            return await createCanvas({ id: canvasId, title: cleanDestinationTitle(destinationOptions.title) }, destinationOptions);
+        } catch (error) {
+            if (!(error instanceof CanvasAgentApiError) || error.status !== 409) throw error;
+            return getCanvas(canvasId, destinationOptions);
+        }
+    };
+
+    const prepareImageDestination = async (input = {}, requestOptions = {}) => {
+        const idempotencyKey = String(input.idempotencyKey || "").trim();
+        if (idempotencyKey.length < 8 || idempotencyKey.length > 200) throw new CanvasAgentApiError("idempotencyKey must contain 8-200 characters.", { code: "usage" });
+        const canvasResult =
+            input.canvasResult ||
+            (await resolveCanvasDestination(input.destination || input.canvasId, {
+                ...requestOptions,
+                idempotencyKey,
+                title: input.canvasTitle,
+            }));
+        const canvasHandle = canvasResult?.canvas?.handle;
+        if (!canvasHandle) throw new CanvasAgentApiError("Gavana did not return a destination canvas handle.", { code: "invalid_response" });
+
+        const count = boundedOutputCount(input.count);
+        const operation = ["generate", "edit", "variations", "action"].includes(input.operation) ? input.operation : "generate";
+        const digest = createHash("sha256").update(`${operation}:${idempotencyKey}`).digest("hex").slice(0, 24);
+        const suppliedTargets = [...(Array.isArray(input.targetNodeIds) ? input.targetNodeIds : []), ...(input.targetNodeId ? [input.targetNodeId] : [])].map((target) => {
+            const parsed = parseStableHandle(target, "node");
+            return `node:${parsed.id}`;
+        });
+        if (suppliedTargets.length) {
+            if (!input.requireIdleTargets) {
+                return {
+                    canvasId: canvasHandle,
+                    destination: String(input.destination || input.canvasId || canvasHandle),
+                    baseRevision: input.baseRevision || canvasResult.canvas.revision,
+                    targetNodeIds: suppliedTargets,
+                    canvas: canvasResult.canvas,
+                };
+            }
+            // Validated explicit targets join the same claim protocol as
+            // automatic matching: the claim replays on exact retries, so a
+            // retry after generation started is not rejected by the idle check.
+            const prompt = String(input.prompt || "").trim();
+            const nodeById = new Map((canvasResult.canvas.nodes || []).map((node) => [node.id, node]));
+            for (const handle of suppliedTargets) {
+                const node = nodeById.get(handle.slice("node:".length));
+                if (!node) throw new CanvasAgentApiError(`Target ${handle} was not found on this canvas.`, { code: "not_found" });
+                if (node.type !== "image") throw new CanvasAgentApiError(`Target ${handle} must be an image node.`, { code: "usage" });
+                if (claimedByInvocation(node, digest, prompt)) continue;
+                if (node.metadata?.agentTargetClaim) throw new CanvasAgentApiError(`Target ${handle} is already claimed by another image invocation. Pick a different node or reuse that invocation's idempotency key.`, { code: "conflict" });
+                if (!emptyIdleImageTarget(node)) {
+                    throw new CanvasAgentApiError(`Target ${handle} already has content or an active generation. Pick an empty idle image node or omit targetNodeId.`, { code: "conflict" });
+                }
+            }
+            const applied = await applyOperations(
+                canvasHandle,
+                {
+                    baseRevision: input.baseRevision || canvasResult.canvas.revision,
+                    idempotencyKey: `image-target-${digest}`,
+                    operations: suppliedTargets.map((handle) => ({
+                        type: "node.update",
+                        nodeId: handle,
+                        patch: { metadata: { prompt, agentTargetClaim: digest } },
+                    })),
+                },
+                requestOptions,
+            );
+            return {
+                canvasId: canvasHandle,
+                destination: String(input.destination || input.canvasId || canvasHandle),
+                baseRevision: applied.canvas.revision,
+                targetNodeIds: suppliedTargets,
+                canvas: applied.canvas,
+            };
+        }
+
+        const targetIds = Array.from({ length: count }, (_, index) => `agent-image-${digest}-${index + 1}`);
+        const targetNodeIds = targetIds.map((id) => `node:${id}`);
+        const existingNodeIds = new Set((canvasResult.canvas.nodes || []).map((node) => node.id));
+        const existingTargetCount = targetIds.filter((id) => existingNodeIds.has(id)).length;
+        if (existingTargetCount && existingTargetCount !== targetIds.length) {
+            throw new CanvasAgentApiError("Automatic image targets are incomplete. Use a new idempotency key or pass explicit --target nodes.", { code: "conflict" });
+        }
+        if (existingTargetCount === targetIds.length) {
+            return {
+                canvasId: canvasHandle,
+                destination: String(input.destination || input.canvasId || canvasHandle),
+                baseRevision: input.baseRevision || canvasResult.canvas.revision,
+                targetNodeIds,
+                canvas: canvasResult.canvas,
+            };
+        }
+
+        // Before creating fresh targets, fill existing empty targets that match
+        // this invocation — typically idle "Generate" placeholders left by an
+        // earlier failed or abandoned attempt. Claimed nodes are stamped with
+        // this invocation's target digest so an exact retry re-selects the same
+        // nodes even after they start loading; the claim shares the automatic
+        // target-creation idempotency key, so the retry replays byte-identical
+        // operations instead of minting different targets.
+        const reusableTargets = reusableIdleImageTargets(canvasResult.canvas.nodes || [], canvasResult.canvas.connections || [], input, digest);
+        if (reusableTargets.length >= count) {
+            const reused = reusableTargets.slice(0, count);
+            const reusablePrompt = String(input.prompt || "").trim();
+            const applied = await applyOperations(
+                canvasHandle,
+                {
+                    baseRevision: input.baseRevision || canvasResult.canvas.revision,
+                    idempotencyKey: `image-target-${digest}`,
+                    operations: reused.map((node) => ({
+                        type: "node.update",
+                        nodeId: `node:${node.id}`,
+                        patch: { metadata: { prompt: reusablePrompt, agentTargetClaim: digest } },
+                    })),
+                },
+                requestOptions,
+            );
+            return {
+                canvasId: canvasHandle,
+                destination: String(input.destination || input.canvasId || canvasHandle),
+                baseRevision: applied.canvas.revision,
+                targetNodeIds: reused.map((node) => `node:${node.id}`),
+                canvas: applied.canvas,
+            };
+        }
+
+        const dimensions = automaticTargetDimensions(input.size, input.targetWidth, input.targetHeight);
+        // Explicit targetX/targetY keeps its historical exact placement; an
+        // omitted position delegates to the shared free-region allocator so
+        // automatic targets never stack on existing content. Successful jobs
+        // reframe placeholders up to GROWN_FRAME_LIMIT while preserving their
+        // centers, so multi-output cells (and the Section wrapped around them)
+        // reserve that grown footprint up front.
+        const explicitOrigin = input.targetX !== undefined || input.targetY !== undefined ? automaticTargetOrigin(canvasResult.canvas.nodes || [], dimensions, input.targetX, input.targetY) : null;
+        const sectioned = count > 1 && !explicitOrigin;
+        const cellSize = sectioned ? { width: Math.max(dimensions.width, GROWN_FRAME_LIMIT), height: Math.max(dimensions.height, GROWN_FRAME_LIMIT) } : dimensions;
+        const cellPositions = explicitOrigin
+            ? targetIds.map((_, index) => ({ x: explicitOrigin.x + index * (dimensions.width + CANVAS_SIBLING_SPACING), y: explicitOrigin.y }))
+            : allocateCanvasRow(
+                  canvasResult.canvas.nodes || [],
+                  targetIds.map(() => cellSize),
+              );
+        const positions = cellPositions.map((cell) => ({ x: cell.x + Math.round((cellSize.width - dimensions.width) / 2), y: cell.y + Math.round((cellSize.height - dimensions.height) / 2) }));
+        const title = cleanTargetTitle(input.targetTitle, operation);
+        const operations = targetIds.map((id, index) => ({
+            type: "node.create",
+            clientId: `image-target-${index + 1}`,
+            node: {
+                id,
+                type: "image",
+                title: count > 1 ? `${title} ${index + 1}` : title,
+                position: positions[index],
+                width: dimensions.width,
+                height: dimensions.height,
+                ...(input.prompt ? { metadata: { prompt: String(input.prompt).slice(0, 8_000) } } : {}),
+            },
+        }));
+        // One task = one Section: a multi-output cluster is wrapped in a titled
+        // Section sized to its grown-cell footprint plus 48 units of padding,
+        // so batch generations stop scattering loose siblings across the
+        // shared canvas — and finished frames still fit inside the wrapper.
+        if (sectioned) {
+            const right = Math.max(...cellPositions.map((cell) => cell.x)) + cellSize.width;
+            const bottom = Math.max(...cellPositions.map((cell) => cell.y)) + cellSize.height;
+            // Padding clamps into the coordinate bound: a row allocated at the
+            // very edge trades a little padding on that edge instead of
+            // producing an out-of-range Section that fails the whole batch.
+            const sectionLeft = Math.max(cellPositions[0].x - CANVAS_SECTION_PADDING, -CANVAS_COORDINATE_LIMIT);
+            const sectionTop = Math.max(cellPositions[0].y - CANVAS_SECTION_PADDING, -CANVAS_COORDINATE_LIMIT);
+            const sectionWidth = Math.min(right + CANVAS_SECTION_PADDING, CANVAS_COORDINATE_LIMIT) - sectionLeft;
+            const sectionHeight = Math.min(bottom + CANVAS_SECTION_PADDING, CANVAS_COORDINATE_LIMIT) - sectionTop;
+            // Oversized custom targets can push the wrapper past the node
+            // dimension limit; the cluster then ships unwrapped rather than
+            // failing the whole batch before generation.
+            if (sectionWidth <= MAX_NODE_DIMENSION && sectionHeight <= MAX_NODE_DIMENSION) {
+                operations.unshift({
+                    type: "node.create",
+                    clientId: "image-target-section",
+                    node: {
+                        id: `agent-image-section-${digest}`,
+                        type: "text",
+                        title,
+                        position: { x: sectionLeft, y: sectionTop },
+                        width: sectionWidth,
+                        height: sectionHeight,
+                        metadata: { isSection: true, content: "", sectionAutoFit: { version: 1, owner: "agent", state: "auto-fit", padding: 48 } },
+                    },
+                });
+            }
+        }
+        let applied;
+        try {
+            applied = await applyOperations(
+                canvasHandle,
+                {
+                    baseRevision: input.baseRevision || canvasResult.canvas.revision,
+                    idempotencyKey: `image-target-${digest}`,
+                    operations,
+                },
+                requestOptions,
+            );
+        } catch (error) {
+            if (error instanceof CanvasAgentApiError && error.status === 409 && String(error.message).includes("already used for a different canvas batch")) {
+                // This invocation previously claimed targets that are no longer
+                // selectable (for example a claimed node was since filled by
+                // someone else). Fail loudly instead of overwriting content or
+                // minting orphan duplicates under a reused key.
+                throw new CanvasAgentApiError("This idempotencyKey already claimed image targets that are no longer available. Use a new idempotency key for a new generation, or check the original job with its run handle.", { status: 409, code: "conflict", cause: error });
+            }
+            throw error;
+        }
+        return {
+            canvasId: canvasHandle,
+            destination: String(input.destination || input.canvasId || canvasHandle),
+            baseRevision: applied.canvas.revision,
+            targetNodeIds,
+            canvas: applied.canvas,
+        };
+    };
+
+    return {
+        baseUrl,
+        request,
+        runWithAnalyticsContext,
+        reportAnalyticsEvent,
+        getAuthStatus: (requestOptions = {}) => request("/auth/status", requestOptions),
+        listCanvases: (requestOptions = {}) =>
+            request("/canvases", {
+                query: paginationQuery(requestOptions, 25),
+                signal: requestOptions.signal,
+            }),
+        createCanvas,
+        getCanvas,
+        getOrCreateAgentCanvas,
+        resolveCanvasDestination,
+        prepareImageDestination,
+        createWorkflow,
+        searchRecipes: (query = "", requestOptions = {}) =>
+            request("/recipes", {
+                query: { q: cleanOptionalText(query, "Recipe search query", 240), ...paginationQuery(requestOptions, 100) },
+                signal: requestOptions.signal,
+            }),
+        getRecipe: (recipeReference, version, requestOptions = {}) => {
+            const recipe = parseRequiredStableHandle(recipeReference, "recipe");
+            return request(`/recipes/${encodeURIComponent(recipe.id)}`, {
+                query: { version: cleanOptionalText(version, "Recipe version", 80) },
+                signal: requestOptions.signal,
+            });
+        },
+        forkRecipe: async (recipeReference, input, requestOptions = {}) => {
+            const recipe = parseRequiredStableHandle(recipeReference, "recipe");
+            const { canvas, ...normalized } = normalizeRecipeForkInput(input);
+            const baseRevision = normalized.baseRevision || (await getCanvas(stableHandle(canvas), requestOptions)).canvas?.revision;
+            if (!baseRevision) throw new CanvasAgentApiError("Read the canvas before forking a Recipe so its current revision is available.", { code: "invalid_response" });
+            return request(`/recipes/${encodeURIComponent(recipe.id)}/fork`, {
+                method: "POST",
+                body: { ...normalized, baseRevision },
+                signal: requestOptions.signal,
+            });
+        },
+        startRecipeRun: async (recipeReference, input, requestOptions = {}) => {
+            const recipe = parseRequiredStableHandle(recipeReference, "recipe");
+            const source = requireRecord(input, "Recipe run");
+            const canvas = parseStableHandle(source.canvasId, "canvas");
+            const canvasHandle = stableHandle(canvas);
+            const baseRevision = cleanOptionalText(source.baseRevision, "Canvas base revision", 200) || (await getCanvas(canvasHandle, requestOptions)).canvas?.revision;
+            if (!baseRevision) throw new CanvasAgentApiError("Read the canvas before starting a Recipe so its current revision is available.", { code: "invalid_response" });
+            return request(`/recipes/${encodeURIComponent(recipe.id)}/runs`, {
+                method: "POST",
+                body: {
+                    ...source,
+                    canvasId: canvasHandle,
+                    baseRevision,
+                    idempotencyKey: requiredIdempotencyKey(source.idempotencyKey),
+                },
+                signal: requestOptions.signal,
+            });
+        },
+        planCampaign: (input, requestOptions = {}) =>
+            request("/campaigns/plan", {
+                method: "POST",
+                body: normalizeCampaignPlanInput(input),
+                signal: requestOptions.signal,
+            }),
+        startCampaign: (input, requestOptions = {}) =>
+            request("/campaigns/start", {
+                method: "POST",
+                body: normalizeCampaignStartInput(input),
+                signal: requestOptions.signal,
+            }),
+        getCampaign: (runReference, requestOptions = {}) => {
+            const run = parseRequiredStableHandle(runReference, "run");
+            return request(`/campaigns/${encodeURIComponent(run.id)}`, { signal: requestOptions.signal });
+        },
+        reviewCampaign: (runReference, input, requestOptions = {}) => {
+            const run = parseRequiredStableHandle(runReference, "run");
+            return request(`/campaigns/${encodeURIComponent(run.id)}/review`, {
+                method: "POST",
+                body: normalizeCampaignReviewInput(input),
+                signal: requestOptions.signal,
+            });
+        },
+        cancelCampaign: (runReference, requestOptions = {}) => {
+            const run = parseRequiredStableHandle(runReference, "run");
+            return request(`/campaigns/${encodeURIComponent(run.id)}`, {
+                method: "DELETE",
+                signal: requestOptions.signal,
+            });
+        },
+        renderCanvas: (canvasReference, requestOptions = {}) => {
+            const canvas = parseStableHandle(canvasReference, "canvas");
+            return request(`/canvases/${encodeURIComponent(canvas.id)}/render`, {
+                query: { ownerUid: canvas.ownerUid },
+                responseType: "text",
+                signal: requestOptions.signal,
+            });
+        },
+        getNode: (canvasReference, nodeReference, requestOptions = {}) => {
+            const canvas = parseStableHandle(canvasReference, "canvas");
+            const node = parseStableHandle(nodeReference, "node");
+            return request(`/canvases/${encodeURIComponent(canvas.id)}/nodes/${encodeURIComponent(node.id)}`, {
+                query: { ownerUid: canvas.ownerUid },
+                signal: requestOptions.signal,
+            });
+        },
+        applyOperations,
+        validateOperations,
+        listAssets: (canvasReference, requestOptions = {}) => {
+            const canvas = canvasReference ? parseStableHandle(canvasReference, "canvas") : undefined;
+            return request("/assets", {
+                query: { canvasId: canvas?.id, ownerUid: canvas?.ownerUid, ...paginationQuery(requestOptions, 200) },
+                signal: requestOptions.signal,
+            });
+        },
+        getAsset: (assetReference, requestOptions = {}) => {
+            const asset = parseStableHandle(assetReference, "asset");
+            return request(`/assets/${encodeURIComponent(asset.id)}`, {
+                query: { ownerUid: asset.ownerUid },
+                signal: requestOptions.signal,
+            });
+        },
+        uploadAsset: (input, requestOptions = {}) => {
+            if (!input || !input.bytes) throw new CanvasAgentApiError("Image bytes are required.", { code: "usage" });
+            const canvas = input.canvasReference ? parseStableHandle(input.canvasReference, "canvas") : undefined;
+            return request("/assets", {
+                method: "POST",
+                query: { canvasId: canvas?.id, ownerUid: canvas?.ownerUid },
+                bytes: input.bytes,
+                fileName: input.fileName,
+                signal: requestOptions.signal,
+            });
+        },
+        listConnections: (requestOptions = {}) =>
+            request("/providers", {
+                query: paginationQuery(requestOptions, 100),
+                signal: requestOptions.signal,
+            }),
+        listModels: (filters = {}, requestOptions = {}) =>
+            request("/models", {
+                query: {
+                    q: cleanOptionalText(filters.query, "Model search query", 240),
+                    provider: cleanOptionalText(filters.provider, "Model provider", 80),
+                    capability: cleanOptionalText(filters.capability, "Model capability", 80),
+                    ...paginationQuery(requestOptions, 100),
+                },
+                signal: requestOptions.signal,
+            }),
+        getModel: (modelReference, requestOptions = {}) => {
+            const model = parseStableHandle(modelReference, "model");
+            return request(`/models/${encodeURIComponent(model.id)}`, { signal: requestOptions.signal });
+        },
+        listActions: (query = "", requestOptions = {}) =>
+            request("/actions", {
+                query: { q: cleanOptionalText(query, "Action search query", 240), ...paginationQuery(requestOptions, 100) },
+                signal: requestOptions.signal,
+            }),
+        getAction: (actionReference, requestOptions = {}) => {
+            const action = parseStableHandle(actionReference, "action");
+            return request(`/actions/${encodeURIComponent(action.id)}`, { signal: requestOptions.signal });
+        },
+        startAction: (actionReference, input, requestOptions = {}) => {
+            const action = parseStableHandle(actionReference, "action");
+            return request(`/actions/${encodeURIComponent(action.id)}/runs`, {
+                method: "POST",
+                body: input,
+                signal: requestOptions.signal,
+            });
+        },
+        startImage: async (operation, input, requestOptions = {}) => {
+            if (operation !== "generate" && operation !== "edit" && operation !== "variations") {
+                throw new CanvasAgentApiError("Image operation must be generate, edit, or variations.", { code: "usage" });
+            }
+            let body = input;
+            if (input?.canvasId === AGENT_CANVAS_DESTINATION) {
+                const resolved = await getOrCreateAgentCanvas(requestOptions);
+                body = { ...input, canvasId: resolved.canvas.handle, baseRevision: input.baseRevision || resolved.canvas.revision };
+            }
+            return request(`/images/${operation}`, {
+                method: "POST",
+                body,
+                signal: requestOptions.signal,
+            });
+        },
+        importImage: (input, requestOptions = {}) =>
+            request("/images/import", {
+                method: "POST",
+                body: input,
+                signal: requestOptions.signal,
+            }),
+        importProductReferencePack: (input, requestOptions = {}) =>
+            request("/product-references/import", {
+                method: "POST",
+                body: input,
+                signal: requestOptions.signal,
+            }),
+        startVideo: (input, requestOptions = {}) =>
+            request("/videos/generate", {
+                method: "POST",
+                body: input,
+                signal: requestOptions.signal,
+            }),
+        getJob: (jobReference, requestOptions = {}) => {
+            const job = parseStableHandle(jobReference, "job");
+            return request(`/jobs/${encodeURIComponent(job.id)}`, { signal: requestOptions.signal });
+        },
+        cancelJob: (jobReference, requestOptions = {}) => {
+            const job = parseStableHandle(jobReference, "job");
+            return request(`/jobs/${encodeURIComponent(job.id)}`, { method: "DELETE", signal: requestOptions.signal });
+        },
+        downloadJobOutput: (jobReference, requestOptions = {}) => {
+            const job = parseStableHandle(jobReference, "job");
+            return request(`/jobs/${encodeURIComponent(job.id)}/output`, { responseType: "response", signal: requestOptions.signal });
+        },
+        waitForJob: async (jobReference, waitOptions = {}) => {
+            const timeoutMs = positiveNumber(waitOptions.timeoutMs, 15 * 60_000);
+            const intervalMs = positiveNumber(waitOptions.intervalMs, 1_500, true);
+            const startedAt = Date.now();
+            let lastStatus = "";
+            while (Date.now() - startedAt <= timeoutMs) {
+                const result = await request(`/jobs/${encodeURIComponent(parseStableHandle(jobReference, "job").id)}`, { signal: waitOptions.signal });
+                if (result?.status !== lastStatus) {
+                    lastStatus = String(result?.status || "");
+                    await waitOptions.onProgress?.(result);
+                }
+                if (TERMINAL_RUN_STATUSES.has(result?.status)) return result;
+                if (waitOptions.signal?.aborted) throw new CanvasAgentApiError("Waiting for the job was canceled.", { code: "canceled" });
+                await sleep(intervalMs);
+            }
+            throw new CanvasAgentApiError(`Job did not finish within ${Math.round(timeoutMs / 1000)} seconds. Resume with job wait ${jobReference}.`, { code: "timeout" });
+        },
+        getRun: (runReference, requestOptions = {}) => {
+            const run = parseSharedRunHandle(runReference);
+            return request(`/runs/${encodeURIComponent(run.id)}`, { signal: requestOptions.signal });
+        },
+        cancelRun: (runReference, requestOptions = {}) => {
+            const run = parseSharedRunHandle(runReference);
+            return request(`/runs/${encodeURIComponent(run.id)}`, { method: "DELETE", signal: requestOptions.signal });
+        },
+        waitForRun: async (runReference, waitOptions = {}) => {
+            const run = parseSharedRunHandle(runReference);
+            const timeoutMs = positiveNumber(waitOptions.timeoutMs, 15 * 60_000);
+            const intervalMs = positiveNumber(waitOptions.intervalMs, 1_500, true);
+            const startedAt = Date.now();
+            let lastStatus = "";
+            while (Date.now() - startedAt <= timeoutMs) {
+                const result = await request(`/runs/${encodeURIComponent(run.id)}`, { signal: waitOptions.signal });
+                if (result?.status !== lastStatus) {
+                    lastStatus = String(result?.status || "");
+                    await waitOptions.onProgress?.(result);
+                }
+                if (TERMINAL_RUN_STATUSES.has(result?.status)) return result;
+                if (waitOptions.signal?.aborted) throw new CanvasAgentApiError("Waiting for the Run was canceled.", { code: "canceled" });
+                await sleep(intervalMs);
+            }
+            throw new CanvasAgentApiError(`Run did not finish within ${Math.round(timeoutMs / 1000)} seconds. Resume with run wait run:${run.id}.`, { code: "timeout" });
+        },
+    };
+}
+
+function normalizeAnalyticsContext(value = {}) {
+    return {
+        traceId: safeAnalyticsName(value.traceId) || randomUUID(),
+        parentEventId: safeAnalyticsName(value.parentEventId) || undefined,
+        invocationId: safeAnalyticsName(value.invocationId) || randomUUID(),
+    };
+}
+
+function safeAnalyticsName(value) {
+    const cleaned = String(value || "")
+        .trim()
+        .slice(0, 180);
+    return /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/.test(cleaned) ? cleaned : "";
+}
+
+function retryDelayMs(retryAfter, attempt) {
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.min(10_000, seconds * 1_000);
+    if (retryAfter) {
+        const date = Date.parse(retryAfter);
+        if (Number.isFinite(date)) return Math.max(0, Math.min(10_000, date - Date.now()));
+    }
+    return 250 * 2 ** attempt;
+}
+
+function parseSharedRunHandle(value) {
+    return parseStableHandle(value, "run");
+}
+
+export function parseStableHandle(value, expectedKind) {
+    const raw = String(value || "").trim();
+    if (!raw) throw new CanvasAgentApiError(`${capitalize(expectedKind)} reference is required.`, { code: "usage" });
+    const parts = raw.split(":");
+    if (expectedKind === "model") {
+        const key = parts.length === 1 ? parts[0] : parts.length === 2 && parts[0] === "model" ? parts[1] : "";
+        if (!/^[A-Za-z0-9_-]{8,600}$/.test(key)) throw invalidHandle(expectedKind);
+        return { kind: expectedKind, id: key };
+    }
+    if (expectedKind === "canvas" || expectedKind === "asset") {
+        if (parts.length === 1) return { kind: expectedKind, id: validateId(parts[0], capitalize(expectedKind)) };
+        if (parts[0] !== expectedKind) throw invalidHandle(expectedKind);
+        if (parts.length === 2) return { kind: expectedKind, id: validateId(parts[1], capitalize(expectedKind)) };
+        if (parts.length === 3) {
+            return {
+                kind: expectedKind,
+                ownerUid: validateId(parts[1], `${capitalize(expectedKind)} owner`),
+                id: validateId(parts[2], capitalize(expectedKind)),
+            };
+        }
+        throw invalidHandle(expectedKind);
+    }
+    if (parts.length === 1) return { kind: expectedKind, id: validateId(parts[0], capitalize(expectedKind)) };
+    if (parts.length !== 2 || parts[0] !== expectedKind) throw invalidHandle(expectedKind);
+    return { kind: expectedKind, id: validateId(parts[1], capitalize(expectedKind)) };
+}
+
+export function parseRequiredStableHandle(value, expectedKind) {
+    const raw = String(value || "").trim();
+    if (!raw.startsWith(`${expectedKind}:`)) throw invalidHandle(expectedKind);
+    return parseStableHandle(raw, expectedKind);
+}
+
+function normalizeCampaignPlanInput(input) {
+    const source = requireRecord(input, "campaign plan");
+    const canvas = parseRequiredStableHandle(source.canvasId, "canvas");
+    const recipe = parseRequiredStableHandle(source.recipeId, "recipe");
+    const brandKit = isRecord(source.brandKit) ? source.brandKit : {};
+    const product = normalizeCampaignProductReference(source.product ?? source.productReference);
+    const brandKitId = normalizeOptionalCampaignBrandKitId(source.brandKitId ?? brandKit.id);
+    const brandKitRevision = normalizeOptionalInteger(source.brandKitRevision ?? brandKit.revision, "Brand Kit revision", 1);
+    const brief = normalizeOptionalCampaignBrief(source.brief);
+    const finalOutputCount = normalizeOptionalInteger(source.finalOutputCount, "Final output count", 1, 4);
+    const aspectRatios = normalizeCampaignAspectRatios(source.aspectRatios);
+    const idempotencyKey = requiredIdempotencyKey(source.idempotencyKey);
+    const recipeVersion = cleanOptionalText(source.recipeVersion, "Recipe version", 80);
+
+    return {
+        canvasId: stableHandle(canvas),
+        recipeId: stableHandle(recipe),
+        ...(recipeVersion ? { recipeVersion } : {}),
+        ...(product ? { product } : {}),
+        ...(brandKitId ? { brandKitId } : {}),
+        ...(brandKitRevision !== undefined ? { brandKitRevision } : {}),
+        ...(brief !== undefined ? { brief } : {}),
+        ...(finalOutputCount !== undefined ? { finalOutputCount } : {}),
+        ...(aspectRatios ? { aspectRatios } : {}),
+        idempotencyKey,
+    };
+}
+
+function normalizeRecipeForkInput(input) {
+    const source = requireRecord(input, "Recipe fork");
+    const canvas = parseRequiredStableHandle(source.canvasId, "canvas");
+    const version = cleanOptionalText(source.version, "Recipe version", 80);
+    const baseRevision = cleanOptionalText(source.baseRevision, "Canvas base revision", 200);
+    const x = normalizeOptionalRecipeForkCoordinate(source.x, "Recipe fork x");
+    const y = normalizeOptionalRecipeForkCoordinate(source.y, "Recipe fork y");
+    return {
+        canvas,
+        canvasId: canvas.id,
+        ...(canvas.ownerUid ? { ownerUid: canvas.ownerUid } : {}),
+        ...(version ? { version } : {}),
+        ...(baseRevision ? { baseRevision } : {}),
+        ...(x !== undefined ? { x } : {}),
+        ...(y !== undefined ? { y } : {}),
+        idempotencyKey: requiredIdempotencyKey(source.idempotencyKey),
+    };
+}
+
+function normalizeOptionalRecipeForkCoordinate(value, label) {
+    if (value === undefined || value === null || value === "") return undefined;
+    const coordinate = Number(value);
+    if (!Number.isFinite(coordinate) || coordinate < -100_000 || coordinate > 100_000) {
+        throw new CanvasAgentApiError(`${label} must be a finite canvas coordinate between -100000 and 100000.`, { code: "usage" });
+    }
+    return Math.round(coordinate);
+}
+
+function normalizeCampaignStartInput(input) {
+    const source = requireRecord(input, "campaign start");
+    const campaign = parseRequiredStableHandle(source.campaignId, "campaign");
+    return {
+        campaignId: stableHandle(campaign),
+        idempotencyKey: requiredIdempotencyKey(source.idempotencyKey),
+    };
+}
+
+function normalizeCampaignReviewInput(input) {
+    const source = requireRecord(input, "campaign review");
+    const approved = source.approvedOutputNodeIds ?? source.approvedOutputs;
+    if (!Array.isArray(approved) || approved.length !== 2) {
+        throw new CanvasAgentApiError("Campaign review requires exactly two approved output node handles.", { code: "usage" });
+    }
+    const approvedOutputNodeIds = approved.map((candidate) => {
+        const value = isRecord(candidate) ? (candidate.handle ?? candidate.nodeId) : candidate;
+        return stableHandle(parseRequiredStableHandle(value, "node"));
+    });
+    if (new Set(approvedOutputNodeIds).size !== approvedOutputNodeIds.length) {
+        throw new CanvasAgentApiError("Campaign review approvals must reference two different output nodes.", { code: "usage" });
+    }
+    return {
+        approvedOutputNodeIds,
+        idempotencyKey: requiredIdempotencyKey(source.idempotencyKey),
+    };
+}
+
+function normalizeCampaignProductReference(value) {
+    if (value === undefined || value === null) return undefined;
+    const reference = isRecord(value) ? (value.handle ?? value.nodeId ?? value.assetId) : value;
+    const raw = String(reference ?? "").trim();
+    if (!raw) return undefined;
+    if (raw.length > 400) {
+        throw new CanvasAgentApiError("Campaign product reference must contain at most 400 characters.", { code: "usage" });
+    }
+    const kind = raw.startsWith("node:") ? "node" : raw.startsWith("asset:") ? "asset" : "";
+    return kind ? stableHandle(parseRequiredStableHandle(raw, kind)) : raw;
+}
+
+function normalizeOptionalCampaignBrandKitId(value) {
+    if (value === undefined || value === null || value === "") return undefined;
+    return validateId(String(value).replace(/^brand-kit:/, ""), "Brand Kit");
+}
+
+function normalizeOptionalCampaignBrief(value) {
+    if (value === undefined || value === null) return undefined;
+    const brief = String(value).trim();
+    if (!brief) return undefined;
+    if (brief.length > 8_000) {
+        throw new CanvasAgentApiError("Campaign brief must contain at most 8000 characters.", { code: "usage" });
+    }
+    return brief;
+}
+
+function normalizeOptionalInteger(value, label, minimum, maximum = Number.MAX_SAFE_INTEGER) {
+    if (value === undefined || value === null || value === "") return undefined;
+    return requiredInteger(value, label, minimum, maximum);
+}
+
+function paginationQuery(options = {}, maximum = 100) {
+    if (options.limit !== undefined && options.limit !== null && options.limit !== "" && typeof options.limit !== "string" && typeof options.limit !== "number") {
+        throw new CanvasAgentApiError(`Page limit must be an integer between 1 and ${maximum}.`, { code: "usage" });
+    }
+    const limit = options.limit === undefined || options.limit === null || options.limit === "" ? undefined : requiredInteger(options.limit, "Page limit", 1, maximum);
+    if (options.cursor !== undefined && options.cursor !== null && typeof options.cursor !== "string") {
+        throw new CanvasAgentApiError("Page cursor must be a string.", { code: "usage" });
+    }
+    const cursor = cleanOptionalText(options.cursor, "Page cursor", 8_192);
+    return {
+        ...(limit !== undefined ? { limit } : {}),
+        ...(cursor ? { cursor } : {}),
+    };
+}
+
+function normalizeCampaignAspectRatios(value) {
+    if (value === undefined || value === null) return undefined;
+    if (!Array.isArray(value) || value.length !== 1) {
+        throw new CanvasAgentApiError("Campaign V1 aspectRatios must contain exactly one supported ratio.", { code: "usage" });
+    }
+    const ratios = value.map((ratio) => String(ratio || "").trim());
+    if (ratios.some((ratio) => !SUPPORTED_CAMPAIGN_ASPECT_RATIOS.has(ratio))) {
+        throw new CanvasAgentApiError("Campaign aspectRatios support 1:1, 4:5, 3:4, 16:9, and 9:16.", { code: "usage" });
+    }
+    return ratios;
+}
+
+function requireRecord(value, label) {
+    if (!isRecord(value)) throw new CanvasAgentApiError(`${capitalize(label)} input must be a JSON object.`, { code: "usage" });
+    return value;
+}
+
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function cleanOptionalText(value, label, maximum) {
+    if (value === undefined || value === null || value === "") return "";
+    const text = String(value).trim();
+    if (text.length > maximum) throw new CanvasAgentApiError(`${label} must contain at most ${maximum} characters.`, { code: "usage" });
+    return text;
+}
+
+function requiredInteger(value, label, minimum, maximum = Number.MAX_SAFE_INTEGER) {
+    const number = Number(value);
+    if (!Number.isInteger(number) || number < minimum || number > maximum) {
+        const range = maximum === Number.MAX_SAFE_INTEGER ? `at least ${minimum}` : `between ${minimum} and ${maximum}`;
+        throw new CanvasAgentApiError(`${label} must be an integer ${range}.`, { code: "usage" });
+    }
+    return number;
+}
+
+function requiredIdempotencyKey(value) {
+    const key = String(value || "").trim();
+    if (key.length < 8 || key.length > 200) {
+        throw new CanvasAgentApiError("idempotencyKey must contain 8-200 characters.", { code: "usage" });
+    }
+    return key;
+}
+
+function stableHandle(reference) {
+    if ((reference.kind === "canvas" || reference.kind === "asset") && reference.ownerUid) return `${reference.kind}:${reference.ownerUid}:${reference.id}`;
+    return `${reference.kind}:${reference.id}`;
+}
+
+function cleanDestinationTitle(value) {
+    const title = String(value || "Agent image output")
+        .replace(/[\r\n]/g, " ")
+        .trim()
+        .slice(0, 160);
+    return title || "Agent image output";
+}
+
+function cleanTargetTitle(value, operation) {
+    const fallback = operation === "edit" ? "Agent image edit" : operation === "variations" ? "Agent image variation" : operation === "action" ? "Image Action result" : "Agent image";
+    const title = String(value || fallback)
+        .replace(/[\r\n]/g, " ")
+        .trim()
+        .slice(0, 160);
+    return title || fallback;
+}
+
+function boundedOutputCount(value) {
+    const count = value === undefined ? 1 : Number(value);
+    if (!Number.isInteger(count) || count < 1 || count > 4) throw new CanvasAgentApiError("Image output count must be between 1 and 4.", { code: "usage" });
+    return count;
+}
+
+function emptyIdleImageTarget(node) {
+    const metadata = node?.metadata || {};
+    if (metadata.storageKey || metadata.aiJobId) return false;
+    if (typeof metadata.content === "string" && metadata.content.trim()) return false;
+    if (metadata.status !== undefined && metadata.status !== "idle") return false;
+    if (metadata.listOutputId || metadata.batchRootId || metadata.isSection || metadata.isList || metadata.recipeInstance || metadata.isVisualRecipe) return false;
+    return true;
+}
+
+function matchesOptionalInvocationText(metadataValue, inputValue) {
+    return String(metadataValue || "").trim() === String(inputValue || "").trim();
+}
+
+/**
+ * True when this invocation's earlier claim on the node is still trustworthy:
+ * the claim digest matches and the node still carries the claimed prompt. A
+ * claim never overrides the current state of a node someone else repurposed —
+ * a changed prompt breaks the match and the invocation fails loudly instead of
+ * overwriting foreign work.
+ */
+function claimedByInvocation(node, digest, prompt) {
+    const metadata = node?.metadata || {};
+    return Boolean(digest) && metadata.agentTargetClaim === digest && String(metadata.prompt || "").trim() === prompt;
+}
+
+function workflowOwnedNodeIds(connections) {
+    const owned = new Set();
+    for (const connection of Array.isArray(connections) ? connections : []) {
+        if (connection?.fromRecipePortNodeId || connection?.toRecipePortNodeId || connection?.recipeMaterializedOutput) {
+            owned.add(connection.fromNodeId);
+            owned.add(connection.toNodeId);
+        }
+    }
+    return owned;
+}
+
+/**
+ * Image targets this invocation may fill instead of creating new nodes.
+ *
+ * Fresh candidates must be empty and idle, carry exactly the requested prompt
+ * and generation parameters, be unclaimed, and must not belong to a workflow:
+ * recipe-owned placeholders are filled by their own runs, so automatic reuse
+ * never touches a node with a recipe port edge or a workflow-output id. Nodes
+ * claimed by this invocation's digest stay candidates while they still carry
+ * the claimed prompt and are not workflow-owned, which keeps exact retries
+ * selecting the same nodes — and therefore replaying the same claim — after
+ * generation started, without ever adopting a node that was repurposed since.
+ * Sorted deterministically for identical selection across calls.
+ */
+export function reusableIdleImageTargets(nodes, connections, input, digest) {
+    const prompt = String(input?.prompt || "").trim();
+    if (!prompt) return [];
+    const workflowOwned = workflowOwnedNodeIds(connections);
+    return (Array.isArray(nodes) ? nodes : [])
+        .filter((node) => {
+            if (node?.type !== "image") return false;
+            const metadata = node.metadata || {};
+            if (workflowOwned.has(node.id) || String(node.id).startsWith("workflow-output-")) return false;
+            if (metadata.agentTargetClaim) return claimedByInvocation(node, digest, prompt);
+            if (!emptyIdleImageTarget(node)) return false;
+            if (String(metadata.prompt || "").trim() !== prompt) return false;
+            return matchesOptionalInvocationText(metadata.model, input.model) && matchesOptionalInvocationText(metadata.size, input.size) && matchesOptionalInvocationText(metadata.quality, input.quality);
+        })
+        .sort((left, right) => (left.position?.y ?? 0) - (right.position?.y ?? 0) || (left.position?.x ?? 0) - (right.position?.x ?? 0) || String(left.id).localeCompare(String(right.id)));
+}
+
+function automaticTargetDimensions(size, requestedWidth, requestedHeight) {
+    const sizeMatch = String(size || "").match(/^(\d{2,5})x(\d{2,5})$/i);
+    const aspect = sizeMatch ? Number(sizeMatch[2]) / Number(sizeMatch[1]) : 1;
+    const width = finiteCanvasNumber(requestedWidth) || 340;
+    const height = finiteCanvasNumber(requestedHeight) || Math.max(180, Math.min(720, Math.round(width * aspect)));
+    return { width, height };
+}
+
+function automaticTargetOrigin(nodes, dimensions, requestedX, requestedY) {
+    const bottom = nodes.reduce((maximum, node) => {
+        const y = finiteCanvasNumber(node?.position?.y, true) || 0;
+        const height = finiteCanvasNumber(node?.height) || dimensions.height;
+        return Math.max(maximum, y + height);
+    }, -80);
+    return {
+        x: finiteCanvasNumber(requestedX, true) ?? 0,
+        y: finiteCanvasNumber(requestedY, true) ?? bottom + 80,
+    };
+}
+
+function finiteCanvasNumber(value, allowZero = false) {
+    if (value === undefined || value === null || value === "") return undefined;
+    const number = Number(value);
+    if (!Number.isFinite(number)) throw new CanvasAgentApiError("Automatic target position and size values must be numbers.", { code: "usage" });
+    if (!allowZero && number <= 0) throw new CanvasAgentApiError("Automatic target width and height must be positive.", { code: "usage" });
+    return number;
+}
+
+export function normalizeBaseUrl(value) {
+    const raw = String(value || "").trim();
+    if (!raw) throw new CanvasAgentApiError("Gavana base URL is required. Run auth login or set GAVANA_BASE_URL.", { code: "configuration" });
+    let url;
+    try {
+        url = new URL(raw);
+    } catch (error) {
+        throw new CanvasAgentApiError("Gavana base URL is invalid.", { code: "configuration", cause: error });
+    }
+    const localHttp = url.protocol === "http:" && (url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "::1");
+    if (url.protocol !== "https:" && !localHttp) throw new CanvasAgentApiError("Gavana base URL must use HTTPS, except on local loopback.", { code: "configuration" });
+    if (url.username || url.password || url.search || url.hash) {
+        throw new CanvasAgentApiError("Gavana base URL cannot contain credentials, query parameters, or a fragment.", { code: "configuration" });
+    }
+    return url.toString().replace(/\/+$/, "");
+}
+
+export function markdownForResult(result) {
+    if (result?.status === "succeeded" && Array.isArray(result.images)) {
+        const lines = [`Created ${result.images.length} image${result.images.length === 1 ? "" : "s"}`, ""];
+        result.images.forEach((image, index) => {
+            lines.push(image.markdown || `[Preview image ${index + 1}](${image.previewUrl})`);
+            lines.push(`${image.assetId} · ${image.nodeId}`);
+            lines.push("");
+        });
+        if (result.destination?.canvasId) lines.push(`Destination: ${result.destination.canvasId}`);
+        if (result.canvasUrl) lines.push(`Review the full canvas: ${result.canvasUrl}`);
+        if (Array.isArray(result.warnings) && result.warnings.length) {
+            lines.push("", ...result.warnings.map((warning) => `Warning: ${warning}`));
+        }
+        return lines.join("\n").trim();
+    }
+    const preview = result?.asset?.previewUrl ? result.asset : result?.node?.previewUrl ? result.node : null;
+    if (preview) {
+        const label = preview.name || preview.title || preview.handle || "Gavana image";
+        return [`![${safeMarkdownAlt(label)}](${preview.previewUrl})`, preview.handle || preview.assetId || preview.node || ""].filter(Boolean).join("\n\n");
+    }
+    return `\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\``;
+}
+
+function cleanToken(value) {
+    const token = String(value || "").trim();
+    if (!token) throw new CanvasAgentApiError("Agent token is required. Run auth login or set GAVANA_AGENT_TOKEN.", { code: "configuration" });
+    if (/\s/.test(token)) throw new CanvasAgentApiError("Agent token is invalid.", { code: "configuration" });
+    return token;
+}
+
+function validateId(value, label) {
+    const id = String(value || "").trim();
+    if (!/^[A-Za-z0-9_-]{1,180}$/.test(id)) throw new CanvasAgentApiError(`${label} reference is invalid.`, { code: "usage" });
+    return id;
+}
+
+function invalidHandle(kind) {
+    return new CanvasAgentApiError(`Expected ${kind}:<id>${kind === "canvas" ? " or canvas:<ownerUid>:<id>" : ""}.`, { code: "usage" });
+}
+
+function capitalize(value) {
+    return `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+}
+
+function safeMarkdownAlt(value) {
+    return String(value || "Gavana image")
+        .replace(/[\[\]\n\r]/g, " ")
+        .slice(0, 100);
+}
+
+function positiveNumber(value, fallback, allowZero = false) {
+    const number = Number(value ?? fallback);
+    if (!Number.isFinite(number) || number < (allowZero ? 0 : 1)) return fallback;
+    return number;
+}
+
+function errorCodeForStatus(status) {
+    if (status === 400 || status === 422) return "validation";
+    if (status === 401) return "unauthorized";
+    if (status === 403) return "forbidden";
+    if (status === 404) return "not_found";
+    if (status === 409) return "conflict";
+    if (status === 429) return "rate_limited";
+    if (status >= 500) return "upstream";
+    return "request_failed";
+}