@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/node_modules/@boombot/core/agent-core/middleware.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Turn pipeline middleware for `@boombot/core` — LangChain-style
+ * `AgentMiddleware` adapted to the BoomBot phase pipeline.
+ *
+ * A middleware observes or wraps phases (`preflight`, `recall`,
+ * `buildPrompt`, `modelRound`, `toolRound`):
+ *
+ * - `beforePhase` hooks run in registration order.
+ * - `afterPhase` hooks run in REVERSE registration order (onion).
+ * - `wrapPhase` hooks compose as an onion: the first registered middleware
+ *   is the outermost wrapper.
+ *
+ * The gateway bridge skips middleware work when `ctx.middlewares` is empty.
+ *
+ * Error semantics (a middleware never crashes a turn):
+ * - An ordinary error from `beforePhase`/`afterPhase` emits a
+ *   `middleware.error` event and the turn continues.
+ * - An ordinary error from `wrapPhase` thrown BEFORE it calls `next()`
+ *   emits `middleware.error` and the rest of the chain runs directly
+ *   (without the faulty wrapper). If the inner chain already ran, the
+ *   error propagates as a normal phase error.
+ * - `MiddlewareAbortError` from ANY hook aborts the turn with
+ *   `{ status: 'error', error: <reason> }`.
+ *
+ * Hooks receive an optional `emit` sink (`MiddlewareEmit`) so they can
+ * publish `AgentEvent`s of their own (e.g. the adaptive routing
+ * middleware's `turn.routed` / `turn.escalated`). Old middlewares that
+ * don't declare the parameter keep working unchanged.
+ */
+import type { AgentEvent, PhaseName, TurnContext } from './types.js';
+export interface TurnMiddleware {
+    readonly name: string;
+    beforePhase?(phase: PhaseName, ctx: TurnContext, emit?: MiddlewareEmit): void | Promise<void>;
+    afterPhase?(phase: PhaseName, ctx: TurnContext, result: unknown, emit?: MiddlewareEmit): void | Promise<void>;
+    wrapPhase?(phase: PhaseName, next: () => Promise<unknown>): Promise<unknown>;
+}
+/** Event sink handed to middleware hooks so they can emit their own `AgentEvent`s. */
+export type MiddlewareEmit = (event: AgentEvent) => void;
+/** Thrown by a middleware hook to abort the whole turn. */
+export declare class MiddlewareAbortError extends Error {
+    readonly code: "MIDDLEWARE_ABORT";
+    constructor(reason: string);
+}
+/**
+ * Middleware-aware phase runner: emits `phase.start` / `phase.end` around
+ * the middleware pipeline, exactly like the old `emitPhase` when no
+ * middlewares are registered.
+ */
+export declare function runPhaseWithMiddleware<T>(phase: PhaseName, ctx: TurnContext, middlewares: readonly TurnMiddleware[], onEvent: MiddlewareEmit, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Built-in middleware: logs the elapsed time of every phase.
+ * `onLog` defaults to `console.debug`; pass your own sink in tests.
+ */
+export declare function loggingMiddleware(onLog?: (message: string) => void): TurnMiddleware;
+/**
+ * Built-in middleware: aborts the turn when any single phase takes longer
+ * than `timeoutMs`. The timeout races the phase — the phase keeps running
+ * in the background but its result is discarded.
+ */
+export declare function timeoutMiddleware(timeoutMs: number): TurnMiddleware;

package/dist/node_modules/@boombot/core/agent-core/middleware.js

@@ -0,0 +1,152 @@
+/** Thrown by a middleware hook to abort the whole turn. */
+export class MiddlewareAbortError extends Error {
+    code = 'MIDDLEWARE_ABORT';
+    constructor(reason) {
+        super(reason);
+        this.name = 'MiddlewareAbortError';
+    }
+}
+function emitMiddlewareError(sink, mw, phase, err) {
+    sink({
+        type: 'middleware.error',
+        middleware: mw.name,
+        phase,
+        error: err instanceof Error ? err.message : String(err),
+    });
+}
+/**
+ * Run one phase function through the middleware onion.
+ * When `middlewares` is empty this is a direct call (zero-cost path).
+ */
+async function runMiddlewarePipeline(phase, ctx, middlewares, onEvent, fn) {
+    if (middlewares.length === 0) {
+        return fn();
+    }
+    for (const mw of middlewares) {
+        if (mw.beforePhase === undefined) {
+            continue;
+        }
+        try {
+            await mw.beforePhase(phase, ctx, onEvent);
+        }
+        catch (err) {
+            if (err instanceof MiddlewareAbortError) {
+                throw err;
+            }
+            emitMiddlewareError(onEvent, mw, phase, err);
+        }
+    }
+    const wrapped = middlewares.reduceRight((next, mw) => {
+        const wrapPhase = mw.wrapPhase;
+        if (wrapPhase === undefined) {
+            return next;
+        }
+        return async () => {
+            let delegated = false;
+            const trackedNext = async () => {
+                delegated = true;
+                return next();
+            };
+            try {
+                return (await wrapPhase(phase, trackedNext));
+            }
+            catch (err) {
+                if (err instanceof MiddlewareAbortError) {
+                    throw err;
+                }
+                if (!delegated) {
+                    // The wrapper failed before delegating: run the rest of the
+                    // chain directly, without the faulty wrapper.
+                    emitMiddlewareError(onEvent, mw, phase, err);
+                    return next();
+                }
+                // The inner chain already ran: this is a phase error, propagate.
+                throw err;
+            }
+        };
+    }, fn);
+    const result = await wrapped();
+    for (let i = middlewares.length - 1; i >= 0; i--) {
+        const mw = middlewares[i];
+        if (mw === undefined || mw.afterPhase === undefined) {
+            continue;
+        }
+        try {
+            await mw.afterPhase(phase, ctx, result, onEvent);
+        }
+        catch (err) {
+            if (err instanceof MiddlewareAbortError) {
+                throw err;
+            }
+            emitMiddlewareError(onEvent, mw, phase, err);
+        }
+    }
+    return result;
+}
+/**
+ * Middleware-aware phase runner: emits `phase.start` / `phase.end` around
+ * the middleware pipeline, exactly like the old `emitPhase` when no
+ * middlewares are registered.
+ */
+export async function runPhaseWithMiddleware(phase, ctx, middlewares, onEvent, fn) {
+    onEvent({ type: 'phase.start', phase });
+    // Duration is measured here rather than left to a middleware so that it is
+    // present with zero middlewares installed — the production turn path has no
+    // timing instrumentation otherwise, which made latency work unfalsifiable.
+    const startedAt = Date.now();
+    try {
+        const value = await runMiddlewarePipeline(phase, ctx, middlewares, onEvent, async () => fn());
+        onEvent({ type: 'phase.end', phase, durationMs: Date.now() - startedAt });
+        return value;
+    }
+    catch (err) {
+        onEvent({ type: 'phase.end', phase, durationMs: Date.now() - startedAt });
+        throw err;
+    }
+}
+/**
+ * Built-in middleware: logs the elapsed time of every phase.
+ * `onLog` defaults to `console.debug`; pass your own sink in tests.
+ */
+export function loggingMiddleware(onLog = (msg) => console.debug(msg)) {
+    return {
+        name: 'logging',
+        wrapPhase: async (phase, next) => {
+            const start = Date.now();
+            try {
+                return await next();
+            }
+            finally {
+                onLog(`[middleware] phase=${phase} elapsedMs=${Date.now() - start}`);
+            }
+        },
+    };
+}
+/**
+ * Built-in middleware: aborts the turn when any single phase takes longer
+ * than `timeoutMs`. The timeout races the phase — the phase keeps running
+ * in the background but its result is discarded.
+ */
+export function timeoutMiddleware(timeoutMs) {
+    return {
+        name: 'timeout',
+        wrapPhase: async (phase, next) => {
+            let timer;
+            try {
+                return await Promise.race([
+                    next(),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => {
+                            reject(new MiddlewareAbortError(`phase '${phase}' timed out after ${timeoutMs}ms`));
+                        }, timeoutMs);
+                    }),
+                ]);
+            }
+            finally {
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                }
+            }
+        },
+    };
+}

package/dist/node_modules/@boombot/core/agent-core/routing.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Adaptive routing for `@boombot/core`.
+ *
+ * The middleware (`createRoutingMiddleware`, name `'routing'`) picks a
+ * `fast` vs `deep` mode per turn with cheap deterministic signals — no LLM
+ * call, no I/O, no allocation of consequence:
+ *
+ * 1. `preflight` — `classifyTurn` over the last user message + tool names.
+ * 2. after every `modelRound` — `classifyToolCalls` may UPGRADE `fast` →
+ *    `deep` when the round's calls look risky (destructive tool, ≥2 network
+ *    / filesystem tools, or sensitive-looking args). The calls come from
+ *    the phase result, not `ctx.messages` (which never sees in-turn calls).
+ * 3. `finalize` — escalate `fast` → `deep` when the optional host-provided
+ *    verification snapshot reports unsupported claims, then run deep
+ *    verification (opt-in `LlmJudgePort`).
+ *
+ * The middleware never mutates `TurnContext`; per-turn state lives in a
+ * `WeakMap<TurnContext, RouteState>`. It never crashes a turn: like every
+ * middleware, hook errors are caught by the pipeline (`middleware.error`).
+ *
+ * Performance: all regexes are precompiled once by `compileRoutingConfig`
+ * (Unicode word-boundary, case-insensitive); `classifyTurn` /
+ * `classifyToolCalls` are pure synchronous functions; `enabled: false`
+ * installs no-op hooks that touch nothing at all.
+ */
+import type { TurnMiddleware } from './middleware.js';
+import type { LlmJudgePort } from './runtime-deps.js';
+/** Routing outcome: `fast` (cheap path) or `deep` (careful path). */
+export type RouteMode = 'fast' | 'deep';
+/** Tool risk classes used by the risk signal. */
+export type ToolRisk = 'safe' | 'network' | 'filesystem' | 'destructive';
+export interface RouteDecision {
+    readonly mode: RouteMode;
+    readonly reason: string;
+    /** Signal names evaluated, in order, up to and including the deciding one. */
+    readonly signals: readonly string[];
+}
+export interface RoutingConfig {
+    /** `false` = the middleware installs no-op hooks (zero-cost). */
+    readonly enabled: boolean;
+    /** Fallback when no signal fires. */
+    readonly defaultMode: RouteMode;
+    /** Tool/command name → forced mode. `'deep'` wins over `'fast'`. */
+    readonly overrides: Readonly<Record<string, RouteMode>>;
+    /** Exact tool name → risk. Prefixes and unknown tools are resolved by `compileRoutingConfig`. */
+    readonly toolRisk: Readonly<Record<string, ToolRisk>>;
+    readonly deepKeywords: readonly string[];
+    readonly fastKeywords: readonly string[];
+    readonly sensitiveArgKeywords: readonly string[];
+    /** # of `?` in the user text that forces `deep`. */
+    readonly complexityQuestionThreshold: number;
+    /** User text length above which the turn goes `deep`. */
+    readonly complexityLengthThreshold: number;
+    readonly llmJudge: {
+        readonly enabled: boolean;
+    };
+}
+export type RoutingConfigInput = Partial<Omit<RoutingConfig, 'llmJudge'>> & {
+    readonly llmJudge?: {
+        readonly enabled?: boolean;
+    };
+};
+/** `RoutingConfig` with every regex precompiled — build once, reuse per turn. */
+export interface CompiledRoutingConfig {
+    readonly enabled: boolean;
+    readonly defaultMode: RouteMode;
+    readonly overrides: Readonly<Record<string, RouteMode>>;
+    readonly exactRisk: Readonly<Record<string, ToolRisk>>;
+    readonly riskPrefixes: ReadonlyArray<readonly [string, ToolRisk]>;
+    readonly fastRe: RegExp;
+    readonly deepRe: RegExp;
+    readonly sensitiveRe: RegExp;
+    readonly complexityQuestionThreshold: number;
+    readonly complexityLengthThreshold: number;
+    readonly llmJudgeEnabled: boolean;
+}
+/** Input to `classifyTurn`. */
+export interface ClassifyTurnInput {
+    readonly text: string;
+    readonly toolNames: readonly string[];
+    readonly recentCorrections: number;
+}
+/** Tool call shape examined by `classifyToolCalls`. */
+export interface ToolCallForRouting {
+    readonly name: string;
+    readonly args: unknown;
+}
+/** Host-provided verification snapshot (e.g. from reasoning-guard); read-only. */
+export interface VerificationSnapshot {
+    readonly claims: readonly unknown[];
+    readonly evidence: readonly unknown[];
+    readonly unsupported: number;
+}
+export interface RoutingMiddlewareOptions {
+    readonly config?: RoutingConfigInput;
+    /** Opt-in: only consulted when `config.llmJudge.enabled` is true. */
+    readonly judge?: LlmJudgePort;
+    /** Optional accessor to the turn's verification snapshot. */
+    readonly getVerification?: () => VerificationSnapshot | undefined;
+    /** Optional accessor to the recent-corrections count (history signal). */
+    readonly getRecentCorrections?: () => number;
+}
+export declare function defaultRoutingConfig(): RoutingConfig;
+export declare function compileRoutingConfig(input?: RoutingConfigInput): CompiledRoutingConfig;
+/** Resolve a tool name → risk: exact match, then `prefix.` match, else `network`. */
+export declare function resolveToolRisk(name: string, config: CompiledRoutingConfig): ToolRisk;
+/**
+ * Pure, synchronous turn classification. Evaluates signals in priority
+ * order and stops at the first that decides; `signals` lists the names
+ * evaluated, up to and including the deciding one.
+ */
+export declare function classifyTurn(input: ClassifyTurnInput, config: CompiledRoutingConfig): RouteDecision;
+/**
+ * Returns a `deep` upgrade decision when this round's calls warrant it,
+ * else `undefined`. Args are only serialized (once per call) for tools that
+ * are not `safe`; circular args are skipped, never crash.
+ */
+export declare function classifyToolCalls(calls: ReadonlyArray<ToolCallForRouting>, config: CompiledRoutingConfig): RouteDecision | undefined;
+/**
+ * Adaptive routing middleware (name `'routing'`). Emits `turn.routed`
+ * (`{ runId, mode, reason }`) at `preflight` and again whenever a later
+ * `modelRound`'s tool calls upgrade the mode; emits `turn.escalated`
+ * (`{ runId, reason }`) at most once per turn.
+ *
+ * With `enabled: false` this returns no-op hooks that call nothing —
+ * not even the option callbacks.
+ */
+export declare function createRoutingMiddleware(options?: RoutingMiddlewareOptions): TurnMiddleware;