botinabox 2.7.10 → 2.8.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Automated Industries
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Automated Industries
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,190 +1,190 @@
-# Bot in a Box
-
-A modular TypeScript framework for building multi-agent bots with LLM orchestration, multi-channel messaging, and task automation.
-
-## Features
-
-- **Execution engine** -- Generic task executor with 22 built-in tools and a tool loop (up to 5 iterations). Agents can read files, send documents, dispatch tasks, search conversations, and more. Apps register tools declaratively.
-- **22 built-in tools** -- File ops (send, read, list, register), task ops (dispatch, cancel, reassign), system status (task, agent, system, active tasks), entity lookup (agents, projects, agent detail), messaging (send message, task comment, read/search conversation), management (create agent, create project). All channel-agnostic.
-- **Chat pipeline** -- Configurable 6-layer chat orchestration: dedup, storage, fast ack (<2s via Haiku), async interpretation, task dispatch, and completion response. Apps provide system prompt and routing rules; framework handles everything else.
-- **Slack integration** -- `SlackBoltAdapter` handles Bolt Socket Mode, message parsing, response delivery, and file uploads. One import, one `start()` call.
-- **Unified config** -- All settings in one `botinabox.config.yml`: models, execution, chat, routing, safety, budget. YAML with env var interpolation. Auto-initializes with sensible defaults.
-- **Message store** -- Store-before-respond guarantee. Inbound messages and attachments stored before any bot response. Channel history for conversation context.
-- **Message interpretation** -- Async structured extraction from messages into tasks, memories, files, and user context. Pluggable extractors for custom data types. Programmatic task creation (no LLM dependency).
-- **Triage routing** -- Content-aware message routing with keyword/regex matching, priority rules, and LLM fallback. Ownership chain logging for every routing decision.
-- **Multi-agent orchestration** -- Define agents with different models, roles, and execution adapters. Task queue with priority scheduling, retry policies, and followup chains.
-- **Loop detection and circuit breakers** -- Pattern-based loop detection (self-loops, ping-pong, blocked re-entry) plus circuit breakers with automatic human escalation.
-- **Learning pipeline** -- Structured feedback capture with auto-promotion: 3+ similar records become a playbook, 3+ agents become a reusable skill.
-- **Governance gates** -- Independent QA, quality, and drift gates that validate agent output and report to the human operator.
-- **Permission relay** -- Remote approval via messaging platforms (Slack, Discord, Telegram). Dual approval: local + remote, first wins.
-- **LLM provider abstraction** -- Swap between Anthropic, OpenAI, and Ollama. Model aliasing, purpose-based routing, fallback chains. Default LLM call wrapper included.
-- **Channel adapters** -- Slack (Bolt Socket Mode), Discord, and webhooks. Auto-discovery, session management, notification queuing.
-- **Workflow engine** -- Multi-step workflows with dependency resolution, parallel execution, and conditional branching.
-- **SQLite data layer** -- 27 core tables, migrations, entity context rendering via [latticesql](https://github.com/automated-industries/lattice). WAL mode.
-- **Event-driven hooks** -- Priority-ordered, filter-based event bus for decoupled communication.
-- **Budget controls** -- Per-agent and global cost tracking with warning thresholds and hard stops.
-- **Scheduling** -- Database-backed cron and one-time schedules.
-- **Connectors** -- Google Gmail, Calendar, and Drive via OAuth2 and service account.
-- **Security** -- Input sanitization, field length enforcement, audit logging, HMAC webhook verification.
-
-## Install
-
-```bash
-npm install botinabox
-```
-
-Install peer dependencies for the providers you need:
-
-```bash
-# For Anthropic
-npm install @anthropic-ai/sdk
-
-# For OpenAI
-npm install openai
-
-# For Google connectors
-npm install googleapis
-```
-
-## Quick Start
-
-```typescript
-import {
-  HookBus, DataStore, defineCoreTables, initConfig,
-  TaskQueue, RunManager, WakeupQueue, ChatPipeline,
-  registerExecutionEngine, createDefaultLLMCall,
-  sendFileTool, readFileTool, listAgentsTool, getTaskStatusTool,
-} from 'botinabox';
-import { SlackBoltAdapter } from 'botinabox/slack';
-import Anthropic from '@anthropic-ai/sdk';
-
-// 1. Config (auto-loads botinabox.config.yml or uses defaults)
-initConfig({});
-const hooks = new HookBus();
-const db = new DataStore({ dbPath: './data/bot.db', wal: true, hooks });
-defineCoreTables(db);
-await db.init();
-
-// 2. Orchestration
-const tasks = new TaskQueue(db, hooks);
-const runs = new RunManager(db, hooks);
-const wakeups = new WakeupQueue(db);
-
-// 3. Execution engine with built-in tools
-const client = new Anthropic();
-await registerExecutionEngine({
-  db, hooks, runs,
-  config: {
-    client,
-    tools: [sendFileTool, readFileTool, listAgentsTool, getTaskStatusTool],
-  },
-});
-
-// 4. Chat pipeline (6-layer: dedup → ack → interpret → dispatch → execute → respond)
-const llmCall = createDefaultLLMCall(client);
-const pipeline = new ChatPipeline(db, hooks, {
-  llmCall, tasks, wakeups,
-  systemPrompt: 'You are a helpful AI assistant.',
-  routingRules: [{ agentSlug: 'assistant', keywords: ['help'] }],
-  fallbackAgent: 'assistant',
-});
-
-// 5. Slack (one import, one start)
-const slack = new SlackBoltAdapter({
-  botToken: process.env.SLACK_BOT_TOKEN!,
-  appToken: process.env.SLACK_APP_TOKEN!,
-  hooks, pipeline,
-});
-await slack.start();
-tasks.startPolling();
-```
-
-## Subpath Exports
-
-| Import path | Description |
-|---|---|
-| `botinabox` | Core framework -- HookBus, DataStore, ChatPipeline, ExecutionEngine, 22 built-in tools, config (loadConfig/getConfig), AgentRegistry, TaskQueue, RunManager, Scheduler, MessageStore, ChatResponder, MessageInterpreter, TriageRouter, createDefaultLLMCall, buildSystemContext, and all shared types |
-| `botinabox/anthropic` | Anthropic Claude provider (`createAnthropicProvider`) |
-| `botinabox/openai` | OpenAI GPT provider (`createOpenAIProvider`) |
-| `botinabox/ollama` | Ollama local model provider (`createOllamaProvider`) |
-| `botinabox/slack` | Slack channel adapter (`SlackAdapter`) |
-| `botinabox/discord` | Discord channel adapter (`DiscordAdapter`) |
-| `botinabox/webhook` | Webhook channel adapter with HMAC verification (`WebhookAdapter`) |
-| `botinabox/google` | Google connectors -- Gmail, Calendar, and Drive via OAuth2 |
-
-## Architecture
-
-```
-                    +-------------------------------------+
-                    |           Channel Adapters           |
-                    |     Slack  .  Discord  .  Webhook    |
-                    +--------------+-----------------------+
-                                   | InboundMessage
-                    +--------------v-----------------------+
-                    |         Message Pipeline              |
-                    |   routing . policies . sessions       |
-                    +--------------+-----------------------+
-                                   | Task
-                    +--------------v-----------------------+
-                    |          Task Queue                   |
-                    |  priority . retry . followup chains   |
-                    +--------------+-----------------------+
-                                   |
-                    +--------------v-----------------------+
-                    |          Run Manager                  |
-                    |    locking . retries . cost tracking  |
-                    +--------------+-----------------------+
-                                   |
-              +--------------------+--------------------+
-              v                    v                    v
-    +------------------+  +------------------+  +------------------+
-    |  CLI Adapter      |  |  API Adapter      |  |  Deterministic   |
-    |  (subprocess)     |  |  (LLM + tools)    |  |  (no LLM)        |
-    +------------------+  +--------+----------+  +------------------+
-                                   |
-                    +--------------v-----------------------+
-                    |         LLM Layer                     |
-                    |  ProviderRegistry . ModelRouter        |
-                    |  BudgetController . Tool Loop          |
-                    +--------------+-----------------------+
-                                   |
-              +--------------------+-------------------+
-              v                    v                   v
-    +---------------+    +---------------+    +---------------+
-    |  Anthropic     |    |  OpenAI        |    |  Ollama        |
-    +---------------+    +---------------+    +---------------+
-```
-
-Cross-cutting concerns -- **HookBus** (events), **DataStore** (persistence), **Security** (sanitization + audit) -- connect all layers.
-
-## Core Concepts
-
-**HookBus** is the central event bus. Handlers subscribe to named events with optional priority ordering and payload filters. Errors in one handler never block others. Use it to decouple layers -- the task queue emits `task.created`, the run manager emits `run.completed`, channels emit `message.inbound`, and your application code listens to whichever events it needs.
-
-**DataStore** wraps [latticesql](https://github.com/automated-industries/lattice) to provide schema-driven SQLite persistence. You call `db.define()` to register table schemas, then `db.init()` to create them. It supports insert, update, upsert, get, query, delete, and migrations. WAL mode is enabled by default for concurrent read access.
-
-**AgentRegistry** manages the lifecycle of agents -- registration, status transitions (idle/running/paused/terminated), configuration revisions, and activity logging. Each agent has a slug, name, adapter type, role, and optional budget. Agents are stored in the database and can be seeded from config on startup.
-
-**TaskQueue** is a priority-ordered work queue backed by SQLite. Tasks have a title, description, assignee, priority (1-10), and support retry policies and followup chains. Chain depth is enforced to prevent infinite recursion. The queue emits `task.created` on the HookBus and supports polling for stale tasks.
-
-**RunManager** handles task execution lifecycle. It acquires a per-agent lock, creates a run record, delegates to an execution adapter (API or CLI), and records the result including exit code, cost, and token usage. Failed runs trigger retry logic with exponential backoff.
-
-**ChannelRegistry** manages channel adapter connections. Register adapters (Slack, Discord, webhook) with their config, then call `start()` to connect them all. Supports hot reconfiguration, health checks, and graceful shutdown.
-
-**MessagePipeline** routes inbound messages from channels to the task queue. It resolves the sender to a user identity, picks the right agent based on channel bindings, applies policy checks (allowlists, mention gates), and creates a task for the assigned agent.
-
-**Scheduler** provides database-backed job scheduling with cron expressions. Register recurring or one-time schedules that emit hook events when they fire. The scheduler polls for due jobs and emits the schedule's `action` as a hook event with its configured payload.
-
-## Documentation
-
-- [Getting Started](docs/getting-started.md) -- Installation, project setup, first bot
-- [Configuration](docs/configuration.md) -- Full config reference
-- [Architecture](docs/architecture.md) -- System design and patterns
-- [Providers](docs/providers.md) -- LLM provider setup and custom providers
-- [Channels](docs/channels.md) -- Channel adapter setup and custom adapters
-- [Orchestration](docs/orchestration.md) -- Agents, tasks, workflows, and budget controls
-- [API Reference](docs/api-reference.md) -- Complete API documentation
-
-## License
-
-MIT
+# Bot in a Box
+
+A modular TypeScript framework for building multi-agent bots with LLM orchestration, multi-channel messaging, and task automation.
+
+## Features
+
+- **Execution engine** -- Generic task executor with 22 built-in tools and a tool loop (up to 5 iterations). Agents can read files, send documents, dispatch tasks, search conversations, and more. Apps register tools declaratively.
+- **22 built-in tools** -- File ops (send, read, list, register), task ops (dispatch, cancel, reassign), system status (task, agent, system, active tasks), entity lookup (agents, projects, agent detail), messaging (send message, task comment, read/search conversation), management (create agent, create project). All channel-agnostic.
+- **Chat pipeline** -- Configurable 6-layer chat orchestration: dedup, storage, fast ack (<2s via Haiku), async interpretation, task dispatch, and completion response. Apps provide system prompt and routing rules; framework handles everything else.
+- **Slack integration** -- `SlackBoltAdapter` handles Bolt Socket Mode, message parsing, response delivery, and file uploads. One import, one `start()` call.
+- **Unified config** -- All settings in one `botinabox.config.yml`: models, execution, chat, routing, safety, budget. YAML with env var interpolation. Auto-initializes with sensible defaults.
+- **Message store** -- Store-before-respond guarantee. Inbound messages and attachments stored before any bot response. Channel history for conversation context.
+- **Message interpretation** -- Async structured extraction from messages into tasks, memories, files, and user context. Pluggable extractors for custom data types. Programmatic task creation (no LLM dependency).
+- **Triage routing** -- Content-aware message routing with keyword/regex matching, priority rules, and LLM fallback. Ownership chain logging for every routing decision.
+- **Multi-agent orchestration** -- Define agents with different models, roles, and execution adapters. Task queue with priority scheduling, retry policies, and followup chains.
+- **Loop detection and circuit breakers** -- Pattern-based loop detection (self-loops, ping-pong, blocked re-entry) plus circuit breakers with automatic human escalation.
+- **Learning pipeline** -- Structured feedback capture with auto-promotion: 3+ similar records become a playbook, 3+ agents become a reusable skill.
+- **Governance gates** -- Independent QA, quality, and drift gates that validate agent output and report to the human operator.
+- **Permission relay** -- Remote approval via messaging platforms (Slack, Discord, Telegram). Dual approval: local + remote, first wins.
+- **LLM provider abstraction** -- Swap between Anthropic, OpenAI, and Ollama. Model aliasing, purpose-based routing, fallback chains. Default LLM call wrapper included.
+- **Channel adapters** -- Slack (Bolt Socket Mode), Discord, and webhooks. Auto-discovery, session management, notification queuing.
+- **Workflow engine** -- Multi-step workflows with dependency resolution, parallel execution, and conditional branching.
+- **SQLite data layer** -- 27 core tables, migrations, entity context rendering via [latticesql](https://github.com/automated-industries/lattice). WAL mode.
+- **Event-driven hooks** -- Priority-ordered, filter-based event bus for decoupled communication.
+- **Budget controls** -- Per-agent and global cost tracking with warning thresholds and hard stops.
+- **Scheduling** -- Database-backed cron and one-time schedules.
+- **Connectors** -- Google Gmail, Calendar, and Drive via OAuth2 and service account.
+- **Security** -- Input sanitization, field length enforcement, audit logging, HMAC webhook verification.
+
+## Install
+
+```bash
+npm install botinabox
+```
+
+Install peer dependencies for the providers you need:
+
+```bash
+# For Anthropic
+npm install @anthropic-ai/sdk
+
+# For OpenAI
+npm install openai
+
+# For Google connectors
+npm install googleapis
+```
+
+## Quick Start
+
+```typescript
+import {
+  HookBus, DataStore, defineCoreTables, initConfig,
+  TaskQueue, RunManager, WakeupQueue, ChatPipeline,
+  registerExecutionEngine, createDefaultLLMCall,
+  sendFileTool, readFileTool, listAgentsTool, getTaskStatusTool,
+} from 'botinabox';
+import { SlackBoltAdapter } from 'botinabox/slack';
+import Anthropic from '@anthropic-ai/sdk';
+
+// 1. Config (auto-loads botinabox.config.yml or uses defaults)
+initConfig({});
+const hooks = new HookBus();
+const db = new DataStore({ dbPath: './data/bot.db', wal: true, hooks });
+defineCoreTables(db);
+await db.init();
+
+// 2. Orchestration
+const tasks = new TaskQueue(db, hooks);
+const runs = new RunManager(db, hooks);
+const wakeups = new WakeupQueue(db);
+
+// 3. Execution engine with built-in tools
+const client = new Anthropic();
+await registerExecutionEngine({
+  db, hooks, runs,
+  config: {
+    client,
+    tools: [sendFileTool, readFileTool, listAgentsTool, getTaskStatusTool],
+  },
+});
+
+// 4. Chat pipeline (6-layer: dedup → ack → interpret → dispatch → execute → respond)
+const llmCall = createDefaultLLMCall(client);
+const pipeline = new ChatPipeline(db, hooks, {
+  llmCall, tasks, wakeups,
+  systemPrompt: 'You are a helpful AI assistant.',
+  routingRules: [{ agentSlug: 'assistant', keywords: ['help'] }],
+  fallbackAgent: 'assistant',
+});
+
+// 5. Slack (one import, one start)
+const slack = new SlackBoltAdapter({
+  botToken: process.env.SLACK_BOT_TOKEN!,
+  appToken: process.env.SLACK_APP_TOKEN!,
+  hooks, pipeline,
+});
+await slack.start();
+tasks.startPolling();
+```
+
+## Subpath Exports
+
+| Import path | Description |
+|---|---|
+| `botinabox` | Core framework -- HookBus, DataStore, ChatPipeline, ExecutionEngine, 22 built-in tools, config (loadConfig/getConfig), AgentRegistry, TaskQueue, RunManager, Scheduler, MessageStore, ChatResponder, MessageInterpreter, TriageRouter, createDefaultLLMCall, buildSystemContext, and all shared types |
+| `botinabox/anthropic` | Anthropic Claude provider (`createAnthropicProvider`) |
+| `botinabox/openai` | OpenAI GPT provider (`createOpenAIProvider`) |
+| `botinabox/ollama` | Ollama local model provider (`createOllamaProvider`) |
+| `botinabox/slack` | Slack channel adapter (`SlackAdapter`) |
+| `botinabox/discord` | Discord channel adapter (`DiscordAdapter`) |
+| `botinabox/webhook` | Webhook channel adapter with HMAC verification (`WebhookAdapter`) |
+| `botinabox/google` | Google connectors -- Gmail, Calendar, and Drive via OAuth2 |
+
+## Architecture
+
+```
+                    +-------------------------------------+
+                    |           Channel Adapters           |
+                    |     Slack  .  Discord  .  Webhook    |
+                    +--------------+-----------------------+
+                                   | InboundMessage
+                    +--------------v-----------------------+
+                    |         Message Pipeline              |
+                    |   routing . policies . sessions       |
+                    +--------------+-----------------------+
+                                   | Task
+                    +--------------v-----------------------+
+                    |          Task Queue                   |
+                    |  priority . retry . followup chains   |
+                    +--------------+-----------------------+
+                                   |
+                    +--------------v-----------------------+
+                    |          Run Manager                  |
+                    |    locking . retries . cost tracking  |
+                    +--------------+-----------------------+
+                                   |
+              +--------------------+--------------------+
+              v                    v                    v
+    +------------------+  +------------------+  +------------------+
+    |  CLI Adapter      |  |  API Adapter      |  |  Deterministic   |
+    |  (subprocess)     |  |  (LLM + tools)    |  |  (no LLM)        |
+    +------------------+  +--------+----------+  +------------------+
+                                   |
+                    +--------------v-----------------------+
+                    |         LLM Layer                     |
+                    |  ProviderRegistry . ModelRouter        |
+                    |  BudgetController . Tool Loop          |
+                    +--------------+-----------------------+
+                                   |
+              +--------------------+-------------------+
+              v                    v                   v
+    +---------------+    +---------------+    +---------------+
+    |  Anthropic     |    |  OpenAI        |    |  Ollama        |
+    +---------------+    +---------------+    +---------------+
+```
+
+Cross-cutting concerns -- **HookBus** (events), **DataStore** (persistence), **Security** (sanitization + audit) -- connect all layers.
+
+## Core Concepts
+
+**HookBus** is the central event bus. Handlers subscribe to named events with optional priority ordering and payload filters. Errors in one handler never block others. Use it to decouple layers -- the task queue emits `task.created`, the run manager emits `run.completed`, channels emit `message.inbound`, and your application code listens to whichever events it needs.
+
+**DataStore** wraps [latticesql](https://github.com/automated-industries/lattice) to provide schema-driven SQLite persistence. You call `db.define()` to register table schemas, then `db.init()` to create them. It supports insert, update, upsert, get, query, delete, and migrations. WAL mode is enabled by default for concurrent read access.
+
+**AgentRegistry** manages the lifecycle of agents -- registration, status transitions (idle/running/paused/terminated), configuration revisions, and activity logging. Each agent has a slug, name, adapter type, role, and optional budget. Agents are stored in the database and can be seeded from config on startup.
+
+**TaskQueue** is a priority-ordered work queue backed by SQLite. Tasks have a title, description, assignee, priority (1-10), and support retry policies and followup chains. Chain depth is enforced to prevent infinite recursion. The queue emits `task.created` on the HookBus and supports polling for stale tasks.
+
+**RunManager** handles task execution lifecycle. It acquires a per-agent lock, creates a run record, delegates to an execution adapter (API or CLI), and records the result including exit code, cost, and token usage. Failed runs trigger retry logic with exponential backoff.
+
+**ChannelRegistry** manages channel adapter connections. Register adapters (Slack, Discord, webhook) with their config, then call `start()` to connect them all. Supports hot reconfiguration, health checks, and graceful shutdown.
+
+**MessagePipeline** routes inbound messages from channels to the task queue. It resolves the sender to a user identity, picks the right agent based on channel bindings, applies policy checks (allowlists, mention gates), and creates a task for the assigned agent.
+
+**Scheduler** provides database-backed job scheduling with cron expressions. Register recurring or one-time schedules that emit hook events when they fire. The scheduler polls for due jobs and emits the schedule's `action` as a hook event with its configured payload.
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) -- Installation, project setup, first bot
+- [Configuration](docs/configuration.md) -- Full config reference
+- [Architecture](docs/architecture.md) -- System design and patterns
+- [Providers](docs/providers.md) -- LLM provider setup and custom providers
+- [Channels](docs/channels.md) -- Channel adapter setup and custom adapters
+- [Orchestration](docs/orchestration.md) -- Agents, tasks, workflows, and budget controls
+- [API Reference](docs/api-reference.md) -- Complete API documentation
+
+## License
+
+MIT

package/bin/botinabox.mjs

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import('../dist/cli.js').then(m => m.main(process.argv.slice(2)));
+import('../dist/cli.js').then(m => m.main(process.argv.slice(2)));

package/dist/channel-DziSPayj.d.ts

@@ -0,0 +1,73 @@
+/** 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[];
+    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,4 @@
-import { C as ChannelAdapter, c as ChannelMeta, a as ChannelCapabilities, I as InboundMessage, b as ChannelConfig, H as HealthStatus, O as OutboundPayload, S as SendResult } from '../../channel-06G0vbIn.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-DziSPayj.js';
 
 /**
  * DiscordAdapter — ChannelAdapter implementation for Discord.

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

@@ -1,7 +1,7 @@
-import { C as ChannelAdapter, c as ChannelMeta, a as ChannelCapabilities, I as InboundMessage, b as ChannelConfig, H as HealthStatus, O as OutboundPayload, S as SendResult } from '../../channel-06G0vbIn.js';
-import { H as HookBus, c as ChatPipeline } from '../../chat-pipeline-DuNX5WoL.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-DziSPayj.js';
+import { H as HookBus, c as ChatPipeline } from '../../chat-pipeline-BGgmH_ap.js';
 import 'better-sqlite3';
-import '../../provider-DLGUfnNx.js';
+import '../../provider-BHkqkSdq.js';
 
 /**
  * SlackAdapter — ChannelAdapter implementation for Slack.
@@ -162,6 +162,27 @@ interface SlackConfig {
     signingSecret?: string;
 }
 
+/**
+ * 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
+ */
+type AttachmentEnricher = (attachment: Attachment, botToken: string) => Promise<string | null>;
+/**
+ * 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).
+ */
+type AttachmentEnricherMap = Partial<Record<AttachmentMediaType, AttachmentEnricher>>;
+/** Internal: the result of running enrichAttachments on a message. */
+interface EnrichedMessage extends InboundMessage {
+    body: string;
+}
+
 /**
  * SlackBoltAdapter — real Bolt Socket Mode integration for botinabox.
  *
@@ -181,6 +202,8 @@ interface SlackBoltAdapterConfig {
     appToken: string;
     hooks: HookBus;
     pipeline: ChatPipeline;
+    /** Optional per-type attachment enrichers. */
+    attachmentEnrichers?: AttachmentEnricherMap;
 }
 declare class SlackBoltAdapter {
     private app;
@@ -190,4 +213,52 @@ declare class SlackBoltAdapter {
     stop(): Promise<void>;
 }
 
-export { type BoltClient, SlackAdapter, SlackBoltAdapter, type SlackBoltAdapterConfig, type SlackConfig, type SlackEvent, type SlackFile, type TranscribeOptions, type TranscribeResult, createSlackAdapter as default, downloadAudio, enrichVoiceMessage, extractVoiceTranscript, formatForSlack, parseSlackEvent, transcribeAudio };
+/**
+ * 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:
+ *
+ *     <original body>
+ *
+ *     [Attached: invoice.pdf]
+ *     <extracted content>
+ */
+declare function enrichAttachments(msg: InboundMessage, botToken: string, 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.
+ *
+ * Consumer must provide an Anthropic API key. The Anthropic SDK is a peer
+ * dependency of botinabox — the consumer must have it installed.
+ */
+declare function createImageEnricher(config: ImageEnricherConfig): 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+.
+ */
+declare function createPdfEnricher(config: PdfEnricherConfig): 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 };