botinabox 1.8.2 → 1.8.3

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,164 @@
+/**
+ * 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,
+            });
+            const parsed = JSON.parse(result.content);
+            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>>>;
+}

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

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ */
+export class MessageStore {
+    db;
+    hooks;
+    constructor(db, hooks) {
+        this.db = db;
+        this.hooks = hooks;
+    }
+    /**
+     * Store an inbound message and its attachments.
+     * Must complete successfully before any bot response is generated.
+     */
+    async storeInbound(msg) {
+        const row = await this.db.insert('messages', {
+            channel: msg.channel,
+            direction: 'inbound',
+            from_user: msg.from,
+            user_id: msg.userId,
+            body: msg.body,
+            thread_id: msg.threadId,
+        });
+        const messageId = row['id'];
+        const attachmentIds = [];
+        // Store each attachment
+        if (msg.attachments && msg.attachments.length > 0) {
+            for (const att of msg.attachments) {
+                const attId = await this.storeAttachment(messageId, {
+                    fileType: att.type,
+                    filename: att.filename,
+                    mimeType: att.mimeType,
+                    sizeBytes: att.size,
+                    url: att.url,
+                });
+                attachmentIds.push(attId);
+            }
+        }
+        await this.hooks.emit('message.stored', {
+            messageId,
+            direction: 'inbound',
+            channel: msg.channel,
+            from: msg.from,
+            attachmentCount: attachmentIds.length,
+        });
+        return { messageId, attachmentIds };
+    }
+    /**
+     * Store an outbound message BEFORE sending it.
+     * Returns the message ID for confirmation tracking.
+     */
+    async storeOutbound(opts) {
+        const row = await this.db.insert('messages', {
+            channel: opts.channel,
+            direction: 'outbound',
+            from_agent: opts.agentSlug,
+            agent_id: opts.agentId,
+            body: opts.text,
+            thread_id: opts.threadId,
+            task_id: opts.taskId,
+        });
+        const messageId = row['id'];
+        await this.hooks.emit('message.stored', {
+            messageId,
+            direction: 'outbound',
+            channel: opts.channel,
+        });
+        return messageId;
+    }
+    /**
+     * Store an attachment linked to a message.
+     */
+    async storeAttachment(messageId, att) {
+        const row = await this.db.insert('message_attachments', {
+            message_id: messageId,
+            file_type: att.fileType,
+            filename: att.filename,
+            mime_type: att.mimeType,
+            size_bytes: att.sizeBytes,
+            contents: att.contents,
+            summary: att.summary,
+            url: att.url,
+        });
+        return row['id'];
+    }
+    /**
+     * Get recent messages in a thread for context building.
+     */
+    async getThreadHistory(threadId, limit = 20) {
+        const messages = await this.db.query('messages', {
+            where: { thread_id: threadId },
+            orderBy: 'created_at',
+            limit,
+        });
+        return messages;
+    }
+    /**
+     * Get recent outbound messages in a thread for redundancy checking.
+     */
+    async getRecentOutbound(threadId, limit = 10) {
+        const messages = await this.db.query('messages', {
+            where: { thread_id: threadId, direction: 'outbound' },
+            orderBy: 'created_at',
+            limit,
+        });
+        return messages;
+    }
+    /**
+     * Get recent messages from a specific user across all threads.
+     */
+    async getUserHistory(userId, channel, limit = 50) {
+        return this.db.query('messages', {
+            where: { from_user: userId, channel },
+            orderBy: 'created_at',
+            limit,
+        });
+    }
+    /**
+     * Get attachments for a message.
+     */
+    async getAttachments(messageId) {
+        return this.db.query('message_attachments', {
+            where: { message_id: messageId },
+        });
+    }
+}

package/dist/core/chat/notification-queue.d.ts

@@ -0,0 +1,34 @@
+/**
+ * NotificationQueue — persistent outbound notification queue with retry.
+ * Story 4.4
+ */
+import type { DataStore } from "../data/data-store.js";
+import type { HookBus } from "../hooks/hook-bus.js";
+import type { ChannelRegistry } from "./channel-registry.js";
+export interface NotificationQueueOpts {
+    maxRetries?: number;
+    pollIntervalMs?: number;
+}
+export declare class NotificationQueue {
+    private readonly db;
+    private readonly hooks;
+    private readonly channelRegistry;
+    private readonly maxRetries;
+    private readonly pollIntervalMs;
+    private timer;
+    constructor(db: DataStore, hooks: HookBus, channelRegistry: ChannelRegistry, opts?: NotificationQueueOpts);
+    /**
+     * Enqueue a notification for delivery.
+     * Returns the notification ID.
+     */
+    enqueue(channel: string, recipient: string, payload: {
+        text: string;
+        threadId?: string;
+        [key: string]: unknown;
+    }): Promise<string>;
+    /** Start the background worker polling for pending notifications. */
+    startWorker(): void;
+    /** Stop the background worker. */
+    stopWorker(): void;
+    private processNext;
+}

package/dist/core/chat/notification-queue.js

@@ -0,0 +1,111 @@
+/**
+ * NotificationQueue — persistent outbound notification queue with retry.
+ * Story 4.4
+ */
+export class NotificationQueue {
+    db;
+    hooks;
+    channelRegistry;
+    maxRetries;
+    pollIntervalMs;
+    timer = null;
+    constructor(db, hooks, channelRegistry, opts) {
+        this.db = db;
+        this.hooks = hooks;
+        this.channelRegistry = channelRegistry;
+        this.maxRetries = opts?.maxRetries ?? 3;
+        this.pollIntervalMs = opts?.pollIntervalMs ?? 5_000;
+    }
+    /**
+     * Enqueue a notification for delivery.
+     * Returns the notification ID.
+     */
+    async enqueue(channel, recipient, payload) {
+        if (!this.channelRegistry.has(channel)) {
+            throw new Error(`No registered adapter for channel: ${channel}`);
+        }
+        const row = await this.db.insert("notifications", {
+            channel,
+            recipient_id: recipient,
+            message: JSON.stringify(payload),
+            status: "pending",
+            retries: 0,
+        });
+        await this.hooks.emit("notification.enqueued", {
+            notificationId: row["id"],
+            channel,
+            recipient,
+        });
+        return row["id"];
+    }
+    /** Start the background worker polling for pending notifications. */
+    startWorker() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.processNext();
+        }, this.pollIntervalMs);
+    }
+    /** Stop the background worker. */
+    stopWorker() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    async processNext() {
+        // Query up to 10 pending or retry notifications
+        const rows = await this.db.query("notifications", {
+            where: { status: "pending" },
+            limit: 10,
+        });
+        for (const row of rows) {
+            const id = row["id"];
+            const channel = row["channel"];
+            const recipient = row["recipient_id"];
+            const retries = row["retries"] ?? 0;
+            let payload;
+            try {
+                payload = JSON.parse(row["message"]);
+            }
+            catch {
+                await this.db.update("notifications", { id }, { status: "failed", error: "Invalid payload" });
+                continue;
+            }
+            const adapter = this.channelRegistry.get(channel);
+            if (!adapter) {
+                await this.db.update("notifications", { id }, {
+                    status: "failed",
+                    error: `No adapter for channel: ${channel}`,
+                });
+                continue;
+            }
+            try {
+                await adapter.send({ peerId: recipient, threadId: payload.threadId }, payload);
+                await this.db.update("notifications", { id }, {
+                    status: "sent",
+                    sent_at: new Date().toISOString(),
+                });
+                await this.hooks.emit("notification.sent", { notificationId: id, channel, recipient });
+            }
+            catch (err) {
+                const newRetries = retries + 1;
+                if (newRetries >= this.maxRetries) {
+                    await this.db.update("notifications", { id }, {
+                        status: "failed",
+                        retries: newRetries,
+                        error: String(err),
+                    });
+                    await this.hooks.emit("notification.failed", { notificationId: id, channel, recipient, error: String(err) });
+                }
+                else {
+                    await this.db.update("notifications", { id }, {
+                        status: "pending",
+                        retries: newRetries,
+                        error: String(err),
+                    });
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,38 @@
+/**
+ * MessagePipeline — routes inbound messages to the task queue.
+ * Story 4.2
+ */
+import type { HookBus } from "../hooks/hook-bus.js";
+import type { AgentRegistry } from "../orchestrator/agent-registry.js";
+import type { TaskQueue } from "../orchestrator/task-queue.js";
+import type { UserRegistry } from "../orchestrator/user-registry.js";
+import type { BotConfig } from "../../shared/index.js";
+import type { InboundMessage } from "./types.js";
+export declare class MessagePipeline {
+    private readonly hooks;
+    private readonly agentRegistry;
+    private readonly taskQueue;
+    private readonly config;
+    private readonly agentBindings;
+    private readonly userRegistry?;
+    constructor(hooks: HookBus, agentRegistry: AgentRegistry, taskQueue: TaskQueue, config: BotConfig, userRegistry?: UserRegistry);
+    /**
+     * Process an inbound message end-to-end.
+     * 1. Emit 'message.inbound'
+     * 2. Resolve agent
+     * 3. Check policy (allowlist / mention gate)
+     * 4. Create task
+     * 5. Emit 'message.processed'
+     */
+    processInbound(msg: InboundMessage): Promise<void>;
+    /**
+     * Resolve the best agent for a given inbound message.
+     * Returns agentId (slug) or undefined if no match.
+     */
+    resolveAgent(msg: InboundMessage): string | undefined;
+    /**
+     * Evaluate messaging policy for the given agent.
+     * Returns false if the message is blocked.
+     */
+    evaluatePolicy(msg: InboundMessage, agentId: string): boolean;
+}