botinabox 2.8.1 → 2.9.0

package/dist/channel-CVm1AWUF.d.ts

@@ -0,0 +1,82 @@
+import { c as ContentBlock } from './provider-BHkqkSdq.js';
+
+/** Channel adapter types — Story 1.5 / 4.1 */
+
+type ChatType = "direct" | "group" | "channel";
+type FormattingMode = "markdown" | "mrkdwn" | "html" | "plain";
+interface ChannelCapabilities {
+    chatTypes: ChatType[];
+    threads: boolean;
+    reactions: boolean;
+    editing: boolean;
+    media: boolean;
+    polls: boolean;
+    maxTextLength: number;
+    formattingMode: FormattingMode;
+}
+interface ChannelMeta {
+    displayName: string;
+    icon?: string;
+    homepage?: string;
+}
+interface InboundMessage {
+    id: string;
+    channel: string;
+    account?: string;
+    from: string;
+    userId?: string;
+    body: string;
+    threadId?: string;
+    replyToId?: string;
+    attachments?: Attachment[];
+    /**
+     * Multimodal content blocks produced by attachment enrichers.
+     * When set, ChatPipeline builds a multimodal user message that passes
+     * these blocks through to the LLM provider alongside `body`.
+     */
+    attachmentBlocks?: ContentBlock[];
+    receivedAt: string;
+    raw?: unknown;
+}
+type AttachmentMediaType = "image" | "video" | "audio" | "pdf" | "doc" | "excel" | "presentation" | "html" | "link" | "misc";
+interface Attachment {
+    type: AttachmentMediaType;
+    url?: string;
+    mimeType?: string;
+    filename?: string;
+    size?: number;
+}
+interface OutboundPayload {
+    text: string;
+    threadId?: string;
+    replyToId?: string;
+    attachments?: Attachment[];
+}
+interface SendResult {
+    success: boolean;
+    messageId?: string;
+    error?: string;
+}
+interface HealthStatus {
+    ok: boolean;
+    latencyMs?: number;
+    error?: string;
+}
+type ChannelConfig = Record<string, unknown>;
+interface ChannelAdapter {
+    /** Unique identifier for this adapter instance */
+    id: string;
+    meta: ChannelMeta;
+    capabilities: ChannelCapabilities;
+    connect(config: ChannelConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    healthCheck(): Promise<HealthStatus>;
+    send(target: {
+        peerId: string;
+        threadId?: string;
+    }, payload: OutboundPayload): Promise<SendResult>;
+    /** Called when a message arrives — set by the framework */
+    onMessage?: (message: InboundMessage) => Promise<void>;
+}
+
+export type { Attachment as A, ChannelAdapter as C, FormattingMode as F, HealthStatus as H, InboundMessage as I, OutboundPayload as O, SendResult as S, AttachmentMediaType as a, ChannelCapabilities as b, ChannelConfig as c, ChannelMeta as d, ChatType as e };

package/dist/channels/discord/index.d.ts

@@ -1,4 +1,5 @@
-import { C as ChannelAdapter, d as ChannelMeta, b as ChannelCapabilities, I as InboundMessage, c as ChannelConfig, H as HealthStatus, O as OutboundPayload, S as SendResult } from '../../channel-DziSPayj.js';
+import { C as ChannelAdapter, d as ChannelMeta, b as ChannelCapabilities, I as InboundMessage, c as ChannelConfig, H as HealthStatus, O as OutboundPayload, S as SendResult } from '../../channel-CVm1AWUF.js';
+import '../../provider-BHkqkSdq.js';
 
 /**
  * DiscordAdapter — ChannelAdapter implementation for Discord.

package/dist/channels/slack/index.d.ts

@@ -1,7 +1,7 @@
-import { C as ChannelAdapter, d as ChannelMeta, b as ChannelCapabilities, I as InboundMessage, c as ChannelConfig, H as HealthStatus, O as OutboundPayload, S as SendResult, A as Attachment, a as AttachmentMediaType } from '../../channel-DziSPayj.js';
-import { H as HookBus, c as ChatPipeline } from '../../chat-pipeline-BGgmH_ap.js';
+import { C as ChannelAdapter, d as ChannelMeta, b as ChannelCapabilities, I as InboundMessage, c as ChannelConfig, H as HealthStatus, O as OutboundPayload, S as SendResult, A as Attachment, a as AttachmentMediaType } from '../../channel-CVm1AWUF.js';
+import { H as HookBus, c as ChatPipeline } from '../../chat-pipeline-aBSj7a4E.js';
+import { c as ContentBlock } from '../../provider-BHkqkSdq.js';
 import 'better-sqlite3';
-import '../../provider-BHkqkSdq.js';
 
 /**
  * SlackAdapter — ChannelAdapter implementation for Slack.
@@ -163,20 +163,30 @@ interface SlackConfig {
 }
 
 /**
- * An AttachmentEnricher downloads an attachment and extracts its textual content.
- *
- * Returns the extracted text on success, or `null` on failure. The framework
- * surfaces the filename/URL as a fallback when the enricher returns null.
- *
- * @param attachment - The attachment metadata (type, url, filename, etc.)
- * @param botToken - Slack bot token, required for authenticated downloads from url_private
+ * Transport-specific context passed to every enricher. Extensible — add a new
+ * optional sub-context when wiring a new source (gmail, drive, dropbox, etc.)
+ * and enrichers that need it can type-guard.
  */
-type AttachmentEnricher = (attachment: Attachment, botToken: string) => Promise<string | null>;
+interface EnrichmentContext {
+    slack?: {
+        botToken: string;
+    };
+    drive?: {
+        client: unknown;
+    };
+    gmail?: {
+        client: unknown;
+    };
+}
 /**
- * A map from attachment type to the enricher that handles it.
- * Types without an entry fall through to the framework's default behavior
- * (surfacing filename + URL in the message body).
+ * An AttachmentEnricher downloads an attachment and returns Claude content
+ * blocks representing it. Text blocks become part of the message body; image
+ * and document blocks flow through to the Anthropic provider unchanged.
+ *
+ * Enrichers throw on failure. The framework catches and falls back to a
+ * plain `[Attached: <filename>]` breadcrumb in the message body.
  */
+type AttachmentEnricher = (attachment: Attachment, ctx: EnrichmentContext) => Promise<ContentBlock[]>;
 type AttachmentEnricherMap = Partial<Record<AttachmentMediaType, AttachmentEnricher>>;
 /** Internal: the result of running enrichAttachments on a message. */
 interface EnrichedMessage extends InboundMessage {
@@ -214,51 +224,32 @@ declare class SlackBoltAdapter {
 }
 
 /**
- * Run enrichers over each attachment on an InboundMessage and append extracted
- * content to the message body.
- *
- * Enrichers are run sequentially. If an enricher throws or returns null, the
- * attachment is surfaced as `[Attached: <filename>]` with no content — the
- * LLM still sees that a file was present.
- *
- * Extracted text is appended to the body in this format:
+ * Run enrichers over each attachment on an InboundMessage. Text blocks get
+ * appended to `body`; image/document blocks get stored on `attachmentBlocks`
+ * so ChatPipeline can assemble a multimodal user message.
  *
- *     <original body>
- *
- *     [Attached: invoice.pdf]
- *     <extracted content>
+ * Enrichers that throw or return empty arrays fall back to a plain
+ * `[Attached: <filename>]` breadcrumb — the LLM still sees the attachment
+ * was there, just without content.
  */
-declare function enrichAttachments(msg: InboundMessage, botToken: string, enrichers: AttachmentEnricherMap): Promise<InboundMessage>;
+declare function enrichAttachments(msg: InboundMessage, ctx: EnrichmentContext, enrichers: AttachmentEnricherMap): Promise<InboundMessage>;
 
-interface ImageEnricherConfig {
-    /** Anthropic API key for vision calls. */
-    apiKey: string;
-    /** Model to use. Defaults to claude-sonnet-4-6. */
-    model?: string;
-    /** Max tokens for the description. Defaults to 1024. */
-    maxTokens?: number;
-    /** Prompt used for image description. */
-    prompt?: string;
-}
 /**
- * Build an enricher that sends Slack-hosted images to Claude's vision API
- * and returns a text description.
+ * Slack image enricher. Downloads the image via the Slack bot token and
+ * returns a single `image` ContentBlock containing the base64 data. No
+ * intermediate vision API call — the downstream Anthropic provider sees
+ * the raw image and processes it natively.
  *
- * Consumer must provide an Anthropic API key. The Anthropic SDK is a peer
- * dependency of botinabox — the consumer must have it installed.
+ * Consumers wire this as `attachmentEnrichers.image = createSlackImageEnricher()`.
  */
-declare function createImageEnricher(config: ImageEnricherConfig): AttachmentEnricher;
+declare function createSlackImageEnricher(): AttachmentEnricher;
 
-interface PdfEnricherConfig {
-    apiKey: string;
-    model?: string;
-    maxTokens?: number;
-    prompt?: string;
-}
 /**
- * Build an enricher that sends Slack-hosted PDFs to Claude's document API
- * and returns a text summary. Requires Claude 3.5+.
+ * Slack PDF enricher. Downloads the PDF via the Slack bot token and returns
+ * a single `document` ContentBlock containing the base64 data. No intermediate
+ * document-extraction API call — the downstream Anthropic provider ingests
+ * the PDF natively.
  */
-declare function createPdfEnricher(config: PdfEnricherConfig): AttachmentEnricher;
+declare function createSlackPdfEnricher(): AttachmentEnricher;
 
-export { type AttachmentEnricher, type AttachmentEnricherMap, type BoltClient, type EnrichedMessage, type ImageEnricherConfig, type PdfEnricherConfig, SlackAdapter, SlackBoltAdapter, type SlackBoltAdapterConfig, type SlackConfig, type SlackEvent, type SlackFile, type TranscribeOptions, type TranscribeResult, createImageEnricher, createPdfEnricher, createSlackAdapter as default, downloadAudio, enrichAttachments, enrichVoiceMessage, extractVoiceTranscript, formatForSlack, parseSlackEvent, transcribeAudio };
+export { type AttachmentEnricher, type AttachmentEnricherMap, type BoltClient, type EnrichedMessage, type EnrichmentContext, SlackAdapter, SlackBoltAdapter, type SlackBoltAdapterConfig, type SlackConfig, type SlackEvent, type SlackFile, type TranscribeOptions, type TranscribeResult, createSlackImageEnricher, createSlackPdfEnricher, createSlackAdapter as default, downloadAudio, enrichAttachments, enrichVoiceMessage, extractVoiceTranscript, formatForSlack, parseSlackEvent, transcribeAudio };

package/dist/channels/slack/index.js

@@ -86,30 +86,43 @@ function createSlackAdapter(client) {
 }
 
 // src/channels/slack/enrichers/enrich.ts
-async function enrichAttachments(msg, botToken, enrichers) {
+async function enrichAttachments(msg, ctx, enrichers) {
   if (!msg.attachments?.length) return msg;
-  const parts = msg.body ? [msg.body] : [];
+  const textParts = msg.body ? [msg.body] : [];
+  const mediaBlocks = [];
   for (const att of msg.attachments) {
     const enricher = enrichers[att.type];
     const label = att.filename ?? att.url ?? att.type;
     if (!enricher) {
-      parts.push(`[Attached: ${label}]`);
+      textParts.push(`[Attached: ${label}]`);
       continue;
     }
-    let extracted = null;
+    let blocks;
     try {
-      extracted = await enricher(att, botToken);
+      blocks = await enricher(att, ctx);
     } catch {
-      extracted = null;
+      textParts.push(`[Attached: ${label}]`);
+      continue;
     }
-    if (extracted) {
-      parts.push(`[Attached: ${label}]
-${extracted}`);
-    } else {
-      parts.push(`[Attached: ${label}]`);
+    if (blocks.length === 0) {
+      textParts.push(`[Attached: ${label}]`);
+      continue;
+    }
+    for (const block of blocks) {
+      if (block.type === "text") {
+        textParts.push(`[Attached: ${label}]
+${block.text}`);
+      } else if (block.type === "image" || block.type === "document") {
+        mediaBlocks.push(block);
+        textParts.push(`[Attached: ${label}]`);
+      }
     }
   }
-  return { ...msg, body: parts.join("\n\n") };
+  return {
+    ...msg,
+    body: textParts.join("\n\n"),
+    attachmentBlocks: mediaBlocks.length > 0 ? mediaBlocks : void 0
+  };
 }
 
 // src/channels/slack/bolt-adapter.ts
@@ -141,7 +154,11 @@ var SlackBoltAdapter = class {
         inbound = await enrichVoiceMessage2(inbound, botToken);
       }
       if (inbound.attachments?.length && this.config.attachmentEnrichers) {
-        inbound = await enrichAttachments(inbound, botToken, this.config.attachmentEnrichers);
+        inbound = await enrichAttachments(
+          inbound,
+          { slack: { botToken } },
+          this.config.attachmentEnrichers
+        );
       }
       await hooks.emit("message.inbound", inbound);
     });
@@ -196,108 +213,57 @@ var SlackBoltAdapter = class {
 };
 
 // src/channels/slack/enrichers/image-enricher.ts
-var DEFAULT_PROMPT = "Describe this image in detail. Include any visible text (OCR), objects, people, layout, and context. Be thorough \u2014 the description will be used as input to another agent that cannot see the image.";
-async function downloadAsBase64(urlPrivate, botToken) {
-  try {
-    const response = await fetch(urlPrivate, {
-      headers: { Authorization: `Bearer ${botToken}` },
+function createSlackImageEnricher() {
+  return async (att, ctx) => {
+    if (!att.url) throw new Error("image enricher: attachment has no url");
+    if (!ctx.slack?.botToken) throw new Error("image enricher: ctx.slack.botToken required");
+    const response = await fetch(att.url, {
+      headers: { Authorization: `Bearer ${ctx.slack.botToken}` },
       signal: AbortSignal.timeout(3e4)
     });
-    if (!response.ok) return null;
-    const buffer = Buffer.from(await response.arrayBuffer());
-    return buffer.toString("base64");
-  } catch {
-    return null;
-  }
-}
-function createImageEnricher(config) {
-  const { apiKey, model = "claude-sonnet-4-6", maxTokens = 1024, prompt = DEFAULT_PROMPT } = config;
-  return async (att, botToken) => {
-    if (!att.url) return null;
-    const mediaType = att.mimeType ?? "image/jpeg";
-    const base64 = await downloadAsBase64(att.url, botToken);
-    if (!base64) return null;
-    const anthropicModule = "@anthropic-ai/sdk";
-    const sdk = await import(anthropicModule);
-    const client = new sdk.default({ apiKey });
-    try {
-      const message = await client.messages.create({
-        model,
-        max_tokens: maxTokens,
-        messages: [
-          {
-            role: "user",
-            content: [
-              {
-                type: "image",
-                source: { type: "base64", media_type: mediaType, data: base64 }
-              },
-              { type: "text", text: prompt }
-            ]
-          }
-        ]
-      });
-      const textBlock = message.content.find((c) => c.type === "text");
-      return textBlock?.text ?? null;
-    } catch {
-      return null;
-    }
+    if (!response.ok) throw new Error(`slack download failed: ${response.status}`);
+    const base64 = Buffer.from(await response.arrayBuffer()).toString("base64");
+    return [
+      {
+        type: "image",
+        source: {
+          type: "base64",
+          media_type: att.mimeType ?? "image/jpeg",
+          data: base64
+        }
+      }
+    ];
   };
 }
 
 // src/channels/slack/enrichers/pdf-enricher.ts
-var DEFAULT_PROMPT2 = "Summarize this PDF in detail. Include all key facts, numbers, dates, names, and any structured content (tables, lists). The summary will be used as input to another agent that cannot see the PDF.";
-async function downloadAsBase642(urlPrivate, botToken) {
-  try {
-    const response = await fetch(urlPrivate, {
-      headers: { Authorization: `Bearer ${botToken}` },
+function createSlackPdfEnricher() {
+  return async (att, ctx) => {
+    if (!att.url) throw new Error("pdf enricher: attachment has no url");
+    if (!ctx.slack?.botToken) throw new Error("pdf enricher: ctx.slack.botToken required");
+    const response = await fetch(att.url, {
+      headers: { Authorization: `Bearer ${ctx.slack.botToken}` },
       signal: AbortSignal.timeout(6e4)
     });
-    if (!response.ok) return null;
-    const buffer = Buffer.from(await response.arrayBuffer());
-    return buffer.toString("base64");
-  } catch {
-    return null;
-  }
-}
-function createPdfEnricher(config) {
-  const { apiKey, model = "claude-sonnet-4-6", maxTokens = 4096, prompt = DEFAULT_PROMPT2 } = config;
-  return async (att, botToken) => {
-    if (!att.url) return null;
-    const base64 = await downloadAsBase642(att.url, botToken);
-    if (!base64) return null;
-    const anthropicModule = "@anthropic-ai/sdk";
-    const sdk = await import(anthropicModule);
-    const client = new sdk.default({ apiKey });
-    try {
-      const message = await client.messages.create({
-        model,
-        max_tokens: maxTokens,
-        messages: [
-          {
-            role: "user",
-            content: [
-              {
-                type: "document",
-                source: { type: "base64", media_type: "application/pdf", data: base64 }
-              },
-              { type: "text", text: prompt }
-            ]
-          }
-        ]
-      });
-      const textBlock = message.content.find((c) => c.type === "text");
-      return textBlock?.text ?? null;
-    } catch {
-      return null;
-    }
+    if (!response.ok) throw new Error(`slack download failed: ${response.status}`);
+    const base64 = Buffer.from(await response.arrayBuffer()).toString("base64");
+    return [
+      {
+        type: "document",
+        source: {
+          type: "base64",
+          media_type: "application/pdf",
+          data: base64
+        }
+      }
+    ];
   };
 }
 export {
   SlackAdapter,
   SlackBoltAdapter,
-  createImageEnricher,
-  createPdfEnricher,
+  createSlackImageEnricher,
+  createSlackPdfEnricher,
   createSlackAdapter as default,
   downloadAudio,
   enrichAttachments,

package/dist/channels/webhook/index.d.ts

@@ -1,4 +1,5 @@
-import { C as ChannelAdapter, d as ChannelMeta, b as ChannelCapabilities, I as InboundMessage, c as ChannelConfig, H as HealthStatus, O as OutboundPayload, S as SendResult } from '../../channel-DziSPayj.js';
+import { C as ChannelAdapter, d as ChannelMeta, b as ChannelCapabilities, I as InboundMessage, c as ChannelConfig, H as HealthStatus, O as OutboundPayload, S as SendResult } from '../../channel-CVm1AWUF.js';
+import '../../provider-BHkqkSdq.js';
 
 /**
  * WebhookAdapter — ChannelAdapter implementation for webhook-based channels.

package/dist/chat-pipeline-aBSj7a4E.d.ts

@@ -0,0 +1,655 @@
+import * as better_sqlite3 from 'better-sqlite3';
+import { I as InboundMessage } from './channel-CVm1AWUF.js';
+import { C as ChatMessage } from './provider-BHkqkSdq.js';
+
+type HookHandler = (context: Record<string, unknown>) => Promise<void> | void;
+type Unsubscribe = () => void;
+interface HookOptions {
+    /** 0–100, default 50. Lower = runs first. */
+    priority?: number;
+    /** Auto-unsubscribe after first invocation. */
+    once?: boolean;
+    /** Only fire if context matches all filter key/value pairs. */
+    filter?: Record<string, unknown>;
+}
+interface HookRegistration {
+    event: string;
+    handler: HookHandler;
+    priority: number;
+    once: boolean;
+    filter?: Record<string, unknown>;
+    /** Internal auto-increment for stable sort within same priority */
+    id: number;
+}
+
+/**
+ * Priority-ordered event bus for decoupled inter-layer communication.
+ * Story 1.1 — handlers run in priority order, errors are isolated,
+ * and registrations are unsubscribable.
+ */
+declare class HookBus {
+    private readonly registrations;
+    private nextId;
+    register(event: string, handler: HookHandler, opts?: HookOptions): Unsubscribe;
+    emit(event: string, context: Record<string, unknown>): Promise<void>;
+    /** Emit synchronously (use only when async is not needed) */
+    emitSync(event: string, context: Record<string, unknown>): void;
+    hasListeners(event: string): boolean;
+    listRegistered(): string[];
+    /** Remove all handlers for an event, or all handlers if no event given */
+    clear(event?: string): void;
+}
+
+interface TableDefinition {
+    columns: Record<string, string>;
+    primaryKey?: string | string[];
+    tableConstraints?: string[];
+    relations?: Record<string, RelationDef>;
+    render?: string | ((rows: Row[]) => string);
+    outputFile?: string;
+    filter?: (rows: Row[]) => Row[];
+}
+interface RelationDef {
+    type: 'belongsTo' | 'hasMany';
+    table: string;
+    foreignKey: string;
+    references?: string;
+}
+interface EntityContextDef {
+    table: string;
+    directory: string;
+    slugColumn: string;
+    files: Record<string, EntityFileSpec>;
+    indexFile?: string;
+    /** Custom index render function. If omitted, a default listing is generated. */
+    indexRender?: (rows: Row[]) => string;
+    protectedFiles?: string[];
+    /** When true, this entity's data is never rendered into other entities' context files. */
+    protected?: boolean;
+    /** Enable at-rest encryption. Requires encryptionKey in Lattice options. */
+    encrypted?: boolean | {
+        columns: string[];
+    };
+}
+interface EntityFileSpec {
+    source: EntitySource;
+    render: string | ((rows: Row[]) => string);
+    junctionColumns?: string[];
+    omitIfEmpty?: boolean;
+}
+type EntitySource = {
+    type: 'self';
+} | {
+    type: 'hasMany';
+    table: string;
+    foreignKey: string;
+    filters?: Filter[];
+    softDelete?: boolean;
+    orderBy?: string;
+    limit?: number;
+} | {
+    type: 'manyToMany';
+    junctionTable: string;
+    localKey: string;
+    remoteKey: string;
+    remoteTable: string;
+    filters?: Filter[];
+    softDelete?: boolean;
+    orderBy?: string;
+    limit?: number;
+} | {
+    type: 'belongsTo';
+    table: string;
+    foreignKey: string;
+} | {
+    type: 'enriched';
+    include: Record<string, EntitySource>;
+} | {
+    type: 'custom';
+    resolve: (row: Row, adapter: SqliteAdapter) => Row[];
+};
+interface Filter {
+    col: string;
+    op: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'in' | 'isNull' | 'isNotNull';
+    val?: unknown;
+}
+interface QueryOptions {
+    where?: Record<string, unknown>;
+    filters?: Filter[];
+    orderBy?: string | Array<{
+        col: string;
+        dir: 'asc' | 'desc';
+    }>;
+    orderDir?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+type Row = Record<string, unknown>;
+type PkLookup = string | Record<string, unknown>;
+interface SqliteAdapter {
+    run(sql: string, params?: unknown[]): better_sqlite3.RunResult;
+    get<T = Row>(sql: string, params?: unknown[]): T | undefined;
+    all<T = Row>(sql: string, params?: unknown[]): T[];
+    tableInfo(table: string): TableInfoRow[];
+    invalidateTableCache(table: string): void;
+}
+interface TableInfoRow {
+    cid: number;
+    name: string;
+    type: string;
+    notnull: number;
+    dflt_value: unknown;
+    pk: number;
+}
+interface SeedItem {
+    table: string;
+    rows: Row[];
+    naturalKey?: string | string[];
+    junctions?: Array<{
+        table: string;
+        items: Array<Row>;
+    }>;
+    softDeleteMissing?: boolean;
+}
+
+declare class DataStoreError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thin wrapper around Lattice that provides the botinabox DataStore API.
+ *
+ * Delegates all data operations to the latticesql package. Application-level
+ * events (task.created, run.completed, etc.) remain on the HookBus — they are
+ * emitted by orchestrator modules, not the data layer.
+ */
+declare class DataStore {
+    private lattice;
+    private readonly hooks;
+    private readonly outputDir;
+    private _initialized;
+    private readonly deferredStatements;
+    constructor(opts: {
+        dbPath: string;
+        outputDir?: string;
+        wal?: boolean;
+        hooks?: HookBus;
+    });
+    /**
+     * Register a table definition. Must be called before init().
+     *
+     * tableConstraints may contain both inline constraints (FOREIGN KEY, UNIQUE)
+     * and standalone SQL statements (CREATE INDEX). Standalone statements are
+     * deferred and executed after init() creates the tables.
+     */
+    define(name: string, def: TableDefinition): void;
+    /**
+     * Register an entity context definition for per-entity file rendering.
+     */
+    defineEntityContext(name: string, def: EntityContextDef): void;
+    init(opts?: {
+        migrations?: Array<{
+            version: string;
+            sql: string;
+        }>;
+    }): Promise<void>;
+    private assertInitialized;
+    insert(table: string, row: Row): Promise<Row>;
+    upsert(table: string, row: Row): Promise<Row>;
+    update(table: string, pk: PkLookup, changes: Row): Promise<Row>;
+    delete(table: string, pk: PkLookup): Promise<void>;
+    /**
+     * Get a single row by primary key.
+     * Returns undefined if not found (Lattice returns null).
+     */
+    get(table: string, pk: PkLookup): Promise<Row | undefined>;
+    query(table: string, opts?: QueryOptions): Promise<Row[]>;
+    count(table: string, opts?: QueryOptions): Promise<number>;
+    link(junctionTable: string, row: Row): Promise<void>;
+    unlink(junctionTable: string, row: Row): Promise<void>;
+    migrate(migrations: Array<{
+        version: string;
+        sql: string;
+    }>): Promise<void>;
+    seed(items: SeedItem[]): Promise<void>;
+    render(): Promise<void>;
+    reconcile(): Promise<void>;
+    tableInfo(table: string): TableInfoRow[];
+    close(): void;
+    on(event: string, handler: (context: Record<string, unknown>) => void): void;
+}
+
+/**
+ * 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 recent messages in a channel (all threads combined).
+     * More reliable than getThreadHistory for DMs where thread_ids are inconsistent.
+     */
+    getChannelHistory(channel: 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>>>;
+}
+
+/**
+ * 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;
+        additionalContext?: 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.
+     *
+     * Only includes inbound (user) messages. Outbound (bot) messages are
+     * excluded to prevent the ack layer from mimicking prior verbose responses,
+     * which caused hallucinated system state and walls of text.
+     */
+    private buildContextWindow;
+}
+
+/**
+ * TriageRouter — content-based routing with deterministic-first resolution.
+ * Story 6.3
+ *
+ * Replaces the simple channel→agent binding with intelligent routing:
+ * 1. Keyword/regex rules evaluated first (deterministic, ~4ms)
+ * 2. LLM classification only for ambiguous messages (async, ~2-4s)
+ * 3. Ownership chain logged for every routing decision
+ *
+ * Key constraint: specialists return to triage, never to another specialist.
+ */
+
+interface RoutingRule {
+    /** Target agent slug */
+    agentSlug: string;
+    /** Keywords that trigger this rule (case-insensitive) */
+    keywords?: string[];
+    /** Regex patterns that trigger this rule */
+    patterns?: string[];
+    /** Priority — lower number wins ties. Default: 50 */
+    priority?: number;
+}
+interface RoutingDecision {
+    timestamp: string;
+    source: string;
+    target: string;
+    reason: string;
+    method: 'deterministic' | 'llm';
+    messageId?: string;
+    channel?: string;
+}
+interface TriageRouterConfig {
+    /** Static routing rules evaluated deterministically */
+    rules: RoutingRule[];
+    /** Fallback agent if no rule matches and LLM is unavailable */
+    fallbackAgent?: string;
+    /** Whether to use LLM for ambiguous messages. Default: true */
+    llmFallback?: boolean;
+    /** Log decisions to the database. Default: true */
+    persist?: boolean;
+}
+declare class TriageRouter {
+    private db;
+    private hooks;
+    private readonly rules;
+    private readonly fallbackAgent?;
+    private readonly llmFallback;
+    private readonly persist;
+    private readonly compiledRules;
+    constructor(db: DataStore, hooks: HookBus, config: TriageRouterConfig);
+    /**
+     * Route an inbound message to the best agent.
+     * Returns the agent slug and the routing decision.
+     */
+    route(msg: InboundMessage): Promise<{
+        agentSlug: string | undefined;
+        decision: RoutingDecision;
+    }>;
+    /**
+     * Query the ownership chain for a given message or channel.
+     */
+    getDecisionHistory(filter?: {
+        channel?: string;
+        limit?: number;
+    }): Promise<RoutingDecision[]>;
+    /**
+     * LLM classification — emits a hook for external LLM integration.
+     * Returns agent slug + reason, or undefined if LLM is unavailable.
+     */
+    private classifyWithLLM;
+    private buildDecision;
+    private logDecision;
+}
+
+/**
+ * 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;
+    /** Skip the ack layer — no fast response before task dispatch (default: false) */
+    skipAck?: 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 skipAck;
+    private readonly threadChannelMap;
+    /** Last dispatch promise — exposed for testing. */
+    lastDispatch: Promise<void>;
+    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).
+     *
+     * ALWAYS creates a task programmatically — task creation does not depend
+     * on LLM classification. Interpretation enriches but never gates dispatch.
+     */
+    private interpretAndDispatch;
+    /**
+     * Programmatic task creation — guaranteed, no LLM dependency.
+     */
+    private guaranteedTaskDispatch;
+    /**
+     * 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;
+}
+
+export { type ChatResponderConfig as C, DataStore as D, type Extractor as E, type Filter as F, HookBus as H, type InterpretationResult as I, type LLMCallFn as L, MessageStore as M, type PkLookup as P, type QueryOptions as Q, type RelationDef as R, type SeedItem as S, type TableDefinition as T, type Unsubscribe as U, ChatResponder as a, MessageInterpreter as b, ChatPipeline as c, type ChatPipelineConfig as d, DataStoreError as e, type EntityContextDef as f, type EntityFileSpec as g, type EntitySource as h, type ExtractedFile as i, type ExtractedMemory as j, type ExtractedTask as k, type ExtractedUserContext as l, type HookHandler as m, type HookOptions as n, type HookRegistration as o, type MessageInterpreterConfig as p, type RoutingDecision as q, type RoutingRule as r, type Row as s, type SqliteAdapter as t, type StoreResult as u, type StoredAttachment as v, type TableInfoRow as w, TriageRouter as x, type TriageRouterConfig as y };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { C as ChannelAdapter, H as HealthStatus, I as InboundMessage } from './channel-DziSPayj.js';
-export { A as Attachment, a as AttachmentMediaType, b as ChannelCapabilities, c as ChannelConfig, d as ChannelMeta, e as ChatType, F as FormattingMode, O as OutboundPayload, S as SendResult } from './channel-DziSPayj.js';
+import { C as ChannelAdapter, H as HealthStatus, I as InboundMessage } from './channel-CVm1AWUF.js';
+export { A as Attachment, a as AttachmentMediaType, b as ChannelCapabilities, c as ChannelConfig, d as ChannelMeta, e as ChatType, F as FormattingMode, O as OutboundPayload, S as SendResult } from './channel-CVm1AWUF.js';
 import { T as TokenUsage, L as LLMProvider, M as ModelInfo, R as ResolvedModel, C as ChatMessage } from './provider-BHkqkSdq.js';
 export { a as ChatParams, b as ChatResult, c as ContentBlock, d as ToolUse } from './provider-BHkqkSdq.js';
 import { C as ConnectorConfig } from './connector-B4Mj0P1b.js';
 export { A as AuthResult, a as Connector, b as ConnectorMeta, P as PushResult, S as SyncOptions, c as SyncResult } from './connector-B4Mj0P1b.js';
-import { C as ChatResponderConfig, D as DataStore, H as HookBus, M as MessageStore, a as ChatResponder, b as MessageInterpreter, E as Extractor } from './chat-pipeline-BGgmH_ap.js';
-export { c as ChatPipeline, d as ChatPipelineConfig, e as DataStoreError, f as EntityContextDef, g as EntityFileSpec, h as EntitySource, i as ExtractedFile, j as ExtractedMemory, k as ExtractedTask, l as ExtractedUserContext, F as Filter, m as HookHandler, n as HookOptions, o as HookRegistration, I as InterpretationResult, L as LLMCallFn, p as MessageInterpreterConfig, P as PkLookup, Q as QueryOptions, R as RelationDef, q as RoutingDecision, r as RoutingRule, s as Row, S as SeedItem, t as SqliteAdapter, u as StoreResult, v as StoredAttachment, T as TableDefinition, w as TableInfoRow, x as TriageRouter, y as TriageRouterConfig, U as Unsubscribe } from './chat-pipeline-BGgmH_ap.js';
+import { C as ChatResponderConfig, D as DataStore, H as HookBus, M as MessageStore, a as ChatResponder, b as MessageInterpreter, E as Extractor } from './chat-pipeline-aBSj7a4E.js';
+export { c as ChatPipeline, d as ChatPipelineConfig, e as DataStoreError, f as EntityContextDef, g as EntityFileSpec, h as EntitySource, i as ExtractedFile, j as ExtractedMemory, k as ExtractedTask, l as ExtractedUserContext, F as Filter, m as HookHandler, n as HookOptions, o as HookRegistration, I as InterpretationResult, L as LLMCallFn, p as MessageInterpreterConfig, P as PkLookup, Q as QueryOptions, R as RelationDef, q as RoutingDecision, r as RoutingRule, s as Row, S as SeedItem, t as SqliteAdapter, u as StoreResult, v as StoredAttachment, T as TableDefinition, w as TableInfoRow, x as TriageRouter, y as TriageRouterConfig, U as Unsubscribe } from './chat-pipeline-aBSj7a4E.js';
 import 'better-sqlite3';
 
 /** Execution adapter types — Story 1.5 / 3.4 / 3.5 */
@@ -1065,6 +1065,7 @@ type ContentBlock = {
     id?: string;
     name?: string;
     input?: unknown;
+    source?: unknown;
 };
 type MessageParam = {
     role: string;

package/dist/index.js

@@ -2161,7 +2161,8 @@ ${ctx2}`;
           history,
           msg.body,
           threadTs,
-          channelId
+          channelId,
+          msg.attachmentBlocks
         );
         await this.hooks.emit("typing.stop", { channel: this.channel, threadId: threadTs });
         if (text) {
@@ -2209,14 +2210,15 @@ ${ctx2}`;
   /**
    * Primary agent tool loop — adapted from ExecutionEngine pattern.
    */
-  async think(systemPrompt, history, currentMessage, threadTs, channelId) {
+  async think(systemPrompt, history, currentMessage, threadTs, channelId, attachmentBlocks) {
     const model = this.config.model ?? "claude-sonnet-4-6";
     const maxIterations = this.config.maxIterations ?? DEFAULT_MAX_ITERATIONS;
     const maxTokens = this.config.maxTokens ?? DEFAULT_MAX_TOKENS;
     const tasksDispatched = [];
+    const userContent = attachmentBlocks?.length ? [...attachmentBlocks, { type: "text", text: currentMessage }] : currentMessage;
     const messages = [
       ...history,
-      { role: "user", content: currentMessage }
+      { role: "user", content: userContent }
     ];
     let finalText = "";
     for (let i = 0; i < maxIterations; i++) {

package/package.json

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