@theowlops/boombot 0.0.0-stage → 1.1.0

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

@@ -0,0 +1,437 @@
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_DEEP_KEYWORDS = [
+    'so sánh',
+    'phân tích',
+    'đánh giá',
+    'tại sao',
+    'vì sao',
+    'ưu nhược',
+    'lựa chọn',
+    'nên chọn',
+    'chi tiết',
+    'kỹ lưỡng',
+    'toàn diện',
+    'trade-off',
+    'tradeoff',
+    'compare',
+    'analyze',
+    'analyse',
+    'analysis',
+    'evaluate',
+    'evaluation',
+    'why',
+    'explain',
+    'pros and cons',
+    'in depth',
+    'deep dive',
+];
+const DEFAULT_FAST_KEYWORDS = [
+    'trả lời nhanh',
+    'nhanh gọn',
+    'gọn lẹ',
+    'tóm tắt',
+    'tóm lại',
+    'quick',
+    'brief',
+    'short',
+    'concise',
+    'tl;dr',
+    'tldr',
+    'nhanh',
+];
+const DEFAULT_SENSITIVE_ARG_KEYWORDS = [
+    'password',
+    'passwd',
+    'secret',
+    'api_key',
+    'apikey',
+    'access_token',
+    'private_key',
+    'privatekey',
+    'credential',
+    'auth_token',
+    'mật khẩu',
+];
+/** Default risk by name prefix; exact names go in `toolRisk`. Unknown → `network`. */
+const DEFAULT_RISK_PREFIXES = [
+    ['research.', 'network'],
+    ['session.', 'safe'],
+    ['schedule.', 'filesystem'],
+    ['provider.', 'filesystem'],
+    ['file.', 'filesystem'],
+    ['channel.', 'network'],
+];
+export function defaultRoutingConfig() {
+    return {
+        enabled: false,
+        defaultMode: 'fast',
+        overrides: {},
+        toolRisk: { 'memory.search': 'safe' },
+        deepKeywords: DEFAULT_DEEP_KEYWORDS,
+        fastKeywords: DEFAULT_FAST_KEYWORDS,
+        sensitiveArgKeywords: DEFAULT_SENSITIVE_ARG_KEYWORDS,
+        complexityQuestionThreshold: 2,
+        complexityLengthThreshold: 800,
+        llmJudge: { enabled: false },
+    };
+}
+// ---------------------------------------------------------------------------
+// Regex compilation (once)
+// ---------------------------------------------------------------------------
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Unicode word-boundary, case-insensitive alternation. Never matches when empty. */
+function compileKeywordRegex(keywords) {
+    if (keywords.length === 0) {
+        return /(?!)/u;
+    }
+    const alt = keywords.map(escapeRegExp).join('|');
+    // NOTE: no `g` flag — `RegExp.test()` with `g` is stateful via `lastIndex`
+    // and would alternate true/false across calls sharing one compiled config.
+    return new RegExp(`(?<![\\p{L}\\p{N}_])(?:${alt})(?![\\p{L}\\p{N}_])`, 'iu');
+}
+export function compileRoutingConfig(input = {}) {
+    const base = defaultRoutingConfig();
+    return Object.freeze({
+        enabled: input.enabled ?? base.enabled,
+        defaultMode: input.defaultMode ?? base.defaultMode,
+        overrides: Object.freeze({ ...(input.overrides ?? base.overrides) }),
+        exactRisk: Object.freeze({ ...(input.toolRisk ?? base.toolRisk) }),
+        riskPrefixes: DEFAULT_RISK_PREFIXES,
+        fastRe: compileKeywordRegex(input.fastKeywords ?? base.fastKeywords),
+        deepRe: compileKeywordRegex(input.deepKeywords ?? base.deepKeywords),
+        sensitiveRe: compileKeywordRegex(input.sensitiveArgKeywords ?? base.sensitiveArgKeywords),
+        complexityQuestionThreshold: input.complexityQuestionThreshold ?? base.complexityQuestionThreshold,
+        complexityLengthThreshold: input.complexityLengthThreshold ?? base.complexityLengthThreshold,
+        llmJudgeEnabled: input.llmJudge?.enabled ?? base.llmJudge.enabled,
+    });
+}
+// ---------------------------------------------------------------------------
+// classifyTurn — pure, sync, no I/O
+// ---------------------------------------------------------------------------
+const RISK_RANK = {
+    safe: 0,
+    network: 1,
+    filesystem: 2,
+    destructive: 3,
+};
+/** Resolve a tool name → risk: exact match, then `prefix.` match, else `network`. */
+export function resolveToolRisk(name, config) {
+    const exact = config.exactRisk[name];
+    if (exact !== undefined) {
+        return exact;
+    }
+    for (const [prefix, risk] of config.riskPrefixes) {
+        if (name.startsWith(prefix)) {
+            return risk;
+        }
+    }
+    return 'network';
+}
+const SIG_USER_KEYWORD = 'user-keyword';
+const SIG_OVERRIDE = 'override';
+const SIG_RISK = 'risk';
+const SIG_COMPLEXITY = 'complexity';
+const SIG_HISTORY = 'history';
+const SIG_DEFAULT = 'default';
+const R_USER_KEYWORD_FAST = 'user-keyword:fast';
+const R_USER_KEYWORD_DEEP = 'user-keyword:deep';
+const R_RISK_DESTRUCTIVE = 'risk:destructive';
+const R_RISK_MULTI = 'risk:multi-network';
+const R_COMPLEXITY_QUESTIONS = 'complexity:questions';
+const R_COMPLEXITY_DEEP_KEYWORD = 'complexity:deep-keyword';
+const R_COMPLEXITY_LENGTH = 'complexity:length';
+const R_HISTORY_CORRECTIONS = 'history:corrections';
+const V_FAST_KEYWORD = { mode: 'fast', reason: R_USER_KEYWORD_FAST };
+const V_DEEP_KEYWORD = { mode: 'deep', reason: R_USER_KEYWORD_DEEP };
+const V_DEEP_DESTRUCTIVE = { mode: 'deep', reason: R_RISK_DESTRUCTIVE };
+const V_DEEP_RISK_MULTI = { mode: 'deep', reason: R_RISK_MULTI };
+const V_DEEP_QUESTIONS = { mode: 'deep', reason: R_COMPLEXITY_QUESTIONS };
+const V_DEEP_COMPLEXITY_KEYWORD = { mode: 'deep', reason: R_COMPLEXITY_DEEP_KEYWORD };
+const V_DEEP_LENGTH = { mode: 'deep', reason: R_COMPLEXITY_LENGTH };
+const V_DEEP_CORRECTIONS = { mode: 'deep', reason: R_HISTORY_CORRECTIONS };
+function countChar(text, code) {
+    let n = 0;
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === code) {
+            n++;
+        }
+    }
+    return n;
+}
+function buildWork(input, config) {
+    const text = input.text;
+    let overrideDeep = false;
+    let overrideFast = false;
+    let overrideDeepName;
+    let overrideFastName;
+    let maxRiskRank = 0;
+    let riskyCount = 0;
+    for (const name of input.toolNames) {
+        const override = config.overrides[name];
+        if (override === 'deep') {
+            overrideDeep = true;
+            overrideDeepName ??= name;
+        }
+        else if (override === 'fast') {
+            overrideFast = true;
+            overrideFastName ??= name;
+        }
+        const rank = RISK_RANK[resolveToolRisk(name, config)];
+        if (rank > maxRiskRank) {
+            maxRiskRank = rank;
+        }
+        if (rank === RISK_RANK.network || rank === RISK_RANK.filesystem) {
+            riskyCount++;
+        }
+    }
+    return {
+        text,
+        recentCorrections: input.recentCorrections,
+        config,
+        fastHit: config.fastRe.test(text),
+        deepHit: config.deepRe.test(text),
+        overrideMode: overrideDeep ? 'deep' : overrideFast ? 'fast' : undefined,
+        overrideName: overrideDeepName ?? overrideFastName,
+        maxRiskRank,
+        riskyCount,
+        questionCount: countChar(text, 63), // '?'
+    };
+}
+/** Priority-ordered signal table: the first check that returns a verdict wins. */
+const SIGNAL_CHECKS = [
+    {
+        name: SIG_USER_KEYWORD,
+        run: (w) => (w.deepHit ? V_DEEP_KEYWORD : w.fastHit ? V_FAST_KEYWORD : undefined),
+    },
+    {
+        name: SIG_OVERRIDE,
+        run: (w) => w.overrideMode === undefined
+            ? undefined
+            : { mode: w.overrideMode, reason: `override:${w.overrideName ?? 'unknown'}` },
+    },
+    {
+        name: SIG_RISK,
+        run: (w) => w.maxRiskRank >= RISK_RANK.destructive
+            ? V_DEEP_DESTRUCTIVE
+            : w.riskyCount >= 2
+                ? V_DEEP_RISK_MULTI
+                : undefined,
+    },
+    {
+        name: SIG_COMPLEXITY,
+        run: (w) => w.questionCount >= w.config.complexityQuestionThreshold
+            ? V_DEEP_QUESTIONS
+            : w.deepHit
+                ? V_DEEP_COMPLEXITY_KEYWORD
+                : w.text.length > w.config.complexityLengthThreshold
+                    ? V_DEEP_LENGTH
+                    : undefined,
+    },
+    {
+        name: SIG_HISTORY,
+        run: (w) => (w.recentCorrections >= 1 ? V_DEEP_CORRECTIONS : undefined),
+    },
+    {
+        name: SIG_DEFAULT,
+        run: (w) => ({ mode: w.config.defaultMode, reason: `default:${w.config.defaultMode}` }),
+    },
+];
+/**
+ * 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 function classifyTurn(input, config) {
+    const work = buildWork(input, config);
+    const signals = [];
+    for (const check of SIGNAL_CHECKS) {
+        signals.push(check.name);
+        const verdict = check.run(work);
+        if (verdict !== undefined) {
+            return { mode: verdict.mode, reason: verdict.reason, signals: Object.freeze(signals) };
+        }
+    }
+    // Unreachable: the `default` signal always decides; kept for the compiler.
+    return {
+        mode: config.defaultMode,
+        reason: `default:${config.defaultMode}`,
+        signals: Object.freeze(signals),
+    };
+}
+// ---------------------------------------------------------------------------
+// classifyToolCalls — fast → deep upgrade per tool round
+// ---------------------------------------------------------------------------
+const R_TOOLCALL_DESTRUCTIVE = 'toolcall:destructive';
+const R_TOOLCALL_MULTI = 'toolcall:multi-network-fs';
+const R_TOOLCALL_SENSITIVE = 'toolcall:sensitive-args';
+/**
+ * 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 function classifyToolCalls(calls, config) {
+    let riskyCount = 0;
+    const nonSafe = [];
+    for (const call of calls) {
+        const risk = resolveToolRisk(call.name, config);
+        if (risk === 'destructive') {
+            return { mode: 'deep', reason: R_TOOLCALL_DESTRUCTIVE, signals: ['toolcall-risk'] };
+        }
+        if (risk === 'network' || risk === 'filesystem') {
+            riskyCount++;
+        }
+        if (risk !== 'safe') {
+            nonSafe.push(call);
+        }
+    }
+    if (riskyCount >= 2) {
+        return { mode: 'deep', reason: R_TOOLCALL_MULTI, signals: ['toolcall-risk'] };
+    }
+    // Only serialize args when the earlier signals didn't already decide.
+    for (const call of nonSafe) {
+        let json;
+        try {
+            json = JSON.stringify(call.args) ?? '';
+        }
+        catch {
+            continue;
+        }
+        if (config.sensitiveRe.test(json)) {
+            return { mode: 'deep', reason: R_TOOLCALL_SENSITIVE, signals: ['toolcall-args'] };
+        }
+    }
+    return undefined;
+}
+const REASON_GUARD_UNSUPPORTED = 'guard:unsupported-claims';
+const UNKNOWN_RUN_ID = 'unknown';
+function lastUserText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message?.role === 'user') {
+            return message.content;
+        }
+    }
+    return '';
+}
+/**
+ * Fast → deep upgrade when a model round's tool calls look risky.
+ *
+ * NOTE: the calls are read from the `modelRound` phase RESULT, never from
+ * `ctx.messages` — the turn pipeline keeps the working message list in a
+ * local variable and never writes the in-turn assistant messages back to
+ * the context, so reading `ctx.messages` here silently disabled the
+ * upgrade (it could only ever see the turn's input history).
+ */
+function upgradeOnRiskyToolCalls(states, config, ctx, result, emit) {
+    const state = states.get(ctx);
+    if (state === undefined || state.mode !== 'fast') {
+        return;
+    }
+    const toolCalls = result
+        ?.toolCalls;
+    if (toolCalls === undefined || toolCalls.length === 0) {
+        return;
+    }
+    const upgrade = classifyToolCalls(toolCalls.map((call) => ({ name: call.name, args: call.arguments })), config);
+    if (upgrade === undefined) {
+        return;
+    }
+    state.mode = 'deep';
+    state.reason = upgrade.reason;
+    emit?.({
+        type: 'turn.routed',
+        runId: ctx.runId ?? UNKNOWN_RUN_ID,
+        mode: 'deep',
+        reason: upgrade.reason,
+    });
+}
+/**
+ * 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 function createRoutingMiddleware(options = {}) {
+    const config = compileRoutingConfig(options.config);
+    if (!config.enabled) {
+        return {
+            name: 'routing',
+            beforePhase: () => { },
+            afterPhase: () => { },
+        };
+    }
+    const { judge, getVerification, getRecentCorrections } = options;
+    const states = new WeakMap();
+    return {
+        name: 'routing',
+        beforePhase(phase, ctx, emit) {
+            if (phase === 'preflight') {
+                const toolNames = ctx.tools.map((tool) => tool.name);
+                const decision = classifyTurn({
+                    text: lastUserText(ctx.messages),
+                    toolNames,
+                    recentCorrections: getRecentCorrections?.() ?? 0,
+                }, config);
+                states.set(ctx, { mode: decision.mode, reason: decision.reason, escalated: false });
+                emit?.({
+                    type: 'turn.routed',
+                    runId: ctx.runId ?? UNKNOWN_RUN_ID,
+                    mode: decision.mode,
+                    reason: decision.reason,
+                });
+                return;
+            }
+        },
+        async afterPhase(phase, ctx, result, emit) {
+            if (phase === 'modelRound') {
+                upgradeOnRiskyToolCalls(states, config, ctx, result, emit);
+                return;
+            }
+            if (phase !== 'finalize') {
+                return;
+            }
+            const state = states.get(ctx);
+            if (state === undefined || state.escalated) {
+                return;
+            }
+            const verification = getVerification?.();
+            if (verification !== undefined && verification.unsupported > 0 && state.mode === 'fast') {
+                state.escalated = true;
+                state.mode = 'deep';
+                state.reason = REASON_GUARD_UNSUPPORTED;
+                emit?.({
+                    type: 'turn.escalated',
+                    runId: ctx.runId ?? UNKNOWN_RUN_ID,
+                    reason: REASON_GUARD_UNSUPPORTED,
+                });
+            }
+            if (state.mode !== 'deep') {
+                return;
+            }
+            if (!config.llmJudgeEnabled || judge === undefined) {
+                return;
+            }
+            try {
+                await judge.judge({
+                    claims: verification?.claims ?? [],
+                    evidence: verification?.evidence ?? [],
+                });
+            }
+            catch (err) {
+                emit?.({
+                    type: 'middleware.error',
+                    middleware: 'routing',
+                    phase,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        },
+    };
+}

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

@@ -0,0 +1,88 @@
+/**
+ * Gateway capabilities exposed to the Python agent turn loop.
+ *
+ * Python reaches only these interfaces through the internal RPC bridge.
+ * The gateway provides concrete implementations (adapters).
+ *
+ * NOTE: `LlmClient` here is deliberately a minimal loop-facing interface,
+ * separate from `@boombot/llm-core`'s richer contract. Gateway adapters
+ * translate between the two.
+ */
+import type { ChatMessage, LlmChunk, MemoryHit, ToolCall, ToolDefinition, ToolResult } from './types.js';
+/** The only way the loop talks to a model: one streaming call per round. */
+export interface LlmClient {
+    complete(messages: readonly ChatMessage[], tools: readonly ToolDefinition[], signal?: AbortSignal): AsyncIterable<LlmChunk>;
+}
+/** Executes a single approved tool call. */
+export interface ToolExecutor {
+    execute(call: ToolCall, signal?: AbortSignal): Promise<ToolResult>;
+}
+/** Lightweight recall used before the first model round (escalation to a
+ *  deeper retrieval agent, if ever needed, lives outside the loop). */
+export interface MemoryPort {
+    recall(query: string): Promise<readonly MemoryHit[]>;
+}
+export type PolicyDecision = 'allow' | 'deny' | 'ask';
+/**
+ * Mandatory gate before every tool call (accident-prevention, not a
+ * security boundary — see root SECURITY.md when it lands).
+ * `'ask'` is treated as a denial when no `ApprovalPort` is configured;
+ * with an approval port, the turn pauses and asks a human (HITL).
+ */
+export interface PolicyPort {
+    checkToolCall(call: ToolCall): PolicyDecision | Promise<PolicyDecision>;
+}
+/** A human-in-the-loop approval request for one tool call. */
+export interface ApprovalRequest {
+    readonly runId: string;
+    readonly callId: string;
+    readonly toolName: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly reason: string;
+}
+/** The human's verdict: approve (optionally with edited args) or reject. */
+export interface ApprovalVerdict {
+    readonly approved: boolean;
+    readonly editedArgs?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Human-in-the-loop approval channel (UI prompt, chat message, etc.).
+ * MUST reject with an `Error` named `'AbortError'` when `signal` aborts,
+ * and throw `ApprovalTimeoutError` when the decision times out.
+ */
+export interface ApprovalPort {
+    requestApproval(req: ApprovalRequest, signal?: AbortSignal): Promise<ApprovalVerdict>;
+}
+/** Thrown by an `ApprovalPort` when nobody decides within `timeoutMs`. */
+export declare class ApprovalTimeoutError extends Error {
+    readonly code: "APPROVAL_TIMEOUT";
+    constructor(runId: string, timeoutMs: number);
+}
+/** Everything one cognitive turn needs from the gateway. */
+export interface AgentRuntimeDeps {
+    readonly llm: LlmClient;
+    readonly tools: ToolExecutor;
+    readonly memory: MemoryPort;
+    readonly policy: PolicyPort;
+    /** Optional: when absent, a policy `'ask'` is treated as a safe denial. */
+    readonly approval?: ApprovalPort;
+}
+/** Input to the optional LLM judge used by adaptive routing's deep verification. */
+export interface JudgeInput {
+    readonly claims: readonly unknown[];
+    readonly evidence: readonly unknown[];
+}
+/** Verdict returned by the LLM judge. */
+export interface JudgeVerdict {
+    readonly supported: boolean;
+    readonly unsupportedClaims: readonly string[];
+    readonly reason?: string;
+}
+/**
+ * Optional LLM-as-judge port for adaptive routing escalation. Disabled by
+ * default; the host wires an implementation only when it wants an extra
+ * model pass over the verification snapshot after an escalation.
+ */
+export interface LlmJudgePort {
+    judge(input: JudgeInput, signal?: AbortSignal): Promise<JudgeVerdict>;
+}

package/dist/node_modules/@boombot/core/agent-core/runtime-deps.js

@@ -0,0 +1,8 @@
+/** Thrown by an `ApprovalPort` when nobody decides within `timeoutMs`. */
+export class ApprovalTimeoutError extends Error {
+    code = 'APPROVAL_TIMEOUT';
+    constructor(runId, timeoutMs) {
+        super(`approval_timeout: no decision for run ${runId} within ${timeoutMs}ms`);
+        this.name = 'ApprovalTimeoutError';
+    }
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Standard tool error policy for `@boombot/core`.
+ *
+ * Every tool executor failure is classified into a `ToolError` (a code +
+ * retryability flag + message) instead of propagating as a raw throw.
+ * `withToolRetry` wraps a `ToolExecutor` so transient failures are retried
+ * with backoff; exhausted retries become a `ToolResult` with `error: true`
+ * that the model can see and react to — a throw NEVER kills the turn.
+ *
+ * BEHAVIOR CHANGE (vs. the pre-upgrade pipeline): previously a throw from
+ * `ToolExecutor.execute` propagated out of `toolRound` and ended the turn
+ * with `status: 'error'`. Now `toolRound` always wraps execution with
+ * `withToolRetry` (defaults), so a throw becomes a tool message the model
+ * reads in the next round.
+ */
+import type { ToolExecutor } from './runtime-deps.js';
+export type ToolErrorCode = 'TIMEOUT' | 'DENIED' | 'FAILED' | 'INVALID_ARGS' | 'RATE_LIMITED';
+export interface ToolError {
+    readonly code: ToolErrorCode;
+    /** True when retrying the exact same call has a chance of succeeding. */
+    readonly retryable: boolean;
+    readonly message: string;
+}
+/**
+ * Classify any thrown value into a `ToolError`. Check order is deliberate:
+ * timeout first (an abort can carry any message), then rate limit, then
+ * argument/validation problems, then denials; anything else is FAILED.
+ */
+export declare function toToolError(err: unknown): ToolError;
+export interface ToolRetryOptions {
+    /** Max retries AFTER the first attempt. Defaults to 1. */
+    readonly maxRetries?: number;
+    /** Base backoff; the n-th retry sleeps `backoffMs * n`. Defaults to 500. */
+    readonly backoffMs?: number;
+    /** Injected for tests; defaults to a real `setTimeout` sleep. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Wrap an executor with the standard retry policy: on throw, classify with
+ * `toToolError`; retry while the error is retryable and attempts remain;
+ * when retries are exhausted (or the error is not retryable), return a
+ * `ToolResult` with `error: true` and the classified `toolError` attached.
+ */
+export declare function withToolRetry(executor: ToolExecutor, opts?: ToolRetryOptions): ToolExecutor;

package/dist/node_modules/@boombot/core/agent-core/tool-errors.js

@@ -0,0 +1,60 @@
+/**
+ * Classify any thrown value into a `ToolError`. Check order is deliberate:
+ * timeout first (an abort can carry any message), then rate limit, then
+ * argument/validation problems, then denials; anything else is FAILED.
+ */
+export function toToolError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const name = err instanceof Error ? err.name : '';
+    if (name === 'AbortError' || /timed?\s*-?out/i.test(message)) {
+        return { code: 'TIMEOUT', retryable: true, message };
+    }
+    if (/rate.?limit|429/i.test(message)) {
+        return { code: 'RATE_LIMITED', retryable: true, message };
+    }
+    if (/invalid (args|arguments|parameters)|validation|schema/i.test(message)) {
+        return { code: 'INVALID_ARGS', retryable: false, message };
+    }
+    if (/denied|forbidden|not allowed|policy/i.test(message)) {
+        return { code: 'DENIED', retryable: false, message };
+    }
+    return { code: 'FAILED', retryable: true, message };
+}
+const defaultSleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * Wrap an executor with the standard retry policy: on throw, classify with
+ * `toToolError`; retry while the error is retryable and attempts remain;
+ * when retries are exhausted (or the error is not retryable), return a
+ * `ToolResult` with `error: true` and the classified `toolError` attached.
+ */
+export function withToolRetry(executor, opts = {}) {
+    const maxRetries = opts.maxRetries ?? 1;
+    const backoffMs = opts.backoffMs ?? 500;
+    const sleep = opts.sleep ?? defaultSleep;
+    return {
+        async execute(call, signal) {
+            let attempt = 0;
+            for (;;) {
+                try {
+                    return await executor.execute(call, signal);
+                }
+                catch (err) {
+                    const toolError = toToolError(err);
+                    if (!toolError.retryable || attempt >= maxRetries) {
+                        return {
+                            callId: call.id,
+                            name: call.name,
+                            output: `[${toolError.code}] ${toolError.message}`,
+                            error: true,
+                            toolError,
+                        };
+                    }
+                    attempt += 1;
+                    await sleep(backoffMs * attempt);
+                }
+            }
+        },
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { AgentRuntimeDeps } from './runtime-deps.js';
+import type { ChatMessage, EventHandler, TurnContext, TurnResult } from './types.js';
+export declare const DEFAULT_MAX_ROUNDS = 20;
+export declare const DEFAULT_MAX_TOOL_CALLS = 64;
+export declare const TOOL_ROUND_CONCURRENCY = 4;
+export declare const EMPTY_RESPONSE_NUDGE = "Your previous response was empty. Answer the user now, or call a tool only if it is necessary. Do not return an empty response.";
+export declare const CONTEXT_RETRY_TARGET_CHARS = 40000;
+export declare const CONTEXT_RETRY_SUMMARY_CHARS = 8000;
+export declare const CONTEXT_RETRY_MESSAGE_CHARS = 8000;
+export declare const CONTEXT_OMISSION_MARKER = "\n[message middle omitted during context recovery]\n";
+export declare class CancelledError extends Error {
+    readonly code: "CANCELLED";
+    constructor(message?: string);
+}
+export declare function isContextOverflow(error: unknown): boolean;
+export declare function shortenContent(content: string, limit: number): string;
+export declare function compactContextForRetry(messages: readonly ChatMessage[]): readonly ChatMessage[];
+/**
+ * Execute a complete cognitive turn natively in TypeScript.
+ */
+export declare function runTurn(deps: AgentRuntimeDeps, context: TurnContext, onEvent?: EventHandler, signal?: AbortSignal): Promise<TurnResult>;