@soulcraft/sdk 1.6.2 → 2.0.0

package/dist/server/handlers/chat/conversations.js

@@ -0,0 +1,314 @@
+/**
+ * @module server/handlers/chat/conversations
+ * @description Conversation and message CRUD operations using Brainy entities.
+ *
+ * Conversations are stored as `collection` entities with `_aiDataType: 'conversation'`.
+ * Messages are `message` entities linked to conversations via `contains` edges.
+ * Temporal ordering uses `precedes` edges between consecutive messages.
+ *
+ * All operations are universal — Workshop, Venue, Academy, and Pulse share
+ * the same conversation storage model.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+/** Metadata field used to identify AI-managed conversation entities. */
+const AI_DATA_TYPE = '_aiDataType';
+// ─────────────────────────────────────────────────────────────────────────────
+// Conversation CRUD
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create a new conversation entity.
+ *
+ * @param brain - Brainy instance.
+ * @param userId - User who owns the conversation.
+ * @param title - Optional initial title.
+ * @returns The conversation ID.
+ */
+export async function createConversation(brain, userId, title) {
+    const conversationId = await brain.add({
+        type: 'collection',
+        data: {
+            title: title || 'New Conversation',
+            userId,
+            startedAt: new Date().toISOString(),
+        },
+        metadata: {
+            name: title || 'New Conversation',
+            isAIManaged: true,
+            [AI_DATA_TYPE]: 'conversation',
+            conversationType: 'chat',
+            active: true,
+        },
+    });
+    return conversationId;
+}
+/**
+ * List all conversations for a user.
+ *
+ * @param brain - Brainy instance.
+ * @param userId - User to list conversations for.
+ * @returns Array of conversation summaries sorted by most recent first.
+ */
+export async function listConversations(brain, userId) {
+    const entities = await brain.find({
+        where: { [AI_DATA_TYPE]: { equals: 'conversation' } },
+        limit: 200,
+    });
+    // Filter to this user's active conversations
+    const userConversations = entities.filter((e) => {
+        const data = e.data || {};
+        const meta = e.metadata || {};
+        return data.userId === userId && meta.active !== false;
+    });
+    // Build conversation summaries with message counts
+    const conversations = await Promise.all(userConversations.map(async (entity) => {
+        const rels = await brain.getRelations({ from: entity.id });
+        const messageRels = rels.filter((r) => r.type === 'contains' || r.verb === 'contains');
+        // Get latest message timestamp
+        let updatedAt = entity.data?.startedAt || new Date().toISOString();
+        if (messageRels.length > 0) {
+            const lastRel = messageRels[messageRels.length - 1];
+            try {
+                const lastMsg = await brain.get(lastRel.to);
+                if (lastMsg?.data?.timestamp) {
+                    updatedAt = lastMsg.data.timestamp;
+                }
+            }
+            catch { /* message may not exist */ }
+        }
+        return {
+            id: entity.id,
+            title: entity.data?.title || 'Untitled Conversation',
+            createdAt: entity.data?.startedAt || new Date().toISOString(),
+            updatedAt,
+            messageCount: messageRels.length,
+        };
+    }));
+    // Sort by most recent first
+    conversations.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+    return conversations;
+}
+/**
+ * Get a conversation with its full message history.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to retrieve.
+ * @returns Full conversation with messages, or null if not found.
+ */
+export async function getConversation(brain, conversationId) {
+    const entity = await brain.get(conversationId);
+    if (!entity)
+        return null;
+    const meta = entity.metadata || {};
+    if (meta[AI_DATA_TYPE] !== 'conversation')
+        return null;
+    // Load all messages
+    const rels = await brain.getRelations({ from: conversationId });
+    const messageRels = rels.filter((r) => r.type === 'contains' || r.verb === 'contains');
+    const messages = [];
+    for (const rel of messageRels) {
+        try {
+            const msg = await brain.get(rel.to);
+            if (msg?.data?.role && msg?.data?.content) {
+                messages.push({
+                    role: msg.data.role,
+                    content: msg.data.content,
+                    timestamp: msg.data.timestamp || '',
+                    ...(msg.data.model ? { model: msg.data.model } : {}),
+                });
+            }
+        }
+        catch { /* skip missing messages */ }
+    }
+    // Sort by timestamp
+    messages.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    return {
+        id: entity.id,
+        title: entity.data?.title || 'Untitled Conversation',
+        createdAt: entity.data?.startedAt || new Date().toISOString(),
+        updatedAt: messages.length > 0
+            ? messages[messages.length - 1].timestamp
+            : entity.data?.startedAt || new Date().toISOString(),
+        messageCount: messages.length,
+        messages,
+    };
+}
+/**
+ * Delete a conversation and all its messages (soft delete).
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to delete.
+ */
+export async function deleteConversation(brain, conversationId) {
+    const entity = await brain.get(conversationId);
+    if (!entity)
+        return;
+    // Soft delete: mark inactive
+    await brain.update({
+        id: conversationId,
+        metadata: { ...entity.metadata, active: false },
+    });
+}
+/**
+ * Rename a conversation.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to rename.
+ * @param title - New title.
+ */
+export async function renameConversation(brain, conversationId, title) {
+    const entity = await brain.get(conversationId);
+    if (!entity)
+        throw new Error('Conversation not found');
+    await brain.update({
+        id: conversationId,
+        data: { ...entity.data, title },
+        metadata: { ...entity.metadata, name: title },
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Message Storage
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Store a message in a conversation.
+ *
+ * Creates the message entity, links it to the conversation via `contains`,
+ * and establishes temporal ordering via `precedes`.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to add the message to.
+ * @param role - Message role ('user' or 'assistant').
+ * @param content - Message text content.
+ * @param events - Optional event emitter for real-time updates.
+ * @returns The message entity ID.
+ */
+export async function storeMessage(brain, conversationId, role, content, events) {
+    // Ensure conversation exists
+    const conversationExists = await brain.get(conversationId);
+    if (!conversationExists) {
+        await brain.add({
+            id: conversationId,
+            type: 'collection',
+            data: {
+                title: 'Chat Conversation',
+                startedAt: new Date().toISOString(),
+            },
+            metadata: {
+                name: 'Chat Conversation',
+                isAIManaged: true,
+                [AI_DATA_TYPE]: 'conversation',
+                conversationType: 'chat',
+                active: true,
+            },
+        });
+    }
+    const preview = content.length > 50 ? content.slice(0, 50) + '...' : content;
+    const messageId = await brain.add({
+        type: 'message',
+        data: {
+            role,
+            content,
+            timestamp: new Date().toISOString(),
+        },
+        metadata: {
+            name: preview,
+            isAIManaged: true,
+            [AI_DATA_TYPE]: 'message',
+            conversationId,
+            wordCount: content.split(' ').length,
+            charCount: content.length,
+            messageType: role === 'user' ? 'question' : 'response',
+        },
+    });
+    // Link message → conversation
+    await brain.relate({
+        from: conversationId,
+        to: messageId,
+        type: 'contains',
+    });
+    // Temporal ordering: link to previous message via `precedes`
+    const previousRels = await brain.getRelations({ from: conversationId });
+    const messageRels = previousRels.filter((r) => (r.type === 'contains' || r.verb === 'contains') && r.to !== messageId);
+    if (messageRels.length > 0) {
+        const lastMessageRel = messageRels[messageRels.length - 1];
+        await brain.relate({
+            from: lastMessageRel.to,
+            to: messageId,
+            type: 'precedes',
+        }).catch(() => { });
+        // If assistant response, link as describing the user's question
+        if (role === 'assistant') {
+            await brain.relate({
+                from: messageId,
+                to: lastMessageRel.to,
+                type: 'describes',
+            }).catch(() => { });
+        }
+    }
+    // Emit activity event
+    events?.emit('activity_message_new', {
+        id: messageId,
+        activityType: role === 'user' ? 'user_message' : 'assistant_message',
+        title: role === 'user' ? 'User message' : 'Assistant response',
+        preview: content.substring(0, 300),
+        conversationId,
+    });
+    return messageId;
+}
+/**
+ * Load conversation history — recent messages in chronological order.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to load.
+ * @param limit - Maximum messages to return (most recent).
+ * @returns Array of role/content pairs.
+ */
+export async function loadConversationHistory(brain, conversationId, limit = 20) {
+    const rels = await brain.getRelations({ from: conversationId });
+    const containsRels = rels.filter((r) => r.type === 'contains' || r.verb === 'contains');
+    const messages = await Promise.all(containsRels.slice(-limit).map(async (rel) => {
+        try {
+            const msg = await brain.get(rel.to);
+            return {
+                role: msg?.data?.role || 'user',
+                content: msg?.data?.content || '',
+                timestamp: msg?.data?.timestamp || '',
+            };
+        }
+        catch {
+            return null;
+        }
+    }));
+    return messages
+        .filter((m) => m !== null && m.content !== '')
+        .sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime())
+        .map(({ role, content }) => ({ role, content }));
+}
+/**
+ * Auto-title a conversation from the first user message.
+ *
+ * Fire-and-forget — errors are logged but don't propagate.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to title.
+ * @param message - The first user message.
+ */
+export async function autoTitleConversation(brain, conversationId, message) {
+    try {
+        const entity = await brain.get(conversationId);
+        const genericTitles = ['New Conversation', 'Chat Conversation'];
+        if (entity && genericTitles.includes(entity.data?.title) && message.length > 0) {
+            const autoTitle = message.substring(0, 50) + (message.length > 50 ? '...' : '');
+            await brain.update({
+                id: conversationId,
+                data: { ...entity.data, title: autoTitle },
+                metadata: { ...entity.metadata, name: autoTitle },
+            });
+        }
+    }
+    catch {
+        // Non-fatal — auto-titling is best-effort
+    }
+}
+//# sourceMappingURL=conversations.js.map

package/dist/server/handlers/chat/conversations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversations.js","sourceRoot":"","sources":["../../../../src/server/handlers/chat/conversations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF,wEAAwE;AACxE,MAAM,YAAY,GAAG,aAAa,CAAA;AAElC,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAa,EACb,MAAc,EACd,KAAc;IAEd,MAAM,cAAc,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC;QACrC,IAAI,EAAE,YAAmB;QACzB,IAAI,EAAE;YACJ,KAAK,EAAE,KAAK,IAAI,kBAAkB;YAClC,MAAM;YACN,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC;QACD,QAAQ,EAAE;YACR,IAAI,EAAE,KAAK,IAAI,kBAAkB;YACjC,WAAW,EAAE,IAAI;YACjB,CAAC,YAAY,CAAC,EAAE,cAAc;YAC9B,gBAAgB,EAAE,MAAM;YACxB,MAAM,EAAE,IAAI;SACb;KACF,CAAC,CAAA;IAEF,OAAO,cAAc,CAAA;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAa,EACb,MAAc;IAEd,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC;QAChC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,EAAE;QACrD,KAAK,EAAE,GAAG;KACJ,CAAC,CAAA;IAET,6CAA6C;IAC7C,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE;QACnD,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,EAAE,CAAA;QACzB,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAA;QAC7B,OAAO,IAAI,CAAC,MAAM,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK,CAAA;IACxD,CAAC,CAAC,CAAA;IAEF,mDAAmD;IACnD,MAAM,aAAa,GAAuB,MAAM,OAAO,CAAC,GAAG,CACzD,iBAAiB,CAAC,GAAG,CAAC,KAAK,EAAE,MAAW,EAAE,EAAE;QAC1C,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAA;QAC1D,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CACzC,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,CAC/C,CAAA;QAED,+BAA+B;QAC/B,IAAI,SAAS,GAAG,MAAM,CAAC,IAAI,EAAE,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;QAClE,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,WAAW,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAE,CAAA;YACpD,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;gBAC3C,IAAI,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;oBAC7B,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,CAAA;gBACpC,CAAC;YACH,CAAC;YAAC,MAAM,CAAC,CAAC,2BAA2B,CAAC,CAAC;QACzC,CAAC;QAED,OAAO;YACL,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,IAAI,uBAAuB;YACpD,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC7D,SAAS;YACT,YAAY,EAAE,WAAW,CAAC,MAAM;SACjC,CAAA;IACH,CAAC,CAAC,CACH,CAAA;IAED,4BAA4B;IAC5B,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAC1B,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAClE,CAAA;IAED,OAAO,aAAa,CAAA;AACtB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAa,EACb,cAAsB;IAEtB,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;IAC9C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IAExB,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAA;IAClC,IAAI,IAAI,CAAC,YAAY,CAAC,KAAK,cAAc;QAAE,OAAO,IAAI,CAAA;IAEtD,oBAAoB;IACpB,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAA;IAC/D,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CACzC,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,CAC/C,CAAA;IAED,MAAM,QAAQ,GAAkB,EAAE,CAAA;IAClC,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YACnC,IAAI,GAAG,EAAE,IAAI,EAAE,IAAI,IAAI,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;gBAC1C,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI;oBACnB,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO;oBACzB,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE;oBACnC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACrD,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,2BAA2B,CAAC,CAAC;IACzC,CAAC;IAED,oBAAoB;IACpB,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACrB,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAClE,CAAA;IAED,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,IAAI,uBAAuB;QACpD,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC7D,SAAS,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC;YAC5B,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,SAAS;YAC1C,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtD,YAAY,EAAE,QAAQ,CAAC,MAAM;QAC7B,QAAQ;KACT,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAa,EACb,cAAsB;IAEtB,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;IAC9C,IAAI,CAAC,MAAM;QAAE,OAAM;IAEnB,6BAA6B;IAC7B,MAAM,KAAK,CAAC,MAAM,CAAC;QACjB,EAAE,EAAE,cAAc;QAClB,QAAQ,EAAE,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE;KAChD,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAa,EACb,cAAsB,EACtB,KAAa;IAEb,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;IAC9C,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAA;IAEtD,MAAM,KAAK,CAAC,MAAM,CAAC;QACjB,EAAE,EAAE,cAAc;QAClB,IAAI,EAAE,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;QAC/B,QAAQ,EAAE,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE;KAC9C,CAAC,CAAA;AACJ,CAAC;AAED,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,cAAsB,EACtB,IAA0B,EAC1B,OAAe,EACf,MAAyB;IAEzB,6BAA6B;IAC7B,MAAM,kBAAkB,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;IAC1D,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxB,MAAM,KAAK,CAAC,GAAG,CAAC;YACd,EAAE,EAAE,cAAc;YAClB,IAAI,EAAE,YAAmB;YACzB,IAAI,EAAE;gBACJ,KAAK,EAAE,mBAAmB;gBAC1B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC;YACD,QAAQ,EAAE;gBACR,IAAI,EAAE,mBAAmB;gBACzB,WAAW,EAAE,IAAI;gBACjB,CAAC,YAAY,CAAC,EAAE,cAAc;gBAC9B,gBAAgB,EAAE,MAAM;gBACxB,MAAM,EAAE,IAAI;aACb;SACF,CAAC,CAAA;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,OAAO,CAAA;IAE5E,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC;QAChC,IAAI,EAAE,SAAgB;QACtB,IAAI,EAAE;YACJ,IAAI;YACJ,OAAO;YACP,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC;QACD,QAAQ,EAAE;YACR,IAAI,EAAE,OAAO;YACb,WAAW,EAAE,IAAI;YACjB,CAAC,YAAY,CAAC,EAAE,SAAS;YACzB,cAAc;YACd,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM;YACpC,SAAS,EAAE,OAAO,CAAC,MAAM;YACzB,WAAW,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU;SACvD;KACF,CAAC,CAAA;IAEF,8BAA8B;IAC9B,MAAM,KAAK,CAAC,MAAM,CAAC;QACjB,IAAI,EAAE,cAAc;QACpB,EAAE,EAAE,SAAS;QACb,IAAI,EAAE,UAAiB;KACxB,CAAC,CAAA;IAEF,6DAA6D;IAC7D,MAAM,YAAY,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAA;IACvE,MAAM,WAAW,GAAG,YAAY,CAAC,MAAM,CACrC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,SAAS,CACnF,CAAA;IAED,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,cAAc,GAAG,WAAW,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAE,CAAA;QAC3D,MAAM,KAAK,CAAC,MAAM,CAAC;YACjB,IAAI,EAAE,cAAc,CAAC,EAAE;YACvB,EAAE,EAAE,SAAS;YACb,IAAI,EAAE,UAAiB;SACxB,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAmB,CAAC,CAAC,CAAA;QAEnC,gEAAgE;QAChE,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;YACzB,MAAM,KAAK,CAAC,MAAM,CAAC;gBACjB,IAAI,EAAE,SAAS;gBACf,EAAE,EAAE,cAAc,CAAC,EAAE;gBACrB,IAAI,EAAE,WAAkB;aACzB,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAmB,CAAC,CAAC,CAAA;QACrC,CAAC;IACH,CAAC;IAED,sBAAsB;IACtB,MAAM,EAAE,IAAI,CAAC,sBAAsB,EAAE;QACnC,EAAE,EAAE,SAAS;QACb,YAAY,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,mBAAmB;QACpE,KAAK,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,oBAAoB;QAC9D,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC;QAClC,cAAc;KACf,CAAC,CAAA;IAEF,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,KAAa,EACb,cAAsB,EACtB,QAAgB,EAAE;IAElB,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAA;IAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAC9B,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,CAC3D,CAAA;IAED,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAChC,YAAY,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,GAAQ,EAAE,EAAE;QAChD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YACnC,OAAO;gBACL,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,IAAI,MAAM;gBAC/B,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,IAAI,EAAE;gBACjC,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,IAAI,EAAE;aACtC,CAAA;QACH,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC,CAAC,CACH,CAAA;IAED,OAAO,QAAQ;SACZ,MAAM,CAAC,CAAC,CAAC,EAA8B,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC;SACzE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;SACjF,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA;AACpD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,KAAa,EACb,cAAsB,EACtB,OAAe;IAEf,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;QAC9C,MAAM,aAAa,GAAG,CAAC,kBAAkB,EAAE,mBAAmB,CAAC,CAAA;QAC/D,IAAI,MAAM,IAAI,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/E,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;YAC/E,MAAM,KAAK,CAAC,MAAM,CAAC;gBACjB,EAAE,EAAE,cAAc;gBAClB,IAAI,EAAE,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE;gBAC1C,QAAQ,EAAE,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;aAClD,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0CAA0C;IAC5C,CAAC;AACH,CAAC"}

package/dist/server/handlers/chat/delegator.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @module server/handlers/chat/delegator
+ * @description Tiered model delegation: Sonnet triage → Haiku execute → Sonnet synthesize.
+ *
+ * The delegator handles normal (non-plan-mode) chat by:
+ * 1. **Triage** — Sonnet analyzes the user message and decides: answer directly,
+ *    delegate specific tasks to Haiku, or recommend Plan Mode for complex work.
+ * 2. **Execute** — Haiku runs each delegated task (tool calls). If a task fails,
+ *    auto-escalates to Sonnet (the fallback model).
+ * 3. **Synthesize** — Sonnet combines task results into a coherent response.
+ *
+ * The delegator uses the injected {@link ChatAIClient} and {@link ToolExecutor},
+ * so it works with any product's tool set (Workshop, Venue, Academy).
+ */
+import type { ChatAIClient, ToolDefinition, ToolExecutor, ToolExecutionContext, DelegatedTask, TriageResult, TaskExecutionResult, DelegationResult } from './types.js';
+/**
+ * Options for the triage phase.
+ */
+export interface TriageOptions {
+    /** The user's message. */
+    message: string;
+    /** Recent conversation history. */
+    conversationHistory: Array<{
+        role: string;
+        content: string;
+    }>;
+    /** AI client for calling Claude. */
+    aiClient: ChatAIClient;
+    /** Available tools (used to populate the triage prompt). */
+    tools: ToolDefinition[];
+    /** Model to use for triage. Defaults to Sonnet. */
+    triageModel?: string;
+}
+/**
+ * Triage a user message — Sonnet decides how to handle it.
+ *
+ * Parses Claude's JSON response into a {@link RoutingDecision}. If parsing
+ * fails, falls back to treating the response as a direct answer.
+ *
+ * @param options - Triage configuration.
+ * @returns The routing decision and token usage.
+ */
+export declare function triageMessage(options: TriageOptions): Promise<TriageResult>;
+/**
+ * Options for executing a single delegated task.
+ */
+export interface ExecuteTaskOptions {
+    /** The task to execute. */
+    task: DelegatedTask;
+    /** AI client for calling Claude. */
+    aiClient: ChatAIClient;
+    /** Tool executor for running tool calls. */
+    toolExecutor: ToolExecutor;
+    /** Tool definitions available to the executor model. */
+    tools: ToolDefinition[];
+    /** Execution context for tool calls. */
+    toolContext: ToolExecutionContext;
+    /** Primary executor model. Defaults to Haiku. */
+    executeModel?: string;
+    /** Fallback model for auto-escalation. Defaults to Sonnet. */
+    fallbackModel?: string;
+}
+/**
+ * Execute a single delegated task using the executor model.
+ *
+ * If the task has explicit `tool` and `input` fields (from triage), executes
+ * the tool directly without an AI call. Otherwise, sends the task description
+ * to the executor model and lets it choose tools.
+ *
+ * Auto-escalates to the fallback model on failure.
+ *
+ * @param options - Task execution configuration.
+ * @returns Execution result with token usage.
+ */
+export declare function executeTask(options: ExecuteTaskOptions): Promise<TaskExecutionResult>;
+/**
+ * Options for the synthesis phase.
+ */
+export interface SynthesizeOptions {
+    /** The original user message. */
+    userMessage: string;
+    /** Results from executed tasks. */
+    taskResults: TaskExecutionResult[];
+    /** AI client for calling Claude. */
+    aiClient: ChatAIClient;
+    /** Model to use for synthesis. Defaults to Sonnet. */
+    synthesizeModel?: string;
+}
+/**
+ * Synthesize task results into a coherent response using Sonnet.
+ *
+ * Takes the raw task outputs and composes a user-facing answer that
+ * addresses the original request.
+ *
+ * @param options - Synthesis configuration.
+ * @returns The synthesized response text and token usage.
+ */
+export declare function synthesizeResults(options: SynthesizeOptions): Promise<{
+    response: string;
+    inputTokens: number;
+    outputTokens: number;
+}>;
+/**
+ * Options for the complete delegation flow.
+ */
+export interface DelegateOptions {
+    /** The user's message. */
+    message: string;
+    /** Recent conversation history. */
+    conversationHistory: Array<{
+        role: string;
+        content: string;
+    }>;
+    /** AI client for calling Claude. */
+    aiClient: ChatAIClient;
+    /** Available tool definitions. */
+    tools: ToolDefinition[];
+    /** Tool executor for running tool calls. */
+    toolExecutor: ToolExecutor;
+    /** Execution context for tool calls. */
+    toolContext: ToolExecutionContext;
+    /** Model for triage/synthesis. */
+    triageModel?: string;
+    /** Model for task execution. */
+    executeModel?: string;
+    /** Fallback model for escalation. */
+    fallbackModel?: string;
+    /** Called when a task starts. */
+    onTaskStart?: (task: DelegatedTask) => Promise<void>;
+    /** Called when a task completes. */
+    onTaskComplete?: (result: TaskExecutionResult) => Promise<void>;
+}
+/**
+ * Execute the full Sonnet → Haiku → Sonnet delegation flow.
+ *
+ * 1. Triage with Sonnet → routing decision
+ * 2. Execute tasks with Haiku (auto-escalate on failure)
+ * 3. Synthesize with Sonnet
+ *
+ * @param options - Delegation configuration.
+ * @returns The delegation result with synthesized response.
+ */
+export declare function delegateAndExecute(options: DelegateOptions): Promise<DelegationResult>;
+//# sourceMappingURL=delegator.d.ts.map

package/dist/server/handlers/chat/delegator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegator.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/chat/delegator.ts"],"names":[],"mappings":"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"}