botinabox 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+Thanks for your interest in contributing to Bot in a Box.
+
+## Development Setup
+
+```bash
+git clone https://github.com/automated-industries/botinabox.git
+cd botinabox
+pnpm install
+pnpm build
+```
+
+## Project Structure
+
+This is a pnpm monorepo. Packages are in `packages/`:
+
+- `shared/` — Types and constants (zero dependencies)
+- `core/` — Core framework
+- `cli/` — CLI scaffolding tool
+- `providers/` — LLM provider adapters
+- `channels/` — Messaging channel adapters
+
+## Running Tests
+
+```bash
+# All packages
+pnpm test:run
+
+# Single package
+cd packages/core && pnpm test
+```
+
+Tests use [Vitest](https://vitest.dev/). Each package has its own `vitest.config.ts`.
+
+## Building
+
+```bash
+# All packages
+pnpm build
+
+# Single package
+cd packages/core && pnpm build
+```
+
+Build uses [tsup](https://tsup.egoist.dev/) targeting ESM with declaration files.
+
+## Type Checking
+
+```bash
+pnpm typecheck
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (`"type": "module"`)
+- ES2022 target
+- No default exports except for provider/channel factory functions
+
+## Making Changes
+
+1. Create a branch from `main`
+2. Make your changes
+3. Add or update tests
+4. Run `pnpm test:run` and `pnpm typecheck`
+5. Open a pull request
+
+## Adding a Provider
+
+1. Create `packages/providers/your-provider/`
+2. Implement the `LLMProvider` interface from `@botinabox/shared`
+3. Export a default factory function
+4. Add `"botinabox": { "type": "provider" }` to `package.json`
+5. Add tests
+
+## Adding a Channel Adapter
+
+1. Create `packages/channels/your-channel/`
+2. Implement the `ChannelAdapter` interface from `@botinabox/shared`
+3. Export a default factory function
+4. Add `"botinabox": { "type": "channel" }` to `package.json`
+5. Add tests
+
+## Reporting Issues
+
+Open an issue on GitHub with:
+
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- Node.js and pnpm versions

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,245 @@
+# Bot in a Box
+
+A modular TypeScript framework for building multi-agent bots with LLM orchestration, multi-channel messaging, and task automation.
+
+## Features
+
+- **Multi-agent orchestration** — Define agents with different models, roles, and execution adapters. Task queue with priority scheduling, retry policies, and followup chains.
+- **LLM provider abstraction** — Swap between Anthropic, OpenAI, and Ollama with a unified interface. Model aliasing, purpose-based routing, and fallback chains.
+- **Channel adapters** — Connect to Slack, Discord, and webhooks. Auto-discovery, session management, and notification queuing.
+- **Workflow engine** — Define multi-step workflows with dependency resolution, parallel execution, and conditional branching.
+- **SQLite data layer** — Schema-driven tables, migrations, entity context rendering, and query builder. WAL mode for concurrent reads.
+- **Event-driven hooks** — Priority-ordered, filter-based event bus for decoupled inter-layer communication.
+- **Budget controls** — Per-agent and global cost tracking with warning thresholds and hard stops.
+- **Security** — Input sanitization, field length enforcement, audit logging, and HMAC webhook verification.
+- **Self-updating** — Built-in update checker with configurable policies and maintenance windows.
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@botinabox/core`](packages/core) | Core framework — config, data, hooks, LLM, orchestration, chat, security |
+| [`@botinabox/shared`](packages/shared) | Shared types, interfaces, and constants (zero dependencies) |
+| [`@botinabox/cli`](packages/cli) | CLI tool for scaffolding new projects |
+| [`@botinabox/provider-anthropic`](packages/providers/anthropic) | Anthropic Claude provider |
+| [`@botinabox/provider-openai`](packages/providers/openai) | OpenAI GPT provider |
+| [`@botinabox/provider-ollama`](packages/providers/ollama) | Ollama local model provider |
+| [`@botinabox/channel-slack`](packages/channels/slack) | Slack channel adapter |
+| [`@botinabox/channel-discord`](packages/channels/discord) | Discord channel adapter |
+| [`@botinabox/channel-webhook`](packages/channels/webhook) | Webhook channel adapter with HMAC verification |
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 20+
+- pnpm 9+
+
+### Install
+
+```bash
+git clone https://github.com/automated-industries/botinabox.git
+cd botinabox
+pnpm install
+pnpm build
+```
+
+### Create a Project
+
+```bash
+npx botinabox init my-bot
+cd my-bot
+```
+
+This generates a project with a config file, environment template, and entry point.
+
+### Configure
+
+Edit `botinabox.config.yml`:
+
+```yaml
+data:
+  path: ./data/bot.db
+  walMode: true
+
+channels:
+  slack:
+    enabled: true
+    botToken: ${SLACK_BOT_TOKEN}
+
+providers:
+  anthropic:
+    enabled: true
+    apiKey: ${ANTHROPIC_API_KEY}
+
+agents:
+  - slug: assistant
+    name: Assistant
+    adapter: api
+    model: smart
+
+models:
+  default: claude-sonnet-4-6
+  aliases:
+    fast: claude-haiku-4-5
+    smart: claude-opus-4-6
+    balanced: claude-sonnet-4-6
+  routing:
+    conversation: fast
+    task_execution: smart
+    classification: fast
+  fallbackChain: []
+```
+
+Set environment variables in `.env`:
+
+```bash
+ANTHROPIC_API_KEY=your_key_here
+SLACK_BOT_TOKEN=xoxb-your-token
+```
+
+### Run
+
+```typescript
+import { HookBus } from '@botinabox/core';
+import { loadConfig } from '@botinabox/core';
+import { DataStore, defineCoreTables } from '@botinabox/core';
+import { ProviderRegistry, ModelRouter } from '@botinabox/core';
+import { AgentRegistry, TaskQueue, RunManager } from '@botinabox/core';
+import { ChannelRegistry, MessagePipeline } from '@botinabox/core';
+import createAnthropicProvider from '@botinabox/provider-anthropic';
+import createSlackAdapter from '@botinabox/channel-slack';
+
+// Load config
+const { config } = loadConfig({ configPath: 'botinabox.config.yml' });
+
+// Initialize systems
+const hooks = new HookBus();
+const db = new DataStore({ dbPath: config.data.path, wal: config.data.walMode, hooks });
+defineCoreTables(db);
+db.init();
+
+// LLM providers
+const providers = new ProviderRegistry();
+providers.register(createAnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! }));
+const router = new ModelRouter(providers, config.models);
+
+// Channels
+const channels = new ChannelRegistry();
+channels.register(createSlackAdapter(), config.channels.slack);
+
+// Orchestration
+const agents = new AgentRegistry(db, hooks);
+const tasks = new TaskQueue(db, hooks);
+const runs = new RunManager(db, hooks);
+const pipeline = new MessagePipeline(hooks, agents, tasks, config);
+
+// Start
+tasks.startPolling();
+await channels.start();
+```
+
+## Architecture
+
+```
+                    ┌─────────────────────────────────────┐
+                    │           Channel Adapters           │
+                    │     Slack  ·  Discord  ·  Webhook    │
+                    └──────────────┬──────────────────────┘
+                                   │ InboundMessage
+                    ┌──────────────▼──────────────────────┐
+                    │         Message Pipeline             │
+                    │   routing · policies · sessions      │
+                    └──────────────┬──────────────────────┘
+                                   │ Task
+                    ┌──────────────▼──────────────────────┐
+                    │          Task Queue                  │
+                    │  priority · retry · followup chains  │
+                    └──────────────┬──────────────────────┘
+                                   │
+                    ┌──────────────▼──────────────────────┐
+                    │          Run Manager                 │
+                    │    locking · retries · cost tracking │
+                    └──────────────┬──────────────────────┘
+                                   │
+              ┌────────────────────┼────────────────────┐
+              ▼                    ▼                    ▼
+    ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐
+    │  CLI Adapter     │  │  API Adapter     │  │  Custom       │
+    │  (subprocess)    │  │  (LLM + tools)   │  │  Adapters     │
+    └─────────────────┘  └────────┬─────────┘  └──────────────┘
+                                  │
+                    ┌─────────────▼───────────────────────┐
+                    │         LLM Layer                    │
+                    │  ProviderRegistry · ModelRouter       │
+                    │  CostTracker · Tool Loop              │
+                    └─────────────┬───────────────────────┘
+                                  │
+              ┌───────────────────┼───────────────────┐
+              ▼                   ▼                   ▼
+    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+    │  Anthropic    │    │  OpenAI       │    │  Ollama       │
+    └──────────────┘    └──────────────┘    └──────────────┘
+```
+
+Cross-cutting concerns — **HookBus** (events), **DataStore** (persistence), **Security** (sanitization + audit) — connect all layers.
+
+## 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
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build all packages
+pnpm build
+
+# Run all tests
+pnpm test:run
+
+# Type-check
+pnpm typecheck
+```
+
+### Project Structure
+
+```
+botinabox/
+├── packages/
+│   ├── core/              # Core framework
+│   │   └── src/
+│   │       ├── config/    # YAML config loader + validation
+│   │       ├── data/      # SQLite ORM, migrations, entity rendering
+│   │       ├── hooks/     # Event bus
+│   │       ├── llm/       # Provider registry, model router, cost tracking
+│   │       ├── chat/      # Channel registry, message pipeline, sessions
+│   │       ├── orchestrator/  # Agents, tasks, runs, workflows, adapters
+│   │       ├── security/  # Sanitizer, audit, column validation
+│   │       └── update/    # Self-update system
+│   ├── shared/            # Types and constants (zero deps)
+│   ├── cli/               # CLI scaffolding tool
+│   ├── providers/
+│   │   ├── anthropic/     # Claude models
+│   │   ├── openai/        # GPT models
+│   │   └── ollama/        # Local models
+│   └── channels/
+│       ├── slack/         # Slack adapter
+│       ├── discord/       # Discord adapter
+│       └── webhook/       # Webhook adapter + HMAC
+├── package.json
+├── pnpm-workspace.yaml
+└── tsconfig.json
+```
+
+## License
+
+MIT

package/bin/botinabox.mjs

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

package/dist/channel-m9f7MFD7.d.ts

@@ -0,0 +1,71 @@
+/** 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;
+    body: string;
+    threadId?: string;
+    replyToId?: string;
+    attachments?: Attachment[];
+    receivedAt: string;
+    raw?: unknown;
+}
+interface Attachment {
+    type: "image" | "file" | "audio" | "video";
+    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, ChannelCapabilities as a, ChannelConfig as b, ChannelMeta as c, ChatType as d };

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

@@ -0,0 +1,86 @@
+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-m9f7MFD7.js';
+
+/**
+ * DiscordAdapter — ChannelAdapter implementation for Discord.
+ * Story 4.6
+ */
+
+/** Minimal Discord client interface for mockability. */
+interface DiscordClient {
+    sendMessage(channelId: string, content: string): Promise<{
+        id: string;
+    }>;
+}
+declare class DiscordAdapter implements ChannelAdapter {
+    readonly id = "discord";
+    readonly meta: ChannelMeta;
+    readonly capabilities: ChannelCapabilities;
+    onMessage?: (message: InboundMessage) => Promise<void>;
+    private connected;
+    private config;
+    private client;
+    constructor(client?: DiscordClient);
+    connect(config: ChannelConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    healthCheck(): Promise<HealthStatus>;
+    send(target: {
+        peerId: string;
+        threadId?: string;
+    }, payload: OutboundPayload): Promise<SendResult>;
+    /** Simulate receiving an inbound message (for testing/webhooks). */
+    receive(event: Record<string, unknown>): Promise<void>;
+}
+/** Factory function — default export for auto-discovery. */
+declare function createDiscordAdapter(client?: DiscordClient): DiscordAdapter;
+
+/**
+ * Discord inbound message parsing.
+ * Story 4.6
+ */
+
+interface DiscordEvent {
+    id?: string;
+    channel_id?: string;
+    guild_id?: string;
+    author?: {
+        id?: string;
+        username?: string;
+    };
+    content?: string;
+    message_reference?: {
+        message_id?: string;
+        channel_id?: string;
+    };
+    timestamp?: string;
+    [key: string]: unknown;
+}
+/**
+ * Parse a Discord message event into an InboundMessage.
+ */
+declare function parseDiscordEvent(event: DiscordEvent): InboundMessage;
+
+/**
+ * Discord outbound formatting.
+ * Discord uses native markdown — just enforce the 2000-char limit.
+ * Story 4.6
+ */
+/**
+ * Split text into Discord-compatible chunks (2000 char max each).
+ */
+declare function chunkForDiscord(text: string): string[];
+/**
+ * Discord uses native markdown — no conversion needed.
+ * Returns the text unchanged (Discord renders it natively).
+ */
+declare function formatForDiscord(text: string): string;
+
+/**
+ * Discord channel configuration types.
+ * Story 4.6
+ */
+interface DiscordConfig {
+    token: string;
+    guildId?: string;
+}
+
+export { DiscordAdapter, type DiscordClient, type DiscordConfig, type DiscordEvent, chunkForDiscord, createDiscordAdapter as default, formatForDiscord, parseDiscordEvent };

package/dist/channels/discord/index.js

@@ -0,0 +1,98 @@
+import {
+  parseDiscordEvent
+} from "../../chunk-DLJKZD3Q.js";
+
+// src/channels/discord/outbound.ts
+var DISCORD_MAX_LENGTH = 2e3;
+function chunkForDiscord(text) {
+  if (text.length <= DISCORD_MAX_LENGTH) return [text];
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > DISCORD_MAX_LENGTH) {
+    const slice = remaining.slice(0, DISCORD_MAX_LENGTH);
+    const lastSpace = slice.lastIndexOf(" ");
+    if (lastSpace > 0) {
+      chunks.push(remaining.slice(0, lastSpace));
+      remaining = remaining.slice(lastSpace + 1);
+    } else {
+      chunks.push(remaining.slice(0, DISCORD_MAX_LENGTH));
+      remaining = remaining.slice(DISCORD_MAX_LENGTH);
+    }
+  }
+  if (remaining.length > 0) chunks.push(remaining);
+  return chunks;
+}
+function formatForDiscord(text) {
+  return text;
+}
+
+// src/channels/discord/adapter.ts
+var DiscordAdapter = class {
+  id = "discord";
+  meta = {
+    displayName: "Discord",
+    icon: "https://discord.com/favicon.ico",
+    homepage: "https://discord.com"
+  };
+  capabilities = {
+    chatTypes: ["direct", "group", "channel"],
+    threads: true,
+    reactions: true,
+    editing: true,
+    media: true,
+    polls: false,
+    maxTextLength: 2e3,
+    formattingMode: "markdown"
+  };
+  onMessage;
+  connected = false;
+  config = null;
+  client;
+  constructor(client) {
+    this.client = client ?? null;
+  }
+  async connect(config) {
+    this.config = config;
+    this.connected = true;
+  }
+  async disconnect() {
+    this.connected = false;
+    this.config = null;
+  }
+  async healthCheck() {
+    return { ok: this.connected };
+  }
+  async send(target, payload) {
+    if (!this.connected) {
+      return { success: false, error: "Not connected" };
+    }
+    const text = formatForDiscord(payload.text);
+    if (this.client) {
+      try {
+        const result = await this.client.sendMessage(target.peerId, text);
+        return { success: true, messageId: result.id };
+      } catch (err) {
+        return { success: false, error: String(err) };
+      }
+    }
+    return { success: true };
+  }
+  /** Simulate receiving an inbound message (for testing/webhooks). */
+  async receive(event) {
+    if (this.onMessage) {
+      const { parseDiscordEvent: parseDiscordEvent2 } = await import("../../inbound-SNEMBLGA.js");
+      const msg = parseDiscordEvent2(event);
+      await this.onMessage(msg);
+    }
+  }
+};
+function createDiscordAdapter(client) {
+  return new DiscordAdapter(client);
+}
+export {
+  DiscordAdapter,
+  chunkForDiscord,
+  createDiscordAdapter as default,
+  formatForDiscord,
+  parseDiscordEvent
+};

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

@@ -0,0 +1,81 @@
+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-m9f7MFD7.js';
+
+/**
+ * SlackAdapter — ChannelAdapter implementation for Slack.
+ * Story 4.5
+ */
+
+/** Minimal Bolt-compatible client interface for mockability. */
+interface BoltClient {
+    postMessage(channel: string, text: string, threadTs?: string): Promise<{
+        ok: boolean;
+        ts?: string;
+    }>;
+}
+declare class SlackAdapter implements ChannelAdapter {
+    readonly id = "slack";
+    readonly meta: ChannelMeta;
+    readonly capabilities: ChannelCapabilities;
+    onMessage?: (message: InboundMessage) => Promise<void>;
+    private connected;
+    private config;
+    private client;
+    constructor(client?: BoltClient);
+    connect(config: ChannelConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    healthCheck(): Promise<HealthStatus>;
+    send(target: {
+        peerId: string;
+        threadId?: string;
+    }, payload: OutboundPayload): Promise<SendResult>;
+    /** Simulate receiving an inbound message (for testing/webhooks). */
+    receive(event: Record<string, unknown>): Promise<void>;
+}
+/** Factory function — default export for auto-discovery. */
+declare function createSlackAdapter(client?: BoltClient): SlackAdapter;
+
+/**
+ * Slack inbound message parsing.
+ * Story 4.5
+ */
+
+interface SlackEvent {
+    type: string;
+    client_msg_id?: string;
+    ts?: string;
+    event_ts?: string;
+    channel?: string;
+    user?: string;
+    text?: string;
+    thread_ts?: string;
+    [key: string]: unknown;
+}
+/**
+ * Parse a Slack event into an InboundMessage.
+ */
+declare function parseSlackEvent(event: SlackEvent): InboundMessage;
+
+/**
+ * Slack outbound formatting.
+ * Story 4.5
+ */
+/**
+ * Convert standard markdown to Slack's mrkdwn format.
+ * - **bold** → *bold*
+ * - _italic_ preserved
+ * - `code` preserved
+ * - ```code block``` preserved
+ */
+declare function formatForSlack(text: string): string;
+
+/**
+ * Slack channel configuration types.
+ * Story 4.5
+ */
+interface SlackConfig {
+    botToken: string;
+    appToken?: string;
+    signingSecret?: string;
+}
+
+export { type BoltClient, SlackAdapter, type SlackConfig, type SlackEvent, createSlackAdapter as default, formatForSlack, parseSlackEvent };