@bbigbang/cli 0.1.0

package/dist/cliSupport.js

@@ -0,0 +1,1306 @@
+import { readFileSync } from 'node:fs';
+import { dirname, extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AGENT_COMMAND_ERROR_CODES, AgentApiClient, AgentCommandError, formatBigbangReceipt, formatMessageHeld, formatPanelVersionConflict, formatTaskHeld, loadAgentCommandContext, readOptionalStdin, readRequiredJsonStdin, readRequiredStdin, resolveCurrentRunContext, toAgentCommandError, } from '@bbigbang/agent-command';
+export const MANUAL_TOPICS = ['index', 'cli-overview', 'examples', 'commands'];
+export const MANUAL_TOPICS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'manual', 'topics');
+export const MANUAL_GENERATED_DIR = join(dirname(fileURLToPath(import.meta.url)), 'manual', 'generated');
+export function manualTopicPath(topic) {
+    return join(MANUAL_TOPICS_DIR, `${topic}.md`);
+}
+export function commandCatalogPath() {
+    return join(MANUAL_GENERATED_DIR, 'command-catalog.json');
+}
+export function readManualTopic(runtime, topic) {
+    return runtime.readFile(manualTopicPath(topic));
+}
+export function readCommandCatalog(runtime) {
+    const raw = runtime.readFile(commandCatalogPath());
+    return JSON.parse(raw);
+}
+export function isManualTopic(topic) {
+    return MANUAL_TOPICS.includes(topic);
+}
+export const ATTACHMENT_UPLOAD_MAX_BYTES = 5 * 1024 * 1024;
+export const ATTACHMENT_TEXT_PREVIEW_MAX_CHARS = 4000;
+export const MUTATION_HINTS = {
+    messageSend: 'Next: run `bigbang message check` for replies.',
+    taskCreate: 'Next: run `bigbang task list` to review created tasks.',
+    taskClaim: 'Next: run `bigbang task update --status in_progress` to start work.',
+    panelInspect: 'Next: run `bigbang panel read-rows --panel-id <id>` to inspect.',
+    toolPublish: 'Next: run `bigbang tool status --tool-id <id>` to verify.',
+    attachmentUpload: 'Next: run `bigbang message send --attachment-id <id>` to share it.',
+    actionPrepare: 'Next: wait for a human admin to confirm or cancel the action card.',
+};
+export function withHint(text, hint) {
+    return `${text}\n${hint}`;
+}
+export const MIME_BY_EXTENSION = {
+    '.txt': 'text/plain',
+    '.md': 'text/markdown',
+    '.markdown': 'text/markdown',
+    '.log': 'text/plain',
+    '.json': 'application/json',
+    '.jsonl': 'application/x-ndjson',
+    '.yaml': 'application/yaml',
+    '.yml': 'application/yaml',
+    '.toml': 'application/toml',
+    '.csv': 'text/csv',
+    '.ts': 'text/typescript',
+    '.tsx': 'text/typescript',
+    '.js': 'text/javascript',
+    '.jsx': 'text/javascript',
+    '.mjs': 'text/javascript',
+    '.py': 'text/x-python',
+    '.sh': 'text/x-shellscript',
+    '.sql': 'text/plain',
+    '.tex': 'application/x-tex',
+    '.html': 'text/html',
+    '.css': 'text/css',
+    '.xml': 'application/xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.pdf': 'application/pdf',
+};
+export function defaultIo() {
+    return {
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+    };
+}
+export function parseOutputFormat(raw) {
+    return raw === 'json' ? 'json' : 'text';
+}
+export function writeOutput(runtime, text, data) {
+    if (runtime.outputFormat === 'json') {
+        runtime.io.stdout.write(`${JSON.stringify(data)}\n`);
+        return;
+    }
+    runtime.io.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
+}
+export function writeJson(runtime, data) {
+    runtime.io.stdout.write(`${JSON.stringify(data)}\n`);
+}
+export function writeReceipt(runtime, receipt) {
+    runtime.io.stderr.write(`${formatBigbangReceipt(receipt)}\n`);
+}
+export function createRuntime(program, options) {
+    const context = loadAgentCommandContext({ env: options.env, readFile: options.readFile });
+    const runContext = resolveCurrentRunContext(context, options.readFile);
+    const clientContext = {
+        ...context,
+        runId: runContext.runId,
+        turnId: runContext.turnId,
+        traceId: runContext.traceId,
+    };
+    return {
+        context,
+        runId: runContext.runId,
+        turnId: runContext.turnId,
+        traceId: runContext.traceId,
+        client: new AgentApiClient(clientContext, { fetch: options.fetch, env: options.env, sleep: options.sleep }),
+        fetch: options.fetch ?? fetch,
+        env: options.env ?? process.env,
+        sleep: options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+        readFile: options.readFile ?? ((path) => readFileSync(path, 'utf8')),
+        io: options.io ?? defaultIo(),
+        outputFormat: parseOutputFormat(program.opts().format),
+    };
+}
+export function repeatOption(value, previous = []) {
+    return [...previous, value];
+}
+export function parsePositiveInteger(name, raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, `--${name} must be a positive integer.`);
+    }
+    return value;
+}
+export function parseRequiredPositiveInteger(name, raw) {
+    const value = parsePositiveInteger(name, raw);
+    if (value === undefined) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, `--${name} is required.`);
+    }
+    return value;
+}
+export function parsePositiveIntegerList(name, raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    return raw.map((item) => parseRequiredPositiveInteger(name, item));
+}
+export function parseNumber(name, raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, `--${name} must be a number.`);
+    }
+    return value;
+}
+export function parseRequiredNumber(name, raw) {
+    const value = parseNumber(name, raw);
+    if (value === undefined) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, `--${name} is required.`);
+    }
+    return value;
+}
+export function parseNonNegativeInteger(name, raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, `--${name} must be a non-negative integer.`);
+    }
+    return value;
+}
+export function requireString(value, flag) {
+    const stringValue = typeof value === 'string' ? value.trim() : '';
+    if (!stringValue)
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, `${flag} is required.`);
+    return stringValue;
+}
+export function requireConversationId(runtime, commandName) {
+    const conversationId = runtime.context.conversationId?.trim();
+    if (!conversationId) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.MISSING_CONVERSATION_ID, `${commandName} requires BIGBANG_CONVERSATION_ID for the current DM reminder scope.`, { suggestedNextAction: 'Run this command from an Bigbang managed direct-message runtime.' });
+    }
+    return conversationId;
+}
+export function responseError(response, fallback) {
+    return new AgentCommandError(response.errorCode ?? (response.status >= 500 ? AGENT_COMMAND_ERROR_CODES.SERVER_5XX : AGENT_COMMAND_ERROR_CODES.REQUEST_FAILED), response.error ?? fallback, {
+        status: response.status,
+        suggestedNextAction: response.suggestedNextAction,
+    });
+}
+export function buildCoreUrl(runtime, path) {
+    const normalizedBase = runtime.context.serverUrl.replace(/\/+$/, '');
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    return `${normalizedBase}${normalizedPath}`;
+}
+export async function fetchJsonRaw(runtime, path, init = {}, options = {}) {
+    const retryBudget = resolveRawRetryBudget(runtime.env, init.method ?? 'GET', options.retry);
+    for (let attempt = 0; attempt <= retryBudget; attempt += 1) {
+        try {
+            const response = await fetchJsonRawOnce(runtime, path, init);
+            if (!shouldRetryJsonRawResponse(response) || attempt >= retryBudget) {
+                return response;
+            }
+        }
+        catch (error) {
+            if (!isNetworkAgentCommandError(error) || attempt >= retryBudget)
+                throw error;
+        }
+        await runtime.sleep(rawRetryDelayMs(attempt));
+    }
+    return fetchJsonRawOnce(runtime, path, init);
+}
+async function fetchJsonRawOnce(runtime, path, init = {}) {
+    let response;
+    try {
+        response = await runtime.fetch(buildCoreUrl(runtime, path), {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${runtime.context.token}`,
+                'X-Bigbang-Agent-Surface': 'bigbang',
+                ...(init.headers ?? {}),
+            },
+        });
+    }
+    catch (error) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.NETWORK_ERROR, `Request to Bigbang core failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error, suggestedNextAction: 'Check that the core server is reachable from this agent runtime.' });
+    }
+    const contentType = response.headers.get('content-type') ?? '';
+    if (!contentType.includes('application/json')) {
+        const text = await response.text();
+        return {
+            ok: false,
+            status: response.status,
+            data: null,
+            error: `Expected JSON response from core but received ${contentType || 'unknown content type'}: ${text.slice(0, 200)}`,
+            errorCode: AGENT_COMMAND_ERROR_CODES.NON_JSON_RESPONSE,
+        };
+    }
+    const data = await response.json();
+    if (response.ok)
+        return { ok: true, status: response.status, data };
+    const record = data && typeof data === 'object' ? data : {};
+    return {
+        ok: false,
+        status: response.status,
+        data,
+        error: typeof record.error === 'string' ? record.error : `Request failed with HTTP ${response.status}`,
+        errorCode: typeof record.error_code === 'string' ? record.error_code : undefined,
+        suggestedNextAction: typeof record.suggested_next_action === 'string' ? record.suggested_next_action : undefined,
+    };
+}
+export async function fetchBinaryRaw(runtime, path, options = {}) {
+    const retryBudget = resolveRawRetryBudget(runtime.env, 'GET', options.retry);
+    for (let attempt = 0; attempt <= retryBudget; attempt += 1) {
+        try {
+            const response = await fetchBinaryRawOnce(runtime, path);
+            if (response.ok || !shouldRetryRawStatus(response.status) || attempt >= retryBudget) {
+                return response;
+            }
+        }
+        catch (error) {
+            if (!isNetworkAgentCommandError(error) || attempt >= retryBudget)
+                throw error;
+        }
+        await runtime.sleep(rawRetryDelayMs(attempt));
+    }
+    return fetchBinaryRawOnce(runtime, path);
+}
+async function fetchBinaryRawOnce(runtime, path) {
+    let response;
+    try {
+        response = await runtime.fetch(buildCoreUrl(runtime, path), {
+            headers: {
+                Authorization: `Bearer ${runtime.context.token}`,
+                'X-Bigbang-Agent-Surface': 'bigbang',
+            },
+        });
+    }
+    catch (error) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.NETWORK_ERROR, `Request to Bigbang core failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error, suggestedNextAction: 'Check that the core server is reachable from this agent runtime.' });
+    }
+    const contentType = response.headers.get('content-type') ?? '';
+    if (!response.ok) {
+        const text = await response.text();
+        return { ok: false, status: response.status, error: text.slice(0, 300) || `HTTP ${response.status}` };
+    }
+    return {
+        ok: true,
+        status: response.status,
+        buffer: Buffer.from(await response.arrayBuffer()),
+        contentType,
+    };
+}
+function resolveRawRetryBudget(env, method, retryMode = 'auto') {
+    if (retryMode === 'never')
+        return 0;
+    if (retryMode === 'auto' && method.toUpperCase() !== 'GET')
+        return 0;
+    const raw = env.BIGBANG_CLI_MAX_RETRIES?.trim();
+    if (raw !== undefined && raw !== '') {
+        const parsed = Number(raw);
+        if (Number.isInteger(parsed) && parsed >= 0)
+            return Math.min(parsed, 5);
+    }
+    return 2;
+}
+function rawRetryDelayMs(attempt) {
+    return attempt === 0 ? 200 : 800;
+}
+function shouldRetryRawStatus(status) {
+    return status === 502 || status === 503 || status === 504;
+}
+function shouldRetryJsonRawResponse(response) {
+    if (response.errorCode === AGENT_COMMAND_ERROR_CODES.NON_JSON_RESPONSE)
+        return false;
+    return shouldRetryRawStatus(response.status);
+}
+function isNetworkAgentCommandError(error) {
+    return error instanceof AgentCommandError && error.code === AGENT_COMMAND_ERROR_CODES.NETWORK_ERROR;
+}
+export function isHeldResponse(data) {
+    return Boolean(data && typeof data === 'object' && (data.held === true ||
+        data.state === 'held'));
+}
+export function isSuppressedResponse(data) {
+    return Boolean(data && typeof data === 'object' && data.suppressed === true);
+}
+export function isVersionConflict(response) {
+    return response.errorCode === 'version_conflict';
+}
+export function isMessageNotResolved(response) {
+    return response.status === 404 && typeof response.error === 'string' && response.error.includes('Cannot resolve message');
+}
+export function appendCommonBody(runtime, body) {
+    return {
+        ...body,
+        ...(runtime.context.conversationId ? { conversationId: runtime.context.conversationId } : {}),
+        ...(runtime.runId ? { runId: runtime.runId } : {}),
+        ...(runtime.turnId ? { turnId: runtime.turnId } : {}),
+        ...(runtime.traceId ? { traceId: runtime.traceId } : {}),
+    };
+}
+export function appendRunContextParams(runtime, params) {
+    if (runtime.runId)
+        params.set('run_id', runtime.runId);
+    if (runtime.turnId)
+        params.set('turn_id', runtime.turnId);
+    if (runtime.traceId)
+        params.set('trace_id', runtime.traceId);
+    if (runtime.context.conversationId)
+        params.set('conversation_id', runtime.context.conversationId);
+    return params;
+}
+export async function parseJsonStdinOrThrow(runtime, label) {
+    return readRequiredJsonStdin(runtime.io.stdin, label);
+}
+export function parseJsonStringOrThrow(content, label) {
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_JSON_STDIN, `${label} did not contain valid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error, suggestedNextAction: 'Validate the payload with jq or node before retrying.' });
+    }
+}
+export function parseJsonObjectStringOrThrow(content, label) {
+    const parsed = parseJsonStringOrThrow(content, label);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_JSON_STDIN, `${label} must be a JSON object.`, { suggestedNextAction: 'Pipe an object payload such as {"title":"..."} instead of an array or scalar.' });
+    }
+    return parsed;
+}
+export function normalizeExpectedVersion(payload) {
+    const normalized = { ...payload };
+    if (normalized.expectedVersion === undefined && Number.isInteger(normalized.expected_version)) {
+        normalized.expectedVersion = normalized.expected_version;
+    }
+    delete normalized.expected_version;
+    return normalized;
+}
+export function normalizePanelPayload(payload, commandName) {
+    if (payload.view !== undefined && payload.component === undefined) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_PANEL_PAYLOAD, `${commandName} expects curated panel JSON with component, props, dataset, and optional actions; view is a Workspace Tool manifest field.`, { suggestedNextAction: 'Use component:"RowTemplateGrid" with props/dataset/actions, or publish a Workspace Tool for tool manifest view JSON.' });
+    }
+    return normalizeExpectedVersion(payload);
+}
+export function summarizePanelState(data) {
+    const record = data && typeof data === 'object' ? data : {};
+    const state = ('perUser' in record || 'shared' in record)
+        ? record
+        : record.state && typeof record.state === 'object'
+            ? record.state
+            : {};
+    const perUser = state.perUser && typeof state.perUser === 'object'
+        ? state.perUser
+        : state;
+    const shared = state.shared && typeof state.shared === 'object'
+        ? state.shared
+        : state;
+    const filters = perUser.filters && typeof perUser.filters === 'object'
+        ? perUser.filters
+        : {};
+    const sort = perUser.sort && typeof perUser.sort === 'object'
+        ? perUser.sort
+        : {};
+    const selection = Array.isArray(shared.selection)
+        ? shared.selection
+        : Array.isArray(perUser.selection)
+            ? perUser.selection
+            : [];
+    const version = typeof state.version === 'number' ? ` version=${state.version}` : '';
+    const filterText = Object.keys(filters).length > 0 ? JSON.stringify(filters) : '(none)';
+    const sortText = Object.keys(sort).length > 0 ? JSON.stringify(sort) : '(none)';
+    const selectionText = selection.length > 0 ? selection.map(String).join(',') : '(none)';
+    return [
+        `Panel state.${version}`,
+        `filters=${filterText}`,
+        `sort=${sortText}`,
+        `selection=${selectionText}`,
+    ].join('\n');
+}
+export function summarizePanelCollaborators(data) {
+    const record = data && typeof data === 'object' ? data : {};
+    const panelId = String(record.panelId ?? record.panel_id ?? '');
+    const collaborators = Array.isArray(record.collaborators) ? record.collaborators : [];
+    const lines = [`Panel collaborators. panel_id=${panelId || '(unknown)'} count=${collaborators.length}`];
+    for (const raw of collaborators) {
+        const item = raw && typeof raw === 'object' ? raw : {};
+        const agentId = String(item.agentId ?? item.agent_id ?? '(unknown)');
+        const name = typeof item.name === 'string' && item.name.trim() ? item.name.trim() : agentId;
+        const role = String(item.role ?? 'collaborator');
+        lines.push(`- ${name} (${agentId}) role=${role}`);
+    }
+    return lines.join('\n');
+}
+export function summarizeSkillList(data) {
+    const record = data && typeof data === 'object' ? data : {};
+    const path = typeof record.path === 'string' ? record.path : '';
+    const roots = Array.isArray(record.roots) ? record.roots.map(String) : [];
+    const skills = Array.isArray(record.skills) ? record.skills : [];
+    const entries = Array.isArray(record.entries) ? record.entries : [];
+    const lines = [
+        path
+            ? `Skill directory. path=${path} entries=${entries.length}`
+            : `Skills. roots=${roots.length} skills=${skills.length}`,
+    ];
+    for (const raw of skills.slice(0, 20)) {
+        const item = raw && typeof raw === 'object' ? raw : {};
+        const name = String(item.name ?? '(unnamed)');
+        const skillPath = String(item.path ?? '');
+        const description = typeof item.description === 'string' && item.description.trim()
+            ? ` — ${item.description.trim()}`
+            : '';
+        lines.push(`- ${name}: ${skillPath}${description}`);
+    }
+    for (const raw of entries.slice(0, 40)) {
+        const item = raw && typeof raw === 'object' ? raw : {};
+        lines.push(`- ${String(item.kind ?? 'entry')} ${String(item.name ?? '(unnamed)')}: ${String(item.path ?? '')}`);
+    }
+    if (skills.length > 20)
+        lines.push(`... ${skills.length - 20} more skill(s)`);
+    if (entries.length > 40)
+        lines.push(`... ${entries.length - 40} more entries`);
+    return lines.join('\n');
+}
+export function summarizeSkillFile(data) {
+    const record = data && typeof data === 'object' ? data : {};
+    const skillPath = String(record.path ?? '');
+    const mimeType = String(record.mimeType ?? 'text/plain');
+    const size = typeof record.size === 'number' ? formatSize(record.size) : 'unknown';
+    const content = typeof record.content === 'string' ? record.content : '';
+    return [
+        `Skill file. path=${skillPath} mime=${mimeType} size=${size}`,
+        '',
+        '```markdown',
+        content,
+        '```',
+    ].join('\n');
+}
+export function normalizeAgentTaskStatus(raw) {
+    const status = requireString(raw, '--status');
+    if (status !== 'todo' && status !== 'in_progress' && status !== 'in_review') {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_TASK_STATUS, '--status must be one of todo, in_progress, or in_review. Agents cannot mark tasks done.', { suggestedNextAction: 'Move completed work to in_review and let a human decide done or send it back.' });
+    }
+    return status;
+}
+export function normalizeTaskListStatus(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return 'all';
+    const status = String(raw).trim();
+    if (status === 'all' || status === 'todo' || status === 'in_progress' || status === 'in_review' || status === 'done') {
+        return status;
+    }
+    throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_TASK_STATUS, '--status must be one of: all, todo, in_progress, in_review, done.');
+}
+export function normalizeTaskScope(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return 'all';
+    const scope = String(raw).trim();
+    if (scope === 'all' || scope === 'dm' || scope === 'channel')
+        return scope;
+    throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, '--scope must be one of: all, dm, channel.');
+}
+export function summarizeTaskIdentity(task) {
+    if (!task)
+        return 'task';
+    const ref = typeof task.agentTaskRef === 'string' && task.agentTaskRef.trim() ? task.agentTaskRef.trim() : '';
+    const number = typeof task.taskNumber === 'number' ? `#t${task.taskNumber}` : '';
+    if (ref && number)
+        return `${ref} · ${number}`;
+    return ref || number || 'task';
+}
+export function summarizeTaskSource(task) {
+    const source = typeof task.sourceLabel === 'string' && task.sourceLabel.trim()
+        ? task.sourceLabel.trim()
+        : typeof task.sourceTarget === 'string' && task.sourceTarget.trim()
+            ? task.sourceTarget.trim()
+            : typeof task.channelId === 'string' && task.channelId.trim()
+                ? task.channelId.trim()
+                : '';
+    return source ? ` source=${source}` : '';
+}
+export function summarizeTaskList(data, emptyText) {
+    const tasks = data && typeof data === 'object' && Array.isArray(data.tasks)
+        ? data.tasks
+        : [];
+    if (tasks.length === 0)
+        return emptyText;
+    const lines = tasks.slice(0, 12).map((task) => {
+        const title = typeof task.title === 'string' ? task.title : 'Untitled task';
+        const status = typeof task.status === 'string' ? task.status : 'unknown';
+        const assignee = typeof task.claimedByName === 'string' && task.claimedByName.trim()
+            ? ` assigned=${task.claimedByName.trim()}`
+            : '';
+        const message = typeof task.messageId === 'string' && task.messageId.trim()
+            ? ` msg=${task.messageId.trim().slice(0, 8)}`
+            : '';
+        const thread = typeof task.threadTarget === 'string' && task.threadTarget.trim()
+            ? ` thread=${task.threadTarget.trim()}`
+            : '';
+        return `${summarizeTaskIdentity(task)} ${status}${assignee}${summarizeTaskSource(task)}${message}${thread}: ${title}`;
+    });
+    const suffix = tasks.length > lines.length ? `\n... ${tasks.length - lines.length} more task(s)` : '';
+    return `Found ${tasks.length} task(s):\n${lines.join('\n')}${suffix}`;
+}
+export function summarizeTaskLookup(data) {
+    if (!data || typeof data !== 'object')
+        return 'Task lookup returned no data.';
+    const record = data;
+    if (record.deletedTask)
+        return `Deleted task ${summarizeTaskIdentity(record.deletedTask)}.`;
+    if (!record.task)
+        return 'Task not found.';
+    const title = typeof record.task.title === 'string' ? record.task.title : 'Untitled task';
+    const status = typeof record.task.status === 'string' ? record.task.status : 'unknown';
+    const assignee = typeof record.task.claimedByName === 'string' && record.task.claimedByName.trim()
+        ? ` assigned=${record.task.claimedByName.trim()}`
+        : ' assigned=unclaimed';
+    const thread = typeof record.task.threadTarget === 'string' && record.task.threadTarget.trim()
+        ? `\nThread: ${record.task.threadTarget.trim()}`
+        : '';
+    return `${summarizeTaskIdentity(record.task)} ${status}${assignee}${summarizeTaskSource(record.task)}: ${title}${thread}`;
+}
+export function formatTaskHistoryEvent(event) {
+    const parts = [
+        typeof event.createdAt === 'string' && event.createdAt.trim() ? event.createdAt.trim() : 'unknown-time',
+        typeof event.type === 'string' && event.type.trim() ? event.type.trim() : 'event',
+    ];
+    if (typeof event.actorName === 'string' && event.actorName.trim()) {
+        const actor = event.actorType === 'system' ? event.actorName.trim() : `@${event.actorName.trim()}`;
+        parts.push(actor);
+    }
+    if (typeof event.fromStatus === 'string' || typeof event.toStatus === 'string') {
+        parts.push(`status ${String(event.fromStatus ?? 'unknown')} -> ${String(event.toStatus ?? 'unknown')}`);
+    }
+    if (typeof event.claimedByNameAfter === 'string' && event.claimedByNameAfter.trim()) {
+        parts.push(`assignee @${event.claimedByNameAfter.trim()}`);
+    }
+    if (typeof event.threadTarget === 'string' && event.threadTarget.trim()) {
+        parts.push(`thread ${event.threadTarget.trim()}`);
+    }
+    return `- ${parts.join(' · ')}`;
+}
+export function summarizeTaskHistory(data) {
+    if (!data || typeof data !== 'object')
+        return 'Task history returned no data.';
+    const record = data;
+    const identity = summarizeTaskIdentity(record.task ?? record.deletedTask);
+    const task = record.task ?? record.deletedTask;
+    const title = task && typeof task.title === 'string' ? task.title : 'Untitled task';
+    const status = task && typeof task.status === 'string' ? task.status : record.deletedTask ? 'deleted' : 'unknown';
+    const events = Array.isArray(record.events) ? record.events : [];
+    const lines = events.slice(0, 12).map(formatTaskHistoryEvent);
+    const suffix = events.length > lines.length ? `\n... ${events.length - lines.length} more event(s)` : '';
+    const timeline = lines.length ? lines.join('\n') : '- No structured task events recorded yet.';
+    return `${record.deletedTask ? 'Deleted task' : 'Task'} ${identity} [${status}] ${title}${task ? summarizeTaskSource(task) : ''}\nOrder: newest first\n\n${timeline}${suffix}`;
+}
+export function summarizeClaimResults(data) {
+    const results = data && typeof data === 'object' && Array.isArray(data.results)
+        ? data.results
+        : [];
+    const succeeded = results.filter((result) => result.success === true).length;
+    const failed = results.length - succeeded;
+    const lines = results.slice(0, 12).map((result) => {
+        const identity = typeof result.taskNumber === 'number' ? `#${result.taskNumber}` : String(result.messageId ?? 'task');
+        if (result.success === true) {
+            const handoff = result.handoffStarted && typeof result.threadTarget === 'string'
+                ? ` handoff=${result.threadTarget}`
+                : '';
+            return `${identity}: claimed${handoff}`;
+        }
+        return `${identity}: failed${result.reason ? ` - ${String(result.reason)}` : ''}`;
+    });
+    const suffix = results.length > lines.length ? `\n... ${results.length - lines.length} more result(s)` : '';
+    return `Claim results: ${succeeded} claimed, ${failed} failed.${lines.length ? `\n${lines.join('\n')}${suffix}` : ''}`;
+}
+export function normalizeReminderScheduleKind(raw) {
+    const value = requireString(raw, '--schedule-kind');
+    if (value === 'one_time' || value === 'recurring')
+        return value;
+    throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, '--schedule-kind must be one_time or recurring.');
+}
+export function normalizeOptionalReminderScheduleKind(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return undefined;
+    return normalizeReminderScheduleKind(raw);
+}
+export function normalizeReminderIntervalUnit(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return undefined;
+    const value = String(raw).trim();
+    if (value === 'hour' || value === 'day' || value === 'week')
+        return value;
+    throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, '--interval-unit must be hour, day, or week.');
+}
+export function parseSnoozeDuration(raw) {
+    const value = requireString(raw, '--by');
+    const match = value.match(/^([1-9]\d*)([mhd])$/);
+    if (!match) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_INPUT, `Unsupported duration format: "${value}". Use a positive integer followed by m, h, or d (e.g. 30m, 2h, 1d).`, { suggestedNextAction: 'Pass --by with a positive duration such as 30m, 2h, or 1d.' });
+    }
+    const amount = Number.parseInt(match[1], 10);
+    const unit = match[2];
+    const multiplier = unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000;
+    const durationMs = amount * multiplier;
+    return { until: Date.now() + durationMs, durationMs };
+}
+export function summarizeTimestamp(raw) {
+    return typeof raw === 'number' && Number.isFinite(raw) ? new Date(raw).toISOString() : 'none';
+}
+export function summarizeReminder(reminder) {
+    const reminderId = String(reminder.reminderId ?? '');
+    const title = String(reminder.title ?? 'untitled');
+    const status = String(reminder.status ?? 'unknown');
+    const scheduleKind = String(reminder.scheduleKind ?? 'one_time');
+    const nextRun = summarizeTimestamp(reminder.nextRunAt);
+    const interval = reminder.intervalUnit && reminder.intervalValue
+        ? ` every=${String(reminder.intervalValue)} ${String(reminder.intervalUnit)}`
+        : '';
+    return `reminder_id=${reminderId} [${status}] ${scheduleKind}${interval} next=${nextRun} title="${title}"`;
+}
+export function summarizeReminderList(data) {
+    const reminders = data && typeof data === 'object' && Array.isArray(data.reminders)
+        ? data.reminders
+        : [];
+    if (reminders.length === 0)
+        return 'No reminders in the current DM scope.';
+    const lines = reminders.slice(0, 20).map((reminder) => {
+        const recentOccurrences = Array.isArray(reminder.recentOccurrences)
+            ? reminder.recentOccurrences
+            : [];
+        const openOccurrence = recentOccurrences.find((occurrence) => {
+            const status = String(occurrence.status ?? '');
+            return status === 'pending' || status === 'dispatched' || status === 'failed' || status === 'snoozed' || status === 'awaiting_review';
+        });
+        const open = openOccurrence
+            ? ` open_occurrence_id=${String(openOccurrence.occurrenceId ?? '')} open_status=${String(openOccurrence.status ?? 'unknown')}`
+            : '';
+        return `- ${summarizeReminder(reminder)}${open}`;
+    });
+    const suffix = reminders.length > lines.length ? `\n... ${reminders.length - lines.length} more reminder(s)` : '';
+    return `Current reminders:\n${lines.join('\n')}${suffix}`;
+}
+export function summarizeOccurrence(label, occurrence) {
+    if (!occurrence)
+        return `${label}: none`;
+    const task = typeof occurrence.taskNumber === 'number' ? ` task=#t${occurrence.taskNumber}` : '';
+    return `${label}: occurrence_id=${String(occurrence.occurrenceId ?? '')} ${String(occurrence.status ?? 'unknown')} scheduled=${summarizeTimestamp(occurrence.scheduledFor)}${task}`;
+}
+export function summarizeReminderOccurrences(data) {
+    if (!data || typeof data !== 'object')
+        return 'Reminder occurrence lookup returned no data.';
+    const payload = data;
+    const reminderId = String(payload.reminder?.reminderId ?? '');
+    const title = String(payload.reminder?.title ?? (reminderId || 'reminder'));
+    const occurrences = payload.occurrences ?? [];
+    if (occurrences.length === 0)
+        return `Reminder "${title}" has no occurrences yet.`;
+    const lines = occurrences.slice(0, 20).map((occurrence) => `- ${summarizeOccurrence('occurrence', occurrence).replace(/^occurrence: /, '')}`);
+    const suffix = occurrences.length > lines.length ? `\n... ${occurrences.length - lines.length} more occurrence(s)` : '';
+    return `Occurrences for "${title}" reminder_id=${reminderId}:\n${lines.join('\n')}${suffix}`;
+}
+export function summarizeReminderCurrent(data) {
+    if (!data || typeof data !== 'object')
+        return 'Reminder current occurrence lookup returned no data.';
+    const payload = data;
+    const reminderId = String(payload.reminder?.reminderId ?? '');
+    const title = String(payload.reminder?.title ?? (reminderId || 'reminder'));
+    return [
+        `Reminder "${title}" reminder_id=${reminderId}`,
+        summarizeOccurrence('Current', payload.currentOccurrence),
+        summarizeOccurrence('Latest', payload.latestOccurrence),
+    ].join('\n');
+}
+export function summarizeReminderAction(action, data, fallbackId) {
+    if (!data || typeof data !== 'object')
+        return `${action} reminder ${fallbackId ?? ''}`.trim();
+    const payload = data;
+    const reminder = payload.reminder ?? (payload.reminderId || payload.title ? payload : undefined);
+    const reminderId = String(reminder?.reminderId ?? fallbackId ?? '');
+    const title = reminder?.title ? ` "${String(reminder.title)}"` : '';
+    const occurrence = payload.occurrence
+        ? ` occurrence_id=${String(payload.occurrence.occurrenceId ?? '')} occurrence_status=${String(payload.occurrence.status ?? 'unknown')}`
+        : '';
+    const task = payload.task && typeof payload.task.taskNumber === 'number'
+        ? ` task=#t${payload.task.taskNumber} task_status=${String(payload.task.status ?? 'unknown')}`
+        : '';
+    return `${action} reminder${title} reminder_id=${reminderId}${occurrence}${task}`.trim();
+}
+export function summarizeActionPrepare(data) {
+    if (!data || typeof data !== 'object')
+        return 'Action card prepared.';
+    const payload = data;
+    const cardId = String(payload.actionCardId ?? payload.action_card_id ?? payload.id ?? '');
+    const actionType = String(payload.actionType ?? payload.action_type ?? 'unknown');
+    const status = String(payload.status ?? 'pending');
+    const panelId = typeof payload.panelId === 'string'
+        ? payload.panelId
+        : typeof payload.panel_id === 'string'
+            ? payload.panel_id
+            : '';
+    const summary = typeof payload.summary === 'string' && payload.summary.trim()
+        ? ` ${payload.summary.trim()}`
+        : '';
+    const panel = panelId ? ` panel_id=${panelId}` : '';
+    return `Action card prepared.${summary} action_card_id=${cardId} action_type=${actionType} status=${status}${panel}`;
+}
+export function summarizeReminderLog(reminderId, data) {
+    const events = Array.isArray(data) ? data : [];
+    if (events.length === 0)
+        return `Reminder ${reminderId} has no events.`;
+    const lines = [`Reminder log for ${reminderId}: ${events.length} event(s)`];
+    for (const raw of events) {
+        const event = raw && typeof raw === 'object' ? raw : {};
+        const createdAt = typeof event.createdAt === 'number' && Number.isFinite(event.createdAt)
+            ? new Date(event.createdAt).toISOString()
+            : 'unknown';
+        const eventType = String(event.eventType ?? 'event');
+        const actorType = String(event.actorType ?? 'unknown');
+        const actorName = typeof event.actorName === 'string' && event.actorName.trim()
+            ? event.actorName.trim()
+            : String(event.actorId ?? 'unknown');
+        const actor = actorType === 'system' ? actorName : `@${actorName}`;
+        const occurrence = typeof event.occurrenceId === 'string' && event.occurrenceId.trim()
+            ? ` occurrence_id=${event.occurrenceId.trim()}`
+            : '';
+        const payload = event.payload && typeof event.payload === 'object' ? JSON.stringify(event.payload) : '';
+        const payloadText = payload ? ` payload=${payload}` : '';
+        lines.push(`- ${createdAt} ${eventType} ${actor}${occurrence}${payloadText}`);
+    }
+    return lines.join('\n');
+}
+export function summarizeReminderSnooze(data) {
+    if (!data || typeof data !== 'object')
+        return 'Reminder occurrence snoozed.';
+    const record = data;
+    const occurrence = record.occurrence && typeof record.occurrence === 'object'
+        ? record.occurrence
+        : {};
+    const occurrenceId = String(occurrence.occurrenceId ?? '');
+    const scheduledFor = typeof occurrence.scheduledFor === 'number' && Number.isFinite(occurrence.scheduledFor)
+        ? new Date(occurrence.scheduledFor).toISOString()
+        : '';
+    const parts = [`Snoozed reminder occurrence${occurrenceId ? ` ${occurrenceId}` : ''}.`];
+    if (scheduledFor)
+        parts.push(`Next run at ${scheduledFor}.`);
+    return parts.join('\n');
+}
+export function summarizeWorkspaceInspect(data) {
+    if (!data || typeof data !== 'object')
+        return 'Workspace inspect returned no data.';
+    const result = data;
+    if (typeof result.reportText === 'string' && result.reportText.trim()) {
+        return result.reportText.trim();
+    }
+    const inspect = result.inspect ?? {};
+    return [
+        '[Workspace inspect]',
+        `node: ${String(result.nodeId ?? 'none')}`,
+        `workspace_root: ${String(result.workspaceRoot ?? 'none')}`,
+        `git: ${inspect.isGit ? 'yes' : 'no'} | kind=${String(inspect.workspaceKind ?? 'unknown')} | branch=${String(inspect.branchName ?? 'none')}`,
+        inspect.repoRoot ? `repo_root: ${String(inspect.repoRoot)}` : null,
+        inspect.remoteUrl ? `remote: ${String(inspect.remoteUrl)}` : null,
+    ].filter(Boolean).join('\n');
+}
+export function summarizeWorkspaceTree(data) {
+    if (!data || typeof data !== 'object')
+        return 'Workspace tree returned no data.';
+    const result = data;
+    const prefix = typeof result.path === 'string' && result.path.trim() ? result.path.trim() : '.';
+    const entries = Array.isArray(result.entries) ? result.entries : [];
+    if (entries.length === 0)
+        return `[Workspace tree]\npath: ${prefix}\n(entries: empty)`;
+    const lines = entries.slice(0, 100).map((entry) => {
+        const size = typeof entry.size === 'number' && Number.isFinite(entry.size) ? ` size=${entry.size}` : '';
+        return `- ${String(entry.path ?? '')} [${String(entry.kind ?? 'unknown')}]${size}`;
+    });
+    const suffix = entries.length > lines.length ? `\n... ${entries.length - lines.length} more entry(s)` : '';
+    return `[Workspace tree]\npath: ${prefix}\n${lines.join('\n')}${suffix}`;
+}
+export function summarizeWorkspaceFile(data) {
+    if (!data || typeof data !== 'object')
+        return 'Workspace file returned no data.';
+    const result = data;
+    const mimeType = String(result.mimeType ?? 'text/plain');
+    const fence = mimeType === 'text/markdown' ? 'markdown' : 'text';
+    return [
+        '[Workspace file]',
+        `path: ${String(result.path ?? '')}`,
+        `mime: ${mimeType}`,
+        `size: ${String(result.size ?? 'unknown')}`,
+        typeof result.modifiedAt === 'number' && Number.isFinite(result.modifiedAt)
+            ? `modified_at: ${new Date(result.modifiedAt).toISOString()}`
+            : null,
+        '',
+        `\`\`\`${fence}`,
+        String(result.content ?? ''),
+        '```',
+    ].filter((line) => line !== null).join('\n');
+}
+export function summarizeToolState(state) {
+    if (!state || typeof state !== 'object')
+        return 'none';
+    const entries = Object.entries(state)
+        .filter(([, value]) => value !== undefined && value !== null && value !== '')
+        .slice(0, 6)
+        .map(([key, value]) => `${key}=${String(value)}`);
+    return entries.length > 0 ? entries.join(' · ') : 'empty';
+}
+export function summarizeToolRun(run) {
+    if (!run)
+        return 'last_run=none';
+    const node = run.executionHostname || run.executionNodeId
+        ? ` node=${String(run.executionHostname ?? run.executionNodeId)}`
+        : '';
+    return `last_run=${String(run.runId ?? '')} action=${String(run.actionId ?? '')} status=${String(run.status ?? 'unknown')}${node}`;
+}
+export function summarizeToolStatus(data) {
+    if (!data || typeof data !== 'object')
+        return 'Workspace tool status returned no data.';
+    const payload = data;
+    const tool = payload.tool ?? {};
+    const manifest = tool.manifest && typeof tool.manifest === 'object'
+        ? tool.manifest
+        : {};
+    const cli = manifest.cli && typeof manifest.cli === 'object'
+        ? manifest.cli
+        : {};
+    const runtime = manifest.runtime && typeof manifest.runtime === 'object'
+        ? manifest.runtime
+        : {};
+    const backend = cli.entry
+        ? `cli.entry=${String(cli.entry)}`
+        : 'legacy-command';
+    const runtimeMode = runtime.mode ? ` runtime=${String(runtime.mode)}` : '';
+    const lines = [
+        '[Workspace tool]',
+        `tool_id: ${String(tool.toolId ?? '')}`,
+        `name: ${String(tool.name ?? '')}`,
+        `slug: ${String(tool.slug ?? '')}`,
+        `revision: ${String(tool.revision ?? '')}`,
+        `agent: ${String(tool.agentName ?? tool.agentId ?? '')}`,
+        `node: ${String(tool.agentNodeId ?? 'unknown')}`,
+        `runtime_state: ${String(tool.runtimeState ?? 'unknown')} | running=${tool.isRunning === true ? 'yes' : 'no'} | active_terminal=${String(tool.activeTerminalId ?? 'none')}`,
+        `backend: ${backend}${runtimeMode}`,
+        `latest_state: ${summarizeToolState(tool.latestState)}`,
+        summarizeToolRun(tool.lastRun),
+    ];
+    if (Array.isArray(payload.runs)) {
+        const runLines = payload.runs.map((run) => `- ${summarizeToolRun(run)}`);
+        lines.push(runLines.length > 0 ? `recent_runs:\n${runLines.join('\n')}` : 'recent_runs: none');
+    }
+    return lines.join('\n');
+}
+export function summarizeToolPublish(data) {
+    if (!data || typeof data !== 'object')
+        return 'Tool publish completed.';
+    const payload = data;
+    return `Tool published. tool_id=${String(payload.toolId ?? '')} revision=${String(payload.revision ?? '')} url=${String(payload.toolUrl ?? '')}`;
+}
+export function summarizeToolVerification(data) {
+    if (!data || typeof data !== 'object')
+        return 'Workspace tool verification updated.';
+    const payload = data;
+    const verification = payload.verification && typeof payload.verification === 'object'
+        ? payload.verification
+        : payload;
+    return [
+        `Tool verification updated. tool_id=${String(verification.toolId ?? '')} status=${String(verification.status ?? '')}`,
+        `summary: ${String(verification.summary ?? '')}`,
+        verification.smokeRunId ? `smoke_run_id: ${String(verification.smokeRunId)}` : null,
+    ].filter(Boolean).join('\n');
+}
+export function summarizeToolValidate(data) {
+    if (!data || typeof data !== 'object')
+        return 'Workspace tool manifest validation returned no data.';
+    const payload = data;
+    const diagnostics = Array.isArray(payload.diagnostics)
+        ? payload.diagnostics
+        : [];
+    const errors = diagnostics.filter((diagnostic) => String(diagnostic.severity).toLowerCase() === 'error');
+    const warnings = diagnostics.filter((diagnostic) => String(diagnostic.severity).toLowerCase() === 'warning');
+    const others = diagnostics.filter((diagnostic) => {
+        const severity = String(diagnostic.severity).toLowerCase();
+        return severity !== 'error' && severity !== 'warning';
+    });
+    const summaryParts = [];
+    if (errors.length > 0)
+        summaryParts.push(`${errors.length} error(s)`);
+    if (warnings.length > 0)
+        summaryParts.push(`${warnings.length} warning(s)`);
+    if (others.length > 0)
+        summaryParts.push(`${others.length} notice(s)`);
+    const summary = summaryParts.length > 0 ? ` ${summaryParts.join(', ')}` : '';
+    const lines = payload.valid === true
+        ? [diagnostics.length === 0 ? 'Workspace tool manifest is valid.' : `Workspace tool manifest is valid with${summary}.`]
+        : [`Workspace tool manifest validation failed.${summary}`];
+    for (const diagnostic of diagnostics) {
+        const severity = String(diagnostic.severity ?? 'info').toUpperCase();
+        const code = String(diagnostic.code ?? '');
+        const message = String(diagnostic.message ?? '');
+        const codePrefix = code ? `${code}: ` : '';
+        lines.push(`[${severity}] ${codePrefix}${message}`);
+    }
+    return lines.join('\n');
+}
+export function summarizeToolAction(data, fallbackActionId) {
+    if (!data || typeof data !== 'object')
+        return `Tool action ${fallbackActionId} completed.`;
+    const payload = data;
+    if (payload.mode === 'notify_agent') {
+        return `Tool action notified agent. action=${fallbackActionId} conversation_id=${String(payload.conversationId ?? '')} queued=${payload.queued === true ? 'yes' : 'no'}`;
+    }
+    const run = payload.run ?? {};
+    const tool = payload.tool ?? {};
+    const node = run.executionHostname || run.executionNodeId
+        ? ` node=${String(run.executionHostname ?? run.executionNodeId)}`
+        : '';
+    return [
+        `Tool action completed. tool_id=${String(tool.toolId ?? '')} action=${String(run.actionId ?? fallbackActionId)} run_id=${String(run.runId ?? '')} status=${String(run.status ?? 'unknown')}${node}`,
+        `latest_state: ${summarizeToolState(payload.latestState ?? tool.latestState)}`,
+    ].join('\n');
+}
+export function inferMimeType(filePath) {
+    return MIME_BY_EXTENSION[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+}
+export function formatSize(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return 'unknown';
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+export function isTextLikeMimeType(mimeType) {
+    const normalized = mimeType.split(';', 1)[0]?.trim().toLowerCase() ?? '';
+    return normalized.startsWith('text/')
+        || normalized === 'application/json'
+        || normalized === 'application/ld+json'
+        || normalized === 'application/xml'
+        || normalized === 'application/x-ndjson'
+        || normalized === 'application/yaml'
+        || normalized === 'application/x-yaml'
+        || normalized === 'application/toml'
+        || normalized === 'application/javascript'
+        || normalized === 'application/typescript'
+        || normalized === 'application/x-tex'
+        || normalized === 'application/x-latex'
+        || normalized === 'application/latex'
+        || normalized.endsWith('+json')
+        || normalized.endsWith('+xml');
+}
+export function isTextLikeAttachment(mimeType, metadata, filename) {
+    if (isTextLikeMimeType(mimeType))
+        return true;
+    const kind = typeof metadata.kind === 'string' ? metadata.kind.trim().toLowerCase() : '';
+    if (['text', 'json', 'markdown', 'csv', 'code', 'yaml', 'xml'].includes(kind))
+        return true;
+    const inferred = inferMimeType(filename);
+    return inferred !== 'application/octet-stream' && isTextLikeMimeType(inferred);
+}
+export function summarizeAttachmentUpload(data) {
+    if (!data || typeof data !== 'object')
+        return 'Attachment uploaded.';
+    const payload = data;
+    const id = String(payload.assetId ?? payload.id ?? '');
+    return [
+        `Attachment uploaded. attachment_id=${id}`,
+        `filename=${String(payload.filename ?? '')} size=${formatSize(Number(payload.sizeBytes ?? 0))} kind=${String(payload.kind ?? 'unknown')}`,
+        `scope=${String(payload.scopeType ?? 'none')}:${String(payload.scopeId ?? 'none')}`,
+        'Pass this id to `bigbang message send --attachment-id`.',
+    ].join('\n');
+}
+export function summarizeAttachmentView(params) {
+    const filename = String(params.metadata.filename ?? params.attachmentId);
+    const mimeType = String(params.metadata.mimeType ?? params.contentType ?? inferMimeType(filename));
+    const sizeBytes = typeof params.metadata.sizeBytes === 'number' ? params.metadata.sizeBytes : params.buffer.length;
+    const base = {
+        attachmentId: params.attachmentId,
+        filename,
+        mimeType,
+        sizeBytes,
+        kind: params.metadata.kind ?? null,
+    };
+    if (isTextLikeAttachment(mimeType, params.metadata, filename)) {
+        const content = params.buffer.toString('utf8');
+        const preview = content.length > ATTACHMENT_TEXT_PREVIEW_MAX_CHARS
+            ? `${content.slice(0, ATTACHMENT_TEXT_PREVIEW_MAX_CHARS)}\n... [truncated ${content.length - ATTACHMENT_TEXT_PREVIEW_MAX_CHARS} chars]`
+            : content;
+        return {
+            text: [
+                `Attachment ${params.attachmentId} (${mimeType}, ${formatSize(sizeBytes)})`,
+                '',
+                '```text',
+                preview,
+                '```',
+            ].join('\n'),
+            data: { ...base, contentPreview: preview, truncated: content.length > ATTACHMENT_TEXT_PREVIEW_MAX_CHARS },
+        };
+    }
+    const note = mimeType.startsWith('image/')
+        ? 'Image attachment downloaded; binary data is not printed by bigbang.'
+        : 'Binary attachment downloaded; binary data is not printed by bigbang.';
+    return {
+        text: `Attachment ${params.attachmentId} (${mimeType}, ${formatSize(sizeBytes)}). ${note}`,
+        data: base,
+    };
+}
+export function summarizeAttachmentComments(attachmentId, data) {
+    const comments = Array.isArray(data) ? data : [];
+    if (comments.length === 0)
+        return `No comments on ${attachmentId}.`;
+    const lines = [`Comments on ${attachmentId}: ${comments.length}`];
+    for (const raw of comments) {
+        const item = raw && typeof raw === 'object' ? raw : {};
+        const author = item.author && typeof item.author === 'object' ? item.author : {};
+        const name = typeof author.name === 'string' && author.name.trim() ? author.name.trim() : String(author.userId ?? 'unknown');
+        const createdAt = typeof item.createdAt === 'number' && Number.isFinite(item.createdAt)
+            ? new Date(item.createdAt).toISOString()
+            : 'unknown';
+        lines.push(`- ${createdAt} @${name}: ${String(item.body ?? '')}`);
+    }
+    return lines.join('\n');
+}
+export function summarizeServerDirectory(data) {
+    if (!data || typeof data !== 'object')
+        return 'Server directory returned no data.';
+    const payload = data;
+    const lines = ['Server directory'];
+    lines.push('channels:');
+    for (const channel of payload.channels ?? []) {
+        const name = String(channel.name ?? '');
+        const joined = channel.joined === true ? 'joined' : 'not joined';
+        const description = typeof channel.description === 'string' && channel.description.trim()
+            ? ` - ${channel.description.trim()}`
+            : '';
+        lines.push(`- #${name} [${joined}]${description}`);
+    }
+    if (!payload.channels?.length)
+        lines.push('- none');
+    lines.push('agents:');
+    for (const agent of payload.agents ?? []) {
+        lines.push(`- @${String(agent.name ?? '')} (${String(agent.status ?? 'unknown')})`);
+    }
+    if (!payload.agents?.length)
+        lines.push('- none');
+    lines.push('humans:');
+    for (const human of payload.humans ?? []) {
+        lines.push(`- @${String(human.name ?? '')}`);
+    }
+    if (!payload.humans?.length)
+        lines.push('- none');
+    return lines.join('\n');
+}
+export function summarizeInboxCheck(data) {
+    const record = data && typeof data === 'object' ? data : {};
+    const totalUnread = Number(record.totalUnread ?? record.total_unread ?? 0);
+    const surfaceCount = Number(record.surfaceCount ?? record.surface_count ?? 0);
+    const items = Array.isArray(record.items) ? record.items : [];
+    if (items.length === 0) {
+        return 'Inbox empty.';
+    }
+    const lines = [
+        `Inbox: ${Number.isFinite(totalUnread) ? totalUnread : items.length} unread across ${Number.isFinite(surfaceCount) ? surfaceCount : items.length} surface(s).`,
+    ];
+    for (const raw of items.slice(0, 20)) {
+        const item = raw && typeof raw === 'object' ? raw : {};
+        const target = String(item.target ?? '(unknown target)');
+        const unreadCount = Number(item.unreadCount ?? item.unread_count ?? 0);
+        const firstSeq = Number(item.firstSeq ?? item.first_seq ?? 0);
+        const lastSeq = Number(item.lastSeq ?? item.last_seq ?? 0);
+        const sender = String(item.lastSenderName ?? item.last_sender_name ?? item.lastSenderType ?? item.last_sender_type ?? 'unknown');
+        const seqRange = Number.isFinite(firstSeq) && Number.isFinite(lastSeq)
+            ? `seq ${firstSeq}-${lastSeq}`
+            : 'seq unknown';
+        lines.push(`- ${target}: ${Number.isFinite(unreadCount) ? unreadCount : 1} unread (${seqRange}, latest ${sender})`);
+    }
+    if (items.length > 20)
+        lines.push(`... ${items.length - 20} more surface(s)`);
+    lines.push('Next: run `bigbang message check` to drain unread content, or `bigbang message read --channel <target>` for targeted context.');
+    return lines.join('\n');
+}
+export function summarizeInboxWait(data) {
+    const record = data && typeof data === 'object' ? data : {};
+    const items = Array.isArray(record.items) ? record.items : [];
+    const timedOut = record.timedOut === true || record.timed_out === true;
+    if (timedOut && items.length === 0) {
+        return 'Inbox wait timed out with no pending surfaces.';
+    }
+    return summarizeInboxCheck(data);
+}
+export function summarizeSelfState(data) {
+    if (!data || typeof data !== 'object')
+        return 'Self state returned no data.';
+    const reportText = data.reportText;
+    if (typeof reportText === 'string' && reportText.trim())
+        return reportText.trim();
+    return 'Self state returned no report text.';
+}
+export function summarizeRuntimePresence(data) {
+    if (!data || typeof data !== 'object')
+        return 'Runtime presence returned no data.';
+    const reportText = data.reportText;
+    if (typeof reportText === 'string' && reportText.trim())
+        return reportText.trim();
+    return 'Runtime presence returned no report text.';
+}
+export function summarizeConversationList(data) {
+    if (!data || typeof data !== 'object')
+        return 'Conversation list returned no data.';
+    const conversations = Array.isArray(data.conversations)
+        ? data.conversations
+        : [];
+    if (conversations.length === 0)
+        return 'No conversations found.';
+    const lines = conversations.slice(0, 40).map((conversation) => {
+        const target = String(conversation.replyTarget ?? conversation.conversationId ?? 'unknown');
+        const status = String(conversation.status ?? 'unknown');
+        const unread = Number(conversation.unreadCount ?? 0);
+        const queued = Number(conversation.queuedPromptCount ?? 0);
+        const active = conversation.hasActiveRun === true ? 'yes' : 'no';
+        const kind = String(conversation.surfaceKind ?? '');
+        return `- ${target}${kind ? ` [${kind}]` : ''} status=${status} unread=${unread} queued=${queued} active=${active}`;
+    });
+    const suffix = conversations.length > lines.length ? `\n... ${conversations.length - lines.length} more conversation(s)` : '';
+    return `Conversations: ${conversations.length}\n${lines.join('\n')}${suffix}`;
+}
+export function summarizeConversationSummary(data) {
+    if (!data || typeof data !== 'object')
+        return 'Conversation summary returned no data.';
+    const record = data.conversation;
+    if (!record)
+        return 'Conversation summary returned no data.';
+    const reportText = record.reportText;
+    if (typeof reportText === 'string' && reportText.trim())
+        return reportText.trim();
+    const target = String(record.replyTarget ?? record.conversationId ?? 'unknown');
+    const status = String(record.status ?? 'unknown');
+    const unread = Number(record.unreadCount ?? 0);
+    const queued = Number(record.queuedPromptCount ?? 0);
+    const summaryText = typeof record.summaryText === 'string' && record.summaryText.trim()
+        ? record.summaryText.trim()
+        : null;
+    return [
+        `Conversation: ${target}`,
+        `status=${status} unread=${unread} queued=${queued}`,
+        ...(summaryText ? [`summary: ${summaryText}`] : []),
+    ].join('\n');
+}
+export function summarizeContextBundle(data) {
+    if (!data || typeof data !== 'object')
+        return 'Context bundle returned no data.';
+    const bundle = data.bundle;
+    if (!bundle)
+        return 'Context bundle returned no data.';
+    const current = bundle.currentConversation && typeof bundle.currentConversation === 'object'
+        ? bundle.currentConversation
+        : {};
+    const target = String(current.replyTarget ?? current.conversationId ?? 'current');
+    const surfaces = Array.isArray(bundle.surfaces) ? bundle.surfaces.length : 0;
+    const tasks = Array.isArray(bundle.tasks) ? bundle.tasks.length : 0;
+    const handoffs = Array.isArray(bundle.handoffs) ? bundle.handoffs.length : 0;
+    const suggestions = Array.isArray(bundle.suggestedHistoryReads) ? bundle.suggestedHistoryReads.length : 0;
+    return [
+        `Context bundle for ${target}`,
+        `surfaces=${surfaces} tasks=${tasks} handoffs=${handoffs} suggested_history_reads=${suggestions}`,
+    ].join('\n');
+}
+export function summarizeHeldMessageDrafts(data) {
+    if (!data || typeof data !== 'object')
+        return 'Held message drafts returned no data.';
+    const drafts = Array.isArray(data.drafts)
+        ? data.drafts
+        : [];
+    if (drafts.length === 0)
+        return 'No held message drafts found.';
+    const lines = drafts.slice(0, 20).map((draft) => {
+        const draftId = String(draft.draftId ?? 'unknown');
+        const target = String(draft.resolvedTarget ?? draft.channelId ?? 'unknown');
+        const status = String(draft.status ?? 'unknown');
+        const preview = typeof draft.contentPreview === 'string' && draft.contentPreview.trim()
+            ? draft.contentPreview.trim()
+            : '';
+        return `- draft_id=${draftId} target=${target} status=${status}${preview ? ` preview="${preview}"` : ''}`;
+    });
+    const suffix = drafts.length > lines.length ? `\n... ${drafts.length - lines.length} more draft(s)` : '';
+    return `Held message drafts: ${drafts.length}\n${lines.join('\n')}${suffix}`;
+}
+export function summarizeHandoffCreate(data) {
+    if (!data || typeof data !== 'object')
+        return 'Handoff created.';
+    const payload = data;
+    const handoff = payload.handoff ?? {};
+    const handoffId = String(handoff.handoffId ?? '');
+    const target = String(handoff.targetReplyTarget ?? handoff.targetConversationId ?? 'unknown');
+    const mode = String(handoff.mode ?? 'unknown');
+    const status = String(handoff.status ?? 'unknown');
+    return [
+        `Handoff created. handoff_id=${handoffId}`,
+        `target=${target} mode=${mode} status=${status}`,
+    ].join('\n');
+}
+export function summarizeHandoffStatus(data) {
+    if (!data || typeof data !== 'object')
+        return 'Handoff status returned no data.';
+    const payload = data;
+    const handoff = payload.handoff ?? {};
+    const handoffId = String(handoff.handoffId ?? '');
+    const source = String(handoff.sourceReplyTarget ?? handoff.sourceConversationId ?? 'unknown');
+    const target = String(handoff.targetReplyTarget ?? handoff.targetConversationId ?? 'unknown');
+    const mode = String(handoff.mode ?? 'unknown');
+    const status = String(handoff.status ?? 'unknown');
+    return [
+        `Handoff ${handoffId}`,
+        `source=${source} target=${target} mode=${mode} status=${status}`,
+    ].join('\n');
+}
+export function summarizePanelComponents(data) {
+    if (!data || typeof data !== 'object')
+        return 'Panel components returned no data.';
+    const components = Array.isArray(data.components)
+        ? data.components
+        : [];
+    if (components.length === 0)
+        return 'No panel UI components available.';
+    const lines = components.map((component) => {
+        const name = String(component.name ?? 'unnamed');
+        const description = typeof component.description === 'string' && component.description.trim()
+            ? ` — ${component.description.trim()}`
+            : '';
+        return `- ${name}${description}`;
+    });
+    return `Available panel UI components: ${components.length}\n${lines.join('\n')}`;
+}
+export function summarizeChannelMembers(data) {
+    if (!data || typeof data !== 'object')
+        return 'Channel members returned no data.';
+    const payload = data;
+    const target = String(payload.channel?.target ?? (payload.channel?.name ? `#${payload.channel.name}` : 'channel'));
+    const members = payload.members ?? [];
+    const lines = [`${target} members (${members.length}):`];
+    for (const member of members) {
+        const self = member.isSelf === true ? ' self' : '';
+        lines.push(`- @${String(member.name ?? '')} agent_id=${String(member.agentId ?? '')} type=${String(member.agentType ?? 'unknown')}${self}`);
+    }
+    if (members.length === 0)
+        lines.push('- none');
+    return lines.join('\n');
+}
+export function summarizeChannelMutation(data, verb) {
+    if (!data || typeof data !== 'object')
+        return `Channel ${verb}.`;
+    const payload = data;
+    const target = String(payload.channel?.target ?? (payload.channel?.name ? `#${payload.channel.name}` : payload.channel?.channelId ?? 'channel'));
+    return `Channel ${verb}: ${target}`;
+}
+export function summarizeThreadUnfollow(data) {
+    if (!data || typeof data !== 'object')
+        return 'Thread unfollowed.';
+    const payload = data;
+    const target = String(payload.channel?.target ?? payload.threadRootId ?? 'thread');
+    const removed = payload.removed ?? {};
+    return [
+        `Thread unfollowed: ${target}`,
+        `removed: participants=${String(removed.participants ?? 0)} roster=${String(removed.roster ?? 0)} notification_state=${String(removed.notificationState ?? 0)} notification_rounds=${String(removed.notificationRounds ?? 0)}`,
+    ].join('\n');
+}
+export function appendReminderConversation(runtime, commandName, body = {}) {
+    return {
+        ...body,
+        conversationId: requireConversationId(runtime, commandName),
+    };
+}
+export { AGENT_COMMAND_ERROR_CODES, AgentCommandError, formatMessageHeld, formatPanelVersionConflict, formatTaskHeld, readOptionalStdin, readRequiredJsonStdin, readRequiredStdin, toAgentCommandError, };