@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/node_modules/@boombot/core/jev/jev.js

@@ -0,0 +1,164 @@
+/**
+ * Jev — local 2-tier cognitive gate (System 1 Reflex).
+ *
+ * Tier 1 rules (pure TypeScript, zero LLM calls):
+ * - Noul: detect prompt injection, catastrophic commands, and policy violations.
+ * - Choice: classify intent into routing buckets.
+ *
+ * Philosophy:
+ * - Deterministic keywords first, then lightweight heuristics.
+ * - No external network, no model inference — target < 2ms per evaluation.
+ * - Threshold > 0.5 on noul score → BLOCK immediately.
+ * - Confidence < 0.45 on choice → escalate to System 2.
+ */
+// ───────────────────────── Noul patterns (danger detection) ─────────────────
+/** Hard danger signals: any single hit raises noul > 0.5 immediately. */
+const DANGER_HARD = [
+    // Prompt injection classic patterns
+    /ignore (?:all )?(?:previous|prior) (?:instructions?|rules?|prompts?)/iu,
+    /bỏ qua (?:mọi|tất cả) (?:chỉ dẫn|hướng dẫn|quy tắc)/iu,
+    /forget (?:all )?(?:your )?(?:instructions?|rules?|system prompt)/iu,
+    /you are now (?:a|an) (?:jailbreak|DAN|unrestricted)/iu,
+    /act as (?:a|an) (?:jailbreak|DAN|evil|harmful)/iu,
+    // Catastrophic shell commands
+    /rm\s+-rf\s+(?:\/|~|\*|\.)/u,
+    /rd\s+\/s\s+\/q\s+(?:c:|d:|\\)/iu,
+    /format\s+(?:c:|d:|\/dev\/)/iu,
+    /mkfs\./u,
+    /dd\s+if=\/dev\/zero/u,
+    // Database nukes
+    /drop\s+(?:database|table|schema)\s+/iu,
+    /truncate\s+table\s+/iu,
+    /delete\s+from\s+\w+\s*(?:;|$)/iu,
+    // Code execution via eval/exec
+    /\beval\s*\(/u,
+    /__import__\s*\(\s*['"]os['"]/u,
+    /exec\s*\(\s*(?:os\.|subprocess\.)/u,
+    // Owner Guard bypass attempts
+    /(?:reveal|show|print|output|leak)\s+(?:your\s+)?(?:system\s+prompt|api\s+key|secret|token|password)/iu,
+    /(?:pretend|assume|imagine)\s+(?:you\s+are|you're)\s+(?:ryan|the\s+owner|sếp)/iu,
+];
+/** Soft danger signals: accumulated points contribute to noul score. */
+const DANGER_SOFT = [
+    [/wget\s+.+\s*\|\s*(?:bash|sh|python)/u, 0.25],
+    [/curl\s+.+\s*\|\s*(?:bash|sh|python)/u, 0.25],
+    [/sudo\s+/u, 0.15],
+    [/chmod\s+[0-7]{3,4}\s+/u, 0.12],
+    [/base64\s+-d\s+/u, 0.18],
+    [/powershell\s+-(?:e(?:nc)?|encodedcommand)/iu, 0.22],
+    [/new-object\s+net\.webclient/iu, 0.20],
+    [/invoke-expression/iu, 0.22],
+    // Attempts to push agent to reveal internal data
+    [/(?:what|show|tell|list).+(?:api.?key|secret|token|password|credentials?)/iu, 0.30],
+    [/system\s+prompt/iu, 0.28],
+];
+function evalNoul(text, startMs) {
+    // Hard patterns: immediate block
+    for (const pattern of DANGER_HARD) {
+        if (pattern.test(text)) {
+            return {
+                type: 'noul',
+                noul: 0.92,
+                decision: true,
+                reason: `Matched hard-danger pattern: ${pattern.source.slice(0, 60)}`,
+                latency_ms: Date.now() - startMs,
+            };
+        }
+    }
+    // Soft accumulation
+    let score = 0.02; // baseline — clean input
+    let matchedReason;
+    for (const [pattern, weight] of DANGER_SOFT) {
+        if (pattern.test(text)) {
+            score += weight;
+            matchedReason ??= `Soft signal: ${pattern.source.slice(0, 50)}`;
+        }
+    }
+    score = Math.min(0.95, score);
+    return {
+        type: 'noul',
+        noul: Math.round(score * 10000) / 10000,
+        decision: score > 0.5,
+        reason: score > 0.1 ? matchedReason : undefined,
+        latency_ms: Date.now() - startMs,
+    };
+}
+// ───────────────────────── Choice routing classifier ────────────────────────
+export const DEFAULT_CHOICES = [
+    'file', // read/write/edit local files
+    'shell', // run terminal commands
+    'search', // web search or file grep
+    'code', // write, review, refactor code
+    'memory', // save/recall memory
+    'skill', // load a skill
+    'chat', // general conversation, Q&A
+    'creative', // write prose, poetry, design
+    'analysis', // data analysis, reasoning
+    'task', // schedule, plan, delegate
+];
+/** Weighted keyword signals per choice bucket. */
+const CHOICE_SIGNALS = [
+    ['file', ['file', 'đọc', 'ghi', 'sửa', 'tập tin', 'read', 'write', 'edit', 'open', 'save', 'path', 'directory', 'folder'], 1.0],
+    ['shell', ['bash', 'cmd', 'terminal', 'lệnh', 'command', 'run', 'chạy', 'execute', 'script', 'shell'], 1.0],
+    ['search', ['search', 'tìm', 'find', 'grep', 'web', 'lookup', 'query', 'tra cứu', 'google', 'look up'], 1.0],
+    ['code', ['code', 'function', 'class', 'implement', 'refactor', 'debug', 'fix', 'bug', 'viết', 'typescript', 'python', 'rust', 'build', 'compile'], 1.0],
+    ['memory', ['nhớ', 'remember', 'memory', 'lưu', 'save', 'note', 'bộ nhớ', 'ghi nhớ', 'add to memory'], 0.9],
+    ['skill', ['skill', 'skills', 'kỹ năng', 'load skill', 'use skill'], 0.8],
+    ['analysis', ['analyze', 'phân tích', 'tính toán', 'calculate', 'evaluate', 'compare', 'assess', 'summary', 'summarize', 'chart'], 1.0],
+    ['task', ['schedule', 'cron', 'task', 'plan', 'delegate', 'lịch', 'nhắc nhở', 'remind', 'todo', 'deadline'], 0.9],
+    ['creative', ['viết', 'write', 'sáng tác', 'poem', 'thơ', 'story', 'article', 'blog', 'design', 'idea', 'brainstorm'], 0.8],
+    ['chat', ['chào', 'hello', 'hi', 'how', 'what', 'why', 'when', 'tell me', 'explain', 'hỏi', 'giải thích', 'chia sẻ'], 0.7],
+];
+function evalChoice(text, choices, startMs) {
+    const lower = text.toLowerCase();
+    const probs = {};
+    // Populate with user-requested choices; use default weights if available.
+    for (const bucket of choices) {
+        const signalRow = CHOICE_SIGNALS.find(([b]) => b === bucket);
+        if (!signalRow) {
+            probs[bucket] = 0.05; // unknown bucket — minimal prior
+            continue;
+        }
+        const [, keywords, base] = signalRow;
+        let hits = 0;
+        for (const kw of keywords) {
+            if (lower.includes(kw))
+                hits++;
+        }
+        probs[bucket] = Math.max(0.01, base * (hits * 0.35 + 0.1));
+    }
+    // Normalise to a probability distribution
+    const total = Object.values(probs).reduce((a, b) => a + b, 0);
+    for (const k of Object.keys(probs)) {
+        probs[k] = Math.round((probs[k] / total) * 10000) / 10000;
+    }
+    const best = Object.entries(probs).sort(([, a], [, b]) => b - a)[0];
+    const [choice, confidence] = best ?? ['chat', 0.1];
+    return {
+        type: 'choice',
+        choice,
+        probabilities: probs,
+        confidence,
+        latency_ms: Date.now() - startMs,
+    };
+}
+/**
+ * Evaluate a user message through System 1 (Jev — pure TS, < 2ms, zero LLM calls).
+ *
+ * Returns `passed: false` when the message triggers a danger threshold —
+ * the caller MUST NOT route to System 2 in that case.
+ */
+export function jevEval(text, opts) {
+    const startMs = Date.now();
+    const choices = opts?.choices ?? DEFAULT_CHOICES;
+    const blockThreshold = opts?.blockThreshold ?? 0.5;
+    const noul = evalNoul(text, startMs);
+    const choice = evalChoice(text, choices, startMs);
+    const totalMs = Date.now() - startMs;
+    return {
+        noul,
+        choice,
+        passed: noul.noul <= blockThreshold,
+        latency_ms: totalMs,
+    };
+}

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

@@ -0,0 +1,22 @@
+export interface JevNoulResult {
+    readonly type: 'noul';
+    /** Probability of danger/malicious intent (0.0 to 1.0). */
+    readonly noul: number;
+    /** True if flagged dangerous (noul > 0.5). */
+    readonly decision: boolean;
+    readonly reason?: string;
+    readonly latency_ms: number;
+}
+export interface JevChoiceResult {
+    readonly type: 'choice';
+    readonly choice: string;
+    readonly probabilities: Record<string, number>;
+    readonly confidence: number;
+    readonly latency_ms: number;
+}
+export interface JevEvaluation {
+    readonly noul: JevNoulResult;
+    readonly choice: JevChoiceResult;
+    readonly passed: boolean;
+    readonly latency_ms: number;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/node_modules/@boombot/core/memory/consolidation/budget.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @boombot/core — hard resource caps for the LLM memory-consolidation job.
+ *
+ * Consolidation runs as a background job outside the agent turn loop. The LLM
+ * is the expensive resource here, so every run is bounded on four axes:
+ * conversations scanned, transcript chars fed to the model, LLM calls made,
+ * and wall-clock time. When any cap is hit the job stops cleanly and reports
+ * the stop reason — it never throws, never retries, and never fails the host.
+ *
+ * Pure logic, zero repo dependencies: safe to unit-test in isolation and to
+ * import from `packages/core` (a leaf package) without pulling agent-worker.
+ */
+export interface ConsolidationBudget {
+    /** Max conversations scanned per run. Must be >= 1. */
+    maxConversationsPerRun: number;
+    /** Max total transcript chars handed to the LLM per run. Must be >= 1. */
+    maxInputCharsPerRun: number;
+    /** Max LLM completion calls per run. Must be >= 1. */
+    maxLlmCallsPerRun: number;
+    /** Wall-clock budget per run in ms. Must be >= 1. */
+    timeoutMs: number;
+    /**
+     * Conversations shorter than this many chars are skipped without spending
+     * an LLM call (relevance pre-filter: one-liners rarely hold durable facts).
+     * Must be >= 0.
+     */
+    minConversationChars: number;
+}
+/** Sane defaults: ~20 conversations or ~60k chars or 10 LLM calls or 2 min. */
+export declare const DEFAULT_CONSOLIDATION_BUDGET: ConsolidationBudget;
+export type BudgetStopReason = 'max-conversations' | 'max-input-chars' | 'max-llm-calls' | 'timeout';
+export interface BudgetUsage {
+    conversations: number;
+    inputChars: number;
+    llmCalls: number;
+    elapsedMs: number;
+}
+/**
+ * Tracks one consolidation run against a `ConsolidationBudget`.
+ *
+ * `admitConversation` / `admitLlmCall` both check AND record: they return
+ * `null` when the unit is admitted, or the `BudgetStopReason` when a cap
+ * would be exceeded (in which case nothing is recorded and the caller should
+ * stop the run cleanly). `checkDeadline` reports a timeout without recording.
+ */
+export declare class ConsolidationBudgetTracker {
+    private readonly budget;
+    private readonly now;
+    private readonly startedAt;
+    private conversations;
+    private inputChars;
+    private llmCalls;
+    constructor(budget: ConsolidationBudget, now?: () => number);
+    /** Admit one conversation of `chars` transcript chars, or report the cap hit. */
+    admitConversation(chars: number): BudgetStopReason | null;
+    /** Admit one LLM call, or report the cap hit. */
+    admitLlmCall(): BudgetStopReason | null;
+    /** Report 'timeout' once the wall-clock budget is exhausted, else null. */
+    checkDeadline(): BudgetStopReason | null;
+    /** Too short to be worth an LLM call — the relevance pre-filter. */
+    isBelowMinChars(chars: number): boolean;
+    get usage(): BudgetUsage;
+}

package/dist/node_modules/@boombot/core/memory/consolidation/budget.js

@@ -0,0 +1,94 @@
+/**
+ * @boombot/core — hard resource caps for the LLM memory-consolidation job.
+ *
+ * Consolidation runs as a background job outside the agent turn loop. The LLM
+ * is the expensive resource here, so every run is bounded on four axes:
+ * conversations scanned, transcript chars fed to the model, LLM calls made,
+ * and wall-clock time. When any cap is hit the job stops cleanly and reports
+ * the stop reason — it never throws, never retries, and never fails the host.
+ *
+ * Pure logic, zero repo dependencies: safe to unit-test in isolation and to
+ * import from `packages/core` (a leaf package) without pulling agent-worker.
+ */
+/** Sane defaults: ~20 conversations or ~60k chars or 10 LLM calls or 2 min. */
+export const DEFAULT_CONSOLIDATION_BUDGET = Object.freeze({
+    maxConversationsPerRun: 20,
+    maxInputCharsPerRun: 60_000,
+    maxLlmCallsPerRun: 10,
+    timeoutMs: 120_000,
+    minConversationChars: 200,
+});
+function requirePositiveInt(name, value) {
+    if (!Number.isFinite(value) || Math.floor(value) !== value || value < 1) {
+        throw new Error(`ConsolidationBudget: ${name} must be a positive integer, got ${value}`);
+    }
+    return value;
+}
+/**
+ * Tracks one consolidation run against a `ConsolidationBudget`.
+ *
+ * `admitConversation` / `admitLlmCall` both check AND record: they return
+ * `null` when the unit is admitted, or the `BudgetStopReason` when a cap
+ * would be exceeded (in which case nothing is recorded and the caller should
+ * stop the run cleanly). `checkDeadline` reports a timeout without recording.
+ */
+export class ConsolidationBudgetTracker {
+    budget;
+    now;
+    startedAt;
+    conversations = 0;
+    inputChars = 0;
+    llmCalls = 0;
+    constructor(budget, now = () => Date.now()) {
+        this.budget = budget;
+        this.now = now;
+        requirePositiveInt('maxConversationsPerRun', budget.maxConversationsPerRun);
+        requirePositiveInt('maxInputCharsPerRun', budget.maxInputCharsPerRun);
+        requirePositiveInt('maxLlmCallsPerRun', budget.maxLlmCallsPerRun);
+        requirePositiveInt('timeoutMs', budget.timeoutMs);
+        if (!Number.isFinite(budget.minConversationChars) || budget.minConversationChars < 0) {
+            throw new Error(`ConsolidationBudget: minConversationChars must be >= 0, got ${budget.minConversationChars}`);
+        }
+        this.startedAt = this.now();
+    }
+    /** Admit one conversation of `chars` transcript chars, or report the cap hit. */
+    admitConversation(chars) {
+        const deadline = this.checkDeadline();
+        if (deadline !== null)
+            return deadline;
+        if (this.conversations >= this.budget.maxConversationsPerRun)
+            return 'max-conversations';
+        const safeChars = Number.isFinite(chars) && chars > 0 ? Math.floor(chars) : 0;
+        if (this.inputChars + safeChars > this.budget.maxInputCharsPerRun)
+            return 'max-input-chars';
+        this.conversations += 1;
+        this.inputChars += safeChars;
+        return null;
+    }
+    /** Admit one LLM call, or report the cap hit. */
+    admitLlmCall() {
+        const deadline = this.checkDeadline();
+        if (deadline !== null)
+            return deadline;
+        if (this.llmCalls >= this.budget.maxLlmCallsPerRun)
+            return 'max-llm-calls';
+        this.llmCalls += 1;
+        return null;
+    }
+    /** Report 'timeout' once the wall-clock budget is exhausted, else null. */
+    checkDeadline() {
+        return this.now() - this.startedAt >= this.budget.timeoutMs ? 'timeout' : null;
+    }
+    /** Too short to be worth an LLM call — the relevance pre-filter. */
+    isBelowMinChars(chars) {
+        return chars < this.budget.minConversationChars;
+    }
+    get usage() {
+        return {
+            conversations: this.conversations,
+            inputChars: this.inputChars,
+            llmCalls: this.llmCalls,
+            elapsedMs: this.now() - this.startedAt,
+        };
+    }
+}

package/dist/node_modules/@boombot/core/memory/consolidation/consolidator.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @boombot/core — LLM memory consolidation as a background job.
+ *
+ * Lesson from Hermes (and ChatGPT "Dreaming" / Mem0 research): consolidation
+ * — extracting durable facts from past conversations into long-term memory —
+ * must run as a background job with its own cursor, NEVER inside the agent
+ * turn loop. The loop is latency-sensitive and every extraction costs an LLM
+ * call; a per-turn hook would burn calls on small talk and touch the hot
+ * path. The host drives `runConsolidation` (or `ConsolidationJob`) on a
+ * timer, far away from turns.
+ *
+ * Design (non-destructive, Mem0-style):
+ * - Extraction is per conversation, via an injected LLM. The core never
+ *   imports agent-worker: the model arrives as `ConsolidationLlm`.
+ * - Writes are append-only through `MemoryProvider.save()` with
+ *   `provenance.source = 'model'`. There is no update path and no atomic
+ *   swap — superseding, if ever needed, is a host concern.
+ * - Deduplication is rule-based (normalized exact match, Mem0's NOOP):
+ *   no extra LLM call is spent deciding whether a fact already exists.
+ * - A relevance pre-filter skips conversations shorter than
+ *   `budget.minConversationChars` before any LLM call (AgentX-style).
+ * - Progress is a watermark cursor under `CONSOLIDATION_STATE_ID`, advanced
+ *   only past fully-processed conversations, so a crash or restart never
+ *   loses work and never reprocesses.
+ * - Four hard budget axes (conversations / input chars / LLM calls /
+ *   wall-clock) stop the run cleanly with a reason. The job never throws
+ *   for LLM or budget reasons — it reports.
+ *
+ * Pure with respect to the agent loop: this module never sees a turn.
+ */
+import { type BudgetStopReason, type BudgetUsage, type ConsolidationBudget } from './budget.js';
+import type { MemoryProvider } from '../provider.js';
+import type { MemoryScope } from '../types.js';
+/**
+ * Sentinel memory id under which consolidation run state (the watermark
+ * cursor) is kept. Mirrors the host's `memory:curation` convention: the
+ * state lives in the store's audit trail, not in a separate KV table.
+ */
+export declare const CONSOLIDATION_STATE_ID = "memory:consolidation";
+/** Actor id recorded in provenance for consolidation-written records. */
+export declare const CONSOLIDATION_ACTOR_ID = "memory-consolidation";
+/**
+ * The only way the consolidator talks to a model: one injected text
+ * completion per conversation. The host adapts its real LLM client
+ * (streaming or not) to this shape; `packages/core` stays a leaf.
+ */
+export interface ConsolidationLlm {
+    completeText(prompt: string, opts?: {
+        maxTokens?: number;
+    }): Promise<string>;
+}
+/** A finished conversation handed to the consolidator by the host. */
+export interface EndedConversation {
+    /** Stable conversation id (session id). Used as the provenance reference. */
+    id: string;
+    /** Principal that owns the conversation. */
+    principalId: string;
+    /** Scope extracted facts are written to (durable = principal scope). */
+    scope: MemoryScope;
+    /** Flattened user+assistant text; tool output is cut by the host. */
+    transcript: string;
+    /** ISO-8601 end time — doubles as the watermark value. */
+    endedAt: string;
+}
+/**
+ * Source of finished conversations after a watermark cursor. The host
+ * implements this over its session store; the core never touches sessions.
+ */
+export interface ConversationSource {
+    listEndedAfter(watermark: string | null, limit: number): Promise<readonly EndedConversation[]>;
+}
+/**
+ * Durable cursor storage. The host implements this over whatever backs
+ * its job state (the reference host uses the memory store's audit trail
+ * under `CONSOLIDATION_STATE_ID`, mirroring `memory:curation`).
+ */
+export interface WatermarkStore {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+}
+export interface ConsolidationReport {
+    at: string;
+    /** Conversations fully handled (including short-skips and parse-skips). */
+    processed: number;
+    factsCreated: number;
+    skippedShort: number;
+    skippedDuplicate: number;
+    stopReason: BudgetStopReason | 'completed' | 'llm-error';
+    usage: BudgetUsage;
+}
+export interface RunConsolidationDeps {
+    llm: ConsolidationLlm;
+    store: MemoryProvider;
+    conversations: ConversationSource;
+    watermarks: WatermarkStore;
+    budget?: ConsolidationBudget;
+}
+/**
+ * Build the extraction prompt for one conversation transcript. Exported so
+ * hosts (and tests) can see the exact contract, including the no-secrets
+ * guardrail: consolidation reads raw transcripts, so the extraction prompt
+ * must explicitly forbid persisting credentials.
+ */
+export declare function buildExtractionPrompt(transcript: string): string;
+/**
+ * Parse the model's extraction output into fact strings. Tolerant: accepts
+ * a bare array, objects with a "text" field, or plain strings; extracts the
+ * first `[...]` block when the model adds prose anyway. Unparseable output
+ * yields an empty list (the conversation is skipped, never fatal).
+ */
+export declare function parseExtractedFacts(raw: string): string[];
+/**
+ * Run one consolidation pass: read the watermark, extract durable facts from
+ * each new conversation via the injected LLM, and append them to memory.
+ *
+ * Never throws for LLM or budget reasons — failures are reported in
+ * `stopReason`. The watermark advances only past fully-processed
+ * conversations, so an LLM failure leaves the failed conversation for the
+ * next run while keeping everything already written.
+ */
+export declare function runConsolidation(deps: RunConsolidationDeps): Promise<ConsolidationReport>;
+export interface ConsolidationJobOptions {
+    llm: ConsolidationLlm;
+    store: MemoryProvider;
+    conversations: ConversationSource;
+    watermarks: WatermarkStore;
+    budget?: ConsolidationBudget;
+    /** Interval between runs in ms. Default 30 minutes. */
+    intervalMs?: number;
+    /**
+     * Called when a scheduled run throws. `runConsolidation` itself never
+     * throws for LLM/budget reasons; this covers host-adapter failures
+     * (session store down, watermark store down).
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Background job that runs consolidation on a timer. Start it once at host
+ * boot; it never touches the agent loop. `runOnce()` exists for tests and
+ * for hosts that drive scheduling themselves (e.g. cron). Mirrors
+ * `CurationJob`, except the run is async (the LLM is remote).
+ */
+export declare class ConsolidationJob {
+    private readonly options;
+    private timer;
+    private running;
+    constructor(options: ConsolidationJobOptions);
+    start(): void;
+    stop(): void;
+    get isRunning(): boolean;
+    runOnce(): Promise<ConsolidationReport>;
+}