botinabox 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1268 @@
+import { C as ChannelAdapter, H as HealthStatus, I as InboundMessage } from './channel-m9f7MFD7.js';
+export { A as Attachment, a as ChannelCapabilities, b as ChannelConfig, c as ChannelMeta, d as ChatType, F as FormattingMode, O as OutboundPayload, S as SendResult } from './channel-m9f7MFD7.js';
+import { T as TokenUsage, L as LLMProvider, M as ModelInfo, R as ResolvedModel, C as ChatMessage } from './provider-qqJYv9nv.js';
+export { a as ChatParams, b as ChatResult, c as ContentBlock, d as ToolDefinition, e as ToolUse } from './provider-qqJYv9nv.js';
+import * as better_sqlite3 from 'better-sqlite3';
+
+/** Execution adapter types — Story 1.5 / 3.4 / 3.5 */
+type RunStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled";
+interface RunContext {
+    runId: string;
+    agentId: string;
+    agentSlug: string;
+    taskId?: string;
+    taskTitle?: string;
+    taskDescription?: string;
+    model: string;
+    workdir: string;
+    sessionParams?: unknown;
+    abortSignal?: AbortSignal;
+    onLog?: (line: string) => void;
+}
+interface RunResult {
+    status: "succeeded" | "failed";
+    output?: string;
+    error?: string;
+    usage?: TokenUsage;
+    costCents?: number;
+    sessionParams?: unknown;
+    clearSession?: boolean;
+    durationMs: number;
+}
+interface ExecutionAdapter {
+    id: string;
+    execute(ctx: RunContext): Promise<RunResult>;
+}
+
+/** Agent types — Story 1.5 / 3.1 */
+type AgentStatus = "idle" | "running" | "paused" | "terminated" | "error";
+interface AgentDefinition {
+    slug: string;
+    name: string;
+    role?: string;
+    adapter: string;
+    model?: string;
+    workdir?: string;
+    instructionsFile?: string;
+    maxConcurrentRuns?: number;
+    budgetMonthlyCents?: number;
+    canCreateAgents?: boolean;
+    skipPermissions?: boolean;
+    config?: Record<string, unknown>;
+}
+interface AgentRecord extends AgentDefinition {
+    id: string;
+    status: AgentStatus;
+    spentMonthlyCents: number;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt?: string;
+}
+interface AgentFilter {
+    status?: AgentStatus | AgentStatus[];
+    role?: string;
+    adapter?: string;
+}
+interface BudgetCheck {
+    allowed: boolean;
+    status: "ok" | "warning" | "hard_stop";
+    spentCents: number;
+    limitCents?: number;
+    message?: string;
+}
+
+/** Task types — Story 1.5 / 3.2 */
+type TaskStatus = "backlog" | "todo" | "in_progress" | "in_review" | "done" | "blocked" | "cancelled";
+interface RetryPolicy {
+    maxRetries: number;
+    backoffMs: number;
+    backoffMultiplier: number;
+    maxBackoffMs: number;
+}
+interface TaskDefinition {
+    title: string;
+    description?: string;
+    assigneeId?: string;
+    priority?: number;
+    parentId?: string;
+    dependsOn?: string[];
+    followupAgentId?: string;
+    followupTemplate?: string;
+    chainOriginId?: string;
+    chainDepth?: number;
+    retryPolicy?: RetryPolicy;
+    metadata?: Record<string, unknown>;
+}
+interface TaskRecord extends Required<Pick<TaskDefinition, "title" | "priority">> {
+    id: string;
+    description: string;
+    assigneeId?: string;
+    status: TaskStatus;
+    priority: number;
+    parentId?: string;
+    dependsOn: string[];
+    followupAgentId?: string;
+    followupTemplate?: string;
+    chainOriginId?: string;
+    chainDepth: number;
+    retryPolicy?: RetryPolicy;
+    retryCount: number;
+    maxRetries: number;
+    nextRetryAt?: string;
+    executionRunId?: string;
+    result?: string;
+    completedOutput?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    deletedAt?: string;
+}
+
+/** Bot configuration types — Story 1.2 / 1.5 */
+interface DataConfig {
+    path: string;
+    walMode: boolean;
+    backupDir?: string;
+}
+interface ModelConfig {
+    aliases: Record<string, string>;
+    default: string;
+    routing: Record<string, string>;
+    fallbackChain: string[];
+    costLimit?: {
+        perRunCents?: number;
+    };
+}
+interface SecurityConfig {
+    fieldLengthLimits?: Record<string, number>;
+    allowedFilePrefixes?: string[];
+}
+interface RenderConfig {
+    outputDir: string;
+    watchIntervalMs: number;
+}
+interface UpdateConfig {
+    policy: "auto-all" | "auto-compatible" | "auto-patch" | "notify" | "manual";
+    checkIntervalMs: number;
+    maintenanceWindow?: {
+        utcHourStart: number;
+        utcHourEnd: number;
+        days?: Array<"mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun">;
+    };
+}
+interface BudgetConfig {
+    globalMonthlyCents?: number;
+    warnPercent: number;
+}
+interface EntityColumnDef {
+    type: "uuid" | "text" | "integer" | "boolean" | "datetime" | "real";
+    required?: boolean;
+    default?: string | number | boolean;
+    references?: string;
+}
+interface EntityConfig {
+    columns: Record<string, EntityColumnDef>;
+    relations?: Array<{
+        type: "hasMany" | "manyToMany" | "belongsTo";
+        table: string;
+        through?: string;
+        localKey?: string;
+        remoteKey?: string;
+    }>;
+}
+interface AgentConfig {
+    slug: string;
+    name: string;
+    role?: string;
+    adapter: string;
+    model?: string;
+    workdir?: string;
+    instructionsFile?: string;
+    maxConcurrentRuns?: number;
+    budgetMonthlyCents?: number;
+    canCreateAgents?: boolean;
+    skipPermissions?: boolean;
+    config?: Record<string, unknown>;
+}
+interface BotConfig {
+    data: DataConfig;
+    channels: Record<string, {
+        enabled: boolean;
+        accounts?: Record<string, unknown>;
+    } & Record<string, unknown>>;
+    agents: AgentConfig[];
+    providers: Record<string, {
+        enabled: boolean;
+    } & Record<string, unknown>>;
+    models: ModelConfig;
+    entities: Record<string, EntityConfig>;
+    security: SecurityConfig;
+    render: RenderConfig;
+    updates: UpdateConfig;
+    budget: BudgetConfig;
+    workflows?: Record<string, WorkflowConfigEntry>;
+}
+interface WorkflowConfigEntry {
+    name: string;
+    description?: string;
+    steps: WorkflowStepConfig[];
+    trigger?: {
+        type: "task_completed" | "event" | "schedule" | "manual";
+        filter?: Record<string, unknown>;
+    };
+}
+interface WorkflowStepConfig {
+    id: string;
+    name: string;
+    agentSlug?: string;
+    taskTemplate: {
+        title: string;
+        description: string;
+    };
+    dependsOn?: string[];
+    onComplete?: "next" | "parallel" | "end";
+    onFail?: "abort" | "skip" | "retry";
+    retryPolicy?: RetryPolicy;
+}
+
+/** Workflow types — Story 1.5 / 5.1 */
+type WorkflowRunStatus = "running" | "completed" | "failed" | "cancelled";
+interface WorkflowStep$1 {
+    id: string;
+    name: string;
+    agentSlug?: string;
+    agentResolver?: string;
+    taskTemplate: {
+        title: string;
+        description: string;
+    };
+    dependsOn?: string[];
+    onComplete?: "next" | "parallel" | "end";
+    onFail?: "abort" | "skip" | "retry";
+    retryPolicy?: RetryPolicy;
+    condition?: string;
+}
+interface WorkflowDefinition$1 {
+    slug: string;
+    name: string;
+    description?: string;
+    steps: WorkflowStep$1[];
+    trigger?: WorkflowTrigger;
+}
+interface WorkflowTrigger {
+    type: "task_completed" | "event" | "schedule" | "manual";
+    filter?: Record<string, unknown>;
+}
+interface WorkflowRunRecord {
+    id: string;
+    workflowId: string;
+    status: WorkflowRunStatus;
+    currentStep: number;
+    context: Record<string, unknown>;
+    originTaskId?: string;
+    startedAt: string;
+    finishedAt?: string;
+    error?: string;
+}
+
+/** Shared constants — event names, default values, status enums */
+/** Hook/event name constants */
+declare const EVENTS: {
+    readonly COST_RECORDED: "cost.recorded";
+    readonly AGENT_CREATED: "agent.created";
+    readonly AGENT_STATUS_CHANGED: "agent.status_changed";
+    readonly BUDGET_EXCEEDED: "budget.exceeded";
+    readonly TASK_CREATED: "task.created";
+    readonly TASK_COMPLETED: "task.completed";
+    readonly TASK_FAILED: "task.failed";
+    readonly TASK_CANCELLED: "task.cancelled";
+    readonly RUN_STARTED: "run.started";
+    readonly RUN_COMPLETED: "run.completed";
+    readonly RUN_FAILED: "run.failed";
+    readonly MESSAGE_INBOUND: "message.inbound";
+    readonly MESSAGE_ROUTED: "message.routed";
+    readonly MESSAGE_PROCESSED: "message.processed";
+    readonly MESSAGE_OUTBOUND: "message.outbound";
+    readonly MESSAGE_SENT: "message.sent";
+    readonly UPDATE_AVAILABLE: "update.available";
+    readonly UPDATE_STARTED: "update.started";
+    readonly UPDATE_COMPLETED: "update.completed";
+    readonly UPDATE_FAILED: "update.failed";
+    readonly WORKFLOW_STARTED: "workflow.started";
+    readonly WORKFLOW_STEP_COMPLETED: "workflow.step_completed";
+    readonly WORKFLOW_COMPLETED: "workflow.completed";
+    readonly WORKFLOW_FAILED: "workflow.failed";
+};
+/** Default config values */
+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;
+    readonly MAX_CHAIN_DEPTH: 5;
+    readonly MAX_NOTIFICATION_RETRIES: 3;
+    readonly UPDATE_CHECK_INTERVAL_MS: 86400000;
+    readonly RENDER_WATCH_INTERVAL_MS: 30000;
+    readonly DATA_PATH: "./data/bot.db";
+    readonly RENDER_OUTPUT_DIR: "./context";
+    readonly LOG_PATH_TEMPLATE: "./data/runs/{runId}.ndjson";
+    readonly BUDGET_WARN_PERCENT: 80;
+};
+/** Task status values */
+declare const TASK_STATUSES: readonly ["backlog", "todo", "in_progress", "in_review", "done", "blocked", "cancelled"];
+/** Agent status values */
+declare const AGENT_STATUSES: readonly ["idle", "running", "paused", "terminated", "error"];
+/** Run status values */
+declare const RUN_STATUSES: readonly ["queued", "running", "succeeded", "failed", "cancelled"];
+
+type HookHandler = (context: Record<string, unknown>) => Promise<void> | void;
+type Unsubscribe = () => void;
+interface HookOptions {
+    /** 0–100, default 50. Lower = runs first. */
+    priority?: number;
+    /** Auto-unsubscribe after first invocation. */
+    once?: boolean;
+    /** Only fire if context matches all filter key/value pairs. */
+    filter?: Record<string, unknown>;
+}
+interface HookRegistration {
+    event: string;
+    handler: HookHandler;
+    priority: number;
+    once: boolean;
+    filter?: Record<string, unknown>;
+    /** Internal auto-increment for stable sort within same priority */
+    id: number;
+}
+
+/**
+ * Priority-ordered event bus for decoupled inter-layer communication.
+ * Story 1.1 — handlers run in priority order, errors are isolated,
+ * and registrations are unsubscribable.
+ */
+declare class HookBus {
+    private readonly registrations;
+    private nextId;
+    register(event: string, handler: HookHandler, opts?: HookOptions): Unsubscribe;
+    emit(event: string, context: Record<string, unknown>): Promise<void>;
+    /** Emit synchronously (use only when async is not needed) */
+    emitSync(event: string, context: Record<string, unknown>): void;
+    hasListeners(event: string): boolean;
+    listRegistered(): string[];
+    /** Remove all handlers for an event, or all handlers if no event given */
+    clear(event?: string): void;
+}
+
+interface ConfigLoadError {
+    field: string;
+    message: string;
+}
+interface ConfigLoadResult {
+    config: BotConfig;
+    errors: ConfigLoadError[];
+}
+/**
+ * Load and merge config from file, with env var interpolation and runtime overrides.
+ * Merge order: defaults < config file < runtime overrides
+ */
+declare function loadConfig(opts?: {
+    configPath?: string;
+    overrides?: Partial<BotConfig>;
+    env?: Record<string, string | undefined>;
+}): ConfigLoadResult;
+/** Get the loaded config singleton. Call loadConfig() first. */
+declare function getConfig(): BotConfig;
+/** Initialize the config singleton. Returns errors if any. */
+declare function initConfig(opts?: Parameters<typeof loadConfig>[0]): ConfigLoadError[];
+/** Reset the singleton (for testing) */
+declare function _resetConfig(): void;
+
+/**
+ * Interpolate ${ENV_VAR} references in YAML string values.
+ * Recursively walks objects and arrays.
+ */
+declare function interpolateEnv(value: unknown, env?: Record<string, string | undefined>): unknown;
+
+interface SchemaError {
+    path: string;
+    message: string;
+}
+declare function validateConfig(config: unknown): SchemaError[];
+
+declare const DEFAULT_CONFIG: BotConfig;
+
+declare class ProviderRegistry {
+    private providers;
+    register(provider: LLMProvider): void;
+    unregister(id: string): void;
+    get(id: string): LLMProvider | undefined;
+    list(): LLMProvider[];
+    listModels(): ModelInfo[];
+}
+
+declare class ModelRouter {
+    private readonly registry;
+    private readonly config;
+    constructor(registry: ProviderRegistry, config: ModelConfig);
+    /**
+     * Resolve a model ID or alias to a ResolvedModel.
+     * 1. Look up alias in config.aliases (or use as-is)
+     * 2. Search all registered providers for a model with that id
+     */
+    resolve(modelIdOrAlias: string): ResolvedModel | undefined;
+    /**
+     * Try primary model, then each in config.fallbackChain.
+     * Throws if none found.
+     */
+    resolveWithFallback(modelIdOrAlias: string): ResolvedModel;
+    /**
+     * Use config.routing[purpose] ?? config.default, then resolveWithFallback.
+     */
+    resolveForPurpose(purpose: string): ResolvedModel;
+    /** Returns all models from all registered providers. */
+    listAvailable(): ModelInfo[];
+}
+
+type Importer$1 = (packageName: string) => Promise<unknown>;
+/**
+ * Scans nodeModulesPath/@botinabox/{pkg}/package.json for each package in the scope.
+ * If pkg.botinabox?.type === 'provider', dynamically imports the package
+ * and returns the discovered LLMProvider instances.
+ *
+ * The optional importer parameter allows injection for testing.
+ */
+declare function discoverProviders(nodeModulesPath: string, importer?: Importer$1): Promise<LLMProvider[]>;
+
+/**
+ * ChannelRegistry — manages channel adapter lifecycle.
+ * Story 4.1
+ */
+
+declare class ChannelRegistryError extends Error {
+    constructor(message: string);
+}
+declare class ChannelRegistry {
+    private readonly adapters;
+    private started;
+    /**
+     * Register a channel adapter.
+     * Throws if an adapter with the same id is already registered.
+     * If registry is already started, immediately connects the adapter.
+     */
+    register(adapter: ChannelAdapter, config?: unknown): void;
+    /**
+     * Unregister a channel adapter.
+     * Disconnects the adapter if it exists.
+     */
+    unregister(id: string): Promise<void>;
+    /**
+     * Reconfigure an adapter: disconnect, update config, reconnect.
+     */
+    reconfigure(id: string, config: unknown): Promise<void>;
+    /**
+     * Run health checks on all registered adapters.
+     */
+    healthCheck(): Promise<Record<string, HealthStatus>>;
+    /** Get an adapter by ID. */
+    get(id: string): ChannelAdapter | undefined;
+    /** List all registered adapters. */
+    list(): ChannelAdapter[];
+    /**
+     * Start: connect all registered adapters and mark registry as started.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop: disconnect all registered adapters.
+     */
+    stop(): Promise<void>;
+}
+
+/**
+ * Auto-discovery for channel adapters.
+ * Scans @botinabox/* packages for botinabox.type === 'channel'.
+ * Story 4.1
+ */
+
+type Importer = (packageName: string) => Promise<unknown>;
+/**
+ * Scans nodeModulesPath/@botinabox/{pkg}/package.json for each package in the scope.
+ * If pkg.botinabox?.type === 'channel', dynamically imports the package
+ * and returns the discovered ChannelAdapter instances.
+ *
+ * The optional importer parameter allows injection for testing.
+ */
+declare function discoverChannels(nodeModulesPath: string, importer?: Importer): Promise<ChannelAdapter[]>;
+
+interface TableDefinition {
+    columns: Record<string, string>;
+    primaryKey?: string | string[];
+    tableConstraints?: string[];
+    relations?: Record<string, RelationDef>;
+    render?: string | ((rows: Row[]) => string);
+    outputFile?: string;
+    filter?: (rows: Row[]) => Row[];
+}
+interface RelationDef {
+    type: 'belongsTo' | 'hasMany';
+    table: string;
+    foreignKey: string;
+    references?: string;
+}
+interface EntityContextDef {
+    table: string;
+    directory: string;
+    slugColumn: string;
+    files: Record<string, EntityFileSpec>;
+    indexFile?: string;
+    protectedFiles?: string[];
+}
+interface EntityFileSpec {
+    source: EntitySource;
+    render: string | ((rows: Row[]) => string);
+    junctionColumns?: string[];
+    omitIfEmpty?: boolean;
+}
+type EntitySource = {
+    type: 'self';
+} | {
+    type: 'hasMany';
+    table: string;
+    foreignKey: string;
+    filters?: Filter[];
+    softDelete?: boolean;
+    orderBy?: string;
+    limit?: number;
+} | {
+    type: 'manyToMany';
+    junctionTable: string;
+    localKey: string;
+    remoteKey: string;
+    remoteTable: string;
+    filters?: Filter[];
+    orderBy?: string;
+    limit?: number;
+} | {
+    type: 'belongsTo';
+    table: string;
+    foreignKey: string;
+} | {
+    type: 'enriched';
+    include: Record<string, EntitySource>;
+} | {
+    type: 'custom';
+    resolve: (row: Row, adapter: SqliteAdapter) => Row[];
+};
+interface Filter {
+    col: string;
+    op: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'in' | 'isNull' | 'isNotNull';
+    val?: unknown;
+}
+interface QueryOptions {
+    where?: Record<string, unknown>;
+    filters?: Filter[];
+    orderBy?: string | Array<{
+        col: string;
+        dir: 'asc' | 'desc';
+    }>;
+    orderDir?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+type Row = Record<string, unknown>;
+type PkLookup = string | Record<string, unknown>;
+interface SqliteAdapter {
+    run(sql: string, params?: unknown[]): better_sqlite3.RunResult;
+    get<T = Row>(sql: string, params?: unknown[]): T | undefined;
+    all<T = Row>(sql: string, params?: unknown[]): T[];
+    tableInfo(table: string): TableInfoRow[];
+    invalidateTableCache(table: string): void;
+}
+interface TableInfoRow {
+    cid: number;
+    name: string;
+    type: string;
+    notnull: number;
+    dflt_value: unknown;
+    pk: number;
+}
+interface SeedItem {
+    table: string;
+    rows: Row[];
+    naturalKey?: string | string[];
+    junctions?: Array<{
+        table: string;
+        items: Array<Row>;
+    }>;
+    softDeleteMissing?: boolean;
+}
+
+declare class DataStoreError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thin wrapper around Lattice that provides the botinabox DataStore API.
+ *
+ * Delegates all data operations to the latticesql package. Application-level
+ * events (task.created, run.completed, etc.) remain on the HookBus — they are
+ * emitted by orchestrator modules, not the data layer.
+ */
+declare class DataStore {
+    private lattice;
+    private readonly hooks;
+    private readonly outputDir;
+    private _initialized;
+    private readonly deferredStatements;
+    constructor(opts: {
+        dbPath: string;
+        outputDir?: string;
+        wal?: boolean;
+        hooks?: HookBus;
+    });
+    /**
+     * Register a table definition. Must be called before init().
+     *
+     * tableConstraints may contain both inline constraints (FOREIGN KEY, UNIQUE)
+     * and standalone SQL statements (CREATE INDEX). Standalone statements are
+     * deferred and executed after init() creates the tables.
+     */
+    define(name: string, def: TableDefinition): void;
+    /**
+     * Register an entity context definition for per-entity file rendering.
+     */
+    defineEntityContext(name: string, def: EntityContextDef): void;
+    init(opts?: {
+        migrations?: Array<{
+            version: string;
+            sql: string;
+        }>;
+    }): Promise<void>;
+    private assertInitialized;
+    insert(table: string, row: Row): Promise<Row>;
+    upsert(table: string, row: Row): Promise<Row>;
+    update(table: string, pk: PkLookup, changes: Row): Promise<Row>;
+    delete(table: string, pk: PkLookup): Promise<void>;
+    /**
+     * Get a single row by primary key.
+     * Returns undefined if not found (Lattice returns null).
+     */
+    get(table: string, pk: PkLookup): Promise<Row | undefined>;
+    query(table: string, opts?: QueryOptions): Promise<Row[]>;
+    count(table: string, opts?: QueryOptions): Promise<number>;
+    link(junctionTable: string, row: Row): Promise<void>;
+    unlink(junctionTable: string, row: Row): Promise<void>;
+    migrate(migrations: Array<{
+        version: string;
+        sql: string;
+    }>): Promise<void>;
+    seed(items: SeedItem[]): Promise<void>;
+    render(): Promise<void>;
+    reconcile(): Promise<void>;
+    tableInfo(table: string): TableInfoRow[];
+    close(): void;
+    on(event: string, handler: (context: Record<string, unknown>) => void): void;
+}
+
+declare class AgentRegistry {
+    private db;
+    private hooks;
+    constructor(db: DataStore, hooks: HookBus);
+    register(agent: {
+        slug: string;
+        name: string;
+        adapter: string;
+        role?: string;
+        [key: string]: unknown;
+    }, opts?: {
+        actorAgentId?: string;
+    }): Promise<string>;
+    getById(id: string): Promise<Record<string, unknown> | undefined>;
+    getBySlug(slug: string): Promise<Record<string, unknown> | undefined>;
+    list(filter?: {
+        status?: string;
+        role?: string;
+    }): Promise<Record<string, unknown>[]>;
+    update(id: string, changes: Record<string, unknown>): Promise<void>;
+    setStatus(id: string, newStatus: string): Promise<void>;
+    terminate(id: string): Promise<void>;
+    seedFromConfig(agentConfigs: Array<{
+        slug: string;
+        name: string;
+        adapter: string;
+        [key: string]: unknown;
+    }>): Promise<void>;
+}
+
+declare const MAX_CHAIN_DEPTH = 5;
+/**
+ * Throws if depth exceeds the maximum allowed chain depth.
+ */
+declare function checkChainDepth(depth: number, max?: number): void;
+/**
+ * Build chain origin metadata for a new child task.
+ * If parentTaskId is provided, sets chain_origin_id and increments depth.
+ * Otherwise returns depth=0 with no origin.
+ */
+declare function buildChainOrigin(parentTaskId?: string, parentOriginId?: string, parentDepth?: number): {
+    chain_origin_id?: string;
+    chain_depth: number;
+};
+
+declare class TaskQueue {
+    private db;
+    private hooks;
+    private config?;
+    private pollTimer;
+    private readonly pollIntervalMs;
+    private readonly staleThresholdMs;
+    constructor(db: DataStore, hooks: HookBus, config?: {
+        pollIntervalMs?: number;
+        staleThresholdMs?: number;
+    } | undefined);
+    create(task: {
+        title: string;
+        description?: string;
+        assignee_id?: string;
+        priority?: number;
+        chain_depth?: number;
+        chain_origin_id?: string;
+        [key: string]: unknown;
+    }): Promise<string>;
+    update(id: string, changes: Record<string, unknown>): Promise<void>;
+    get(id: string): Promise<Record<string, unknown> | undefined>;
+    list(filter?: {
+        status?: string;
+        assignee_id?: string;
+    }): Promise<Record<string, unknown>[]>;
+    startPolling(): void;
+    stopPolling(): void;
+    private poll;
+}
+
+/**
+ * MessagePipeline — routes inbound messages to the task queue.
+ * Story 4.2
+ */
+
+declare class MessagePipeline {
+    private readonly hooks;
+    private readonly agentRegistry;
+    private readonly taskQueue;
+    private readonly config;
+    private readonly agentBindings;
+    constructor(hooks: HookBus, agentRegistry: AgentRegistry, taskQueue: TaskQueue, config: BotConfig);
+    /**
+     * 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'
+     */
+    processInbound(msg: InboundMessage): Promise<void>;
+    /**
+     * Resolve the best agent for a given inbound message.
+     * Returns agentId (slug) or undefined if no match.
+     */
+    resolveAgent(msg: InboundMessage): string | undefined;
+    /**
+     * Evaluate messaging policy for the given agent.
+     * Returns false if the message is blocked.
+     */
+    evaluatePolicy(msg: InboundMessage, agentId: string): boolean;
+}
+
+/**
+ * Chat routing — maps channel/scope to agentId.
+ * Story 4.2
+ */
+
+/**
+ * Build a map from channel identifier to agentId.
+ * Each agent may have a config.channel or config.channels binding.
+ */
+declare function buildAgentBindings(agents: AgentConfig[]): Map<string, string>;
+
+/**
+ * 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.
+ */
+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.
+ */
+declare function checkMentionGate(msg: InboundMessage, botId: string): boolean;
+
+/**
+ * SessionKey — structured key for chat sessions.
+ * Story 4.3
+ */
+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;
+}
+
+/**
+ * ChatSessionManager — wraps orchestrator SessionManager with SessionKey-based lookup.
+ * Story 4.3
+ */
+
+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>;
+}
+
+/**
+ * NotificationQueue — persistent outbound notification queue with retry.
+ * Story 4.4
+ */
+
+interface NotificationQueueOpts {
+    maxRetries?: number;
+    pollIntervalMs?: number;
+}
+declare class NotificationQueue {
+    private readonly db;
+    private readonly hooks;
+    private readonly channelRegistry;
+    private readonly maxRetries;
+    private readonly pollIntervalMs;
+    private timer;
+    constructor(db: DataStore, hooks: HookBus, channelRegistry: ChannelRegistry, opts?: NotificationQueueOpts);
+    /**
+     * Enqueue a notification for delivery.
+     * Returns the notification ID.
+     */
+    enqueue(channel: string, recipient: string, payload: {
+        text: string;
+        threadId?: string;
+        [key: string]: unknown;
+    }): Promise<string>;
+    /** Start the background worker polling for pending notifications. */
+    startWorker(): void;
+    /** Stop the background worker. */
+    stopWorker(): void;
+    private processNext;
+}
+
+/**
+ * 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.
+ */
+declare function chunkText(text: string, maxLen: number): string[];
+
+/**
+ * Text formatter — converts markdown to channel-specific formats.
+ * Story 4.4
+ */
+/**
+ * Format text for the given mode:
+ * - 'mrkdwn': Slack's mrkdwn format (**bold** → *bold*, _italic_ preserved, `code` preserved)
+ * - 'html': basic markdown → HTML (strong, em, code, pre)
+ * - 'plain': strip markdown markers
+ */
+declare function formatText(text: string, mode: "mrkdwn" | "html" | "plain"): string;
+
+/**
+ * Define all 15 core tables on a DataStore instance.
+ * Call before db.init().
+ */
+declare function defineCoreTables(db: DataStore): void;
+
+/** Initial migration set for core tables */
+declare const CORE_MIGRATIONS: Array<{
+    version: string;
+    sql: string;
+}>;
+
+interface SanitizerOptions {
+    fieldLengthLimits?: Record<string, number>;
+    truncateSuffix?: string;
+}
+interface AuditEvent {
+    table: string;
+    operation: 'insert' | 'update' | 'delete';
+    pk: unknown;
+    timestamp: number;
+    changedColumns?: string[];
+}
+
+/**
+ * Sanitizes a row object by:
+ * 1. Stripping null bytes from string values
+ * 2. Stripping control characters (preserving \n, \r, \t)
+ * 3. Truncating fields that exceed their byte length limit
+ *
+ * Non-string values pass through unchanged.
+ * Returns a new object — input is never mutated.
+ */
+declare function sanitize(row: Record<string, unknown>, opts?: SanitizerOptions): Record<string, unknown>;
+
+interface ColumnValidator {
+    validateWrite(table: string, row: Record<string, unknown>): Record<string, unknown>;
+    validateRead(table: string, columns: string[]): void;
+    invalidateCache(table: string): void;
+}
+/**
+ * Validates column names against the live SQLite schema.
+ *
+ * - validateWrite: strips unknown columns silently
+ * - validateRead: throws on unknown columns
+ */
+declare class ColumnValidatorImpl implements ColumnValidator {
+    private readonly db;
+    constructor(db: DataStore);
+    private getValidColumns;
+    validateWrite(table: string, row: Record<string, unknown>): Record<string, unknown>;
+    validateRead(table: string, columns: string[]): void;
+    invalidateCache(_table: string): void;
+}
+
+interface AuditEmitterOptions {
+    auditTables?: string[];
+}
+/**
+ * Emits audit events via the HookBus for tracked tables.
+ *
+ * - auditTables defaults to [] (nothing audited)
+ * - '*' wildcard audits all tables
+ * - emit is fire-and-forget — errors are swallowed, no awaiting
+ */
+declare class AuditEmitter {
+    private readonly hooks;
+    private readonly auditTables;
+    constructor(hooks: HookBus, opts?: AuditEmitterOptions);
+    shouldAudit(table: string): boolean;
+    emit(event: AuditEvent): void;
+}
+
+interface PackageUpdate {
+    name: string;
+    installedVersion: string;
+    latestVersion: string;
+    updateType: 'patch' | 'minor' | 'major';
+}
+interface UpdateManifest {
+    checkedAt: string;
+    packages: PackageUpdate[];
+    hasUpdates: boolean;
+}
+
+/**
+ * Simple semver utilities — no external deps.
+ */
+declare function parseVersion(v: string): [number, number, number];
+declare function compareVersions(a: string, b: string): -1 | 0 | 1;
+declare function classifyUpdate(from: string, to: string): 'patch' | 'minor' | 'major' | 'none';
+
+declare class UpdateChecker {
+    private nodeModulesPath;
+    private opts?;
+    private readonly fetchFn;
+    constructor(nodeModulesPath: string, opts?: {
+        fetch?: typeof globalThis.fetch;
+    } | undefined);
+    getInstalledPackages(): string[];
+    check(packageNames?: string[]): Promise<UpdateManifest>;
+}
+
+declare class BackupManager {
+    private projectRoot;
+    constructor(projectRoot: string);
+    backup(): Promise<string>;
+    restore(backupPath: string): Promise<void>;
+    cleanup(backupPath: string): Promise<void>;
+}
+
+type UpdatePolicy = 'auto-all' | 'auto-compatible' | 'auto-patch' | 'notify' | 'manual';
+declare class UpdateManager {
+    private checker;
+    private db;
+    private hooks;
+    private opts?;
+    private backupManager;
+    constructor(checker: UpdateChecker, db: DataStore, hooks: HookBus, opts?: {
+        projectRoot?: string;
+        policy?: UpdatePolicy;
+        maintenanceWindow?: {
+            utcHourStart: number;
+            utcHourEnd: number;
+        };
+    } | undefined);
+    checkAndNotify(): Promise<UpdateManifest>;
+    applyUpdates(updates: PackageUpdate[]): Promise<void>;
+    isInMaintenanceWindow(): boolean;
+    filterByPolicy(updates: PackageUpdate[]): PackageUpdate[];
+}
+
+interface PackageMigration {
+    version: string;
+    package: string;
+    sql: string;
+}
+/**
+ * Runs package migrations using the __lattice_migrations table for tracking.
+ * Each migration is keyed by "{package}:{version}" to ensure idempotency.
+ */
+declare function runPackageMigrations(db: DataStore, migrations: PackageMigration[]): Promise<void>;
+
+declare class RunManager {
+    private db;
+    private hooks;
+    private config?;
+    private locks;
+    private orphanTimer;
+    private readonly staleThresholdMs;
+    constructor(db: DataStore, hooks: HookBus, config?: {
+        staleThresholdMs?: number;
+        maxBackoffMs?: number;
+    } | undefined);
+    isLocked(agentId: string): boolean;
+    startRun(agentId: string, taskId: string, adapter?: string): Promise<string>;
+    finishRun(runId: string, result: {
+        exitCode: number;
+        output?: string;
+        costCents?: number;
+        usage?: unknown;
+    }): Promise<void>;
+    reapOrphans(): Promise<void>;
+    startOrphanReaper(intervalMs?: number): void;
+    stopOrphanReaper(): void;
+}
+
+declare class BudgetController {
+    private db;
+    private hooks;
+    constructor(db: DataStore, hooks: HookBus);
+    checkBudget(agentId: string): Promise<{
+        allowed: boolean;
+        reason?: string;
+        currentSpendCents: number;
+        limitCents: number;
+    }>;
+    resetMonthlySpend(agentId: string): Promise<void>;
+    globalCheck(): Promise<{
+        allowed: boolean;
+        totalSpentCents: number;
+        limitCents: number;
+    }>;
+}
+
+interface WorkflowStep {
+    id: string;
+    name: string;
+    agentSlug?: string;
+    taskTemplate: {
+        title: string;
+        description: string;
+    };
+    dependsOn?: string[];
+    onComplete?: 'next' | 'parallel' | 'end';
+    onFail?: 'abort' | 'skip' | 'retry';
+}
+interface WorkflowDefinition {
+    name: string;
+    description?: string;
+    steps: WorkflowStep[];
+    trigger?: {
+        type: 'task_completed' | 'event' | 'schedule' | 'manual';
+        filter?: Record<string, unknown>;
+    };
+}
+declare class WorkflowEngine {
+    private db;
+    private hooks;
+    private taskQueue;
+    constructor(db: DataStore, hooks: HookBus, taskQueue: TaskQueue);
+    /**
+     * Define/register a workflow.
+     */
+    define(slug: string, def: WorkflowDefinition): Promise<void>;
+    /**
+     * Start a workflow run.
+     */
+    start(workflowSlug: string, context: Record<string, unknown>): Promise<string>;
+    /**
+     * Called when a task with workflow_run_id completes.
+     */
+    onStepCompleted(taskId: string, output: string): Promise<void>;
+    /**
+     * Mark a workflow run as failed.
+     */
+    onStepFailed(taskId: string, error: string): Promise<void>;
+    private _createStepTask;
+}
+
+declare class WakeupQueue {
+    private db;
+    constructor(db: DataStore);
+    enqueue(agentId: string, source: string, context?: Record<string, unknown>): Promise<string>;
+    coalesce(agentId: string, context?: Record<string, unknown>): Promise<void>;
+    getNext(agentId: string): Promise<Record<string, unknown> | undefined>;
+    markFired(wakeupId: string, runId: string): Promise<void>;
+}
+
+declare class SessionManager {
+    private db;
+    constructor(db: DataStore);
+    save(agentId: string, channelId: string, peerId: string, params: Record<string, unknown>): Promise<string>;
+    load(agentId: string, channelId: string, peerId: string): Promise<Record<string, unknown> | undefined>;
+    clear(agentId: string, channelId: string, peerId: string): Promise<void>;
+    shouldClear(session: Record<string, unknown>, opts: {
+        maxRuns?: number;
+        maxAgeHours?: number;
+    }): Promise<boolean>;
+    private _find;
+}
+
+declare class NdjsonLogger {
+    private logPath;
+    constructor(logPath: string);
+    log(stream: 'stdout' | 'stderr', chunk: string): void;
+    close(): void;
+}
+
+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;
+}
+
+/**
+ * Creates a config revision record with before/after snapshots.
+ * Note: uses config_revisions table with config_yaml storing JSON of {agentId, before, after}.
+ */
+declare function createConfigRevision(db: DataStore, agentId: string, before: Record<string, unknown>, after: Record<string, unknown>): Promise<void>;
+
+/**
+ * Dependency resolution utilities for workflow steps and task deps.
+ */
+interface StepRef {
+    id: string;
+    dependsOn?: string[];
+}
+/**
+ * DFS cycle detection — returns true if cycle exists.
+ */
+declare function detectCycle(steps: StepRef[]): boolean;
+/**
+ * Returns step IDs in topological (execution) order.
+ * Throws if a cycle is detected.
+ */
+declare function topologicalSort(steps: StepRef[]): string[];
+/**
+ * Returns true if all dependencies are satisfied (present in completedTaskIds).
+ */
+declare function areDependenciesMet(taskDepsJson: string | undefined, completedTaskIds: Set<string>): boolean;
+
+/**
+ * Simple template interpolation for workflow step templates.
+ * Supports {{key}} and {{steps.stepId.output}} patterns.
+ */
+declare function interpolate(template: string, context: Record<string, unknown>): string;
+
+declare class ApiExecutionAdapter {
+    private modelRouter;
+    readonly type = "api";
+    constructor(modelRouter: ModelRouter);
+    execute(ctx: {
+        agent: {
+            id: string;
+            model?: string;
+            adapter_config?: string;
+        };
+        task: {
+            description?: string;
+            context?: string;
+        };
+        sessionParams?: {
+            history?: ChatMessage[];
+        };
+        contextFiles?: string[];
+        abortSignal?: AbortSignal;
+        onLog?: (stream: 'stdout' | 'stderr', chunk: string) => void;
+    }): Promise<{
+        output: string;
+        exitCode: number;
+        usage: TokenUsage & {
+            provider: string;
+            model: string;
+        };
+        sessionParams: {
+            history: ChatMessage[];
+        };
+    }>;
+}
+
+declare class CliExecutionAdapter {
+    readonly type = "cli";
+    execute(ctx: {
+        agent: {
+            id: string;
+            cwd?: string;
+            adapter_config?: string;
+            skip_permissions?: boolean;
+        };
+        task: {
+            title: string;
+            description?: string;
+            context?: string;
+        };
+        logPath?: string;
+        onLog?: (stream: string, chunk: string) => void;
+        abortSignal?: AbortSignal;
+    }): Promise<{
+        output: string;
+        exitCode: number;
+    }>;
+}
+
+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, DEFAULTS, DEFAULT_CONFIG, type DataConfig, DataStore, DataStoreError, 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 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 SchemaError, 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, 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, checkAllowlist, checkChainDepth, checkMentionGate, chunkText, classifyUpdate, compareVersions, createConfigRevision, defineCoreTables, detectCycle, discoverChannels, discoverProviders, formatText, getConfig, initConfig, interpolate, interpolateEnv, loadConfig, parseVersion, runPackageMigrations, sanitize, topologicalSort, validateConfig };