botinabox 1.6.0 → 1.8.0

package/README.md

@@ -5,6 +5,8 @@ A modular TypeScript framework for building multi-agent bots with LLM orchestrat
 ## Features
 
 - **Multi-agent orchestration** -- Define agents with different models, roles, and execution adapters. Task queue with priority scheduling, retry policies, and followup chains.
+- **Chat response layer** -- Fast (<2s) conversational responses via cheap LLM. Rolling context window, LLM-filtered readability, redundancy suppression. Store-before-respond guarantee for all messages.
+- **Message interpretation** -- Async structured extraction from messages into tasks, memories, files, and user context. Pluggable extractors for custom data types.
 - **Two-tier agents** -- Deterministic adapter for tasks that don't need LLM reasoning (routing, validation, data fetching). API and CLI adapters for LLM-driven tasks.
 - **Triage routing** -- Content-aware message routing with keyword/regex matching, priority rules, and LLM fallback for ambiguous messages. Ownership chain logging for every routing decision.
 - **Loop detection and circuit breakers** -- Pattern-based loop detection (self-loops, ping-pong, blocked re-entry) plus circuit breakers with automatic human escalation when agents fail repeatedly.

package/dist/index.d.ts

@@ -1035,6 +1035,340 @@ declare class NotificationQueue {
     private processNext;
 }
 
+/**
+ * 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.
+ */
+
+interface StoredAttachment {
+    fileType: string;
+    filename?: string;
+    mimeType?: string;
+    sizeBytes?: number;
+    contents?: string;
+    summary?: string;
+    url?: string;
+}
+interface StoreResult {
+    messageId: string;
+    attachmentIds: string[];
+}
+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 attachments for a message.
+     */
+    getAttachments(messageId: string): Promise<Array<Record<string, unknown>>>;
+}
+
+/**
+ * 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.
+ */
+
+interface ChatResponderConfig {
+    /** System prompt for the conversational responder */
+    systemPrompt?: string;
+    /** Max tokens for context window. Default: 4000 */
+    contextWindowTokens?: number;
+    /** Max recent outbound messages to check for redundancy. Default: 10 */
+    redundancyWindow?: number;
+    /** Model to use for responses. Default: 'fast' (resolved via ModelRouter) */
+    model?: string;
+    /** Caller-provided LLM call function */
+    llmCall: (params: {
+        model: string;
+        messages: ChatMessage[];
+        system?: string;
+        maxTokens?: number;
+    }) => Promise<{
+        content: string;
+    }>;
+}
+declare class ChatResponder {
+    private db;
+    private hooks;
+    private messageStore;
+    private readonly systemPrompt;
+    private readonly contextWindowTokens;
+    private readonly redundancyWindow;
+    private readonly model;
+    private readonly llmCall;
+    constructor(db: DataStore, hooks: HookBus, messageStore: MessageStore, config: ChatResponderConfig);
+    /**
+     * Generate a fast conversational response to an inbound message.
+     * Uses rolling context window from thread history.
+     */
+    respond(opts: {
+        messageBody: string;
+        threadId: string;
+        channel: string;
+        userName?: string;
+        capabilities?: string;
+    }): Promise<string>;
+    /**
+     * Filter any outbound message through the LLM for human readability.
+     * This is the single funnel ALL responses pass through.
+     */
+    filterResponse(text: string, context?: {
+        channel?: string;
+        threadId?: string;
+        source?: string;
+    }): Promise<string>;
+    /**
+     * Check if a candidate outbound message is redundant with recent messages.
+     * Returns true if the message should be suppressed.
+     */
+    isRedundant(text: string, threadId: string): Promise<boolean>;
+    /**
+     * Full send pipeline: check redundancy → filter → store → deliver.
+     * Returns the message ID, or undefined if suppressed as redundant.
+     */
+    sendResponse(opts: {
+        text: string;
+        channel: string;
+        threadId: string;
+        agentId?: string;
+        agentSlug?: string;
+        taskId?: string;
+        source?: string;
+        skipRedundancyCheck?: boolean;
+        skipFilter?: boolean;
+    }): Promise<string | undefined>;
+    /**
+     * Build a context window from thread history, trimmed to token limit.
+     */
+    private buildContextWindow;
+}
+
+/**
+ * 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.
+ */
+
+interface ExtractedTask {
+    title: string;
+    description?: string;
+    dueDate?: string;
+    scheduled?: boolean;
+    priority?: number;
+}
+interface ExtractedMemory {
+    summary: string;
+    contents: string;
+    tags?: string[];
+    category?: string;
+}
+interface ExtractedFile {
+    filename: string;
+    fileType: string;
+    contents: string;
+    summary: string;
+}
+interface ExtractedUserContext {
+    trait: string;
+    value: string;
+}
+interface InterpretationResult {
+    messageId: string;
+    tasks: ExtractedTask[];
+    memories: ExtractedMemory[];
+    files: ExtractedFile[];
+    userContext: ExtractedUserContext[];
+    custom: Record<string, unknown[]>;
+    isTaskRequest: boolean;
+}
+type LLMCallFn = (params: {
+    model: string;
+    messages: ChatMessage[];
+    system?: string;
+    maxTokens?: number;
+}) => Promise<{
+    content: string;
+}>;
+/**
+ * Pluggable extractor interface for custom data types.
+ */
+interface Extractor {
+    readonly type: string;
+    extract(message: {
+        body: string;
+        attachments?: Array<Record<string, unknown>>;
+    }, llmCall: LLMCallFn): Promise<unknown[]>;
+}
+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;
+}
+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;
+}
+
+/**
+ * ChatPipeline — configurable 6-layer chat orchestration.
+ * Story 7.4
+ *
+ * Replaces duplicated handler code across apps with a single configurable
+ * pipeline. Apps provide: system prompt, routing rules, LLM call function,
+ * and optional message filter. Everything else is framework-level.
+ *
+ * Layers:
+ *   1. Dedup + Storage (MessageStore)
+ *   2. Fast Response (ChatResponder)
+ *   3. Interpretation (MessageInterpreter)
+ *   4. Post-Interpretation Response
+ *   5. Task Dispatch (TriageRouter)
+ *   6. Task Execution Response
+ */
+
+interface ChatPipelineConfig {
+    /** LLM call function for chat responses and interpretation */
+    llmCall: ChatResponderConfig['llmCall'];
+    /** System prompt for the conversational responder */
+    systemPrompt: string;
+    /** Agent routing rules for task dispatch */
+    routingRules: RoutingRule[];
+    /** Default agent when no rule matches */
+    fallbackAgent: string;
+    /** Optional message filter — return false to ignore a message */
+    messageFilter?: (msg: InboundMessage) => boolean;
+    /** Optional capabilities description for the responder */
+    capabilities?: string;
+    /** Channel this pipeline handles (default: 'slack') */
+    channel?: string;
+    /** Custom extractors for MessageInterpreter */
+    extractors?: Extractor[];
+    /** Dedup window in ms (default: 300_000 = 5 min) */
+    dedupWindowMs?: number;
+    /** Model for fast responses (default: 'fast') */
+    model?: string;
+    /** Enable LLM fallback routing (default: false) */
+    llmRouting?: boolean;
+    /** TaskQueue instance — required for task dispatch */
+    tasks: {
+        create(task: Record<string, unknown>): Promise<string>;
+        update(id: string, changes: Record<string, unknown>): Promise<void>;
+        get(id: string): Promise<Record<string, unknown> | undefined>;
+    };
+    /** WakeupQueue instance — required for agent waking */
+    wakeups: {
+        enqueue(agentId: string, source: string, context?: Record<string, unknown>): Promise<string>;
+    };
+}
+declare class ChatPipeline {
+    private db;
+    private hooks;
+    readonly messageStore: MessageStore;
+    readonly responder: ChatResponder;
+    readonly interpreter: MessageInterpreter;
+    readonly router: TriageRouter;
+    private readonly channel;
+    private readonly messageFilter?;
+    private readonly capabilities?;
+    private readonly dedupWindowMs;
+    private readonly tasks;
+    private readonly wakeups;
+    private readonly threadChannelMap;
+    constructor(db: DataStore, hooks: HookBus, config: ChatPipelineConfig);
+    /**
+     * Resolve the Slack channel ID for a thread (for response delivery).
+     */
+    resolveChannel(threadId: string, taskId?: string): Promise<string | undefined>;
+    /**
+     * Register the 6-layer pipeline on the HookBus.
+     */
+    private registerHandlers;
+    /**
+     * Check and record message dedup (SHA256 hash, configurable window).
+     */
+    private isDuplicate;
+    /**
+     * Async interpretation + task dispatch (Layers 3-5).
+     */
+    private interpretAndDispatch;
+    /**
+     * Route and dispatch extracted tasks.
+     */
+    private dispatchTasks;
+    /**
+     * Resolve Slack channel ID from thread_task_map or in-memory fallback.
+     */
+    private resolveChannelId;
+    /**
+     * Build human-readable interpretation summary.
+     */
+    private buildSummary;
+}
+
 /**
  * Text chunker — splits long text into chunks at natural boundaries.
  * Story 4.4
@@ -2128,4 +2462,4 @@ declare function isLoginRequired(stdout: string): boolean;
 /** Rewrite local image paths to prevent CLI auto-embedding as vision content. */
 declare function deactivateLocalImagePaths(prompt: string): string;
 
-export { AGENT_STATUSES, type AgentConfig, type AgentDefinition, type AgentFilter, type AgentRecord, AgentRegistry, type AgentStatus, ApiExecutionAdapter, type ApprovalResponse, type ApprovalStatus, AuditEmitter, type AuditEvent, BackupManager, type BotConfig, BreakerState, type BudgetCheck, type BudgetConfig, BudgetController, CORE_MIGRATIONS, ChannelAdapter, ChannelRegistry, ChannelRegistryError, ChatMessage, ChatSessionManager, CircuitBreaker, type CircuitBreakerConfig, CliExecutionAdapter, type ColumnValidator, ColumnValidatorImpl, type ConfigLoadError, type ConfigLoadResult, ConnectorConfig, DEFAULTS, DEFAULT_CONFIG, type DataConfig, DataStore, DataStoreError, DeterministicAdapter, type DeterministicConfig, type DomainEntityContextOptions, type DomainSchemaOptions, DriftGate, EVENTS, type EntityColumnDef, type EntityConfig, type EntityContextDef, type EntityFileSpec, type EntitySource, type ExecutionAdapter, type FeedbackEntry, type Filter, type GateFinding, type GateInput, type GateResult, GateRunner, type GateVerdict, GovernanceGate, HealthStatus, HookBus, type HookHandler, type HookOptions, type HookRegistration, InboundMessage, LLMProvider, LearningPipeline, type LearningPipelineConfig, type LoopDetection, LoopDetector, type LoopDetectorConfig, LoopType, MAX_CHAIN_DEPTH, MessagePipeline, type ModelConfig, ModelInfo, ModelRouter, NdjsonLogger, NotificationQueue, type PackageMigration, type PackageUpdate, type ParsedStream, type PermissionPrompt, type PermissionProvider, PermissionRelay, type PermissionRelayConfig, type PkLookup, type PlaybookEntry, ProviderRegistry, QAGate, QualityGate, type QueryOptions, RUN_STATUSES, type RelationDef, type RenderConfig, ResolvedModel, type RetryPolicy, type RoutingDecision, type RoutingRule, type Row, type RunContext, RunManager, type RunResult, type RunStatus, type SanitizerOptions, type Schedule, type ScheduleDef, Scheduler, type SchemaError, type SecretInput, type SecretMeta, SecretStore, type SecurityConfig, type SeedItem, SessionKey, SessionManager, type SkillEntry, type SqliteAdapter, type StepRef, TASK_STATUSES, type TableDefinition, type TableInfoRow, type TaskDefinition, TaskQueue, type TaskRecord, type TaskStatus, TokenUsage, TriageRouter, type TriageRouterConfig, type Unsubscribe, UpdateChecker, type UpdateConfig, UpdateManager, type UpdateManifest, type UsageSummary, type User, type UserInput, UserRegistry, WakeupQueue, type WorkflowConfigEntry, type WorkflowDefinition$1 as WorkflowDefinition, WorkflowEngine, type WorkflowRunRecord, type WorkflowRunStatus, type WorkflowStep$1 as WorkflowStep, type WorkflowStepConfig, type WorkflowTrigger, _resetConfig, areDependenciesMet, autoUpdate, buildAgentBindings, buildChainOrigin, buildProcessEnv, checkAllowlist, checkChainDepth, checkMentionGate, chunkText, classifyUpdate, compareVersions, createConfigRevision, deactivateLocalImagePaths, defineCoreEntityContexts, defineCoreTables, defineDomainEntityContexts, defineDomainTables, detectCycle, discoverChannels, discoverProviders, formatText, getConfig, initConfig, interpolate, interpolateEnv, isLoginRequired, isMaxTurns, loadConfig, parseClaudeStream, parseVersion, runPackageMigrations, sanitize, topologicalSort, truncateAtWord, validateConfig };
+export { AGENT_STATUSES, type AgentConfig, type AgentDefinition, type AgentFilter, type AgentRecord, AgentRegistry, type AgentStatus, ApiExecutionAdapter, type ApprovalResponse, type ApprovalStatus, AuditEmitter, type AuditEvent, BackupManager, type BotConfig, BreakerState, type BudgetCheck, type BudgetConfig, BudgetController, CORE_MIGRATIONS, ChannelAdapter, ChannelRegistry, ChannelRegistryError, ChatMessage, ChatPipeline, type ChatPipelineConfig, ChatResponder, type ChatResponderConfig, ChatSessionManager, CircuitBreaker, type CircuitBreakerConfig, CliExecutionAdapter, type ColumnValidator, ColumnValidatorImpl, type ConfigLoadError, type ConfigLoadResult, ConnectorConfig, DEFAULTS, DEFAULT_CONFIG, type DataConfig, DataStore, DataStoreError, DeterministicAdapter, type DeterministicConfig, type DomainEntityContextOptions, type DomainSchemaOptions, DriftGate, EVENTS, type EntityColumnDef, type EntityConfig, type EntityContextDef, type EntityFileSpec, type EntitySource, type ExecutionAdapter, type ExtractedFile, type ExtractedMemory, type ExtractedTask, type ExtractedUserContext, type Extractor, type FeedbackEntry, type Filter, type GateFinding, type GateInput, type GateResult, GateRunner, type GateVerdict, GovernanceGate, HealthStatus, HookBus, type HookHandler, type HookOptions, type HookRegistration, InboundMessage, type InterpretationResult, type LLMCallFn, LLMProvider, LearningPipeline, type LearningPipelineConfig, type LoopDetection, LoopDetector, type LoopDetectorConfig, LoopType, MAX_CHAIN_DEPTH, MessageInterpreter, type MessageInterpreterConfig, MessagePipeline, MessageStore, type ModelConfig, ModelInfo, ModelRouter, NdjsonLogger, NotificationQueue, type PackageMigration, type PackageUpdate, type ParsedStream, type PermissionPrompt, type PermissionProvider, PermissionRelay, type PermissionRelayConfig, type PkLookup, type PlaybookEntry, ProviderRegistry, QAGate, QualityGate, type QueryOptions, RUN_STATUSES, type RelationDef, type RenderConfig, ResolvedModel, type RetryPolicy, type RoutingDecision, type RoutingRule, type Row, type RunContext, RunManager, type RunResult, type RunStatus, type SanitizerOptions, type Schedule, type ScheduleDef, Scheduler, type SchemaError, type SecretInput, type SecretMeta, SecretStore, type SecurityConfig, type SeedItem, SessionKey, SessionManager, type SkillEntry, type SqliteAdapter, type StepRef, type StoreResult, type StoredAttachment, TASK_STATUSES, type TableDefinition, type TableInfoRow, type TaskDefinition, TaskQueue, type TaskRecord, type TaskStatus, TokenUsage, TriageRouter, type TriageRouterConfig, type Unsubscribe, UpdateChecker, type UpdateConfig, UpdateManager, type UpdateManifest, type UsageSummary, type User, type UserInput, UserRegistry, WakeupQueue, type WorkflowConfigEntry, type WorkflowDefinition$1 as WorkflowDefinition, WorkflowEngine, type WorkflowRunRecord, type WorkflowRunStatus, type WorkflowStep$1 as WorkflowStep, type WorkflowStepConfig, type WorkflowTrigger, _resetConfig, areDependenciesMet, autoUpdate, buildAgentBindings, buildChainOrigin, buildProcessEnv, checkAllowlist, checkChainDepth, checkMentionGate, chunkText, classifyUpdate, compareVersions, createConfigRevision, deactivateLocalImagePaths, defineCoreEntityContexts, defineCoreTables, defineDomainEntityContexts, defineDomainTables, detectCycle, discoverChannels, discoverProviders, formatText, getConfig, initConfig, interpolate, interpolateEnv, isLoginRequired, isMaxTurns, loadConfig, parseClaudeStream, parseVersion, runPackageMigrations, sanitize, topologicalSort, truncateAtWord, validateConfig };

package/dist/index.js

@@ -1159,6 +1159,682 @@ var NotificationQueue = class {
   }
 };
 
+// src/core/chat/message-store.ts
+var MessageStore = class {
+  constructor(db, hooks) {
+    this.db = db;
+    this.hooks = hooks;
+  }
+  db;
+  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 = [];
+    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 attachments for a message.
+   */
+  async getAttachments(messageId) {
+    return this.db.query("message_attachments", {
+      where: { message_id: messageId }
+    });
+  }
+};
+
+// src/core/chat/chat-responder.ts
+var 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 \u2014 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.`;
+var DEFAULT_CONTEXT_TOKENS = 4e3;
+var DEFAULT_REDUNDANCY_WINDOW = 10;
+var APPROX_CHARS_PER_TOKEN = 4;
+var ChatResponder = class {
+  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;
+  }
+  db;
+  hooks;
+  messageStore;
+  systemPrompt;
+  contextWindowTokens;
+  redundancyWindow;
+  model;
+  llmCall;
+  /**
+   * Generate a fast conversational response to an inbound message.
+   * Uses rolling context window from thread history.
+   */
+  async respond(opts) {
+    const history = await this.messageStore.getThreadHistory(
+      opts.threadId,
+      50
+      // get more, trim by tokens
+    );
+    const messages = this.buildContextWindow(history, opts.messageBody);
+    let system = this.systemPrompt;
+    if (opts.capabilities) {
+      system += `
+
+System capabilities you are aware of:
+${opts.capabilities}`;
+    }
+    if (opts.userName) {
+      system += `
+
+You are talking to: ${opts.userName}`;
+    }
+    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) {
+    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.
+
+---
+${text}`
+        }
+      ],
+      maxTokens: 1e3
+    });
+    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).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.
+
+RECENT MESSAGES:
+${recentTexts}
+
+NEW MESSAGE:
+${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) {
+    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 void 0;
+      }
+    }
+    const filtered = opts.skipFilter ? opts.text : await this.filterResponse(opts.text, {
+      channel: opts.channel,
+      threadId: opts.threadId,
+      source: opts.source
+    });
+    const messageId = await this.messageStore.storeOutbound({
+      channel: opts.channel,
+      text: filtered,
+      threadId: opts.threadId,
+      agentId: opts.agentId,
+      agentSlug: opts.agentSlug,
+      taskId: opts.taskId
+    });
+    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 = [];
+    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;
+    }
+    messages.push({ role: "user", content: currentMessage });
+    return messages;
+  }
+};
+
+// src/core/chat/message-interpreter.ts
+var 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": actionable requests the user wants done. NOT conversational messages.
+- "memories": information, notes, random thoughts to remember. Parse thematically \u2014 one message can have multiple memories.
+- "user_context": personality traits, preferences, or learnings about the user.
+- "is_task_request": true if the message contains at least one actionable task.
+- If the message is just a greeting or conversation, return empty arrays and is_task_request: false.
+- Return ONLY valid JSON, no markdown or explanation.`;
+var MessageInterpreter = class {
+  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;
+  }
+  db;
+  hooks;
+  extractors;
+  model;
+  llmCall;
+  autoCreateTasks;
+  /**
+   * 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"];
+    const attachments = await this.db.query("message_attachments", {
+      where: { message_id: messageId }
+    });
+    const parsed = await this.extractWithLLM(body);
+    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
+      });
+    }
+    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"
+      });
+    }
+    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"] ?? ""
+        });
+      }
+    }
+    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 {
+      }
+    }
+    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: 1e3
+      });
+      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 {
+      return {
+        tasks: [],
+        memories: [],
+        userContext: [],
+        isTaskRequest: false
+      };
+    }
+  }
+};
+
+// src/core/chat/chat-pipeline.ts
+import { createHash, randomUUID } from "crypto";
+var DEFAULT_DEDUP_WINDOW_MS = 5 * 60 * 1e3;
+var ChatPipeline = class {
+  constructor(db, hooks, config) {
+    this.db = db;
+    this.hooks = hooks;
+    this.channel = config.channel ?? "slack";
+    this.messageFilter = config.messageFilter;
+    this.capabilities = config.capabilities;
+    this.dedupWindowMs = config.dedupWindowMs ?? DEFAULT_DEDUP_WINDOW_MS;
+    this.tasks = config.tasks;
+    this.wakeups = config.wakeups;
+    this.messageStore = new MessageStore(db, hooks);
+    this.responder = new ChatResponder(db, hooks, this.messageStore, {
+      llmCall: config.llmCall,
+      model: config.model ?? "fast",
+      systemPrompt: config.systemPrompt
+    });
+    this.interpreter = new MessageInterpreter(db, hooks, {
+      llmCall: config.llmCall,
+      model: config.model ?? "fast",
+      extractors: config.extractors
+    });
+    this.router = new TriageRouter(db, hooks, {
+      rules: config.routingRules,
+      fallbackAgent: config.fallbackAgent,
+      llmFallback: config.llmRouting ?? false,
+      persist: true
+    });
+    this.registerHandlers();
+  }
+  db;
+  hooks;
+  messageStore;
+  responder;
+  interpreter;
+  router;
+  channel;
+  messageFilter;
+  capabilities;
+  dedupWindowMs;
+  tasks;
+  wakeups;
+  // In-memory thread → channel mapping for response routing
+  // (before thread_task_map exists)
+  threadChannelMap = /* @__PURE__ */ new Map();
+  /**
+   * Resolve the Slack channel ID for a thread (for response delivery).
+   */
+  resolveChannel(threadId, taskId) {
+    return this.resolveChannelId(threadId, taskId);
+  }
+  /**
+   * Register the 6-layer pipeline on the HookBus.
+   */
+  registerHandlers() {
+    this.hooks.register("message.inbound", async (ctx) => {
+      const msg = ctx;
+      if (msg.channel !== this.channel) return;
+      if (this.messageFilter && !this.messageFilter(msg)) return;
+      if (await this.isDuplicate(msg)) return;
+      const rawTs = msg.raw?.ts;
+      const threadTs = msg.threadId ?? rawTs ?? msg.id;
+      const channelId = msg.account ?? "";
+      if (threadTs && channelId) {
+        this.threadChannelMap.set(threadTs, channelId);
+      }
+      const { messageId } = await this.messageStore.storeInbound(msg);
+      const ackResponse = await this.responder.respond({
+        messageBody: msg.body,
+        threadId: threadTs,
+        channel: this.channel,
+        capabilities: this.capabilities
+      });
+      await this.responder.sendResponse({
+        text: ackResponse,
+        channel: this.channel,
+        threadId: threadTs,
+        source: "responder",
+        skipFilter: true,
+        skipRedundancyCheck: true
+      });
+      void this.interpretAndDispatch(messageId, msg, threadTs, channelId);
+    });
+    this.hooks.register("run.completed", async (ctx) => {
+      const taskId = ctx.taskId;
+      if (!taskId) return;
+      const task = await this.db.get("tasks", { id: taskId });
+      const output = task?.result;
+      if (!output) return;
+      const mappings = await this.db.query("thread_task_map", {
+        where: { task_id: taskId }
+      });
+      if (mappings.length === 0) return;
+      const mapping = mappings[0];
+      await this.responder.sendResponse({
+        text: output,
+        channel: this.channel,
+        threadId: mapping.thread_ts,
+        agentId: ctx.agentId,
+        taskId,
+        source: "agent"
+      });
+    }, { priority: 90 });
+  }
+  /**
+   * Check and record message dedup (SHA256 hash, configurable window).
+   */
+  async isDuplicate(msg) {
+    const hash = createHash("sha256").update(`${msg.from}:${msg.body}`).digest("hex");
+    const cutoff = new Date(Date.now() - this.dedupWindowMs).toISOString();
+    const recent = await this.db.query("message_dedup", {
+      where: { content_hash: hash }
+    });
+    if (recent.some((r) => r.created_at > cutoff)) {
+      return true;
+    }
+    await this.db.insert("message_dedup", {
+      content_hash: hash,
+      channel_id: msg.account ?? ""
+    });
+    return false;
+  }
+  /**
+   * Async interpretation + task dispatch (Layers 3-5).
+   */
+  async interpretAndDispatch(messageId, msg, threadTs, channelId) {
+    try {
+      const result = await this.interpreter.interpret(messageId);
+      if (result.tasks.length > 0 || result.memories.length > 0) {
+        const summary = this.buildSummary(result);
+        await this.responder.sendResponse({
+          text: summary,
+          channel: this.channel,
+          threadId: threadTs,
+          source: "interpretation"
+        });
+      }
+      if (result.isTaskRequest && result.tasks.length > 0) {
+        await this.dispatchTasks(result, msg, threadTs, channelId);
+      }
+    } catch (err) {
+      await this.hooks.emit("interpretation.error", {
+        messageId,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  /**
+   * Route and dispatch extracted tasks.
+   */
+  async dispatchTasks(result, msg, threadTs, channelId) {
+    for (const extractedTask of result.tasks) {
+      const { agentSlug: targetSlug } = await this.router.route(msg);
+      if (!targetSlug) continue;
+      const agents = await this.db.query("agents", { where: { slug: targetSlug } });
+      const targetAgent = agents[0];
+      if (!targetAgent) continue;
+      const handlerAgentId = targetAgent.id;
+      if (threadTs) {
+        const existing = await this.db.query("thread_task_map", {
+          where: { thread_ts: threadTs, channel_id: channelId }
+        });
+        if (existing.length > 0) {
+          const taskId2 = existing[0].task_id;
+          const task = await this.tasks.get(taskId2);
+          if (task && task.status !== "done" && task.status !== "cancelled") {
+            const updatedDesc = `${task.description ?? ""}
+
+---
+**Follow-up (${(/* @__PURE__ */ new Date()).toISOString()}):**
+${msg.body}`;
+            await this.tasks.update(taskId2, { description: updatedDesc });
+            await this.wakeups.enqueue(handlerAgentId, "chat_followup", { taskId: taskId2 });
+            return;
+          }
+        }
+      }
+      const description = `## Chat Message
+
+**Channel:** ${channelId}
+**Thread:** ${threadTs}
+**From:** ${msg.from}
+**Time:** ${msg.receivedAt}
+
+---
+
+${extractedTask.description ?? msg.body}`;
+      const taskId = randomUUID();
+      if (threadTs) {
+        await this.db.insert("thread_task_map", {
+          thread_ts: threadTs,
+          channel_id: channelId,
+          task_id: taskId
+        });
+      }
+      await this.tasks.create({
+        id: taskId,
+        title: extractedTask.title.slice(0, 120),
+        description,
+        assignee_id: handlerAgentId,
+        priority: extractedTask.priority ?? 5
+      });
+      await this.wakeups.enqueue(handlerAgentId, "chat_dispatch", { taskId });
+    }
+  }
+  /**
+   * Resolve Slack channel ID from thread_task_map or in-memory fallback.
+   */
+  async resolveChannelId(threadId, taskId) {
+    if (taskId) {
+      const mappings = await this.db.query("thread_task_map", {
+        where: { task_id: taskId }
+      });
+      if (mappings.length > 0) return mappings[0].channel_id;
+    }
+    if (threadId) {
+      const mappings = await this.db.query("thread_task_map", {
+        where: { thread_ts: threadId }
+      });
+      if (mappings.length > 0) return mappings[0].channel_id;
+    }
+    return this.threadChannelMap.get(threadId);
+  }
+  /**
+   * Build human-readable interpretation summary.
+   */
+  buildSummary(result) {
+    const parts = [];
+    if (result.tasks.length > 0) {
+      const names = result.tasks.map((t) => t.title).join(", ");
+      parts.push(`I've identified ${result.tasks.length} task${result.tasks.length > 1 ? "s" : ""}: ${names}. Working on ${result.tasks.length > 1 ? "them" : "it"} now.`);
+    }
+    if (result.memories.length > 0) {
+      parts.push(`Noted ${result.memories.length} thing${result.memories.length > 1 ? "s" : ""} to remember.`);
+    }
+    return parts.join(" ");
+  }
+};
+
 // src/core/chat/text-chunker.ts
 function chunkText(text, maxLen) {
   if (maxLen <= 0) throw new Error("maxLen must be > 0");
@@ -1826,6 +2502,66 @@ function defineCoreTables(db) {
       "FOREIGN KEY (playbook_id) REFERENCES playbooks(id)"
     ]
   });
+  db.define("message_attachments", {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      message_id: "TEXT NOT NULL",
+      file_type: "TEXT NOT NULL DEFAULT 'file'",
+      filename: "TEXT",
+      mime_type: "TEXT",
+      size_bytes: "INTEGER",
+      contents: "TEXT",
+      summary: "TEXT",
+      url: "TEXT",
+      created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP"
+    },
+    tableConstraints: [
+      "CREATE INDEX IF NOT EXISTS idx_message_attachments_message ON message_attachments(message_id)",
+      "FOREIGN KEY (message_id) REFERENCES messages(id)"
+    ]
+  });
+  db.define("thread_task_map", {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      thread_ts: "TEXT NOT NULL",
+      channel_id: "TEXT NOT NULL",
+      task_id: "TEXT NOT NULL",
+      created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP"
+    },
+    tableConstraints: [
+      "CREATE UNIQUE INDEX IF NOT EXISTS idx_thread_task_map_thread ON thread_task_map(thread_ts, channel_id)",
+      "CREATE INDEX IF NOT EXISTS idx_thread_task_map_task ON thread_task_map(task_id)"
+    ]
+  });
+  db.define("message_dedup", {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      content_hash: "TEXT NOT NULL",
+      channel_id: "TEXT NOT NULL",
+      created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP"
+    },
+    tableConstraints: [
+      "CREATE INDEX IF NOT EXISTS idx_message_dedup_hash ON message_dedup(content_hash, created_at)"
+    ]
+  });
+  db.define("memories", {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      message_id: "TEXT",
+      user_id: "TEXT",
+      summary: "TEXT NOT NULL",
+      contents: "TEXT NOT NULL",
+      tags: "TEXT NOT NULL DEFAULT '[]'",
+      category: "TEXT",
+      created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+      updated_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+      deleted_at: "TEXT"
+    },
+    tableConstraints: [
+      "CREATE INDEX IF NOT EXISTS idx_memories_user ON memories(user_id, created_at)",
+      "CREATE INDEX IF NOT EXISTS idx_memories_message ON memories(message_id)"
+    ]
+  });
 }
 
 // src/core/data/core-migrations.ts
@@ -5473,6 +6209,8 @@ export {
   CORE_MIGRATIONS,
   ChannelRegistry,
   ChannelRegistryError,
+  ChatPipeline,
+  ChatResponder,
   ChatSessionManager,
   CircuitBreaker,
   CliExecutionAdapter,
@@ -5491,7 +6229,9 @@ export {
   LoopDetector,
   LoopType,
   MAX_CHAIN_DEPTH,
+  MessageInterpreter,
   MessagePipeline,
+  MessageStore,
   ModelRouter,
   NdjsonLogger,
   NotificationQueue,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botinabox",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Bot in a Box — framework for building multi-agent bots",
   "type": "module",
   "main": "./dist/index.js",