botinabox 2.5.0 → 2.5.2

package/dist/core/chat/chat-responder.js

@@ -0,0 +1,185 @@
+/**
+ * ChatResponder — fast conversational layer with LLM-filtered responses.
+ * Story 7.2
+ *
+ * Provides rapid (<2s) conversational responses using a cheap LLM (Haiku).
+ * The responder has awareness of tools and capabilities but does NOT execute
+ * anything — it keeps the conversation going while work happens async.
+ *
+ * All outbound messages (direct, post-interpretation, task execution) are
+ * filtered through this layer for human readability and redundancy checking.
+ */
+const DEFAULT_SYSTEM_PROMPT = `You are a helpful, enthusiastic AI digital assistant. Your job is to:
+- Acknowledge the user's message and relay what you understand
+- Let them know what will happen next (if a task is being worked on)
+- Answer conversational questions directly
+- Be honest when you need to look something up — say "let me find out"
+- Keep responses concise and friendly
+
+You are aware of tools and capabilities in the system but you do NOT execute anything.
+You cannot run code, search databases, or take actions. You are purely conversational.
+If the user asks you to DO something, acknowledge it and say it will be handled.`;
+const DEFAULT_CONTEXT_TOKENS = 4000;
+const DEFAULT_REDUNDANCY_WINDOW = 10;
+const APPROX_CHARS_PER_TOKEN = 4;
+export class ChatResponder {
+    db;
+    hooks;
+    messageStore;
+    systemPrompt;
+    contextWindowTokens;
+    redundancyWindow;
+    model;
+    llmCall;
+    constructor(db, hooks, messageStore, config) {
+        this.db = db;
+        this.hooks = hooks;
+        this.messageStore = messageStore;
+        this.systemPrompt = config.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+        this.contextWindowTokens = config.contextWindowTokens ?? DEFAULT_CONTEXT_TOKENS;
+        this.redundancyWindow = config.redundancyWindow ?? DEFAULT_REDUNDANCY_WINDOW;
+        this.model = config.model ?? 'fast';
+        this.llmCall = config.llmCall;
+    }
+    /**
+     * Generate a fast conversational response to an inbound message.
+     * Uses rolling context window from thread history.
+     */
+    async respond(opts) {
+        // Build context window from thread history
+        const history = await this.messageStore.getThreadHistory(opts.threadId, 50);
+        const messages = this.buildContextWindow(history, opts.messageBody);
+        // Build system prompt with optional capabilities awareness
+        let system = this.systemPrompt;
+        if (opts.capabilities) {
+            system += `\n\nSystem capabilities you are aware of:\n${opts.capabilities}`;
+        }
+        if (opts.userName) {
+            system += `\n\nYou are talking to: ${opts.userName}`;
+        }
+        if (opts.additionalContext) {
+            system += opts.additionalContext;
+        }
+        const result = await this.llmCall({
+            model: this.model,
+            messages,
+            system,
+            maxTokens: 500,
+        });
+        return result.content;
+    }
+    /**
+     * Filter any outbound message through the LLM for human readability.
+     * This is the single funnel ALL responses pass through.
+     */
+    async filterResponse(text, context) {
+        // Short messages don't need filtering
+        if (text.length < 100)
+            return text;
+        const result = await this.llmCall({
+            model: this.model,
+            messages: [
+                {
+                    role: 'user',
+                    content: `Rewrite this agent/system message to be human-friendly and conversational. Keep the substance, remove jargon, make it feel like a helpful assistant talking to a person. If it's already readable, return it as-is. Do not add preamble like "Here's the rewritten version". Just output the rewritten text.\n\n---\n${text}`,
+                },
+            ],
+            maxTokens: 1000,
+        });
+        return result.content;
+    }
+    /**
+     * Check if a candidate outbound message is redundant with recent messages.
+     * Returns true if the message should be suppressed.
+     */
+    async isRedundant(text, threadId) {
+        const recent = await this.messageStore.getRecentOutbound(threadId, this.redundancyWindow);
+        if (recent.length === 0)
+            return false;
+        const recentTexts = recent
+            .map(m => m['body'] ?? '')
+            .filter(t => t.length > 0)
+            .slice(-5) // last 5 outbound messages
+            .join('\n---\n');
+        const result = await this.llmCall({
+            model: this.model,
+            messages: [
+                {
+                    role: 'user',
+                    content: `Does this NEW message duplicate or substantially overlap the RECENT messages already sent? Answer with just "redundant" or "not redundant". If the new message has meaningful new information or updates, it is NOT redundant.\n\nRECENT MESSAGES:\n${recentTexts}\n\nNEW MESSAGE:\n${text}`,
+                },
+            ],
+            maxTokens: 10,
+        });
+        return result.content.toLowerCase().includes('redundant') &&
+            !result.content.toLowerCase().includes('not redundant');
+    }
+    /**
+     * Full send pipeline: check redundancy → filter → store → deliver.
+     * Returns the message ID, or undefined if suppressed as redundant.
+     */
+    async sendResponse(opts) {
+        // 1. Redundancy check
+        if (!opts.skipRedundancyCheck) {
+            const redundant = await this.isRedundant(opts.text, opts.threadId);
+            if (redundant) {
+                await this.hooks.emit('response.suppressed', {
+                    channel: opts.channel,
+                    threadId: opts.threadId,
+                    reason: 'redundant',
+                });
+                return undefined;
+            }
+        }
+        // 2. Filter for readability
+        const filtered = opts.skipFilter
+            ? opts.text
+            : await this.filterResponse(opts.text, {
+                channel: opts.channel,
+                threadId: opts.threadId,
+                source: opts.source,
+            });
+        // 3. Store outbound message
+        const messageId = await this.messageStore.storeOutbound({
+            channel: opts.channel,
+            text: filtered,
+            threadId: opts.threadId,
+            agentId: opts.agentId,
+            agentSlug: opts.agentSlug,
+            taskId: opts.taskId,
+        });
+        // 4. Emit for delivery (NotificationQueue listens)
+        await this.hooks.emit('response.ready', {
+            messageId,
+            channel: opts.channel,
+            threadId: opts.threadId,
+            text: filtered,
+            taskId: opts.taskId,
+        });
+        return messageId;
+    }
+    /**
+     * Build a context window from thread history, trimmed to token limit.
+     */
+    buildContextWindow(history, currentMessage) {
+        const maxChars = this.contextWindowTokens * APPROX_CHARS_PER_TOKEN;
+        let charCount = currentMessage.length;
+        const messages = [];
+        // Walk backwards through history, adding messages until we hit the limit
+        for (let i = history.length - 1; i >= 0; i--) {
+            const msg = history[i];
+            const body = msg['body'] ?? '';
+            const direction = msg['direction'];
+            if (charCount + body.length > maxChars)
+                break;
+            messages.unshift({
+                role: direction === 'inbound' ? 'user' : 'assistant',
+                content: body,
+            });
+            charCount += body.length;
+        }
+        // Add current message
+        messages.push({ role: 'user', content: currentMessage });
+        return messages;
+    }
+}

package/dist/core/chat/formatter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Text formatter — converts markdown to channel-specific formats.
+ * Story 4.4
+ */
+/**
+ * Format text for the given mode:
+ * - 'mrkdwn': Slack's mrkdwn format (**bold** → *bold*, _italic_ preserved, `code` preserved)
+ * - 'html': basic markdown → HTML (strong, em, code, pre)
+ * - 'plain': strip markdown markers
+ */
+export declare function formatText(text: string, mode: "mrkdwn" | "html" | "plain"): string;

package/dist/core/chat/formatter.js

@@ -0,0 +1,60 @@
+/**
+ * Text formatter — converts markdown to channel-specific formats.
+ * Story 4.4
+ */
+/**
+ * Format text for the given mode:
+ * - 'mrkdwn': Slack's mrkdwn format (**bold** → *bold*, _italic_ preserved, `code` preserved)
+ * - 'html': basic markdown → HTML (strong, em, code, pre)
+ * - 'plain': strip markdown markers
+ */
+export function formatText(text, mode) {
+    switch (mode) {
+        case "mrkdwn":
+            return toMrkdwn(text);
+        case "html":
+            return toHtml(text);
+        case "plain":
+            return toPlain(text);
+    }
+}
+function toMrkdwn(text) {
+    // **bold** → *bold* (Slack uses single asterisk for bold)
+    let result = text.replace(/\*\*(.+?)\*\*/g, "*$1*");
+    // __bold__ → *bold*
+    result = result.replace(/__(.+?)__/g, "*$1*");
+    // _italic_ remains as _italic_ (already valid mrkdwn)
+    // `code` remains as `code`
+    // ```code block``` remains
+    return result;
+}
+function toHtml(text) {
+    // Code blocks first (before inline)
+    let result = text.replace(/```([\s\S]*?)```/g, "<pre><code>$1</code></pre>");
+    // Inline code
+    result = result.replace(/`(.+?)`/g, "<code>$1</code>");
+    // **bold**
+    result = result.replace(/\*\*(.+?)\*\*/g, "<strong>$1</strong>");
+    // __bold__
+    result = result.replace(/__(.+?)__/g, "<strong>$1</strong>");
+    // *italic*
+    result = result.replace(/\*(.+?)\*/g, "<em>$1</em>");
+    // _italic_
+    result = result.replace(/_(.+?)_/g, "<em>$1</em>");
+    return result;
+}
+function toPlain(text) {
+    // Remove code blocks
+    let result = text.replace(/```[\s\S]*?```/g, (m) => m.replace(/```/g, "").trim());
+    // Remove inline code markers
+    result = result.replace(/`(.+?)`/g, "$1");
+    // Remove **bold**
+    result = result.replace(/\*\*(.+?)\*\*/g, "$1");
+    // Remove __bold__
+    result = result.replace(/__(.+?)__/g, "$1");
+    // Remove *italic*
+    result = result.replace(/\*(.+?)\*/g, "$1");
+    // Remove _italic_
+    result = result.replace(/_(.+?)_/g, "$1");
+    return result;
+}

package/dist/core/chat/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Chat layer exports — Stories 4.1–4.4
+ */
+export { ChannelRegistry, ChannelRegistryError } from "./channel-registry.js";
+export { discoverChannels } from "./auto-discovery.js";
+export { MessagePipeline } from "./pipeline.js";
+export { buildAgentBindings } from "./routing.js";
+export { TriageRouter } from "./triage-router.js";
+export type { RoutingRule, RoutingDecision, TriageRouterConfig } from "./triage-router.js";
+export { checkAllowlist, checkMentionGate } from "./policies.js";
+export { SessionKey } from "./session-key.js";
+export { ChatSessionManager } from "./session-manager.js";
+export { NotificationQueue } from "./notification-queue.js";
+export { MessageStore } from "./message-store.js";
+export type { StoredAttachment, StoreResult } from "./message-store.js";
+export { ChatResponder } from "./chat-responder.js";
+export type { ChatResponderConfig } from "./chat-responder.js";
+export { MessageInterpreter } from "./message-interpreter.js";
+export type { Extractor, ExtractedTask, ExtractedMemory, ExtractedFile, ExtractedUserContext, InterpretationResult, MessageInterpreterConfig, LLMCallFn, } from "./message-interpreter.js";
+export { ChatPipeline } from "./chat-pipeline.js";
+export type { ChatPipelineConfig } from "./chat-pipeline.js";
+export { chunkText } from "./text-chunker.js";
+export { formatText } from "./formatter.js";
+export type { ChatType, FormattingMode, ChannelCapabilities, ChannelMeta, InboundMessage, Attachment, OutboundPayload, SendResult, HealthStatus, ChannelConfig, ChannelAdapter, } from "./types.js";

package/dist/core/chat/index.js

@@ -0,0 +1,18 @@
+/**
+ * Chat layer exports — Stories 4.1–4.4
+ */
+export { ChannelRegistry, ChannelRegistryError } from "./channel-registry.js";
+export { discoverChannels } from "./auto-discovery.js";
+export { MessagePipeline } from "./pipeline.js";
+export { buildAgentBindings } from "./routing.js";
+export { TriageRouter } from "./triage-router.js";
+export { checkAllowlist, checkMentionGate } from "./policies.js";
+export { SessionKey } from "./session-key.js";
+export { ChatSessionManager } from "./session-manager.js";
+export { NotificationQueue } from "./notification-queue.js";
+export { MessageStore } from "./message-store.js";
+export { ChatResponder } from "./chat-responder.js";
+export { MessageInterpreter } from "./message-interpreter.js";
+export { ChatPipeline } from "./chat-pipeline.js";
+export { chunkText } from "./text-chunker.js";
+export { formatText } from "./formatter.js";

package/dist/core/chat/message-interpreter.d.ts

@@ -0,0 +1,91 @@
+/**
+ * MessageInterpreter — async structured extraction from messages.
+ * Story 7.3
+ *
+ * After every message is stored, the interpreter runs async to extract
+ * structured data types: tasks, memories, files, user context, and custom types.
+ *
+ * Uses a cheap LLM (Haiku) for classification and extraction.
+ * Pluggable extractors allow apps to add custom data types.
+ */
+import type { DataStore } from '../data/data-store.js';
+import type { HookBus } from '../hooks/hook-bus.js';
+import type { ChatMessage } from '../../shared/index.js';
+export interface ExtractedTask {
+    title: string;
+    description?: string;
+    dueDate?: string;
+    scheduled?: boolean;
+    priority?: number;
+}
+export interface ExtractedMemory {
+    summary: string;
+    contents: string;
+    tags?: string[];
+    category?: string;
+}
+export interface ExtractedFile {
+    filename: string;
+    fileType: string;
+    contents: string;
+    summary: string;
+}
+export interface ExtractedUserContext {
+    trait: string;
+    value: string;
+}
+export interface InterpretationResult {
+    messageId: string;
+    tasks: ExtractedTask[];
+    memories: ExtractedMemory[];
+    files: ExtractedFile[];
+    userContext: ExtractedUserContext[];
+    custom: Record<string, unknown[]>;
+    isTaskRequest: boolean;
+}
+export type LLMCallFn = (params: {
+    model: string;
+    messages: ChatMessage[];
+    system?: string;
+    maxTokens?: number;
+}) => Promise<{
+    content: string;
+}>;
+/**
+ * Pluggable extractor interface for custom data types.
+ */
+export interface Extractor {
+    readonly type: string;
+    extract(message: {
+        body: string;
+        attachments?: Array<Record<string, unknown>>;
+    }, llmCall: LLMCallFn): Promise<unknown[]>;
+}
+export interface MessageInterpreterConfig {
+    /** Additional custom extractors beyond built-in ones */
+    extractors?: Extractor[];
+    /** Model for interpretation LLM calls. Default: 'fast' */
+    model?: string;
+    /** LLM call function */
+    llmCall: LLMCallFn;
+    /** Auto-create tasks from extracted tasks. Default: false */
+    autoCreateTasks?: boolean;
+}
+export declare class MessageInterpreter {
+    private db;
+    private hooks;
+    private readonly extractors;
+    private readonly model;
+    private readonly llmCall;
+    private readonly autoCreateTasks;
+    constructor(db: DataStore, hooks: HookBus, config: MessageInterpreterConfig);
+    /**
+     * Interpret a stored message asynchronously.
+     * Extracts tasks, memories, files, user context, and custom types.
+     */
+    interpret(messageId: string): Promise<InterpretationResult>;
+    /**
+     * Extract structured data from message text using LLM.
+     */
+    private extractWithLLM;
+}

package/dist/core/chat/message-interpreter.js

@@ -0,0 +1,166 @@
+/**
+ * MessageInterpreter — async structured extraction from messages.
+ * Story 7.3
+ *
+ * After every message is stored, the interpreter runs async to extract
+ * structured data types: tasks, memories, files, user context, and custom types.
+ *
+ * Uses a cheap LLM (Haiku) for classification and extraction.
+ * Pluggable extractors allow apps to add custom data types.
+ */
+const INTERPRET_SYSTEM = `You are a message parser. Extract structured data from the user's message.
+
+Return a JSON object with these fields:
+{
+  "tasks": [{ "title": "...", "description": "...", "priority": 1-10 }],
+  "memories": [{ "summary": "one-line", "contents": "full text", "tags": ["tag1"], "category": "..." }],
+  "user_context": [{ "trait": "...", "value": "..." }],
+  "is_task_request": true/false
+}
+
+Rules:
+- "tasks": ALWAYS create at least one task from every message. The task title should capture the user's intent. If the message is just a greeting or acknowledgment, create a task with title "Respond to greeting" or similar. Tasks are cheap — the execution layer decides whether action is needed.
+- "memories": information, notes, random thoughts to remember. Parse thematically — one message can have multiple memories.
+- "user_context": personality traits, preferences, or learnings about the user.
+- "is_task_request": ALWAYS true. Every message gets a task. The execution layer handles triage.
+- Return ONLY valid JSON, no markdown or explanation.`;
+export class MessageInterpreter {
+    db;
+    hooks;
+    extractors;
+    model;
+    llmCall;
+    autoCreateTasks;
+    constructor(db, hooks, config) {
+        this.db = db;
+        this.hooks = hooks;
+        this.extractors = config.extractors ?? [];
+        this.model = config.model ?? 'fast';
+        this.llmCall = config.llmCall;
+        this.autoCreateTasks = config.autoCreateTasks ?? false;
+    }
+    /**
+     * Interpret a stored message asynchronously.
+     * Extracts tasks, memories, files, user context, and custom types.
+     */
+    async interpret(messageId) {
+        const message = await this.db.get('messages', { id: messageId });
+        if (!message)
+            throw new Error(`Message not found: ${messageId}`);
+        const body = message['body'];
+        const userId = message['user_id'];
+        // Get attachments
+        const attachments = await this.db.query('message_attachments', {
+            where: { message_id: messageId },
+        });
+        // Run built-in LLM extraction
+        const parsed = await this.extractWithLLM(body);
+        // Store extracted memories
+        for (const memory of parsed.memories) {
+            await this.db.insert('memories', {
+                message_id: messageId,
+                user_id: userId,
+                summary: memory.summary,
+                contents: memory.contents,
+                tags: JSON.stringify(memory.tags ?? []),
+                category: memory.category,
+            });
+        }
+        // Store user context as memories with 'user_context' category
+        for (const ctx of parsed.userContext) {
+            await this.db.insert('memories', {
+                message_id: messageId,
+                user_id: userId,
+                summary: ctx.trait,
+                contents: ctx.value,
+                tags: JSON.stringify(['user_context']),
+                category: 'user_context',
+            });
+        }
+        // Extract from attachments (file contents/summaries)
+        const files = [];
+        for (const att of attachments) {
+            if (att['contents']) {
+                files.push({
+                    filename: att['filename'] ?? 'unknown',
+                    fileType: att['file_type'] ?? 'file',
+                    contents: att['contents'],
+                    summary: att['summary'] ?? '',
+                });
+            }
+        }
+        // Run custom extractors
+        const custom = {};
+        for (const extractor of this.extractors) {
+            try {
+                const results = await extractor.extract({ body, attachments }, this.llmCall);
+                if (results.length > 0) {
+                    custom[extractor.type] = results;
+                }
+            }
+            catch {
+                // Custom extractor failed — continue with others
+            }
+        }
+        const result = {
+            messageId,
+            tasks: parsed.tasks,
+            memories: parsed.memories,
+            files,
+            userContext: parsed.userContext,
+            custom,
+            isTaskRequest: parsed.isTaskRequest,
+        };
+        await this.hooks.emit('interpretation.completed', {
+            messageId,
+            taskCount: result.tasks.length,
+            memoryCount: result.memories.length,
+            fileCount: result.files.length,
+            isTaskRequest: result.isTaskRequest,
+        });
+        return result;
+    }
+    /**
+     * Extract structured data from message text using LLM.
+     */
+    async extractWithLLM(body) {
+        try {
+            const result = await this.llmCall({
+                model: this.model,
+                messages: [{ role: 'user', content: body }],
+                system: INTERPRET_SYSTEM,
+                maxTokens: 1000,
+            });
+            // Strip markdown fences if present (LLMs often wrap JSON in ```json...```)
+            const raw = result.content.replace(/^```(?:json)?\s*\n?/i, '').replace(/\n?```\s*$/i, '').trim();
+            const parsed = JSON.parse(raw);
+            return {
+                tasks: (parsed.tasks ?? []).map(t => ({
+                    title: t.title,
+                    description: t.description,
+                    priority: t.priority,
+                })),
+                memories: (parsed.memories ?? []).map(m => ({
+                    summary: m.summary,
+                    contents: m.contents,
+                    tags: m.tags,
+                    category: m.category,
+                })),
+                userContext: (parsed.user_context ?? []).map(u => ({
+                    trait: u.trait,
+                    value: u.value,
+                })),
+                isTaskRequest: parsed.is_task_request ?? false,
+            };
+        }
+        catch {
+            // LLM parse failed — return empty
+            return {
+                tasks: [],
+                memories: [],
+                userContext: [],
+                isTaskRequest: false,
+            };
+        }
+    }
+}

package/dist/core/chat/message-store.d.ts

@@ -0,0 +1,66 @@
+/**
+ * MessageStore — store-before-respond guarantee for all chat interactions.
+ * Story 7.1
+ *
+ * Every inbound message (with attachments) is stored BEFORE the bot responds.
+ * Every outbound message is stored BEFORE it is sent to the user.
+ * Storage confirmation is required before any response flows.
+ */
+import type { DataStore } from '../data/data-store.js';
+import type { HookBus } from '../hooks/hook-bus.js';
+import type { InboundMessage } from './types.js';
+export interface StoredAttachment {
+    fileType: string;
+    filename?: string;
+    mimeType?: string;
+    sizeBytes?: number;
+    contents?: string;
+    summary?: string;
+    url?: string;
+}
+export interface StoreResult {
+    messageId: string;
+    attachmentIds: string[];
+}
+export declare class MessageStore {
+    private db;
+    private hooks;
+    constructor(db: DataStore, hooks: HookBus);
+    /**
+     * Store an inbound message and its attachments.
+     * Must complete successfully before any bot response is generated.
+     */
+    storeInbound(msg: InboundMessage): Promise<StoreResult>;
+    /**
+     * Store an outbound message BEFORE sending it.
+     * Returns the message ID for confirmation tracking.
+     */
+    storeOutbound(opts: {
+        channel: string;
+        text: string;
+        threadId?: string;
+        agentId?: string;
+        agentSlug?: string;
+        taskId?: string;
+    }): Promise<string>;
+    /**
+     * Store an attachment linked to a message.
+     */
+    storeAttachment(messageId: string, att: StoredAttachment): Promise<string>;
+    /**
+     * Get recent messages in a thread for context building.
+     */
+    getThreadHistory(threadId: string, limit?: number): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Get recent outbound messages in a thread for redundancy checking.
+     */
+    getRecentOutbound(threadId: string, limit?: number): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Get recent messages from a specific user across all threads.
+     */
+    getUserHistory(userId: string, channel: string, limit?: number): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Get attachments for a message.
+     */
+    getAttachments(messageId: string): Promise<Array<Record<string, unknown>>>;
+}