@martini-film/cli 0.3.0 → 0.4.1

package/dist/cli.js

@@ -1,24 +1,33 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { resolve, join } from 'node:path';
-import { CliApiError, createApiClient } from './api.js';
+import { CliApiError, createApiClient, isMediaBlock, isTextBlock } from './api.js';
 import { approvalSupport, runWithApproval } from './approve.js';
 import { flagBoolean, flagString, parseArgs } from './args.js';
 import { download, upload, wait } from './commands/assets.js';
+import { call } from './commands/call.js';
 import { assertKnownFlags, compoundBooleanFlags, CONTEXT_FLAG_ALIASES, needsLocalProjection, selectedFields, timeoutMs, wantsWait, } from './commands/context.js';
 import { files } from './commands/files.js';
+import { guide } from './commands/guide.js';
 import { login, logout, whoami } from './commands/login.js';
-import { init, models, probe, tools, version } from './commands/tools.js';
+import { init } from './commands/init.js';
+import { models, probe, tools, version } from './commands/tools.js';
+import { use } from './commands/use.js';
 import { resolveConfig } from './config.js';
-import { renderCompoundHelp, renderHelp, renderToolHelp } from './help.js';
-import { findTool, loadManifest } from './manifest.js';
-import { EXIT, assertRawDestination, printBytes, printError, printResult, printWarning, selectFields, warnNoFieldsMatched, } from './output.js';
-import { ArgumentError, buildArguments, flagSpecs, GLOBAL_FLAG_NAMES } from './schema.js';
-import { assetsOutcome, handleOutcome, producedAssetIds, waitForAssets, waitForDelivery, waitForJob, waitForRun, WaitTimeoutError, } from './wait.js';
+import { GUIDE_HASH_HEADER, guideFetcher, guideHashNotice, loadBakedGuide, openGuide, } from './guideCache.js';
+import { renderCompoundHelp, renderHelp, renderToolHelp, schemaKeyLines } from './help.js';
+import { findTool, loadManifest, TOOL_NAME_PATTERN } from './manifest.js';
+import { openManifest } from './manifestCache.js';
+import { EXIT, MEDIA_EXTENSIONS, assertRawDestination, expandMapPaths, hasUndeclaredMapStep, isDeclaredPath, isEmptyProjection, isMediaOutPath, noFieldsMatchedMessage, noteMediaStubs, printBytes, printError, printResult, printWarning, resolveMapPaths, selectFields, unmatchedFields, warnUnmatchedFields, } from './output.js';
+import { ArgumentError, argumentSchema, buildArguments, explainInvalidArguments, flagSpecs, GLOBAL_FLAG_NAMES, unknownToolFlags, } from './schema.js';
+import { assetsOutcome, handleOutcome, notCompleted, producedAssetIds, waitForAssets, waitForDelivery, waitForJob, waitForRun, WaitTimeoutError, } from './wait.js';
 export const COMPOUND_COMMANDS = [
     login,
     logout,
     whoami,
+    use,
+    guide,
     tools,
+    call,
     models,
     upload,
     download,
@@ -29,7 +38,14 @@ export const COMPOUND_COMMANDS = [
     version,
 ];
 export { GLOBAL_FLAG_NAMES };
-const TOOL_ONLY_GLOBAL_FLAGS = new Set(['approve', 'max-olives', 'out-dir']);
+const TOOL_ONLY_GLOBAL_FLAGS = new Set([
+    'approve',
+    'max-olives',
+    'out-dir',
+    'schema',
+    'all',
+    'keys',
+]);
 const GLOBAL_FLAGS_FOR_COMPOUNDS = new Set([
     ...[...GLOBAL_FLAG_NAMES].filter(flag => !TOOL_ONLY_GLOBAL_FLAGS.has(flag)),
     ...CONTEXT_FLAG_ALIASES,
@@ -42,20 +58,13 @@ const WAIT_BY_DEFAULT = new Set([
     'upscale_assets',
     'render_blender_take',
 ]);
-const BOOLEAN_GLOBAL_FLAGS = new Set(['help', 'version', 'wait', 'quiet', 'raw', 'context', 'approve']);
-export async function main(options) {
-    const env = options.env ?? process.env;
-    const cwd = options.cwd ?? process.cwd();
-    const output = {
-        ...(options.stdout ? { stdout: options.stdout } : {}),
-        ...(options.stderr ? { stderr: options.stderr } : {}),
-        ...(options.isTTY !== undefined ? { isTTY: options.isTTY } : {}),
-    };
-    const manifest = options.manifest ?? loadManifest();
+const ORDERED_RESULT_TOOLS = new Set(['inspect_video']);
+const BOOLEAN_GLOBAL_FLAGS = new Set(['help', 'version', 'wait', 'quiet', 'raw', 'context', 'approve', 'all', 'keys']);
+function parseCommandLine(argv, manifest) {
     const toolFor = (command) => command && !COMPOUND_COMMANDS.some(candidate => candidate.name === command)
         ? findTool(command, manifest)
         : undefined;
-    const parsed = parseArgs(options.argv, (flag, command) => {
+    return parseArgs(argv, (flag, command) => {
         if (BOOLEAN_GLOBAL_FLAGS.has(flag))
             return true;
         const compound = COMPOUND_COMMANDS.find(candidate => candidate.name === command);
@@ -69,81 +78,245 @@ export async function main(options) {
         const tool = toolFor(command);
         return tool ? flagSpecs(tool).some(spec => spec.flag === flag && spec.kind === 'array') : false;
     });
+}
+export async function main(options) {
+    const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    const output = {
+        ...(options.stdout ? { stdout: options.stdout } : {}),
+        ...(options.stderr ? { stderr: options.stderr } : {}),
+        ...(options.isTTY !== undefined ? { isTTY: options.isTTY } : {}),
+    };
+    let session;
     try {
-        if (flagBoolean(parsed.flags, 'version') && parsed.command === undefined)
-            parsed.command = 'version';
-        if (parsed.command === undefined ||
-            parsed.command === 'help' ||
-            (flagBoolean(parsed.flags, 'help') && !parsed.command)) {
-            printResult(renderHelp(manifest, COMPOUND_COMMANDS), output);
-            return EXIT.ok;
-        }
-        const compound = COMPOUND_COMMANDS.find(command => command.name === parsed.command);
-        const tool = compound ? undefined : findTool(parsed.command, manifest);
-        if (!compound && !tool) {
-            throw new ArgumentError(`Unknown command "${parsed.command}". Run martini --help for the list.`);
+        session = openSession(options, env, cwd, output);
+    }
+    catch (error) {
+        return printError(error, output);
+    }
+    const { config, clientFor, client, manifests } = session;
+    let refreshed;
+    for (;;) {
+        const manifest = manifests.state.manifest;
+        const parsed = parseCommandLine(options.argv, manifest);
+        if (parsed.command)
+            output.command = parsed.command;
+        try {
+            if (flagBoolean(parsed.flags, 'version') && parsed.command === undefined)
+                parsed.command = 'version';
+            if (parsed.command === undefined && parsed.flags.has('schema')) {
+                throw new ArgumentError("--schema describes one tool's arguments: martini <tool> --schema [flag].");
+            }
+            if (parsed.command === undefined ||
+                parsed.command === 'help' ||
+                (flagBoolean(parsed.flags, 'help') && !parsed.command)) {
+                printResult(renderHelp(manifest, COMPOUND_COMMANDS), output);
+                return EXIT.ok;
+            }
+            const compound = COMPOUND_COMMANDS.find(command => command.name === parsed.command);
+            const tool = compound ? undefined : findTool(parsed.command, manifest);
+            if (!compound && !tool) {
+                if (refreshed === undefined && TOOL_NAME_PATTERN.test(parsed.command)) {
+                    refreshed = await manifests.refresh();
+                    if (refreshed === 'updated')
+                        continue;
+                }
+                throw unknownCommandError(parsed.command, refreshed);
+            }
+            if (flagBoolean(parsed.flags, 'help')) {
+                printResult(tool
+                    ? renderToolHelp(tool, { all: flagBoolean(parsed.flags, 'all') === true })
+                    : renderCompoundHelp(compound), output);
+                return EXIT.ok;
+            }
+            if (parsed.flags.has('schema')) {
+                const target = schemaTarget(options.argv, parsed.flags);
+                const borrowed = compound ? compoundSchema(compound.name, target, manifest) : undefined;
+                if (compound && !borrowed) {
+                    throw new ArgumentError(`--schema describes a tool's arguments; ${compound.name} is a compound command (martini ${compound.name} --help lists its flags).`);
+                }
+                const schema = borrowed ?? argumentSchema(tool, target);
+                printResult(flagBoolean(parsed.flags, 'keys') === true
+                    ? `${schemaKeyLines(schema, target ? `--${target.replace(/^--/, '')}` : `${tool.name} arguments`).join('\n')}\n`
+                    : `${JSON.stringify(schema, null, 2)}\n`, output);
+                return EXIT.ok;
+            }
+            if (parsed.flags.has('keys'))
+                throw new ArgumentError('--keys goes with --schema: martini <tool> --schema <flag> --keys.');
+            if (parsed.flags.has('all'))
+                throw new ArgumentError('--all goes with --help: martini <tool> --help --all.');
+            if (compound)
+                assertKnownFlags(compound, parsed.flags, GLOBAL_FLAGS_FOR_COMPOUNDS);
+            else {
+                if (refreshed === undefined && unknownToolFlags(tool, parsed.flags, nonArgumentFlags(tool)).length > 0) {
+                    refreshed = await manifests.refresh();
+                    if (refreshed === 'updated')
+                        continue;
+                }
+                if (parsed.positionals.length > 0)
+                    throw strayPositionalError(tool, parsed.positionals);
+            }
+            for (const warning of config.warnings)
+                printWarning('CONFIG_WARNING', warning, output);
+            const out = flagString(parsed.flags, 'out');
+            if (out)
+                output.out = resolve(cwd, out);
+            output.inRun = Boolean(config.runId);
+            output.quiet = flagBoolean(parsed.flags, 'quiet') ?? false;
+            return await runCommand(compound, tool, {
+                client,
+                clientFor,
+                config,
+                manifest,
+                manifests,
+                guide: lazyGuide(options, config, env, output),
+                flags: parsed.flags,
+                positionals: parsed.positionals,
+                output,
+                env,
+                cwd,
+                now: options.now ?? Date.now,
+                sleep: options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms))),
+            });
         }
-        if (flagBoolean(parsed.flags, 'help')) {
-            printResult(tool ? renderToolHelp(tool) : renderCompoundHelp(compound), output);
-            return EXIT.ok;
+        catch (error) {
+            if (error instanceof CliApiError && error.result !== undefined)
+                printResult(error.result, output);
+            return printError(error, output);
         }
-        if (compound)
-            assertKnownFlags(compound, parsed.flags, GLOBAL_FLAGS_FOR_COMPOUNDS);
-        else if (parsed.positionals.length > 0)
-            throw strayPositionalError(tool, parsed.positionals);
-        const config = resolveConfig(parsed.flags, { env, cwd });
-        for (const warning of config.warnings)
-            printWarning('CONFIG_WARNING', warning, output);
-        const clientFor = options.createClient ??
-            (resolved => createApiClient(resolved, { ...(options.fetch ? { fetch: options.fetch } : {}), env }));
-        const out = flagString(parsed.flags, 'out');
-        if (out)
-            output.out = out;
-        output.inRun = Boolean(config.runId);
-        output.quiet = flagBoolean(parsed.flags, 'quiet') ?? false;
-        const context = {
-            client: clientFor(config),
-            clientFor,
-            config,
-            manifest,
-            flags: parsed.flags,
-            positionals: parsed.positionals,
-            output,
+    }
+}
+function openSession(options, env, cwd, output) {
+    const baked = options.manifest ?? loadManifest();
+    const preliminary = parseCommandLine(options.argv, baked);
+    const config = resolveConfig(preliminary.flags, { env, cwd });
+    const warnings = { ...output, quiet: flagBoolean(preliminary.flags, 'quiet') ?? false };
+    const noticeGuideHash = guideHashNotice({
+        baked: loadBakedGuide(),
+        apiUrl: config.apiUrl,
+        apiKey: config.apiKey,
+        env,
+        quiet: warnings.quiet === true,
+        warn: (code, message) => printWarning(code, message, warnings),
+    });
+    const clientFor = options.createClient ??
+        ((resolved) => createApiClient(resolved, {
+            ...(options.fetch ? { fetch: options.fetch } : {}),
             env,
-            cwd,
-            now: options.now ?? Date.now,
-            sleep: options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms))),
-        };
-        const select = selectedFields(context);
-        timeoutMs(context);
-        if (compound) {
-            const result = await compound.run(context);
-            const projected = select.length && result && typeof result === 'object' ? selectFields(result, select) : result;
-            warnNoFieldsMatched(projected, select, output);
-            printResult(projected, output);
-            return EXIT.ok;
-        }
-        const result = await runTool(tool, context, parsed.flags);
-        warnNoFieldsMatched(result, select, output, knownResultFields(tool));
-        printResult(result, output);
-        return EXIT.ok;
+            onResponse: response => {
+                const hash = response.headers.get(GUIDE_HASH_HEADER);
+                if (hash)
+                    noticeGuideHash(hash);
+            },
+        }));
+    const client = clientFor(config);
+    const manifests = openManifest({
+        baked,
+        apiUrl: config.apiUrl,
+        apiKey: config.apiKey,
+        env,
+        fetchManifest: ifNoneMatch => client.fetchManifest(ifNoneMatch),
+        warn: (code, message) => printWarning(code, message, warnings),
+        ...(options.now ? { now: options.now } : {}),
+    });
+    return { config, clientFor, client, manifests };
+}
+function lazyGuide(options, config, env, output) {
+    let runtime;
+    return () => (runtime ??= openGuide({
+        baked: loadBakedGuide(),
+        apiUrl: config.apiUrl,
+        apiKey: config.apiKey,
+        env,
+        fetchGuide: guideFetcher({ fetch: options.fetch ?? fetch, apiUrl: config.apiUrl, apiKey: config.apiKey, env }),
+        warn: (code, message) => printWarning(code, message, output),
+        ...(options.now ? { now: options.now } : {}),
+    }));
+}
+function schemaTarget(argv, flags) {
+    const value = flagString(flags, 'schema');
+    if (value)
+        return value;
+    const index = argv.indexOf('--schema');
+    const next = index >= 0 ? argv[index + 1] : undefined;
+    if (!next?.startsWith('--') || next === '--')
+        return undefined;
+    const name = next.slice(2).split('=')[0];
+    return GLOBAL_FLAG_NAMES.has(name) ? undefined : name;
+}
+const COMPOUND_SCHEMAS = {
+    upload: { lineage: { tool: 'upload_assets_prepare', path: 'files.lineage' } },
+};
+function compoundSchema(command, target, manifest) {
+    const flag = target?.replace(/^--/, '');
+    const source = flag ? COMPOUND_SCHEMAS[command]?.[flag] : undefined;
+    if (!source)
+        return undefined;
+    const tool = findTool(source.tool, manifest);
+    try {
+        if (tool)
+            return argumentSchema(tool, source.path);
     }
     catch (error) {
-        if (error instanceof CliApiError && error.result !== undefined)
-            printResult(error.result, output);
-        return printError(error, output);
+        if (!(error instanceof ArgumentError))
+            throw error;
     }
+    throw new ArgumentError(`This server's ${source.tool} takes no ${flag} block, so martini ${command} sends none (its result says lineage: "none").`);
 }
-async function runTool(tool, context, flags) {
+function unknownCommandError(name, refreshed) {
+    const message = `Unknown command "${name}". Run martini --help for the list.`;
+    if (!TOOL_NAME_PATTERN.test(name))
+        return new ArgumentError(message);
+    const checked = refreshed === 'updated' || refreshed === 'unchanged';
+    return new ArgumentError(message, {
+        hint: checked
+            ? `The server's tool list for this key has no "${name}" either (martini tools compares it with this build's). To send the call by name anyway: martini call ${name} --args '{…}' --context (--context adds this directory's projectId; call fills nothing else).`
+            : `The server's tool list was not checked, so a tool added since this build may be missing: martini call ${name} --args '{…}' --context sends the call by name (--context adds this directory's projectId; call fills nothing else).`,
+    });
+}
+function nonArgumentFlags(tool) {
     const properties = tool.inputSchema.properties ?? {};
     const ignore = new Set(GLOBAL_FLAG_NAMES);
     for (const alias of CONTEXT_FLAG_ALIASES) {
         if (!(alias.replace(/-id$/, 'Id') in properties))
             ignore.add(alias);
     }
+    return ignore;
+}
+async function runCommand(compound, tool, context) {
+    const { output } = context;
+    const select = selectedFields(context);
+    timeoutMs(context);
+    if (compound) {
+        const result = await compound.run(context);
+        printResult(result && typeof result === 'object'
+            ? projectResult(result, select, { readOnly: compound.readOnly === true, known: [], command: compound.name }, output)
+            : result, output);
+        return EXIT.ok;
+    }
+    printResult(await runTool(tool, context, context.flags), output);
+    return EXIT.ok;
+}
+function projectResult(result, select, what, output) {
+    if (select.length === 0)
+        return result;
+    const projected = selectFields(result, select);
+    if (!isEmptyProjection(projected) || isEmptyProjection(result)) {
+        warnUnmatchedFields(result, select, output, what.schema);
+        return projected;
+    }
+    if (allDeclared(select, what.schema))
+        return projected;
+    const message = noFieldsMatchedMessage(what.typed ?? select, what.known, result, what.schema);
+    if (what.readOnly)
+        throw new CliApiError(message, { code: 'NO_FIELDS_MATCHED', status: 0 });
+    printWarning('NO_FIELDS_MATCHED', `${message} ${what.command} did its work, so its whole result is printed instead; do not run it again for this.`, output);
+    return result;
+}
+async function runTool(tool, context, flags) {
     const useContext = flagBoolean(flags, 'context') !== false;
     const args = buildArguments(tool, flags, {
-        ignore,
+        ignore: nonArgumentFlags(tool),
         context: useContext
             ? {
                 ...(context.config.projectId ? { projectId: context.config.projectId } : {}),
@@ -152,91 +325,134 @@ async function runTool(tool, context, flags) {
             }
             : {},
     });
+    try {
+        return await runToolWith(tool, context, flags, args);
+    }
+    catch (error) {
+        if (error instanceof CliApiError && error.code === 'INVALID_ARGUMENTS') {
+            const message = explainInvalidArguments(error.message, args, tool.inputSchema);
+            if (message !== error.message) {
+                const explained = new CliApiError(message, {
+                    code: error.code,
+                    status: error.status,
+                    tool: error.tool,
+                    ...(error.hint ? { hint: error.hint } : {}),
+                });
+                if (error.result !== undefined)
+                    explained.result = error.result;
+                throw explained;
+            }
+        }
+        throw error;
+    }
+}
+async function runToolWith(tool, context, flags, args) {
+    const readOnly = tool.annotations.readOnlyHint === true;
+    const out = context.output.out ?? flagString(flags, 'out');
     const outDir = flagString(flags, 'out-dir');
     if (outDir) {
-        if (flagString(flags, 'out'))
+        if (out)
             throw new ArgumentError('Use either --out or --out-dir.');
-        if (tool.annotations.readOnlyHint !== true) {
+        if (!readOnly) {
             throw new ArgumentError('--out-dir requires a read-only tool. Run this command without --out-dir.');
         }
-        const result = await context.client.callTool(tool.name, args);
-        const media = result.media ?? [];
-        if (media.length === 0)
-            return result;
-        const headers = [...(result.text ?? '').matchAll(/^Asset ([A-Za-z0-9_-]+) \((\d+)\/\d+\)/gm)];
+        const result = await context.client.callToolBlocks(tool.name, args, { media: 'inline' });
+        const files = mediaFiles(result.blocks, tool.name);
+        if (files.length === 0)
+            return readableBlocks(result.blocks);
         const directory = resolve(context.cwd, outDir);
-        const files = media.map((block, index) => {
-            const header = headers[index];
-            const assetId = header?.[1] ?? (media.length === 1 ? result.assetId : undefined);
-            if (!assetId) {
-                throw new CliApiError(`Media block ${index}: missing Asset header or single-media result.assetId.`, {
-                    code: 'INVALID_RESPONSE',
-                    status: 0,
-                    tool: tool.name,
-                });
-            }
-            const extensions = {
-                'image/jpeg': 'jpg',
-                'image/png': 'png',
-                'image/webp': 'webp',
-                'audio/mpeg': 'mp3',
-                'audio/wav': 'wav',
-            };
-            if (!block.mimeType || !Object.hasOwn(extensions, block.mimeType)) {
-                throw new CliApiError(`Media block ${index}: missing or unknown mimeType (${block.mimeType ?? 'missing'}).`, {
-                    code: 'INVALID_RESPONSE',
-                    status: 0,
-                    tool: tool.name,
-                });
-            }
-            const ext = extensions[block.mimeType];
-            const name = `${header ? `${header[2]}-` : ''}${assetId.replace(/[^A-Za-z0-9_-]/g, '_')}.${ext}`;
-            return { path: join(directory, name), bytes: Buffer.from(block.data, 'base64') };
-        });
         mkdirSync(directory, { recursive: true });
-        files.forEach(({ path, bytes }) => {
-            writeFileSync(path, bytes);
-            if (!context.output.quiet) {
-                ;
-                (context.output.stdout ?? (text => process.stdout.write(text)))(`${path}\n`);
-            }
-        });
-        context.output.quiet = true;
-        return undefined;
+        for (const file of files)
+            writeFileSync(join(directory, file.name), file.bytes);
+        const receipt = {
+            dir: directory,
+            files: files.map(file => ({
+                path: join(directory, file.name),
+                mimeType: file.mimeType,
+                bytes: file.bytes.byteLength,
+                ...(file.about !== undefined ? { about: file.about } : {}),
+            })),
+            ...(unpairedTexts(result.blocks).length ? { notes: unpairedTexts(result.blocks) } : {}),
+        };
+        return projectResult(receipt, selectedFields(context), { readOnly: false, known: Object.keys(receipt), command: tool.name }, context.output);
     }
-    if (flagBoolean(flags, 'raw')) {
+    const mediaOut = out !== undefined && isMediaOutPath(out);
+    const raw = flagBoolean(flags, 'raw') === true;
+    const mediaFromResult = mediaOut && !raw && !readOnly;
+    if (raw || (mediaOut && readOnly)) {
         assertRawDestination(context.output);
-        let raw;
+        let bytes;
         try {
-            raw = await context.client.callToolRaw(tool.name, args);
+            bytes = await context.client.callToolRaw(tool.name, args);
         }
         catch (error) {
             if (error instanceof CliApiError && error.code === 'NOT_RAW_ELIGIBLE') {
-                throw new ArgumentError('This result cannot use --raw --out. Use --out-dir <dir> to write multiple media files.');
+                throw new ArgumentError(raw
+                    ? 'This result cannot use --raw: it does not hold exactly one media block. Use --out-dir <dir> to write several media files.'
+                    : `--out ${out} names a media file, but ${tool.name} did not answer exactly one image or audio block. Use --out-dir <dir> for several media files, or name a .json file for the JSON result.`);
             }
             throw error;
         }
-        printBytes(raw.bytes, { ...context.output, contentType: raw.contentType });
+        printBytes(bytes.bytes, {
+            ...context.output,
+            contentType: bytes.contentType,
+            meta: bytes.meta,
+            fields: selectedFields(context),
+            wrote: !readOnly,
+        });
         delete context.output.out;
         context.output.quiet = true;
-        return raw.meta;
+        return undefined;
     }
-    const select = selectedFields(context);
+    const requested = mediaFromResult ? [] : selectedFields(context);
+    const finish = (result) => (mediaFromResult ? saveMediaFromResult(result, tool, context, out) : result);
+    if (ORDERED_RESULT_TOOLS.has(tool.name)) {
+        approvalFlags(tool, flags);
+        const media = context.output.out ? 'inline' : 'stub';
+        const result = await context.client.callToolBlocks(tool.name, args, { media });
+        if (media === 'stub')
+            noteMediaStubs(result.blocks, context.output);
+        return projectResult(readableBlocks(result.blocks), requested, { readOnly: true, known: ['blocks'], command: tool.name }, context.output);
+    }
+    const select = expandMapPaths(requested, tool.outputSchema);
+    const known = Object.keys(tool.outputSchema?.properties ?? {});
     const shouldWait = wantsWait(context, WAIT_BY_DEFAULT.has(tool.name));
     const approve = approvalFlags(tool, flags);
-    const local = shouldWait || approve !== null || needsLocalProjection(select);
+    const local = shouldWait ||
+        approve !== null ||
+        needsLocalProjection(select) ||
+        hasUndeclaredMapStep(requested, tool.outputSchema) ||
+        !readOnly ||
+        tool.outputSchema === undefined;
+    const what = { readOnly, known, command: tool.name, typed: requested, schema: tool.outputSchema };
+    const selectIn = (value) => resolveMapPaths(value, requested, tool.outputSchema);
     const result = approve
         ? await runWithApproval(tool, context.client, args, approve.support, approve.maxOlives === undefined ? {} : { maxOlives: approve.maxOlives })
         : await context.client.callTool(tool.name, args, !local && select.length ? { select } : {});
-    if (!shouldWait)
-        return local ? selectFields(result, select) : result;
+    if (!shouldWait) {
+        if (local)
+            return finish(projectResult(result, selectIn(result), what, context.output));
+        if (select.length && unmatchedFields(result, select).length === select.length) {
+            if (allDeclared(select, tool.outputSchema))
+                return result;
+            throw new CliApiError(noFieldsMatchedMessage(requested, known, undefined, tool.outputSchema), {
+                code: 'NO_FIELDS_MATCHED',
+                status: 0,
+            });
+        }
+        warnUnmatchedFields(result, select, context.output, tool.outputSchema);
+        return result;
+    }
     const projectId = typeof args.projectId === 'string' ? args.projectId : context.config.projectId;
     try {
-        return selectFields(await waitForToolResult(result, context, projectId), select);
+        const waited = await waitForToolResult(result, context, projectId);
+        return finish(projectResult(waited, selectIn(waited), what, context.output));
     }
     catch (error) {
-        if (error instanceof CliApiError) {
-            const kept = selectFields(result, select);
+        if (error instanceof WaitTimeoutError && projectId)
+            error.project = projectId;
+        if (error instanceof CliApiError && error.code !== 'NO_FIELDS_MATCHED' && error.result === undefined) {
+            const kept = selectFields(result, selectIn(result));
             const base = kept && typeof kept === 'object' && !Array.isArray(kept) ? kept : { result: kept };
             error.result =
                 error instanceof WaitTimeoutError
@@ -246,6 +462,131 @@ async function runTool(tool, context, flags) {
         throw error;
     }
 }
+function saveMediaFromResult(result, tool, context, out) {
+    const record = result && typeof result === 'object' && !Array.isArray(result) ? result : {};
+    const media = (Array.isArray(record.media) ? record.media : []).filter((block) => block !== null && typeof block === 'object' && typeof block.data === 'string');
+    delete context.output.out;
+    if (media.length !== 1) {
+        printWarning('OUT_NOT_MEDIA', `${tool.name} answered ${media.length === 0 ? 'no image or audio block' : `${media.length} media blocks`}, so nothing was written to ${out}; its result is printed instead. ${tool.name} did its work: do not run it again for this. Name a .json file to save a result, or use --out-dir on a read-only tool for several media files.`, context.output);
+        return result;
+    }
+    const { media: _media, ...rest } = record;
+    printBytes(Buffer.from(media[0].data, 'base64'), {
+        ...context.output,
+        out,
+        ...(typeof media[0].mimeType === 'string' ? { contentType: media[0].mimeType } : {}),
+        meta: rest,
+        fields: selectedFields(context),
+        wrote: true,
+    });
+    context.output.quiet = true;
+    return undefined;
+}
+function allDeclared(paths, schema) {
+    return schema !== undefined && paths.every(path => isDeclaredPath(path, schema));
+}
+function readableBlocks(blocks) {
+    return {
+        blocks: blocks.map(block => {
+            if (!isTextBlock(block))
+                return block;
+            const parsed = parseLabelledJson(block.text);
+            return parsed ? { type: 'text', ...(parsed.label ? { label: parsed.label } : {}), json: parsed.json } : block;
+        }),
+    };
+}
+function parseLabelledJson(text) {
+    const header = /^(Asset [A-Za-z0-9_-]+ \(\d+\/\d+\))\s*\n/.exec(text);
+    const body = header ? text.slice(header[0].length) : text;
+    if (!body.trimStart().startsWith('{'))
+        return null;
+    try {
+        const json = JSON.parse(body);
+        if (!json || typeof json !== 'object' || Array.isArray(json))
+            return null;
+        return { ...(header ? { label: header[1] } : {}), json: json };
+    }
+    catch {
+        return null;
+    }
+}
+function unpairedTexts(blocks) {
+    const notes = [];
+    blocks.forEach((block, index) => {
+        if (!isTextBlock(block))
+            return;
+        const previous = blocks[index - 1];
+        const next = blocks[index + 1];
+        const paired = (next !== undefined && isMediaBlock(next)) ||
+            (previous !== undefined && isMediaBlock(previous) && (index < 2 || !isTextBlock(blocks[index - 2])));
+        if (!paired)
+            notes.push(block.text);
+    });
+    return notes;
+}
+function mediaFiles(blocks, toolName) {
+    const invalid = (message) => new CliApiError(message, { code: 'INVALID_RESPONSE', status: 0, tool: toolName });
+    const taken = new Set();
+    const files = [];
+    let text;
+    blocks.forEach((block, index) => {
+        if (isTextBlock(block)) {
+            text = block.text;
+            return;
+        }
+        if (!isMediaBlock(block))
+            return;
+        const mimeType = typeof block.mimeType === 'string' ? block.mimeType : undefined;
+        if (!mimeType || !Object.hasOwn(MEDIA_EXTENSIONS, mimeType)) {
+            throw invalid(`Block ${index} (${block.type}): missing or unknown mimeType (${mimeType ?? 'missing'}).`);
+        }
+        if (!('data' in block) || typeof block.data !== 'string')
+            throw invalid(`Block ${index} (${block.type}): no data.`);
+        const before = stemFrom(text);
+        const describing = before ? text : textAfter(blocks, index);
+        const stem = before ?? stemFrom(describing) ?? `block-${index}`;
+        let name = `${stem}.${MEDIA_EXTENSIONS[mimeType]}`;
+        for (let copy = 2; taken.has(name); copy++)
+            name = `${stem}-${copy}.${MEDIA_EXTENSIONS[mimeType]}`;
+        taken.add(name);
+        const about = describing === undefined ? null : parseLabelledJson(describing);
+        files.push({ name, mimeType, bytes: Buffer.from(block.data, 'base64'), ...(about ? { about: about.json } : {}) });
+    });
+    return files;
+}
+function stemFrom(text) {
+    if (text === undefined)
+        return null;
+    const header = /^Asset ([A-Za-z0-9_-]+) \((\d+)\/\d+\)/.exec(text);
+    if (header) {
+        const name = nameSlug(parseLabelledJson(text)?.json.displayName);
+        return name ? `${header[2]}-${name}-${header[1]}` : `${header[2]}-${header[1]}`;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        const assetId = parsed && typeof parsed === 'object' ? parsed.assetId : undefined;
+        if (typeof assetId === 'string' && assetId)
+            return assetId.replace(/[^A-Za-z0-9_-]/g, '_');
+    }
+    catch {
+    }
+    return null;
+}
+function nameSlug(value) {
+    if (typeof value !== 'string')
+        return '';
+    return value
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .slice(0, 40)
+        .replace(/^-+|-+$/g, '');
+}
+function textAfter(blocks, index) {
+    const next = blocks[index + 1];
+    return next && isTextBlock(next) ? next.text : undefined;
+}
 async function waitForToolResult(result, context, projectId) {
     if (!result || typeof result !== 'object')
         return result;
@@ -253,25 +594,32 @@ async function waitForToolResult(result, context, projectId) {
     if (record.approvalNeeded === true || record.generated === false)
         return result;
     const waitOptions = { timeoutMs: timeoutMs(context), now: context.now, sleep: context.sleep };
+    const settled = (waited) => {
+        const failure = notCompleted(waited);
+        if (!failure)
+            return { ...record, waited };
+        failure.result = { ...record, waited };
+        throw failure;
+    };
     if (typeof record.runId === 'string') {
-        return { ...record, waited: handleOutcome('run', await waitForRun(context.client, record.runId, waitOptions)) };
+        return settled(handleOutcome('run', await waitForRun(context.client, record.runId, waitOptions)));
     }
     if (typeof record.renderId === 'string' || typeof record.exportId === 'string') {
         const ids = {
             ...(typeof record.renderId === 'string' ? { renderId: record.renderId } : {}),
             ...(typeof record.exportId === 'string' ? { exportId: record.exportId } : {}),
         };
-        return { ...record, waited: handleOutcome('render', await waitForDelivery(context.client, ids, waitOptions)) };
+        return settled(handleOutcome('render', await waitForDelivery(context.client, ids, waitOptions)));
     }
     if (typeof record.jobId === 'string') {
-        return { ...record, waited: handleOutcome('job', await waitForJob(context.client, record.jobId, waitOptions)) };
+        return settled(handleOutcome('job', await waitForJob(context.client, record.jobId, waitOptions)));
     }
     if (!projectId)
         return result;
     const ids = producedAssetIds(result);
     if (ids.length === 0)
         return result;
-    return { ...record, waited: assetsOutcome(await waitForAssets(context.client, projectId, ids, waitOptions)) };
+    return settled(assetsOutcome(await waitForAssets(context.client, projectId, ids, waitOptions)));
 }
 function strayPositionalError(tool, tokens) {
     const list = flagSpecs(tool).find(spec => spec.kind === 'array');
@@ -295,7 +643,4 @@ function approvalFlags(tool, flags) {
         throw new ArgumentError('--max-olives must be a number of olives.');
     return { support, maxOlives };
 }
-function knownResultFields(tool) {
-    return Object.keys(tool.outputSchema?.properties ?? {});
-}
 //# sourceMappingURL=cli.js.map