@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/node_modules/@boombot/core/scheduler/types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Public types for the BoomBot durable scheduler.
+ *
+ * A scheduled job contains an opaque ID, owner, schedule,
+ * timezone, payload reference, enabled state, concurrency policy, retry
+ * policy, and next-run time. Schedules are persisted before acknowledgment.
+ */
+export type ConcurrencyPolicy = 'forbid' | 'allow' | 'replace';
+export type MissedRunPolicy = 'skip' | 'run_once' | 'catch_up_bounded';
+export type RunStatus = 'claimed' | 'running' | 'completed' | 'failed' | 'dead_letter';
+/** User-supplied schedule specification (validated at the trust boundary). */
+export interface ScheduleSpec {
+    readonly name: string;
+    /** 5-field cron expression, e.g. "0 9 * * 1-5". */
+    readonly cron: string;
+    /** IANA timezone, e.g. "Asia/Ho_Chi_Minh". */
+    readonly timezone: string;
+    /**
+     * Registered prompt text submitted as an agent turn when the schedule
+     * fires. This is inert text — never code, never a shell command.
+     */
+    readonly promptText: string;
+    readonly enabled?: boolean;
+    readonly concurrencyPolicy?: ConcurrencyPolicy;
+    readonly missedRunPolicy?: MissedRunPolicy;
+    /** Max catch-up runs per tick for `catch_up_bounded`. Default 3. */
+    readonly maxCatchUp?: number;
+    /** Max attempts per run before dead-letter. Default 3. */
+    readonly maxAttempts?: number;
+    readonly baseRetryDelayMs?: number;
+    readonly maxRetryDelayMs?: number;
+}
+export interface SchedulerJob {
+    readonly id: string;
+    readonly ownerPrincipalId: string;
+    readonly name: string;
+    readonly cronExpr: string;
+    readonly timezone: string;
+    readonly promptText: string;
+    readonly enabled: boolean;
+    readonly concurrencyPolicy: ConcurrencyPolicy;
+    readonly missedRunPolicy: MissedRunPolicy;
+    readonly maxCatchUp: number;
+    readonly maxAttempts: number;
+    readonly baseRetryDelayMs: number;
+    readonly maxRetryDelayMs: number;
+    /** ISO-8601 UTC of the next scheduled fire, or null when disabled. */
+    readonly nextRunAt: string | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface SchedulerRun {
+    readonly id: string;
+    readonly jobId: string;
+    readonly idempotencyKey: string;
+    /** ISO-8601 UTC fire time this run serves. */
+    readonly scheduledFireAt: string;
+    readonly status: RunStatus;
+    readonly attempt: number;
+    readonly notBeforeAt: string;
+    readonly claimedBy: string;
+    readonly leaseExpiresAt: string;
+    readonly claimedAt: string;
+    readonly completedAt: string | null;
+    readonly errorCode: string | null;
+}
+/**
+ * Proof that the caller was authenticated by the HOST's authN layer
+ * (SECURITY FIX: confused-deputy / identity-binding gap, medium).
+ *
+ * `ScheduleRegistry` management methods take this instead of a bare
+ * principal-id string. Only `createAuthenticatedContext()` — which the host
+ * calls with the principal id from its OWN verified session/auth context —
+ * can mint a value carrying the brand: a plain `{ principalId }` object (or
+ * a header / JWT claim / plugin-supplied string the host did not verify)
+ * fails both the type check and the runtime brand check in
+ * `assertAuthenticatedContext()`.
+ *
+ * HOST INTEGRATION (MUST):
+ * - Mint the context from the Gateway's authenticated session ONLY.
+ * - NEVER mint from user input, request headers, plugin-supplied data, or
+ *   unverified token claims. A confused-deputy host that mints from
+ *   attacker-influenced data re-opens the impersonation gap below.
+ */
+/**
+ * Brand key: a module-private runtime symbol, also used as the type-level
+ * brand via its `unique symbol` type. Never exported, so only
+ * `createAuthenticatedContext()` (this module) can mint a branded context;
+ * a forged plain object fails the runtime check in
+ * `assertAuthenticatedContext()`.
+ */
+declare const authenticatedBrand: unique symbol;
+export interface AuthenticatedContext {
+    readonly principalId: string;
+    readonly [authenticatedBrand]: true;
+}
+/**
+ * Mint an `AuthenticatedContext`. The host MUST call this with the
+ * principal id from its own verified session/auth context — never from
+ * user input, headers, or plugin data (see `AuthenticatedContext`).
+ */
+export declare function createAuthenticatedContext(principalId: string): AuthenticatedContext;
+/**
+ * Runtime brand check: rejects forged or plain `{ principalId }` objects
+ * that were not minted by `createAuthenticatedContext()`. Defense in depth
+ * behind the type-level brand.
+ */
+export declare function assertAuthenticatedContext(context: unknown): asserts context is AuthenticatedContext;
+/** Narrow port: who may manage schedules. Wired by the host to Gateway authZ. */
+export interface SchedulerAuthorizer {
+    canManage(principalId: string): boolean | Promise<boolean>;
+}
+/**
+ * Narrow port: submit a turn for a fired schedule. The host wires this to the
+ * sessions facade (`turn.submit`); `command_idempotency` dedupes on the
+ * idempotency key. The scheduler never executes anything itself.
+ */
+export interface TurnSubmitter {
+    submit(input: {
+        readonly principalId: string;
+        readonly text: string;
+        readonly idempotencyKey: string;
+        /**
+         * Run context, populated by `SchedulerRunner.driveRun` when driving a
+         * claimed run. Host submitters (e.g. the gateway scheduler service) use
+         * these to record per-attempt delivery outcomes. Optional so existing
+         * submitters that only need the narrow port keep compiling.
+         */
+        readonly jobId?: string;
+        readonly jobName?: string;
+        readonly runId?: string;
+        readonly attempt?: number;
+    }): Promise<{
+        readonly turnId: string;
+    }>;
+}
+/** Wall-clock source (injectable for tests). */
+export interface WallClock {
+    now(): number;
+}
+export type SchedulerErrorCode = 'SCHEDULER_UNAUTHORIZED' | 'SCHEDULER_INVALID_SPEC' | 'SCHEDULER_NOT_FOUND' | 'SCHEDULER_CONFLICT' | 'SCHEDULER_LIMIT_EXCEEDED' | 'SCHEDULER_INVALID_STATE' | 'SCHEDULER_STORAGE_ERROR';
+export declare class SchedulerError extends Error {
+    readonly code: SchedulerErrorCode;
+    constructor(code: SchedulerErrorCode, message: string, cause?: unknown);
+}
+export declare function unauthorized(message: string): SchedulerError;
+export declare function invalidSpec(message: string): SchedulerError;
+export declare function notFound(message: string): SchedulerError;
+export declare function limitExceeded(message: string): SchedulerError;
+/**
+ * The target exists but is in a state that forbids the operation
+ * (e.g. `run-now` on a disabled schedule). Client-caused: hosts map this
+ * to a 4xx, never a 500.
+ */
+export declare function invalidState(message: string): SchedulerError;
+export declare function storageError(message: string, cause?: unknown): SchedulerError;
+export {};

package/dist/node_modules/@boombot/core/scheduler/types.js

@@ -0,0 +1,89 @@
+/**
+ * Public types for the BoomBot durable scheduler.
+ *
+ * A scheduled job contains an opaque ID, owner, schedule,
+ * timezone, payload reference, enabled state, concurrency policy, retry
+ * policy, and next-run time. Schedules are persisted before acknowledgment.
+ */
+/**
+ * Proof that the caller was authenticated by the HOST's authN layer
+ * (SECURITY FIX: confused-deputy / identity-binding gap, medium).
+ *
+ * `ScheduleRegistry` management methods take this instead of a bare
+ * principal-id string. Only `createAuthenticatedContext()` — which the host
+ * calls with the principal id from its OWN verified session/auth context —
+ * can mint a value carrying the brand: a plain `{ principalId }` object (or
+ * a header / JWT claim / plugin-supplied string the host did not verify)
+ * fails both the type check and the runtime brand check in
+ * `assertAuthenticatedContext()`.
+ *
+ * HOST INTEGRATION (MUST):
+ * - Mint the context from the Gateway's authenticated session ONLY.
+ * - NEVER mint from user input, request headers, plugin-supplied data, or
+ *   unverified token claims. A confused-deputy host that mints from
+ *   attacker-influenced data re-opens the impersonation gap below.
+ */
+/**
+ * Brand key: a module-private runtime symbol, also used as the type-level
+ * brand via its `unique symbol` type. Never exported, so only
+ * `createAuthenticatedContext()` (this module) can mint a branded context;
+ * a forged plain object fails the runtime check in
+ * `assertAuthenticatedContext()`.
+ */
+const authenticatedBrand = Symbol('boombot.scheduler.authenticated');
+/**
+ * Mint an `AuthenticatedContext`. The host MUST call this with the
+ * principal id from its own verified session/auth context — never from
+ * user input, headers, or plugin data (see `AuthenticatedContext`).
+ */
+export function createAuthenticatedContext(principalId) {
+    if (typeof principalId !== 'string' || principalId.length === 0) {
+        throw unauthorized('principalId is required to mint an authenticated context');
+    }
+    return { principalId, [authenticatedBrand]: true };
+}
+/**
+ * Runtime brand check: rejects forged or plain `{ principalId }` objects
+ * that were not minted by `createAuthenticatedContext()`. Defense in depth
+ * behind the type-level brand.
+ */
+export function assertAuthenticatedContext(context) {
+    if (typeof context !== 'object' ||
+        context === null ||
+        typeof context.principalId !== 'string' ||
+        context[authenticatedBrand] !== true) {
+        throw unauthorized('caller context is not authenticated: mint via createAuthenticatedContext() ' +
+            'from the host authN layer');
+    }
+}
+export class SchedulerError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'SchedulerError';
+        this.code = code;
+    }
+}
+export function unauthorized(message) {
+    return new SchedulerError('SCHEDULER_UNAUTHORIZED', message);
+}
+export function invalidSpec(message) {
+    return new SchedulerError('SCHEDULER_INVALID_SPEC', message);
+}
+export function notFound(message) {
+    return new SchedulerError('SCHEDULER_NOT_FOUND', message);
+}
+export function limitExceeded(message) {
+    return new SchedulerError('SCHEDULER_LIMIT_EXCEEDED', message);
+}
+/**
+ * The target exists but is in a state that forbids the operation
+ * (e.g. `run-now` on a disabled schedule). Client-caused: hosts map this
+ * to a 4xx, never a 500.
+ */
+export function invalidState(message) {
+    return new SchedulerError('SCHEDULER_INVALID_STATE', message);
+}
+export function storageError(message, cause) {
+    return new SchedulerError('SCHEDULER_STORAGE_ERROR', message, cause);
+}

package/dist/node_modules/@boombot/core/task-runner/index.d.ts

@@ -0,0 +1,7 @@
+export type { StepStatus, Task, TaskCheckpoint, TaskEvent, TaskInput, TaskRunner, TaskStatus, TaskStep, TurnRunner, TurnRunnerEvent, } from './types.js';
+export { TaskError } from './types.js';
+export { TaskStore, createTaskStore } from './store.js';
+export { createTaskRunner } from './runner.js';
+export type { TaskRunnerOptions } from './runner.js';
+export { decomposeGoal, planToTaskInput, createAndStartFromGoal, } from './planner.js';
+export type { PlannedStep, TaskPlan, TaskPlannerOptions, } from './planner.js';

package/dist/node_modules/@boombot/core/task-runner/index.js

@@ -0,0 +1,5 @@
+// @boombot/core — background task runner with durable checkpoints.
+export { TaskError } from './types.js';
+export { TaskStore, createTaskStore } from './store.js';
+export { createTaskRunner } from './runner.js';
+export { decomposeGoal, planToTaskInput, createAndStartFromGoal, } from './planner.js';

package/dist/node_modules/@boombot/core/task-runner/planner.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Dynamic Task Decomposition & Planner for @boombot/core.
+ *
+ * Decomposes high-level complex goals into ordered, durable TaskSteps
+ * with explicit dependencies, checkpoints, and automated fallback planning.
+ */
+import type { Task, TaskInput, TaskRunner } from './types.js';
+export interface PlannedStep {
+    readonly title: string;
+    readonly prompt: string;
+    readonly description?: string;
+    readonly dependencies?: readonly number[];
+}
+export interface TaskPlan {
+    readonly goal: string;
+    readonly summary: string;
+    readonly steps: readonly PlannedStep[];
+    readonly totalSteps: number;
+}
+export interface TaskPlannerOptions {
+    /** Optional custom LLM decomposition function. */
+    readonly decomposeLlm?: (goal: string, context?: string) => Promise<string>;
+    /** Maximum number of sub-steps allowed. Default 8. */
+    readonly maxSteps?: number;
+}
+/**
+ * Decomposes a high-level goal into an ordered, executable TaskPlan.
+ */
+export declare function decomposeGoal(goal: string, context?: string, options?: TaskPlannerOptions): Promise<TaskPlan>;
+/**
+ * Converts a TaskPlan into TaskInput ready for TaskRunner.createAndStart.
+ */
+export declare function planToTaskInput(plan: TaskPlan): TaskInput;
+/**
+ * Helper to decompose a goal and immediately launch it in the given TaskRunner.
+ */
+export declare function createAndStartFromGoal(runner: TaskRunner, goal: string, context?: string, options?: TaskPlannerOptions): Promise<Task>;

package/dist/node_modules/@boombot/core/task-runner/planner.js

@@ -0,0 +1,154 @@
+/**
+ * Dynamic Task Decomposition & Planner for @boombot/core.
+ *
+ * Decomposes high-level complex goals into ordered, durable TaskSteps
+ * with explicit dependencies, checkpoints, and automated fallback planning.
+ */
+/**
+ * Parses structured JSON response from LLM or extracts steps from bulleted text.
+ */
+function parseLlmPlanJson(raw, goal) {
+    try {
+        const jsonMatch = raw.match(/\{[\s\S]*\}/);
+        if (!jsonMatch)
+            return null;
+        const parsed = JSON.parse(jsonMatch[0]);
+        if (!parsed || !Array.isArray(parsed.steps) || parsed.steps.length === 0) {
+            return null;
+        }
+        const steps = parsed.steps.map((s, idx) => ({
+            title: typeof s.title === 'string' ? s.title : `Step ${idx + 1}`,
+            prompt: typeof s.prompt === 'string' && s.prompt.trim()
+                ? s.prompt.trim()
+                : typeof s.title === 'string'
+                    ? s.title
+                    : `Execute step ${idx + 1}`,
+            description: typeof s.description === 'string' ? s.description : undefined,
+            dependencies: Array.isArray(s.dependencies)
+                ? s.dependencies.filter((d) => typeof d === 'number')
+                : undefined,
+        }));
+        return {
+            goal,
+            summary: typeof parsed.summary === 'string' ? parsed.summary : `Plan for: ${goal}`,
+            steps,
+            totalSteps: steps.length,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Heuristically extracts numbered/bulleted steps from user input if present.
+ */
+function extractHeuristicSteps(text) {
+    const lines = text.split('\n').map((l) => l.trim());
+    const steps = [];
+    const stepPattern = /^(?:(?:\d+[\.\)]|\-|\*)\s+)(.+)$/;
+    for (const line of lines) {
+        const match = line.match(stepPattern);
+        if (match && match[1]) {
+            const content = match[1].trim();
+            if (content.length > 5) {
+                steps.push({
+                    title: content.slice(0, 50),
+                    prompt: content,
+                });
+            }
+        }
+    }
+    return steps;
+}
+/**
+ * Standard 4-phase autonomous software engineering lifecycle.
+ */
+function createDefaultDecomposition(goal, context) {
+    const ctxHint = context ? ` (Context: ${context})` : '';
+    const steps = [
+        {
+            title: 'Phase 1: Reconnaissance & Inspection',
+            prompt: `Inspect codebase, identify required files, analyze dependencies and verify prerequisites for: ${goal}${ctxHint}`,
+            description: 'Audit workspace and understand existing architecture before making changes.',
+        },
+        {
+            title: 'Phase 2: Core Implementation',
+            prompt: `Implement core changes, logic, and data models to fulfill goal: ${goal}${ctxHint}`,
+            description: 'Perform minimal, targeted implementation adhering to clean architecture.',
+            dependencies: [0],
+        },
+        {
+            title: 'Phase 3: Verification & Test Execution',
+            prompt: `Verify changes for: ${goal}. Run unit tests, typechecks, linter and inspect edge cases.`,
+            description: 'Run automated test suites and ensure zero regressions.',
+            dependencies: [1],
+        },
+        {
+            title: 'Phase 4: Polish & Documentation',
+            prompt: `Review diffs, ensure no secrets or debug statements remain, and document changes for: ${goal}`,
+            description: 'Finalize deliverable with clean git state and audit verification.',
+            dependencies: [2],
+        },
+    ];
+    return {
+        goal,
+        summary: `Autonomous Plan: ${goal.slice(0, 60)}`,
+        steps,
+        totalSteps: steps.length,
+    };
+}
+/**
+ * Decomposes a high-level goal into an ordered, executable TaskPlan.
+ */
+export async function decomposeGoal(goal, context, options = {}) {
+    const maxSteps = options.maxSteps ?? 8;
+    // 1. If LLM decomposer function provided, attempt structured decomposition
+    if (options.decomposeLlm) {
+        try {
+            const raw = await options.decomposeLlm(goal, context);
+            const plan = parseLlmPlanJson(raw, goal);
+            if (plan && plan.steps.length > 0) {
+                return {
+                    ...plan,
+                    steps: plan.steps.slice(0, maxSteps),
+                    totalSteps: Math.min(plan.steps.length, maxSteps),
+                };
+            }
+        }
+        catch {
+            // Fall through to heuristic / rule-based planner
+        }
+    }
+    // 2. Check for explicit bulleted steps in the goal prompt
+    const userSteps = extractHeuristicSteps(goal);
+    if (userSteps.length >= 2) {
+        const limited = userSteps.slice(0, maxSteps);
+        return {
+            goal,
+            summary: `User Specified Steps (${limited.length} phases)`,
+            steps: limited,
+            totalSteps: limited.length,
+        };
+    }
+    // 3. Fallback to robust 4-phase autonomous software engineering lifecycle
+    return createDefaultDecomposition(goal, context);
+}
+/**
+ * Converts a TaskPlan into TaskInput ready for TaskRunner.createAndStart.
+ */
+export function planToTaskInput(plan) {
+    return {
+        title: plan.summary,
+        steps: plan.steps.map((s) => ({
+            prompt: `[${s.title}] ${s.prompt}`,
+        })),
+    };
+}
+/**
+ * Helper to decompose a goal and immediately launch it in the given TaskRunner.
+ */
+export async function createAndStartFromGoal(runner, goal, context, options = {}) {
+    const plan = await decomposeGoal(goal, context, options);
+    const input = planToTaskInput(plan);
+    return runner.createAndStart(input);
+}

package/dist/node_modules/@boombot/core/task-runner/runner.d.ts

@@ -0,0 +1,8 @@
+import type { TaskStore } from './store.js';
+import type { TaskEvent, TaskRunner, TurnRunner } from './types.js';
+export interface TaskRunnerOptions {
+    store: TaskStore;
+    turnRunner: TurnRunner;
+    onEvent?: (e: TaskEvent) => void;
+}
+export declare function createTaskRunner(options: TaskRunnerOptions): TaskRunner;