whale-code 6.4.0

package/dist/server/tool-router.js

@@ -0,0 +1,803 @@
+/**
+ * Tool Router — unified tool registry, dispatch, and execution.
+ *
+ * SINGLE SOURCE OF TRUTH for all AI systems (MCP server, HTTP agent, workflows, CLI).
+ *
+ * Architecture:
+ * - ai_tool_registry (DB):   tool definitions (name, description, schema) — queried by ALL clients
+ * - TOOL_HANDLERS (code):    name → handler function mapping — the only place handler routing lives
+ * - user_tools (DB):         per-store custom tools — additive, never filtered from built-ins
+ * - getToolsForAgent():      consistent tool set — all registry tools always available
+ * - executeTool():           unified dispatch — handler lookup + timeout + audit logging
+ *
+ * To add a new tool:
+ *   1. Add handler in src/server/handlers/
+ *   2. Import and register in TOOL_HANDLERS below
+ *   3. Add row to ai_tool_registry table (defines schema for all clients)
+ *   That's it — MCP, WhaleChat, workflows, CLI all pick it up automatically.
+ */
+import { sanitizeError } from "../shared/agent-core.js";
+import { validateToolArgs } from "./validation.js";
+import { sanitizeToolDescription } from "./lib/prompt-sanitizer.js";
+import { validateUrl } from "./lib/ssrf-guard.js";
+import { handleInventory, handleInventoryQuery, handleInventoryAudit } from "./handlers/inventory.js";
+import { handlePurchaseOrders, handleTransfers } from "./handlers/supply-chain.js";
+import { handleProducts, handleCollections } from "./handlers/catalog.js";
+import { handleCustomers, handleOrders } from "./handlers/crm.js";
+import { handleAnalytics } from "./handlers/analytics.js";
+import { handleLocations, handleSuppliers, handleAlerts, handleAuditTrail, handleStore } from "./handlers/operations.js";
+import { handleEmail, handleDocuments } from "./handlers/comms.js";
+import { handleWebSearch, handleTelemetry } from "./handlers/platform.js";
+import { handleBrowser } from "./handlers/browser.js";
+import { handleDiscovery } from "./handlers/discovery.js";
+import { handleVoice } from "./handlers/voice.js";
+import { handleWorkflows } from "./handlers/workflows.js";
+import { handleEmbeddings } from "./handlers/embeddings.js";
+import { handleLLM } from "./handlers/llm-providers.js";
+import { handleImageGen } from "./handlers/image-gen.js";
+import { handleVideoGen } from "./handlers/video-gen.js";
+import { handleAPIKeys } from "./handlers/api-keys.js";
+import { handleCreations } from "./handlers/creations.js";
+import { handleMetaAds } from "./handlers/meta-ads.js";
+import { handleKali } from "./handlers/kali.js";
+import { handleLocalAgent } from "./handlers/local-agent.js";
+import { handleEnrichment } from "./handlers/enrichment.js";
+import { summarizeResult, withTimeout } from "./lib/utils.js";
+// ============================================================================
+// AUDIT LOG BATCHING — buffer inserts and flush periodically
+// ============================================================================
+const auditLogBuffer = [];
+const AUDIT_FLUSH_INTERVAL = 500; // ms
+const AUDIT_FLUSH_MAX = 100; // max records before force flush
+let auditFlushTimer = null;
+export async function flushAuditLogs(supabase) {
+    if (auditLogBuffer.length === 0)
+        return;
+    const batch = auditLogBuffer.splice(0, auditLogBuffer.length);
+    try {
+        const { error } = await supabase.from("audit_logs").insert(batch);
+        if (error)
+            console.error("[audit-batch] flush error:", error.message, "lost", batch.length, "records");
+    }
+    catch (err) {
+        console.error("[audit-batch] flush exception:", err.message, "lost", batch.length, "records");
+    }
+}
+function queueAuditLog(supabase, row) {
+    auditLogBuffer.push(row);
+    if (auditLogBuffer.length >= AUDIT_FLUSH_MAX) {
+        flushAuditLogs(supabase);
+    }
+    else if (!auditFlushTimer) {
+        auditFlushTimer = setTimeout(() => {
+            auditFlushTimer = null;
+            flushAuditLogs(supabase);
+        }, AUDIT_FLUSH_INTERVAL);
+    }
+}
+// ============================================================================
+// IN-MEMORY EXECUTION METRICS
+// ============================================================================
+const toolMetrics = new Map();
+export function getToolMetrics() {
+    const result = {};
+    for (const [name, m] of toolMetrics) {
+        result[name] = { invocations: m.invocations, errors: m.errors, avgMs: m.invocations > 0 ? Math.round(m.totalMs / m.invocations) : 0, lastMs: m.lastMs };
+    }
+    return result;
+}
+function recordToolMetric(toolName, durationMs, success) {
+    let m = toolMetrics.get(toolName);
+    if (!m) {
+        m = { invocations: 0, errors: 0, totalMs: 0, lastMs: 0 };
+        toolMetrics.set(toolName, m);
+    }
+    m.invocations++;
+    m.totalMs += durationMs;
+    m.lastMs = durationMs;
+    if (!success)
+        m.errors++;
+}
+let cachedResult = null;
+let cacheTime = 0;
+/** Pre-computed API-ready tool defs (name + truncated description + input_schema).
+ *  Computed once at load time, reused every turn without re-serialization. */
+let cachedApiToolDefs = null;
+/** Truncate a description to maxLen characters, ending at a word boundary with ellipsis. */
+function truncateDescription(desc, maxLen = 150) {
+    if (desc.length <= maxLen)
+        return desc;
+    const cut = desc.lastIndexOf(" ", maxLen - 3);
+    return desc.substring(0, cut > 0 ? cut : maxLen - 3) + "...";
+}
+/**
+ * Load tools from ai_tool_registry, split into core (auto_load=true) and extended.
+ * The `discover_tools` meta-tool is always injected into core.
+ * Descriptions are truncated to 150 chars at load time.
+ */
+export async function loadTools(supabase, forceRefresh = false) {
+    if (!forceRefresh && cachedResult && Date.now() - cacheTime < 60_000)
+        return cachedResult;
+    const { data, error } = await supabase
+        .from("ai_tool_registry")
+        .select("name, description, definition, auto_load")
+        .eq("is_active", true)
+        .neq("tool_mode", "code");
+    if (error || !data) {
+        return cachedResult || { core: [], extended: [], all: [] };
+    }
+    const allTools = data.map((t) => ({
+        name: t.name,
+        description: sanitizeToolDescription(truncateDescription(t.description || t.definition?.description || t.name)),
+        input_schema: t.definition?.input_schema || { type: "object", properties: {} },
+    }));
+    const core = [];
+    const extended = [];
+    // Check if any row has auto_load set — if the column doesn't exist yet
+    // (migration not run), all values will be null/undefined. In that case,
+    // treat ALL tools as core to preserve pre-migration behavior.
+    const migrationApplied = data.some((t) => t.auto_load === true || t.auto_load === false);
+    if (!migrationApplied) {
+        // Pre-migration: all tools are core (original behavior)
+        core.push(...allTools);
+    }
+    else {
+        for (let i = 0; i < data.length; i++) {
+            if (data[i].auto_load) {
+                core.push(allTools[i]);
+            }
+            else {
+                extended.push(allTools[i]);
+            }
+        }
+    }
+    // Always inject discover_tools into core set
+    if (!core.some(t => t.name === "discover_tools")) {
+        core.push(DISCOVER_TOOLS_DEF);
+    }
+    // Pre-compute API-ready tool defs keyed by name — avoids per-turn .map()
+    cachedApiToolDefs = new Map();
+    for (const t of [...core, ...extended]) {
+        cachedApiToolDefs.set(t.name, {
+            name: t.name,
+            description: t.description,
+            input_schema: t.input_schema,
+        });
+    }
+    cachedResult = { core, extended, all: allTools };
+    cacheTime = Date.now();
+    return cachedResult;
+}
+/**
+ * Get pre-computed API-ready tool definitions. Returns frozen objects keyed by name
+ * so the agent loop can look up defs without re-mapping every turn.
+ * Falls back to building from a ToolDef[] if cache not yet populated.
+ */
+export function getCachedToolDefs(tools) {
+    if (cachedApiToolDefs) {
+        // Fast path: look up each active tool in the pre-computed map
+        const result = [];
+        for (const t of tools) {
+            const cached = cachedApiToolDefs.get(t.name);
+            if (cached) {
+                result.push(cached);
+            }
+            else {
+                // Dynamic tool (e.g. delegate_task, user tools, discovered tools) — build on the fly
+                result.push({
+                    name: t.name,
+                    description: truncateDescription(t.description),
+                    input_schema: t.input_schema,
+                });
+            }
+        }
+        return result;
+    }
+    // Fallback: cache not populated yet — build from scratch with truncation
+    return tools.map((t) => ({
+        name: t.name,
+        description: truncateDescription(t.description),
+        input_schema: t.input_schema,
+    }));
+}
+/** discover_tools meta-tool — lets the model load extended tool schemas on demand */
+const DISCOVER_TOOLS_DEF = {
+    name: "discover_tools",
+    description: "Load full schemas for extended tools not in your core set. Call this before using a tool that is listed under 'Extended Tools' in your system prompt. You can load tools by name or by category.",
+    input_schema: {
+        type: "object",
+        properties: {
+            names: {
+                type: "array",
+                items: { type: "string" },
+                description: "Specific tool names to load (e.g. ['kali', 'browser', 'voice'])",
+            },
+            category: {
+                type: "string",
+                description: "Load all tools in this category (e.g. 'security', 'media', 'operations')",
+            },
+            refresh: {
+                type: "boolean",
+                description: "Force reload tool definitions from DB (bust cache). Use when tools may have been updated mid-conversation.",
+            },
+        },
+    },
+};
+// ============================================================================
+// USER TOOLS (per-store custom tools from user_tools table)
+// ============================================================================
+const userToolCache = new Map();
+const USER_TOOL_CACHE_MAX = 100;
+function evictUserToolCache() {
+    if (userToolCache.size <= USER_TOOL_CACHE_MAX)
+        return;
+    const entries = [...userToolCache.entries()].sort((a, b) => a[1].lastAccessed - b[1].lastAccessed);
+    const excess = userToolCache.size - USER_TOOL_CACHE_MAX;
+    for (let i = 0; i < excess; i++) {
+        userToolCache.delete(entries[i][0]);
+    }
+}
+export async function loadUserTools(supabase, storeId) {
+    const cached = userToolCache.get(storeId);
+    if (cached && Date.now() - cached.time < 60_000) {
+        cached.lastAccessed = Date.now();
+        return { rows: cached.tools, defs: cached.defs };
+    }
+    const { data, error } = await supabase
+        .from("user_tools")
+        .select("id, name, display_name, description, input_schema, execution_type, is_read_only, requires_approval, http_config, rpc_function, sql_template, allowed_tables, max_execution_time_ms")
+        .eq("store_id", storeId)
+        .eq("is_active", true);
+    if (error || !data?.length)
+        return { rows: [], defs: [] };
+    const rows = data;
+    const defs = rows.map((t) => ({
+        name: `user_tool__${t.name}`,
+        description: sanitizeToolDescription(`[Custom Tool] ${t.display_name}: ${t.description}${t.requires_approval ? " (requires approval)" : ""}`),
+        input_schema: t.input_schema || { type: "object", properties: {} },
+    }));
+    userToolCache.set(storeId, { tools: rows, defs, time: Date.now(), lastAccessed: Date.now() });
+    evictUserToolCache();
+    return { rows, defs };
+}
+export function getUserToolByPrefixedName(rows, prefixedName) {
+    const toolName = prefixedName.replace(/^user_tool__/, "");
+    return rows.find((t) => t.name === toolName);
+}
+export function getToolsForAgent(agent, coreTools, userToolDefs = []) {
+    // Core registry tools are always available (matches MCP server behavior).
+    // enabled_tools only restricts custom user tools.
+    if (agent.enabled_tools?.length > 0) {
+        const filteredUserTools = userToolDefs.filter((t) => agent.enabled_tools.includes(t.name));
+        return [...coreTools, ...filteredUserTools];
+    }
+    return [...coreTools, ...userToolDefs];
+}
+const DEFAULT_TIMEOUT = 30_000;
+/**
+ * Every built-in tool MUST be registered here. This map is the single source
+ * of truth for handler routing, timeouts, and store requirements.
+ * Adding a tool to ai_tool_registry without an entry here → "Unknown tool" error.
+ */
+export const TOOL_HANDLERS = {
+    // --- Business Data ---
+    inventory: { handler: (sb, args, sid) => {
+            const a = args.action || "";
+            if (a.startsWith("audit_"))
+                return handleInventoryAudit(sb, { ...args, action: a.slice(6) }, sid);
+            if (["summary", "velocity", "by_location", "in_stock", "out_of_stock", "by_category"].includes(a))
+                return handleInventoryQuery(sb, args, sid);
+            return handleInventory(sb, args, sid);
+        }, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    purchase_orders: { handler: handlePurchaseOrders, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    transfers: { handler: handleTransfers, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    products: { handler: handleProducts, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    collections: { handler: handleCollections, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    customers: { handler: handleCustomers, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    orders: { handler: handleOrders, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    analytics: { handler: handleAnalytics, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    locations: { handler: handleLocations, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    suppliers: { handler: handleSuppliers, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    store: { handler: handleStore, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    // --- Communication ---
+    email: { handler: handleEmail, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    documents: { handler: handleDocuments, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    // --- Operations ---
+    alerts: { handler: handleAlerts, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    audit_trail: { handler: handleAuditTrail, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    workflows: { handler: handleWorkflows, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    // --- AI & Generation ---
+    voice: { handler: handleVoice, timeout: 120_000, requiresStore: true },
+    image_gen: { handler: handleImageGen, timeout: 60_000, requiresStore: true },
+    video_gen: { handler: handleVideoGen, timeout: 600_000, requiresStore: true },
+    llm: { handler: handleLLM, timeout: 120_000, requiresStore: true },
+    embeddings: { handler: handleEmbeddings, timeout: 60_000, requiresStore: true },
+    creations: { handler: handleCreations, timeout: 60_000, requiresStore: true },
+    // --- Platform & Infrastructure (no store required) ---
+    web_search: { handler: handleWebSearch, timeout: DEFAULT_TIMEOUT, requiresStore: false },
+    telemetry: { handler: handleTelemetry, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    browser: { handler: handleBrowser, timeout: 120_000, requiresStore: true },
+    discovery: { handler: handleDiscovery, timeout: DEFAULT_TIMEOUT, requiresStore: false },
+    api_keys: { handler: handleAPIKeys, timeout: DEFAULT_TIMEOUT, requiresStore: true },
+    // --- Advertising ---
+    meta_ads: { handler: handleMetaAds, timeout: 300_000, requiresStore: true },
+    // --- Security & Local ---
+    kali: { handler: handleKali, timeout: 600_000, requiresStore: true, supportsProgress: true },
+    local_agent: { handler: handleLocalAgent, timeout: 600_000, requiresStore: false },
+    // --- Customer Data Protection ---
+    enrichment: { handler: handleEnrichment, timeout: 60_000, requiresStore: true },
+    // --- Meta: Tool Discovery (lazy loading) ---
+    discover_tools: { handler: handleDiscoverTools, timeout: 5000, requiresStore: false },
+};
+Object.freeze(TOOL_HANDLERS);
+/** Get all registered built-in tool names */
+export function getRegisteredToolNames() {
+    return Object.keys(TOOL_HANDLERS);
+}
+// ============================================================================
+// DISCOVER_TOOLS HANDLER — returns full schemas for extended tools on demand
+// ============================================================================
+/** Full extended tool defs (with schemas) — used by handleDiscoverTools to return schemas on demand */
+let _extendedToolsCache = [];
+/** Lightweight extended tool index — name + first-sentence description only (for system prompt) */
+let _extendedToolsIndex = [];
+/** Called by index.ts after loadTools() to populate the discover_tools cache.
+ *  Stores full schemas for on-demand loading, plus a lightweight index for the system prompt. */
+export function setExtendedToolsCache(tools) {
+    _extendedToolsCache = tools;
+    // Pre-compute lightweight index: name + first sentence only (no schemas)
+    _extendedToolsIndex = tools.map(t => ({
+        name: t.name,
+        description: t.description.split(".")[0],
+    }));
+}
+/** Get full extended tools with schemas (for discover_tools handler) */
+export function getExtendedToolsCache() {
+    return _extendedToolsCache;
+}
+/** Get lightweight extended tools index — name + short description only (for system prompt).
+ *  Avoids serializing full schemas into the prompt. */
+export function getExtendedToolsIndex() {
+    return _extendedToolsIndex;
+}
+/**
+ * Get full tool schemas for specific tool names from the extended tools cache.
+ * Used by the agent loop to inject discovered tool schemas into the active tool set.
+ * Returns only tools that exist in the cache; unknown names are silently skipped.
+ */
+export function getFullToolSchemas(toolNames) {
+    if (!toolNames.length || !_extendedToolsCache.length)
+        return [];
+    const nameSet = new Set(toolNames);
+    return _extendedToolsCache.filter(t => nameSet.has(t.name));
+}
+// Tool category heuristics — maps tool names to categories for category-based discovery
+const TOOL_CATEGORIES = {
+    // Business Data
+    inventory: "business", purchase_orders: "business", transfers: "business",
+    products: "business", collections: "business", customers: "business",
+    orders: "business", analytics: "business", locations: "business",
+    suppliers: "business", store: "business",
+    // Communication
+    email: "communication", documents: "communication",
+    // Operations
+    alerts: "operations", audit_trail: "operations", workflows: "operations",
+    telemetry: "operations",
+    // Media & AI
+    voice: "media", image_gen: "media", video_gen: "media",
+    llm: "ai", embeddings: "ai", creations: "media",
+    // Platform
+    web_search: "platform", browser: "platform", discovery: "platform",
+    api_keys: "platform",
+    // Security
+    kali: "security", local_agent: "platform",
+    // Advertising
+    meta_ads: "advertising",
+    // Data
+    enrichment: "data",
+};
+async function handleDiscoverTools(sb, args) {
+    const names = args.names;
+    const category = args.category;
+    const refresh = args.refresh;
+    // Force reload from DB if refresh requested — busts the 60s cache
+    if (refresh) {
+        try {
+            const freshResult = await loadTools(sb, true);
+            setExtendedToolsCache(freshResult.extended);
+        }
+        catch {
+            // If refresh fails, continue with stale cache — better than erroring
+        }
+    }
+    if (!names?.length && !category) {
+        return { success: false, error: "Provide 'names' (array of tool names) or 'category' to discover tools." };
+    }
+    let matching = [];
+    if (names?.length) {
+        const nameSet = new Set(names);
+        matching = _extendedToolsCache.filter(t => nameSet.has(t.name));
+    }
+    if (category) {
+        const cat = category.toLowerCase();
+        const categoryTools = _extendedToolsCache.filter(t => TOOL_CATEGORIES[t.name] === cat);
+        // Merge without duplicates
+        const existingNames = new Set(matching.map(t => t.name));
+        for (const t of categoryTools) {
+            if (!existingNames.has(t.name))
+                matching.push(t);
+        }
+    }
+    if (matching.length === 0) {
+        const available = _extendedToolsCache.map(t => t.name).join(", ");
+        return { success: false, error: `No matching extended tools found. Available: ${available}` };
+    }
+    return {
+        success: true,
+        data: {
+            tools: matching.map(t => ({ name: t.name, description: t.description, input_schema: t.input_schema })),
+            count: matching.length,
+            refreshed: !!refresh,
+        },
+    };
+}
+// ============================================================================
+// USER TOOL EXECUTOR — handles RPC, HTTP, SQL execution types
+// ============================================================================
+async function executeUserTool(supabase, userTool, args, storeId, agentId, conversationId) {
+    const timeout = userTool.max_execution_time_ms || 5000;
+    if (userTool.execution_type === "http") {
+        return executeHTTPUserTool(supabase, userTool, args, storeId, timeout);
+    }
+    try {
+        const { data, error } = await supabase.rpc("execute_user_tool", {
+            p_tool_id: userTool.id,
+            p_store_id: storeId,
+            p_args: args,
+            p_agent_id: agentId || null,
+            p_conversation_id: conversationId || null,
+        });
+        if (error)
+            return { success: false, error: error.message };
+        const result = data;
+        if (result.pending_approval) {
+            return { success: false, error: `Tool requires approval. Execution ID: ${result.execution_id}. ${result.message}` };
+        }
+        if (result.success && result.data && result.data.execute_sql) {
+            return executeSQLUserTool(supabase, result.data, args, storeId);
+        }
+        return result.success
+            ? { success: true, data: result.data }
+            : { success: false, error: result.error || "Unknown error" };
+    }
+    catch (err) {
+        return { success: false, error: sanitizeError(err) };
+    }
+}
+async function executeHTTPUserTool(supabase, userTool, args, storeId, timeout) {
+    const config = userTool.http_config;
+    if (!config || !config.url) {
+        return { success: false, error: "HTTP tool has no URL configured" };
+    }
+    const httpCfg = config;
+    let url = httpCfg.url;
+    let headers = { ...(httpCfg.headers || {}) };
+    // Collect secret names referenced in the URL, headers, and body template
+    const configStr = JSON.stringify({ url: httpCfg.url, headers: httpCfg.headers, body: httpCfg.body_template });
+    const secretRefs = [...configStr.matchAll(/\{\{secret:(\w+)\}\}/g)].map(m => m[1]);
+    // Decrypt each referenced secret via RPC (consistent with all other handlers)
+    const secretMap = new Map();
+    await Promise.all([...new Set(secretRefs)].map(async (name) => {
+        try {
+            const { data } = await supabase.rpc("decrypt_secret", { p_name: name, p_store_id: storeId });
+            if (data)
+                secretMap.set(name, data);
+        }
+        catch { /* secret not found — will remain as {{secret:NAME}} placeholder */ }
+    }));
+    const resolveSecrets = (text) => {
+        return text.replace(/\{\{secret:(\w+)\}\}/g, (_, name) => secretMap.get(name) || `{{secret:${name}}}`);
+    };
+    const resolveArgs = (text) => {
+        return text.replace(/\{\{(\w+)\}\}/g, (_, name) => {
+            if (name === "secret")
+                return `{{${name}}}`;
+            const val = args[name];
+            return val !== undefined ? String(val) : `{{${name}}}`;
+        });
+    };
+    const resolve = (text) => resolveSecrets(resolveArgs(text));
+    url = resolve(url);
+    for (const [key, val] of Object.entries(headers)) {
+        headers[key] = resolve(val);
+    }
+    let body;
+    const method = (httpCfg.method || "GET").toUpperCase();
+    if (method !== "GET" && method !== "HEAD") {
+        if (httpCfg.body_template) {
+            const resolvedBody = {};
+            for (const [key, val] of Object.entries(httpCfg.body_template)) {
+                if (typeof val === "string") {
+                    resolvedBody[key] = resolve(val);
+                }
+                else {
+                    resolvedBody[key] = val;
+                }
+            }
+            for (const [key, val] of Object.entries(args)) {
+                if (!(key in resolvedBody)) {
+                    resolvedBody[key] = val;
+                }
+            }
+            body = JSON.stringify(resolvedBody);
+        }
+        else {
+            body = JSON.stringify(args);
+        }
+        if (!headers["Content-Type"] && !headers["content-type"]) {
+            headers["Content-Type"] = "application/json";
+        }
+    }
+    // P0 FIX: Use shared SSRF guard with DNS resolve-then-check (replaces inline regex)
+    const ssrfError = await validateUrl(url);
+    if (ssrfError) {
+        return { success: false, error: `Blocked: ${ssrfError}` };
+    }
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout);
+        const resp = await fetch(url, { method, headers, body, signal: controller.signal });
+        clearTimeout(timer);
+        // Clear secrets from memory as soon as the request is sent
+        secretMap.clear();
+        const contentType = resp.headers.get("content-type") || "";
+        let data;
+        if (contentType.includes("json")) {
+            data = await resp.json();
+        }
+        else {
+            data = await resp.text();
+        }
+        if (!resp.ok) {
+            return { success: false, error: `HTTP ${resp.status}: ${typeof data === "string" ? data.substring(0, 500) : JSON.stringify(data).substring(0, 500)}` };
+        }
+        return { success: true, data };
+    }
+    catch (err) {
+        // Clear secrets from memory even on error
+        secretMap.clear();
+        if (err.name === "AbortError") {
+            return { success: false, error: `HTTP request timed out after ${timeout}ms` };
+        }
+        return { success: false, error: sanitizeError(err) };
+    }
+}
+async function executeSQLUserTool(supabase, sqlConfig, args, storeId) {
+    if (!sqlConfig.is_read_only) {
+        return { success: false, error: "Write SQL tools are not supported in server execution" };
+    }
+    if (!sqlConfig.template) {
+        return { success: false, error: "No SQL template configured" };
+    }
+    try {
+        const { data, error } = await supabase.rpc("execute_safe_sql", {
+            p_sql: sqlConfig.template,
+            p_params: args,
+            p_store_id: storeId,
+            p_allowed_tables: sqlConfig.allowed_tables || [],
+        });
+        if (error)
+            return { success: false, error: error.message };
+        if (data?.success) {
+            return { success: true, data: data.data };
+        }
+        return { success: false, error: data?.error || "SQL execution failed" };
+    }
+    catch (err) {
+        return { success: false, error: sanitizeError(err) };
+    }
+}
+// ============================================================================
+// SUPPLY CHAIN — action aliasing (LLMs omit po_/transfer_ prefix)
+// ============================================================================
+async function executeSupplyChain(supabase, args, storeId, traceId, userId, userEmail, source, conversationId, userToolRows, agentId) {
+    let scAction = args.action || "";
+    const PO_ALIASES = {
+        create: "po_create", list: "po_list", get: "po_get",
+        add_items: "po_add_items", approve: "po_approve", mark_ordered: "po_mark_ordered",
+        receive: "po_receive", cancel: "po_cancel",
+    };
+    if (PO_ALIASES[scAction])
+        scAction = PO_ALIASES[scAction];
+    if (scAction === "find_suppliers") {
+        return executeTool(supabase, "suppliers", { ...args, action: "find_suppliers" }, storeId, traceId, userId, userEmail, source, conversationId, userToolRows, agentId);
+    }
+    if (scAction.startsWith("po_")) {
+        return executeTool(supabase, "purchase_orders", { ...args, action: scAction.slice(3) }, storeId, traceId, userId, userEmail, source, conversationId, userToolRows, agentId);
+    }
+    if (scAction.startsWith("transfer_")) {
+        return executeTool(supabase, "transfers", { ...args, action: scAction.slice(9) }, storeId, traceId, userId, userEmail, source, conversationId, userToolRows, agentId);
+    }
+    return { success: false, error: `Unknown supply_chain action: ${scAction}. Use po_create, po_list, po_get, po_approve, po_receive, po_cancel, transfer_create, transfer_list, transfer_approve, transfer_ship, transfer_receive, transfer_cancel, find_suppliers.` };
+}
+// ============================================================================
+// TOOL EXECUTOR — dispatches via unified handler registry
+// ============================================================================
+export async function executeTool(supabase, toolName, args, storeId, traceId, userId, userEmail, source, conversationId, userToolRows, agentId, onToolProgress, 
+/** Skip per-tool audit when called within a conversation — persistAgentTurn handles it */
+skipAudit) {
+    const startTime = Date.now();
+    const action = args.action;
+    let result;
+    // Handle supply_chain aliases (LLMs often omit po_/transfer_ prefix)
+    if (toolName === "supply_chain") {
+        return executeSupplyChain(supabase, args, storeId, traceId, userId, userEmail, source, conversationId, userToolRows, agentId);
+    }
+    // Look up handler from unified registry
+    const entry = TOOL_HANDLERS[toolName];
+    // Check store requirement from registry (not hardcoded)
+    const requiresStore = entry ? entry.requiresStore : true;
+    if (requiresStore && (!storeId || !/^[0-9a-fA-F]{8}-/.test(storeId))) {
+        return { success: false, error: `store_id is required for ${toolName}. Ensure a store is selected.` };
+    }
+    // Permission enforcement — check agent flags before tool execution
+    if (agentId) {
+        const { data: agentFlags } = await supabase.from("ai_agent_config")
+            .select("can_query, can_modify")
+            .eq("id", agentId).single();
+        if (agentFlags) {
+            // Read-only agent check — block ALL tool calls if can_query is false
+            if (!agentFlags.can_query) {
+                const readActions = ["list", "get", "search", "query", "summary", "stats", "count", "by_location", "in_stock", "out_of_stock", "velocity"];
+                const action = args.action;
+                if (action && readActions.includes(action)) {
+                    return { success: false, error: `Agent does not have query permission (can_query=false). Contact an admin.` };
+                }
+            }
+            // Mutation check — already in system prompt but enforce at execution level
+            if (!agentFlags.can_modify) {
+                const writeActions = ["create", "update", "delete", "upsert", "send", "approve", "cancel", "add", "remove", "set", "adjust", "transfer"];
+                const action = args.action;
+                if (action && writeActions.some(wa => action.startsWith(wa))) {
+                    return { success: false, error: `Agent has read-only access (can_modify=false). Cannot perform "${action}".` };
+                }
+            }
+        }
+    }
+    // User tool approval check — requires_approval enforced at execution level
+    if (toolName.startsWith("user_tool__") && userToolRows?.length) {
+        const userTool = getUserToolByPrefixedName(userToolRows, toolName);
+        if (userTool?.requires_approval) {
+            return { success: false, error: `Tool "${userTool.display_name}" requires approval before execution. Use the workflow approval system to request permission.` };
+        }
+    }
+    // Validate mutation args before dispatch — read-only actions pass through
+    const validation = validateToolArgs(toolName, args);
+    if (!validation.valid) {
+        return { success: false, error: validation.error };
+    }
+    args = validation.data;
+    const execStartMs = Date.now();
+    try {
+        let toolPromise;
+        if (entry) {
+            // Dispatch via unified handler registry — pass progress callback to handlers that support it
+            const progressCb = entry.supportsProgress && onToolProgress
+                ? (progress) => onToolProgress(toolName, progress)
+                : undefined;
+            toolPromise = entry.handler(supabase, args, storeId, progressCb);
+        }
+        else if (toolName.startsWith("user_tool__") && userToolRows && storeId) {
+            // Custom user tools
+            const userTool = getUserToolByPrefixedName(userToolRows, toolName);
+            if (userTool) {
+                toolPromise = executeUserTool(supabase, userTool, args, storeId, agentId, conversationId);
+            }
+            else {
+                toolPromise = Promise.resolve({ success: false, error: `Unknown user tool: ${toolName}` });
+            }
+        }
+        else {
+            toolPromise = Promise.resolve({ success: false, error: `Unknown tool: ${toolName}. Use the discover_tools action to see available tools.` });
+        }
+        const timeoutMs = entry?.timeout || DEFAULT_TIMEOUT;
+        // FIX 7: Timeout cascade validation — warn if step timeout < tool timeout
+        const stepTimeout = args._step_timeout_seconds;
+        if (stepTimeout && stepTimeout * 1000 < timeoutMs) {
+            console.warn(`[timeout-cascade] Step timeout (${stepTimeout}s) < tool timeout (${timeoutMs / 1000}s) for ${toolName}. Tool may outlive step.`);
+        }
+        result = await withTimeout(toolPromise, timeoutMs, toolName);
+    }
+    catch (err) {
+        result = { success: false, error: sanitizeError(err) };
+    }
+    // Record execution metrics
+    recordToolMetric(toolName, Date.now() - execStartMs, result.success);
+    // Audit log — enriched with OTEL fields for distributed tracing
+    // Skipped when tool is called within a conversation (SSE chat, channel agent, workflow)
+    // because persistAgentTurn already logs the full conversation with tool details
+    if (skipAudit)
+        return result;
+    try {
+        const endTime = Date.now();
+        // Compute payload sizes for observability
+        const inputJson = JSON.stringify(args);
+        const outputJson = result.data ? JSON.stringify(result.data) : "";
+        const inputBytes = inputJson.length;
+        const outputBytes = outputJson.length;
+        const details = {
+            source: source || "fly_container",
+            args,
+            // Keys that SwiftUI telemetry panel reads for rich display
+            tool_input: args,
+            input_bytes: inputBytes,
+            output_bytes: outputBytes,
+        };
+        if (result.success && result.data) {
+            details.result_summary = summarizeResult(toolName, action, result.data);
+            // Store full result for rich telemetry display (capped at 50KB to prevent JSONB bloat)
+            if (outputBytes <= 50_000) {
+                details.tool_result = result.data;
+            }
+            else {
+                details.tool_result = {
+                    _truncated: true,
+                    _type: Array.isArray(result.data) ? "array" : "object",
+                    _size: outputBytes,
+                    _count: Array.isArray(result.data) ? result.data.length : Object.keys(result.data).length,
+                };
+            }
+        }
+        if (result.error) {
+            details.tool_error = result.error;
+        }
+        const bytes = new Uint8Array(8);
+        crypto.getRandomValues(bytes);
+        const spanId = Array.from(bytes).map(b => b.toString(16).padStart(2, "0")).join("");
+        const auditRow = {
+            action: `tool.${toolName}${action ? `.${action}` : ""}`,
+            severity: result.success ? "info" : "error",
+            store_id: storeId || null,
+            resource_type: "mcp_tool",
+            resource_id: toolName,
+            request_id: traceId || null,
+            conversation_id: conversationId || null,
+            source: source || "fly_container",
+            details,
+            error_message: result.error || null,
+            duration_ms: endTime - startTime,
+            user_id: userId || null,
+            user_email: userEmail || null,
+            // OTEL fields
+            trace_id: traceId || null,
+            span_id: spanId,
+            span_kind: "INTERNAL",
+            service_name: "agent-server",
+            status_code: result.success ? "OK" : "ERROR",
+            start_time: new Date(startTime).toISOString(),
+            end_time: new Date(endTime).toISOString(),
+        };
+        queueAuditLog(supabase, auditRow);
+    }
+    catch (err) {
+        console.error("[audit] exception:", err);
+    }
+    return result;
+}
+// ============================================================================
+// AGENT LOADER
+// ============================================================================
+export async function loadAgentConfig(supabase, agentId, storeId) {
+    let query = supabase
+        .from("ai_agent_config")
+        .select("*")
+        .eq("id", agentId);
+    // P0 FIX: Filter by store_id to prevent cross-tenant agent access
+    if (storeId) {
+        query = query.eq("store_id", storeId);
+    }
+    const { data, error } = await query.single();
+    if (error || !data)
+        return null;
+    return data;
+}