whale-code 6.4.0

package/dist/shared/agent-core.js

@@ -0,0 +1,534 @@
+/**
+ * Shared Agent Core — single source of truth for CLI + server agent
+ *
+ * Pure TypeScript, no runtime-specific APIs (no Deno.env, no process.env, no fs).
+ * Both the CLI (Node.js) and server (Fly container) import from here.
+ */
+import { getProvider } from "./constants.js";
+/**
+ * Resolve the effective tool_choice for a given turn.
+ *
+ * Priority:
+ * 1. Explicit override from caller (toolChoice option)
+ * 2. Loop detection: if last 3 turns all used the same tool, force "none"
+ * 3. Keyword detection: if user message mentions a tool name, force that tool
+ * 4. Default: "auto"
+ */
+export function resolveToolChoice(opts) {
+    // 1. Explicit override always wins
+    if (opts.toolChoice !== undefined)
+        return opts.toolChoice;
+    // 2. Loop detection: if last 3+ turns all used the exact same tool, force text
+    if (opts.recentToolUses.length >= 3) {
+        const last3 = opts.recentToolUses.slice(-3);
+        if (last3[0] === last3[1] && last3[1] === last3[2]) {
+            return "none";
+        }
+    }
+    // 3. Keyword matching: check if the user message mentions a specific tool name
+    //    Only on the first turn (avoids false positives on multi-turn conversations)
+    if (opts.turnCount === 1 && opts.userMessage && opts.availableToolNames.length > 0) {
+        const msgLower = opts.userMessage.toLowerCase();
+        for (const toolName of opts.availableToolNames) {
+            // Match tool name as a whole word (e.g. "blender_do" not "do")
+            // Only consider tool names >= 4 chars to avoid false positives
+            if (toolName.length >= 4 && msgLower.includes(toolName.toLowerCase())) {
+                return { type: "tool", name: toolName };
+            }
+        }
+    }
+    // 4. Default
+    return "auto";
+}
+// ============================================================================
+// MODEL-AWARE CONTEXT MANAGEMENT
+// ============================================================================
+/** Compaction trigger threshold — shared so agent loops can track budget */
+export const COMPACTION_TRIGGER_TOKENS = 120_000;
+/** Max cumulative tokens before forcing wrap-up (prevents runaway compaction cost) */
+export const COMPACTION_TOTAL_BUDGET = 2_000_000;
+/** Default session cost budget in USD — Infinity = no limit (budget enforcement disabled by default) */
+export const DEFAULT_SESSION_COST_BUDGET_USD = Infinity;
+export function getCompactionConfig(model) {
+    const provider = getProvider(model);
+    switch (provider) {
+        case "gemini":
+            return { triggerTokens: 700_000, totalBudget: 4_000_000, isNative: false };
+        case "openai":
+            return { triggerTokens: 120_000, totalBudget: 2_000_000, isNative: false };
+        case "bedrock":
+        case "anthropic":
+        default:
+            return { triggerTokens: COMPACTION_TRIGGER_TOKENS, totalBudget: COMPACTION_TOTAL_BUDGET, isNative: true };
+    }
+}
+/**
+ * Returns Anthropic beta flags and context_management config for the given model.
+ * - Opus 4.6 / Sonnet 4.6: compact at 120K (pause after) + clear thinking + clear tools at 80K/keep 3
+ * - All other Claude models: clear thinking + clear tools at 80K/keep 3
+ * - Non-Anthropic models (Gemini, OpenAI): no betas, no context management
+ */
+export function getContextManagement(model) {
+    // Non-Anthropic models don't use Anthropic betas or context management
+    const provider = getProvider(model);
+    if (provider === "gemini" || provider === "openai") {
+        return { betas: [], config: { edits: [] } };
+    }
+    const edits = [];
+    const betas = ["context-management-2025-06-27"];
+    // Thinking block clearing — must come FIRST in edits array (API requirement).
+    // Keeps last 2 turns of thinking to maintain reasoning continuity while
+    // preventing unbounded growth from extended thinking.
+    edits.push({
+        type: "clear_thinking_20251015",
+        keep: { type: "thinking_turns", value: 2 },
+    });
+    // Server-side compaction for models that support compact_20260112.
+    // pause_after_compaction: true enables the loop to preserve recent messages
+    // and track compaction count for budget enforcement.
+    const supportsCompaction = model.includes("opus-4-6") || model.includes("sonnet-4-6");
+    if (supportsCompaction) {
+        edits.push({
+            type: "compact_20260112",
+            trigger: { type: "input_tokens", value: COMPACTION_TRIGGER_TOKENS },
+            pause_after_compaction: true,
+            instructions: "Summarize the conversation preserving: (1) task goals and constraints, (2) files created/modified with paths, (3) decisions made and rationale, (4) errors encountered and resolutions, (5) exact next steps. Be concise but preserve all state needed to continue work without repeating mistakes.",
+        });
+        betas.push("compact-2026-01-12");
+    }
+    edits.push({
+        type: "clear_tool_uses_20250919",
+        trigger: { type: "input_tokens", value: 80_000 },
+        keep: { type: "tool_uses", value: 3 },
+    });
+    return { betas, config: { edits } };
+}
+/**
+ * Model-aware max output tokens.
+ * Agent config max_tokens takes priority but is capped at model maximum.
+ *
+ * DEFAULT_OUTPUT_TOKENS is the sensible per-response cap (like Claude Code's ~16K).
+ * The full MODEL_MAX is only used when explicitly requested via agentMax.
+ */
+const DEFAULT_OUTPUT_TOKENS = 16384; // 16K — sane default, prevents single-response burns
+const MODEL_MAX_OUTPUT_TOKENS = {
+    // Anthropic — current models (actual API-enforced limits)
+    "claude-opus-4-6": 128000, // 128K
+    "claude-sonnet-4-6": 64000, // 64K (API enforces 64000, not 65536)
+    "claude-haiku-4-5-20251001": 64000, // 64K
+    // Anthropic — legacy models
+    "claude-sonnet-4-5-20250929": 64000, // 64K (API enforces 64000)
+    "claude-opus-4-5-20251101": 64000, // 64K
+    "claude-opus-4-1-20250805": 32768, // 32K
+    "claude-sonnet-4-20250514": 64000, // 64K
+    "claude-opus-4-20250514": 32768, // 32K
+    "claude-3-7-sonnet-20250219": 64000, // 64K
+    "claude-3-haiku-20240307": 4096, // 4K
+    // Bedrock — same limits as direct API
+    "anthropic.claude-sonnet-4-6": 64000,
+    "us.anthropic.claude-sonnet-4-20250514-v1:0": 64000,
+    "us.anthropic.claude-sonnet-4-5-20250929-v1:0": 64000,
+    "us.anthropic.claude-haiku-4-5-20251001-v1:0": 64000,
+    // Google Gemini
+    "gemini-3-pro-preview": 65536,
+    "gemini-3-flash-preview": 65536,
+    "gemini-2.5-pro": 65536,
+    "gemini-2.5-flash": 65536,
+    "gemini-2.5-flash-lite": 65536,
+    // OpenAI — GPT-5 family: 128K max output, o-series: 100K
+    "gpt-5": 128000,
+    "gpt-5-mini": 128000,
+    "gpt-5-nano": 128000,
+    "o3": 100000,
+    "o4-mini": 100000,
+    "gpt-4o": 16384,
+};
+export function getMaxOutputTokens(model, agentMax) {
+    const modelMax = MODEL_MAX_OUTPUT_TOKENS[model] ?? DEFAULT_OUTPUT_TOKENS;
+    // If caller explicitly sets agentMax, respect it (capped at model max).
+    // Otherwise use sane default — never auto-request 128K output.
+    if (agentMax)
+        return Math.min(agentMax, modelMax);
+    return Math.min(DEFAULT_OUTPUT_TOKENS, modelMax);
+}
+// ============================================================================
+// MULTI-BREAKPOINT PROMPT CACHING
+// ============================================================================
+/**
+ * Add prompt cache breakpoints to tools and messages.
+ * Uses 2 of 4 allowed breakpoints:
+ * - Last tool definition
+ * - Turn boundary (second-to-last message)
+ * System prompt caching is handled by the caller.
+ */
+export function addPromptCaching(tools, messages) {
+    const cachedTools = tools.length > 0
+        ? [...tools.slice(0, -1), { ...tools[tools.length - 1], cache_control: { type: "ephemeral" } }]
+        : [...tools];
+    const cachedMessages = [...messages];
+    if (cachedMessages.length >= 2) {
+        const idx = cachedMessages.length - 2;
+        const msg = cachedMessages[idx];
+        if (typeof msg.content === "string") {
+            cachedMessages[idx] = {
+                ...msg,
+                content: [{ type: "text", text: msg.content, cache_control: { type: "ephemeral" } }],
+            };
+        }
+        else if (Array.isArray(msg.content)) {
+            const blocks = [...msg.content];
+            blocks[blocks.length - 1] = { ...blocks[blocks.length - 1], cache_control: { type: "ephemeral" } };
+            cachedMessages[idx] = { ...msg, content: blocks };
+        }
+    }
+    return { tools: cachedTools, messages: cachedMessages };
+}
+// ============================================================================
+// LOOP DETECTION
+// ============================================================================
+/** djb2 string hash — fast, deterministic, no dependencies */
+function djb2Hash(str) {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) + hash + str.charCodeAt(i)) & 0xffffffff;
+    }
+    return hash.toString(36);
+}
+export class LoopDetector {
+    history = [];
+    consecutiveErrors = new Map();
+    turnErrors = 0;
+    turnHadErrors = false;
+    sessionErrors = new Map();
+    failedStrategies = new Set();
+    consecutiveFailedTurns = 0;
+    totalSessionErrors = 0;
+    static IDENTICAL_CALL_LIMIT = 4;
+    static CONSECUTIVE_ERROR_LIMIT = 3;
+    static TURN_ERROR_LIMIT = 5;
+    static WINDOW = 20;
+    static SESSION_TOOL_ERROR_LIMIT = 10;
+    static CONSECUTIVE_FAILED_TURN_LIMIT = 3;
+    /** Get the error-tracking key for a tool call. Tools with an `action` param
+     *  are tracked per-action so e.g. voice/speak failing won't block voice/music_compose. */
+    errorKey(name, input) {
+        if (input && typeof input.action === "string")
+            return `${name}:${input.action}`;
+        return name;
+    }
+    recordCall(name, input) {
+        const inputHash = djb2Hash(JSON.stringify({ name, ...input }));
+        const eKey = this.errorKey(name, input);
+        if (this.failedStrategies.has(inputHash)) {
+            return {
+                blocked: true,
+                reason: `Blocked: this exact "${name}" call failed in a previous turn. Try a fundamentally different approach.`,
+            };
+        }
+        const sessionErrorCount = this.sessionErrors.get(eKey) || 0;
+        if (sessionErrorCount >= LoopDetector.SESSION_TOOL_ERROR_LIMIT) {
+            return {
+                blocked: true,
+                reason: `Tool "${name}" (action: ${input.action || "default"}) has failed ${sessionErrorCount} times this session. Stop using this tool and try a different approach.`,
+            };
+        }
+        if (this.turnErrors >= LoopDetector.TURN_ERROR_LIMIT) {
+            return {
+                blocked: true,
+                reason: `${this.turnErrors} errors this turn. Stop and re-assess your approach.`,
+            };
+        }
+        const errorCount = this.consecutiveErrors.get(eKey) || 0;
+        if (errorCount >= LoopDetector.CONSECUTIVE_ERROR_LIMIT) {
+            return {
+                blocked: true,
+                reason: `Tool "${name}" (action: ${input.action || "default"}) blocked: failed ${errorCount} times consecutively. Try a different approach or action.`,
+            };
+        }
+        const windowSlice = this.history.slice(-LoopDetector.WINDOW);
+        const identicalCount = windowSlice.filter((h) => h.inputHash === inputHash).length;
+        if (identicalCount >= LoopDetector.IDENTICAL_CALL_LIMIT) {
+            return {
+                blocked: true,
+                reason: `Tool "${name}" blocked: identical call made ${identicalCount} times. Try different parameters.`,
+            };
+        }
+        this.history.push({ name, inputHash });
+        if (this.history.length > LoopDetector.WINDOW * 2) {
+            this.history = this.history.slice(-LoopDetector.WINDOW);
+        }
+        return { blocked: false };
+    }
+    recordResult(name, success, input) {
+        const eKey = this.errorKey(name, input);
+        if (success) {
+            this.consecutiveErrors.delete(eKey);
+        }
+        else {
+            const current = this.consecutiveErrors.get(eKey) || 0;
+            this.consecutiveErrors.set(eKey, current + 1);
+            this.turnErrors++;
+            this.turnHadErrors = true;
+            const sessionCount = this.sessionErrors.get(eKey) || 0;
+            this.sessionErrors.set(eKey, sessionCount + 1);
+            this.totalSessionErrors++;
+            if (input) {
+                const inputHash = djb2Hash(JSON.stringify({ name, ...input }));
+                this.failedStrategies.add(inputHash);
+                if (this.failedStrategies.size > 200) {
+                    const arr = Array.from(this.failedStrategies);
+                    this.failedStrategies = new Set(arr.slice(-100));
+                }
+            }
+        }
+    }
+    endTurn() {
+        if (this.turnHadErrors) {
+            this.consecutiveFailedTurns++;
+        }
+        else {
+            this.consecutiveFailedTurns = 0;
+            // A clean turn means the agent has recovered — unblock previously failed strategies
+            // so it can retry calls that failed due to bad params (e.g., wrong UUID format)
+            this.failedStrategies.clear();
+            // Decay session error counts on clean turns so tools aren't permanently blocked.
+            // Each clean turn halves all session error counts, allowing recovery from
+            // transient issues while still blocking persistently broken tools.
+            if (this.sessionErrors.size > 0) {
+                for (const [key, count] of this.sessionErrors) {
+                    const decayed = Math.floor(count / 2);
+                    if (decayed <= 0) {
+                        this.sessionErrors.delete(key);
+                    }
+                    else {
+                        this.sessionErrors.set(key, decayed);
+                    }
+                }
+            }
+        }
+        // Reset turn-level counters so the NEXT dispatch batch starts fresh.
+        // Session-level counters (sessionErrors, consecutiveFailedTurns) persist.
+        this.turnErrors = 0;
+        this.turnHadErrors = false;
+        if (this.consecutiveFailedTurns >= LoopDetector.CONSECUTIVE_FAILED_TURN_LIMIT) {
+            return {
+                shouldBail: true,
+                message: `You have had errors in ${this.consecutiveFailedTurns} consecutive turns (${this.totalSessionErrors} total errors). Your approach is not working. STOP and explain to the user what's failing.`,
+            };
+        }
+        return { shouldBail: false };
+    }
+    resetTurn() {
+        this.history = [];
+        this.consecutiveErrors.clear();
+        this.turnErrors = 0;
+        this.turnHadErrors = false;
+    }
+    reset() {
+        this.resetTurn();
+        this.sessionErrors.clear();
+        this.failedStrategies.clear();
+        this.consecutiveFailedTurns = 0;
+        this.totalSessionErrors = 0;
+    }
+    getSessionStats() {
+        return {
+            totalErrors: this.totalSessionErrors,
+            failedStrategies: this.failedStrategies.size,
+            consecutiveFailedTurns: this.consecutiveFailedTurns,
+        };
+    }
+}
+/**
+ * Returns the thinking configuration and required beta string for the given model.
+ * - Opus 4.6: adaptive thinking (no budget needed)
+ * - Sonnet/Haiku: enabled with 10000 token budget
+ * - budget_tokens must be strictly < max_tokens
+ */
+export function getThinkingConfig(model, enabled) {
+    if (!enabled) {
+        return { thinking: { type: "disabled" }, beta: "" };
+    }
+    const provider = getProvider(model);
+    // Gemini models: thinking is always-on for 2.5+/3.x — signal pass-through
+    if (provider === "gemini") {
+        return { thinking: { type: "enabled" }, beta: "" };
+    }
+    // OpenAI models: reasoning models (o-series) have built-in reasoning, GPT models don't support thinking
+    if (provider === "openai") {
+        const isReasoning = /^o\d/.test(model);
+        return { thinking: { type: isReasoning ? "enabled" : "disabled" }, beta: "" };
+    }
+    if (model.includes("opus-4-6") || model.includes("sonnet-4-6")) {
+        return {
+            thinking: { type: "adaptive" },
+            beta: "adaptive-thinking-2026-01-28",
+        };
+    }
+    // Sonnet 4.5/4.0 / Haiku: fixed budget
+    return {
+        thinking: { type: "enabled", budget_tokens: 10_000 },
+        beta: "interleaved-thinking-2025-05-14",
+    };
+}
+// ============================================================================
+// COST TRACKING
+// ============================================================================
+export const MODEL_PRICING = {
+    // Anthropic direct — Claude 4.x
+    "claude-sonnet-4-6": { inputPer1M: 3.0, outputPer1M: 15.0, thinkingPer1M: 15.0 },
+    "claude-sonnet-4-20250514": { inputPer1M: 3.0, outputPer1M: 15.0, thinkingPer1M: 15.0 },
+    "claude-sonnet-4-5-20250929": { inputPer1M: 3.0, outputPer1M: 15.0, thinkingPer1M: 15.0 },
+    "claude-opus-4-6": { inputPer1M: 5.0, outputPer1M: 25.0, thinkingPer1M: 25.0 },
+    "claude-opus-4-20250514": { inputPer1M: 5.0, outputPer1M: 25.0, thinkingPer1M: 25.0 },
+    "claude-opus-4-5-20251101": { inputPer1M: 5.0, outputPer1M: 25.0, thinkingPer1M: 25.0 },
+    "claude-haiku-4-20250514": { inputPer1M: 1.0, outputPer1M: 5.0, thinkingPer1M: 5.0 },
+    "claude-haiku-4-5-20251001": { inputPer1M: 1.0, outputPer1M: 5.0, thinkingPer1M: 5.0 },
+    // Anthropic direct — Claude 3.5
+    "claude-3-5-sonnet-20241022": { inputPer1M: 3.0, outputPer1M: 15.0 },
+    "claude-3-5-haiku-20241022": { inputPer1M: 0.80, outputPer1M: 4.0 },
+    // Bedrock — Claude 4.x
+    "anthropic.claude-sonnet-4-6": { inputPer1M: 3.0, outputPer1M: 15.0, thinkingPer1M: 15.0 },
+    "us.anthropic.claude-sonnet-4-20250514-v1:0": { inputPer1M: 3.0, outputPer1M: 15.0, thinkingPer1M: 15.0 },
+    "us.anthropic.claude-sonnet-4-5-20250929-v1:0": { inputPer1M: 3.0, outputPer1M: 15.0, thinkingPer1M: 15.0 },
+    "us.anthropic.claude-haiku-4-5-20251001-v1:0": { inputPer1M: 1.0, outputPer1M: 5.0, thinkingPer1M: 5.0 },
+    // Bedrock — Claude 3.5
+    "us.anthropic.claude-3-5-haiku-20241022-v1:0": { inputPer1M: 0.80, outputPer1M: 4.0 },
+    // Bedrock — Llama & Nova
+    "us.meta.llama3-1-70b-instruct-v1:0": { inputPer1M: 0.72, outputPer1M: 0.72 },
+    "us.amazon.nova-pro-v1:0": { inputPer1M: 0.80, outputPer1M: 3.20 },
+    // Gemini (thinking tokens are cheaper than output)
+    "gemini-3-pro-preview": { inputPer1M: 1.25, outputPer1M: 10.0, thinkingPer1M: 2.50 },
+    "gemini-3-flash-preview": { inputPer1M: 0.15, outputPer1M: 0.60, thinkingPer1M: 0.15 },
+    "gemini-2.5-pro": { inputPer1M: 1.25, outputPer1M: 10.0, thinkingPer1M: 2.50 },
+    "gemini-2.5-flash": { inputPer1M: 0.15, outputPer1M: 0.60, thinkingPer1M: 0.15 },
+    "gemini-2.5-flash-lite": { inputPer1M: 0.075, outputPer1M: 0.30, thinkingPer1M: 0.075 },
+    "gemini-2.0-flash": { inputPer1M: 0.10, outputPer1M: 0.40 },
+    "gemini-2.0-flash-lite": { inputPer1M: 0.075, outputPer1M: 0.30 },
+    // OpenAI — GPT
+    "gpt-5": { inputPer1M: 1.25, outputPer1M: 10.0 },
+    "gpt-5-mini": { inputPer1M: 0.25, outputPer1M: 2.0 },
+    "gpt-5-nano": { inputPer1M: 0.05, outputPer1M: 0.40 },
+    "gpt-4o": { inputPer1M: 2.50, outputPer1M: 10.0 },
+    "gpt-4o-mini": { inputPer1M: 0.15, outputPer1M: 0.60 },
+    "gpt-4-turbo": { inputPer1M: 10.0, outputPer1M: 30.0 },
+    // OpenAI — reasoning models
+    "o1": { inputPer1M: 15.0, outputPer1M: 60.0, thinkingPer1M: 60.0 },
+    "o1-mini": { inputPer1M: 3.0, outputPer1M: 12.0, thinkingPer1M: 12.0 },
+    "o3": { inputPer1M: 2.0, outputPer1M: 8.0, thinkingPer1M: 8.0 },
+    "o3-mini": { inputPer1M: 1.10, outputPer1M: 4.40, thinkingPer1M: 4.40 },
+    "o4-mini": { inputPer1M: 1.10, outputPer1M: 4.40, thinkingPer1M: 4.40 },
+};
+export function estimateCostUsd(inputTokens, outputTokens, model, thinkingTokens = 0, cacheReadTokens = 0, cacheCreationTokens = 0) {
+    // Exact match first, then find a pricing key that is a prefix of the model ID
+    const pricing = MODEL_PRICING[model]
+        || MODEL_PRICING[Object.keys(MODEL_PRICING).find((k) => model.startsWith(k)) ?? ""]
+        || MODEL_PRICING["claude-sonnet-4-6"];
+    const thinkingRate = pricing.thinkingPer1M || pricing.outputPer1M;
+    const inputRate = pricing.inputPer1M;
+    // Base cost
+    let cost = (inputTokens / 1_000_000) * inputRate
+        + (outputTokens / 1_000_000) * pricing.outputPer1M
+        + (thinkingTokens / 1_000_000) * thinkingRate;
+    // Cache pricing — subtract savings for cached tokens
+    // Anthropic/Bedrock: cache reads 90% cheaper, cache creation 25% surcharge
+    // OpenAI: cache reads 50% cheaper, no creation surcharge
+    // Gemini: cache reads 75% cheaper
+    if (cacheReadTokens > 0 || cacheCreationTokens > 0) {
+        const provider = getProvider(model);
+        if (provider === "anthropic" || provider === "bedrock") {
+            cost -= (cacheReadTokens / 1_000_000) * inputRate * 0.9;
+            cost += (cacheCreationTokens / 1_000_000) * inputRate * 0.25;
+        }
+        else if (provider === "openai") {
+            cost -= (cacheReadTokens / 1_000_000) * inputRate * 0.5;
+        }
+        else if (provider === "gemini") {
+            cost -= (cacheReadTokens / 1_000_000) * inputRate * 0.75;
+        }
+    }
+    return cost;
+}
+// ============================================================================
+// MODEL ROUTING BY TASK COMPLEXITY
+// ============================================================================
+/**
+ * Route to cheaper model when the task is simple enough.
+ * Returns the model to actually use.
+ */
+export function routeModel(message, requestedModel, forceModel) {
+    // If user explicitly picked a model, respect it
+    if (forceModel)
+        return requestedModel;
+    // Estimate token count (rough: 1 token ~= 4 chars)
+    const estimatedTokens = Math.ceil(message.length / 4);
+    // Simple queries → Haiku (30x cheaper than Opus)
+    const simplePatterns = /^(what|who|when|where|show|list|get|find|look ?up|check)\b/i;
+    const complexPatterns = /\b(analyze|implement|refactor|design|architect|debug|explain why|compare|evaluate|write|create|build|fix)\b/i;
+    if (estimatedTokens < 50 && simplePatterns.test(message) && !complexPatterns.test(message)) {
+        return "claude-haiku-4-5-20251001";
+    }
+    // Medium queries → Sonnet
+    if (estimatedTokens < 200 && !complexPatterns.test(message)) {
+        return "claude-sonnet-4-5-20250929";
+    }
+    // Complex → honor requested model
+    return requestedModel;
+}
+export function categorizeError(err) {
+    const e = err;
+    const status = e?.status || e?.statusCode;
+    const msg = String(e?.message || "").toLowerCase();
+    if (status === 429 || msg.includes("rate limit")) {
+        return { category: "RATE_LIMIT", retryable: true };
+    }
+    if (status === 401 || status === 403 || msg.includes("unauthorized") || msg.includes("forbidden") || msg.includes("invalid api key")) {
+        return { category: "AUTH", retryable: false };
+    }
+    if (status === 400 || msg.includes("malformed") || msg.includes("invalid") || msg.includes("validation")) {
+        return { category: "MALFORMED", retryable: false };
+    }
+    if (status === 500 || status === 502 || status === 503 || status === 529 || msg.includes("overloaded") || msg.includes("internal server error")) {
+        return { category: "PROVIDER_DOWN", retryable: true };
+    }
+    if (msg.includes("timeout") || msg.includes("timed out") || msg.includes("deadline") || msg.includes("econnreset")) {
+        return { category: "TIMEOUT", retryable: true };
+    }
+    if (msg.includes("econnrefused") || msg.includes("enetunreach") || msg.includes("enotfound") || msg.includes("fetch failed") || msg.includes("network")) {
+        return { category: "NETWORK", retryable: true };
+    }
+    return { category: "UNKNOWN", retryable: false };
+}
+// ============================================================================
+// RETRY LOGIC
+// ============================================================================
+export function isRetryableError(err) {
+    return categorizeError(err).retryable;
+}
+// ============================================================================
+// TOOL RESULT TRUNCATION (deprecated — Anthropic context_management handles limits)
+// ============================================================================
+/** @deprecated — Anthropic context_management handles limits. Use SAFETY_MAX_CHARS in tool-dispatch instead. */
+export function truncateToolResult(content, maxChars) {
+    if (content.length <= maxChars)
+        return content;
+    return content.slice(0, maxChars) + `\n\n... (truncated — ${content.length.toLocaleString()} chars total)`;
+}
+/** @deprecated — Anthropic context_management handles limits. */
+export function getMaxToolResultChars(contextConfig) {
+    return contextConfig?.max_tool_result_chars || 80_000;
+}
+// ============================================================================
+// UTILITY — sanitize errors (strip API keys, passwords)
+// ============================================================================
+export function sanitizeError(err) {
+    const msg = String(err);
+    return msg
+        .replace(/sk-[a-zA-Z0-9_-]+/g, "sk-***")
+        .replace(/AIzaSy[a-zA-Z0-9_-]+/g, "AIzaSy***")
+        .replace(/AKIA[A-Z0-9]{16}/g, "AKIA***")
+        .replace(/key[=:]\s*["']?[a-zA-Z0-9_-]{20,}["']?/gi, "key=***")
+        .replace(/password[=:]\s*["']?[^\s"']+["']?/gi, "password=***")
+        .replace(/\n\s+at\s+.*/g, "")
+        .substring(0, 500);
+}

package/dist/shared/anthropic-types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Typed Anthropic SSE Events — replaces `as any` casts in stream processing.
+ *
+ * Based on Anthropic API streaming specification.
+ * Pure TypeScript, no runtime dependencies.
+ */
+export interface TextContentBlock {
+    type: "text";
+    text: string;
+}
+export interface ToolUseContentBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+}
+export interface ThinkingContentBlock {
+    type: "thinking";
+}
+export interface CompactionContentBlock {
+    type: "compaction";
+}
+export interface CiteContentBlock {
+    type: "cite";
+    cited_text: string;
+    document_index: number;
+    document_title?: string;
+    start_char_index: number;
+    end_char_index: number;
+}
+export type ContentBlock = TextContentBlock | ToolUseContentBlock | ThinkingContentBlock | CompactionContentBlock | CiteContentBlock;
+export interface TextDelta {
+    type: "text_delta";
+    text: string;
+}
+export interface InputJsonDelta {
+    type: "input_json_delta";
+    partial_json: string;
+}
+export interface ThinkingDelta {
+    type: "thinking_delta";
+    thinking: string;
+}
+export interface SignatureDelta {
+    type: "signature_delta";
+    signature: string;
+}
+export interface CompactionDelta {
+    type: "compaction_delta";
+    content: string;
+}
+export interface CiteDelta {
+    type: "cite_delta";
+    cited_text?: string;
+    document_index?: number;
+    document_title?: string;
+    start_char_index?: number;
+    end_char_index?: number;
+}
+export type ContentBlockDelta = TextDelta | InputJsonDelta | ThinkingDelta | SignatureDelta | CompactionDelta | CiteDelta;
+export interface BetaUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+export interface MessageStartEvent {
+    type: "message_start";
+    message: {
+        usage: BetaUsage;
+    };
+}
+export interface ContentBlockStartEvent {
+    type: "content_block_start";
+    index: number;
+    content_block: ContentBlock;
+}
+export interface ContentBlockDeltaEvent {
+    type: "content_block_delta";
+    index: number;
+    delta: ContentBlockDelta;
+}
+export interface ContentBlockStopEvent {
+    type: "content_block_stop";
+    index: number;
+}
+export interface MessageDeltaEvent {
+    type: "message_delta";
+    delta: {
+        stop_reason?: string;
+        context_management?: {
+            applied_edits?: Array<Record<string, unknown>>;
+        };
+    };
+    usage: {
+        output_tokens: number;
+        input_tokens?: number;
+        cache_read_input_tokens?: number;
+        thinking_tokens?: number;
+    };
+}
+export interface StreamErrorEvent {
+    type: "error";
+    error: string | Record<string, unknown>;
+}
+export type BetaStreamEvent = MessageStartEvent | ContentBlockStartEvent | ContentBlockDeltaEvent | ContentBlockStopEvent | MessageDeltaEvent | StreamErrorEvent;

package/dist/shared/anthropic-types.js

@@ -0,0 +1,7 @@
+/**
+ * Typed Anthropic SSE Events — replaces `as any` casts in stream processing.
+ *
+ * Based on Anthropic API streaming specification.
+ * Pure TypeScript, no runtime dependencies.
+ */
+export {};