@bbigbang/core 0.1.0

package/dist/web/sharedCollaborationCapsules.js

@@ -0,0 +1,163 @@
+import { randomUUID } from 'node:crypto';
+import { createPromptContextSection } from './promptContextSections.js';
+export const SHARED_COLLABORATION_MAX_VISIBLE_AGENT_MESSAGES = 50;
+const ORIGIN_EXCERPT_MAX_CHARS = 480;
+function normalizeThreadKey(threadRootId) {
+    return threadRootId?.trim() ?? '';
+}
+function normalizeParticipantAgentIds(agentIds) {
+    return [...new Set(agentIds.map((agentId) => agentId.trim()).filter(Boolean))].sort();
+}
+function truncateOriginExcerpt(content) {
+    const normalized = content.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= ORIGIN_EXCERPT_MAX_CHARS)
+        return normalized;
+    return `${normalized.slice(0, ORIGIN_EXCERPT_MAX_CHARS - 15).trimEnd()} ... [truncated]`;
+}
+function parseParticipantAgentIds(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed)
+            ? normalizeParticipantAgentIds(parsed.filter((item) => typeof item === 'string'))
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function supersedeActiveSharedCollaborationCapsule(db, params) {
+    db.prepare(`UPDATE shared_collaboration_capsules
+        SET state = 'superseded',
+            superseded_at = ?,
+            superseded_by_message_id = ?,
+            superseded_by_seq = ?,
+            updated_at = ?
+      WHERE channel_id = ?
+        AND thread_root_id = ?
+        AND state = 'active'`).run(params.now, params.supersededByMessageId, params.supersededBySeq, params.now, params.channelId, normalizeThreadKey(params.threadRootId));
+}
+export function createSharedCollaborationCapsuleForUserMessage(db, params) {
+    const participantAgentIds = normalizeParticipantAgentIds(params.participantAgentIds);
+    if (participantAgentIds.length < 2)
+        return null;
+    const capsuleId = randomUUID();
+    const threadRootId = normalizeThreadKey(params.threadRootId);
+    const maxVisibleAgentMessages = Math.max(1, Math.floor(params.maxVisibleAgentMessages ?? SHARED_COLLABORATION_MAX_VISIBLE_AGENT_MESSAGES));
+    const originContentExcerpt = truncateOriginExcerpt(params.originContent);
+    db.prepare(`INSERT INTO shared_collaboration_capsules(
+       capsule_id, channel_id, thread_root_id, origin_message_id, origin_seq,
+       origin_content_excerpt, participant_agent_ids_json, state,
+       max_visible_agent_messages, created_at, updated_at
+     )
+     VALUES(?, ?, ?, ?, ?, ?, ?, 'active', ?, ?, ?)`).run(capsuleId, params.channelId, threadRootId, params.originMessageId, params.originSeq, originContentExcerpt, JSON.stringify(participantAgentIds), maxVisibleAgentMessages, params.now, params.now);
+    return {
+        capsuleId,
+        channelId: params.channelId,
+        threadRootId,
+        originMessageId: params.originMessageId,
+        originSeq: params.originSeq,
+        originContentExcerpt,
+        participantAgentIds,
+        state: 'active',
+        contributionCount: 0,
+        maxVisibleAgentMessages,
+    };
+}
+export function recordUserMessageSharedCollaborationCapsule(db, params) {
+    return db.transaction(() => {
+        supersedeActiveSharedCollaborationCapsule(db, {
+            channelId: params.channelId,
+            threadRootId: params.threadRootId,
+            supersededByMessageId: params.messageId,
+            supersededBySeq: params.seq,
+            now: params.now,
+        });
+        return createSharedCollaborationCapsuleForUserMessage(db, {
+            channelId: params.channelId,
+            threadRootId: params.threadRootId,
+            originMessageId: params.messageId,
+            originSeq: params.seq,
+            originContent: params.content,
+            participantAgentIds: params.mentionedAgentIds,
+            now: params.now,
+        });
+    })();
+}
+function countVisibleAgentContributions(db, capsule) {
+    if (capsule.participantAgentIds.length === 0)
+        return 0;
+    const placeholders = capsule.participantAgentIds.map(() => '?').join(', ');
+    const row = db.prepare(`SELECT COUNT(*) as count
+       FROM channel_messages
+      WHERE channel_id = ?
+        AND COALESCE(thread_root_id, '') = ?
+        AND seq > ?
+        AND sender_type = 'agent'
+        AND sender_id IN (${placeholders})
+        AND (message_kind IS NULL OR message_kind <> 'system_hidden')`).get(capsule.channelId, capsule.threadRootId, capsule.originSeq, ...capsule.participantAgentIds);
+    return Math.max(0, Math.floor(row?.count ?? 0));
+}
+export function loadActiveSharedCollaborationCapsuleForPeerUpdate(db, params) {
+    const threadRootId = normalizeThreadKey(params.threadRootId);
+    const row = db.prepare(`SELECT capsule_id as capsuleId,
+            channel_id as channelId,
+            thread_root_id as threadRootId,
+            origin_message_id as originMessageId,
+            origin_seq as originSeq,
+            origin_content_excerpt as originContentExcerpt,
+            participant_agent_ids_json as participantAgentIdsJson,
+            max_visible_agent_messages as maxVisibleAgentMessages
+       FROM shared_collaboration_capsules
+      WHERE channel_id = ?
+        AND thread_root_id = ?
+        AND state = 'active'
+      LIMIT 1`).get(params.channelId, threadRootId);
+    if (!row)
+        return null;
+    const participantAgentIds = parseParticipantAgentIds(row.participantAgentIdsJson);
+    if (!participantAgentIds.includes(params.targetAgentId))
+        return null;
+    const contributionCount = countVisibleAgentContributions(db, {
+        channelId: row.channelId,
+        threadRootId: row.threadRootId,
+        originSeq: row.originSeq,
+        participantAgentIds,
+    });
+    const maxVisibleAgentMessages = Math.max(1, Math.floor(row.maxVisibleAgentMessages));
+    if (contributionCount >= maxVisibleAgentMessages) {
+        db.prepare(`UPDATE shared_collaboration_capsules
+          SET state = 'capped',
+              updated_at = ?
+        WHERE capsule_id = ?
+          AND state = 'active'`).run(params.now, row.capsuleId);
+        return null;
+    }
+    return {
+        capsuleId: row.capsuleId,
+        channelId: row.channelId,
+        threadRootId: row.threadRootId,
+        originMessageId: row.originMessageId,
+        originSeq: row.originSeq,
+        originContentExcerpt: row.originContentExcerpt,
+        participantAgentIds,
+        state: 'active',
+        contributionCount,
+        maxVisibleAgentMessages,
+    };
+}
+export function buildSharedCollaborationCapsuleSection(params) {
+    const participantLine = params.participantNames.length > 0
+        ? params.participantNames.map((name) => `@${name}`).join(', ')
+        : params.capsule.participantAgentIds.join(', ');
+    const includeRoot = params.includeRootHint === true ? ', include_root=true' : '';
+    return createPromptContextSection('shared_collaboration_capsule', [
+        '[Shared collaboration capsule]',
+        `capsule: ${params.capsule.capsuleId}`,
+        `origin: seq=${params.capsule.originSeq} msg=${params.capsule.originMessageId}`,
+        `participants: ${participantLine}`,
+        `visible_agent_contributions: ${params.capsule.contributionCount}/${params.capsule.maxVisibleAgentMessages}`,
+        'original_request_excerpt:',
+        params.capsule.originContentExcerpt,
+        `Full origin/request context: bigbang message read --channel "${params.replyTarget}" --around "${params.capsule.originMessageId}" --limit 20${includeRoot ? ' --include-root' : ''}`,
+    ].join('\n'));
+}

package/dist/web/soloSessionRelay.js

@@ -0,0 +1,42 @@
+export class SoloSessionRelay {
+    clientsBySessionId = new Map();
+    registerClient(soloSessionId, agentId, socket) {
+        const existing = this.clientsBySessionId.get(soloSessionId);
+        if (existing) {
+            if (existing.socket !== socket)
+                return 'collision';
+            if (existing.agentId !== agentId)
+                return 'agent_mismatch';
+            return 'ok';
+        }
+        this.clientsBySessionId.set(soloSessionId, { agentId, socket });
+        return 'ok';
+    }
+    unregisterClient(soloSessionId) {
+        this.clientsBySessionId.delete(soloSessionId);
+    }
+    getAgentId(soloSessionId) {
+        return this.clientsBySessionId.get(soloSessionId)?.agentId ?? null;
+    }
+    relayNodeMessage(msg) {
+        if (msg.type !== 'solo.run.event'
+            && msg.type !== 'solo.run.end'
+            && msg.type !== 'solo.permission.request') {
+            return false;
+        }
+        const binding = this.clientsBySessionId.get(msg.soloSessionId);
+        if (!binding || binding.socket.readyState !== 1) {
+            return false;
+        }
+        binding.socket.send(JSON.stringify(msg));
+        return true;
+    }
+    sendToClient(soloSessionId, msg) {
+        const binding = this.clientsBySessionId.get(soloSessionId);
+        if (!binding || binding.socket.readyState !== 1) {
+            return false;
+        }
+        binding.socket.send(JSON.stringify(msg));
+        return true;
+    }
+}

package/dist/web/soloWsHandler.js

@@ -0,0 +1,138 @@
+import { randomUUID } from 'node:crypto';
+import { buildSoloSystemPrompt } from '@bbigbang/memory';
+export function handleSoloWebSocket(socket, agent, nodeRegistry, soloRelay) {
+    const agentId = agent.agentId;
+    const nodeId = agent.nodeId?.trim();
+    if (!nodeId) {
+        socket.send(JSON.stringify({ type: 'error', message: 'Agent has no connected node.' }));
+        socket.close();
+        return;
+    }
+    const connectedSessions = new Set();
+    const sendError = (message) => {
+        if (socket.readyState === 1) {
+            socket.send(JSON.stringify({ type: 'error', message }));
+        }
+    };
+    const forwardToNode = (msg) => {
+        const sent = nodeRegistry.send(nodeId, msg);
+        if (!sent) {
+            sendError('Agent node is not connected.');
+        }
+        return sent;
+    };
+    socket.on('message', (raw) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(String(raw));
+        }
+        catch {
+            sendError('Invalid message payload.');
+            return;
+        }
+        const soloSessionId = parsed.soloSessionId?.trim();
+        if (!soloSessionId) {
+            sendError('soloSessionId is required.');
+            return;
+        }
+        if (!connectedSessions.has(soloSessionId)) {
+            const registered = soloRelay.registerClient(soloSessionId, agentId, socket);
+            if (registered === 'collision') {
+                sendError('soloSessionId is already bound to another client.');
+                return;
+            }
+            if (registered === 'agent_mismatch') {
+                sendError('soloSessionId is already bound to a different agent.');
+                return;
+            }
+            connectedSessions.add(soloSessionId);
+        }
+        switch (parsed.type) {
+            case 'solo.prompt': {
+                const text = parsed.text?.trim();
+                if (!text) {
+                    sendError('Prompt text is required.');
+                    return;
+                }
+                if (agent.agentType !== 'codex_app_server') {
+                    sendError('Solo mode is only supported for codex_app_server agents.');
+                    return;
+                }
+                const workspacePath = agent.workspacePath?.trim();
+                if (!workspacePath) {
+                    sendError('Agent workspace is not configured.');
+                    return;
+                }
+                const dispatch = {
+                    type: 'solo.run.dispatch',
+                    soloSessionId,
+                    agentId,
+                    agentType: agent.agentType,
+                    workspacePath,
+                    agentName: agent.name,
+                    model: agent.model,
+                    reasoningEffort: agent.reasoningEffort,
+                    codexMode: agent.codexMode,
+                    codexServiceTier: agent.codexServiceTier,
+                    envVars: agent.envVars,
+                    disabledToolKinds: agent.disabledToolKinds,
+                    prompt: text,
+                    systemPromptText: buildSoloSystemPrompt({
+                        name: agent.name,
+                        bio: agent.description,
+                        description: agent.systemPrompt,
+                        workspacePath,
+                    }),
+                };
+                forwardToNode(dispatch);
+                break;
+            }
+            case 'solo.cancel':
+                forwardToNode({ type: 'solo.cancel', soloSessionId });
+                break;
+            case 'solo.steer': {
+                const steerText = parsed.text?.trim();
+                if (!steerText) {
+                    sendError('Steer text is required.');
+                    return;
+                }
+                forwardToNode({ type: 'solo.steer', soloSessionId, prompt: steerText });
+                break;
+            }
+            case 'solo.approval.response': {
+                if (!parsed.requestId?.trim() || !parsed.decision) {
+                    sendError('requestId and decision are required.');
+                    return;
+                }
+                forwardToNode({
+                    type: 'solo.permission.response',
+                    soloSessionId,
+                    requestId: parsed.requestId,
+                    decision: parsed.decision,
+                    selectedActionId: parsed.selectedActionId,
+                    responseText: parsed.responseText,
+                    answers: parsed.answers,
+                });
+                break;
+            }
+            default:
+                sendError('Unsupported solo message type.');
+        }
+    });
+    socket.on('error', (error) => {
+        // The close handler owns cleanup; this log keeps socket-level failures visible.
+        console.warn('[solo-ws] socket error', error);
+    });
+    socket.on('close', () => {
+        for (const soloSessionId of connectedSessions) {
+            soloRelay.unregisterClient(soloSessionId);
+            if (nodeId) {
+                nodeRegistry.send(nodeId, { type: 'solo.close', soloSessionId });
+            }
+        }
+        connectedSessions.clear();
+    });
+}
+export function createSoloSessionId() {
+    return randomUUID();
+}

package/dist/web/suggestedPlannerScheduler.js

@@ -0,0 +1,56 @@
+import { getSuggestedPlannerTerminalError, } from '../services/suggestedPlannerService.js';
+export const SUGGESTED_PLANNER_POLL_INTERVAL_MS = 60_000;
+export function startSuggestedPlannerScheduler(params) {
+    const intervalMs = Math.max(5_000, params.intervalMs ?? SUGGESTED_PLANNER_POLL_INTERVAL_MS);
+    let closed = false;
+    let running = false;
+    let timer = null;
+    const tick = async () => {
+        if (closed || running)
+            return;
+        running = true;
+        try {
+            const now = Date.now();
+            for (const config of params.suggestedPlannerService.listDueConfigs(now)) {
+                const username = params.suggestedPlannerService.getUsernameForUserId(config.userId);
+                if (!username)
+                    continue;
+                const runningPlan = params.db.prepare(`SELECT run_id as runId FROM suggested_planner_runs
+           WHERE user_id = ? AND status = 'running' LIMIT 1`).get(config.userId);
+                if (runningPlan)
+                    continue;
+                await params.suggestedPlannerService.dispatchPlanRun({
+                    userId: config.userId,
+                    username,
+                });
+            }
+        }
+        finally {
+            running = false;
+        }
+    };
+    timer = setInterval(() => {
+        void tick();
+    }, intervalMs);
+    timer.unref?.();
+    return {
+        tick,
+        stop: () => {
+            closed = true;
+            if (!timer)
+                return;
+            clearInterval(timer);
+            timer = null;
+        },
+    };
+}
+export async function handleSuggestedPlannerRunFinished(params) {
+    const row = params.db.prepare(`SELECT user_id as userId FROM suggested_planner_runs WHERE run_id = ? AND status = 'running'`).get(params.runId);
+    if (!row)
+        return;
+    await params.suggestedPlannerService.finalizePlanRun({
+        runId: params.runId,
+        userId: row.userId,
+        error: getSuggestedPlannerTerminalError(params.stopReason, params.error),
+    });
+}

package/dist/web/surfaceActivationPolicy.js

@@ -0,0 +1,108 @@
+import { isThreadTarget, resolveChannelTaskBoardPresencePolicy, resolveDirectTaskThreadPresencePolicy, } from './workspaceMemoryHints.js';
+const STRONG_SIGNAL_ORDER = [
+    'open_handoff',
+    'handoff_required',
+    'bound_task_match',
+    'task_thread',
+    'explicit_handoff_target',
+    'active_dm_task_thread_linkage',
+    'handoff_recovery_bootstrap',
+];
+const RELEVANT_CONTEXT_REASON_SIGNAL_MAP = {
+    active_handoff: 'open_handoff',
+    current_conversation_handoff: 'open_handoff',
+    bound_task_match: 'bound_task_match',
+};
+export function historyLimitForSurfaceActivationTier(tier) {
+    switch (tier) {
+        case 'L1':
+            return 0;
+        case 'L2-lite':
+            return 2;
+        case 'L2':
+            return 2;
+        case 'L2-task':
+        case 'L3':
+            return 4;
+        default:
+            return 0;
+    }
+}
+export function collectSurfaceActivationStrongSignals(flags) {
+    if (!flags)
+        return [];
+    return STRONG_SIGNAL_ORDER.filter((signal) => flags[signal]);
+}
+export function extractRelevantContextStrongSignals(bundle) {
+    const top = bundle?.items[0];
+    if (!top)
+        return [];
+    const flags = {};
+    for (const reason of top.reasons) {
+        const signal = RELEVANT_CONTEXT_REASON_SIGNAL_MAP[reason.code];
+        if (signal)
+            flags[signal] = true;
+    }
+    return collectSurfaceActivationStrongSignals(flags);
+}
+export function shouldPreinjectRelevantContextHint(params) {
+    return !isThreadTarget(params.target) && params.strongSignals.length > 0;
+}
+export function resolveChannelSurfaceActivationPolicy(params) {
+    const threadSurface = isThreadTarget(params.target);
+    const strongSignals = collectSurfaceActivationStrongSignals({
+        ...params.strongSignalFlags,
+        bound_task_match: params.hasBoundTask ?? false,
+        task_thread: Boolean(params.hasBoundTask && threadSurface),
+    });
+    const activationTier = threadSurface
+        ? (params.hasBoundTask ? 'L2-task' : 'L2')
+        : (strongSignals.length > 0 ? 'L2-lite' : 'L1');
+    const resumeTier = threadSurface ? activationTier : 'L2-lite';
+    return {
+        surfaceKind: 'channel',
+        activationTier,
+        resumeTier,
+        strongSignals,
+        taskBoardPresence: resolveChannelTaskBoardPresencePolicy({
+            target: params.target,
+            hasBoundTask: params.hasBoundTask,
+            includeOpenTasks: params.includeOpenTasks,
+        }),
+        includeParticipantsByDefault: params.hasBoundTask
+            ? true
+            : threadSurface
+                ? true
+                : params.reason === 'agent_mention'
+                    || (params.reason === 'channel_activity' && (params.participantsCount ?? 0) > 0)
+                    || (params.participantsCount ?? 0) > 1,
+        includeOpenTasksByDefault: Boolean(params.includeOpenTasks),
+        optionalPayloadTiers: params.includeOpenTasks ? ['L3'] : [],
+    };
+}
+export function resolveDirectSurfaceActivationPolicy(params) {
+    const threadSurface = isThreadTarget(params.target);
+    const strongSignals = collectSurfaceActivationStrongSignals(params.strongSignalFlags);
+    const activationTier = threadSurface
+        ? 'L2'
+        : (strongSignals.length > 0 ? 'L2-lite' : 'L1');
+    const resumeTier = threadSurface ? 'L2' : 'L2-lite';
+    const optionalPayloadTiers = [];
+    if (params.includeDmActiveTaskThreads)
+        optionalPayloadTiers.push('L3');
+    if (params.promptIncludeDmContextSnapshot || params.includeDmContextSnapshot)
+        optionalPayloadTiers.push('L3');
+    return {
+        surfaceKind: 'direct',
+        activationTier,
+        resumeTier,
+        strongSignals,
+        dmTaskThreadPresence: resolveDirectTaskThreadPresencePolicy({
+            target: params.target,
+            includeDmActiveTaskThreads: params.includeDmActiveTaskThreads,
+        }),
+        includeDmSnapshotByDefault: Boolean(params.includeDmContextSnapshot),
+        promptIncludeDmSnapshotByDefault: Boolean(params.promptIncludeDmContextSnapshot ?? params.includeDmContextSnapshot),
+        optionalPayloadTiers: Array.from(new Set(optionalPayloadTiers)),
+    };
+}

package/dist/web/surfaceCollaborators.js

@@ -0,0 +1,61 @@
+export function ensureSurfaceOwner(db, params) {
+    upsertSurfaceCollaborator(db, {
+        ...params,
+        role: 'owner',
+    });
+}
+export function upsertSurfaceCollaborator(db, params) {
+    const now = params.createdAt ?? Date.now();
+    db.prepare(`INSERT INTO surface_collaborators(
+       surface_type,
+       surface_id,
+       agent_id,
+       role,
+       added_by,
+       created_at
+     )
+     VALUES(?, ?, ?, ?, ?, ?)
+     ON CONFLICT(surface_type, surface_id, agent_id)
+     DO UPDATE SET
+       role = CASE
+         WHEN surface_collaborators.role = 'owner' THEN 'owner'
+         ELSE excluded.role
+       END,
+       added_by = COALESCE(surface_collaborators.added_by, excluded.added_by)`).run(params.surfaceType, params.surfaceId, params.agentId, params.role, params.addedBy ?? null, now);
+}
+export function getSurfaceCollaboratorRole(db, surfaceType, surfaceId, agentId) {
+    const row = db.prepare(`SELECT role
+       FROM surface_collaborators
+      WHERE surface_type = ?
+        AND surface_id = ?
+        AND agent_id = ?
+      LIMIT 1`).get(surfaceType, surfaceId, agentId);
+    return row?.role ?? null;
+}
+export function isSurfaceCollaborator(db, surfaceType, surfaceId, agentId) {
+    return getSurfaceCollaboratorRole(db, surfaceType, surfaceId, agentId) !== null;
+}
+export function isSurfaceOwner(db, surfaceType, surfaceId, agentId) {
+    return getSurfaceCollaboratorRole(db, surfaceType, surfaceId, agentId) === 'owner';
+}
+export function listSurfaceCollaborators(db, surfaceType, surfaceId) {
+    const rows = db.prepare(`SELECT surface_type as surfaceType,
+            surface_id as surfaceId,
+            agent_id as agentId,
+            role,
+            added_by as addedBy,
+            created_at as createdAt
+       FROM surface_collaborators
+      WHERE surface_type = ?
+        AND surface_id = ?
+      ORDER BY CASE role WHEN 'owner' THEN 0 ELSE 1 END, created_at ASC, agent_id ASC`).all(surfaceType, surfaceId);
+    return rows;
+}
+export function removeSurfaceCollaborator(db, surfaceType, surfaceId, agentId) {
+    const result = db.prepare(`DELETE FROM surface_collaborators
+      WHERE surface_type = ?
+        AND surface_id = ?
+        AND agent_id = ?
+        AND role != 'owner'`).run(surfaceType, surfaceId, agentId);
+    return result.changes > 0;
+}