botinabox 1.8.2 → 1.8.3

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

@@ -0,0 +1,5 @@
+/**
+ * Interpolate ${ENV_VAR} references in YAML string values.
+ * Recursively walks objects and arrays.
+ */
+export declare function interpolateEnv(value: unknown, env?: Record<string, string | undefined>): unknown;

package/dist/core/config/interpolate.js

@@ -0,0 +1,27 @@
+/**
+ * Interpolate ${ENV_VAR} references in YAML string values.
+ * Recursively walks objects and arrays.
+ */
+export function interpolateEnv(value, env = process.env) {
+    if (typeof value === "string") {
+        return value.replace(/\$\{([^}]+)\}/g, (_, name) => {
+            const envVal = env[name];
+            if (envVal === undefined) {
+                // Leave the placeholder if env var is not set (don't silently swallow)
+                return `\${${name}}`;
+            }
+            return envVal;
+        });
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => interpolateEnv(item, env));
+    }
+    if (value !== null && typeof value === "object") {
+        const result = {};
+        for (const [k, v] of Object.entries(value)) {
+            result[k] = interpolateEnv(v, env);
+        }
+        return result;
+    }
+    return value;
+}

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

@@ -0,0 +1,24 @@
+import type { BotConfig } from "../../shared/index.js";
+export interface ConfigLoadError {
+    field: string;
+    message: string;
+}
+export 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
+ */
+export declare function loadConfig(opts?: {
+    configPath?: string;
+    overrides?: Partial<BotConfig>;
+    env?: Record<string, string | undefined>;
+}): ConfigLoadResult;
+/** Get the loaded config singleton. Call loadConfig() first. */
+export declare function getConfig(): BotConfig;
+/** Initialize the config singleton. Returns errors if any. */
+export declare function initConfig(opts?: Parameters<typeof loadConfig>[0]): ConfigLoadError[];
+/** Reset the singleton (for testing) */
+export declare function _resetConfig(): void;

package/dist/core/config/loader.js

@@ -0,0 +1,59 @@
+import { readFileSync, existsSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { DEFAULT_CONFIG } from "./defaults.js";
+import { interpolateEnv } from "./interpolate.js";
+function deepMerge(base, override) {
+    if (override === undefined || override === null)
+        return base;
+    if (base === undefined || base === null)
+        return override;
+    if (typeof base !== "object" || typeof override !== "object")
+        return override;
+    if (Array.isArray(override))
+        return override;
+    const result = { ...base };
+    for (const [k, v] of Object.entries(override)) {
+        if (v !== undefined) {
+            result[k] = deepMerge(result[k], v);
+        }
+    }
+    return result;
+}
+/**
+ * Load and merge config from file, with env var interpolation and runtime overrides.
+ * Merge order: defaults < config file < runtime overrides
+ */
+export function loadConfig(opts) {
+    const configPath = opts?.configPath ?? "botinabox.config.yml";
+    const errors = [];
+    let fileConfig = {};
+    if (existsSync(configPath)) {
+        try {
+            const raw = readFileSync(configPath, "utf-8");
+            const parsed = parseYaml(raw);
+            fileConfig = interpolateEnv(parsed, opts?.env ?? process.env);
+        }
+        catch (err) {
+            errors.push({ field: "configPath", message: `Failed to parse ${configPath}: ${String(err)}` });
+        }
+    }
+    const merged = deepMerge(deepMerge(DEFAULT_CONFIG, fileConfig), opts?.overrides ?? {});
+    return { config: Object.freeze(merged), errors };
+}
+let _config = null;
+/** Get the loaded config singleton. Call loadConfig() first. */
+export function getConfig() {
+    if (!_config)
+        throw new Error("Config not loaded — call loadConfig() first");
+    return _config;
+}
+/** Initialize the config singleton. Returns errors if any. */
+export function initConfig(opts) {
+    const { config, errors } = loadConfig(opts);
+    _config = config;
+    return errors;
+}
+/** Reset the singleton (for testing) */
+export function _resetConfig() {
+    _config = null;
+}

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

@@ -0,0 +1,5 @@
+export interface SchemaError {
+    path: string;
+    message: string;
+}
+export declare function validateConfig(config: unknown): SchemaError[];

package/dist/core/config/schema.js

@@ -0,0 +1,119 @@
+import Ajv from "ajv";
+const ajv = new Ajv({ allErrors: true, coerceTypes: false });
+const BOT_CONFIG_SCHEMA = {
+    type: "object",
+    additionalProperties: true,
+    properties: {
+        data: {
+            type: "object",
+            required: ["path", "walMode"],
+            properties: {
+                path: { type: "string", minLength: 1 },
+                walMode: { type: "boolean" },
+                backupDir: { type: "string" },
+            },
+        },
+        models: {
+            type: "object",
+            required: ["aliases", "default", "routing", "fallbackChain"],
+            properties: {
+                aliases: { type: "object", additionalProperties: { type: "string" } },
+                default: { type: "string", minLength: 1 },
+                routing: { type: "object", additionalProperties: { type: "string" } },
+                fallbackChain: { type: "array", items: { type: "string" } },
+                costLimit: {
+                    type: "object",
+                    properties: {
+                        perRunCents: { type: "number", minimum: 0 },
+                    },
+                },
+            },
+        },
+        security: {
+            type: "object",
+            properties: {
+                fieldLengthLimits: { type: "object", additionalProperties: { type: "number" } },
+                allowedFilePrefixes: { type: "array", items: { type: "string" } },
+            },
+        },
+        render: {
+            type: "object",
+            required: ["outputDir", "watchIntervalMs"],
+            properties: {
+                outputDir: { type: "string", minLength: 1 },
+                watchIntervalMs: { type: "number", minimum: 1000 },
+            },
+        },
+        updates: {
+            type: "object",
+            required: ["policy", "checkIntervalMs"],
+            properties: {
+                policy: { type: "string", enum: ["auto-all", "auto-compatible", "auto-patch", "notify", "manual"] },
+                checkIntervalMs: { type: "number", minimum: 60_000 },
+            },
+        },
+        budget: {
+            type: "object",
+            required: ["warnPercent"],
+            properties: {
+                warnPercent: { type: "number", minimum: 1, maximum: 100 },
+                globalMonthlyCents: { type: "number", minimum: 0 },
+            },
+        },
+        agents: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["slug", "name", "adapter"],
+                properties: {
+                    slug: { type: "string", minLength: 1, pattern: "^[a-z0-9-]+$" },
+                    name: { type: "string", minLength: 1 },
+                    adapter: { type: "string", minLength: 1 },
+                    model: { type: "string" },
+                    workdir: { type: "string" },
+                    maxConcurrentRuns: { type: "number", minimum: 1 },
+                    budgetMonthlyCents: { type: "number", minimum: 0 },
+                    canCreateAgents: { type: "boolean" },
+                    skipPermissions: { type: "boolean" },
+                },
+            },
+        },
+        channels: {
+            type: "object",
+            additionalProperties: {
+                type: "object",
+                required: ["enabled"],
+                properties: {
+                    enabled: { type: "boolean" },
+                },
+            },
+        },
+        providers: {
+            type: "object",
+            additionalProperties: {
+                type: "object",
+                required: ["enabled"],
+                properties: {
+                    enabled: { type: "boolean" },
+                },
+            },
+        },
+    },
+};
+let _validate = null;
+function getValidator() {
+    if (!_validate) {
+        _validate = ajv.compile(BOT_CONFIG_SCHEMA);
+    }
+    return _validate;
+}
+export function validateConfig(config) {
+    const validate = getValidator();
+    const valid = validate(config);
+    if (valid)
+        return [];
+    return (validate.errors ?? []).map(err => ({
+        path: err.instancePath || "/",
+        message: err.message ?? "invalid",
+    }));
+}

package/dist/core/data/core-entity-contexts.d.ts

@@ -0,0 +1,14 @@
+import type { DataStore } from "./data-store.js";
+/**
+ * Define default entity context rendering for botinabox core tables.
+ * Call after defineCoreTables() and before or after init().
+ *
+ * Renders:
+ * - agents/ — per-agent context (AGENT.md, PROJECTS.md if agent_project exists)
+ * - users/  — per-user context (USER.md) — protected
+ * - skills/ — per-skill context (SKILL.md)
+ *
+ * Apps can override by calling db.defineEntityContext() with the same table name
+ * BEFORE calling defineCoreEntityContexts().
+ */
+export declare function defineCoreEntityContexts(db: DataStore): void;

package/dist/core/data/core-entity-contexts.js

@@ -0,0 +1,197 @@
+import { truncateAtWord } from "../../shared/utils.js";
+/**
+ * Define default entity context rendering for botinabox core tables.
+ * Call after defineCoreTables() and before or after init().
+ *
+ * Renders:
+ * - agents/ — per-agent context (AGENT.md, PROJECTS.md if agent_project exists)
+ * - users/  — per-user context (USER.md) — protected
+ * - skills/ — per-skill context (SKILL.md)
+ *
+ * Apps can override by calling db.defineEntityContext() with the same table name
+ * BEFORE calling defineCoreEntityContexts().
+ */
+export function defineCoreEntityContexts(db) {
+    // --- Agents ---
+    db.defineEntityContext("agents", {
+        table: "agents",
+        directory: "agents",
+        slugColumn: "slug",
+        indexFile: "agents/AGENTS.md",
+        files: {
+            "AGENT.md": {
+                source: { type: "self" },
+                render: (rows) => {
+                    const a = rows[0];
+                    if (!a)
+                        return "";
+                    return [
+                        `# ${a.name}`,
+                        "",
+                        a.role ? `**Role:** ${a.role}` : null,
+                        a.adapter ? `**Adapter:** ${a.adapter}` : null,
+                        a.status ? `**Status:** ${a.status}` : null,
+                        a.cwd ? `**Working Directory:** ${a.cwd}` : null,
+                        a.reports_to ? `**Reports To:** ${a.reports_to}` : null,
+                        "",
+                    ]
+                        .filter(Boolean)
+                        .join("\n");
+                },
+            },
+            "SKILLS.md": {
+                source: {
+                    type: "manyToMany",
+                    junctionTable: "agent_skills",
+                    localKey: "agent_id",
+                    remoteKey: "skill_id",
+                    remoteTable: "skills",
+                },
+                omitIfEmpty: true,
+                render: (rows) => {
+                    if (!rows.length)
+                        return "";
+                    const lines = [`# Skills (${rows.length})`, ""];
+                    for (const s of rows) {
+                        lines.push(`## ${s.name}`);
+                        if (s.category)
+                            lines.push(`**Category:** ${s.category}`);
+                        if (s.description)
+                            lines.push("", s.description);
+                        if (s.definition)
+                            lines.push("", "```", s.definition, "```");
+                        lines.push("");
+                    }
+                    return lines.join("\n");
+                },
+            },
+            "PLAYBOOKS.md": {
+                source: {
+                    type: "manyToMany",
+                    junctionTable: "agent_playbooks",
+                    localKey: "agent_id",
+                    remoteKey: "playbook_id",
+                    remoteTable: "playbooks",
+                },
+                omitIfEmpty: true,
+                render: (rows) => {
+                    if (!rows.length)
+                        return "";
+                    const lines = [`# Playbooks (${rows.length})`, ""];
+                    for (const pb of rows) {
+                        lines.push(`## ${pb.pattern ?? pb.name ?? "Unnamed"}`);
+                        if (pb.rule)
+                            lines.push("", pb.rule);
+                        lines.push("");
+                    }
+                    return lines.join("\n");
+                },
+            },
+        },
+    });
+    // --- Users (protected) ---
+    db.defineEntityContext("users", {
+        table: "users",
+        directory: "users",
+        slugColumn: "id",
+        protected: true,
+        indexFile: "users/USERS.md",
+        files: {
+            "USER.md": {
+                source: { type: "self" },
+                render: (rows) => {
+                    const u = rows[0];
+                    if (!u)
+                        return "";
+                    return [
+                        `# ${u.name}`,
+                        "",
+                        u.role ? `**Role:** ${u.role}` : null,
+                        u.title ? `**Title:** ${u.title}` : null,
+                        u.email ? `**Email:** ${u.email}` : null,
+                        u.timezone ? `**Timezone:** ${u.timezone}` : null,
+                        "",
+                    ]
+                        .filter(Boolean)
+                        .join("\n");
+                },
+            },
+        },
+    });
+    // --- Skills ---
+    db.defineEntityContext("skills", {
+        table: "skills",
+        directory: "skills",
+        slugColumn: "slug",
+        indexFile: "skills/SKILLS.md",
+        files: {
+            "SKILL.md": {
+                source: { type: "self" },
+                render: (rows) => {
+                    const s = rows[0];
+                    if (!s)
+                        return "";
+                    return [
+                        `# ${s.name}`,
+                        "",
+                        s.category ? `**Category:** ${s.category}` : null,
+                        s.description ? `\n${s.description}` : null,
+                        s.definition ? `\n## Definition\n\n${s.definition}` : null,
+                        "",
+                    ]
+                        .filter(Boolean)
+                        .join("\n");
+                },
+            },
+        },
+    });
+    // --- Messages ---
+    db.defineEntityContext("messages", {
+        table: "messages",
+        directory: "messages",
+        slugColumn: "id",
+        indexFile: "messages/MESSAGES.md",
+        indexRender: (rows) => {
+            const active = rows.filter((r) => r.deleted_at == null);
+            if (!active.length)
+                return "# Messages\n\nNo messages.\n";
+            const recent = active.slice(-100);
+            const lines = recent.map((r) => {
+                const dir = r.direction === "outbound" ? "→" : "←";
+                const who = r.from_agent ?? r.from_user ?? "unknown";
+                const time = (r.created_at ?? "").slice(0, 16);
+                const preview = truncateAtWord(r.body ?? "", 80);
+                return `- ${dir} **${who}** (${time}): ${preview}`;
+            });
+            return `# Messages\n\nLast ${lines.length} messages:\n\n${lines.join("\n")}\n`;
+        },
+        files: {
+            "MESSAGE.md": {
+                source: { type: "self" },
+                render: (rows) => {
+                    const m = rows[0];
+                    if (!m)
+                        return "";
+                    return [
+                        "# Message",
+                        "",
+                        `**Direction:** ${m.direction}`,
+                        m.from_user ? `**From User:** ${m.from_user}` : null,
+                        m.from_agent ? `**From Agent:** ${m.from_agent}` : null,
+                        `**Channel:** ${m.channel}`,
+                        m.thread_id ? `**Thread:** ${m.thread_id}` : null,
+                        m.task_id ? `**Task:** ${m.task_id}` : null,
+                        `**Time:** ${m.created_at}`,
+                        "",
+                        "---",
+                        "",
+                        m.body,
+                        "",
+                    ]
+                        .filter(Boolean)
+                        .join("\n");
+                },
+            },
+        },
+    });
+}

package/dist/core/data/core-migrations.d.ts

@@ -0,0 +1,5 @@
+/** Initial migration set for core tables */
+export declare const CORE_MIGRATIONS: Array<{
+    version: string;
+    sql: string;
+}>;

package/dist/core/data/core-migrations.js

@@ -0,0 +1,45 @@
+/** Initial migration set for core tables */
+export const CORE_MIGRATIONS = [
+    {
+        version: "001_initial_schema",
+        sql: `-- Initial schema is applied via DataStore.define() + init().
+          -- This migration is a no-op placeholder for version tracking.
+          SELECT 1;`,
+    },
+    {
+        version: "002_activity_log_indexes",
+        sql: `CREATE INDEX IF NOT EXISTS idx_activity_log_type ON activity_log(event_type, recorded_at);`,
+    },
+    {
+        version: "003_runs_cost_index",
+        sql: `CREATE INDEX IF NOT EXISTS idx_runs_cost ON runs(agent_id, completed_at) WHERE cost_cents > 0;`,
+    },
+    {
+        version: "004_schedules_table",
+        sql: `CREATE TABLE IF NOT EXISTS schedules (
+            id TEXT PRIMARY KEY,
+            name TEXT NOT NULL,
+            description TEXT,
+            type TEXT NOT NULL DEFAULT 'recurring',
+            cron TEXT,
+            run_at TEXT,
+            timezone TEXT DEFAULT 'UTC',
+            enabled INTEGER NOT NULL DEFAULT 1,
+            action TEXT NOT NULL,
+            action_config TEXT DEFAULT '{}',
+            last_fired_at TEXT,
+            next_fire_at TEXT,
+            created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+            updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+            deleted_at TEXT
+          )`,
+    },
+    {
+        version: "005_schedules_name_index",
+        sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_schedules_name ON schedules(name) WHERE deleted_at IS NULL`,
+    },
+    {
+        version: "006_schedules_next_index",
+        sql: `CREATE INDEX IF NOT EXISTS idx_schedules_next ON schedules(enabled, next_fire_at) WHERE deleted_at IS NULL`,
+    },
+];

package/dist/core/data/core-schema.d.ts

@@ -0,0 +1,6 @@
+import type { DataStore } from "./data-store.js";
+/**
+ * Define all 18 core tables on a DataStore instance.
+ * Call before db.init().
+ */
+export declare function defineCoreTables(db: DataStore): void;