@genspark/cli 1.5.0 → 1.5.2

package/dist/index.js

@@ -26,14 +26,15 @@ import * as os from 'os';
 import * as pathModule from 'path';
 import { createRequire } from 'module';
 import { spawn } from 'child_process';
-import { ApiClient, unauthenticatedRequest } from './client.js';
-import { classifyFileArg, awaitLocalFileReady, decideAfterWait, localFileNotReadyError, } from './localFiles.js';
-import { setDebugEnabled, setOutputFormat, debug, info, error as logError, output, } from './logger.js';
+import { ApiClient, isAuthError, unauthenticatedRequest, } from './client.js';
+import { classifyFileArg, awaitLocalFileReady, decideAfterWait, localFileNotReadyError, passthroughWarning, } from './localFiles.js';
+import { setDebugEnabled, setOutputFormat, debug, info, warn, error as logError, output, } from './logger.js';
 import { loadConfigFile, getConfigPath, loadToolsCache, normalizeBaseUrl, saveToolsCache, setConfigPathOverride, updateConfigFile, } from './config.js';
 import { checkForUpdates } from './updater.js';
+import { shimLegacyTaskInvocation } from './task-shim.js';
 import { getSandboxRuntime } from './runtime.js';
 import { registerDesignCommand } from './commands/design.js';
-import { pickExistingFileOperand } from './commands/aidrive-upload.js';
+import { collectUploadFiles, pickExistingUploadOperand, } from './commands/aidrive-upload.js';
 import { parseLastSeenIndex, eventStdoutLine } from './commands/chat-events.js';
 import { mediaItemsKeyFor, mediaSummaryLines } from './mediaSummary.js';
 import { registerMeshCommand, getMeshInvocation, runMesh, } from './commands/mesh.js';
@@ -157,6 +158,7 @@ const CONTENT_TYPE_MAP = {
     '.png': 'image/png',
     '.gif': 'image/gif',
     '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
     '.pdf': 'application/pdf',
     '.txt': 'text/plain',
     '.json': 'application/json',
@@ -164,6 +166,20 @@ const CONTENT_TYPE_MAP = {
     '.css': 'text/css',
     '.js': 'application/javascript',
     '.ts': 'application/typescript',
+    '.jsx': 'text/javascript',
+    '.tsx': 'text/typescript',
+    '.vue': 'text/html',
+    '.py': 'text/x-python',
+    '.java': 'text/x-java-source',
+    '.go': 'text/x-go',
+    '.rs': 'text/x-rust',
+    '.c': 'text/x-c',
+    '.cc': 'text/x-c++',
+    '.cpp': 'text/x-c++',
+    '.h': 'text/x-c',
+    '.hpp': 'text/x-c++',
+    '.yaml': 'application/x-yaml',
+    '.yml': 'application/x-yaml',
     '.md': 'text/markdown',
     '.xml': 'application/xml',
     '.csv': 'text/csv',
@@ -173,6 +189,46 @@ const CONTENT_TYPE_MAP = {
     '.wav': 'audio/wav',
     '.webm': 'video/webm',
 };
+/** Preserve interleaved --image/--file order; Commander groups options by key. */
+export function collectDesignAttachmentArgs(argv) {
+    const result = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        const equalsMatch = token.match(/^--(image|file)=(.+)$/);
+        if (equalsMatch) {
+            result.push({
+                path: equalsMatch[2],
+                role: equalsMatch[1] === 'image' ? 'visual_reference' : 'context',
+            });
+            continue;
+        }
+        if (token !== '--image' && token !== '--file')
+            continue;
+        const role = token === '--image' ? 'visual_reference' : 'context';
+        while (index + 1 < argv.length && !argv[index + 1].startsWith('-')) {
+            result.push({ path: argv[index + 1], role });
+            index += 1;
+        }
+    }
+    return result;
+}
+async function uploadDesignAttachments(values, client) {
+    const attachments = [];
+    // Upload the complete batch before executeTool: any failure aborts project
+    // creation/continuation rather than leaving a half-bound Design project.
+    for (const value of values) {
+        const localPath = expandHome(value.path);
+        if (!isLocalFilePath(localPath)) {
+            throw new Error(`File not found: ${value.path}`);
+        }
+        const name = pathModule.basename(localPath);
+        const ext = pathModule.extname(localPath).toLowerCase();
+        const mimeType = CONTENT_TYPE_MAP[ext] || 'application/octet-stream';
+        const url = await uploadLocalFile(localPath, client);
+        attachments.push({ url, name, mime_type: mimeType, role: value.role });
+    }
+    return attachments;
+}
 /**
  * Stream a local file to a URL using Node.js http/https.request +
  * fs.createReadStream so the file is never fully buffered in memory.
@@ -296,7 +352,7 @@ async function uploadLocalFile(filePath, client) {
  *
  * This avoids the roundabout blob-upload + download_file two-step approach.
  */
-async function uploadToAiDrive(filePath, uploadPath, override = false) {
+async function uploadToAiDrive(filePath, uploadPath, override = false, workspace = 'personal') {
     const fileName = pathModule.basename(filePath);
     const ext = pathModule.extname(filePath).toLowerCase();
     const contentType = CONTENT_TYPE_MAP[ext] || 'application/octet-stream';
@@ -304,7 +360,7 @@ async function uploadToAiDrive(filePath, uploadPath, override = false) {
     info(`Uploading ${fileName} (${formatFileSize(fileSize)}, ${contentType}) directly to AI Drive...`);
     const globalOpts = getGlobalOptions();
     const baseUrl = globalOpts.baseUrl.replace(/\/$/, '');
-    const uploadUrl = `${baseUrl}/api/tool_cli/aidrive/upload?upload_path=${encodeURIComponent(uploadPath)}${override ? '&override=true' : ''}`;
+    const uploadUrl = `${baseUrl}/api/tool_cli/aidrive/upload?upload_path=${encodeURIComponent(uploadPath)}&workspace=${encodeURIComponent(workspace)}${override ? '&override=true' : ''}`;
     const headers = { 'Content-Type': contentType };
     if (globalOpts.apiKey)
         headers['X-Api-Key'] = globalOpts.apiKey;
@@ -362,7 +418,9 @@ async function resolveFileArg(value, client) {
         case 'passthrough':
             // No local evidence beyond the parent directory: let the backend try
             // it as an AI Drive path (its failure mode is a per-URL actionable
-            // error, not a generic one).
+            // error, not a generic one). Warn first so a failed producer in the
+            // same batch is diagnosable from this call's own output.
+            warn(passthroughWarning(localPath, readiness));
             return value;
     }
 }
@@ -586,6 +644,12 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
     }
     const props = tool.parameters?.properties || {};
     const required = tool.parameters?.required || [];
+    // When --args-file is on the command line, required params may live in
+    // the file, which Commander cannot see — its parse-time required checks
+    // would reject the invocation before the file is ever read. Register
+    // everything optional in that case; the action handler re-validates the
+    // required set AFTER the file merge (#46011).
+    const argsFileInvoked = process.argv.some(a => a === '--args-file' || a.startsWith('--args-file='));
     // If primary_arg is set, make it a positional argument
     if (tool.cli.primary_arg && props[tool.cli.primary_arg]) {
         const param = props[tool.cli.primary_arg];
@@ -599,7 +663,9 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
         // usage say e.g. "missing required argument 'deck'" instead of 'value'
         // (#43556: the anonymous form sent agents guessing).
         const argName = tool.cli.primary_arg;
-        const bracket = isRequired && !isServiceAction ? `<${argName}>` : `[${argName}]`;
+        const bracket = isRequired && !isServiceAction && !argsFileInvoked
+            ? `<${argName}>`
+            : `[${argName}]`;
         cmd.argument(bracket, param.description || argName);
     }
     // Add remaining params as --options
@@ -614,7 +680,8 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
         // requiredOption would block every invocation before the action handler
         // (and its collector) ever runs.
         const isRequired = tool.name === 'create_task' ||
-            (tool.name === 'skills_save' && name === 'files')
+            (tool.name === 'skills_save' && name === 'files') ||
+            argsFileInvoked
             ? false
             : required.includes(name);
         const paramType = Array.isArray(param.type) ? param.type[0] : param.type;
@@ -677,17 +744,34 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
         cmd.option('--attach <values...>', 'Attach local files or URLs (alias for --attachments; repeatable)');
         cmd.option('--attachment <values...>', 'Attach local files or URLs (alias for --attachments; repeatable)');
     }
+    // Quoting-hazard-free input path (#46011): a shell-invoked agent passing
+    // rich text in double quotes gets `$`-tokens expanded before gsk sees
+    // argv ("$150k" → "50k"). A JSON file / stdin never crosses shell quoting.
+    cmd.option('--args-file <path>', 'Read arguments from a JSON object file ("-" = stdin). File keys ' +
+        'override flag values. Use for rich text (strings containing $, ' +
+        'quotes, newlines) instead of double-quoted flags. Server ' +
+        'parameters only — CLI-only options (e.g. --local_file) must ' +
+        'still be passed as flags.');
     // Add -o/--output-file option for tools that produce downloadable files
     const outputFileKeys = tool.cli.output_file_keys || [];
     if (outputFileKeys.length > 0) {
         cmd.option('-o, --output-file <path>', 'Download the generated file to a local path');
     }
+    // task ask (task_continue) shares the async-first submit → --follow
+    // upgrades the stub into a live SSE follow, same as task create.
+    // (Named --follow, not --attach: tools with an attachments array param
+    // already own --attach as a file alias.)
+    if (tool.name === 'task_continue') {
+        cmd.option('--follow', 'After the async submit, follow the durable run live (SSE) and exit with the terminal result', false);
+    }
     // For create_task, add --acp flag to enter ACP stdio bridge mode
     if (tool.name === 'create_task') {
         cmd.option('--acp', 'Start as ACP (Agent Client Protocol) stdio agent instead of one-shot execution', false);
+        cmd.option('--follow', 'After the async submit, follow the durable run live (SSE) and exit with the terminal result', false);
         cmd.option('-o, --output-file <path>', 'Export the artifact (pptx/docx/xlsx) to a local file after task completes');
         cmd.option('--session-id <id>', 'ACP session ID (used with get-project)');
-        cmd.option('--file <values...>', 'Import local CSV/Excel files into the task (auto-uploaded to blob storage)');
+        cmd.option('--file <values...>', 'Import local files (Design: structured context; other tasks: CSV/Excel file_urls)');
+        cmd.option('--image <values...>', 'Design only: upload ordered local visual references');
         cmd.addHelpText('after', '\nVirtual subcommands:\n' +
             '  get-project              Get Genspark project info for an ACP session (local file lookup, no API call)\n' +
             '    --session-id <id>      ACP session ID (required)\n' +
@@ -695,8 +779,15 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             'Example:\n' +
             '  gsk task get-project --session-id <acp_session_id>\n');
     }
+    if (tool.name === 'task_continue') {
+        cmd.option('--image <values...>', 'Design only: append ordered local visual references');
+        cmd.option('--file <values...>', 'Design only: append ordered local context files');
+    }
     // For the aidrive tool, add client-side options used with --local_file upload
     if (tool.name === 'aidrive') {
+        if (!Object.hasOwn(props, 'workspace')) {
+            cmd.option('--workspace <value>', 'AI Drive workspace: personal or public_brain');
+        }
         cmd.option('--local_file <path>', 'Local file path to upload to AI Drive (supports files >5 MB; alternative to --file_content)');
         cmd.option('--override', 'Overwrite an existing file at the destination path (used with --local_file)', false);
     }
@@ -744,7 +835,10 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             : undefined;
         if (tool.cli.primary_arg === 'action' &&
             Array.isArray(actionEnum) &&
-            primaryArgValue === undefined) {
+            primaryArgValue === undefined &&
+            // The action may arrive via --args-file (read later in the
+            // handler) — don't short-circuit to the action listing then.
+            !opts.argsFile) {
             logError(tool.description);
             logError(`Available actions: ${actionEnum.join(', ')}`);
             logError(`Usage: gsk ${cmd.name()} <action> [options]  ` +
@@ -790,8 +884,10 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
                 await startAcpBridge(taskType, clientFactory().getOptions());
                 return;
             }
-            // For create_task (non-ACP): validate required params manually
-            if (tool.name === 'create_task') {
+            // For create_task (non-ACP): validate required params manually.
+            // Skipped when --args-file is present — required params may live in
+            // the file, and the post-merge revalidation below enforces them.
+            if (tool.name === 'create_task' && !opts.argsFile) {
                 for (const reqParam of required) {
                     if (reqParam === tool.cli.primary_arg)
                         continue;
@@ -826,7 +922,25 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             const outputFilePath = opts.outputFile;
             delete opts.outputFile;
             delete opts.acp; // ACP flag is client-side only
+            // -o exports an artifact of the FINISHED project — an async submit
+            // stub has nothing to export yet, so an export request implies the
+            // live follow.
+            const attachTask = !!opts.follow || !!outputFilePath;
+            delete opts.follow; // client-side only
             delete opts.sessionId; // get-project flag is client-side only
+            const argsFilePath = opts.argsFile;
+            delete opts.argsFile; // client-side only; merged below
+            // Required checks were relaxed because --args-file appeared in argv;
+            // an explicitly EMPTY value (`--args-file=` / `--args-file ""`,
+            // parsed as '') would skip the merge AND the revalidation below — a
+            // validation bypass, not a degenerate no-op. Refuse it. undefined is
+            // deliberately allowed: argv detection can false-positive on a
+            // literal "--args-file" VALUE of another option, and the server-side
+            // required validation still covers that arm.
+            if (argsFilePath !== undefined && !argsFilePath) {
+                logError('--args-file requires a non-empty path (or "-" for stdin)');
+                process.exit(1);
+            }
             const args = { ...opts };
             // Set primary arg
             if (tool.cli.primary_arg && primaryArgValue !== undefined) {
@@ -857,6 +971,54 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
                 delete args.attach;
                 delete args.attachment;
             }
+            // Merge --args-file after every flag-derived write (positional,
+            // attachment aliases) so file keys genuinely win: the file is the
+            // deliberate rich payload, flags are the convenience layer (#46011).
+            // It sits before the numeric coercion below so file-provided
+            // numeric strings get the same schema-driven coercion flags do.
+            if (argsFilePath) {
+                let fileArgs;
+                try {
+                    const { readArgsFile } = await import('./argsFile.js');
+                    fileArgs = readArgsFile(argsFilePath);
+                }
+                catch (err) {
+                    logError(err.message);
+                    process.exit(1);
+                }
+                // The file carries SERVER parameters only. CLI-only options
+                // (--local_file, --file, --out, ...) are processed from flags by
+                // client-side blocks below that never see the file — honoring
+                // them here would silently do nothing, so warn and drop instead.
+                for (const key of Object.keys(fileArgs)) {
+                    if (!(key in props)) {
+                        warn(`--args-file: "${key}" is not a server parameter of ` +
+                            `${tool.name} and was ignored — CLI-only options must be ` +
+                            'passed as flags.');
+                        delete fileArgs[key];
+                    }
+                }
+                Object.assign(args, fileArgs);
+                // Required params were registered optional because the file may
+                // carry them (Commander validates before the file is readable) —
+                // re-validate the merged set now. CLI-populated params are
+                // exempt: skills_save's `files` is schema-required but filled by
+                // the directory collector further down, which deliberately owns
+                // the value (file-wins does not apply to collector-owned params).
+                for (const reqParam of required) {
+                    if (tool.name === 'skills_save' && reqParam === 'files')
+                        continue;
+                    if (args[reqParam] === undefined || args[reqParam] === null) {
+                        // The primary arg is a positional — there is no --<name>
+                        // flag for it, so the recovery hint must not invent one.
+                        const hint = reqParam === tool.cli.primary_arg
+                            ? `pass it as the positional argument or include it in --args-file`
+                            : `pass --${reqParam} or include it in --args-file`;
+                        logError(`Missing required parameter: ${reqParam} (${hint})`);
+                        process.exit(1);
+                    }
+                }
+            }
             // Coerce numeric strings to numbers based on schema
             for (const [name, param] of Object.entries(props)) {
                 if (args[name] !== undefined) {
@@ -941,6 +1103,10 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
                     info(`Warning: ${dir} carries provenance for ${collected.sidecarOwner} — ` +
                         `saving will fork this skill into your own catalog.`);
                 }
+                // Collector-owned: `files` must be {path, content} read from the
+                // local directory, so this assignment intentionally overrides any
+                // --args-file value (the file-wins rule covers flag-shaped params
+                // only, not CLI-populated ones).
                 args.files = collected.files;
             }
             // aidrive upload ergonomics: `gsk aidrive upload <path>` is the natural
@@ -954,10 +1120,21 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             // no usable source, fail with an actionable message that names
             // --local_file rather than the opaque backend error.
             if (tool.name === 'aidrive' &&
-                primaryArgValue === 'upload' &&
+                // args.action, not the positional: the action may arrive via
+                // --args-file (sb-git's clone-url gate uses the same pattern).
+                args.action === 'upload' &&
                 !opts.local_file &&
-                !opts.file_content) {
-                const pathOperand = pickExistingFileOperand(cmd.args.slice(1));
+                // args, not opts: file_content is a server param and may have
+                // arrived via --args-file (merged into args above).
+                !args.file_content) {
+                // Skip the first operand only when it really is the action: with
+                // the action arriving via --args-file, Commander binds a bare
+                // path to the [action] positional slot, so cmd.args[0] is itself
+                // a path candidate.
+                const operandCandidates = primaryArgValue !== undefined && primaryArgValue === args.action
+                    ? cmd.args.slice(1)
+                    : cmd.args;
+                const pathOperand = pickExistingUploadOperand(operandCandidates);
                 if (pathOperand) {
                     opts.local_file = pathOperand;
                 }
@@ -973,10 +1150,11 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             // Stream the file directly to AI Drive via the dedicated tool_cli
             // endpoint (POST /api/tool_cli/aidrive/upload) — no blob middleman.
             if (tool.name === 'aidrive' &&
-                primaryArgValue === 'upload' &&
+                args.action === 'upload' &&
                 opts.local_file) {
                 const localFilePath = opts.local_file;
                 const override = !!opts.override;
+                const workspace = args.workspace || 'personal';
                 if (!fs.existsSync(localFilePath)) {
                     logError(`File not found: ${localFilePath}`);
                     process.exit(1);
@@ -988,13 +1166,54 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
                 const uploadPath = rawUploadPath.startsWith('/')
                     ? rawUploadPath
                     : `/${rawUploadPath}`;
-                // Stream directly to AI Drive — single request, no blob middleman
-                const result = await uploadToAiDrive(localFilePath, uploadPath, override);
-                output(result);
+                const localStat = fs.statSync(localFilePath);
+                const files = collectUploadFiles(localFilePath);
+                if (localStat.isDirectory()) {
+                    if (files.length === 0) {
+                        logError(`Folder has no files to upload: ${localFilePath}`);
+                        process.exit(1);
+                    }
+                    info(`Uploading folder ${localFilePath} (${files.length} files)...`);
+                    const uploaded = [];
+                    for (const file of files) {
+                        const destination = pathModule.posix.join(uploadPath, file.relativePath);
+                        const result = await uploadToAiDrive(file.absolutePath, destination, override, workspace);
+                        if (result.status !== 'ok') {
+                            output(result);
+                            process.exit(1);
+                        }
+                        uploaded.push(destination);
+                    }
+                    output({
+                        status: 'ok',
+                        message: `Uploaded ${uploaded.length} files`,
+                        data: { workspace, root: uploadPath, files: uploaded },
+                    });
+                }
+                else {
+                    // Stream directly to AI Drive — single request, no blob middleman
+                    const result = await uploadToAiDrive(localFilePath, uploadPath, override, workspace);
+                    output(result);
+                }
                 return;
             }
-            // create_task --file: upload local files and pass as file_urls
-            if (tool.name === 'create_task' && opts.file) {
+            const designAttachmentArgs = collectDesignAttachmentArgs(process.argv);
+            const isDesignAttachmentCommand = designAttachmentArgs.length > 0 &&
+                ((tool.name === 'create_task' && args.task_type === 'design') ||
+                    tool.name === 'task_continue');
+            if (isDesignAttachmentCommand) {
+                const uploaded = await uploadDesignAttachments(designAttachmentArgs, client);
+                const existing = Array.isArray(args.attachments)
+                    ? args.attachments
+                    : [];
+                args.attachments = [...existing, ...uploaded];
+                delete args.image;
+                delete args.file;
+            }
+            // Non-Design create_task --file keeps its CSV/Excel file_urls contract.
+            if (tool.name === 'create_task' &&
+                args.task_type !== 'design' &&
+                opts.file) {
                 const fileValues = Array.isArray(opts.file)
                     ? opts.file
                     : [opts.file];
@@ -1027,7 +1246,36 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             }
             // Resolve local file paths to uploaded URLs
             const resolvedArgs = await resolveLocalFiles(args, client);
-            const result = await client.executeTool(tool.name, resolvedArgs);
+            // The server owns the async-first default: create_task /
+            // task_continue return a submit stub ({status: "submitted",
+            // run_id, stream_url}) unless `--wait true` was passed. --attach
+            // upgrades the stub into a live SSE follow that exits with the
+            // run's terminal result — the work still executes server-side.
+            let result = await client.executeTool(tool.name, resolvedArgs);
+            const stubData = result.data;
+            if (attachTask &&
+                result.status === 'ok' &&
+                stubData &&
+                typeof stubData.stream_url === 'string' &&
+                (stubData.status === 'submitted' ||
+                    stubData.status === 'duplicate_submit_converged')) {
+                const meta = await client.attachGskTaskRun(stubData.stream_url);
+                const runStatus = String(meta.status || '');
+                const summary = meta.result_summary && typeof meta.result_summary === 'object'
+                    ? meta.result_summary
+                    : {};
+                result = {
+                    status: runStatus === 'succeeded' ? 'ok' : 'error',
+                    message: runStatus === 'succeeded'
+                        ? 'success'
+                        : `task ended with status ${runStatus || 'unknown'}`,
+                    data: {
+                        ...summary,
+                        run_id: stubData.run_id,
+                        run_status: runStatus,
+                    },
+                };
+            }
             const isSbGitCloneUrl = tool.name === 'sb-git' &&
                 resolvedArgs.action === 'clone-url';
             if (isSbGitCloneUrl &&
@@ -1179,7 +1427,10 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
                 typeof result.data === 'object') {
                 const data = result.data;
                 const projectId = data.project_id;
-                const taskType = (primaryArgValue || args.type);
+                // args.type is the value actually sent to the API: the positional
+                // is copied into args and --args-file may override it (file wins),
+                // so the export must key on the merged view, never the positional.
+                const taskType = args.type;
                 if (projectId && taskType) {
                     info(`Exporting ${taskType} artifact...`);
                     try {
@@ -1929,19 +2180,23 @@ _groupCommands.set('phone-call', phoneCallCmd);
 // gk_tool_cli_conversation) and attach as dynamic subcommands via the
 // seeded _groupCommands entry; this static parent only gives the group a
 // real description instead of the generated "Commands for chat".
-const chatCmd = program
-    .command('chat')
-    .description('Headless agent conversations: start one and get ids back immediately, ' +
-    'poll status for replies, send follow-ups, stop, delete, rename ' +
-    '(see subcommands).');
-_groupCommands.set('chat', chatCmd);
-// `chat events` is static (not server-registered): it needs real-time
+// The task command tree. Verbs are server-registered (create / status /
+// info / ask / answer / messages / wait / stop / delete / rename attach as
+// dynamic subcommands via the seeded group); this static parent gives the
+// group a description, and hosts the one static verb below.
+const taskCmd = program
+    .command('task')
+    .description('Agent tasks and conversations: create one (submits and returns in ' +
+    'seconds), poll status, read outputs, send follow-ups, answer ' +
+    'agent questions, stop, delete, rename (see subcommands).');
+_groupCommands.set('task', taskCmd);
+// `task events` is static (not server-registered): it needs real-time
 // line-by-line output the generic dynamic-command handler cannot provide
 // (that path buffers intermediate NDJSON messages and only prints the
 // final result).
-chatCmd
+taskCmd
     .command('events <project_id>')
-    .description("Attach to the conversation's in-flight run and stream its events " +
+    .description("Attach to the task's in-flight run and stream its events " +
     'live (one JSON line per event on stdout): the first line is a ' +
     'project_data snapshot event, buffered events since run start ' +
     'replay next, then live events follow until the run ends. Every ' +
@@ -1991,10 +2246,78 @@ chatCmd
         process.exit(1);
     }
 });
+// `task export` is static: it composes two calls (task_status to resolve
+// the task type, then /export_artifact) plus an optional local download —
+// the generic dynamic handler maps one verb to one server tool.
+taskCmd
+    .command('export <project_id>')
+    .description("Convert and download a task's deliverable (docs → docx/pdf, " +
+    'slides → pptx/pdf, sheets → xlsx). Prints the download URL; with ' +
+    '-o <path> also saves the file locally. The task type is resolved ' +
+    'automatically from the project; `gsk task artifacts <project_id>` ' +
+    'lists what a task produced and which formats it can export.')
+    .option('--format <format>', 'export format: auto | docx | pdf | pptx | xlsx (auto picks the ' +
+    "task type's natural format)", 'auto')
+    .option('-o, --output-file <path>', 'save the exported file to this path')
+    .action(async (projectId, opts) => {
+    try {
+        const client = createClient();
+        const statusResult = await client.executeTool('task_status', {
+            id: projectId,
+        });
+        const statusData = statusResult.data;
+        const taskType = statusResult.status === 'ok' && statusData
+            ? statusData.task_type
+            : undefined;
+        if (!taskType) {
+            output(statusResult.status === 'ok'
+                ? {
+                    status: 'error',
+                    message: `Cannot resolve task type for ${projectId}`,
+                    data: null,
+                }
+                : statusResult);
+            process.exit(1);
+        }
+        const exportResult = await client.exportArtifact(projectId, taskType, opts.format || 'auto');
+        const expData = exportResult.data;
+        if (exportResult.status === 'ok' && expData && opts.outputFile) {
+            const downloadUrl = expData.download_url;
+            if (downloadUrl) {
+                expData.local_path = await downloadToFile(downloadUrl, opts.outputFile, client);
+            }
+            else {
+                // The converter can report ok with an empty URL (e.g. the
+                // share-link build failed server-side) — surface it instead
+                // of printing ok with no file on disk.
+                output({
+                    status: 'error',
+                    message: 'Export produced no download_url — nothing was saved ' +
+                        `to ${opts.outputFile}`,
+                    data: expData,
+                });
+                process.exit(1);
+            }
+        }
+        output(exportResult);
+        if (exportResult.status === 'error') {
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        logError(err.message);
+        process.exit(1);
+    }
+});
 // ============================================
 // Dynamic Tool Registration & Startup
 // ============================================
 async function main() {
+    // Pre-tree `gsk task <type>` compat (see shimLegacyTaskInvocation).
+    process.argv = [
+        ...process.argv.slice(0, 2),
+        ...shimLegacyTaskInvocation(process.argv.slice(2)),
+    ];
     // `gsk mesh ...` is a native-binary passthrough — intercept it before the
     // tool-fetch path and npm self-update gating (it needs neither). Handling it
     // outside commander keeps the rest of the CLI's option parsing intact (see
@@ -2046,7 +2369,20 @@ async function main() {
                 debug(`Fetched and cached ${tools.length} tools from server`);
             }
             catch (err) {
-                debug(`Failed to fetch tools: ${err.message}`);
+                if (isAuthError(err)) {
+                    // A definitive auth verdict must be loud: swallowing it registers
+                    // zero dynamic commands and the user sees "unknown command" with
+                    // no hint that the token is the cause (#45982). Warn-and-continue
+                    // (not fail-fast) so built-in commands — `gsk login` above all —
+                    // still work with an expired token.
+                    warn(`API token rejected (HTTP ${err.httpStatus}) — ` +
+                        'invalid or expired. Server-provided commands were NOT loaded; ' +
+                        'if the command you need is missing, run `gsk login` to ' +
+                        're-authenticate.');
+                }
+                else {
+                    debug(`Failed to fetch tools: ${err.message}`);
+                }
                 // Continue without dynamic commands - built-in commands still work
             }
         }