@carrierllc/mcp 0.2.1 → 0.2.3

package/dist/tools-carrier-ask.js

@@ -1,913 +0,0 @@
-/**
- * Carrier MCP — carrier_ask + carrier_ask_describe (v2.0 live routing).
- *
- * IMPLEMENTATION STATUS: LIVE (Phase 2)
- * carrier_ask now routes via Claude Haiku 4.5 on AWS Bedrock tool-use.
- * The router receives the full TOOL_REGISTRY as its tool catalog and returns
- * a single tool_use block identifying the best matching tool + extracted params.
- *
- * ACTIVATION:
- *   - Requires AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY in Doppler carrier/dev+stg+prd.
- *   - Set CARRIER_ASK_ENABLED=true in Doppler to activate per-env.
- *   - Without the credentials/flag, carrier_ask gracefully degrades to routing_pending.
- *
- * DESIGN CHOICES:
- *   - Router model: Claude Haiku 4.5 on Bedrock (us.anthropic.claude-haiku-4-5-20251001-v1:0).
- *   - Auth: SigV4 via aws4fetch — no AWS SDK bundle (CF Worker compatible).
- *   - tool_choice: { type: "any" } — forces a tool_use response.
- *   - Ambiguous/no-match: sentinel "carrier_clarify" tool for Haiku to signal.
- *   - HARD_BLOCK_TOOLS: always return confirm_token; never auto-execute.
- *   - Confirm token TTL: 120s. Single-use (deleted on consume).
- *   - Intent hashing: SHA-256, hex. Not stored verbatim (PII guard).
- *   - Audit log: Analytics Engine, fire-and-forget. Extended schema for router.
- *   - Rate-limit (429): returns friendly retry hint, never crashes.
- *
- * SAFETY FLOORS (non-negotiable):
- *   - Resolved tool name validated against TOOL_REGISTRY — no hallucination.
- *   - HARD_BLOCK_TOOLS always require confirm_token round-trip.
- *   - No-match / ambiguous: structured response, never fabricated tool call.
- */
-import { AwsClient } from "aws4fetch";
-import { z } from "zod";
-import { sha256 } from "@noble/hashes/sha256";
-import { bytesToHex } from "@noble/hashes/utils";
-import { TOOL_SCOPES, DESTRUCTIVE_TOOLS, wrapHandler } from "./tools.js";
-import { BACKLOG_TOOL_SCOPES } from "./tools-backlog.js";
-// ---------------------------------------------------------------------------
-// Tool registry — complete list of all MCP tool names known at build time.
-// Resolved tool names are validated against this set before returning to caller.
-// ---------------------------------------------------------------------------
-const TOOL_REGISTRY = new Set([
-    // v1 OCS tools (43)
-    ...Object.keys(TOOL_SCOPES),
-    // v1.1 backlog tools
-    ...Object.keys(BACKLOG_TOOL_SCOPES),
-    // intelligence composites (8)
-    "diagnose_subscriber",
-    "fleet_health",
-    "detect_usage_anomalies",
-    "optimize_package",
-    "churn_risk",
-    "audit_network_coverage",
-    "marketing_intelligence",
-    "high_cost_subscribers",
-    // event ring buffer (1)
-    "list_recent_ocs_events",
-    // MCP App tools (3)
-    "fleet_health_app",
-    "provision_esim_wizard",
-    "balance_topup_form",
-    // router tools (self-reference)
-    "carrier_ask",
-    "carrier_ask_describe",
-]);
-// Tools that MUST NEVER auto-execute from a natural-language intent.
-// Always require confirm_token round-trip regardless of confidence.
-const HARD_BLOCK_TOOLS = new Set([
-    "clean_all_packages",
-    "delete_subscriber_package",
-    "modify_account_balance",
-    "modify_subscriber_status",
-    "change_sim_status",
-    "reset_subscriber_gz_counter",
-]);
-// ---------------------------------------------------------------------------
-// Confirm token helpers
-// ---------------------------------------------------------------------------
-const CONFIRM_TOKEN_TTL_SECONDS = 120;
-const CONFIRM_TOKEN_PREFIX = "carrier_ask_confirm:";
-function generateConfirmToken() {
-    const bytes = crypto.getRandomValues(new Uint8Array(16));
-    return bytesToHex(bytes);
-}
-async function storeConfirmToken(kv, token, payload) {
-    await kv.put(`${CONFIRM_TOKEN_PREFIX}${token}`, JSON.stringify(payload), { expirationTtl: CONFIRM_TOKEN_TTL_SECONDS });
-}
-async function consumeConfirmToken(kv, token) {
-    const raw = await kv.get(`${CONFIRM_TOKEN_PREFIX}${token}`, "text");
-    if (!raw)
-        return null;
-    await kv.delete(`${CONFIRM_TOKEN_PREFIX}${token}`);
-    return JSON.parse(raw);
-}
-// ---------------------------------------------------------------------------
-// Intent hashing — SHA-256, hex-encoded.
-// ---------------------------------------------------------------------------
-export function hashIntent(intent) {
-    return bytesToHex(sha256(new TextEncoder().encode(intent)));
-}
-// ---------------------------------------------------------------------------
-// Router tool catalog for Bedrock.
-// Sentinel "carrier_clarify" signals ambiguity without hallucinating a match.
-// ---------------------------------------------------------------------------
-const ROUTER_TOOLS = [
-    {
-        name: "carrier_clarify",
-        description: "Use ONLY when the intent is genuinely ambiguous and you cannot determine a single best-matching tool. " +
-            "Provide 1-3 candidate tools and a clarifying question.",
-        input_schema: {
-            type: "object",
-            properties: {
-                candidates: {
-                    type: "array",
-                    items: {
-                        type: "object",
-                        properties: {
-                            tool: { type: "string" },
-                            reason: { type: "string" },
-                        },
-                        required: ["tool", "reason"],
-                    },
-                },
-                clarifying_question: { type: "string" },
-            },
-            required: ["candidates", "clarifying_question"],
-        },
-    },
-    {
-        name: "list_reseller_accounts",
-        description: "List all reseller accounts. Intent: 'show my accounts', 'list resellers', 'what accounts do I have'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "get_reseller_info",
-        description: "Get info about a specific reseller. Intent: 'reseller info', 'account details for reseller X'.",
-        input_schema: { type: "object", properties: { reseller_id: { type: "number" } } },
-    },
-    {
-        name: "esim_status_per_account",
-        description: "Show eSIM counts by status per account. Intent: 'esim overview', 'how many esims active per account'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "get_subscriber",
-        description: "Look up a single subscriber by ICCID or MSISDN. Intent: 'get subscriber', 'look up ICCID', 'find SIM 8931...'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, msisdn: { type: "string" } } },
-    },
-    {
-        name: "list_subscribers",
-        description: "List subscribers in an account. Intent: 'list subscribers', 'show all SIMs', 'subscribers in account X'.",
-        input_schema: { type: "object", properties: { account_id: { type: "number" }, page: { type: "number" } } },
-    },
-    {
-        name: "subscriber_usage",
-        description: "Show data usage for a subscriber (max 7 days). Intent: 'how much data did X use', 'usage for subscriber', 'data consumption'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, start: { type: "string" }, end: { type: "string" } } },
-    },
-    {
-        name: "subscriber_network_events",
-        description: "Show network events (attach/detach/roaming) for a subscriber. Intent: 'network events', 'connection history', 'roaming events'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, start: { type: "string" }, end: { type: "string" } } },
-    },
-    {
-        name: "list_subscriber_packages",
-        description: "List active packages for a subscriber. Intent: 'what packages does subscriber have', 'show data packages', 'subscriber plan'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "list_package_templates",
-        description: "List available package templates. Intent: 'what packages can I assign', 'show product catalog', 'available data plans'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "assign_package",
-        description: "Assign a one-time data package to a subscriber. Intent: 'assign package', 'give subscriber X the Y plan', 'add data package'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, packageTemplateId: { type: "number" } } },
-    },
-    {
-        name: "assign_recurring_package",
-        description: "Set up auto-renewing recurring package for a subscriber. Intent: 'monthly plan', 'recurring package', 'auto-renew data'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, packageTemplateId: { type: "number" } } },
-    },
-    {
-        name: "modify_package_limits",
-        description: "Change data/voice/SMS limits on an existing package. Intent: 'change package limit', 'update data cap', 'modify plan limits'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, packageId: { type: "number" } } },
-    },
-    {
-        name: "modify_package_expiry",
-        description: "Change the expiry date of a subscriber package. Intent: 'extend package', 'change expiry', 'push package end date'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, packageId: { type: "number" }, expiryDate: { type: "string" } } },
-    },
-    {
-        name: "modify_package_status",
-        description: "Activate or pause a specific package. Intent: 'pause package', 'activate package', 'suspend data plan'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, packageId: { type: "number" }, status: { type: "string" } } },
-    },
-    {
-        name: "stop_resume_recurring_package",
-        description: "Stop or resume a recurring package. Intent: 'cancel auto-renew', 'stop recurring', 'resume monthly plan'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, packageId: { type: "number" }, action: { type: "string" } } },
-    },
-    {
-        name: "delete_subscriber_package",
-        description: "DESTRUCTIVE: Delete a package from a subscriber. Intent: 'delete package', 'remove plan from subscriber'. Requires confirm_token.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, packageId: { type: "number" } } },
-    },
-    {
-        name: "clean_all_packages",
-        description: "DESTRUCTIVE: Remove ALL packages from a subscriber. Irreversible. Intent: 'reset packages', 'clean all plans', 'wipe packages'. Requires confirm_token.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "modify_subscriber_status",
-        description: "DESTRUCTIVE if terminating: Change subscriber status (ACTIVE/SUSPENDED/TERMINATED). Intent: 'suspend subscriber', 'pause SIM', 'terminate', 'reactivate'. Requires confirm_token.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, status: { type: "string" } } },
-    },
-    {
-        name: "modify_subscriber_balance",
-        description: "Add or set credit balance for a subscriber. Intent: 'top up subscriber', 'add credit', 'set subscriber balance'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, amount: { type: "number" } } },
-    },
-    {
-        name: "modify_account_balance",
-        description: "DESTRUCTIVE: Modify account-level balance. Intent: 'adjust account balance', 'add account credit'. Requires confirm_token.",
-        input_schema: { type: "object", properties: { accountId: { type: "number" }, amount: { type: "number" } } },
-    },
-    {
-        name: "modify_subscriber_contact_info",
-        description: "Update subscriber contact details. Intent: 'update subscriber name', 'change email for SIM', 'fix contact info'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, name: { type: "string" }, email: { type: "string" } } },
-    },
-    {
-        name: "set_subscriber_traffic_restrictions",
-        description: "Enable or disable voice/SMS/data restrictions. Intent: 'block data for subscriber', 'restrict voice', 'data-only SIM'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "modify_subscriber_steering_list",
-        description: "Set preferred network steering list for a subscriber. Intent: 'change network preference', 'steer to operator X', 'preferred network'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, steeringListId: { type: "number" } } },
-    },
-    {
-        name: "push_steering_to_subscriber",
-        description: "Push network steering config to subscriber device. Intent: 'push steering', 'apply network config', 'force network update'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "move_subscriber_range_to_account",
-        description: "Move a range of subscribers to a different account. Intent: 'move subscribers', 'transfer SIMs to account'.",
-        input_schema: { type: "object", properties: { accountId: { type: "number" } } },
-    },
-    {
-        name: "hlr_get_bitrate",
-        description: "Get current HLR bitrate cap for a subscriber. Intent: 'what speed is subscriber throttled to', 'get bitrate', 'check speed cap'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "hlr_set_bitrate",
-        description: "Set or remove HLR speed cap (throttle). Intent: 'throttle subscriber', 'set speed limit', 'cap to 256kbps', 'remove throttle'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, bitrate: { type: "number" } } },
-    },
-    {
-        name: "change_sim_status",
-        description: "DESTRUCTIVE: Change physical SIM card status. Intent: 'deactivate SIM', 'delete SIM card', 'suspend card'. Requires confirm_token.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, status: { type: "string" } } },
-    },
-    {
-        name: "send_sms",
-        description: "Send SMS to a subscriber. Intent: 'send text to subscriber', 'SMS ICCID X', 'message subscriber'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, message: { type: "string" } } },
-    },
-    {
-        name: "get_sim_provider_status",
-        description: "Get SIM provider / eSIM profile status. Intent: 'SIM provider status', 'eSIM profile downloaded?', 'check profile status'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "get_subscriber_location",
-        description: "Get approximate subscriber location. Intent: 'where is subscriber', 'subscriber location', 'locate SIM'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "get_subscriber_location_by_cell_id",
-        description: "Get granular subscriber location by cell tower. Intent: 'cell-level location', 'cell tower for subscriber', 'exact location'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "list_steering_lists",
-        description: "List available network steering lists. Intent: 'show steering lists', 'available networks', 'what network profiles exist'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "list_network_profiles",
-        description: "List network profiles. Intent: 'list network profiles', 'show network configs'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "list_location_zones",
-        description: "List location zones. Intent: 'list zones', 'show coverage zones'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "list_detailed_location_zones",
-        description: "List detailed location zones with coordinates. Intent: 'detailed zones', 'zone coordinates', 'coverage map'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "list_destination_prefixes",
-        description: "List destination number prefixes. Intent: 'list prefixes', 'routing prefixes', 'number ranges'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "list_destination_lists",
-        description: "List destination lists for voice/SMS routing. Intent: 'destination lists', 'routing lists'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "list_sponsors",
-        description: "List sponsor accounts. Intent: 'list sponsors', 'show sponsor accounts'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "get_tariff",
-        description: "Get tariff/rate rules. Intent: 'what are my rates', 'tariff info', 'pricing rules'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "create_package_template",
-        description: "Create a new package template. Intent: 'create package', 'new product', 'add package template'.",
-        input_schema: { type: "object", properties: { name: { type: "string" } } },
-    },
-    {
-        name: "create_location_zone",
-        description: "Create a new location zone. Intent: 'create zone', 'add location zone', 'new coverage zone'.",
-        input_schema: { type: "object", properties: { name: { type: "string" } } },
-    },
-    {
-        name: "modify_template_core",
-        description: "Modify core settings of a package template. Intent: 'edit package template', 'change template name/settings'.",
-        input_schema: { type: "object", properties: { templateId: { type: "number" } } },
-    },
-    {
-        name: "modify_template_recurring",
-        description: "Modify recurring billing settings of a template. Intent: 'change template renewal', 'edit recurring settings'.",
-        input_schema: { type: "object", properties: { templateId: { type: "number" } } },
-    },
-    {
-        name: "modify_template_throttling",
-        description: "Modify throttling settings of a template. Intent: 'change template speed', 'edit throttle on template'.",
-        input_schema: { type: "object", properties: { templateId: { type: "number" } } },
-    },
-    {
-        name: "subscriber_active_period",
-        description: "Get or set the active period for a subscriber. Intent: 'active period', 'subscriber validity', 'SIM activation window'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "list_recent_ocs_events",
-        description: "List recent OCS events for a subscriber (last 50, 24h window). Intent: 'recent events', 'event history', 'OCS log'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "affect_subscriber_phone_number",
-        description: "Assign or unassign a phone number to a subscriber. Intent: 'assign phone number', 'give SIM a number', 'remove number'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, msisdn: { type: "string" } } },
-    },
-    {
-        name: "modify_subscriber_mobile_plan",
-        description: "Change the mobile plan for a subscriber. Intent: 'change mobile plan', 'switch plan', 'update rate plan'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, planId: { type: "number" } } },
-    },
-    {
-        name: "modify_subscriber_package_active_period",
-        description: "Modify the active period of a subscriber's package. Intent: 'extend package period', 'change package dates'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" }, packageId: { type: "number" } } },
-    },
-    {
-        name: "modify_subscriber_voip_plan",
-        description: "Change VoIP plan for a subscriber. Intent: 'change voip plan', 'update voice plan'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "reset_subscriber_gz_counter",
-        description: "DESTRUCTIVE: Reset a subscriber's guaranteed zone counter. Irreversible. Intent: 'reset gz counter', 'clear gz usage'. Requires confirm_token.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "diagnose_subscriber",
-        description: "Run composite diagnostic on a subscriber. Intent: 'why is subscriber offline', 'diagnose SIM', 'troubleshoot ICCID'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "fleet_health",
-        description: "Show overall fleet health (active/suspended/churned counts, alerts). Intent: 'fleet status', 'how is my fleet', 'health overview', 'how many esims active'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "detect_usage_anomalies",
-        description: "Detect unusual data usage patterns across the fleet. Intent: 'usage anomalies', 'abnormal data use', 'spike detection'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "optimize_package",
-        description: "Suggest package optimizations for a subscriber based on usage. Intent: 'optimize package', 'right-size plan', 'package recommendation'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "churn_risk",
-        description: "Identify subscribers at risk of churning. Intent: 'churn risk', 'at-risk subscribers', 'who might leave'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "audit_network_coverage",
-        description: "Audit network coverage for subscriber or fleet. Intent: 'coverage audit', 'network coverage check', 'coverage gaps'.",
-        input_schema: { type: "object", properties: { iccid: { type: "string" } } },
-    },
-    {
-        name: "marketing_intelligence",
-        description: "Get marketing intelligence: usage trends, popular packages, growth metrics. Intent: 'marketing data', 'growth report', 'popular plans'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "high_cost_subscribers",
-        description: "List subscribers generating highest costs. Intent: 'high cost subscribers', 'most expensive SIMs', 'cost outliers'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "fleet_health_app",
-        description: "Open the fleet health MCP App UI. Intent: 'open fleet dashboard app', 'fleet health UI'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "provision_esim_wizard",
-        description: "Open the eSIM provisioning wizard app. Intent: 'provision esim', 'new esim wizard', 'onboard esim'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "balance_topup_form",
-        description: "Open the balance top-up form app. Intent: 'top up balance', 'add credit form', 'balance topup'.",
-        input_schema: { type: "object", properties: {} },
-    },
-    {
-        name: "carrier_ask_describe",
-        description: "Get documentation for a specific carrier tool. Intent: 'describe tool X', 'how does assign_package work', 'tool documentation'.",
-        input_schema: { type: "object", properties: { tool_name: { type: "string" } } },
-    },
-];
-// System prompt for the Haiku router
-const ROUTER_SYSTEM_PROMPT = `You are a carrier fleet operations router. Your job is to map a user's natural-language intent to exactly ONE tool from the Carrier MCP tool registry.
-
-Rules:
-1. Pick the single best-matching tool. Never pick carrier_ask (the router itself).
-2. Extract any parameters mentioned in the intent (ICCID, account IDs, amounts, etc.) as the tool's input.
-3. Use carrier_clarify ONLY when genuinely ambiguous — when multiple tools are equally likely and you need more information.
-4. DESTRUCTIVE tools are flagged in their descriptions — still pick them if they match; the safety layer handles the confirm flow.
-5. Only include params explicitly mentioned in the intent.
-6. Context fields (iccid, account_id, reseller_id) from the routing context take precedence.`;
-// ---------------------------------------------------------------------------
-// Default Bedrock config
-// ---------------------------------------------------------------------------
-const DEFAULT_REGION = "us-east-1";
-const DEFAULT_MODEL_ID = "us.anthropic.claude-haiku-4-5-20251001-v1:0";
-// ---------------------------------------------------------------------------
-// callBedrock — SigV4-signed InvokeModel via aws4fetch.
-// Exported for testing (mock globalThis.fetch or AwsClient in tests).
-// ---------------------------------------------------------------------------
-export async function callBedrock(env, payload) {
-    const region = env.AWS_REGION ?? DEFAULT_REGION;
-    const modelId = env.BEDROCK_MODEL_ID ?? DEFAULT_MODEL_ID;
-    const aws = new AwsClient({
-        accessKeyId: env.AWS_ACCESS_KEY_ID,
-        secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
-        region,
-        service: "bedrock",
-    });
-    const url = `https://bedrock-runtime.${region}.amazonaws.com/model/${encodeURIComponent(modelId)}/invoke`;
-    const resp = await aws.fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Accept: "application/json" },
-        body: JSON.stringify(payload),
-    });
-    if (!resp.ok) {
-        const body = await resp.text();
-        // 429 → surface as a structured rate-limit signal
-        if (resp.status === 429) {
-            const retryAfter = resp.headers.get("retry-after");
-            const err = new Error(`Bedrock rate limit: ${body}`);
-            err.isRateLimit = true;
-            err.retryAfter = retryAfter;
-            throw err;
-        }
-        throw new Error(`Bedrock invoke failed: ${resp.status} ${body}`);
-    }
-    return (await resp.json());
-}
-// ---------------------------------------------------------------------------
-// _routeIntent — core routing logic via Claude Haiku 4.5 on Bedrock.
-// Exported for testing (mock callBedrock or globalThis.fetch in tests).
-// ---------------------------------------------------------------------------
-export async function _routeIntent(intent, context, env) {
-    // Feature flag gate
-    if (env.CARRIER_ASK_ENABLED !== "true" || !env.AWS_ACCESS_KEY_ID || !env.AWS_SECRET_ACCESS_KEY) {
-        return {
-            match: "routing_pending",
-            intent_received: intent,
-            note: "carrier_ask routing engine is not yet activated. " +
-                "Add AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY to Doppler carrier/dev+stg+prd and set CARRIER_ASK_ENABLED=true.",
-            scaffold_version: "v2.0-bedrock",
-        };
-    }
-    // Merge context into user message (omit keys with undefined — JSON.stringify drops them)
-    const definedContext = Object.fromEntries(Object.entries(context).filter(([, value]) => value !== undefined));
-    const contextNote = Object.keys(definedContext).length > 0
-        ? `\n\nPre-resolved context: ${JSON.stringify(definedContext)}`
-        : "";
-    const userMessage = `${intent}${contextNote}`;
-    const payload = {
-        anthropic_version: "bedrock-2023-05-31",
-        max_tokens: 512,
-        system: ROUTER_SYSTEM_PROMPT,
-        messages: [{ role: "user", content: userMessage }],
-        tools: ROUTER_TOOLS,
-        tool_choice: { type: "any" },
-    };
-    let response;
-    try {
-        response = await callBedrock({
-            AWS_ACCESS_KEY_ID: env.AWS_ACCESS_KEY_ID,
-            AWS_SECRET_ACCESS_KEY: env.AWS_SECRET_ACCESS_KEY,
-            AWS_REGION: env.AWS_REGION,
-            BEDROCK_MODEL_ID: env.BEDROCK_MODEL_ID,
-        }, payload);
-    }
-    catch (err) {
-        if (err instanceof Error && err.isRateLimit) {
-            const retryAfter = err.retryAfter;
-            const parsedSeconds = retryAfter ? parseInt(retryAfter, 10) : 60;
-            return {
-                match: "rate_limited",
-                retry_after_seconds: Number.isFinite(parsedSeconds) ? parsedSeconds : 60,
-                suggestion: "Bedrock rate limit reached. Please retry after the indicated delay.",
-            };
-        }
-        throw err;
-    }
-    // Extract tool_use block
-    const toolUseBlock = response.content.find((block) => block.type === "tool_use");
-    if (!toolUseBlock) {
-        return {
-            match: "none",
-            closest: [],
-            suggestion: "Could not determine the right tool for this intent. Try rephrasing or use carrier_ask_describe to explore available tools.",
-        };
-    }
-    const { name: resolvedTool, input } = toolUseBlock;
-    const resolvedParams = (input ?? {});
-    // Clarification sentinel
-    if (resolvedTool === "carrier_clarify") {
-        const candidates = (resolvedParams.candidates ?? []);
-        const clarifyingQuestion = typeof resolvedParams.clarifying_question === "string"
-            ? resolvedParams.clarifying_question
-            : "Could you clarify your intent?";
-        return {
-            match: "ambiguous",
-            candidates,
-            clarifying_question: clarifyingQuestion,
-        };
-    }
-    // Hallucination guard
-    if (!TOOL_REGISTRY.has(resolvedTool)) {
-        return {
-            match: "none",
-            closest: [],
-            suggestion: `Router returned unknown tool '${resolvedTool}'. Please try rephrasing your intent.`,
-        };
-    }
-    // HARD_BLOCK: require confirm_token
-    if (HARD_BLOCK_TOOLS.has(resolvedTool)) {
-        return {
-            match: "pending_confirm",
-            resolved_tool: resolvedTool,
-            resolved_params: resolvedParams,
-            confidence: 0.95,
-            confirm_required: true,
-            confirm_token: "", // filled by caller after storeConfirmToken
-            confirm_expires_in_seconds: CONFIRM_TOKEN_TTL_SECONDS,
-            safety_note: `'${resolvedTool}' is a protected destructive operation. ` +
-                "Re-call carrier_ask with the returned confirm_token to execute.",
-        };
-    }
-    // Safe read/write tool
-    return {
-        match: "confirmed",
-        resolved_tool: resolvedTool,
-        resolved_params: resolvedParams,
-        confidence: 0.95,
-        confirm_required: false,
-        execution_note: `Call '${resolvedTool}' directly with resolved_params to execute. ` +
-            "carrier_ask does not auto-execute — the caller makes the explicit tool call.",
-    };
-}
-// ---------------------------------------------------------------------------
-// Audit log write for carrier_ask routing events.
-// ---------------------------------------------------------------------------
-function writeCarrierAskAudit(env, row) {
-    try {
-        env.AUDIT_LOG.writeDataPoint({
-            blobs: [
-                "carrier_ask", // blob[0] tool_name
-                row.resolved_tool, // blob[1] resolved tool (or "none")
-                row.status, // blob[2] ok | error
-                row.match, // blob[3] match type
-                row.intent_hash, // blob[4] SHA-256 of intent
-                row.confirm_token_state, // blob[5] confirm token state
-                row.sub, // blob[6] user subject
-            ],
-            doubles: [row.latency_ms],
-            indexes: [String(row.reseller_id)],
-        });
-    }
-    catch {
-        // Never let audit failure propagate
-    }
-}
-// ---------------------------------------------------------------------------
-// registerAllCarrierAskTools — registers carrier_ask + carrier_ask_describe
-// ---------------------------------------------------------------------------
-export function registerAllCarrierAskTools(server, ctx) {
-    // =========================================================================
-    // carrier_ask — natural-language router
-    // =========================================================================
-    server.registerTool("carrier_ask", {
-        title: "Natural Language Carrier Tool Router",
-        description: "Use this when you want to perform a carrier operation but don't know which specific tool to call. " +
-            "Describe your intent in plain language and carrier_ask will identify the correct tool(s) and " +
-            "suggest the required parameters. For simple read intents, it executes directly and returns results. " +
-            "For destructive operations it returns a confirm_token that you must pass in a second call. " +
-            "Params: `intent` (string — natural language description of what you want to do), " +
-            "`context` (optional: iccid, account_id, reseller_id if already known). " +
-            "Returns: RouteResult — confirmed | pending_confirm | ambiguous | none. " +
-            "Do NOT use this when you know the right tool — direct calls are faster and cheaper.",
-        inputSchema: {
-            intent: z
-                .string()
-                .min(3)
-                .describe("Natural-language description of the operation to perform " +
-                "(e.g. 'suspend ICCID 89316 until next month', 'show fleet health', " +
-                "'assign Europe 5GB package to subscriber 89316...')"),
-            context: z
-                .object({
-                iccid: z.string().optional().describe("Subscriber ICCID if already known"),
-                account_id: z.number().optional().describe("Account ID if already known"),
-                reseller_id: z.number().optional().describe("Reseller ID if already known"),
-            })
-                .optional()
-                .describe("Optional pre-resolved context to improve routing accuracy"),
-            confirm_token: z
-                .string()
-                .optional()
-                .describe("One-time token from a previous carrier_ask call with confirm_required=true. " +
-                "Providing this executes the previously staged destructive operation."),
-        },
-    }, wrapHandler("carrier_ask", "[carrier_ask]", "read", ctx, async (args, _token) => {
-        const { intent, context = {}, confirm_token } = args;
-        const intentHash = hashIntent(intent);
-        const start = Date.now();
-        // ------------------------------------------------------------------
-        // Confirm token redemption path
-        // ------------------------------------------------------------------
-        if (confirm_token) {
-            const staged = await consumeConfirmToken(ctx.env.OAUTH_KV, confirm_token);
-            if (!staged) {
-                writeCarrierAskAudit(ctx.env, {
-                    intent_hash: intentHash,
-                    match: "confirm_expired",
-                    resolved_tool: "none",
-                    confirm_token_state: "expired",
-                    status: "error",
-                    latency_ms: Date.now() - start,
-                    sub: ctx.props.sub,
-                    reseller_id: ctx.props.reseller_id,
-                });
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: "confirm_token_expired",
-                                message: `Confirm token '${confirm_token}' has expired or was already used. ` +
-                                    `Tokens expire after ${CONFIRM_TOKEN_TTL_SECONDS}s. Re-issue the original intent to get a new token.`,
-                            }),
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            const resolvedTool = staged.resolved_tool;
-            if (!TOOL_REGISTRY.has(resolvedTool)) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: "invalid_tool",
-                                message: `Staged tool '${resolvedTool}' is not in the tool registry.`,
-                            }),
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            writeCarrierAskAudit(ctx.env, {
-                intent_hash: typeof staged.intent_hash === "string" ? staged.intent_hash : intentHash,
-                match: "confirm_executed",
-                resolved_tool: resolvedTool,
-                confirm_token_state: "redeemed",
-                status: "ok",
-                latency_ms: Date.now() - start,
-                sub: ctx.props.sub,
-                reseller_id: ctx.props.reseller_id,
-            });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            match: "confirm_executed",
-                            resolved_tool: resolvedTool,
-                            resolved_params: staged.resolved_params,
-                            note: "Confirm token accepted. Call the resolved_tool directly with resolved_params " +
-                                "to execute the operation. carrier_ask does not auto-execute — the caller must " +
-                                "make the explicit tool call.",
-                        }),
-                    },
-                ],
-            };
-        }
-        // ------------------------------------------------------------------
-        // Main routing path
-        // ------------------------------------------------------------------
-        let route;
-        try {
-            route = await _routeIntent(intent, context, ctx.env);
-        }
-        catch (err) {
-            writeCarrierAskAudit(ctx.env, {
-                intent_hash: intentHash,
-                match: "error",
-                resolved_tool: "none",
-                confirm_token_state: "none",
-                status: "error",
-                latency_ms: Date.now() - start,
-                sub: ctx.props.sub,
-                reseller_id: ctx.props.reseller_id,
-            });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            error: "routing_error",
-                            message: err instanceof Error
-                                ? err.message
-                                : "An unexpected error occurred during routing.",
-                        }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        // Issue confirm token for HARD_BLOCK results
-        let finalRoute = route;
-        let confirmTokenState = "none";
-        if (route.match === "pending_confirm") {
-            const token = generateConfirmToken();
-            await storeConfirmToken(ctx.env.OAUTH_KV, token, {
-                resolved_tool: route.resolved_tool,
-                resolved_params: route.resolved_params,
-                intent_hash: intentHash,
-                issued_at: new Date().toISOString(),
-            });
-            finalRoute = { ...route, confirm_token: token };
-            confirmTokenState = "issued";
-        }
-        const resolvedToolForAudit = (route.match === "confirmed" || route.match === "pending_confirm")
-            ? route.resolved_tool
-            : "none";
-        writeCarrierAskAudit(ctx.env, {
-            intent_hash: intentHash,
-            match: route.match,
-            resolved_tool: resolvedToolForAudit,
-            confirm_token_state: confirmTokenState,
-            status: "ok",
-            latency_ms: Date.now() - start,
-            sub: ctx.props.sub,
-            reseller_id: ctx.props.reseller_id,
-        });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(finalRoute, null, 2),
-                },
-            ],
-        };
-    }));
-    // =========================================================================
-    // carrier_ask_describe — drill-down companion
-    // =========================================================================
-    server.registerTool("carrier_ask_describe", {
-        title: "Describe a Carrier Tool",
-        description: "Get full documentation for any registered Carrier MCP tool: description, " +
-            "parameters, 2-3 example invocations, required scope, destructive flag, and guidance. " +
-            "Params: `tool_name` (exact MCP tool name, e.g. 'assign_package'). " +
-            "Returns: structured tool metadata. Does NOT execute the tool.",
-        inputSchema: {
-            tool_name: z
-                .string()
-                .describe("The exact MCP tool name to describe (e.g. 'assign_package', 'hlr_set_bitrate')"),
-        },
-    }, wrapHandler("carrier_ask_describe", "[carrier_ask_describe]", "read", ctx, async ({ tool_name }, _token) => {
-        if (!TOOL_REGISTRY.has(tool_name)) {
-            const closest = [...TOOL_REGISTRY]
-                .filter((name) => name.includes(tool_name.split("_")[0] ?? "") || tool_name.includes(name.split("_")[0] ?? ""))
-                .slice(0, 5);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            error: "tool_not_found",
-                            tool_name,
-                            message: `'${tool_name}' is not a registered Carrier MCP tool.`,
-                            did_you_mean: closest.length > 0 ? closest : undefined,
-                            total_registered: TOOL_REGISTRY.size,
-                        }),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        const allScopes = { ...TOOL_SCOPES, ...BACKLOG_TOOL_SCOPES };
-        const scope = allScopes[tool_name] ?? "read";
-        const isDestructive = DESTRUCTIVE_TOOLS.has(tool_name);
-        const isHardBlock = HARD_BLOCK_TOOLS.has(tool_name);
-        const doc = {
-            tool_name,
-            scope,
-            destructive: isDestructive,
-            hard_block: isHardBlock,
-            hard_block_note: isHardBlock
-                ? "This tool is in the HARD_BLOCK list: carrier_ask will never auto-execute it. " +
-                    "It always requires an explicit confirm_token redemption."
-                : undefined,
-            dry_run_supported: isDestructive,
-            examples: buildExamples(tool_name),
-            note: "Full parameter descriptions are available in the tool's inputSchema. " +
-                "Call the tool with no arguments to trigger the MCP schema introspection response.",
-        };
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(doc, null, 2),
-                },
-            ],
-        };
-    }));
-}
-// ---------------------------------------------------------------------------
-// buildExamples — curated invocation examples for high-traffic tools.
-// ---------------------------------------------------------------------------
-function buildExamples(toolName) {
-    const examples = {
-        assign_package: [
-            { intent: "Give subscriber 89316... the Europe 5GB package", params: { iccid: "89316...", packageTemplateId: 42 } },
-            { intent: "Assign a one-time data package to this eSIM", params: { iccid: "89316...", packageTemplateId: 42 } },
-        ],
-        assign_recurring_package: [
-            { intent: "Set up monthly auto-renewal for subscriber 89316...", params: { iccid: "89316...", packageTemplateId: 55 } },
-        ],
-        modify_subscriber_status: [
-            { intent: "Pause Maya's subscription for 2 months", params: { iccid: "89316...", status: "SUSPENDED" } },
-            { intent: "Reactivate subscriber 89316...", params: { iccid: "89316...", status: "ACTIVE" } },
-        ],
-        hlr_set_bitrate: [
-            { intent: "Throttle ICCID 89316... to 256kbps", params: { iccid: "89316...", bitrate: 256000 } },
-            { intent: "Remove speed cap from subscriber 89316...", params: { iccid: "89316...", bitrate: 0 } },
-        ],
-        modify_subscriber_steering_list: [
-            { intent: "Connect this eSIM to the best network in Italy", params: { iccid: "89316...", steeringListId: 7 } },
-        ],
-        push_steering_to_subscriber: [
-            { intent: "Push the new steering config to the device", params: { iccid: "89316..." } },
-        ],
-        clean_all_packages: [
-            { intent: "Reset all packages for subscriber 89316... before reprovisioning", params: { iccid: "89316...", dry_run: true } },
-        ],
-        fleet_health: [
-            { intent: "Show me the fleet status overview", params: {} },
-            { intent: "How many eSIMs are active right now", params: {} },
-        ],
-        diagnose_subscriber: [
-            { intent: "Why is subscriber 89316... offline?", params: { iccid: "89316..." } },
-        ],
-    };
-    return examples[toolName] ?? [
-        { intent: `Call ${toolName} for subscriber 89316...`, params: { iccid: "89316..." } },
-    ];
-}
-// Export for TOOL_INVENTORY generation and reconcile script
-export { TOOL_REGISTRY, HARD_BLOCK_TOOLS };
-//# sourceMappingURL=tools-carrier-ask.js.map