@bbigbang/channel-bridge 0.1.0

package/dist/messageFormat.d.ts

@@ -0,0 +1,26 @@
+export type IncomingMessageItem = {
+    message_id: string;
+    target: string;
+    timestamp: string;
+    sender_name: string;
+    sender_type: string;
+    content: string;
+    task_number?: number | null;
+    task_status?: string | null;
+    task_assignee_name?: string | null;
+};
+export type HistoryMessageItem = {
+    id: string;
+    target: string;
+    seq: number;
+    createdAt: string;
+    senderName: string;
+    senderType: string;
+    content: string;
+    taskNumber?: number | null;
+    taskStatus?: string | null;
+    taskAssigneeName?: string | null;
+};
+export declare function formatBeijingPromptTimestamp(input: string): string;
+export declare function formatMessages(messages: IncomingMessageItem[]): string;
+export declare function formatHistoryMessages(messages: HistoryMessageItem[]): string;

package/dist/messageFormat.js

@@ -0,0 +1,85 @@
+const MESSAGE_SEPARATOR = '\n\n---\n\n';
+const BEIJING_TIME_ZONE = 'Asia/Shanghai';
+const BEIJING_DATE_TIME_FORMATTER = new Intl.DateTimeFormat('en-US', {
+    timeZone: BEIJING_TIME_ZONE,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+});
+function formatBeijingDateTime(input) {
+    const date = new Date(input);
+    if (!Number.isFinite(date.getTime()))
+        return input;
+    const parts = BEIJING_DATE_TIME_FORMATTER.formatToParts(date);
+    const values = {};
+    for (const part of parts) {
+        if (part.type !== 'literal')
+            values[part.type] = part.value;
+    }
+    return `${values.year}-${values.month}-${values.day} ${values.hour}:${values.minute}:${values.second}`;
+}
+export function formatBeijingPromptTimestamp(input) {
+    return `${formatBeijingDateTime(input)} UTC+8`;
+}
+function formatMetadataBlock(lines) {
+    return ['[Message metadata]', ...lines.filter(Boolean)].join('\n');
+}
+function formatBodyBlock(label, body) {
+    return `${label}\n${body}`;
+}
+function joinParts(parts) {
+    return parts.filter((part) => Boolean(part)).join('  ');
+}
+export function formatMessages(messages) {
+    return messages
+        .map((m) => {
+        const taskLine = m.task_number != null
+            ? `task: #${m.task_number} [${m.task_status ?? 'todo'}]${m.task_assignee_name ? ` @${m.task_assignee_name}` : ''}`
+            : null;
+        const metadata = formatMetadataBlock([
+            joinParts([
+                `target: ${m.target}`,
+                `msg: ${m.message_id.slice(0, 8)}`,
+            ]),
+            joinParts([
+                `time: ${formatBeijingPromptTimestamp(m.timestamp)}`,
+                `sender: @${m.sender_name}`,
+                m.sender_type === 'agent' ? 'sender_type: agent' : null,
+            ]),
+            taskLine,
+        ]);
+        const body = formatBodyBlock('[Message body]', m.content);
+        return `${metadata}\n\n${body}`;
+    })
+        .join(MESSAGE_SEPARATOR);
+}
+export function formatHistoryMessages(messages) {
+    return messages
+        .map((m) => {
+        const taskLine = m.taskNumber != null
+            ? `task: #${m.taskNumber} [${m.taskStatus ?? 'todo'}]${m.taskAssigneeName ? ` @${m.taskAssigneeName}` : ''}`
+            : null;
+        const metadata = formatMetadataBlock([
+            joinParts([
+                `target: ${m.target}`,
+                `msg: ${m.id.slice(0, 8)}`,
+            ]),
+            joinParts([
+                `seq: ${m.seq}`,
+                `time: ${formatBeijingPromptTimestamp(m.createdAt)}`,
+            ]),
+            joinParts([
+                `sender: @${m.senderName}`,
+                m.senderType === 'agent' ? 'sender_type: agent' : null,
+            ]),
+            taskLine,
+        ]);
+        const body = formatBodyBlock('[Message body]', m.content);
+        return `${metadata}\n\n${body}`;
+    })
+        .join(MESSAGE_SEPARATOR);
+}

package/dist/panelFormat.d.ts

@@ -0,0 +1,25 @@
+import type { ComponentContract } from '@bbigbang/protocol';
+/**
+ * Format a component contract registry into a human-readable text summary
+ * suitable for agent tool output.
+ */
+export declare function formatComponentRegistry(contracts: ComponentContract[]): string;
+/**
+ * Format a panel state object into a human-readable text summary.
+ * Supports both legacy flat shape { state } and new envelope shape { perUser, shared, version }.
+ */
+export declare function formatPanelState(state: unknown): string;
+export declare function formatPanelRows(result: unknown): string;
+export declare function formatPanelEvents(result: unknown): string;
+export declare function formatPanelCollaborators(result: unknown): string;
+/**
+ * Format a render_panel success response.
+ */
+export declare function formatRenderPanelSuccess(panelId: string, data?: unknown): string;
+export declare function formatPatchPanelSuccess(data: unknown): string;
+export declare function formatPatchPanelError(data: unknown): string;
+export declare function formatUpsertPanelError(data: unknown): string;
+/**
+ * Format a render_panel structured error into an agent-readable message.
+ */
+export declare function formatRenderPanelError(data: unknown): string;

package/dist/panelFormat.js

@@ -0,0 +1,391 @@
+/**
+ * Format a component contract registry into a human-readable text summary
+ * suitable for agent tool output.
+ */
+export function formatComponentRegistry(contracts) {
+    if (!contracts.length) {
+        return 'No UI components available.';
+    }
+    const lines = [
+        '## Available UI Components',
+        '',
+        'Treat this output as the canonical current-run source for component props, dataset, state, and supported actions before the first render_panel call.',
+        'For detailed RowTemplateGrid template grammar and valid node examples, use the mounted ui-panel skill docs.',
+        'Copy the declared prop names, field names, media slots, and supported actions from here instead of guessing.',
+        'When the user asks to plan layout first with /panel:plan or /tool:plan, send a chat wireframe and wait for confirmation; do not call render_panel or publish_workspace_tool in that planning run.',
+        'For status, monitoring, dashboard, or tool-control views, prefer RowTemplateGrid Columns and concise field labels instead of stacking every field vertically in one Card.',
+        'Dataset source kinds currently accepted by render_panel are workspace_jsonl, inline_rows, attachment_manifest, query_handle, and api_jsonl. query_handle uses handle="workspace_jsonl:<path>" for one dynamic paged workspace JSONL file, or handle="workspace_jsonl_list:[\\"a.jsonl\\",\\"b.jsonl\\"]" for ordered multi-file JSONL aggregation. api_jsonl reads JSONL from url:"http://..." or ordered urls:[...] endpoints on the agent node, agent-node allowlisted remote origins, or agent-node allowlisted URL prefixes. api_jsonl auth uses optional node-side auth.profile names only; never include header values or tokens in panel payloads. Relative workspace paths are workspace-relative and absolute workspace paths require the node allowlist.',
+        'For RowTemplateGrid, top-level panel.actions is an action registry, not a guaranteed visible toolbar; use ActionBar or ActionButton for explicit visible action controls.',
+        'Panel action mode is explicit: use mode="notify_agent" to wake the agent, or mode="platform_exec" with command and optional workspace-relative cwd for direct execution on the agent node. For panel-to-tool promotion, actions may also declare toolKind, paramsSchema, persistent, maxRunSeconds, and idleTimeoutSeconds as Workspace Tool manifest hints; ordinary panel clicks do not prompt for paramsSchema. Legacy rpcCommand/rpcCwd input remains accepted for compatibility.',
+        '',
+    ];
+    for (const c of contracts) {
+        lines.push(`### ${c.name}`);
+        lines.push(`Display: ${c.displayName}`);
+        lines.push(`Description: ${c.description}`);
+        lines.push(`Data model: ${c.dataModel.kind}`);
+        if (c.propsSchema && Object.keys(c.propsSchema).length > 0) {
+            lines.push(`Props: ${JSON.stringify(c.propsSchema)}`);
+        }
+        if (c.datasetSchema) {
+            const fields = c.datasetSchema.fields.map((f) => `${f.name}${f.label ? ` label="${f.label}"` : ''} (${f.type}${f.filterable ? ', filterable' : ''}${f.sortable ? ', sortable' : ''})`);
+            lines.push(`Dataset fields: ${fields.join(', ')}`);
+            if (c.datasetSchema.mediaSlots.length) {
+                const slots = c.datasetSchema.mediaSlots.map((s) => `${s.name} (${s.kind}, ${s.displayType})`);
+                lines.push(`Media slots: ${slots.join(', ')}`);
+            }
+        }
+        if (c.stateSchema && Object.keys(c.stateSchema).length > 0) {
+            lines.push(`State schema: ${JSON.stringify(c.stateSchema)}`);
+        }
+        if (c.clientInteractions?.length) {
+            lines.push(`Client interactions: ${c.clientInteractions.join(', ')}`);
+        }
+        if (c.supportedActions?.length) {
+            const actions = c.supportedActions.map((a) => `${a.id} (${a.label})`);
+            lines.push(`Supported actions: ${actions.join(', ')}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Format a panel state object into a human-readable text summary.
+ * Supports both legacy flat shape { state } and new envelope shape { perUser, shared, version }.
+ */
+export function formatPanelState(state) {
+    const envelope = state && typeof state === 'object' ? state : {};
+    // Detect envelope shape (non-direct scope)
+    if ('perUser' in envelope || 'shared' in envelope) {
+        const perUser = envelope.perUser && typeof envelope.perUser === 'object'
+            ? envelope.perUser
+            : {};
+        const shared = envelope.shared && typeof envelope.shared === 'object'
+            ? envelope.shared
+            : {};
+        const version = typeof envelope.version === 'number' ? envelope.version : 0;
+        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 : [];
+        const lines = ['## Panel State\n'];
+        lines.push(`Version: ${version}`);
+        const filterEntries = Object.entries(filters);
+        if (filterEntries.length > 0) {
+            lines.push('Filters (per-user):');
+            for (const [key, value] of filterEntries) {
+                lines.push(`  ${key}: ${String(value)}`);
+            }
+        }
+        else {
+            lines.push('Filters (per-user): (none)');
+        }
+        const sortEntries = Object.entries(sort);
+        if (sortEntries.length > 0) {
+            lines.push('Sort (per-user):');
+            for (const [key, value] of sortEntries) {
+                lines.push(`  ${key}: ${String(value)}`);
+            }
+        }
+        else {
+            lines.push('Sort (per-user): (none)');
+        }
+        if (selection.length > 0) {
+            lines.push(`Shared selection: ${selection.map(String).join(', ')}`);
+        }
+        else {
+            lines.push('Shared selection: (none)');
+        }
+        return lines.join('\n');
+    }
+    // Legacy flat shape (direct scope)
+    const s = envelope;
+    const filters = s.filters && typeof s.filters === 'object' ? s.filters : {};
+    const sort = s.sort && typeof s.sort === 'object' ? s.sort : {};
+    const selection = Array.isArray(s.selection) ? s.selection : [];
+    const lines = ['## Panel State\n'];
+    const filterEntries = Object.entries(filters);
+    if (filterEntries.length > 0) {
+        lines.push('Filters:');
+        for (const [key, value] of filterEntries) {
+            lines.push(`  ${key}: ${String(value)}`);
+        }
+    }
+    else {
+        lines.push('Filters: (none)');
+    }
+    const sortEntries = Object.entries(sort);
+    if (sortEntries.length > 0) {
+        lines.push('Sort:');
+        for (const [key, value] of sortEntries) {
+            lines.push(`  ${key}: ${String(value)}`);
+        }
+    }
+    else {
+        lines.push('Sort: (none)');
+    }
+    if (selection.length > 0) {
+        lines.push(`Selection: ${selection.map(String).join(', ')}`);
+    }
+    else {
+        lines.push('Selection: (none)');
+    }
+    return lines.join('\n');
+}
+export function formatPanelRows(result) {
+    const record = result && typeof result === 'object' ? result : {};
+    const panelId = typeof record.panelId === 'string' ? record.panelId : '(unknown)';
+    const rows = Array.isArray(record.rows) ? record.rows : [];
+    const nextCursor = typeof record.nextCursor === 'string' ? record.nextCursor : null;
+    const lines = [`## Panel Rows`, '', `Panel ID: ${panelId}`, `Rows returned: ${rows.length}`];
+    for (const rawRow of rows) {
+        const row = rawRow && typeof rawRow === 'object' ? rawRow : {};
+        const rowIndex = typeof row.rowIndex === 'number' ? row.rowIndex : '?';
+        const fields = row.fields && typeof row.fields === 'object' ? row.fields : {};
+        const media = row.media && typeof row.media === 'object' ? row.media : {};
+        lines.push('');
+        lines.push(`### Row ${rowIndex}`);
+        lines.push(`Fields: ${JSON.stringify(fields)}`);
+        lines.push(`Media refs: ${JSON.stringify(media)}`);
+    }
+    if (nextCursor) {
+        lines.push('');
+        lines.push(`Next cursor: ${nextCursor}`);
+    }
+    return lines.join('\n');
+}
+function formatEventRefs(refs) {
+    const parts = [];
+    for (const key of ['selectedRowIndices', 'selectedRowIds', 'changedRowIndices', 'changedRowIds']) {
+        const value = refs[key];
+        if (Array.isArray(value) && value.length > 0) {
+            parts.push(`${key}=${JSON.stringify(value)}`);
+        }
+    }
+    return parts.length > 0 ? parts.join('; ') : '(none)';
+}
+export function formatPanelEvents(result) {
+    const record = result && typeof result === 'object' ? result : {};
+    const panelId = typeof record.panelId === 'string' ? record.panelId : '(unknown)';
+    const events = Array.isArray(record.events) ? record.events : [];
+    const nextCursor = typeof record.nextCursor === 'string' ? record.nextCursor : null;
+    const lines = [`## Panel Events`, '', `Panel ID: ${panelId}`, `Events returned: ${events.length}`];
+    for (const rawEvent of events) {
+        const event = rawEvent && typeof rawEvent === 'object' ? rawEvent : {};
+        const eventId = typeof event.eventId === 'number' ? event.eventId : '?';
+        const kind = typeof event.event === 'string' ? event.event : 'unknown';
+        const label = typeof event.label === 'string' ? event.label : kind;
+        const summary = typeof event.summary === 'string' ? event.summary : '';
+        const wakePolicy = typeof event.wakePolicy === 'string' ? event.wakePolicy : 'persisted';
+        const version = typeof event.version === 'number' ? event.version : '?';
+        const timestamp = typeof event.timestamp === 'number' ? event.timestamp : null;
+        const actor = event.actor && typeof event.actor === 'object' && !Array.isArray(event.actor)
+            ? event.actor
+            : {};
+        const actorType = typeof actor.type === 'string' ? actor.type : 'unknown';
+        const actorId = typeof actor.id === 'string' && actor.id.trim() ? actor.id : 'unknown';
+        const actorRunId = typeof actor.runId === 'string' && actor.runId.trim() ? `, runId=${actor.runId}` : '';
+        const refs = event.refs && typeof event.refs === 'object' && !Array.isArray(event.refs)
+            ? event.refs
+            : {};
+        const metadataSummary = event.metadataSummary && typeof event.metadataSummary === 'object' && !Array.isArray(event.metadataSummary)
+            ? event.metadataSummary
+            : {};
+        lines.push('');
+        lines.push(`### Event ${eventId}: ${label}`);
+        lines.push(`Type: ${kind}`);
+        lines.push(`Wake policy: ${wakePolicy}`);
+        lines.push(`Version: ${version}`);
+        if (timestamp != null)
+            lines.push(`Timestamp: ${timestamp}`);
+        lines.push(`Actor: ${actorType}:${actorId}${actorRunId}`);
+        if (summary)
+            lines.push(`Summary: ${summary}`);
+        if (typeof event.submitKind === 'string')
+            lines.push(`Submit kind: ${event.submitKind}`);
+        if (typeof event.actionId === 'string')
+            lines.push(`Action ID: ${event.actionId}`);
+        lines.push(`Refs: ${formatEventRefs(refs)}`);
+        if (Object.keys(metadataSummary).length > 0) {
+            lines.push(`Metadata summary: ${JSON.stringify(metadataSummary)}`);
+        }
+    }
+    if (nextCursor) {
+        lines.push('');
+        lines.push(`Next cursor: ${nextCursor}`);
+    }
+    return lines.join('\n');
+}
+export function formatPanelCollaborators(result) {
+    const record = result && typeof result === 'object' ? result : {};
+    const panelId = typeof record.panelId === 'string' ? record.panelId : '(unknown)';
+    const collaborators = Array.isArray(record.collaborators) ? record.collaborators : [];
+    const lines = ['## Panel Collaborators', '', `Panel ID: ${panelId}`];
+    if (collaborators.length === 0) {
+        lines.push('Collaborators: (none)');
+        return lines.join('\n');
+    }
+    lines.push('Collaborators:');
+    for (const raw of collaborators) {
+        const item = raw && typeof raw === 'object' ? raw : {};
+        const agentId = typeof item.agentId === 'string' ? item.agentId : '(unknown)';
+        const name = typeof item.name === 'string' && item.name.trim() ? item.name.trim() : agentId;
+        const role = typeof item.role === 'string' ? item.role : 'collaborator';
+        const addedBy = typeof item.addedBy === 'string' && item.addedBy.trim() ? `, addedBy=${item.addedBy}` : '';
+        lines.push(`- ${name} (${agentId}): ${role}${addedBy}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Format a render_panel success response.
+ */
+export function formatRenderPanelSuccess(panelId, data) {
+    const record = data && typeof data === 'object' ? data : {};
+    const diagnostics = record.diagnostics && typeof record.diagnostics === 'object'
+        ? record.diagnostics
+        : {};
+    const duplicateCandidates = Array.isArray(diagnostics.duplicatePanelCandidates)
+        ? diagnostics.duplicatePanelCandidates
+        : [];
+    const lines = [
+        `Panel created successfully. Panel ID: ${panelId}`,
+        '',
+        `Spot-check with read_panel_rows(panel_id="${panelId}", limit=3), remember the panel_id plus dataset path, then use send_message(panel_ids=["${panelId}"]) to share it in the conversation.`,
+        `This panel was created without a stable handle; continue this exact panel with patch_panel(panel_id="${panelId}", ...). For future recurring annotation/evaluation/workbench flows, start with upsert_panel(handle=...) so updates land in the same handle-bound panel.`,
+    ];
+    if (duplicateCandidates.length > 0) {
+        lines.push('');
+        lines.push('Duplicate panel diagnostic: this conversation already has similar panels.');
+        for (const rawCandidate of duplicateCandidates.slice(0, 3)) {
+            const candidate = rawCandidate && typeof rawCandidate === 'object' ? rawCandidate : {};
+            const candidateId = typeof candidate.panelId === 'string' ? candidate.panelId : '(unknown)';
+            const handle = typeof candidate.handle === 'string' && candidate.handle.trim() ? ` handle=${candidate.handle}` : '';
+            const title = typeof candidate.title === 'string' && candidate.title.trim() ? ` title="${candidate.title}"` : '';
+            const version = typeof candidate.version === 'number' ? ` version=${candidate.version}` : '';
+            const reason = typeof candidate.reason === 'string' ? ` reason=${candidate.reason}` : '';
+            lines.push(`- ${candidateId}${handle}${title}${version}${reason}`);
+        }
+        if (typeof diagnostics.recommendation === 'string' && diagnostics.recommendation.trim()) {
+            lines.push(`Recommendation: ${diagnostics.recommendation}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function formatPatchPanelSuccess(data) {
+    const record = data && typeof data === 'object' ? data : {};
+    const panelId = typeof record.panel_id === 'string' ? record.panel_id : '(unknown)';
+    const version = typeof record.version === 'number' ? record.version : '(unknown)';
+    const status = typeof record.status === 'string' ? record.status : '(unknown)';
+    const rowCount = typeof record.row_count === 'number' ? record.row_count : '(unknown)';
+    const changed = Array.isArray(record.changed) ? record.changed.map(String).join(', ') : '(unknown)';
+    return [
+        'Panel patched successfully.',
+        `Panel ID: ${panelId}`,
+        `Version: ${version}`,
+        `Status: ${status}`,
+        `Rows: ${rowCount}`,
+        `Changed: ${changed}`,
+    ].join('\n');
+}
+export function formatPatchPanelError(data) {
+    if (!data || typeof data !== 'object') {
+        return 'Panel patch failed: unknown error';
+    }
+    const record = data;
+    const failureClass = typeof record.failure_class === 'string' ? record.failure_class : 'unknown_error';
+    const details = record.details && typeof record.details === 'object'
+        ? record.details
+        : {};
+    const lines = [
+        `Panel patch failed: ${failureClass}`,
+        `Details: ${JSON.stringify(details, null, 2)}`,
+    ];
+    if (failureClass === 'version_conflict') {
+        lines.push('Recommended next step: read_panel_events/read_panel_rows or read_panel_state as needed, merge any user changes, then retry with expected_version set to currentVersion. Do not blindly overwrite saved user state or annotations.');
+    }
+    return lines.join('\n');
+}
+export function formatUpsertPanelError(data) {
+    if (!data || typeof data !== 'object') {
+        return 'Panel upsert failed: unknown error';
+    }
+    const record = data;
+    const failureClass = typeof record.failure_class === 'string' ? record.failure_class : 'unknown_error';
+    const details = record.details && typeof record.details === 'object'
+        ? record.details
+        : {};
+    const lines = [
+        `Panel upsert failed: ${failureClass}`,
+        `Details: ${JSON.stringify(details, null, 2)}`,
+    ];
+    if (failureClass === 'version_conflict') {
+        lines.push('Recommended next step: read_panel_events/read_panel_rows or read_panel_state as needed, merge any user changes, then retry upsert_panel(...) with expected_version set to currentVersion. Do not blindly overwrite saved user state or annotations.');
+    }
+    else if (failureClass === 'renderer_switch_forbidden') {
+        lines.push('Recommended next step: keep the existing handle on its current component, or intentionally create a separate new panel with a different stable handle.');
+    }
+    else {
+        lines.push('Correct the issue and retry upsert_panel(...) with the same stable handle.');
+    }
+    return lines.join('\n');
+}
+/**
+ * Format a render_panel structured error into an agent-readable message.
+ */
+export function formatRenderPanelError(data) {
+    if (!data || typeof data !== 'object') {
+        return 'Panel creation failed: unknown error';
+    }
+    const record = data;
+    const failureClass = typeof record.failure_class === 'string' ? record.failure_class : 'unknown_error';
+    const details = record.details && typeof record.details === 'object'
+        ? record.details
+        : {};
+    const lines = [`Panel creation failed: ${failureClass}`];
+    if (failureClass === 'unknown_component') {
+        const component = typeof details.component === 'string' ? details.component : 'unknown';
+        lines.push(`Component "${component}" is not in the curated registry. Use list_ui_components() to see available components.`);
+    }
+    else if (failureClass === 'invalid_props') {
+        lines.push(`Props do not match the component's propsSchema.`);
+        lines.push(`Details: ${JSON.stringify(details, null, 2)}`);
+        lines.push('Re-read list_ui_components() before retrying so the component-level contract matches exactly.');
+        lines.push('If this is RowTemplateGrid, re-check the mounted ui-panel skill docs for the template grammar before retrying.');
+    }
+    else if (failureClass === 'invalid_dataset') {
+        lines.push(`Dataset rows do not match the component's datasetSchema.`);
+        lines.push(`Details: ${JSON.stringify(details, null, 2)}`);
+        lines.push('Re-read list_ui_components() before retrying so the dataset fields and media slots match the current contract.');
+        lines.push('If this is RowTemplateGrid, re-check the mounted ui-panel skill docs before retrying in case the template references undeclared fields or slots.');
+    }
+    else if (failureClass === 'missing_required_fields') {
+        const missingFields = Array.isArray(details.missingFields) ? details.missingFields : [];
+        lines.push(`Missing required fields: ${missingFields.join(', ')}`);
+    }
+    else if (failureClass === 'dataset_path_unreadable') {
+        const path = typeof details.path === 'string' ? details.path : 'unknown';
+        const reason = typeof details.reason === 'string' ? details.reason : 'unknown';
+        lines.push(`Cannot read dataset at "${path}": ${reason}`);
+    }
+    else if (failureClass === 'manifest_too_large') {
+        const rowCount = typeof details.rowCount === 'number' ? details.rowCount : 'unknown';
+        const max = typeof details.max === 'number' ? details.max : 'unknown';
+        lines.push(`Manifest has ${rowCount} rows, exceeding the maximum of ${max}.`);
+    }
+    else if (failureClass === 'ingest_failed') {
+        const reason = typeof details.reason === 'string' ? details.reason : 'unknown';
+        lines.push(`Ingest failed: ${reason}`);
+    }
+    else if (failureClass === 'version_conflict') {
+        lines.push(`Details: ${JSON.stringify(details, null, 2)}`);
+        lines.push('Recommended next step: read_panel_events/read_panel_rows or read_panel_state as needed, merge any user changes, then retry with expected_version set to currentVersion. Do not blindly overwrite saved user state or annotations.');
+    }
+    else {
+        lines.push(`Details: ${JSON.stringify(details, null, 2)}`);
+    }
+    lines.push('\nCorrect the issue and retry render_panel(...).');
+    return lines.join('\n');
+}

package/dist/surfaceFormats.d.ts

@@ -0,0 +1,15 @@
+import type { RuntimePresenceResponse, SelfStateResponse, SurfaceConversationItem, SurfaceSummaryPayload } from '@bbigbang/protocol';
+export type ToolFormat = 'text' | 'json' | 'both';
+export type { SelfStateResponse, SurfaceConversationItem, SurfaceSummaryPayload };
+type SurfaceConversationView = Omit<SurfaceConversationItem, 'summary'> & {
+    context?: SurfaceSummaryPayload;
+    summary?: SurfaceSummaryPayload;
+};
+export declare function formatToolResult(format: ToolFormat, text: string, data: unknown): string;
+export declare function formatSendMessageDiagnostics(data: Record<string, unknown>): string;
+export declare function formatConversationListText(conversations: SurfaceConversationView[]): string;
+export declare function formatConversationSummaryToolText(conversation: SurfaceConversationView): string;
+export declare function formatRuntimePresenceToolText(presence: RuntimePresenceResponse): string;
+export declare function buildCompactRuntimePresenceData(presence: RuntimePresenceResponse): Record<string, unknown>;
+export declare function formatSelfStateToolText(state: SelfStateResponse): string;
+export declare function buildCompactSelfStateData(state: SelfStateResponse): Record<string, unknown>;