@theowlops/boombot 0.0.0-stage → 1.1.1

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

@@ -0,0 +1,189 @@
+/**
+ * Core message + turn types for `@boombot/core`.
+ *
+ * Python owns the turn loop; these transport-agnostic contracts let the
+ * TypeScript gateway expose capabilities and middleware safely.
+ */
+import type { TurnMiddleware } from './middleware.js';
+import type { RouteMode } from './routing.js';
+import type { ToolError } from './tool-errors.js';
+/** Minimal JSON Schema subset used for tool parameter declarations. */
+export interface JSONSchema {
+    readonly type?: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+    readonly description?: string;
+    readonly properties?: Readonly<Record<string, JSONSchema>>;
+    readonly required?: readonly string[];
+    readonly items?: JSONSchema;
+    readonly enum?: readonly (string | number | boolean)[];
+    readonly additionalProperties?: boolean | JSONSchema;
+}
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+export interface ChatMessage {
+    readonly role: MessageRole;
+    readonly content: string;
+    /** Optional image references for multimodal user messages. */
+    readonly images?: readonly {
+        readonly url: string;
+        readonly detail?: 'low' | 'high' | 'auto';
+    }[];
+    /** Tool calls requested by the assistant in this message. */
+    readonly toolCalls?: readonly ToolCall[];
+    /** For role `'tool'`: the id of the call this message answers. */
+    readonly toolCallId?: string;
+    /** For role `'tool'`: tool name, for readability. */
+    readonly name?: string;
+}
+export interface ToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+}
+export interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: JSONSchema;
+}
+export interface ToolResult {
+    readonly callId: string;
+    readonly name: string;
+    /** Serialized output, or an error description when `error` is true. */
+    readonly output: string;
+    readonly error: boolean;
+    /** Present when the call was blocked by policy instead of executed. */
+    readonly deniedByPolicy?: boolean;
+    /** Present when the call was skipped because a human rejected approval. */
+    readonly rejectedByApprover?: boolean;
+    /** Classified error when execution threw and the retry policy produced this result. */
+    readonly toolError?: ToolError;
+}
+export interface TurnBudget {
+    /** Max model calls per turn, including a reserved final answer-only call. Defaults to 8. */
+    readonly maxRounds?: number;
+    /** Max total tool executions per turn. Defaults to 32. */
+    readonly maxToolCalls?: number;
+}
+/** One memory hit returned by the `MemoryPort.recall` interface. */
+export interface MemoryHit {
+    readonly id: string;
+    readonly content: string;
+    readonly score: number;
+}
+/** Output of the `recall` phase. */
+export interface MemoryRecallResult {
+    readonly hits: readonly MemoryHit[];
+}
+export interface TurnContext {
+    readonly sessionId: string;
+    readonly messages: readonly ChatMessage[];
+    readonly tools: readonly ToolDefinition[];
+    readonly budget?: TurnBudget;
+    /** Correlates events/approvals across a turn; generated when omitted. */
+    readonly runId?: string;
+    /** Middleware pipeline (onion order); empty/absent = zero-cost old path. */
+    readonly middlewares?: readonly TurnMiddleware[];
+}
+/** A single streamed chunk from the LLM. */
+export interface LlmChunk {
+    readonly delta?: string;
+    /** Chain-of-thought fragment (`reasoning_content` on OpenAI-compatible, `thinking` on Anthropic). */
+    readonly reasoningDelta?: string;
+    readonly toolCallDelta?: ToolCallDelta;
+    readonly toolCalls?: readonly ToolCall[];
+    readonly usage?: LlmUsage;
+    readonly done?: boolean;
+}
+/** Provider-reported token usage. Missing fields mean the provider omitted them. */
+export interface LlmUsage {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+}
+/** Fragment of a tool call streamed across chunks; accumulated by `modelRound`. */
+export interface ToolCallDelta {
+    readonly id?: string;
+    readonly index?: number;
+    readonly name?: string;
+    /** JSON fragment of the arguments object, concatenated in order. */
+    readonly argumentsJson?: string;
+}
+export type TurnStatus = 'completed' | 'cancelled' | 'error';
+export interface TurnResult {
+    readonly status: TurnStatus;
+    readonly messages: readonly ChatMessage[];
+    readonly rounds: number;
+    readonly toolCallsExecuted: number;
+    readonly toolCallsDenied: number;
+    readonly usage?: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly totalTokens: number;
+    };
+    readonly error?: string;
+}
+export type EventHandler = (event: AgentEvent) => void;
+/** Phase payloads consumed by gateway middleware after Python returns them. */
+export interface ModelRoundResult {
+    readonly text: string;
+    readonly toolCalls: readonly ToolCall[];
+    readonly assistantMessage: ChatMessage;
+}
+export interface ToolRoundResult {
+    readonly results: readonly ToolResult[];
+    readonly stoppedByPolicy: boolean;
+}
+export type PhaseName = 'preflight' | 'recall' | 'buildPrompt' | 'modelRound' | 'toolRound' | 'finalize';
+export type AgentEvent = {
+    readonly type: 'turn.start';
+    readonly sessionId: string;
+    readonly runId: string;
+} | {
+    readonly type: 'phase.start';
+    readonly phase: PhaseName;
+} | {
+    readonly type: 'phase.end';
+    readonly phase: PhaseName;
+    readonly durationMs: number;
+} | {
+    readonly type: 'middleware.error';
+    readonly middleware: string;
+    readonly phase: PhaseName;
+    readonly error: string;
+} | {
+    readonly type: 'memory.hits';
+    readonly count: number;
+} | {
+    readonly type: 'text.delta';
+    readonly text: string;
+} | {
+    readonly type: 'reasoning.delta';
+    readonly text: string;
+} | {
+    readonly type: 'tool.call';
+    readonly call: ToolCall;
+} | {
+    readonly type: 'tool.result';
+    readonly result: ToolResult;
+} | {
+    readonly type: 'policy.deny';
+    readonly call: ToolCall;
+    readonly reason: string;
+} | {
+    readonly type: 'approval.pending';
+    readonly call: ToolCall;
+    readonly reason: string;
+} | {
+    readonly type: 'approval.resolved';
+    readonly call: ToolCall;
+    readonly approved: boolean;
+} | {
+    readonly type: 'turn.routed';
+    readonly runId: string;
+    readonly mode: RouteMode;
+    readonly reason: string;
+} | {
+    readonly type: 'turn.escalated';
+    readonly runId: string;
+    readonly reason: string;
+} | {
+    readonly type: 'turn.end';
+    readonly result: TurnResult;
+};

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

@@ -0,0 +1,7 @@
+/**
+ * Core message + turn types for `@boombot/core`.
+ *
+ * Python owns the turn loop; these transport-agnostic contracts let the
+ * TypeScript gateway expose capabilities and middleware safely.
+ */
+export {};

package/dist/node_modules/@boombot/core/compaction/compactor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Context Compactor.
+ *
+ * Implements rolling context window compaction to prevent LLM context-overflow
+ * crashes. Preserves system prompt, compacts middle history into a structured summary,
+ * and maintains the most recent hot turns verbatim.
+ */
+import type { ChatMessage } from '../agent-core/types.js';
+import type { CompactionPolicy, CompactionResult } from './types.js';
+export interface ContextSummarizer {
+    summarize(messages: readonly ChatMessage[]): Promise<string>;
+}
+export declare class ContextCompactor {
+    private readonly policy;
+    private readonly customSummarizer?;
+    constructor(policy: CompactionPolicy, customSummarizer?: ContextSummarizer | undefined);
+    compact(messages: readonly ChatMessage[]): Promise<CompactionResult>;
+    private createDeterministicSummary;
+}

package/dist/node_modules/@boombot/core/compaction/compactor.js

@@ -0,0 +1,127 @@
+/**
+ * Context Compactor.
+ *
+ * Implements rolling context window compaction to prevent LLM context-overflow
+ * crashes. Preserves system prompt, compacts middle history into a structured summary,
+ * and maintains the most recent hot turns verbatim.
+ */
+import { estimateConversationTokens, } from './estimator.js';
+export class ContextCompactor {
+    policy;
+    customSummarizer;
+    constructor(policy, customSummarizer) {
+        this.policy = policy;
+        this.customSummarizer = customSummarizer;
+    }
+    async compact(messages) {
+        const originalTokens = estimateConversationTokens(messages);
+        const triggerThreshold = this.policy.triggerThreshold ?? 0.75;
+        const triggerTokens = Math.floor(this.policy.maxContextTokens * triggerThreshold);
+        if (originalTokens <= triggerTokens || messages.length <= 4) {
+            return {
+                compacted: false,
+                originalTokens,
+                compactedTokens: originalTokens,
+                messages,
+                prunedTurnsCount: 0,
+            };
+        }
+        // Separate system messages, middle turns, and hot zone turns
+        const systemMessages = [];
+        const nonSystemMessages = [];
+        for (const msg of messages) {
+            if (msg.role === 'system') {
+                systemMessages.push(msg);
+            }
+            else {
+                nonSystemMessages.push(msg);
+            }
+        }
+        const hotZoneRounds = Math.max(2, this.policy.hotZoneRounds ?? 4);
+        // Each round typically consists of user + assistant (+ tool calls/results)
+        // Conservatively take last (hotZoneRounds * 2) non-system messages as hot zone
+        const hotZoneSplitIndex = Math.max(0, nonSystemMessages.length - hotZoneRounds * 2);
+        const prunedMessages = nonSystemMessages.slice(0, hotZoneSplitIndex);
+        const hotZoneMessages = nonSystemMessages.slice(hotZoneSplitIndex);
+        if (prunedMessages.length === 0) {
+            return {
+                compacted: false,
+                originalTokens,
+                compactedTokens: originalTokens,
+                messages,
+                prunedTurnsCount: 0,
+            };
+        }
+        // Generate summary of pruned messages
+        let summaryText;
+        if (this.customSummarizer) {
+            try {
+                summaryText = await this.customSummarizer.summarize(prunedMessages);
+            }
+            catch {
+                summaryText = this.createDeterministicSummary(prunedMessages);
+            }
+        }
+        else {
+            summaryText = this.createDeterministicSummary(prunedMessages);
+        }
+        const summaryMessage = {
+            role: 'system',
+            content: `[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were compacted into the summary below. This is a handoff from a previous context window — treat it as background reference, NOT as active instructions. Do NOT answer questions or fulfill requests mentioned in this summary; they were already addressed. Respond ONLY to the latest user message that appears AFTER this summary.\n\n${summaryText}\n\n--- END OF CONTEXT SUMMARY ---`,
+        };
+        const finalMessages = [
+            ...systemMessages,
+            summaryMessage,
+            ...hotZoneMessages,
+        ];
+        const compactedTokens = estimateConversationTokens(finalMessages);
+        return {
+            compacted: true,
+            originalTokens,
+            compactedTokens,
+            messages: finalMessages,
+            prunedTurnsCount: prunedMessages.length,
+            summary: summaryText,
+        };
+    }
+    createDeterministicSummary(messages) {
+        const userTopics = [];
+        const userMessagesVerbatim = [];
+        const toolActions = [];
+        const keyResolutions = [];
+        for (const msg of messages) {
+            if (msg.role === 'user') {
+                const text = msg.content.trim();
+                const snippet = text.slice(0, 160);
+                if (snippet)
+                    userTopics.push(`- User requested: "${snippet}"`);
+                if (text)
+                    userMessagesVerbatim.unshift(`> ${text.slice(0, 240)}`);
+            }
+            else if (msg.role === 'assistant') {
+                if (msg.toolCalls && msg.toolCalls.length > 0) {
+                    for (const tc of msg.toolCalls) {
+                        toolActions.push(`- Executed tool: ${tc.name}`);
+                    }
+                }
+                else if (msg.content) {
+                    const firstLine = (msg.content.split('\n')[0] ?? '').trim().slice(0, 160);
+                    if (firstLine)
+                        keyResolutions.push(`- Assistant confirmed: ${firstLine}`);
+                }
+            }
+            else if (msg.role === 'tool') {
+                const preview = msg.content.trim().slice(0, 100);
+                toolActions.push(`  Tool output preview: ${preview}...`);
+            }
+        }
+        return [
+            '## Historical Task Snapshot\n' + (userTopics.length > 0 ? userTopics.slice(-6).join('\n') : '- Routine assistance turns completed.'),
+            toolActions.length > 0 ? `## Completed Actions\n${toolActions.slice(-8).join('\n')}` : '',
+            keyResolutions.length > 0 ? `## Key Decisions & Resolutions\n${keyResolutions.slice(-5).join('\n')}` : '',
+            userMessagesVerbatim.length > 0 ? `## User Messages (verbatim, newest first)\n${userMessagesVerbatim.slice(0, 4).join('\n\n')}` : '',
+        ]
+            .filter(Boolean)
+            .join('\n\n');
+    }
+}

package/dist/node_modules/@boombot/core/compaction/estimator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Multilingual Token Estimator.
+ *
+ * Fast heuristic token estimation supporting mixed ASCII, code, and
+ * multi-byte Unicode (Vietnamese diacritics, CJK).
+ */
+import type { ChatMessage } from '../agent-core/types.js';
+export declare function estimateTextTokens(text: string): number;
+export declare function estimateMessageTokens(message: ChatMessage): number;
+export declare function estimateConversationTokens(messages: readonly ChatMessage[]): number;

package/dist/node_modules/@boombot/core/compaction/estimator.js

@@ -0,0 +1,48 @@
+/**
+ * Multilingual Token Estimator.
+ *
+ * Fast heuristic token estimation supporting mixed ASCII, code, and
+ * multi-byte Unicode (Vietnamese diacritics, CJK).
+ */
+export function estimateTextTokens(text) {
+    if (!text || text.length === 0)
+        return 0;
+    let asciiChars = 0;
+    let nonAsciiChars = 0;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 128) {
+            asciiChars++;
+        }
+        else {
+            nonAsciiChars++;
+        }
+    }
+    // English/Code: ~3.8 chars per BPE token + 1 token baseline
+    // Vietnamese / CJK Unicode: ~1.8 chars per BPE token due to byte-pair splitting
+    const asciiTokens = Math.ceil(asciiChars / 3.8);
+    const nonAsciiTokens = Math.ceil(nonAsciiChars / 1.8);
+    return asciiTokens + nonAsciiTokens;
+}
+export function estimateMessageTokens(message) {
+    let count = 4; // role & framing token overhead
+    count += estimateTextTokens(message.content);
+    if (message.toolCalls) {
+        for (const tc of message.toolCalls) {
+            count += 8; // tool call framing
+            count += estimateTextTokens(tc.name);
+            count += estimateTextTokens(JSON.stringify(tc.arguments ?? {}));
+        }
+    }
+    if (message.toolCallId) {
+        count += estimateTextTokens(message.toolCallId);
+    }
+    return count;
+}
+export function estimateConversationTokens(messages) {
+    let total = 2; // prompt start/end framing
+    for (const m of messages) {
+        total += estimateMessageTokens(m);
+    }
+    return total;
+}

package/dist/node_modules/@boombot/core/compaction/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './estimator.js';
+export * from './compactor.js';

package/dist/node_modules/@boombot/core/compaction/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './estimator.js';
+export * from './compactor.js';

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

@@ -0,0 +1,31 @@
+/**
+ * Context Window Compaction Types.
+ *
+ * Defines contracts for tracking message context token consumption,
+ * rolling compaction strategies, and summary generation.
+ */
+import type { ChatMessage } from '../agent-core/types.js';
+export interface CompactionPolicy {
+    /** Maximum allowable context tokens before compaction triggers (e.g. 257000 or 32000). */
+    readonly maxContextTokens: number;
+    /** Trigger threshold ratio [0.1, 0.95]. Default 0.75 (compact at 75% capacity). */
+    readonly triggerThreshold?: number;
+    /** Target token budget after compaction completes [0.2, 0.8]. Default 0.40. */
+    readonly targetRatio?: number;
+    /** Number of newest turns to always preserve uncompacted (hot zone). Default 4. */
+    readonly hotZoneRounds?: number;
+}
+export interface CompactionResult {
+    readonly compacted: boolean;
+    readonly originalTokens: number;
+    readonly compactedTokens: number;
+    readonly messages: readonly ChatMessage[];
+    readonly prunedTurnsCount: number;
+    readonly summary?: string;
+}
+export interface TurnSummary {
+    readonly roundRange: [number, number];
+    readonly keyDecisions: readonly string[];
+    readonly artifactsProduced: readonly string[];
+    readonly toolResultsSummary: readonly string[];
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Context Window Compaction Types.
+ *
+ * Defines contracts for tracking message context token consumption,
+ * rolling compaction strategies, and summary generation.
+ */
+export {};

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

@@ -0,0 +1,9 @@
+export * from './agent-core/index.js';
+export * from './memory/index.js';
+export * from './task-runner/index.js';
+export * from './scheduler/index.js';
+export * from './research/index.js';
+export * from './workflow/index.js';
+export * from './compaction/index.js';
+export * from './reflection/index.js';
+export * from './jev/index.js';

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

@@ -0,0 +1,9 @@
+export * from './agent-core/index.js';
+export * from './memory/index.js';
+export * from './task-runner/index.js';
+export * from './scheduler/index.js';
+export * from './research/index.js';
+export * from './workflow/index.js';
+export * from './compaction/index.js';
+export * from './reflection/index.js';
+export * from './jev/index.js';

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

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './jev.js';

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

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './jev.js';

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

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ */
+import type { JevEvaluation } from './types.js';
+export declare const DEFAULT_CHOICES: readonly ["file", "shell", "search", "code", "memory", "skill", "chat", "creative", "analysis", "task"];
+export type DefaultChoice = typeof DEFAULT_CHOICES[number];
+export interface JevOptions {
+    /** Override the set of routing choices. Defaults to {@link DEFAULT_CHOICES}. */
+    readonly choices?: readonly string[];
+    /** Noul threshold to block. Defaults to 0.5. */
+    readonly blockThreshold?: number;
+}
+/**
+ * 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 declare function jevEval(text: string, opts?: JevOptions): JevEvaluation;
+export type { JevEvaluation, JevNoulResult, JevChoiceResult } from './types.js';