botinabox 1.8.2 → 1.8.3

package/dist/core/chat/pipeline.js

@@ -0,0 +1,89 @@
+/**
+ * MessagePipeline — routes inbound messages to the task queue.
+ * Story 4.2
+ */
+import { buildAgentBindings } from "./routing.js";
+import { checkAllowlist, checkMentionGate } from "./policies.js";
+export class MessagePipeline {
+    hooks;
+    agentRegistry;
+    taskQueue;
+    config;
+    agentBindings;
+    userRegistry;
+    constructor(hooks, agentRegistry, taskQueue, config, userRegistry) {
+        this.hooks = hooks;
+        this.agentRegistry = agentRegistry;
+        this.taskQueue = taskQueue;
+        this.config = config;
+        this.agentBindings = buildAgentBindings(config.agents);
+        this.userRegistry = userRegistry;
+    }
+    /**
+     * Process an inbound message end-to-end.
+     * 1. Emit 'message.inbound'
+     * 2. Resolve agent
+     * 3. Check policy (allowlist / mention gate)
+     * 4. Create task
+     * 5. Emit 'message.processed'
+     */
+    async processInbound(msg) {
+        await this.hooks.emit("message.inbound", { message: msg, channel: msg.channel });
+        // Resolve sender to a user record (auto-creates if UserRegistry is available)
+        if (this.userRegistry && !msg.userId) {
+            const user = await this.userRegistry.resolveOrCreate(msg.from, msg.channel);
+            msg.userId = user.id;
+        }
+        const agentId = this.resolveAgent(msg);
+        if (agentId !== undefined) {
+            const allowed = this.evaluatePolicy(msg, agentId);
+            if (allowed) {
+                await this.taskQueue.create({
+                    title: `Message from ${msg.from} on ${msg.channel}`,
+                    description: msg.body,
+                    assignee_id: agentId,
+                    context: JSON.stringify({ message: msg, userId: msg.userId }),
+                });
+            }
+        }
+        await this.hooks.emit("message.processed", {
+            message: msg,
+            channel: msg.channel,
+            agentId: agentId ?? null,
+            userId: msg.userId ?? null,
+        });
+    }
+    /**
+     * Resolve the best agent for a given inbound message.
+     * Returns agentId (slug) or undefined if no match.
+     */
+    resolveAgent(msg) {
+        // Try direct channel binding first
+        const bound = this.agentBindings.get(msg.channel);
+        if (bound)
+            return bound;
+        // Fallback: first agent in config
+        const first = this.config.agents[0];
+        return first?.slug;
+    }
+    /**
+     * Evaluate messaging policy for the given agent.
+     * Returns false if the message is blocked.
+     */
+    evaluatePolicy(msg, agentId) {
+        const channelConfig = this.config.channels[msg.channel];
+        // Check allowlist
+        const allowFrom = channelConfig?.["allowFrom"] ?? [];
+        if (!checkAllowlist(allowFrom, msg.from)) {
+            return false;
+        }
+        // Check mention gate
+        const mentionGated = channelConfig?.["requireMention"] ?? false;
+        if (mentionGated) {
+            if (!checkMentionGate(msg, agentId)) {
+                return false;
+            }
+        }
+        return true;
+    }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Chat policy helpers — allowlist and mention gate checks.
+ * Story 4.2
+ */
+import type { InboundMessage } from "./types.js";
+/**
+ * Returns true if the sender is in the allowlist.
+ * If allowFrom is empty, all senders are allowed.
+ */
+export declare function checkAllowlist(allowFrom: string[], senderId: string): boolean;
+/**
+ * Returns true if the message passes the mention gate.
+ * In group/channel contexts, the bot must be mentioned (body contains @botId or similar).
+ * In direct contexts, always passes.
+ */
+export declare function checkMentionGate(msg: InboundMessage, botId: string): boolean;

package/dist/core/chat/policies.js

@@ -0,0 +1,25 @@
+/**
+ * Chat policy helpers — allowlist and mention gate checks.
+ * Story 4.2
+ */
+/**
+ * Returns true if the sender is in the allowlist.
+ * If allowFrom is empty, all senders are allowed.
+ */
+export function checkAllowlist(allowFrom, senderId) {
+    if (allowFrom.length === 0)
+        return true;
+    return allowFrom.includes(senderId);
+}
+/**
+ * Returns true if the message passes the mention gate.
+ * In group/channel contexts, the bot must be mentioned (body contains @botId or similar).
+ * In direct contexts, always passes.
+ */
+export function checkMentionGate(msg, botId) {
+    // For direct messages, no mention required
+    // We check via a simple heuristic: if the message contains the botId mention
+    // This is called only when mention gating is enabled
+    const body = msg.body ?? "";
+    return body.includes(`@${botId}`) || body.includes(botId);
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Chat routing — maps channel/scope to agentId.
+ * Story 4.2
+ *
+ * @deprecated Use TriageRouter for content-aware routing with keyword/regex
+ * matching and LLM fallback. This static channel→agent binding is kept for
+ * backward compatibility only. See `./triage-router.ts`.
+ */
+import type { AgentConfig } from "../../shared/index.js";
+/**
+ * Build a map from channel identifier to agentId.
+ * Each agent may have a config.channel or config.channels binding.
+ *
+ * @deprecated Use TriageRouter instead — it supports keyword, regex,
+ * and LLM-based routing with ownership chain logging.
+ */
+export declare function buildAgentBindings(agents: AgentConfig[]): Map<string, string>;

package/dist/core/chat/routing.js

@@ -0,0 +1,36 @@
+/**
+ * Chat routing — maps channel/scope to agentId.
+ * Story 4.2
+ *
+ * @deprecated Use TriageRouter for content-aware routing with keyword/regex
+ * matching and LLM fallback. This static channel→agent binding is kept for
+ * backward compatibility only. See `./triage-router.ts`.
+ */
+/**
+ * Build a map from channel identifier to agentId.
+ * Each agent may have a config.channel or config.channels binding.
+ *
+ * @deprecated Use TriageRouter instead — it supports keyword, regex,
+ * and LLM-based routing with ownership chain logging.
+ */
+export function buildAgentBindings(agents) {
+    const bindings = new Map();
+    for (const agent of agents) {
+        const agentId = agent.slug;
+        const cfg = agent.config ?? {};
+        // Support config.channel (single) or config.channels (array)
+        const channels = [];
+        if (typeof cfg["channel"] === "string") {
+            channels.push(cfg["channel"]);
+        }
+        if (Array.isArray(cfg["channels"])) {
+            for (const ch of cfg["channels"]) {
+                channels.push(ch);
+            }
+        }
+        for (const ch of channels) {
+            bindings.set(ch, agentId);
+        }
+    }
+    return bindings;
+}

package/dist/core/chat/session-key.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SessionKey — structured key for chat sessions.
+ * Story 4.3
+ */
+export declare class SessionKey {
+    readonly agentId: string;
+    readonly channel: string;
+    readonly scope: string;
+    constructor(agentId: string, channel: string, scope: string);
+    toString(): string;
+    toJSON(): {
+        agentId: string;
+        channel: string;
+        scope: string;
+    };
+    static fromString(key: string): SessionKey;
+    /**
+     * Build a session key from structured parameters.
+     *
+     * @param agentId      - The agent identifier
+     * @param channel      - The channel identifier
+     * @param chatType     - 'dm' or 'group'
+     * @param peerId       - The peer/user ID
+     * @param dmScope      - DM scoping strategy
+     *   - 'main'               → single session per agent+channel regardless of peer
+     *   - 'per-peer'           → one session per (agent, peer)
+     *   - 'per-channel-peer'   → one session per (agent, channel, peer)
+     */
+    static build(agentId: string, channel: string, chatType: "dm" | "group", peerId: string, dmScope: "main" | "per-peer" | "per-channel-peer"): SessionKey;
+}

package/dist/core/chat/session-key.js

@@ -0,0 +1,65 @@
+/**
+ * SessionKey — structured key for chat sessions.
+ * Story 4.3
+ */
+export class SessionKey {
+    agentId;
+    channel;
+    scope;
+    constructor(agentId, channel, scope) {
+        this.agentId = agentId;
+        this.channel = channel;
+        this.scope = scope;
+    }
+    toString() {
+        return `agent:${this.agentId}:${this.channel}:${this.scope}`;
+    }
+    toJSON() {
+        return {
+            agentId: this.agentId,
+            channel: this.channel,
+            scope: this.scope,
+        };
+    }
+    static fromString(key) {
+        const parts = key.split(":");
+        if (parts.length < 4 || parts[0] !== "agent") {
+            throw new Error(`Invalid SessionKey format: ${key}`);
+        }
+        // agentId might contain ':', so reconstruct carefully
+        // Format: "agent:{agentId}:{channel}:{scope}"
+        // We assume agentId, channel, scope do NOT contain ':'
+        const [, agentId, channel, scope] = parts;
+        if (!agentId || !channel || !scope) {
+            throw new Error(`Invalid SessionKey format: ${key}`);
+        }
+        return new SessionKey(agentId, channel, scope);
+    }
+    /**
+     * Build a session key from structured parameters.
+     *
+     * @param agentId      - The agent identifier
+     * @param channel      - The channel identifier
+     * @param chatType     - 'dm' or 'group'
+     * @param peerId       - The peer/user ID
+     * @param dmScope      - DM scoping strategy
+     *   - 'main'               → single session per agent+channel regardless of peer
+     *   - 'per-peer'           → one session per (agent, peer)
+     *   - 'per-channel-peer'   → one session per (agent, channel, peer)
+     */
+    static build(agentId, channel, chatType, peerId, dmScope) {
+        if (chatType === "group") {
+            // Groups are always scoped to the channel
+            return new SessionKey(agentId, channel, channel);
+        }
+        // DM scoping
+        switch (dmScope) {
+            case "main":
+                return new SessionKey(agentId, channel, "main");
+            case "per-peer":
+                return new SessionKey(agentId, channel, peerId);
+            case "per-channel-peer":
+                return new SessionKey(agentId, channel, `${channel}:${peerId}`);
+        }
+    }
+}

package/dist/core/chat/session-manager.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ChatSessionManager — wraps orchestrator SessionManager with SessionKey-based lookup.
+ * Story 4.3
+ */
+import type { DataStore } from "../data/data-store.js";
+import { SessionKey } from "./session-key.js";
+export declare class ChatSessionManager {
+    private readonly inner;
+    constructor(db: DataStore);
+    save(key: SessionKey, params: Record<string, unknown>): Promise<string>;
+    load(key: SessionKey): Promise<Record<string, unknown> | undefined>;
+    clear(key: SessionKey): Promise<void>;
+    shouldClear(session: Record<string, unknown>, opts: {
+        maxRuns?: number;
+        maxAgeHours?: number;
+    }): Promise<boolean>;
+}

package/dist/core/chat/session-manager.js

@@ -0,0 +1,23 @@
+/**
+ * ChatSessionManager — wraps orchestrator SessionManager with SessionKey-based lookup.
+ * Story 4.3
+ */
+import { SessionManager } from "../orchestrator/session-manager.js";
+export class ChatSessionManager {
+    inner;
+    constructor(db) {
+        this.inner = new SessionManager(db);
+    }
+    async save(key, params) {
+        return this.inner.save(key.agentId, key.channel, key.scope, params);
+    }
+    async load(key) {
+        return this.inner.load(key.agentId, key.channel, key.scope);
+    }
+    async clear(key) {
+        return this.inner.clear(key.agentId, key.channel, key.scope);
+    }
+    async shouldClear(session, opts) {
+        return this.inner.shouldClear(session, opts);
+    }
+}

package/dist/core/chat/text-chunker.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Text chunker — splits long text into chunks at natural boundaries.
+ * Story 4.4
+ */
+/**
+ * Split text into chunks of at most maxLen characters.
+ * Splits at paragraph boundaries first, then sentence, then word, then hard-cuts.
+ */
+export declare function chunkText(text: string, maxLen: number): string[];

package/dist/core/chat/text-chunker.js

@@ -0,0 +1,48 @@
+/**
+ * Text chunker — splits long text into chunks at natural boundaries.
+ * Story 4.4
+ */
+/**
+ * Split text into chunks of at most maxLen characters.
+ * Splits at paragraph boundaries first, then sentence, then word, then hard-cuts.
+ */
+export function chunkText(text, maxLen) {
+    if (maxLen <= 0)
+        throw new Error("maxLen must be > 0");
+    if (text.length <= maxLen)
+        return [text];
+    const chunks = [];
+    function splitInto(segment) {
+        if (segment.length <= maxLen) {
+            if (segment.length > 0)
+                chunks.push(segment);
+            return;
+        }
+        // Try paragraph split (\n\n)
+        const paraIdx = segment.lastIndexOf("\n\n", maxLen);
+        if (paraIdx > 0) {
+            chunks.push(segment.slice(0, paraIdx));
+            splitInto(segment.slice(paraIdx + 2).trimStart());
+            return;
+        }
+        // Try sentence split (". ")
+        const sentIdx = segment.lastIndexOf(". ", maxLen);
+        if (sentIdx > 0) {
+            chunks.push(segment.slice(0, sentIdx + 1));
+            splitInto(segment.slice(sentIdx + 2).trimStart());
+            return;
+        }
+        // Try word split (" ")
+        const wordIdx = segment.lastIndexOf(" ", maxLen);
+        if (wordIdx > 0) {
+            chunks.push(segment.slice(0, wordIdx));
+            splitInto(segment.slice(wordIdx + 1));
+            return;
+        }
+        // Hard cut
+        chunks.push(segment.slice(0, maxLen));
+        splitInto(segment.slice(maxLen));
+    }
+    splitInto(text);
+    return chunks;
+}

package/dist/core/chat/triage-router.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+import type { DataStore } from '../data/data-store.js';
+import type { HookBus } from '../hooks/hook-bus.js';
+import type { InboundMessage } from './types.js';
+export 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;
+}
+export interface RoutingDecision {
+    timestamp: string;
+    source: string;
+    target: string;
+    reason: string;
+    method: 'deterministic' | 'llm';
+    messageId?: string;
+    channel?: string;
+}
+export 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;
+}
+export 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;
+}

package/dist/core/chat/triage-router.js

@@ -0,0 +1,142 @@
+/**
+ * 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.
+ */
+export class TriageRouter {
+    db;
+    hooks;
+    rules;
+    fallbackAgent;
+    llmFallback;
+    persist;
+    compiledRules;
+    constructor(db, hooks, config) {
+        this.db = db;
+        this.hooks = hooks;
+        this.rules = config.rules;
+        this.fallbackAgent = config.fallbackAgent;
+        this.llmFallback = config.llmFallback ?? true;
+        this.persist = config.persist ?? true;
+        // Pre-compile patterns for fast matching
+        this.compiledRules = this.rules
+            .sort((a, b) => (a.priority ?? 50) - (b.priority ?? 50))
+            .map((rule) => ({
+            rule,
+            regexes: (rule.patterns ?? []).map((p) => new RegExp(p, 'i')),
+            keywordSet: new Set((rule.keywords ?? []).map((k) => k.toLowerCase())),
+        }));
+    }
+    /**
+     * Route an inbound message to the best agent.
+     * Returns the agent slug and the routing decision.
+     */
+    async route(msg) {
+        const body = msg.body.toLowerCase();
+        const words = new Set(body.split(/\s+/));
+        // Phase 1: Deterministic — keyword + regex matching
+        for (const { rule, regexes, keywordSet } of this.compiledRules) {
+            // Keyword match
+            for (const keyword of keywordSet) {
+                if (words.has(keyword) || body.includes(keyword)) {
+                    const decision = this.buildDecision(rule.agentSlug, `keyword: '${keyword}'`, 'deterministic', msg);
+                    await this.logDecision(decision);
+                    return { agentSlug: rule.agentSlug, decision };
+                }
+            }
+            // Regex match
+            for (const regex of regexes) {
+                if (regex.test(msg.body)) {
+                    const decision = this.buildDecision(rule.agentSlug, `pattern: ${regex.source}`, 'deterministic', msg);
+                    await this.logDecision(decision);
+                    return { agentSlug: rule.agentSlug, decision };
+                }
+            }
+        }
+        // Phase 2: LLM classification (if enabled)
+        if (this.llmFallback) {
+            const agentSlugs = this.rules.map((r) => r.agentSlug);
+            const classified = await this.classifyWithLLM(msg, agentSlugs);
+            if (classified) {
+                const decision = this.buildDecision(classified.agentSlug, `llm: ${classified.reason}`, 'llm', msg);
+                await this.logDecision(decision);
+                return { agentSlug: classified.agentSlug, decision };
+            }
+        }
+        // Phase 3: Fallback
+        const decision = this.buildDecision(this.fallbackAgent, 'fallback: no rule matched', 'deterministic', msg);
+        await this.logDecision(decision);
+        return { agentSlug: this.fallbackAgent, decision };
+    }
+    /**
+     * Query the ownership chain for a given message or channel.
+     */
+    async getDecisionHistory(filter) {
+        const rows = await this.db.query('activity_log', {
+            where: { event_type: 'triage_decision' },
+        });
+        let decisions = rows.map((r) => {
+            try {
+                return JSON.parse(r['payload']);
+            }
+            catch {
+                return null;
+            }
+        }).filter((d) => d !== null);
+        if (filter?.channel) {
+            decisions = decisions.filter((d) => d.channel === filter.channel);
+        }
+        // Sort by timestamp descending
+        decisions.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+        if (filter?.limit) {
+            decisions = decisions.slice(0, filter.limit);
+        }
+        return decisions;
+    }
+    /**
+     * LLM classification — emits a hook for external LLM integration.
+     * Returns agent slug + reason, or undefined if LLM is unavailable.
+     */
+    async classifyWithLLM(msg, agentSlugs) {
+        // Emit classification request — listeners provide the result
+        const result = {};
+        await this.hooks.emit('triage.classify', {
+            message: msg,
+            candidates: agentSlugs,
+            respond: (slug, reason) => {
+                result.agentSlug = slug;
+                result.reason = reason;
+            },
+        });
+        if (result.agentSlug && result.reason) {
+            return { agentSlug: result.agentSlug, reason: result.reason };
+        }
+        return undefined;
+    }
+    buildDecision(target, reason, method, msg) {
+        return {
+            timestamp: new Date().toISOString(),
+            source: 'triage',
+            target: target ?? 'none',
+            reason,
+            method,
+            messageId: msg.id,
+            channel: msg.channel,
+        };
+    }
+    async logDecision(decision) {
+        if (!this.persist)
+            return;
+        await this.db.insert('activity_log', {
+            event_type: 'triage_decision',
+            payload: JSON.stringify(decision),
+        });
+        await this.hooks.emit('triage.routed', { decision });
+    }
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Chat types — re-exports from @botinabox/shared channel types.
+ * Story 4.1
+ */
+export type { ChatType, FormattingMode, ChannelCapabilities, ChannelMeta, InboundMessage, Attachment, OutboundPayload, SendResult, HealthStatus, ChannelConfig, ChannelAdapter, } from "../../shared/index.js";

package/dist/core/chat/types.js

@@ -0,0 +1,5 @@
+/**
+ * Chat types — re-exports from @botinabox/shared channel types.
+ * Story 4.1
+ */
+export {};

package/dist/core/config/defaults.d.ts

@@ -0,0 +1,2 @@
+import type { BotConfig } from "../../shared/index.js";
+export declare const DEFAULT_CONFIG: BotConfig;

package/dist/core/config/defaults.js

@@ -0,0 +1,38 @@
+export const DEFAULT_CONFIG = {
+    data: {
+        path: "./data/bot.db",
+        walMode: true,
+    },
+    channels: {},
+    agents: [],
+    providers: {},
+    models: {
+        aliases: {
+            fast: "claude-haiku-4-5",
+            smart: "claude-opus-4-6",
+            balanced: "claude-sonnet-4-6",
+        },
+        default: "smart",
+        routing: {
+            conversation: "fast",
+            task_execution: "smart",
+            classification: "fast",
+        },
+        fallbackChain: [],
+    },
+    entities: {},
+    security: {
+        fieldLengthLimits: { default: 65535 },
+    },
+    render: {
+        outputDir: "./context",
+        watchIntervalMs: 30_000,
+    },
+    updates: {
+        policy: "auto-compatible",
+        checkIntervalMs: 86_400_000,
+    },
+    budget: {
+        warnPercent: 80,
+    },
+};

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

@@ -0,0 +1,6 @@
+export { loadConfig, getConfig, initConfig, _resetConfig } from "./loader.js";
+export type { ConfigLoadError, ConfigLoadResult } from "./loader.js";
+export { interpolateEnv } from "./interpolate.js";
+export { validateConfig } from "./schema.js";
+export type { SchemaError } from "./schema.js";
+export { DEFAULT_CONFIG } from "./defaults.js";

package/dist/core/config/index.js

@@ -0,0 +1,4 @@
+export { loadConfig, getConfig, initConfig, _resetConfig } from "./loader.js";
+export { interpolateEnv } from "./interpolate.js";
+export { validateConfig } from "./schema.js";
+export { DEFAULT_CONFIG } from "./defaults.js";