@lotagate/cli 0.1.21 → 0.1.22

package/dist/application/commands/command-registry.js

@@ -0,0 +1,64 @@
+import { CliError } from '../../domain/errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../../domain/errors/error-codes.js';
+export class CommandRegistry {
+    actions;
+    byId = new Map();
+    constructor(actions) {
+        this.actions = actions;
+        for (const action of actions) {
+            if (action.path.length === 0)
+                throw new Error(`Command action ${action.id} has no path.`);
+            if (this.byId.has(action.id))
+                throw new Error(`Command action ${action.id} is already registered.`);
+            this.byId.set(action.id, action);
+        }
+        for (const surface of ['direct', 'tui'])
+            this.assertNoSurfaceCollisions(surface);
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    list(surface, includeHidden = false) {
+        return this.actions
+            .filter((action) => action.surfaces.includes(surface) && (includeHidden || !action.hiddenFromHelp))
+            .sort(compareActionPath);
+    }
+    actionsForRoot(root, surface) {
+        const normalized = root.toLowerCase();
+        return this.actions.filter((action) => action.surfaces.includes(surface) && action.path[0] === normalized);
+    }
+    resolve(tokens, surface) {
+        const root = tokens[0]?.toLowerCase();
+        if (root === undefined)
+            throw invalidCommand('A command is required.');
+        const candidates = this.actionsForRoot(root, surface)
+            .filter((action) => pathMatches(action.path, tokens))
+            .sort((left, right) => right.path.length - left.path.length);
+        const action = candidates[0];
+        if (action !== undefined)
+            return action;
+        if (this.actionsForRoot(root, surface).length === 0)
+            throw invalidCommand(`Unknown command: ${root}.`);
+        throw invalidCommand(`Unsupported ${root} command.`);
+    }
+    assertNoSurfaceCollisions(surface) {
+        const seen = new Set();
+        for (const action of this.actions.filter((item) => item.surfaces.includes(surface))) {
+            const key = action.path.join(' ');
+            if (seen.has(key))
+                throw new Error(`Command path collision on ${surface}: ${key}.`);
+            seen.add(key);
+        }
+    }
+}
+function pathMatches(path, tokens) {
+    if (tokens.length < path.length)
+        return false;
+    return path.every((segment, index) => tokens[index]?.toLowerCase() === segment);
+}
+function compareActionPath(left, right) {
+    return left.path.join(' ').localeCompare(right.path.join(' '));
+}
+function invalidCommand(userMessage) {
+    return new CliError(CLI_ERROR_CODES.INVALID_ARGUMENT, userMessage, { category: 'arguments', userMessage });
+}

package/dist/application/commands/command-runtime.d.ts

@@ -0,0 +1,2 @@
+import { CommandRegistry } from './command-registry.js';
+export declare const COMMAND_REGISTRY: CommandRegistry;

package/dist/application/commands/command-runtime.js

@@ -0,0 +1,3 @@
+import { COMMAND_ACTIONS } from './command-catalog.js';
+import { CommandRegistry } from './command-registry.js';
+export const COMMAND_REGISTRY = new CommandRegistry(COMMAND_ACTIONS);

package/dist/application/commands/goal-command-handlers.d.ts

@@ -0,0 +1,3 @@
+import type { Writable } from 'node:stream';
+import type { CliRuntime } from '../../bootstrap/runtime-factory.js';
+export declare function runGoalCommand(positionals: readonly string[], flags: ReadonlyMap<string, string | boolean>, runtime: CliRuntime, cwd: string, stdout: Writable): Promise<number>;

package/dist/application/commands/goal-command-handlers.js

@@ -0,0 +1,120 @@
+import { isFlagEnabled, requirePositional } from './cli-args.js';
+import { ProjectSessionAccess } from '../session/project-session-access.js';
+import { AuthenticationService } from '../auth/authentication-service.js';
+import { loadExecutionConfig } from '../config/execution-config.js';
+import { createLotaGateClient } from '../../infrastructure/sdk/lotagate-client-factory.js';
+import { runHeadlessAgentTurn } from '../orchestration/headless-agent-turn.js';
+import { runGoalLoop } from '../orchestration/goal-runner.js';
+import { CliAgentSessionStore } from '../agent/agent-session-store.js';
+import { formatGoalStatus } from '../orchestration/goal-output.js';
+import { parseGoalInput } from '../orchestration/goal-input.js';
+import { CliError } from '../../domain/errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../../domain/errors/error-codes.js';
+import { MODEL_SELECT_HINT, TRUST_GRANT_HINT } from './command-hints.js';
+import { createTurnId, recordTurnCompletion, recordTurnFailure, recordTurnStart } from '../session/session-turn-lifecycle.js';
+export async function runGoalCommand(positionals, flags, runtime, cwd, stdout) {
+    const action = positionals[0] ?? 'status';
+    if (action === 'run')
+        return runGoalLoopCommand(positionals.slice(1).join(' ').trim(), flags, runtime, cwd, stdout);
+    const sessionId = requirePositional(positionals, 1, 'session id');
+    const identity = await runtime.projectTrust.inspect(cwd);
+    await new ProjectSessionAccess(runtime.sessionStore).require(sessionId, identity.fingerprint);
+    if (action === 'status')
+        return writeGoal(stdout, await runtime.goalStore.get(sessionId), isFlagEnabled(flags, 'json'));
+    if (action === 'set') {
+        const objective = requirePositional([positionals.slice(2).join(' ')], 0, 'goal objective');
+        const state = await runtime.goalStore.replace(sessionId, readInput(objective, flags));
+        return writeGoal(stdout, state, isFlagEnabled(flags, 'json'));
+    }
+    if (action === 'pause') {
+        const state = await runtime.goalStore.pause(sessionId);
+        return writeGoal(stdout, state, isFlagEnabled(flags, 'json'));
+    }
+    if (action === 'resume') {
+        const state = await runtime.goalStore.get(sessionId);
+        if (state === undefined)
+            throw new CliError(CLI_ERROR_CODES.GOAL_NOT_FOUND, 'Goal not found.', { category: 'goal', userMessage: 'Goal was not found.' });
+        return runGoalLoopCommand(state.objective, flags, runtime, cwd, stdout, sessionId);
+    }
+    if (action === 'clear') {
+        await runtime.goalStore.clear(sessionId);
+        stdout.write('Goal cleared.\n');
+        return 0;
+    }
+    throw new Error(`Unsupported goal action: ${action}`);
+}
+async function runGoalLoopCommand(objective, flags, runtime, cwd, stdout, existingSessionId) {
+    if (objective.length === 0)
+        throw new CliError(CLI_ERROR_CODES.MISSING_ARGUMENT, 'Missing goal objective.', { category: 'arguments', userMessage: 'A goal objective is required.' });
+    const identity = await runtime.projectTrust.inspect(cwd);
+    if (!await runtime.projectTrust.isTrusted(identity))
+        throw new CliError(CLI_ERROR_CODES.PROJECT_TRUST_REQUIRED, 'Project trust is required for goals.', { category: 'project', userMessage: 'Project is not trusted.', hint: TRUST_GRANT_HINT });
+    const loaded = await loadExecutionConfig(runtime, cwd);
+    if (loaded.config.model === null)
+        throw new CliError(CLI_ERROR_CODES.MODEL_NOT_FOUND, 'No model is selected.', { category: 'model', userMessage: 'No model is selected.', hint: MODEL_SELECT_HINT });
+    const model = loaded.config.model;
+    const profile = loaded.config.profile ?? AuthenticationService.defaultProfileName();
+    const credential = await runtime.auth.requireCredential(profile);
+    const session = existingSessionId === undefined
+        ? await runtime.sessionStore.create({ projectFingerprint: identity.fingerprint, cwd: identity.canonicalPath, model: loaded.config.model, profile, status: 'active' })
+        : await runtime.sessionStore.get(existingSessionId);
+    if (session === undefined)
+        throw new CliError(CLI_ERROR_CODES.SESSION_NOT_FOUND, 'Goal session not found.', { category: 'session', userMessage: 'Goal session was not found.' });
+    if (existingSessionId === undefined)
+        await runtime.goalStore.create(session.id, readInput(objective, flags));
+    else
+        await runtime.goalStore.resume(session.id);
+    const client = createLotaGateClient(credential.profile, credential.apiKey);
+    const agentSessionStore = new CliAgentSessionStore();
+    const abortController = new AbortController();
+    const onInterrupt = () => abortController.abort(new Error('Goal interrupted by user.'));
+    process.once('SIGINT', onInterrupt);
+    try {
+        const final = await runGoalLoop({
+            runtime, sessionId: session.id, objective, model, client, signal: abortController.signal,
+            runTurn: async (prompt, callbacks, signal) => {
+                const turnId = createTurnId();
+                await recordTurnStart(runtime.sessionStore, session.id, turnId, prompt);
+                try {
+                    const state = await runtime.goalStore.get(session.id);
+                    const response = await runHeadlessAgentTurn({
+                        runtime, cwd, model, client, prompt, output: stdout, sessionId: session.id,
+                        agentSessionStore, signal, turnId,
+                        ...(state === undefined ? {} : { goal: { objective: state.objective, status: state.status, turns: state.turns, evaluatorRuns: state.evaluatorRuns, tokensUsed: state.usage.totalTokens, ...(state.tokenBudget === undefined ? {} : { tokenBudget: state.tokenBudget }), ...(state.maxTurns === undefined ? {} : { maxTurns: state.maxTurns }), ...(state.maxDurationMs === undefined ? {} : { maxDurationMs: state.maxDurationMs }), ...(state.lastError === undefined ? {} : { lastError: state.lastError }), ...(state.lastEvaluation === undefined ? {} : { lastEvaluation: state.lastEvaluation.reason }) } }),
+                        onUsage: callbacks.onUsage, onSubagentUsage: callbacks.onUsage, onSnapshot: callbacks.onSnapshot,
+                    });
+                    stdout.write('\n');
+                    await recordTurnCompletion(runtime.sessionStore, session.id, turnId, response);
+                    return response;
+                }
+                catch (error) {
+                    callbacks.onError(error);
+                    await recordTurnFailure(runtime.sessionStore, session.id, turnId, error, false);
+                    throw error;
+                }
+            },
+        });
+        await runtime.sessionStore.updateStatus(session.id, final?.status === 'completed' ? 'completed' : final?.status === 'paused' ? 'active' : 'failed');
+        stdout.write(`Goal session: ${session.id}\n`);
+        const safelyPaused = final?.status === 'paused' && final.lastError?.startsWith('Goal paused by safety limit:') === true;
+        return final?.status === 'completed' || safelyPaused ? 0 : 1;
+    }
+    finally {
+        process.off('SIGINT', onInterrupt);
+    }
+}
+function readInput(objective, flags) {
+    return parseGoalInput(objective, flags);
+}
+function writeGoal(stdout, state, json) {
+    if (json) {
+        stdout.write(`${JSON.stringify(state ?? null)}\n`);
+        return state === undefined ? 1 : 0;
+    }
+    if (state === undefined) {
+        stdout.write('No active goal.\n');
+        return 1;
+    }
+    stdout.write(`${formatGoalStatus(state)}\n`);
+    return 0;
+}

package/dist/application/commands/media-command-handlers.d.ts

@@ -0,0 +1,9 @@
+import type { CliRuntime } from '../../bootstrap/runtime-factory.js';
+import type { CommandInvocation } from './command-contract.js';
+import type { CommandOutput } from './command-output.js';
+export interface CommandActivityObserver {
+    start(key: string, label: string): {
+        complete(isError: boolean): void;
+    };
+}
+export declare function runMediaCommand(invocation: CommandInvocation, runtime: CliRuntime, cwd: string, output: CommandOutput, activity?: CommandActivityObserver, suppliedSignal?: AbortSignal): Promise<number>;

package/dist/application/commands/media-command-handlers.js

@@ -0,0 +1,307 @@
+import { AuthenticationService } from '../auth/authentication-service.js';
+import { loadExecutionConfig } from '../config/execution-config.js';
+import { waitForVideoOperation } from '../media/video-operation-poller.js';
+import { loadModelCatalog } from '../model/model-catalog-service.js';
+import { CliError } from '../../domain/errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../../domain/errors/error-codes.js';
+import { SDK_BINARY_MEDIA_RESPONSE_BYTES, validateMediaCommandOptions, } from '../../domain/media/gateway-media-contract.js';
+import { resolveMediaExecutionPolicy } from '../../domain/media/media-execution-policy.js';
+import { readGatewayAudioInput, readGatewayImageEditInput } from '../../infrastructure/filesystem/gateway-media-input-reader.js';
+import { WorkspaceMediaArtifactStore } from '../../infrastructure/filesystem/workspace-media-artifact-store.js';
+import { normalizeImage } from '../../infrastructure/clipboard/image-normalizer.js';
+import { downloadPublicMedia } from '../../infrastructure/network/safe-media-downloader.js';
+import { createLotaGateClient } from '../../infrastructure/sdk/lotagate-client-factory.js';
+import { SdkMediaGatewayClient } from '../../infrastructure/sdk/sdk-media-gateway-client.js';
+import { MODEL_SELECT_HINT } from './command-hints.js';
+import { writeMediaCommandResult } from './media-command-output.js';
+import { getStringFlag, isFlagEnabled, requirePositional, requireStringFlag } from './cli-args.js';
+export async function runMediaCommand(invocation, runtime, cwd, output, activity, suppliedSignal) {
+    validateMediaCommandOptions(invocation.action.id, invocation.positionals, invocation.options);
+    const ownAbort = suppliedSignal === undefined ? new AbortController() : undefined;
+    const signal = suppliedSignal ?? ownAbort.signal;
+    const onInterrupt = () => ownAbort?.abort(new Error('Media command interrupted.'));
+    if (ownAbort !== undefined)
+        process.once('SIGINT', onInterrupt);
+    const startedAt = Date.now();
+    try {
+        runtime.logger.info('Media command started.', { action: invocation.action.id });
+        const exitCode = await executeMediaCommand(invocation, runtime, cwd, output, activity, signal);
+        runtime.logger.info('Media command completed.', { action: invocation.action.id, exitCode, durationMs: Date.now() - startedAt });
+        return exitCode;
+    }
+    catch (error) {
+        const details = error instanceof CliError
+            ? { code: error.code, category: error.category, correlationId: error.correlationId }
+            : {};
+        runtime.logger.error('Media command failed.', { action: invocation.action.id, durationMs: Date.now() - startedAt, ...details });
+        throw error;
+    }
+    finally {
+        if (ownAbort !== undefined)
+            process.off('SIGINT', onInterrupt);
+    }
+}
+async function executeMediaCommand(invocation, runtime, cwd, output, activity, signal) {
+    const action = invocation.action.id;
+    if (action !== 'video.status')
+        await runtime.projectTrust.requireTrusted(await runtime.projectTrust.inspect(cwd));
+    const loaded = await loadExecutionConfig(runtime, cwd);
+    const profileName = loaded.config.profile ?? AuthenticationService.defaultProfileName();
+    const credential = await runtime.auth.requireCredential(profileName);
+    const client = new SdkMediaGatewayClient(createLotaGateClient(credential.profile, credential.apiKey));
+    const store = new WorkspaceMediaArtifactStore(cwd, runtime.logger);
+    const policy = resolveMediaExecutionPolicy();
+    if (action === 'video.status')
+        return showVideoStatus(requirePositional(invocation.positionals, 0, 'operation id'), client, runtime.logger, output, activity, signal);
+    if (action === 'video.download')
+        return downloadVideo(requirePositional(invocation.positionals, 0, 'operation id'), invocation.options, client, store, runtime.logger, output, activity, signal);
+    const model = await resolveModel(invocation.options, loaded.config.model, runtime, cwd);
+    if (action === 'image.generate')
+        return generateImage(invocation.positionals, invocation.options, model, client, store, policy.downloadTimeoutMs, output, activity, signal);
+    if (action === 'image.edit')
+        return editImage(invocation.positionals, invocation.options, model, client, store, cwd, policy.downloadTimeoutMs, output, activity, signal);
+    if (action === 'audio.speech')
+        return createSpeech(invocation.positionals, invocation.options, model, client, store, output, activity, signal);
+    if (action === 'audio.transcribe' || action === 'audio.translate')
+        return processAudio(action, invocation.options, model, client, store, cwd, output, activity, signal);
+    if (action === 'video.generate')
+        return createVideo(invocation.positionals, invocation.options, model, client, store, policy, runtime, output, activity, signal);
+    throw new Error(`Unsupported media command: ${action}`);
+}
+async function resolveModel(flags, selected, runtime, cwd) {
+    const model = getStringFlag(flags, 'model') ?? selected;
+    if (model === null || model === undefined)
+        throw new CliError(CLI_ERROR_CODES.MODEL_NOT_FOUND, 'No model is selected.', { category: 'model', userMessage: 'No model is selected.', hint: MODEL_SELECT_HINT });
+    const catalog = await loadModelCatalog(runtime, cwd);
+    if (!catalog.data.some((candidate) => candidate.id === model)) {
+        throw new CliError(CLI_ERROR_CODES.MODEL_NOT_FOUND, `Model is not available: ${model}`, { category: 'model', userMessage: `Model is not available: ${model}.`, hint: MODEL_SELECT_HINT });
+    }
+    return model;
+}
+async function generateImage(positionals, flags, model, client, store, downloadTimeoutMs, output, activity, signal) {
+    const prompt = requirePrompt(positionals, 'image');
+    const images = await withActivity(activity, 'image.generate', 'image generation', () => client.generateImage({ model, prompt, ...imageOptions(flags) }, { signal }));
+    const stored = await withActivity(activity, 'image.store', 'image download and save', () => storeImages(images, artifactRequest('image', prompt, requestedImageExtension(flags), flags), store, downloadTimeoutMs, signal));
+    const paths = stored.map((item) => item.path);
+    writeMediaCommandResult(output, { kind: 'media', mediaType: 'image', artifacts: paths.map((path) => ({ path })) }, formatStored('Generated image', paths));
+    return 0;
+}
+async function editImage(positionals, flags, model, client, store, cwd, downloadTimeoutMs, output, activity, signal) {
+    const prompt = requirePrompt(positionals, 'image edit');
+    const input = await readGatewayImageEditInput(requireStringFlag(flags, 'image'), getStringFlag(flags, 'mask'), cwd);
+    const result = await withActivity(activity, 'image.edit', 'image edit', () => client.editImage({
+        model,
+        prompt,
+        images: [...input.images],
+        ...(input.mask === undefined ? {} : { mask: input.mask }),
+        ...imageOptions(flags),
+        ...(getStringFlag(flags, 'input-fidelity') === undefined ? {} : { inputFidelity: getStringFlag(flags, 'input-fidelity') }),
+    }, { signal }));
+    const stored = await withActivity(activity, 'image.store', 'image download and save', () => storeImages(result, artifactRequest('image', prompt, requestedImageExtension(flags), flags), store, downloadTimeoutMs, signal));
+    const paths = stored.map((item) => item.path);
+    writeMediaCommandResult(output, { kind: 'media', mediaType: 'image', artifacts: paths.map((path) => ({ path })) }, formatStored('Generated image', paths));
+    return 0;
+}
+async function createSpeech(positionals, flags, model, client, store, output, activity, signal) {
+    const input = requirePrompt(positionals, 'speech');
+    const responseFormat = getStringFlag(flags, 'response-format');
+    const audio = await withActivity(activity, 'audio.speech', 'speech generation', () => client.createSpeech({
+        model,
+        input,
+        voice: requireStringFlag(flags, 'voice'),
+        ...(getStringFlag(flags, 'instructions') === undefined ? {} : { instructions: getStringFlag(flags, 'instructions') }),
+        ...(responseFormat === undefined ? {} : { responseFormat }),
+        ...(getNumberFlag(flags, 'speed') === undefined ? {} : { speed: getNumberFlag(flags, 'speed') }),
+    }, { signal }));
+    assertBinaryOutputSize(audio.bytes);
+    const extension = responseFormat ?? extensionFromContentType(audio.contentType, 'mp3');
+    const stored = await withActivity(activity, 'audio.store', 'speech save', () => store.writeMany(artifactRequest('speech', input, extension, flags), [audio.bytes]));
+    const paths = stored.map((item) => item.path);
+    writeMediaCommandResult(output, { kind: 'media', mediaType: 'audio', artifacts: paths.map((path) => ({ path })) }, formatStored('Generated speech', paths));
+    return 0;
+}
+async function processAudio(action, flags, model, client, store, cwd, output, activity, signal) {
+    const input = await readGatewayAudioInput(requireStringFlag(flags, 'file'), cwd);
+    const responseFormat = getStringFlag(flags, 'response-format') ?? 'json';
+    const payload = {
+        model,
+        file: input.bytes,
+        filename: input.filename,
+        responseFormat,
+        ...(getStringFlag(flags, 'prompt') === undefined ? {} : { prompt: getStringFlag(flags, 'prompt') }),
+        ...(getNumberFlag(flags, 'temperature') === undefined ? {} : { temperature: getNumberFlag(flags, 'temperature') }),
+        ...(action === 'audio.transcribe' && getStringFlag(flags, 'language') !== undefined ? { language: getStringFlag(flags, 'language') } : {}),
+        ...(action === 'audio.transcribe' ? optionalCsv(flags, 'timestamp-granularities', ['word', 'segment']) : {}),
+        ...(action === 'audio.transcribe' ? optionalCsv(flags, 'include') : {}),
+    };
+    const text = await withActivity(activity, action, action === 'audio.transcribe' ? 'audio transcription' : 'audio translation', () => (action === 'audio.transcribe' ? client.transcribe(payload, { signal }) : client.translate(payload, { signal })));
+    const kind = action === 'audio.transcribe' ? 'transcription' : 'translation';
+    const stored = await withActivity(activity, `${action}.store`, `${kind} save`, () => store.writeMany(artifactRequest(kind, input.sourceName, textExtension(responseFormat), flags), [Buffer.from(text, 'utf8')]));
+    if (isTextResponseFormat(responseFormat))
+        output.write(`${text}\nSaved ${kind}: ${stored[0].path}\n`);
+    else
+        output.write(formatStored(`${capitalize(kind)} result`, stored.map((item) => item.path)));
+    return 0;
+}
+async function createVideo(positionals, flags, model, client, store, policy, runtime, output, activity, signal) {
+    const prompt = requirePrompt(positionals, 'video');
+    const parameters = parseParameters(getStringFlag(flags, 'parameters'));
+    const operation = await withActivity(activity, 'video.create', 'video generation request', () => client.createVideo({ model, prompt, ...(parameters === undefined ? {} : { parameters }) }, { signal }));
+    if (operation.errorMessage !== undefined)
+        throw videoError(operation);
+    runtime.logger.info('Video generation accepted.', { operationId: operation.id, model });
+    output.write(`Video operation: ${operation.id}\n`);
+    if (isFlagEnabled(flags, 'no-wait'))
+        return 0;
+    const completed = operation.done ? operation : await withActivity(activity, `video.wait:${operation.id}`, 'video generation', () => waitForVideoOperation(client, operation.id, policy, signal));
+    if (completed.errorMessage !== undefined)
+        throw videoError(completed);
+    const binary = await withActivity(activity, `video.download:${operation.id}`, 'video download', () => client.downloadVideo(operation.id, { signal }));
+    assertBinaryOutputSize(binary.bytes);
+    const stored = await withActivity(activity, `video.store:${operation.id}`, 'video save', () => store.writeMany(artifactRequest('video', prompt, extensionFromContentType(binary.contentType, 'mp4'), flags), [binary.bytes]));
+    runtime.logger.info('Video artifact stored.', { operationId: operation.id, artifactCount: stored.length, artifactBytes: sumArtifactBytes(stored) });
+    const paths = stored.map((item) => item.path);
+    writeMediaCommandResult(output, { kind: 'media', mediaType: 'video', artifacts: paths.map((path) => ({ path })) }, formatStored('Generated video', paths));
+    return 0;
+}
+async function showVideoStatus(id, client, logger, output, activity, signal) {
+    const operation = await withActivity(activity, `video.status:${id}`, 'video status', () => client.getVideoOperation(id, { signal }), (result) => result.errorMessage !== undefined);
+    logger.info('Video status retrieved.', { operationId: operation.id, status: operation.errorMessage === undefined ? (operation.done ? 'completed' : 'pending') : 'failed' });
+    if (operation.errorMessage !== undefined) {
+        throw videoError(operation);
+    }
+    output.write(`Video operation ${operation.id}: ${operation.done ? 'COMPLETED' : 'PENDING'}\n`);
+    return 0;
+}
+async function downloadVideo(id, flags, client, store, logger, output, activity, signal) {
+    const binary = await withActivity(activity, `video.download:${id}`, 'video download', () => client.downloadVideo(id, { signal }));
+    assertBinaryOutputSize(binary.bytes);
+    const stored = await withActivity(activity, `video.store:${id}`, 'video save', () => store.writeMany(artifactRequest('video', id, extensionFromContentType(binary.contentType, 'mp4'), flags), [binary.bytes]));
+    logger.info('Video artifact downloaded.', { operationId: id, artifactCount: stored.length, artifactBytes: sumArtifactBytes(stored) });
+    const paths = stored.map((item) => item.path);
+    writeMediaCommandResult(output, { kind: 'media', mediaType: 'video', artifacts: paths.map((path) => ({ path })) }, formatStored('Downloaded video', paths));
+    return 0;
+}
+function imageOptions(flags) {
+    const quality = getStringFlag(flags, 'quality');
+    const background = getStringFlag(flags, 'background');
+    const outputFormat = getStringFlag(flags, 'output-format');
+    return {
+        ...(getIntegerFlag(flags, 'n') === undefined ? {} : { n: getIntegerFlag(flags, 'n') }),
+        ...(getStringFlag(flags, 'size') === undefined ? {} : { size: getStringFlag(flags, 'size') }),
+        ...(quality === undefined ? {} : { quality: quality }),
+        ...(background === undefined ? {} : { background: background }),
+        ...(outputFormat === undefined ? {} : { outputFormat: outputFormat }),
+        ...(getIntegerFlag(flags, 'output-compression') === undefined ? {} : { outputCompression: getIntegerFlag(flags, 'output-compression') }),
+        ...(getStringFlag(flags, 'moderation') === undefined ? {} : { moderation: getStringFlag(flags, 'moderation') }),
+        ...(getStringFlag(flags, 'user') === undefined ? {} : { user: getStringFlag(flags, 'user') }),
+    };
+}
+function artifactRequest(kind, source, extension, flags) {
+    const out = getStringFlag(flags, 'out');
+    const outDir = getStringFlag(flags, 'out-dir');
+    return { kind, source, extension, ...(out === undefined ? {} : { out }), ...(outDir === undefined ? {} : { outDir }), force: isFlagEnabled(flags, 'force') };
+}
+async function storeImages(images, request, store, downloadTimeoutMs, signal) {
+    const bytes = [];
+    let extension = request.extension;
+    for (const image of images) {
+        const normalized = image.base64 === undefined
+            ? await downloadGeneratedImage(image.url, downloadTimeoutMs, signal)
+            : decodeImage(image.base64);
+        bytes.push(normalized.bytes);
+        extension = imageExtension(normalized.mimeType, extension);
+    }
+    return store.writeMany({ ...request, extension }, bytes);
+}
+function decodeImage(value) {
+    if (!/^[A-Za-z0-9+/]*={0,2}$/u.test(value) || value.length % 4 !== 0)
+        throw mediaError('The provider returned invalid Base64 image data.');
+    const bytes = Buffer.from(value, 'base64');
+    assertBinaryOutputSize(bytes);
+    return normalizeImage(bytes, undefined, SDK_BINARY_MEDIA_RESPONSE_BYTES);
+}
+async function downloadGeneratedImage(value, timeoutMs, signal) {
+    const download = await downloadPublicMedia(value, { maxBytes: SDK_BINARY_MEDIA_RESPONSE_BYTES, timeoutMs, signal });
+    const normalized = normalizeImage(download.bytes, download.contentType, SDK_BINARY_MEDIA_RESPONSE_BYTES);
+    if (!['image/png', 'image/jpeg', 'image/webp'].includes(normalized.mimeType))
+        throw mediaError(`Unsupported generated image format: ${normalized.mimeType}.`);
+    return normalized;
+}
+function requirePrompt(positionals, label) {
+    const value = positionals.join(' ').trim();
+    if (value.length === 0)
+        throw mediaError(`A prompt is required for ${label}.`);
+    return value;
+}
+function getIntegerFlag(flags, name) {
+    const value = getStringFlag(flags, name);
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/u.test(value) || !Number.isSafeInteger(Number(value)))
+        throw mediaError(`--${name} must be an integer.`);
+    return Number(value);
+}
+function getNumberFlag(flags, name) {
+    const value = getStringFlag(flags, name);
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        throw mediaError(`--${name} must be a finite number.`);
+    return parsed;
+}
+function optionalCsv(flags, name, allowed) {
+    const value = getStringFlag(flags, name);
+    if (value === undefined)
+        return {};
+    const values = value.split(',').map((item) => item.trim()).filter(Boolean);
+    if (values.length === 0 || (allowed !== undefined && values.some((item) => !allowed.includes(item))))
+        throw mediaError(`--${name} contains an unsupported value.`);
+    return name === 'timestamp-granularities' ? { timestampGranularities: values } : { include: values };
+}
+function parseParameters(raw) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        const value = JSON.parse(raw);
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            throw new Error();
+        return value;
+    }
+    catch {
+        throw mediaError('--parameters must be a JSON object.');
+    }
+}
+function requestedImageExtension(flags) { return getStringFlag(flags, 'output-format') ?? 'png'; }
+function imageExtension(mimeType, fallback) { return mimeType === 'image/jpeg' ? 'jpeg' : mimeType === 'image/webp' ? 'webp' : mimeType === 'image/png' ? 'png' : fallback; }
+function extensionFromContentType(contentType, fallback) { const type = contentType?.toLowerCase(); if (type === 'audio/mpeg')
+    return 'mp3'; if (type === 'audio/ogg')
+    return 'opus'; if (type === 'audio/aac')
+    return 'aac'; if (type === 'audio/flac')
+    return 'flac'; if (type === 'audio/wav' || type === 'audio/x-wav')
+    return 'wav'; if (type === 'video/webm')
+    return 'webm'; if (type === 'video/quicktime')
+    return 'mov'; if (type === 'video/mp4')
+    return 'mp4'; return fallback; }
+function textExtension(format) { return format === 'text' ? 'txt' : format === 'verbose_json' || format === 'diarized_json' ? 'json' : format; }
+function isTextResponseFormat(format) { return format === 'text' || format === 'srt' || format === 'vtt'; }
+function assertBinaryOutputSize(bytes) { if (bytes.byteLength === 0 || bytes.byteLength > SDK_BINARY_MEDIA_RESPONSE_BYTES)
+    throw mediaError('Generated media exceeds the supported binary output limit.'); }
+function formatStored(label, paths) { return `${label}${paths.length === 1 ? '' : 's'} saved:\n${paths.map((item) => `  ${item}`).join('\n')}\n`; }
+function capitalize(value) { return `${value[0]?.toUpperCase() ?? ''}${value.slice(1)}`; }
+function sumArtifactBytes(artifacts) { return artifacts.reduce((total, artifact) => total + artifact.bytes, 0); }
+function mediaError(userMessage) { return new CliError(CLI_ERROR_CODES.INVALID_ARGUMENT, userMessage, { category: 'media', userMessage }); }
+function videoError(operation) { return new CliError('MEDIA_VIDEO_FAILED', `Video operation failed: ${operation.id}`, { category: 'media', userMessage: operation.errorMessage ?? `Video operation failed: ${operation.id}` }); }
+async function withActivity(activity, key, label, operation, isFailure = () => false) {
+    const entry = activity?.start(key, label);
+    try {
+        const result = await operation();
+        entry?.complete(isFailure(result));
+        return result;
+    }
+    catch (error) {
+        entry?.complete(true);
+        throw error;
+    }
+}

package/dist/application/commands/media-command-output.d.ts

@@ -0,0 +1,11 @@
+import type { CommandOutput } from './command-output.js';
+export type MediaArtifactType = 'image' | 'audio' | 'video';
+export interface MediaCommandResult {
+    readonly kind: 'media';
+    readonly mediaType: MediaArtifactType;
+    readonly artifacts: readonly {
+        readonly path: string;
+    }[];
+}
+/** Keeps normal CLI output text while exposing media metadata to Desktop protocol callers. */
+export declare function writeMediaCommandResult(output: CommandOutput, result: MediaCommandResult, fallbackText: string): void;

package/dist/application/commands/media-command-output.js

@@ -0,0 +1,8 @@
+/** Keeps normal CLI output text while exposing media metadata to Desktop protocol callers. */
+export function writeMediaCommandResult(output, result, fallbackText) {
+    if (output.writeStructured === undefined) {
+        output.write(fallbackText);
+        return;
+    }
+    output.writeStructured(result, fallbackText);
+}

package/dist/application/commands/runtime-command-handlers.d.ts

@@ -0,0 +1,7 @@
+import type { CommandOutput } from './command-output.js';
+import type { createCompositionRoot } from '../../bootstrap/composition-root.js';
+type CliRuntime = ReturnType<typeof createCompositionRoot>;
+export declare function runSessionCommand(positionals: readonly string[], flags: ReadonlyMap<string, string | boolean>, runtime: CliRuntime, cwd: string, stdout: CommandOutput, resumeInteractive?: (sessionId: string) => Promise<number>): Promise<number>;
+export declare function runChatCommand(positionals: readonly string[], runtime: CliRuntime, cwd: string, stdout: CommandOutput): Promise<number>;
+export declare function runExecCommand(positionals: readonly string[], flags: ReadonlyMap<string, string | boolean>, runtime: CliRuntime, cwd: string, stdout: CommandOutput): Promise<number>;
+export {};