botinabox 2.9.5 → 2.9.7

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

@@ -1,655 +0,0 @@
-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 };