@gavana.ai/cli 0.2.0 → 0.2.2

package/src/runner.mjs

@@ -3,15 +3,17 @@ import { execFile as execFileCallback } from "node:child_process";
 import fs from "node:fs/promises";
 import http from "node:http";
 import path from "node:path";
+import { createInterface } from "node:readline/promises";
 import { promisify } from "node:util";
 
-import { CanvasAgentApiError, createCanvasAgentClient, markdownForResult } from "./client.mjs";
+import { CanvasAgentApiError, createCanvasAgentClient, markdownForResult, parseElementHandle } from "./client.mjs";
 import { GAVANA_CLI_VERSION, gavanaCapabilitySummary } from "./capabilities.mjs";
 import { GAVANA_CLI_GROUP_HELP, gavanaCommandActions, gavanaCommandGroupUsageLines, gavanaCommandGroups, gavanaCommandIsKnown, gavanaCommandUsageLines } from "./commands.mjs";
 import { agentConfigFilePath, listAgentProfiles, readAgentConfig, readAgentConfigMetadata, removeAgentProfile, setActiveAgentProfile, writeAgentConfig } from "./config.mjs";
+import { gavanaMcpClientDefinition } from "./mcp-targets.mjs";
 
-const BOOLEAN_OPTIONS = new Set(["help", "version", "pretty", "raw", "yes", "wait", "no-wait", "progress", "token-stdin", "no-verify", "no-browser", "audio", "no-audio", "read-only"]);
-const REPEATABLE_OPTIONS = new Set(["reference", "reference-role", "input", "param", "target", "ratio", "approved", "field"]);
+const BOOLEAN_OPTIONS = new Set(["help", "version", "pretty", "raw", "yes", "confirm", "rebase", "wait", "no-wait", "progress", "token-stdin", "no-verify", "no-browser", "audio", "no-audio", "read-only"]);
+const REPEATABLE_OPTIONS = new Set(["reference", "reference-role", "element", "input", "param", "target", "ratio", "approved", "field", "source-asset", "collection"]);
 const MAX_REFERENCE_IMAGES = 16;
 const MAX_VIDEO_REFERENCE_IMAGES = 9;
 const MAX_REFERENCE_IMAGE_BYTES = 50 * 1024 * 1024;
@@ -66,7 +68,7 @@ export async function runGavanaCli(argv = process.argv.slice(2), runtime = {}) {
             return 0;
         }
         if (group === "config") {
-            const result = await runConfigCommand(action, positionals, parsed.options, env);
+            const result = await runConfigCommand(action, positionals, parsed.options, env, runtime);
             writeResult(stdout, result, parsed.options);
             return 0;
         }
@@ -78,7 +80,7 @@ export async function runGavanaCli(argv = process.argv.slice(2), runtime = {}) {
 
         const selectedProfile = firstString(parsed.options.profile) || env.GAVANA_PROFILE || env.CRAFTBOARD_PROFILE || "";
         const profileEnv = selectedProfile ? { ...env, GAVANA_PROFILE: selectedProfile } : env;
-        const config = group === "mcp" ? await readAgentConfigMetadata(profileEnv) : await readAgentConfig(profileEnv);
+        const config = group === "mcp" ? await readAgentConfigMetadata(profileEnv) : await readAgentConfig(profileEnv, keychainDependencies(runtime));
         const token = firstString(parsed.options.token) || env.GAVANA_AGENT_TOKEN || env.CRAFTBOARD_AGENT_TOKEN || config.token;
         const baseUrl = firstString(parsed.options["base-url"]) || env.GAVANA_BASE_URL || env.CRAFTBOARD_BASE_URL || config.baseUrl || "https://app.gavana.ai";
         if (group === "mcp") {
@@ -91,6 +93,7 @@ export async function runGavanaCli(argv = process.argv.slice(2), runtime = {}) {
             writeResult(stdout, result, parsed.options);
             return result.ok ? 0 : 1;
         }
+        if (!token && config.credentialState === "inaccessible") throw keychainInaccessibleError();
         const client = createCanvasAgentClient({ token, baseUrl, surface: "cli", fetchImpl: runtime.fetchImpl });
         return await runTrackedRemoteCommand(client, `${group}.${String(action || "default").toLowerCase()}`, runtime.analyticsEnabled ?? !runtime.fetchImpl, async () => {
             if (group === "api") {
@@ -101,6 +104,9 @@ export async function runGavanaCli(argv = process.argv.slice(2), runtime = {}) {
                 env,
                 stderr,
                 readClipboardImage: runtime.readClipboardImage,
+                confirm: runtime.confirm,
+                stdin: runtime.stdin || process.stdin,
+                isInteractive: runtime.isInteractive ?? Boolean((runtime.stdin || process.stdin).isTTY && stderr.isTTY),
                 legacyCampaignCommandsEnabled:
                     runtime.legacyCampaignCommandsEnabled ??
                     (env.GAVANA_ENABLE_LEGACY_CAMPAIGN_COMMANDS === "true" ||
@@ -159,7 +165,8 @@ function exitCodeForResult(group, action, result) {
     const waitedJob = group === "job" && action === "wait";
     const waitedRun = group === "run" && action === "wait";
     const waitedRecipe = group === "recipe" && action === "run";
-    if ((waitedImage || waitedVideo || waitedAction || waitedJob || waitedRun || waitedRecipe) && (result?.status === "failed" || result?.status === "canceled" || result?.status === "expired")) return 9;
+    const terminalWorkFailure = group === "work" && action === "execute" && ["FAILED", "PARTIALLY_FAILED", "CANCELED"].includes(String(result?.status || "").toUpperCase());
+    if (((waitedImage || waitedVideo || waitedAction || waitedJob || waitedRun || waitedRecipe) && (result?.status === "failed" || result?.status === "canceled" || result?.status === "expired")) || terminalWorkFailure) return 9;
     return 0;
 }
 
@@ -206,6 +213,35 @@ async function executeCommand(client, group, action, args, options, runtime) {
         }
     }
 
+    if (group === "work") {
+        if (action === "prepare") {
+            const supplied = await optionalJsonInput(options);
+            return client.prepareWork(
+                supplied || {
+                    request: firstString(options.request) || args.join(" ") || requiredArg(args, 0, "work prepare requires --request."),
+                    ...(repeatableStrings(options.reference).length ? { references: repeatableStrings(options.reference) } : {}),
+                    ...(firstString(options.canvas) ? { canvasId: firstString(options.canvas) } : {}),
+                    idempotencyKey: firstString(options["idempotency-key"]),
+                },
+            );
+        }
+        if (action === "get") return client.getWork(firstString(options.work) || requiredArg(args, 0, "work get requires work:<id>."));
+        if (action === "refresh") return client.refreshWork(firstString(options.work) || requiredArg(args, 0, "work refresh requires work:<id>."));
+        if (action === "continue") {
+            const supplied = await optionalJsonInput(options);
+            const workId = firstString(options.work) || supplied?.workId || requiredArg(args, 0, "work continue requires work:<id>.");
+            const input = supplied ? omitKeys(supplied, ["workId"]) : workContinuationInput(options);
+            return client.continueWork(workId, input);
+        }
+        if (action === "execute") {
+            requireWorkConfirmation(options);
+            const supplied = await optionalJsonInput(options);
+            const workId = firstString(options.work) || supplied?.workId || requiredArg(args, 0, "work execute requires work:<id>.");
+            const input = supplied ? omitKeys(supplied, ["workId"]) : { confirm: true, idempotencyKey: firstString(options["idempotency-key"]) };
+            return client.executeWork(workId, input);
+        }
+    }
+
     if (group === "campaign") {
         if (action === "plan") {
             const supplied = await optionalJsonInput(options);
@@ -379,6 +415,45 @@ async function executeCommand(client, group, action, args, options, runtime) {
         }
     }
 
+    if (group === "element") {
+        if (action === "list") {
+            const state = firstString(options.state);
+            if (state && state !== "active" && state !== "archived") throw usageError("--state must be active or archived.");
+            return client.listElements({ query: firstString(options.query) || args.join(" "), ...(state ? { state } : {}) }, paginationOptions(options, 100));
+        }
+        if (action === "get") {
+            const elementId = requiredArg(args, 0, "element get requires element:<id>@v<n>.");
+            if (!parseElementHandle(elementId).version) throw usageError("element get requires an exact element:<id>@v<n> revision handle.");
+            return client.getElement(elementId);
+        }
+        if (action === "history") return client.listElementHistory(requiredArg(args, 0, "element history requires element:<id>."), paginationOptions(options, 100));
+        if (action === "create" || action === "update") {
+            const supplied = await optionalJsonInput(options);
+            const input = supplied || elementInputFromOptions(options);
+            if (action === "create") return client.createElement(input);
+            return client.updateElement(requiredArg(args, 0, "element update requires element:<id>."), input);
+        }
+        if (action === "collections") {
+            const supplied = await optionalJsonInput(options);
+            const collectionIds = supplied?.collectionIds === undefined ? repeatableStrings(options.collection) : supplied.collectionIds;
+            return client.updateElementCollections(requiredArg(args, 0, "element collections requires element:<id>."), collectionIds);
+        }
+        if (action === "archive") {
+            const elementId = requiredArg(args, 0, "element archive requires element:<id>.");
+            await requireDestructiveConfirmation(options, runtime, `Archive ${elementId}? It will remain restorable.`, "element archive is destructive. Re-run with --yes in non-interactive mode.");
+            return client.archiveElement(elementId);
+        }
+        if (action === "restore") return client.restoreElement(requiredArg(args, 0, "element restore requires element:<id>."));
+        if (action === "collection-list") return client.listElementCollections(paginationOptions(options, 100));
+        if (action === "collection-create") return client.createElementCollection({ name: firstString(options.name) || args.join(" ") });
+        if (action === "collection-rename") return client.updateElementCollection(requiredArg(args, 0, "element collection-rename requires element-collection:<id>."), { name: firstString(options.name) || requiredArg(args, 1, "element collection-rename requires --name.") });
+        if (action === "collection-delete") {
+            const collectionId = requiredArg(args, 0, "element collection-delete requires element-collection:<id>.");
+            await requireDestructiveConfirmation(options, runtime, `Delete ${collectionId}? This removes the collection, not its Elements.`, "element collection-delete is destructive. Re-run with --yes in non-interactive mode.");
+            return client.deleteElementCollection(collectionId);
+        }
+    }
+
     if (group === "ai-connection" || group === "provider") {
         if (action === "list") return client.listConnections(paginationOptions(options, 100));
     }
@@ -429,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,
@@ -551,7 +626,7 @@ async function runAuthCommand(action, _args, options, env, runtime) {
     if (action === "login") {
         const profile = firstString(options.profile) || env.GAVANA_PROFILE || env.CRAFTBOARD_PROFILE || "";
         const profileEnv = profile ? { ...env, GAVANA_PROFILE: profile } : env;
-        const current = await readAgentConfig(profileEnv);
+        const current = await readAgentConfig(profileEnv, keychainDependencies(runtime));
         let token = firstString(options.token) || env.GAVANA_AGENT_TOKEN || env.CRAFTBOARD_AGENT_TOKEN || (options["token-stdin"] === true ? (await readAllStdin()).trim() : "");
         const baseUrl = createCanvasAgentClient({
             token: "configuration-validation",
@@ -593,10 +668,21 @@ async function runAuthCommand(action, _args, options, env, runtime) {
     if (action === "status") {
         const profile = firstString(options.profile) || env.GAVANA_PROFILE || env.CRAFTBOARD_PROFILE || "";
         const profileEnv = profile ? { ...env, GAVANA_PROFILE: profile } : env;
-        const config = await readAgentConfig(profileEnv);
+        const config = await readAgentConfig(profileEnv, keychainDependencies(runtime));
         const token = firstString(options.token) || env.GAVANA_AGENT_TOKEN || env.CRAFTBOARD_AGENT_TOKEN || config.token;
         const baseUrl = firstString(options["base-url"]) || env.GAVANA_BASE_URL || env.CRAFTBOARD_BASE_URL || config.baseUrl;
-        if (!token || !baseUrl) return { authenticated: false, configured: false, configPath: agentConfigFilePath(env) };
+        if (!token || !baseUrl) {
+            return {
+                authenticated: false,
+                configured: false,
+                profile: config.profile,
+                baseUrl: baseUrl || "",
+                credentialStore: config.credentialStore || "",
+                credentialState: config.credentialState,
+                ...(config.credentialState === "inaccessible" ? { detail: keychainInaccessibleError().message } : {}),
+                configPath: agentConfigFilePath(env),
+            };
+        }
         const client = createCanvasAgentClient({ token, baseUrl, surface: "cli", fetchImpl });
         const verification = await verifyAuthentication(client);
         let canvasCount = verification.canvasCount;
@@ -612,9 +698,11 @@ async function runAuthCommand(action, _args, options, env, runtime) {
         return {
             ...verification,
             profile: config.profile,
-            configured: Boolean(config.token && config.baseUrl),
+            configured: Boolean(config.credentialState === "available" && config.baseUrl),
             baseUrl: client.baseUrl,
             token: maskToken(token),
+            credentialStore: config.credentialStore || "",
+            credentialState: config.credentialState,
             ...(canvasCount === undefined ? {} : { canvasCount }),
             configPath: agentConfigFilePath(env),
         };
@@ -622,7 +710,7 @@ async function runAuthCommand(action, _args, options, env, runtime) {
     if (action === "logout") {
         const profile = firstString(options.profile) || env.GAVANA_PROFILE || env.CRAFTBOARD_PROFILE || "";
         const profileEnv = profile ? { ...env, GAVANA_PROFILE: profile } : env;
-        const config = await readAgentConfig(profileEnv);
+        const config = await readAgentConfig(profileEnv, keychainDependencies(runtime));
         if (config.authMode === "oauth" && config.token && config.baseUrl) {
             await revokeBrowserOAuthToken(config.baseUrl, config.token, fetchImpl || globalThis.fetch);
         }
@@ -653,7 +741,7 @@ export async function performBrowserOAuthLogin({ baseUrl, readOnly = false, noBr
     const state = crypto.randomBytes(24).toString("base64url");
     const callback = runtime.createOAuthCallbackServer ? await runtime.createOAuthCallbackServer(state) : await createOAuthCallbackServer(state);
     try {
-        const scopes = readOnly ? "canvas:read asset:read" : "canvas:read canvas:write asset:read image:generate video:generate job:manage";
+        const scopes = readOnly ? "canvas:read asset:read element:read" : "canvas:read canvas:write asset:read element:read element:write image:generate video:generate job:manage";
         const registrationResponse = await fetchImpl(`${origin}/oauth/register`, {
             method: "POST",
             headers: { "Content-Type": "application/json", Accept: "application/json" },
@@ -757,20 +845,31 @@ async function openBrowser(url) {
     return execFile("xdg-open", [url]);
 }
 
-async function runConfigCommand(action, args, options, env) {
-    if (action === "list" || action === "profiles" || !action) return listAgentProfiles(env);
+async function runConfigCommand(action, args, options, env, runtime = {}) {
+    if (action === "list" || action === "profiles" || !action) {
+        const result = await listAgentProfiles(env, keychainDependencies(runtime));
+        return {
+            ...result,
+            profiles: result.profiles.map((profile) =>
+                profile.credentialState === "inaccessible" ? { ...profile, detail: keychainInaccessibleError().message } : profile,
+            ),
+        };
+    }
     if (action === "use") {
         const profile = firstString(options.profile) || requiredArg(args, 0, "config use requires a profile name.");
         return { active: true, ...(await setActiveAgentProfile(profile, env)) };
     }
     if (action === "get") {
         const profile = firstString(options.profile) || args[0] || "";
-        const config = await readAgentConfig(profile ? { ...env, GAVANA_PROFILE: profile } : env);
+        const config = await readAgentConfig(profile ? { ...env, GAVANA_PROFILE: profile } : env, keychainDependencies(runtime));
         return {
             profile: config.profile,
             baseUrl: config.baseUrl || "",
-            configured: Boolean(config.token && config.baseUrl),
+            configured: Boolean(config.credentialState === "available" && config.baseUrl),
             token: config.token ? maskToken(config.token) : "",
+            credentialStore: config.credentialStore || "",
+            credentialState: config.credentialState,
+            ...(config.credentialState === "inaccessible" ? { detail: keychainInaccessibleError().message } : {}),
             configPath: agentConfigFilePath(env),
         };
     }
@@ -778,17 +877,18 @@ async function runConfigCommand(action, args, options, env) {
 }
 
 async function runDoctor(client, config, env, baseUrl, credentialSource = "") {
+    const credentialInaccessible = config.credentialState === "inaccessible" && !credentialSource;
     const checks = [
         { name: "node", ok: Number(process.versions.node.split(".")[0]) >= 20, detail: process.version },
         {
             name: "credentials",
             ok: Boolean(client),
-            detail: credentialSource || (config.token && config.baseUrl ? agentConfigFilePath(env) : client ? "Environment or command-line override" : "Run gavana auth login or set GAVANA_AGENT_TOKEN."),
+            detail: credentialInaccessible ? keychainInaccessibleError().message : credentialSource || (config.token && config.baseUrl ? agentConfigFilePath(env) : client ? "Environment or command-line override" : "Run gavana auth login or set GAVANA_AGENT_TOKEN."),
         },
         { name: "base_url", ok: /^https:\/\//.test(baseUrl) || /^http:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?(?:\/|$)/.test(baseUrl), detail: baseUrl },
     ];
     if (!client) {
-        checks.push({ name: "authentication", ok: false, detail: "No token is configured. Run gavana auth login." });
+        checks.push({ name: "authentication", ok: false, detail: credentialInaccessible ? keychainInaccessibleError().message : "No token is configured. Run gavana auth login." });
         return { ok: false, profile: config.profile, checks };
     }
     try {
@@ -801,6 +901,14 @@ async function runDoctor(client, config, env, baseUrl, credentialSource = "") {
     return { ok: checks.every((check) => check.ok), profile: config.profile, checks };
 }
 
+function keychainDependencies(runtime) {
+    return runtime.readKeychainCredential ? { readKeychainCredential: runtime.readKeychainCredential } : {};
+}
+
+function keychainInaccessibleError() {
+    return new CanvasAgentApiError("The configured macOS Keychain credential is inaccessible to this process. Run this command from a Keychain-authorized terminal or provide GAVANA_AGENT_TOKEN for this invocation; do not log in again unless the credential is actually missing.", { code: "keychain_inaccessible" });
+}
+
 async function runApiCommand(client, methodOrPath, args, options) {
     const knownMethod = /^(get|post|put|patch|delete)$/i.test(methodOrPath || "");
     const method = knownMethod ? methodOrPath.toUpperCase() : "GET";
@@ -823,34 +931,16 @@ async function runMcpCommand(action, args, options, baseUrl, runtime) {
     if (action !== "install" && action !== "config") throw usageError("mcp supports install and config.");
     const clientName = (firstString(options.client) || args[0] || "codex").toLowerCase();
     if (action === "install" && clientName !== "codex" && clientName !== "claude") {
-        throw usageError("mcp install supports codex and claude. Use mcp config for cursor, chatgpt, or local clients.");
+        throw usageError("mcp install supports codex and claude. Use mcp config for cursor, vscode, chatgpt, or local clients.");
     }
-    const endpoint = `${baseUrl}${options["read-only"] === true ? "/mcp/readonly" : "/mcp"}`;
-    const definition = mcpClientDefinition(clientName, endpoint, options["read-only"] === true);
+    const definition = gavanaMcpClientDefinition(clientName, baseUrl, options["read-only"] === true);
+    if (!definition) throw usageError("mcp client must be codex, claude, cursor, vscode, chatgpt, or local.");
     if (action === "config" || !definition.command) return definition;
     const execute = runtime.execFile || execFile;
     await execute(definition.command, definition.args);
     return { ...definition, installed: true };
 }
 
-function mcpClientDefinition(clientName, endpoint, readOnly = false) {
-    if (clientName === "codex") return { client: "codex", transport: "streamable-http", endpoint, command: "codex", args: ["mcp", "add", "gavana", "--url", endpoint] };
-    if (clientName === "claude") return { client: "claude", transport: "streamable-http", endpoint, command: "claude", args: ["mcp", "add", "--transport", "http", "gavana", endpoint] };
-    if (clientName === "cursor") return { client: "cursor", transport: "streamable-http", endpoint, config: { mcpServers: { gavana: { url: endpoint } } } };
-    if (clientName === "chatgpt") return { client: "chatgpt", transport: "streamable-http", endpoint, instructions: "Add the endpoint as a custom MCP connector, then complete Gavana OAuth in the browser." };
-    if (clientName === "stdio" || clientName === "local") {
-        return {
-            client: "local",
-            transport: "stdio",
-            command: "npx",
-            args: ["-y", "@gavana.ai/mcp@0.2.0"],
-            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.",
-        };
-    }
-    throw usageError("mcp client must be codex, claude, cursor, chatgpt, or local.");
-}
-
 function completionScript(shell) {
     // Generated from the command table, so a new command is completable the moment
     // it is declared. This list used to be a third hand-maintained copy of the
@@ -1108,6 +1198,20 @@ async function imageInput(client, operation, args, options, runtime) {
     const count = supplied.count !== undefined || options.count !== undefined ? (supplied.count ?? requiredNumber(options.count, "--count must be a number.")) : undefined;
     if (count !== undefined && (!Number.isInteger(Number(count)) || Number(count) < 1 || Number(count) > 4)) throw usageError("--count must be an integer between 1 and 4.");
     const referenceInputs = imageReferenceInputs(supplied.references, options.reference, supplied.referenceRoles, options["reference-role"]);
+    const optionElements = repeatableStrings(options.element);
+    if (supplied.elements !== undefined && optionElements.length) throw usageError("Set Elements in JSON or with --element, not both.");
+    const elements = supplied.elements === undefined ? optionElements : Array.isArray(supplied.elements) ? supplied.elements : (() => { throw usageError("elements must be an array."); })();
+    if (elements.length > 8) throw usageError("An image job can use up to 8 Elements.");
+    for (const entry of elements) {
+        const typed = entry && typeof entry === "object" && !Array.isArray(entry) ? entry : null;
+        if (typed && Object.keys(typed).some((key) => key !== "handle" && key !== "role" && key !== "influence")) throw usageError('An Element reference may contain only "handle", "role", and "influence".');
+        const handle = typeof entry === "string" ? entry.trim() : typeof typed?.handle === "string" ? typed.handle.trim() : "";
+        if (!/^element:[A-Za-z0-9_-]{1,160}@v[1-9][0-9]*$/.test(handle)) throw usageError("Each --element must be a version-pinned element:<id>@v<n> handle.");
+        if (typed?.role !== undefined && !["identity", "construction", "texture", "fit", "style"].includes(typed.role)) throw usageError("Element roles must be identity, construction, texture, fit, or style.");
+        if (typed?.influence !== undefined && (typeof typed.influence !== "number" || !Number.isFinite(typed.influence) || typed.influence < 0 || typed.influence > 1)) throw usageError("Element influence must be a number from 0 through 1.");
+    }
+    const elementHandles = elements.map((entry) => (typeof entry === "string" ? entry.trim() : entry.handle.trim()));
+    if (new Set(elementHandles).size !== elementHandles.length) throw usageError("Element handles must be unique.");
     const preparedReferences = await prepareReferenceInputs(referenceInputs.map((reference) => reference.value), runtime);
     const canvasResult = await client.resolveCanvasDestination(destination, {
         idempotencyKey,
@@ -1145,6 +1249,7 @@ async function imageInput(client, operation, args, options, runtime) {
         targetY: _targetY,
         targetWidth: _targetWidth,
         targetHeight: _targetHeight,
+        elements: _elements,
         ...jobSupplied
     } = supplied;
     return {
@@ -1156,6 +1261,7 @@ async function imageInput(client, operation, args, options, runtime) {
         ...(prompt ? { prompt } : {}),
         ...(supplied.promptNodeId || firstString(options["prompt-node"]) ? { promptNodeId: supplied.promptNodeId || firstString(options["prompt-node"]) } : {}),
         ...(references.length ? { references: references.some((reference) => reference.role) ? references : referenceHandles } : {}),
+        ...(elements.length ? { elements } : {}),
         ...(source ? { source } : {}),
         ...(supplied.connectionId || firstString(options.connection) ? { connectionId: supplied.connectionId || firstString(options.connection) } : {}),
         ...(supplied.model || firstString(options.model) ? { model: supplied.model || firstString(options.model) } : {}),
@@ -1474,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() {
@@ -1763,6 +1863,7 @@ function exitCodeForError(error) {
     if (
         error.code === "usage" ||
         error.code === "configuration" ||
+        error.code === "keychain_inaccessible" ||
         error.code === "validation" ||
         error.code === "input_validation_error" ||
         error.code === "invalid_json" ||
@@ -1786,10 +1887,55 @@ function requiredArg(args, index, message) {
     return value;
 }
 
+function workContinuationInput(options) {
+    const action = firstString(options.action);
+    const idempotencyKey = firstString(options["idempotency-key"]);
+    if (action === "answer") return { action, answer: firstString(options.answer), idempotencyKey };
+    if (action === "select_direction") return { action, directionId: firstString(options["direction-id"]), idempotencyKey };
+    if (action === "adjust") return { action, adjustment: firstString(options.adjustment), idempotencyKey };
+    if (action === "acknowledge_canvas") return { action, idempotencyKey };
+    if (options.rebase === true) return { rebase: true, idempotencyKey };
+    throw usageError("work continue requires --action answer, select_direction, adjust, acknowledge_canvas, or --rebase.");
+}
+
+function omitKeys(value, keys) {
+    return Object.fromEntries(Object.entries(value).filter(([key]) => !keys.includes(key)));
+}
+
 function requireConfirmation(options, message) {
     if (options.yes !== true) throw usageError(message);
 }
 
+function requireWorkConfirmation(options) {
+    if (options.confirm !== true) throw usageError("work execute starts paid work. Re-run with --confirm.");
+}
+
+async function requireDestructiveConfirmation(options, runtime, prompt, nonInteractiveMessage) {
+    if (options.yes === true) return;
+    if (!runtime.isInteractive) throw usageError(nonInteractiveMessage);
+    const confirmed = typeof runtime.confirm === "function" ? await runtime.confirm(prompt) : await promptForConfirmation(runtime.stdin, runtime.stderr, prompt);
+    if (!confirmed) throw usageError("Destructive operation cancelled.");
+}
+
+async function promptForConfirmation(input, output, prompt) {
+    const terminal = createInterface({ input, output, terminal: true });
+    try {
+        return /^(y|yes)$/i.test((await terminal.question(`${prompt} [y/N] `)).trim());
+    } finally {
+        terminal.close();
+    }
+}
+
+function elementInputFromOptions(options) {
+    return {
+        name: firstString(options.name),
+        type: firstString(options.type),
+        sourceAssetIds: repeatableStrings(options["source-asset"]),
+        ...(firstString(options.guidelines) ? { guidelines: firstString(options.guidelines) } : {}),
+        ...(repeatableStrings(options.collection).length ? { collectionIds: repeatableStrings(options.collection) } : {}),
+    };
+}
+
 function parseJsonOption(value, message) {
     const text = firstString(value);
     return text ? parseJson(text, message) : null;
@@ -1900,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/campaign_plan.mjs

@@ -7,8 +7,8 @@ import { campaignAspectRatio, campaignIdempotencyKey, campaignProductReference,
 
 export function defineCampaignPlan(client) {
     return {
-        title: "Legacy campaign plan",
-        description: "Compatibility operation for an existing campaign integration. Do not use it for new work; use editable canvas blocks and explicit image jobs instead.",
+        title: "Retired campaign plan (migration only)",
+        description: "Compatibility operation for an existing historical campaign integration. The server rejects mutations unless its explicit migration flag is enabled. Do not use it for new creative work; use editable Canvas Sections, reference nodes, and explicit image jobs instead.",
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: z.object({
             canvasId: exactCanvasReference,

package/src/tools/campaign_review.mjs

@@ -7,8 +7,8 @@ import { approvedOutputReferences, campaignIdempotencyKey, runReference } from "
 
 export function defineCampaignReview(client) {
     return {
-       title: "Legacy campaign review",
-       description: "Compatibility operation for an existing campaign record. New work should remain editable on the canvas.",
+       title: "Retired campaign review (migration only)",
+       description: "Compatibility operation for an existing historical campaign record. This old approval gate is not for new creative work; keep new directions editable and spatially organized on the Canvas.",
        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
        inputSchema: z.object({
            runId: runReference,

package/src/tools/campaign_start.mjs

@@ -7,8 +7,8 @@ import { campaignIdempotencyKey, campaignReference } from "./schemas.mjs";
 
 export function defineCampaignStart(client) {
     return {
-       title: "Legacy campaign start",
-       description: "Compatibility operation for an existing campaign record. Do not use it as a new-work workflow.",
+       title: "Retired campaign start (migration only)",
+       description: "Starts an existing historical campaign record only when the server's explicit compatibility migration flag is enabled. Its old review gate is not a creative workflow; use editable Canvas Sections, reference nodes, and explicit image jobs for new work.",
        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
        inputSchema: z.object({
            campaignId: campaignReference,

package/src/tools/definitions.mjs

@@ -31,6 +31,18 @@ import { defineCanvasList } from "./canvas_list.mjs";
 import { defineCanvasValidate } from "./canvas_validate.mjs";
 import { defineConnectionCreate } from "./connection_create.mjs";
 import { defineConnectionDelete } from "./connection_delete.mjs";
+import { defineElementArchive } from "./element_archive.mjs";
+import { defineElementCollectionCreate } from "./element_collection_create.mjs";
+import { defineElementCollectionDelete } from "./element_collection_delete.mjs";
+import { defineElementCollectionList } from "./element_collection_list.mjs";
+import { defineElementCollectionUpdate } from "./element_collection_update.mjs";
+import { defineElementCreate } from "./element_create.mjs";
+import { defineElementGet } from "./element_get.mjs";
+import { defineElementHistory } from "./element_history.mjs";
+import { defineElementList } from "./element_list.mjs";
+import { defineElementRestore } from "./element_restore.mjs";
+import { defineElementUpdate } from "./element_update.mjs";
+import { defineElementUpdateCollections } from "./element_update_collections.mjs";
 import { defineGuideGet } from "./guide_get.mjs";
 import { defineGuideSearch } from "./guide_search.mjs";
 import { defineJobCancel } from "./job_cancel.mjs";
@@ -53,6 +65,11 @@ import { defineRunCancel } from "./run_cancel.mjs";
 import { defineRunGet } from "./run_get.mjs";
 import { defineRunWait } from "./run_wait.mjs";
 import { defineVideoGenerate } from "./video_generate.mjs";
+import { defineWorkContinue } from "./work_continue.mjs";
+import { defineWorkExecute } from "./work_execute.mjs";
+import { defineWorkGet } from "./work_get.mjs";
+import { defineWorkPrepare } from "./work_prepare.mjs";
+import { defineWorkRefresh } from "./work_refresh.mjs";
 
 /** @type {Record<string, (client: unknown) => object>} */
 export const GAVANA_TOOL_DEFINITIONS = Object.freeze({
@@ -79,6 +96,18 @@ export const GAVANA_TOOL_DEFINITIONS = Object.freeze({
     canvas_validate: defineCanvasValidate,
     connection_create: defineConnectionCreate,
     connection_delete: defineConnectionDelete,
+    element_archive: defineElementArchive,
+    element_collection_create: defineElementCollectionCreate,
+    element_collection_delete: defineElementCollectionDelete,
+    element_collection_list: defineElementCollectionList,
+    element_collection_update: defineElementCollectionUpdate,
+    element_create: defineElementCreate,
+    element_get: defineElementGet,
+    element_history: defineElementHistory,
+    element_list: defineElementList,
+    element_restore: defineElementRestore,
+    element_update: defineElementUpdate,
+    element_update_collections: defineElementUpdateCollections,
     guide_get: defineGuideGet,
     guide_search: defineGuideSearch,
     job_cancel: defineJobCancel,
@@ -101,6 +130,11 @@ export const GAVANA_TOOL_DEFINITIONS = Object.freeze({
     run_get: defineRunGet,
     run_wait: defineRunWait,
     video_generate: defineVideoGenerate,
+    work_continue: defineWorkContinue,
+    work_execute: defineWorkExecute,
+    work_get: defineWorkGet,
+    work_prepare: defineWorkPrepare,
+    work_refresh: defineWorkRefresh,
 });
 
 /** Build every local tool config for a client, in registry order. */

package/src/tools/element_archive.mjs

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { mutableElementReference } from "./schemas.mjs";
+
+export function defineElementArchive(client) {
+    return {
+        title: "Archive a Gavana Element",
+        description: "Archive an Element. First read and show the affected Element to the user; it stays recoverable and confirm must be true only after explicit approval.",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({ elementId: mutableElementReference, confirm: z.literal(true).describe("Must be true after the user confirms archival.") }),
+        handler: ({ elementId }) => client.archiveElement(elementId),
+    };
+}

package/src/tools/element_collection_create.mjs

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export function defineElementCollectionCreate(client) {
+    return {
+        title: "Create an Element collection",
+        description: "Create a user-owned collection for organizing Elements.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        inputSchema: z.object({ name: z.string().min(1).max(120) }),
+        handler: (input) => client.createElementCollection(input),
+    };
+}

package/src/tools/element_collection_delete.mjs

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { elementCollectionReference } from "./schemas.mjs";
+
+export function defineElementCollectionDelete(client) {
+    return {
+        title: "Delete an Element collection",
+        description: "Delete a collection without deleting its Elements. First show the affected collection to the user; confirm must be true only after explicit approval.",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({ collectionId: elementCollectionReference, confirm: z.literal(true).describe("Must be true after the user confirms deletion.") }),
+        handler: ({ collectionId }) => client.deleteElementCollection(collectionId),
+    };
+}

package/src/tools/element_collection_list.mjs

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { listOptions } from "./helpers.mjs";
+import { listCursor, listLimit } from "./schemas.mjs";
+
+export function defineElementCollectionList(client) {
+    return {
+        title: "List Element collections",
+        description: "List the user's Element collections.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({ limit: listLimit(100), cursor: listCursor }),
+        handler: ({ limit, cursor }) => client.listElementCollections(listOptions(limit, cursor)),
+    };
+}