@bbigbang/channel-bridge 0.1.0

package/dist/surfaceFormats.js

@@ -0,0 +1,349 @@
+function formatTaskIdentity(agentTaskRef, taskNumber) {
+    if (agentTaskRef && taskNumber != null)
+        return `${agentTaskRef} · #t${taskNumber}`;
+    if (agentTaskRef)
+        return agentTaskRef;
+    if (taskNumber != null)
+        return `#t${taskNumber}`;
+    return 'task';
+}
+export function formatToolResult(format, text, data) {
+    if (format === 'json') {
+        return JSON.stringify(data, null, 2);
+    }
+    if (format === 'both') {
+        return `${text}\n\n## Structured\n\`\`\`json\n${JSON.stringify(data, null, 2)}\n\`\`\``;
+    }
+    return text;
+}
+export function formatSendMessageDiagnostics(data) {
+    const diagnostics = data.diagnostics && typeof data.diagnostics === 'object'
+        ? data.diagnostics
+        : null;
+    const panel = diagnostics?.panel && typeof diagnostics.panel === 'object'
+        ? diagnostics.panel
+        : null;
+    const unattachedPanelIds = Array.isArray(panel?.unattachedProducedPanelIds)
+        ? panel.unattachedProducedPanelIds
+            .map((id) => typeof id === 'string' ? id.trim() : '')
+            .filter((id) => id.length > 0)
+        : [];
+    if (unattachedPanelIds.length === 0)
+        return '';
+    const recommendation = typeof panel?.recommendation === 'string' && panel.recommendation.trim()
+        ? `\nRecommendation: ${panel.recommendation.trim()}`
+        : '';
+    return `\n\nPanel diagnostic: this run produced additional panels that were not attached to this message: ${unattachedPanelIds.join(', ')}.${recommendation}`;
+}
+export function formatConversationListText(conversations) {
+    if (conversations.length === 0)
+        return 'No conversations found.';
+    const lines = conversations.map((conversation) => {
+        const context = getConversationContext(conversation);
+        const parts = [
+            `${conversation.replyTarget} [${conversation.status}]`,
+            `surface=${conversation.surfaceKind}`,
+            `unread=${conversation.unreadCount}`,
+            `queued=${conversation.queuedPromptCount}`,
+        ];
+        if (context?.myRole)
+            parts.push(`role=${context.myRole}`);
+        if (context?.goal)
+            parts.push(`goal=${context.goal}`);
+        if (context?.nextStep)
+            parts.push(`next=${context.nextStep}`);
+        if (context?.blockers?.length)
+            parts.push(`blockers=${context.blockers.join('; ')}`);
+        if (context?.lastMessage) {
+            parts.push(`last=@${context.lastMessage.senderName}: ${context.lastMessage.preview}`);
+        }
+        return `- ${parts.join('  ')}`;
+    }).join('\n');
+    return `## My Conversations (${conversations.length})\n\n${lines}`;
+}
+export function formatConversationSummaryToolText(conversation) {
+    if (conversation.reportText?.trim())
+        return conversation.reportText.trim();
+    const context = getConversationContext(conversation);
+    const lines = [
+        `Target: ${conversation.replyTarget}`,
+        `Status: ${conversation.status}`,
+        `Surface: ${conversation.surfaceKind}`,
+        `Unread: ${conversation.unreadCount}`,
+        `Queued prompts: ${conversation.queuedPromptCount}`,
+    ];
+    if (context?.goal)
+        lines.push(`Goal: ${context.goal}`);
+    if (context?.recentState)
+        lines.push(`Recent state: ${context.recentState}`);
+    if (context?.blockers?.length)
+        lines.push(`Blockers: ${context.blockers.join('; ')}`);
+    if (context?.nextStep)
+        lines.push(`Next: ${context.nextStep}`);
+    if (context?.myRole)
+        lines.push(`My role: ${context.myRole}`);
+    if (context?.ownerName)
+        lines.push(`Owner: @${context.ownerName}`);
+    if (context?.boundTask) {
+        lines.push(`Bound task: ${formatTaskIdentity(context.boundTask.agentTaskRef, context.boundTask.taskNumber)} [${context.boundTask.status}]`);
+    }
+    if (context?.participants?.length) {
+        lines.push(`Participants: ${context.participants.map((name) => `@${name}`).join(', ')}`);
+    }
+    if (context?.activeHandoff) {
+        lines.push(`Active handoff: ${context.activeHandoff.handoffId} ${context.activeHandoff.mode} [${context.activeHandoff.status}] -> ${context.activeHandoff.targetReplyTarget}`);
+    }
+    if (context?.lastMessage) {
+        lines.push(`Last message: @${context.lastMessage.senderName} — ${context.lastMessage.preview}`);
+    }
+    return lines.join('\n');
+}
+export function formatRuntimePresenceToolText(presence) {
+    if (presence.reportText?.trim())
+        return presence.reportText.trim();
+    const driverNames = (presence.runtime?.runtimeDrivers ?? []).map((driver) => driver.agentType).join(', ') || 'none';
+    const lines = [
+        '[Runtime presence]',
+        `node: ${presence.node?.nodeId ?? 'none'}${presence.node?.machineName ? ` (${presence.node.machineName})` : ''} [${presence.node?.status ?? 'unknown'}]`,
+        `runtime: workspace_root=${presence.runtime?.workspaceRoot ?? 'unknown'} | terminals=${presence.runtime?.terminalBackendAvailable == null ? 'unknown' : (presence.runtime.terminalBackendAvailable ? 'yes' : 'no')} | drivers=${driverNames}`,
+        `hosts: total=${presence.summary?.totalHosts ?? 0}, active=${presence.summary?.activeHosts ?? 0}, idle=${presence.summary?.idleHosts ?? 0}, failed=${presence.summary?.failedHosts ?? 0}, approval=${presence.summary?.hostsWithPendingApproval ?? 0}, resumable=${presence.summary?.resumableHosts ?? 0}`,
+    ];
+    if (presence.currentHost) {
+        lines.push(`current_host: ${(presence.currentHost.replyTarget ?? presence.currentHost.hostKey)} [${presence.currentHost.state}] | pending_dispatch=${presence.currentHost.pendingDispatchCount} | approval=${presence.currentHost.hasPendingApproval ? 'yes' : 'no'}`);
+    }
+    return lines.join('\n');
+}
+export function buildCompactRuntimePresenceData(presence) {
+    return {
+        generatedAt: presence.generatedAt ?? null,
+        node: presence.node ?? null,
+        runtime: presence.runtime
+            ? {
+                workspaceRoot: presence.runtime.workspaceRoot ?? null,
+                terminalBackendAvailable: presence.runtime.terminalBackendAvailable ?? null,
+                runtimeDrivers: (presence.runtime.runtimeDrivers ?? []).map((driver) => driver.agentType),
+                capabilities: presence.runtime.capabilities
+                    ? Object.entries(presence.runtime.capabilities)
+                        .filter(([, enabled]) => Boolean(enabled))
+                        .map(([name]) => name)
+                    : [],
+            }
+            : null,
+        summary: presence.summary ?? null,
+        currentHost: presence.currentHost
+            ? {
+                target: presence.currentHost.replyTarget ?? null,
+                state: presence.currentHost.state,
+                pendingDispatchCount: presence.currentHost.pendingDispatchCount,
+                hasPendingApproval: presence.currentHost.hasPendingApproval,
+                resumable: presence.currentHost.resumable,
+            }
+            : null,
+        otherHosts: (presence.otherHosts ?? []).map((host) => ({
+            target: host.replyTarget ?? null,
+            state: host.state,
+            pendingDispatchCount: host.pendingDispatchCount,
+            hasPendingApproval: host.hasPendingApproval,
+        })),
+    };
+}
+export function formatSelfStateToolText(state) {
+    if (state.reportText?.trim())
+        return state.reportText.trim();
+    const currentConversationId = state.currentConversation?.conversationId ?? null;
+    const otherSurfaces = (state.conversations ?? []).filter((item) => item.conversationId !== currentConversationId);
+    const lines = ['[Agent self state]'];
+    if (state.currentContext?.myRole)
+        lines.push(`role_here: ${state.currentContext.myRole}`);
+    if (state.currentContext?.boundTask) {
+        lines.push(`bound_task: ${formatTaskIdentity(state.currentContext.boundTask.agentTaskRef, state.currentContext.boundTask.taskNumber)} [${state.currentContext.boundTask.status}]`);
+    }
+    lines.push('other_surfaces:');
+    if (otherSurfaces.length === 0) {
+        lines.push('- none');
+    }
+    else {
+        for (const conversation of otherSurfaces.slice(0, 6)) {
+            const summary = getConversationContext(conversation);
+            const extras = [];
+            if (conversation.unreadCount > 0)
+                extras.push(`unread=${conversation.unreadCount}`);
+            if (summary?.myRole)
+                extras.push(`role=${summary.myRole}`);
+            if (summary?.boundTask) {
+                extras.push(`task=${formatTaskIdentity(summary.boundTask.agentTaskRef, summary.boundTask.taskNumber)} [${summary.boundTask.status}]`);
+            }
+            if (summary?.activeHandoff) {
+                extras.push(`handoff=${summary.activeHandoff.handoffId} ${summary.activeHandoff.mode} [${summary.activeHandoff.status}]`);
+            }
+            const teaser = buildSelfStateTeaser(summary);
+            if (teaser)
+                extras.push(`teaser=${teaser}`);
+            lines.push(`- ${conversation.replyTarget} [${conversation.surfaceKind}, ${conversation.status}]${extras.length ? ` | ${extras.join(' | ')}` : ''}`);
+        }
+        const hiddenSurfaces = otherSurfaces.slice(6);
+        if (hiddenSurfaces.length > 0) {
+            lines.push(`- hidden=${hiddenSurfaces.length}${formatHiddenSurfaceBreakdown(hiddenSurfaces)}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function buildCompactSelfStateData(state) {
+    const currentConversationId = state.currentConversation?.conversationId ?? null;
+    const currentBoundTaskId = state.currentContext?.boundTask?.taskId ?? null;
+    const allOtherSurfaces = (state.conversations ?? [])
+        .filter((conversation) => conversation.conversationId !== currentConversationId);
+    const otherSurfaces = allOtherSurfaces
+        .slice(0, 4)
+        .map((conversation) => {
+        const summary = getConversationContext(conversation);
+        const activeHandoff = summary?.activeHandoff ?? null;
+        return {
+            target: conversation.replyTarget,
+            status: conversation.status,
+            surfaceKind: conversation.surfaceKind,
+            ...(conversation.unreadCount > 0 ? { unreadCount: conversation.unreadCount } : {}),
+            role: summary?.myRole ?? null,
+            task: toCompactBoundTask(summary?.boundTask ?? null),
+            activeHandoff: activeHandoff
+                ? {
+                    handoffId: activeHandoff.handoffId,
+                    mode: activeHandoff.mode,
+                    status: activeHandoff.status,
+                    target: activeHandoff.targetReplyTarget,
+                }
+                : null,
+            teaser: buildSelfStateTeaser(summary),
+        };
+    });
+    const hiddenSurfaces = allOtherSurfaces.slice(4);
+    const visibleTasks = (state.recentTasks ?? [])
+        .filter((task) => task.taskId !== currentBoundTaskId)
+        .slice(0, 3);
+    const hiddenTasksCount = Math.max(0, (state.summary?.involvedTasks ?? 0) - (currentBoundTaskId ? 1 : 0) - visibleTasks.length);
+    return {
+        generatedAt: state.generatedAt ?? null,
+        agent: state.agent
+            ? {
+                name: state.agent.name ?? null,
+                agentType: state.agent.agentType ?? null,
+                joinedChannels: (state.agent.joinedChannels ?? []).map((channel) => channel.target),
+            }
+            : null,
+        runtimePresence: state.runtimePresence
+            ? buildCompactRuntimePresenceData(state.runtimePresence)
+            : null,
+        summary: state.summary
+            ? {
+                conversations: state.summary.totalConversations ?? 0,
+                active: state.summary.activeConversations ?? 0,
+                queued: state.summary.queuedConversations ?? 0,
+                recovering: state.summary.recoveringConversations ?? 0,
+                approval: state.summary.awaitingApprovalConversations ?? 0,
+                failed: state.summary.failedConversations ?? 0,
+                surfacesWithNewActivity: state.summary.surfacesWithUnread ?? 0,
+                pending: state.summary.pendingPrompts ?? 0,
+                tasks: {
+                    claimed: state.summary.claimedTasks ?? 0,
+                    involved: state.summary.involvedTasks ?? 0,
+                    review: state.summary.inReviewTasks ?? 0,
+                },
+            }
+            : null,
+        current: state.currentConversation
+            ? {
+                target: state.currentConversation.replyTarget,
+                status: state.currentConversation.status,
+                surfaceKind: state.currentConversation.surfaceKind,
+                role: state.currentContext?.myRole ?? null,
+                task: toCompactBoundTask(state.currentContext?.boundTask ?? null),
+                blockers: (state.currentContext?.blockers ?? [])
+                    .map((blocker) => summarizeInline(blocker, 96))
+                    .filter((blocker) => Boolean(blocker)),
+                activeHandoff: state.currentContext?.activeHandoff
+                    ? {
+                        handoffId: state.currentContext.activeHandoff.handoffId,
+                        mode: state.currentContext.activeHandoff.mode,
+                        status: state.currentContext.activeHandoff.status,
+                        target: state.currentContext.activeHandoff.targetReplyTarget,
+                    }
+                    : null,
+            }
+            : null,
+        otherSurfaces,
+        ...(hiddenSurfaces.length > 0
+            ? {
+                hiddenSurfaces: {
+                    count: hiddenSurfaces.length,
+                    byStatus: summarizeHiddenSurfaceStatuses(hiddenSurfaces),
+                },
+            }
+            : {}),
+        tasks: visibleTasks
+            .map((task) => ({
+            task: formatTaskIdentity(task.agentTaskRef, task.taskNumber),
+            status: task.status,
+            title: summarizeInline(task.title),
+            target: task.threadTarget ?? task.sourceTarget ?? null,
+        })),
+        ...(hiddenTasksCount > 0 ? { hiddenTasksCount } : {}),
+        handoffs: (state.recentHandoffs ?? [])
+            .filter((handoff) => handoff.status !== 'completed')
+            .slice(0, 3)
+            .map((handoff) => ({
+            handoffId: handoff.handoffId,
+            mode: handoff.mode,
+            status: handoff.status,
+            source: handoff.sourceTarget ?? null,
+            target: handoff.targetReplyTarget,
+        })),
+    };
+}
+function summarizeInline(value, maxLength = 96) {
+    const trimmed = value?.trim() ?? '';
+    if (!trimmed)
+        return null;
+    if (trimmed.length <= maxLength)
+        return trimmed;
+    return `${trimmed.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+function getConversationContext(conversation) {
+    return conversation?.context ?? null;
+}
+function buildSelfStateTeaser(summary, maxLength = 64) {
+    const candidates = [
+        summary?.boundTask?.title,
+        summary?.goal,
+        summary?.lastMessage?.preview,
+    ];
+    for (const candidate of candidates) {
+        const teaser = summarizeInline(candidate, maxLength);
+        if (teaser)
+            return teaser;
+    }
+    return null;
+}
+function formatHiddenSurfaceBreakdown(conversations) {
+    const parts = Object.entries(summarizeHiddenSurfaceStatuses(conversations))
+        .map(([status, count]) => `${status}=${count}`);
+    return parts.length > 0 ? `(${parts.join(',')})` : '';
+}
+function summarizeHiddenSurfaceStatuses(conversations) {
+    const order = ['active', 'queued', 'recovering', 'awaiting_approval', 'failed', 'idle'];
+    const counts = new Map();
+    for (const conversation of conversations) {
+        counts.set(conversation.status, (counts.get(conversation.status) ?? 0) + 1);
+    }
+    const result = {};
+    for (const status of order) {
+        const count = counts.get(status) ?? 0;
+        if (count > 0)
+            result[status] = count;
+    }
+    return result;
+}
+function toCompactBoundTask(boundTask) {
+    if (!boundTask)
+        return null;
+    return `${formatTaskIdentity(boundTask.agentTaskRef, boundTask.taskNumber)} [${boundTask.status}]`;
+}

package/dist/taskUpdateFormat.d.ts

@@ -0,0 +1,3 @@
+import type { TaskUpdateDelivery } from '@bbigbang/protocol';
+export declare function formatTaskUpdateDeliveryText(delivery: TaskUpdateDelivery): string;
+export declare function formatTaskUpdateDeliveriesSection(deliveries: TaskUpdateDelivery[]): string;

package/dist/taskUpdateFormat.js

@@ -0,0 +1,17 @@
+export function formatTaskUpdateDeliveryText(delivery) {
+    const noteTargets = delivery.recommendedNoteTargets.length > 0
+        ? delivery.recommendedNoteTargets.join(', ')
+        : 'none';
+    return [
+        delivery.summaryText,
+        `Recommended note targets: ${noteTargets}`,
+        delivery.noteGuidance,
+        delivery.memoryReminder,
+    ].join('\n');
+}
+export function formatTaskUpdateDeliveriesSection(deliveries) {
+    if (deliveries.length === 0)
+        return '';
+    const blocks = deliveries.map((delivery) => formatTaskUpdateDeliveryText(delivery)).join('\n\n');
+    return `\n\nTask update guidance:\n${blocks}`;
+}

package/dist/textPreview.d.ts

@@ -0,0 +1,9 @@
+declare const DEFAULT_INLINE_TEXT_PREVIEW_MAX_BYTES: number;
+export declare function buildInlineTextPreview(params: {
+    attachmentId: string;
+    mimeType: string;
+    sizeLabel: string;
+    fileBuffer: Buffer;
+    maxBytes?: number;
+}): string;
+export { DEFAULT_INLINE_TEXT_PREVIEW_MAX_BYTES };

package/dist/textPreview.js

@@ -0,0 +1,38 @@
+const DEFAULT_INLINE_TEXT_PREVIEW_MAX_BYTES = 64 * 1024;
+function trimIncompleteUtf8Suffix(buffer) {
+    if (buffer.length === 0)
+        return buffer;
+    let continuationBytes = 0;
+    while (continuationBytes < Math.min(3, buffer.length)
+        && (buffer[buffer.length - 1 - continuationBytes] & 0b1100_0000) === 0b1000_0000) {
+        continuationBytes += 1;
+    }
+    const leadIndex = buffer.length - 1 - continuationBytes;
+    if (leadIndex < 0) {
+        return buffer.subarray(0, buffer.length - continuationBytes);
+    }
+    const leadByte = buffer[leadIndex];
+    const expectedLength = ((leadByte & 0b1000_0000) === 0 ? 1
+        : (leadByte & 0b1110_0000) === 0b1100_0000 ? 2
+            : (leadByte & 0b1111_0000) === 0b1110_0000 ? 3
+                : (leadByte & 0b1111_1000) === 0b1111_0000 ? 4
+                    : 1);
+    const actualLength = buffer.length - leadIndex;
+    if (actualLength < expectedLength) {
+        return buffer.subarray(0, leadIndex);
+    }
+    return buffer;
+}
+export function buildInlineTextPreview(params) {
+    const maxBytes = params.maxBytes ?? DEFAULT_INLINE_TEXT_PREVIEW_MAX_BYTES;
+    const truncated = params.fileBuffer.length > maxBytes;
+    const previewBuffer = truncated
+        ? params.fileBuffer.subarray(0, maxBytes)
+        : params.fileBuffer;
+    const previewText = trimIncompleteUtf8Suffix(previewBuffer).toString('utf8');
+    const suffix = truncated
+        ? `\n\n[truncated preview: showing first ${(maxBytes / 1024).toFixed(0)} KB of ${params.sizeLabel}; inspect locally for the full file.]`
+        : '';
+    return `Attachment ${params.attachmentId} (${params.mimeType}, ${params.sizeLabel}):\n\n${previewText}${suffix}`;
+}
+export { DEFAULT_INLINE_TEXT_PREVIEW_MAX_BYTES };

package/dist/workspaceFormats.d.ts

@@ -0,0 +1,7 @@
+import type { AgentWorkspaceFileResult, AgentWorkspaceListResult, AgentWorkspaceInspectResult } from '@bbigbang/protocol';
+export declare function formatWorkspaceInspectToolText(result: AgentWorkspaceInspectResult & {
+    reportText?: string | null;
+}): string;
+export declare function buildCompactWorkspaceInspectData(result: AgentWorkspaceInspectResult): Record<string, unknown>;
+export declare function formatWorkspaceTreeToolText(result: AgentWorkspaceListResult): string;
+export declare function formatWorkspaceFileToolText(result: AgentWorkspaceFileResult): string;

package/dist/workspaceFormats.js

@@ -0,0 +1,41 @@
+export function formatWorkspaceInspectToolText(result) {
+    if (result.reportText?.trim())
+        return result.reportText.trim();
+    const inspect = result.inspect;
+    return [
+        '[Workspace inspect]',
+        `node: ${result.nodeId ?? 'none'}`,
+        `workspace_root: ${result.workspaceRoot ?? 'none'}`,
+        `git: ${inspect?.isGit ? 'yes' : 'no'} | kind=${inspect?.workspaceKind ?? 'unknown'} | branch=${inspect?.branchName ?? 'none'}`,
+        inspect?.repoRoot ? `repo_root: ${inspect.repoRoot}` : null,
+        inspect?.remoteUrl ? `remote: ${inspect.remoteUrl}` : null,
+    ].filter(Boolean).join('\n');
+}
+export function buildCompactWorkspaceInspectData(result) {
+    return {
+        nodeId: result.nodeId ?? null,
+        workspaceRoot: result.workspaceRoot ?? null,
+        inspect: result.inspect ?? null,
+    };
+}
+export function formatWorkspaceTreeToolText(result) {
+    const prefix = result.path ? result.path : '.';
+    if (!result.entries.length)
+        return `[Workspace tree]\npath: ${prefix}\n(entries: empty)`;
+    const lines = result.entries.map((entry) => `- ${entry.path} [${entry.kind}]`);
+    return `[Workspace tree]\npath: ${prefix}\n${lines.join('\n')}`;
+}
+export function formatWorkspaceFileToolText(result) {
+    const fence = result.mimeType === 'text/markdown' ? 'markdown' : 'text';
+    return [
+        '[Workspace file]',
+        `path: ${result.path}`,
+        `mime: ${result.mimeType}`,
+        `size: ${result.size}`,
+        result.modifiedAt != null ? `modified_at: ${new Date(result.modifiedAt).toISOString()}` : null,
+        '',
+        `\`\`\`${fence}`,
+        result.content,
+        '\`\`\`',
+    ].filter((line) => line !== null).join('\n');
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@bbigbang/channel-bridge",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "channel-bridge": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "!dist/**/__tests__/**",
+    "!dist/**/*.test.*",
+    "!dist/**/*.map",
+    "package.json"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.3.6",
+    "@bbigbang/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "echo 'No lint configured'",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run"
+  }
+}