botinabox 2.5.1 → 2.5.2

package/dist/core/orchestrator/run-manager.d.ts

@@ -0,0 +1,31 @@
+import type { DataStore } from '../data/data-store.js';
+import type { HookBus } from '../hooks/hook-bus.js';
+import type { CircuitBreaker } from './circuit-breaker.js';
+export declare class RunManager {
+    private db;
+    private hooks;
+    private config?;
+    private locks;
+    private orphanTimer;
+    private readonly staleThresholdMs;
+    private circuitBreaker?;
+    constructor(db: DataStore, hooks: HookBus, config?: {
+        staleThresholdMs?: number;
+        maxBackoffMs?: number;
+    } | undefined);
+    /**
+     * Attach a CircuitBreaker to prevent retries on broken agents.
+     */
+    setCircuitBreaker(cb: CircuitBreaker): void;
+    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;
+}

package/dist/core/orchestrator/run-manager.js

@@ -0,0 +1,178 @@
+import { checkChainDepth, MAX_CHAIN_DEPTH } from './chain-guard.js';
+import { interpolate } from './template-interpolate.js';
+const DEFAULT_STALE_THRESHOLD_MS = 30 * 60 * 1000; // 30 minutes
+const BASE_BACKOFF_MS = 5_000;
+const DEFAULT_MAX_BACKOFF_MS = 5 * 60 * 1000; // 5 minutes
+export class RunManager {
+    db;
+    hooks;
+    config;
+    locks = new Map(); // agentId → runId
+    orphanTimer = null;
+    staleThresholdMs;
+    circuitBreaker;
+    constructor(db, hooks, config) {
+        this.db = db;
+        this.hooks = hooks;
+        this.config = config;
+        this.staleThresholdMs = config?.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS;
+    }
+    /**
+     * Attach a CircuitBreaker to prevent retries on broken agents.
+     */
+    setCircuitBreaker(cb) {
+        this.circuitBreaker = cb;
+    }
+    isLocked(agentId) {
+        return this.locks.has(agentId);
+    }
+    async startRun(agentId, taskId, adapter) {
+        if (this.locks.has(agentId)) {
+            throw new Error(`Agent already has an active run`);
+        }
+        const row = await this.db.insert('runs', {
+            agent_id: agentId,
+            task_id: taskId,
+            adapter: adapter,
+            status: 'running',
+            started_at: new Date().toISOString(),
+        });
+        const runId = row['id'];
+        this.locks.set(agentId, runId);
+        return runId;
+    }
+    async finishRun(runId, result) {
+        const run = await this.db.get('runs', { id: runId });
+        if (!run)
+            throw new Error(`Run not found: ${runId}`);
+        const succeeded = result.exitCode === 0;
+        const status = succeeded ? 'succeeded' : 'failed';
+        const usage = result.usage;
+        await this.db.update('runs', { id: runId }, {
+            status,
+            completed_at: new Date().toISOString(),
+            exit_code: result.exitCode,
+            cost_cents: result.costCents ?? 0,
+            input_tokens: usage?.['inputTokens'] ?? 0,
+            output_tokens: usage?.['outputTokens'] ?? 0,
+            error_message: result.exitCode !== 0 ? result.output : undefined,
+        });
+        // Release lock
+        const agentId = run['agent_id'];
+        this.locks.delete(agentId);
+        const taskId = run['task_id'];
+        if (!succeeded) {
+            // Record failure in circuit breaker (if attached)
+            if (this.circuitBreaker) {
+                await this.circuitBreaker.recordFailure(agentId, result.output);
+            }
+            // Retry policy — skip retry if circuit breaker is open
+            const task = await this.db.get('tasks', { id: taskId });
+            if (task) {
+                const retryCount = task['retry_count'] ?? 0;
+                const maxRetries = task['max_retries'] ?? 0;
+                const circuitOpen = this.circuitBreaker
+                    ? !this.circuitBreaker.canExecute(agentId)
+                    : false;
+                if (retryCount < maxRetries && !circuitOpen) {
+                    // Exponential backoff: BASE_BACKOFF_MS * 2^retryCount
+                    const maxBackoff = this.config?.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+                    const backoffMs = Math.min(BASE_BACKOFF_MS * Math.pow(2, retryCount), maxBackoff);
+                    const nextRetryAt = new Date(Date.now() + backoffMs).toISOString();
+                    await this.db.update('tasks', { id: taskId }, {
+                        retry_count: retryCount + 1,
+                        next_retry_at: nextRetryAt,
+                        status: 'todo',
+                        execution_run_id: null,
+                        updated_at: new Date().toISOString(),
+                    });
+                }
+                else {
+                    // Retries exhausted or circuit open — mark task as failed
+                    await this.db.update('tasks', { id: taskId }, {
+                        status: 'failed',
+                        updated_at: new Date().toISOString(),
+                    });
+                }
+            }
+        }
+        else {
+            // Record success in circuit breaker (if attached)
+            if (this.circuitBreaker) {
+                await this.circuitBreaker.recordSuccess(agentId);
+            }
+            // Mark task done with result before emitting run.completed,
+            // so hook handlers can read task.result immediately.
+            await this.db.update('tasks', { id: taskId }, {
+                status: 'done',
+                result: result.output,
+                updated_at: new Date().toISOString(),
+            });
+            // Followup chain
+            const task = await this.db.get('tasks', { id: taskId });
+            if (task && task['followup_agent_id']) {
+                const chainDepth = (task['chain_depth'] ?? 0) + 1;
+                checkChainDepth(chainDepth, MAX_CHAIN_DEPTH);
+                const followupAgentId = task['followup_agent_id'];
+                const followupTemplate = task['followup_template'] ?? 'Followup: {{output}}';
+                const context = { output: result.output ?? '' };
+                const title = interpolate(followupTemplate, context);
+                const chainOriginId = task['chain_origin_id'] ?? taskId;
+                await this.db.insert('tasks', {
+                    title,
+                    description: title,
+                    assignee_id: followupAgentId,
+                    status: 'todo',
+                    priority: task['priority'] ?? 5,
+                    chain_depth: chainDepth,
+                    chain_origin_id: chainOriginId,
+                });
+                await this.hooks.emit('task.followup.created', {
+                    originTaskId: taskId,
+                    followupAgentId,
+                    chainDepth,
+                });
+            }
+        }
+        await this.hooks.emit('run.completed', {
+            runId,
+            agentId,
+            taskId,
+            status,
+            exitCode: result.exitCode,
+        });
+    }
+    async reapOrphans() {
+        const cutoff = new Date(Date.now() - this.staleThresholdMs).toISOString();
+        const staleRuns = (await this.db.query('runs', { where: { status: 'running' } }))
+            .filter((r) => {
+            const startedAt = r['started_at'];
+            return startedAt != null && startedAt < cutoff;
+        });
+        for (const run of staleRuns) {
+            await this.db.update('runs', { id: run['id'] }, {
+                status: 'failed',
+                completed_at: new Date().toISOString(),
+                error_message: 'Orphaned run reaped by RunManager',
+            });
+            // Release in-memory lock if we hold it
+            const agentId = run['agent_id'];
+            if (this.locks.get(agentId) === run['id']) {
+                this.locks.delete(agentId);
+            }
+        }
+    }
+    startOrphanReaper(intervalMs = 60_000) {
+        if (this.orphanTimer)
+            return;
+        this.orphanTimer = setInterval(() => {
+            void this.reapOrphans();
+        }, intervalMs);
+    }
+    stopOrphanReaper() {
+        if (this.orphanTimer) {
+            clearInterval(this.orphanTimer);
+            this.orphanTimer = null;
+        }
+    }
+}

package/dist/core/orchestrator/scheduler.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Scheduler — database-backed job scheduling with cron expressions.
+ *
+ * Supports one-time and recurring schedules. When a schedule fires,
+ * 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.
+ */
+import type { DataStore } from "../data/data-store.js";
+import type { HookBus } from "../hooks/hook-bus.js";
+export interface ScheduleDef {
+    name: string;
+    description?: string;
+    /** Cron expression for recurring schedules */
+    cron?: string;
+    /** ISO 8601 datetime for one-time schedules */
+    runAt?: string;
+    /** Hook event name to emit when fired */
+    action: string;
+    /** JSON-serializable payload passed to the hook */
+    actionConfig?: Record<string, unknown>;
+    timezone?: string;
+}
+export interface Schedule {
+    id: string;
+    name: string;
+    description: string | null;
+    type: "one_time" | "recurring";
+    cron: string | null;
+    run_at: string | null;
+    timezone: string;
+    enabled: number;
+    action: string;
+    action_config: string;
+    last_fired_at: string | null;
+    next_fire_at: string | null;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+}
+export declare class Scheduler {
+    private db;
+    private hooks;
+    private timer;
+    constructor(db: DataStore, hooks: HookBus);
+    /**
+     * Start the scheduler. Computes initial next_fire_at for schedules
+     * that don't have one, then polls for due schedules.
+     */
+    start(pollIntervalMs?: number): Promise<void>;
+    stop(): void;
+    /** Check for and fire due schedules. */
+    tick(): Promise<void>;
+    /** Register a new schedule. */
+    register(def: ScheduleDef): Promise<string>;
+    /** Update an existing schedule. */
+    update(id: string, changes: Partial<Pick<ScheduleDef, "name" | "cron" | "runAt" | "action" | "actionConfig" | "timezone" | "description">> & {
+        enabled?: boolean;
+    }): Promise<void>;
+    /** Soft-delete a schedule. */
+    unregister(id: string): Promise<void>;
+    /** List schedules, optionally filtered. */
+    list(filter?: {
+        enabled?: boolean;
+        action?: string;
+    }): Promise<Schedule[]>;
+    /** Compute next_fire_at for any enabled schedule missing it. */
+    private initializeNextFireTimes;
+}

package/dist/core/orchestrator/scheduler.js

@@ -0,0 +1,198 @@
+/**
+ * Scheduler — database-backed job scheduling with cron expressions.
+ *
+ * Supports one-time and recurring schedules. When a schedule fires,
+ * 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.
+ */
+import cronParser from "cron-parser";
+import { v4 as uuid } from "uuid";
+function computeNextFire(cron, timezone, after) {
+    const interval = cronParser.parseExpression(cron, {
+        currentDate: after ?? new Date(),
+        tz: timezone,
+    });
+    return interval.next().toISOString();
+}
+export class Scheduler {
+    db;
+    hooks;
+    timer = null;
+    constructor(db, hooks) {
+        this.db = db;
+        this.hooks = hooks;
+    }
+    /**
+     * Start the scheduler. Computes initial next_fire_at for schedules
+     * that don't have one, then polls for due schedules.
+     */
+    async start(pollIntervalMs = 30_000) {
+        await this.initializeNextFireTimes();
+        this.timer = setInterval(() => {
+            void this.tick();
+        }, pollIntervalMs);
+        // Fire immediately on start
+        void this.tick();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Check for and fire due schedules. */
+    async tick() {
+        const now = new Date().toISOString();
+        const schedules = (await this.db.query("schedules", {
+            where: { enabled: 1 },
+        })).filter((s) => s["deleted_at"] == null &&
+            s["next_fire_at"] != null &&
+            s["next_fire_at"] <= now);
+        for (const schedule of schedules) {
+            try {
+                const config = JSON.parse(schedule.action_config || "{}");
+                // Filter prototype pollution vectors
+                const safeConfig = {};
+                for (const [k, v] of Object.entries(config)) {
+                    if (!k.startsWith('__'))
+                        safeConfig[k] = v;
+                }
+                // Emit the action hook (e.g. 'connector.sync', 'channel.send')
+                await this.hooks.emit(schedule.action, {
+                    schedule_id: schedule.id,
+                    schedule_name: schedule.name,
+                    ...safeConfig,
+                });
+                // Emit observability hook
+                await this.hooks.emit("schedule.fired", {
+                    schedule_id: schedule.id,
+                    schedule_name: schedule.name,
+                    action: schedule.action,
+                    fired_at: now,
+                });
+                // Update last_fired_at and compute next
+                if (schedule.type === "recurring" && schedule.cron) {
+                    const nextFire = computeNextFire(schedule.cron, schedule.timezone, new Date());
+                    await this.db.update("schedules", { id: schedule.id }, {
+                        last_fired_at: now,
+                        next_fire_at: nextFire,
+                        updated_at: now,
+                    });
+                }
+                else {
+                    // One-time: disable after firing
+                    await this.db.update("schedules", { id: schedule.id }, {
+                        last_fired_at: now,
+                        next_fire_at: null,
+                        enabled: 0,
+                        updated_at: now,
+                    });
+                }
+            }
+            catch (err) {
+                console.error(`[Scheduler] Error firing schedule "${schedule.name}":`, err);
+                await this.hooks.emit("schedule.error", {
+                    schedule_id: schedule.id,
+                    schedule_name: schedule.name,
+                    error: String(err),
+                });
+            }
+        }
+    }
+    /** Register a new schedule. */
+    async register(def) {
+        const id = uuid();
+        const type = def.cron ? "recurring" : "one_time";
+        const timezone = def.timezone ?? "UTC";
+        let nextFire = null;
+        if (def.cron) {
+            nextFire = computeNextFire(def.cron, timezone);
+        }
+        else if (def.runAt) {
+            nextFire = new Date(def.runAt).toISOString();
+        }
+        await this.db.insert("schedules", {
+            id,
+            name: def.name,
+            description: def.description ?? null,
+            type,
+            cron: def.cron ?? null,
+            run_at: def.runAt ?? null,
+            timezone,
+            enabled: 1,
+            action: def.action,
+            action_config: JSON.stringify(def.actionConfig ?? {}),
+            next_fire_at: nextFire,
+        });
+        return id;
+    }
+    /** Update an existing schedule. */
+    async update(id, changes) {
+        const row = {
+            updated_at: new Date().toISOString(),
+        };
+        if (changes.name !== undefined)
+            row["name"] = changes.name;
+        if (changes.description !== undefined)
+            row["description"] = changes.description;
+        if (changes.action !== undefined)
+            row["action"] = changes.action;
+        if (changes.actionConfig !== undefined)
+            row["action_config"] = JSON.stringify(changes.actionConfig);
+        if (changes.enabled !== undefined)
+            row["enabled"] = changes.enabled ? 1 : 0;
+        if (changes.cron !== undefined) {
+            row["cron"] = changes.cron;
+            row["type"] = "recurring";
+            row["run_at"] = null;
+            row["next_fire_at"] = computeNextFire(changes.cron, changes.timezone ?? "UTC");
+        }
+        else if (changes.runAt !== undefined) {
+            row["run_at"] = changes.runAt;
+            row["type"] = "one_time";
+            row["cron"] = null;
+            row["next_fire_at"] = new Date(changes.runAt).toISOString();
+        }
+        if (changes.timezone !== undefined)
+            row["timezone"] = changes.timezone;
+        await this.db.update("schedules", { id }, row);
+    }
+    /** Soft-delete a schedule. */
+    async unregister(id) {
+        await this.db.update("schedules", { id }, {
+            enabled: 0,
+            deleted_at: new Date().toISOString(),
+            updated_at: new Date().toISOString(),
+        });
+    }
+    /** List schedules, optionally filtered. */
+    async list(filter) {
+        const where = {};
+        if (filter?.enabled !== undefined)
+            where["enabled"] = filter.enabled ? 1 : 0;
+        if (filter?.action !== undefined)
+            where["action"] = filter.action;
+        return (await this.db.query("schedules", { where })).filter((s) => s["deleted_at"] == null);
+    }
+    /** Compute next_fire_at for any enabled schedule missing it. */
+    async initializeNextFireTimes() {
+        const schedules = (await this.db.query("schedules", { where: { enabled: 1 } })).filter((s) => s["deleted_at"] == null && s["next_fire_at"] == null);
+        for (const s of schedules) {
+            let nextFire = null;
+            if (s.type === "recurring" && s.cron) {
+                nextFire = computeNextFire(s.cron, s.timezone);
+            }
+            else if (s.type === "one_time" && s.run_at) {
+                nextFire = new Date(s.run_at).toISOString();
+            }
+            if (nextFire) {
+                await this.db.update("schedules", { id: s.id }, {
+                    next_fire_at: nextFire,
+                    updated_at: new Date().toISOString(),
+                });
+            }
+        }
+    }
+}

package/dist/core/orchestrator/secret-store.d.ts

@@ -0,0 +1,57 @@
+import type { DataStore } from "../data/data-store.js";
+import type { HookBus } from "../hooks/hook-bus.js";
+export interface SecretInput {
+    name: string;
+    type?: string;
+    environment?: string;
+    value?: string;
+    location?: string;
+    description?: string;
+    rotation_schedule?: string;
+    expires_at?: string;
+    notes?: string;
+    org_id?: string;
+}
+export interface SecretMeta {
+    id: string;
+    org_id: string | null;
+    name: string;
+    type: string;
+    environment: string;
+    location: string | null;
+    description: string | null;
+    rotation_schedule: string | null;
+    expires_at: string | null;
+    notes: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export declare class SecretStore {
+    private readonly db;
+    private readonly hooks;
+    private readonly encKey;
+    /**
+     * @param db - DataStore instance
+     * @param hooks - HookBus instance
+     * @param encryptionKey - Optional master key for encrypting secrets at rest.
+     *   When provided, all new secrets are encrypted with AES-256-GCM.
+     *   Existing plaintext secrets are read transparently (passthrough on decrypt).
+     */
+    constructor(db: DataStore, hooks: HookBus, encryptionKey?: string);
+    set(input: SecretInput): Promise<SecretMeta>;
+    get(name: string, environment?: string): Promise<string | null>;
+    getMeta(name: string, environment?: string): Promise<SecretMeta | null>;
+    list(): Promise<SecretMeta[]>;
+    rotate(name: string, newValue: string, environment?: string): Promise<void>;
+    delete(name: string, environment?: string): Promise<void>;
+    /**
+     * Load a sync cursor by key. Returns undefined if not found.
+     * Cursors are stored as secrets with type='sync_cursor'.
+     */
+    loadCursor(key: string): Promise<string | undefined>;
+    /**
+     * Persist a sync cursor by key. Creates or updates the secret.
+     */
+    saveCursor(key: string, value: string): Promise<void>;
+    private _toMeta;
+}