@bbigbang/cli 0.1.0

package/dist/commands/reminderCommands.js

@@ -0,0 +1,220 @@
+import { AGENT_COMMAND_ERROR_CODES, AgentCommandError, appendReminderConversation, createRuntime, normalizeOptionalReminderScheduleKind, normalizeReminderIntervalUnit, normalizeReminderScheduleKind, parseJsonObjectStringOrThrow, parseNumber, parsePositiveInteger, parseRequiredNumber, parseSnoozeDuration, readOptionalStdin, requireConversationId, requireString, responseError, summarizeReminderAction, summarizeReminderCurrent, summarizeReminderList, summarizeReminderLog, summarizeReminderOccurrences, summarizeReminderSnooze, writeOutput } from '../cliSupport.js';
+export function registerReminderCommands(program, options) {
+    const reminder = program.command('reminder').description('Reminder operations for the current DM scope');
+    reminder.command('list')
+        .description('List reminders in the current DM scope')
+        .action(async () => {
+        const runtime = createRuntime(program, options);
+        const params = new URLSearchParams();
+        params.set('conversationId', requireConversationId(runtime, 'reminder list'));
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminders?${params.toString()}`);
+        if (!response.ok)
+            throw responseError(response, 'list reminders failed');
+        writeOutput(runtime, summarizeReminderList(response.data), response.data);
+    });
+    reminder.command('create')
+        .description('Create a reminder from flags or stdin JSON')
+        .option('--title <title>', 'Reminder title')
+        .option('--prompt-text <text>', 'Reminder task brief')
+        .option('--schedule-kind <kind>', 'one_time or recurring')
+        .option('--start-at <ms>', 'First trigger time as unix milliseconds')
+        .option('--interval-unit <unit>', 'Recurring interval unit: hour, day, week')
+        .option('--interval-value <n>', 'Recurring interval value')
+        .option('--end-at <ms>', 'Optional end time as unix milliseconds')
+        .option('--max-occurrences <n>', 'Optional recurring occurrence cap')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const stdin = (await readOptionalStdin(runtime.io.stdin)) ?? '';
+        const body = stdin
+            ? parseJsonObjectStringOrThrow(stdin, 'reminder create JSON payload')
+            : {
+                title: requireString(opts.title, '--title'),
+                promptText: requireString(opts.promptText, '--prompt-text'),
+                scheduleKind: normalizeReminderScheduleKind(opts.scheduleKind),
+                startAt: parseRequiredNumber('start-at', opts.startAt),
+                ...(normalizeReminderIntervalUnit(opts.intervalUnit) ? { intervalUnit: normalizeReminderIntervalUnit(opts.intervalUnit) } : {}),
+                ...(parsePositiveInteger('interval-value', opts.intervalValue) !== undefined ? { intervalValue: parsePositiveInteger('interval-value', opts.intervalValue) } : {}),
+                ...(parseNumber('end-at', opts.endAt) !== undefined ? { endAt: parseNumber('end-at', opts.endAt) } : {}),
+                ...(parsePositiveInteger('max-occurrences', opts.maxOccurrences) !== undefined ? { maxOccurrences: parsePositiveInteger('max-occurrences', opts.maxOccurrences) } : {}),
+            };
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminders`, appendReminderConversation(runtime, 'reminder create', body));
+        if (!response.ok)
+            throw responseError(response, 'create reminder failed');
+        writeOutput(runtime, summarizeReminderAction('Created', response.data), response.data);
+    });
+    reminder.command('update')
+        .description('Update a reminder in the current DM scope from flags or stdin JSON')
+        .requiredOption('--reminder-id <id>', 'Reminder id')
+        .option('--title <title>', 'New title')
+        .option('--prompt-text <text>', 'New task brief')
+        .option('--schedule-kind <kind>', 'one_time or recurring')
+        .option('--start-at <ms>', 'New start time as unix milliseconds')
+        .option('--interval-unit <unit>', 'Recurring interval unit: hour, day, week')
+        .option('--interval-value <n>', 'Recurring interval value')
+        .option('--end-at <ms>', 'Optional end time as unix milliseconds')
+        .option('--max-occurrences <n>', 'Optional recurring occurrence cap')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const reminderId = requireString(opts.reminderId, '--reminder-id');
+        const stdin = (await readOptionalStdin(runtime.io.stdin)) ?? '';
+        const body = stdin
+            ? parseJsonObjectStringOrThrow(stdin, 'reminder update JSON payload')
+            : {};
+        if (!stdin) {
+            if (opts.title !== undefined)
+                body.title = String(opts.title);
+            if (opts.promptText !== undefined)
+                body.promptText = String(opts.promptText);
+            const scheduleKind = normalizeOptionalReminderScheduleKind(opts.scheduleKind);
+            if (scheduleKind !== undefined)
+                body.scheduleKind = scheduleKind;
+            const startAt = parseNumber('start-at', opts.startAt);
+            if (startAt !== undefined)
+                body.startAt = startAt;
+            const intervalUnit = normalizeReminderIntervalUnit(opts.intervalUnit);
+            if (intervalUnit !== undefined)
+                body.intervalUnit = intervalUnit;
+            const intervalValue = parsePositiveInteger('interval-value', opts.intervalValue);
+            if (intervalValue !== undefined)
+                body.intervalValue = intervalValue;
+            const endAt = parseNumber('end-at', opts.endAt);
+            if (endAt !== undefined)
+                body.endAt = endAt;
+            const maxOccurrences = parsePositiveInteger('max-occurrences', opts.maxOccurrences);
+            if (maxOccurrences !== undefined)
+                body.maxOccurrences = maxOccurrences;
+        }
+        const response = await runtime.client.request('PATCH', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminders/${encodeURIComponent(reminderId)}`, appendReminderConversation(runtime, 'reminder update', body));
+        if (!response.ok)
+            throw responseError(response, 'update reminder failed');
+        writeOutput(runtime, summarizeReminderAction('Updated', response.data, reminderId), response.data);
+    });
+    const simpleReminderAction = (name, routeSuffix, label) => {
+        reminder.command(name)
+            .description(`${label} a reminder in the current DM scope`)
+            .requiredOption('--reminder-id <id>', 'Reminder id')
+            .action(async (opts) => {
+            const runtime = createRuntime(program, options);
+            const reminderId = requireString(opts.reminderId, '--reminder-id');
+            const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminders/${encodeURIComponent(reminderId)}/${routeSuffix}`, appendReminderConversation(runtime, `reminder ${name}`));
+            if (!response.ok)
+                throw responseError(response, `${name} reminder failed`);
+            writeOutput(runtime, summarizeReminderAction(label, response.data, reminderId), response.data);
+        });
+    };
+    simpleReminderAction('pause', 'pause', 'Paused');
+    simpleReminderAction('resume', 'resume', 'Resumed');
+    simpleReminderAction('cancel', 'cancel', 'Cancelled');
+    simpleReminderAction('run-now', 'run-now', 'Ran');
+    simpleReminderAction('abandon', 'abandon', 'Abandoned');
+    reminder.command('occurrences')
+        .description('List recent occurrences for one reminder')
+        .requiredOption('--reminder-id <id>', 'Reminder id')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const reminderId = requireString(opts.reminderId, '--reminder-id');
+        const params = new URLSearchParams();
+        params.set('conversationId', requireConversationId(runtime, 'reminder occurrences'));
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminders/${encodeURIComponent(reminderId)}/occurrences?${params.toString()}`);
+        if (!response.ok)
+            throw responseError(response, 'list reminder occurrences failed');
+        writeOutput(runtime, summarizeReminderOccurrences(response.data), response.data);
+    });
+    reminder.command('current')
+        .description('Read current and latest occurrence for one reminder')
+        .requiredOption('--reminder-id <id>', 'Reminder id')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const reminderId = requireString(opts.reminderId, '--reminder-id');
+        const params = new URLSearchParams();
+        params.set('conversationId', requireConversationId(runtime, 'reminder current'));
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminders/${encodeURIComponent(reminderId)}/current-occurrence?${params.toString()}`);
+        if (!response.ok)
+            throw responseError(response, 'get current reminder occurrence failed');
+        writeOutput(runtime, summarizeReminderCurrent(response.data), response.data);
+    });
+    reminder.command('submit-for-review')
+        .description('Submit a one-time reminder occurrence for user review')
+        .option('--occurrence-id <id>', 'Occurrence id')
+        .option('--reminder-id <id>', 'Reminder id; submits current open occurrence when occurrence id is omitted')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const occurrenceId = typeof opts.occurrenceId === 'string' ? opts.occurrenceId.trim() : '';
+        const reminderId = typeof opts.reminderId === 'string' ? opts.reminderId.trim() : '';
+        if (!occurrenceId && !reminderId) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, 'Provide --occurrence-id or --reminder-id.');
+        }
+        const path = occurrenceId
+            ? `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminder-occurrences/${encodeURIComponent(occurrenceId)}/submit-for-review`
+            : `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminders/${encodeURIComponent(reminderId)}/submit-current-for-review`;
+        const response = await runtime.client.request('POST', path, appendReminderConversation(runtime, 'reminder submit-for-review'));
+        if (!response.ok)
+            throw responseError(response, 'submit reminder occurrence for review failed');
+        writeOutput(runtime, summarizeReminderAction('Submitted for review', response.data, occurrenceId || reminderId), response.data);
+    });
+    reminder.command('complete')
+        .description('Complete a recurring reminder occurrence; one-time reminders should be submitted for review and completed by the user')
+        .option('--occurrence-id <id>', 'Occurrence id')
+        .option('--reminder-id <id>', 'Reminder id; completes current open occurrence when occurrence id is omitted')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const occurrenceId = typeof opts.occurrenceId === 'string' ? opts.occurrenceId.trim() : '';
+        const reminderId = typeof opts.reminderId === 'string' ? opts.reminderId.trim() : '';
+        if (!occurrenceId && !reminderId) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, 'Provide --occurrence-id or --reminder-id.');
+        }
+        const path = occurrenceId
+            ? `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminder-occurrences/${encodeURIComponent(occurrenceId)}/complete`
+            : `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminders/${encodeURIComponent(reminderId)}/complete-current`;
+        const response = await runtime.client.request('POST', path, appendReminderConversation(runtime, 'reminder complete'));
+        if (!response.ok)
+            throw responseError(response, 'complete reminder occurrence failed');
+        writeOutput(runtime, summarizeReminderAction('Completed', response.data, occurrenceId || reminderId), response.data);
+    });
+    reminder.command('log')
+        .description('Read the lifecycle event log for a reminder')
+        .requiredOption('--reminder-id <id>', 'Reminder id')
+        .option('--limit <n>', 'Maximum events to return')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const reminderId = requireString(opts.reminderId, '--reminder-id');
+        const params = new URLSearchParams();
+        const limit = parsePositiveInteger('limit', opts.limit);
+        if (limit !== undefined)
+            params.set('limit', String(limit));
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminders/${encodeURIComponent(reminderId)}/log${qs ? `?${qs}` : ''}`);
+        if (!response.ok)
+            throw responseError(response, 'read reminder log failed');
+        writeOutput(runtime, summarizeReminderLog(reminderId, response.data), response.data);
+    });
+    reminder.command('snooze')
+        .description('Snooze a reminder occurrence by a relative duration')
+        .requiredOption('--occurrence-id <id>', 'Occurrence id')
+        .requiredOption('--by <duration>', 'Duration until next run: 30m, 2h, 1d')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const occurrenceId = requireString(opts.occurrenceId, '--occurrence-id');
+        const { until } = parseSnoozeDuration(opts.by);
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminder-occurrences/${encodeURIComponent(occurrenceId)}/snooze`, appendReminderConversation(runtime, 'reminder snooze', { until }));
+        if (!response.ok)
+            throw responseError(response, 'snooze reminder occurrence failed');
+        writeOutput(runtime, summarizeReminderSnooze(response.data), response.data);
+    });
+    reminder.command('skip')
+        .description('Skip a reminder occurrence')
+        .requiredOption('--occurrence-id <id>', 'Occurrence id')
+        .option('--reason <reason>', 'Optional short reason to store with the skip event')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const occurrenceId = requireString(opts.occurrenceId, '--occurrence-id');
+        const body = {};
+        if (typeof opts.reason === 'string' && opts.reason.trim().length > 0) {
+            body.reason = opts.reason.trim();
+        }
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/reminder-occurrences/${encodeURIComponent(occurrenceId)}/skip`, appendReminderConversation(runtime, 'reminder skip', body));
+        if (!response.ok)
+            throw responseError(response, 'skip reminder occurrence failed');
+        writeOutput(runtime, summarizeReminderAction('Skipped', response.data, occurrenceId), response.data);
+    });
+}

package/dist/commands/skillToolAttachmentCommands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { BuildBigbangProgramOptions } from '../cliSupport.js';
+export declare function registerSkillToolAttachmentCommands(program: Command, options: BuildBigbangProgramOptions): void;

package/dist/commands/skillToolAttachmentCommands.js

@@ -0,0 +1,261 @@
+import { readFileSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
+import { AGENT_COMMAND_ERROR_CODES, AgentCommandError, ATTACHMENT_UPLOAD_MAX_BYTES, MUTATION_HINTS, appendCommonBody, appendRunContextParams, createRuntime, fetchBinaryRaw, fetchJsonRaw, formatSize, inferMimeType, parseJsonObjectStringOrThrow, parsePositiveInteger, readOptionalStdin, requireString, responseError, summarizeAttachmentComments, summarizeAttachmentUpload, summarizeAttachmentView, summarizeSkillFile, summarizeSkillList, summarizeToolAction, summarizeToolPublish, summarizeToolStatus, summarizeToolValidate, summarizeToolVerification, withHint, writeOutput } from '../cliSupport.js';
+export function registerSkillToolAttachmentCommands(program, options) {
+    const skill = program.command('skill').description('Agent skill operations');
+    skill.command('list')
+        .description('List configured skills or entries under a skill directory')
+        .option('--path <path>', 'Absolute skill directory path under a configured skill root')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const params = new URLSearchParams();
+        if (opts.path)
+            params.set('path', requireString(opts.path, '--path'));
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/skills${qs ? `?${qs}` : ''}`);
+        if (!response.ok)
+            throw responseError(response, 'list skills failed');
+        writeOutput(runtime, summarizeSkillList(response.data), response.data);
+    });
+    skill.command('read')
+        .description('Read a text skill file')
+        .requiredOption('--path <path>', 'Absolute skill file path under a configured skill root')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const params = new URLSearchParams();
+        params.set('path', requireString(opts.path, '--path'));
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/skills/file?${params.toString()}`);
+        if (!response.ok)
+            throw responseError(response, 'read skill file failed');
+        writeOutput(runtime, summarizeSkillFile(response.data), response.data);
+    });
+    const tool = program.command('tool').description('Workspace Tool operations');
+    tool.command('publish')
+        .description('Publish a Workspace Tool manifest from the current agent workspace')
+        .requiredOption('--manifest-path <path>', 'Workspace-relative path to tool.json')
+        .option('--source-message-id <id>', 'Source message id to associate with the published tool')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const manifestPath = requireString(opts.manifestPath, '--manifest-path');
+        const stdin = (await readOptionalStdin(runtime.io.stdin)) ?? '';
+        const body = {
+            manifestPath,
+        };
+        if (stdin.trim()) {
+            body.manifestContent = stdin;
+        }
+        else {
+            try {
+                const manifestContent = runtime.readFile(manifestPath);
+                if (manifestContent.trim())
+                    body.manifestContent = manifestContent;
+            }
+            catch {
+                // Core can still attempt the workspace read; this preserves legacy path-only behavior.
+            }
+        }
+        if (opts.sourceMessageId)
+            body.sourceMessageId = opts.sourceMessageId;
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/tools/publish`, appendCommonBody(runtime, body));
+        if (!response.ok)
+            throw responseError(response, 'workspace tool publish failed');
+        writeOutput(runtime, withHint(summarizeToolPublish(response.data), MUTATION_HINTS.toolPublish), response.data);
+    });
+    tool.command('validate')
+        .description('Validate a Workspace Tool manifest without publishing')
+        .requiredOption('--manifest-path <path>', 'Workspace-relative path to tool.json')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const manifestPath = requireString(opts.manifestPath, '--manifest-path');
+        const stdin = (await readOptionalStdin(runtime.io.stdin)) ?? '';
+        const body = {
+            manifestPath,
+        };
+        if (stdin.trim()) {
+            body.manifestContent = stdin;
+        }
+        else {
+            try {
+                const manifestContent = runtime.readFile(manifestPath);
+                if (manifestContent.trim())
+                    body.manifestContent = manifestContent;
+            }
+            catch {
+                // Core can still attempt the workspace read; this preserves legacy path-only behavior.
+            }
+        }
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/tools/publish?dryRun=true`, appendCommonBody(runtime, body));
+        if (!response.ok)
+            throw responseError(response, 'workspace tool validate failed');
+        const record = response.data && typeof response.data === 'object' ? response.data : {};
+        const isValid = record.valid === true;
+        writeOutput(runtime, summarizeToolValidate(response.data), response.data);
+        if (!isValid) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_INPUT, 'Workspace tool manifest validation failed.');
+        }
+    });
+    tool.command('status')
+        .description('Read Workspace Tool runtime and revision status')
+        .requiredOption('--tool-id <id>', 'Workspace Tool id')
+        .option('--include-runs', 'Include recent run history')
+        .option('--run-limit <n>', 'Recent run limit when --include-runs is used')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const params = appendRunContextParams(runtime, new URLSearchParams());
+        if (opts.includeRuns)
+            params.set('include_runs', 'true');
+        const runLimit = parsePositiveInteger('run-limit', opts.runLimit);
+        if (runLimit !== undefined)
+            params.set('run_limit', String(Math.min(runLimit, 20)));
+        const toolId = requireString(opts.toolId, '--tool-id');
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/tools/${encodeURIComponent(toolId)}/status${qs ? `?${qs}` : ''}`);
+        if (!response.ok)
+            throw responseError(response, 'workspace tool status failed');
+        writeOutput(runtime, summarizeToolStatus(response.data), response.data);
+    });
+    tool.command('run')
+        .description('Run a Workspace Tool action')
+        .requiredOption('--tool-id <id>', 'Workspace Tool id')
+        .requiredOption('--action-id <id>', 'Action id from the tool manifest')
+        .option('--params-json <json>', 'Action params as a JSON object; stdin JSON object takes precedence')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const toolId = requireString(opts.toolId, '--tool-id');
+        const actionId = requireString(opts.actionId, '--action-id');
+        const stdin = (await readOptionalStdin(runtime.io.stdin)) ?? '';
+        const params = stdin.trim()
+            ? parseJsonObjectStringOrThrow(stdin, 'tool action params JSON payload')
+            : opts.paramsJson
+                ? parseJsonObjectStringOrThrow(String(opts.paramsJson), '--params-json')
+                : {};
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/tools/${encodeURIComponent(toolId)}/actions/${encodeURIComponent(actionId)}`, appendCommonBody(runtime, { params }));
+        if (!response.ok)
+            throw responseError(response, 'workspace tool action failed');
+        writeOutput(runtime, summarizeToolAction(response.data, actionId), response.data);
+    });
+    tool.command('verify')
+        .description('Write back target-machine verification for an installed Workspace Tool')
+        .requiredOption('--tool-id <id>', 'Workspace Tool id')
+        .requiredOption('--status <status>', 'Verification status: verified, warning, or failed')
+        .requiredOption('--summary <text>', 'Short verification summary')
+        .option('--details-json <json>', 'Additional verification details as a JSON object')
+        .option('--smoke-run-id <id>', 'Workspace Tool run id from a smoke action, when available')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const toolId = requireString(opts.toolId, '--tool-id');
+        const status = requireString(opts.status, '--status');
+        const summary = requireString(opts.summary, '--summary');
+        const details = opts.detailsJson
+            ? parseJsonObjectStringOrThrow(String(opts.detailsJson), '--details-json')
+            : undefined;
+        const body = { status, summary };
+        if (details)
+            body.details = details;
+        if (opts.smokeRunId)
+            body.smokeRunId = requireString(opts.smokeRunId, '--smoke-run-id');
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/tools/${encodeURIComponent(toolId)}/verify`, appendCommonBody(runtime, body));
+        if (!response.ok)
+            throw responseError(response, 'workspace tool verification failed');
+        writeOutput(runtime, summarizeToolVerification(response.data), response.data);
+    });
+    const attachment = program.command('attachment').description('Attachment upload and view helpers');
+    attachment.command('upload')
+        .description('Upload a local file as a platform attachment')
+        .requiredOption('--file <path>', 'Local file path visible to the agent runtime')
+        .option('--channel <target>', 'Optional channel target override such as #general or a raw channel id')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const filePath = requireString(opts.file, '--file');
+        const channel = typeof opts.channel === 'string' ? opts.channel.trim() : '';
+        if (!channel && !runtime.context.conversationId) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.MISSING_ATTACHMENT_SCOPE, 'attachment upload requires BIGBANG_CONVERSATION_ID or --channel.', { suggestedNextAction: 'Run from a managed conversation runtime or pass --channel for a channel-scoped upload.' });
+        }
+        let size = 0;
+        try {
+            size = statSync(filePath).size;
+        }
+        catch (error) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.FILE_UNREADABLE, `Attachment file is not readable: ${filePath}`, { cause: error, suggestedNextAction: 'Check the file path from the agent workspace and retry.' });
+        }
+        if (size > ATTACHMENT_UPLOAD_MAX_BYTES) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.FILE_TOO_LARGE, `Attachment file exceeds ${formatSize(ATTACHMENT_UPLOAD_MAX_BYTES)}: ${formatSize(size)}.`, { suggestedNextAction: 'Upload a smaller file or write a summary/artifact path instead.' });
+        }
+        let fileBuffer;
+        try {
+            fileBuffer = readFileSync(filePath);
+        }
+        catch (error) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.FILE_UNREADABLE, `Attachment file is not readable: ${filePath}`, { cause: error, suggestedNextAction: 'Check the file path from the agent workspace and retry.' });
+        }
+        const mimeType = inferMimeType(filePath);
+        const form = new FormData();
+        if (channel) {
+            form.append('channelId', channel);
+        }
+        else if (runtime.context.conversationId) {
+            form.append('conversationId', runtime.context.conversationId);
+        }
+        form.append('file', new Blob([new Uint8Array(fileBuffer)], { type: mimeType }), basename(filePath));
+        const response = await fetchJsonRaw(runtime, `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/assets/upload`, {
+            method: 'POST',
+            body: form,
+        });
+        if (!response.ok)
+            throw responseError(response, 'attachment upload failed');
+        writeOutput(runtime, withHint(summarizeAttachmentUpload(response.data), MUTATION_HINTS.attachmentUpload), response.data);
+    });
+    attachment.command('view')
+        .description('Download and preview a platform attachment')
+        .requiredOption('--attachment-id <id>', 'Attachment id returned by upload or shown in a message')
+        .option('--channel <target>', 'Optional channel target override for channel-scoped attachments')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const attachmentId = requireString(opts.attachmentId, '--attachment-id');
+        const channel = typeof opts.channel === 'string' ? opts.channel.trim() : '';
+        if (!channel && !runtime.context.conversationId) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.MISSING_ATTACHMENT_SCOPE, 'attachment view requires BIGBANG_CONVERSATION_ID or --channel for access checks.', { suggestedNextAction: 'Run from a managed conversation runtime that can access the attachment, or pass --channel for a channel-scoped attachment.' });
+        }
+        const query = new URLSearchParams({
+            agentId: runtime.context.agentId,
+        });
+        if (channel)
+            query.set('channelId', channel);
+        else if (runtime.context.conversationId)
+            query.set('conversationId', runtime.context.conversationId);
+        const metadataResponse = await fetchJsonRaw(runtime, `/api/assets/${encodeURIComponent(attachmentId)}/meta?${query.toString()}`);
+        if (!metadataResponse.ok)
+            throw responseError(metadataResponse, 'attachment metadata fetch failed');
+        const binaryResponse = await fetchBinaryRaw(runtime, `/api/assets/${encodeURIComponent(attachmentId)}?${query.toString()}`);
+        if (!binaryResponse.ok) {
+            throw new AgentCommandError(binaryResponse.status >= 500 ? AGENT_COMMAND_ERROR_CODES.SERVER_5XX : AGENT_COMMAND_ERROR_CODES.REQUEST_FAILED, `attachment download failed: ${binaryResponse.error}`, { status: binaryResponse.status });
+        }
+        const metadata = metadataResponse.data && typeof metadataResponse.data === 'object'
+            ? metadataResponse.data
+            : {};
+        const summary = summarizeAttachmentView({
+            attachmentId,
+            metadata,
+            buffer: binaryResponse.buffer,
+            contentType: binaryResponse.contentType,
+        });
+        writeOutput(runtime, summary.text, summary.data);
+    });
+    attachment.command('comments')
+        .description('List comments on a platform attachment')
+        .requiredOption('--attachment-id <id>', 'Attachment id returned by upload or shown in a message')
+        .option('--limit <n>', 'Max comments to return')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const attachmentId = requireString(opts.attachmentId, '--attachment-id');
+        const params = new URLSearchParams();
+        const limit = parsePositiveInteger('limit', opts.limit);
+        if (limit !== undefined)
+            params.set('limit', String(limit));
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/attachments/${encodeURIComponent(attachmentId)}/comments${qs ? `?${qs}` : ''}`);
+        if (!response.ok)
+            throw responseError(response, 'list attachment comments failed');
+        writeOutput(runtime, summarizeAttachmentComments(attachmentId, response.data), response.data);
+    });
+}

package/dist/commands/taskCommands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { BuildBigbangProgramOptions } from '../cliSupport.js';
+export declare function registerTaskCommands(program: Command, options: BuildBigbangProgramOptions): void;