@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/node_modules/@boombot/cronjobs/service.d.ts

@@ -0,0 +1,53 @@
+import { ScheduleRegistry, SchedulerRunner, ScheduleStore, type AuthenticatedContext, type SchedulerJob } from "@boombot/core";
+import { type Schedule as ProtocolSchedule, type StreamEvent } from "@boombot/protocol";
+export interface TurnSubmitInput {
+    readonly sessionId?: string;
+    readonly input: string;
+    readonly channel?: string;
+    readonly replyTo?: string;
+}
+export interface TurnService {
+    submit(input: TurnSubmitInput): Promise<{
+        readonly turnId: string;
+        readonly sessionId: string;
+    }>;
+}
+export interface EventBus {
+    publish(event: StreamEvent): void;
+}
+export interface CommandHandlerRegistry {
+    register(type: string, handler: CommandHandler): void;
+}
+export type CommandHandler = (ctx: ServiceContext, payload: unknown, meta: {
+    readonly requestId: string;
+}) => Promise<unknown>;
+export interface SchedulerServiceInternals {
+    readonly store: ScheduleStore;
+    readonly registry: ScheduleRegistry;
+    readonly runner: SchedulerRunner;
+    readonly authContext: AuthenticatedContext;
+}
+export interface SchedulerServiceHandle {
+    list(): Promise<ProtocolSchedule[]>;
+    fireNow(id: string): Promise<{
+        turnId: string;
+    }>;
+    stop(): Promise<void>;
+    /**
+     * Host wiring for command handlers (`schedule.*`). Additive to the
+     * `{ list(), fireNow(id), stop() }` contract.
+     */
+    readonly internals: SchedulerServiceInternals;
+}
+export interface ServiceContext {
+    readonly dataDir: string;
+    log(level: string, message: string, meta?: Record<string, unknown>): void;
+    readonly events: EventBus;
+    readonly registry: CommandHandlerRegistry;
+    readonly turnService?: TurnService;
+    schedulerService?: SchedulerServiceHandle;
+}
+/** Principal that owns schedules until per-user gateway authZ lands. */
+export declare const SCHEDULER_SERVICE_PRINCIPAL = "scheduler:service";
+export declare function toProtocolSchedule(job: SchedulerJob): ProtocolSchedule;
+export declare function startSchedulerService(ctx: ServiceContext): Promise<() => Promise<void>>;

package/dist/node_modules/@boombot/cronjobs/service.js

@@ -0,0 +1,200 @@
+/**
+ * Gateway scheduler service: wires the durable `@boombot/core` cron
+ * engine into the gateway runtime.
+ *
+ * - Durable store: `${dataDir}/scheduler.sqlite` (WAL, same file the
+ *   scheduler package manages; survives gateway restarts).
+ * - Execution semantics come from the package (`SchedulerRunner`):
+ *   at-most-once claim (advance `next_run_at` before dispatch, one atomic
+ *   transaction), idle watchdog (only runs past `lease_expires_at` are
+ *   recovered), bounded catch-up.
+ * - On fire, the registered prompt text is submitted as an agent turn via
+ *   `ctx.turnService` with `channel: 'scheduler'` and `replyTo: <job id>`.
+ *   If the turn service is not ready yet, the run is NOT dispatched: the
+ *   failure is logged and recorded, and the runner retries with backoff
+ *   until `maxAttempts`, then dead-letters — the gateway never crashes.
+ * - Every dispatch attempt writes a delivery outcome
+ *   (`fired`/`completed`/`failed` + turnId/error) into the store's
+ *   `scheduler_deliveries` table, and a matching `StreamEvent` is published
+ *   on success using existing protocol event types.
+ *
+ * NOTE: `ServiceContext` is defined locally to the exact contract below.
+ * The coordinator owns the shared `context.ts`; when it lands, delete the
+ * local definition and import the shared one (fields must stay compatible).
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { buildClaimFires, ScheduleRegistry, SchedulerRunner, ScheduleStore, createAuthenticatedContext, invalidState, notFound, } from "@boombot/core";
+import {} from "@boombot/protocol";
+// ---------------------------------------------------------------------------
+// Mapping
+// ---------------------------------------------------------------------------
+/** Principal that owns schedules until per-user gateway authZ lands. */
+export const SCHEDULER_SERVICE_PRINCIPAL = "scheduler:service";
+export function toProtocolSchedule(job) {
+    const schedule = {
+        id: job.id,
+        name: job.name,
+        cron: job.cronExpr,
+        prompt: job.promptText,
+        enabled: job.enabled,
+    };
+    if (job.nextRunAt !== null) {
+        schedule.nextRunAt = job.nextRunAt;
+    }
+    return schedule;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+const RUNNER_TICK_MS = 1000;
+const RUNNER_LEASE_MS = 60_000;
+export async function startSchedulerService(ctx) {
+    mkdirSync(ctx.dataDir, { recursive: true });
+    const dbPath = join(ctx.dataDir, "scheduler.sqlite");
+    const store = ScheduleStore.open(dbPath);
+    // The registry's authorizer port is wired permissive: the gateway HTTP
+    // layer authenticates every `schedule.*` caller upstream (phase 2 auth).
+    // Tighten this to per-principal gateway authZ when it lands.
+    const registry = new ScheduleRegistry(store, {
+        authorizer: { canManage: () => true },
+    });
+    const authContext = createAuthenticatedContext(SCHEDULER_SERVICE_PRINCIPAL);
+    const submitter = {
+        submit: async ({ principalId, text, jobId, jobName, runId, attempt }) => {
+            const recordedAt = new Date().toISOString();
+            const delivery = runId !== undefined && jobId !== undefined
+                ? { runId, jobId, attempt: attempt ?? 1, recordedAt }
+                : undefined;
+            if (delivery !== undefined) {
+                store.recordDelivery({ ...delivery, outcome: "fired" });
+            }
+            const turnService = ctx.turnService;
+            if (!turnService) {
+                ctx.log("error", "scheduler: turnService not ready; run not dispatched", {
+                    jobId,
+                    principalId,
+                });
+                if (delivery !== undefined) {
+                    store.recordDelivery({
+                        ...delivery,
+                        outcome: "failed",
+                        error: "turnService not ready",
+                    });
+                }
+                // Throw: the runner treats this as a transient submit failure and
+                // retries with backoff until maxAttempts, then dead-letters.
+                throw new Error("turnService not ready: scheduler run not dispatched");
+            }
+            try {
+                const scheduleSessionId = jobId !== undefined ? `sch_sess_${jobId}` : undefined;
+                const { turnId } = await turnService.submit({
+                    sessionId: scheduleSessionId,
+                    input: text,
+                    channel: "scheduler",
+                    replyTo: jobId,
+                });
+                if (delivery !== undefined) {
+                    store.recordDelivery({ ...delivery, outcome: "completed", turnId });
+                }
+                ctx.log("info", "scheduler: run dispatched as agent turn", {
+                    jobId,
+                    jobName,
+                    turnId,
+                });
+                ctx.events.publish({
+                    type: "agent.turn.done",
+                    payload: {
+                        turnId,
+                        status: "queued",
+                        output: `schedule "${jobName ?? jobId ?? "unknown"}" fired`,
+                    },
+                });
+                return { turnId };
+            }
+            catch (error) {
+                const message = errorMessage(error);
+                // Never log the prompt text: it may carry sensitive user content.
+                ctx.log("error", "scheduler: run dispatch failed", {
+                    jobId,
+                    jobName,
+                    error: message,
+                });
+                if (delivery !== undefined) {
+                    store.recordDelivery({ ...delivery, outcome: "failed", error: message });
+                }
+                throw error;
+            }
+        },
+    };
+    const runner = new SchedulerRunner({
+        store,
+        submitter,
+        tickIntervalMs: RUNNER_TICK_MS,
+        leaseMs: RUNNER_LEASE_MS,
+        onError: (error, phase) => {
+            ctx.log("error", `scheduler: tick ${phase} phase failed`, {
+                error: errorMessage(error),
+            });
+        },
+    });
+    runner.start();
+    const fireNow = async (id) => {
+        const job = store.getJob(id);
+        if (job === undefined) {
+            throw notFound(`schedule ${id} not found`);
+        }
+        if (!job.enabled) {
+            throw invalidState(`schedule ${id} is disabled`);
+        }
+        const nowIso = new Date().toISOString();
+        const fires = buildClaimFires(job, [nowIso]);
+        const fire = fires[0];
+        if (fire === undefined) {
+            throw new Error("scheduler: failed to build run-now claim");
+        }
+        const claim = store.claimJob({
+            jobId: job.id,
+            expectedNextRunAt: job.nextRunAt,
+            fires: [fire],
+            // run-now is an extra manual fire; the regular cadence is unchanged.
+            newNextRunAt: job.nextRunAt,
+            concurrency: job.concurrencyPolicy,
+            runnerId: runner.id,
+            leaseExpiresAt: new Date(Date.now() + RUNNER_LEASE_MS).toISOString(),
+            nowIso,
+        });
+        if (!claim.ok) {
+            throw new Error(`schedule ${id} could not be claimed for run-now (${claim.reason})`);
+        }
+        // Drive immediately instead of waiting for the next tick.
+        await runner.tickOnce(Date.now());
+        const delivery = store
+            .listDeliveries(job.id, 10)
+            .find((d) => d.runId === fire.runId && d.outcome === "completed" && d.turnId !== null);
+        const turnId = delivery?.turnId ?? null;
+        if (turnId === null) {
+            throw new Error(`schedule ${id} run-now dispatch failed`);
+        }
+        return { turnId };
+    };
+    let stopped = false;
+    const stop = async () => {
+        if (stopped)
+            return;
+        stopped = true;
+        await runner.stop();
+        store.close();
+    };
+    ctx.schedulerService = {
+        list: async () => (await registry.list(authContext)).map(toProtocolSchedule),
+        fireNow,
+        stop,
+        internals: { store, registry, runner, authContext },
+    };
+    ctx.log("info", "scheduler: service started", { dbPath });
+    return stop;
+}

package/dist/node_modules/@boombot/plugins/index.d.ts

@@ -0,0 +1,2 @@
+export * from './manager.js';
+export * from './installer.js';

package/dist/node_modules/@boombot/plugins/index.js

@@ -0,0 +1,2 @@
+export * from './manager.js';
+export * from './installer.js';

package/dist/node_modules/@boombot/plugins/installer.d.ts

@@ -0,0 +1,45 @@
+import { type BoomBotPluginManifest } from '@boombot/protocol';
+export interface InstalledPluginInfo {
+    readonly id: string;
+    readonly version: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly capabilities: readonly string[];
+    readonly directory: string;
+    readonly entry: string;
+    readonly isValid: boolean;
+    readonly error?: string;
+}
+export interface MarketplacePlugin {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly author: string;
+    readonly capabilities: readonly string[];
+    readonly tags: readonly string[];
+    readonly template: {
+        manifest: BoomBotPluginManifest;
+        code: string;
+    };
+}
+export declare const MARKETPLACE_CATALOG: readonly MarketplacePlugin[];
+export declare class PluginInstaller {
+    static getMarketplace(): readonly MarketplacePlugin[];
+    static listInstalled(root: string): Promise<readonly InstalledPluginInfo[]>;
+    static install(spec: string, options: {
+        root: string;
+        force?: boolean;
+    }): Promise<{
+        ok: boolean;
+        id: string;
+        message: string;
+    }>;
+    static uninstall(pluginId: string, options: {
+        root: string;
+    }): Promise<{
+        ok: boolean;
+        id: string;
+        message: string;
+    }>;
+}