botinabox 0.6.0 → 1.0.0

package/README.md

@@ -4,173 +4,248 @@ A modular TypeScript framework for building multi-agent bots with LLM orchestrat
 
 ## 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 via [latticesql](https://github.com/automated-industries/lattice). 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.
-- **Scheduling** -- Database-backed cron and one-time schedules that fire hook events.
-- **Google connectors** -- Gmail and Calendar integration via OAuth2.
-- **Security** -- Input sanitization, field length enforcement, audit logging, and HMAC webhook verification.
-
-## Install
+- **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.
+- **Protected primitives** — Users and secrets are first-class, privacy-isolated objects. User identity resolution across channels. Secrets with optional AES-256-GCM at-rest encryption.
+- **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
-npm install botinabox
+git clone https://github.com/automated-industries/botinabox.git
+cd botinabox
+pnpm install
+pnpm build
 ```
 
-Install peer dependencies for the providers you need:
+### Create a Project
 
 ```bash
-# For Anthropic
-npm install @anthropic-ai/sdk
+npx botinabox init my-bot
+cd my-bot
+```
 
-# For OpenAI
-npm install openai
+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`:
 
-# For Google connectors
-npm install googleapis
+```bash
+ANTHROPIC_API_KEY=your_key_here
+SLACK_BOT_TOKEN=xoxb-your-token
 ```
 
-## Quick Start
+### Run
 
 ```typescript
-import {
-  HookBus,
-  DataStore,
-  defineCoreTables,
-  AgentRegistry,
-  TaskQueue,
-  RunManager,
-} from 'botinabox';
-
-// 1. Create core services
+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: './data/bot.db', wal: true, hooks });
-
-// 2. Define tables and initialize
+const db = new DataStore({ dbPath: config.data.path, wal: config.data.walMode, hooks });
 defineCoreTables(db);
-await db.init();
+db.init();
 
-// 3. Set up orchestration
+// 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);
 
-// 4. Register an agent
-const agentId = await agents.register({
-  slug: 'assistant',
-  name: 'Assistant',
-  adapter: 'api',
-  role: 'general',
-});
-
-// 5. Listen for task creation
-hooks.register('task.created', async (ctx) => {
-  console.log(`Task created: ${ctx.taskId}`);
-});
-
-// 6. Create a task
-const taskId = await tasks.create({
-  title: 'Summarize the quarterly report',
-  description: 'Read the Q4 report and produce a 3-paragraph summary.',
-  assignee_id: agentId,
-  priority: 3,
-});
-
-// 7. Wire up task completion hooks
-hooks.register('run.completed', async (ctx) => {
-  console.log(`Run finished for task ${ctx.taskId}, exit code: ${ctx.exitCode}`);
-});
+// Start
+tasks.startPolling();
+await channels.start();
 ```
 
-## Subpath Exports
-
-| Import path | Description |
-|---|---|
-| `botinabox` | Core framework -- HookBus, DataStore, AgentRegistry, TaskQueue, RunManager, ChannelRegistry, MessagePipeline, Scheduler, config, security, 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 and Calendar 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      |  |  Custom       |
-    |  (subprocess)     |  |  (LLM + tools)    |  |  Adapters     |
-    +------------------+  +--------+----------+  +---------------+
-                                   |
-                    +--------------v-----------------------+
-                    |         LLM Layer                     |
-                    |  ProviderRegistry . ModelRouter        |
-                    |  BudgetController . Tool Loop          |
-                    +--------------+-----------------------+
-                                   |
-              +--------------------+-------------------+
-              v                    v                   v
-    +---------------+    +---------------+    +---------------+
-    |  Anthropic     |    |  OpenAI        |    |  Ollama        |
-    +---------------+    +---------------+    +---------------+
+                    ┌─────────────────────────────────────┐
+                    │           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.
+Cross-cutting concerns — **HookBus** (events), **DataStore** (persistence), **Security** (sanitization + audit) — connect all layers.
 
-## Core Concepts
+## Documentation
 
-**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.
+- [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
 
-**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.
+## Development
 
-**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.
+```bash
+# Install dependencies
+pnpm install
 
-**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.
+# Build all packages
+pnpm build
 
-**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.
+# Run all tests
+pnpm test:run
 
-**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.
+# Type-check
+pnpm typecheck
+```
 
-**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.
+### Project Structure
 
-**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.
+```
+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
+```
 
-## Documentation
+## Staying up to date
+
+**CLI users:** The `botinabox` CLI checks for new versions automatically and prints a notice when an update is available. Run `botinabox update` to upgrade in place. Alternatively, use `npx botinabox` to always run the latest version without a global install.
 
-- [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
+**Library consumers:** By default, `npm install botinabox` adds a `^` semver range to your `package.json`, so patch and minor updates are picked up on your next `npm install`. For fully automated dependency updates, set up [Dependabot](https://docs.github.com/en/code-security/dependabot) or [Renovate](https://github.com/renovatebot/renovate) — they'll create PRs in your repo whenever a new version is published.
 
 ## License
 

package/dist/index.d.ts

@@ -305,6 +305,7 @@ declare const EVENTS: {
 declare const DEFAULTS: {
     readonly TASK_POLL_INTERVAL_MS: 30000;
     readonly NOTIFICATION_POLL_INTERVAL_MS: 5000;
+    readonly HEARTBEAT_INTERVAL_MS: 300000;
     readonly ORPHAN_REAP_INTERVAL_MS: 300000;
     readonly STALE_RUN_THRESHOLD_MS: 1800000;
     readonly STALE_TASK_AGE_MS: 7200000;
@@ -1319,6 +1320,23 @@ declare class NdjsonLogger {
     close(): void;
 }
 
+/**
+ * @deprecated Use {@link Scheduler} from `botinabox` instead.
+ * HeartbeatScheduler uses in-memory setInterval which loses state on restart.
+ * The Scheduler class uses database-backed schedules with cron expressions.
+ */
+declare class HeartbeatScheduler {
+    private wakeupQueue;
+    private hooks;
+    private timers;
+    constructor(wakeupQueue: WakeupQueue, hooks: HookBus);
+    start(agents: Array<{
+        id: string;
+        heartbeat_config: string;
+    }>): void;
+    stop(): void;
+}
+
 /**
  * Scheduler — database-backed job scheduling with cron expressions.
  *
@@ -1326,7 +1344,7 @@ declare class NdjsonLogger {
  * it emits the schedule's `action` as a hook event with the
  * `action_config` payload. Consumers subscribe to handle the action.
  *
- * Supports one-time and recurring use cases.
+ * Replaces HeartbeatScheduler for recurring use cases.
  */
 
 interface ScheduleDef {
@@ -1549,4 +1567,4 @@ declare function isLoginRequired(stdout: string): boolean;
 /** Rewrite local image paths to prevent CLI auto-embedding as vision content. */
 declare function deactivateLocalImagePaths(prompt: string): string;
 
-export { AGENT_STATUSES, type AgentConfig, type AgentDefinition, type AgentFilter, type AgentRecord, AgentRegistry, type AgentStatus, ApiExecutionAdapter, AuditEmitter, type AuditEvent, BackupManager, type BotConfig, type BudgetCheck, type BudgetConfig, BudgetController, CORE_MIGRATIONS, ChannelAdapter, ChannelRegistry, ChannelRegistryError, ChatMessage, ChatSessionManager, CliExecutionAdapter, type ColumnValidator, ColumnValidatorImpl, type ConfigLoadError, type ConfigLoadResult, ConnectorConfig, DEFAULTS, DEFAULT_CONFIG, type DataConfig, DataStore, DataStoreError, type DomainEntityContextOptions, type DomainSchemaOptions, EVENTS, type EntityColumnDef, type EntityConfig, type EntityContextDef, type EntityFileSpec, type EntitySource, type ExecutionAdapter, type Filter, HealthStatus, HookBus, type HookHandler, type HookOptions, type HookRegistration, InboundMessage, LLMProvider, MAX_CHAIN_DEPTH, MessagePipeline, type ModelConfig, ModelInfo, ModelRouter, NdjsonLogger, NotificationQueue, type PackageMigration, type PackageUpdate, type ParsedStream, type PkLookup, ProviderRegistry, type QueryOptions, RUN_STATUSES, type RelationDef, type RenderConfig, ResolvedModel, type RetryPolicy, type Row, type RunContext, RunManager, type RunResult, type RunStatus, type SanitizerOptions, type Schedule, type ScheduleDef, Scheduler, type SchemaError, type SecretInput, type SecretMeta, SecretStore, type SecurityConfig, type SeedItem, SessionKey, SessionManager, type SqliteAdapter, type StepRef, TASK_STATUSES, type TableDefinition, type TableInfoRow, type TaskDefinition, TaskQueue, type TaskRecord, type TaskStatus, TokenUsage, type Unsubscribe, UpdateChecker, type UpdateConfig, UpdateManager, type UpdateManifest, type UsageSummary, type User, type UserInput, UserRegistry, WakeupQueue, type WorkflowConfigEntry, type WorkflowDefinition$1 as WorkflowDefinition, WorkflowEngine, type WorkflowRunRecord, type WorkflowRunStatus, type WorkflowStep$1 as WorkflowStep, type WorkflowStepConfig, type WorkflowTrigger, _resetConfig, areDependenciesMet, buildAgentBindings, buildChainOrigin, buildProcessEnv, checkAllowlist, checkChainDepth, checkMentionGate, chunkText, classifyUpdate, compareVersions, createConfigRevision, deactivateLocalImagePaths, defineCoreEntityContexts, defineCoreTables, defineDomainEntityContexts, defineDomainTables, detectCycle, discoverChannels, discoverProviders, formatText, getConfig, initConfig, interpolate, interpolateEnv, isLoginRequired, isMaxTurns, loadConfig, parseClaudeStream, parseVersion, runPackageMigrations, sanitize, topologicalSort, validateConfig };
+export { AGENT_STATUSES, type AgentConfig, type AgentDefinition, type AgentFilter, type AgentRecord, AgentRegistry, type AgentStatus, ApiExecutionAdapter, AuditEmitter, type AuditEvent, BackupManager, type BotConfig, type BudgetCheck, type BudgetConfig, BudgetController, CORE_MIGRATIONS, ChannelAdapter, ChannelRegistry, ChannelRegistryError, ChatMessage, ChatSessionManager, CliExecutionAdapter, type ColumnValidator, ColumnValidatorImpl, type ConfigLoadError, type ConfigLoadResult, ConnectorConfig, DEFAULTS, DEFAULT_CONFIG, type DataConfig, DataStore, DataStoreError, type DomainEntityContextOptions, type DomainSchemaOptions, EVENTS, type EntityColumnDef, type EntityConfig, type EntityContextDef, type EntityFileSpec, type EntitySource, type ExecutionAdapter, type Filter, HealthStatus, HeartbeatScheduler, HookBus, type HookHandler, type HookOptions, type HookRegistration, InboundMessage, LLMProvider, MAX_CHAIN_DEPTH, MessagePipeline, type ModelConfig, ModelInfo, ModelRouter, NdjsonLogger, NotificationQueue, type PackageMigration, type PackageUpdate, type ParsedStream, type PkLookup, ProviderRegistry, type QueryOptions, RUN_STATUSES, type RelationDef, type RenderConfig, ResolvedModel, type RetryPolicy, type Row, type RunContext, RunManager, type RunResult, type RunStatus, type SanitizerOptions, type Schedule, type ScheduleDef, Scheduler, type SchemaError, type SecretInput, type SecretMeta, SecretStore, type SecurityConfig, type SeedItem, SessionKey, SessionManager, type SqliteAdapter, type StepRef, TASK_STATUSES, type TableDefinition, type TableInfoRow, type TaskDefinition, TaskQueue, type TaskRecord, type TaskStatus, TokenUsage, type Unsubscribe, UpdateChecker, type UpdateConfig, UpdateManager, type UpdateManifest, type UsageSummary, type User, type UserInput, UserRegistry, WakeupQueue, type WorkflowConfigEntry, type WorkflowDefinition$1 as WorkflowDefinition, WorkflowEngine, type WorkflowRunRecord, type WorkflowRunStatus, type WorkflowStep$1 as WorkflowStep, type WorkflowStepConfig, type WorkflowTrigger, _resetConfig, areDependenciesMet, buildAgentBindings, buildChainOrigin, buildProcessEnv, checkAllowlist, checkChainDepth, checkMentionGate, chunkText, classifyUpdate, compareVersions, createConfigRevision, deactivateLocalImagePaths, defineCoreEntityContexts, defineCoreTables, defineDomainEntityContexts, defineDomainTables, detectCycle, discoverChannels, discoverProviders, formatText, getConfig, initConfig, interpolate, interpolateEnv, isLoginRequired, isMaxTurns, loadConfig, parseClaudeStream, parseVersion, runPackageMigrations, sanitize, topologicalSort, validateConfig };

package/dist/index.js

@@ -35,6 +35,8 @@ var EVENTS = {
 var DEFAULTS = {
   TASK_POLL_INTERVAL_MS: 3e4,
   NOTIFICATION_POLL_INTERVAL_MS: 5e3,
+  HEARTBEAT_INTERVAL_MS: 3e5,
+  // 5 minutes
   ORPHAN_REAP_INTERVAL_MS: 3e5,
   // 5 minutes
   STALE_RUN_THRESHOLD_MS: 18e5,
@@ -1153,17 +1155,15 @@ var DataStore = class {
         outputFile: def.indexFile,
         render: def.indexRender ?? ((rows) => {
           const active = rows.filter((r) => r.deleted_at == null);
-          const dir = def.directory;
-          const title = dir.charAt(0).toUpperCase() + dir.slice(1);
+          const title = def.directory.charAt(0).toUpperCase() + def.directory.slice(1);
           if (!active.length) return `# ${title}
 
 None.
 `;
           const lines = active.map((r) => {
-            const slug = String(r[def.slugColumn] ?? r.name ?? r.id ?? "unknown");
-            const name2 = String(r.name ?? slug);
+            const name2 = String(r.name ?? r[def.slugColumn] ?? r.id ?? "unknown");
             const status = r.status ? ` (${r.status})` : "";
-            return `- [${name2}](${dir}/${slug}/)${status}`;
+            return `- **${name2}**${status}`;
           });
           return `# ${title}
 
@@ -3406,6 +3406,38 @@ var NdjsonLogger = class {
   }
 };
 
+// src/core/orchestrator/heartbeat-scheduler.ts
+var HeartbeatScheduler = class {
+  constructor(wakeupQueue, hooks) {
+    this.wakeupQueue = wakeupQueue;
+    this.hooks = hooks;
+  }
+  wakeupQueue;
+  hooks;
+  timers = /* @__PURE__ */ new Map();
+  start(agents) {
+    for (const agent of agents) {
+      let config;
+      try {
+        config = JSON.parse(agent.heartbeat_config);
+      } catch {
+        continue;
+      }
+      if (!config.enabled || !config.intervalSec) continue;
+      const timer = setInterval(() => {
+        void this.wakeupQueue.enqueue(agent.id, "heartbeat");
+      }, config.intervalSec * 1e3);
+      this.timers.set(agent.id, timer);
+    }
+  }
+  stop() {
+    for (const timer of this.timers.values()) {
+      clearInterval(timer);
+    }
+    this.timers.clear();
+  }
+};
+
 // src/core/orchestrator/scheduler.ts
 import cronParser from "cron-parser";
 import { v4 as uuid } from "uuid";
@@ -4160,6 +4192,7 @@ export {
   DataStore,
   DataStoreError,
   EVENTS,
+  HeartbeatScheduler,
   HookBus,
   MAX_CHAIN_DEPTH,
   MessagePipeline,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botinabox",
-  "version": "0.6.0",
+  "version": "1.0.0",
   "description": "Bot in a Box — framework for building multi-agent bots",
   "type": "module",
   "main": "./dist/index.js",
@@ -59,7 +59,7 @@
     "@types/uuid": "^10.0.0",
     "ajv": "^8.17.1",
     "cron-parser": "^4.9.0",
-    "latticesql": "^0.18.0",
+    "latticesql": "^1.0.0",
     "uuid": "^13.0.0",
     "yaml": "^2.7.0"
   },