@carrierllc/mcp 0.10.0 → 0.10.2

package/dist/index.js

@@ -2,10 +2,11 @@
 import {
   CARRIER_VERSION,
   OCS_MAX_USAGE_WINDOW_DAYS,
+  OcsApiError,
+  OcsClient,
   ROUTER_RULES,
   TARGET_IDS,
-  acquireEndpointSlot,
-  applyParamRenames,
+  activePeriodFromPackages,
   applySubscriberFilters,
   buildListSubscriberParams,
   buildRouterCatalog,
@@ -33,21 +34,24 @@ import {
   networkEventsOverPeriodParams,
   normalizePackageTemplate,
   normalizePackageTemplateChanges,
+  ocsLocalDateTime,
+  packageActivePeriodParams,
+  prepaidPackageLimits,
   probeAll,
   provisionClerk,
   rankTargets,
   recordToolDescription,
+  recurringIdForPackage,
   recurringPackageParams,
   renderHtml,
   repairPlanFor,
-  runWithBudget,
   storefrontClerkUrls,
   subscriberIdParams,
   subscriberRows,
   usageOverPeriodParams,
   verifyStorefront,
   withOcsListSummary
-} from "./chunk-DUAENMJE.js";
+} from "./chunk-PYXTCG4L.js";
 import "./chunk-SHKKVIIA.js";
 
 // src/index.ts
@@ -58,59 +62,6 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import * as Sentry from "@sentry/cloudflare";
 
-// src/client.ts
-var OcsApiError = class extends Error {
-  constructor(code, message, method) {
-    super(`[${method}] OCS error ${code}: ${message}`);
-    this.code = code;
-    this.method = method;
-    this.name = "OcsApiError";
-  }
-  code;
-  method;
-};
-var OcsClient = class {
-  baseUrl;
-  token;
-  constructor(baseUrl2, token2) {
-    this.baseUrl = baseUrl2.replace(/\/+$/, "");
-    this.token = token2;
-  }
-  async call(method, params = {}) {
-    await acquireEndpointSlot(this.token, method, "interactive");
-    const url = `${this.baseUrl}/v1?token=${this.token}`;
-    const body2 = JSON.stringify({ [method]: applyParamRenames(method, params) });
-    return runWithBudget(method, async (signal) => {
-      const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: body2,
-        signal
-      });
-      if (!res.ok) {
-        throw new OcsApiError(res.status, `HTTP ${res.status} ${res.statusText}`, method);
-      }
-      const json = await res.json();
-      if (json.status?.code !== 0) {
-        throw new OcsApiError(json.status?.code ?? -1, json.status?.msg ?? "Unknown error", method);
-      }
-      if (method === "getCustomerTariff" && json["listTariffRule"] !== void 0) {
-        return json["listTariffRule"];
-      }
-      if (method === "getSubscriberLocationByCellId") {
-        const byMethod = json[method];
-        if (byMethod !== void 0) {
-          return byMethod;
-        }
-        if (json["subscriberLocation"] !== void 0) {
-          return json["subscriberLocation"];
-        }
-      }
-      return json[method] ?? json;
-    });
-  }
-};
-
 // ../../packages/carrier-ai/dist/index.js
 import { AwsClient } from "aws4fetch";
 var AI_TIER_POLICY = {
@@ -1370,7 +1321,12 @@ function registerAllTools(server2, ctx) {
       TOOL_SCOPES["modify_account_balance"],
       ctx,
       async ({ accountId, amount, mode }, token2) => {
-        const params = { accountId, amount, mode };
+        const params = { accountId };
+        if (mode === "set") {
+          params.setBalance = amount;
+        } else {
+          params.amount = amount;
+        }
         return ocsCall(ctx.env, token2, "modifyAccountBalance", params);
       }
     )
@@ -1751,11 +1707,13 @@ function registerAllTools(server2, ctx) {
     "move_subscriber_range_to_account",
     {
       title: "Move Subscribers to Account",
-      description: "Use this to move a contiguous ICCID range of subscribers to a different account. Useful for bulk subscriber migrations between accounts or during account restructuring. Params: `iccidFrom` (start ICCID of range, inclusive), `iccidTo` (end ICCID of range, inclusive), `accountId` (target account ID from `list_reseller_accounts`). Returns: OCS confirmation of the range move with affected subscriber count. Do NOT use this for a single subscriber move \u2014 provide identical iccidFrom and iccidTo. Always call `list_subscribers` on the range first to verify the correct subscribers are included.",
+      description: "BREAKING CHANGE (2026-08-28): this tool's contract was rebuilt around account-ID ranges to match what OCS actually accepts \u2014 ICCID-pair targeting (`iccidFrom`/`iccidTo` + a single `accountId`) is gone. Zero field names were ever shared with OCS's real `moveSubscriberRangeToAccount` shape (verified live 2026-08-24 \u2014 see packages/ocs-spec/ocs-accepted-params.json), so every prior call to this tool failed outright; nothing that used to work stops working. Use this to move a contiguous range of subscribers, identified by IMSI or ICCID, from one account to another. Cross-reseller moves lose the subscribers' packages. Params: `srcAccountId` (source account ID from `list_reseller_accounts`), `destAccount` (destination account ID), `rangeType` ('IMSI' | 'ICCID' \u2014 which identifier `rangeStart`/`rangeEnd` are expressed in), `rangeStart` (inclusive start of the range), `rangeEnd` (inclusive end of the range). Returns: OCS confirmation with the count of subscribers moved. Do NOT use this for a single subscriber move \u2014 provide identical rangeStart and rangeEnd. Always call `list_subscribers` on the range first to verify the correct subscribers are included.",
       inputSchema: {
-        iccidFrom: z.string().describe("Start ICCID of range"),
-        iccidTo: z.string().describe("End ICCID of range"),
-        accountId: z.number().describe("Target account ID"),
+        srcAccountId: z.number().describe("Source account ID to move subscribers FROM"),
+        destAccount: z.number().describe("Destination account ID to move subscribers TO"),
+        rangeType: z.enum(["IMSI", "ICCID"]).describe("Whether rangeStart/rangeEnd identify subscribers by IMSI or ICCID"),
+        rangeStart: z.string().describe("Inclusive start of the identifier range"),
+        rangeEnd: z.string().describe("Inclusive end of the identifier range"),
         ...DRY_RUN_FIELD
       },
       annotations: { destructiveHint: true }
@@ -1765,10 +1723,12 @@ function registerAllTools(server2, ctx) {
       "moveSubscriberRangeToAccount",
       TOOL_SCOPES["move_subscriber_range_to_account"],
       ctx,
-      async ({ iccidFrom, iccidTo, accountId }, token2) => ocsCall(ctx.env, token2, "moveSubscriberRangeToAccount", {
-        iccidFrom,
-        iccidTo,
-        accountId
+      async ({ srcAccountId, destAccount, rangeType, rangeStart, rangeEnd }, token2) => ocsCall(ctx.env, token2, "moveSubscriberRangeToAccount", {
+        srcAccountId,
+        destAccount,
+        rangeType,
+        rangeStart,
+        rangeEnd
       })
     )
   );
@@ -1957,11 +1917,17 @@ function registerAllTools(server2, ctx) {
       "modifySubscriberPrepaidPackageLimits",
       TOOL_SCOPES["modify_package_limits"],
       ctx,
-      async ({ iccid, packageId, limits }, token2) => ocsCall(ctx.env, token2, "modifySubscriberPrepaidPackageLimits", {
-        iccid,
-        packageId,
-        ...JSON.parse(limits)
-      })
+      async ({ packageId, limits }, token2) => (
+        // OCS accepts only packageId/newLimits/comment here, so `iccid` never
+        // reaches the wire, and the limits nest under `newLimits`
+        // (dataByte/mocSecond/mtcSecond/moSms/mtSms) rather than sitting flat.
+        // mcp-stdio is a BYO-token surface, so unlike mcp-server there is no
+        // ownership-evidence use for the ICCID here.
+        ocsCall(ctx.env, token2, "modifySubscriberPrepaidPackageLimits", {
+          packageId,
+          newLimits: prepaidPackageLimits(JSON.parse(limits))
+        })
+      )
     )
   );
   server2.registerTool(
@@ -1993,9 +1959,11 @@ function registerAllTools(server2, ctx) {
       "modifySubscriberPrepaidPackageExpDate",
       TOOL_SCOPES["modify_package_expiry"],
       ctx,
-      async ({ iccid, packageId, expirationDate, validity_days }, token2) => {
-        const params = { iccid, packageId };
-        if (expirationDate !== void 0) params.expirationDate = expirationDate;
+      async ({ packageId, expirationDate, validity_days }, token2) => {
+        const params = { packageId };
+        if (expirationDate !== void 0) {
+          params.newExpirationDate = ocsLocalDateTime(expirationDate);
+        }
         if (validity_days !== void 0) params.newValidityDuration = validity_days;
         return ocsCall(ctx.env, token2, "modifySubscriberPrepaidPackageExpDate", params);
       }
@@ -2019,11 +1987,24 @@ function registerAllTools(server2, ctx) {
       "modifySubscriberPrepaidPackageStatus",
       TOOL_SCOPES["modify_package_status"],
       ctx,
-      async ({ iccid, packageId, status }, token2) => ocsCall(ctx.env, token2, "modifySubscriberPrepaidPackageStatus", {
-        iccid,
-        packageId,
-        status
-      })
+      async ({ packageId, status }, token2) => {
+        const normalised = String(status).trim().toUpperCase();
+        if (normalised !== "ACTIVE" && normalised !== "INACTIVE") {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Invalid status "${status}". Use "ACTIVE" or "INACTIVE".`
+              }
+            ]
+          };
+        }
+        return ocsCall(ctx.env, token2, "modifySubscriberPrepaidPackageStatus", {
+          subsPrepaidPackageId: packageId,
+          active: normalised === "ACTIVE"
+        });
+      }
     )
   );
   server2.registerTool(
@@ -2044,11 +2025,29 @@ function registerAllTools(server2, ctx) {
       "stopResumeSubsRecurringPackage",
       TOOL_SCOPES["stop_resume_recurring_package"],
       ctx,
-      async ({ iccid, packageId, action }, token2) => ocsCall(ctx.env, token2, "stopResumeSubsRecurringPackage", {
-        iccid,
-        packageId,
-        action
-      })
+      async ({ iccid, packageId, action }, token2) => {
+        const client2 = new OcsClient(ctx.env.CARRIER_OCS_BASE_URL, token2);
+        const listed = await client2.call(
+          "listSubscriberPrepaidPackages",
+          { iccid }
+        );
+        const recurringId = recurringIdForPackage(listed, packageId);
+        if (recurringId === void 0) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Package ${packageId} is not a recurring package on ICCID ${iccid}. stop_resume_recurring_package needs a package that came from a recurring template \u2014 call list_subscriber_packages and pick one that reports a recurring subscription.`
+              }
+            ]
+          };
+        }
+        return ocsCall(ctx.env, token2, "stopResumeSubsRecurringPackage", {
+          recurringId,
+          active: action === "resume"
+        });
+      }
     )
   );
   server2.registerTool(
@@ -4171,7 +4170,7 @@ function registerIntelligenceTools(server2, ctx) {
   }, async ({ accountId }) => {
     const token2 = await ctx.getUserToken(ctx.props.sub);
     const resellerId = await getDefaultResellerId(ctx.env, token2).catch(() => void 0);
-    const [statusResult, accountsResult] = await Promise.all([
+    const [statusResult, accountsResult, resellerInfoResult] = await Promise.all([
       safeCall(
         ctx.env,
         token2,
@@ -4183,7 +4182,17 @@ function registerIntelligenceTools(server2, ctx) {
         token2,
         "listResellerAccount",
         resellerId !== void 0 ? { resellerId } : {}
-      )
+      ),
+      // The reseller's OWN balance. Sub-account balances cannot show that the
+      // parent is out of credit, and that is the one state which silently
+      // zeroes every rating group (2026-08-28: reseller 1170 at 0.00 while
+      // fleet_health reported "require no action").
+      resellerId !== void 0 ? safeCall(
+        ctx.env,
+        token2,
+        "getResellerInfo",
+        { id: resellerId }
+      ) : Promise.resolve({ data: null, error: null })
     ]);
     const sections = ["# Fleet Health Dashboard\n"];
     const counts = extractEsimStatusCounts(statusResult.data);
@@ -4232,11 +4241,20 @@ High suspension rate (${totalSuspended} suspended vs ${totalActive} active)`);
       const criticalZero = accounts.filter(
         (a) => a.packageOnly === false && Number(a.balance ?? 0) <= 0
       );
+      const resellerRaw = resellerInfoResult?.data ?? null;
+      const rawBalance = resellerRaw?.getResellerInfo?.balance;
+      const resellerBalance = rawBalance === void 0 || rawBalance === null ? null : Number(rawBalance);
+      const resellerOutOfCredit = resellerBalance !== null && resellerBalance <= 0;
       sections.push(`
 ## Account Summary`);
       sections.push(`- Total accounts: ${accounts.length}`);
       sections.push(`- Low balance (< 10): ${lowBalance.length}`);
       sections.push(`- Package-only with 0 balance: ${packageOnlyZero.length}`);
+      if (resellerBalance !== null) {
+        sections.push(
+          `- Reseller balance: ${resellerBalance.toFixed(2)}` + (resellerOutOfCredit ? ` (OUT OF CREDIT - nothing can be rated)` : ``)
+        );
+      }
       if (lowBalance.length > 0) {
         sections.push(`
 ### Low Balance Accounts (< 10)`);
@@ -4266,8 +4284,15 @@ Action: top up non-package-only accounts at 0 balance to restore rated traffic.`
         sections.push(`
 All accounts healthy.`);
       } else if (informational > 0 && warning <= 0) {
-        sections.push(`
+        if (resellerOutOfCredit) {
+          sections.push(
+            `
+Action: reseller balance is ${resellerBalance.toFixed(2)}. Package-only accounts draw on their packages, but a reseller at 0 cannot rate any traffic - sessions are accepted and granted 0 bytes. Top up the reseller.`
+          );
+        } else {
+          sections.push(`
 Package-only accounts at 0 balance require no action.`);
+        }
       }
     } else {
       sections.push(`
@@ -5088,7 +5113,7 @@ function registerAllBacklogTools(server2, ctx) {
         const client2 = new OcsClient(ctx.env.CARRIER_OCS_BASE_URL, token2);
         const result2 = await client2.call(
           "modifySubscriberMobilePlan",
-          { subscriber: iccid, mobilePlanId: mobile_plan_id }
+          { subscriberId: { iccid }, mobilePlanId: mobile_plan_id }
         );
         return {
           content: [{ type: "text", text: JSON.stringify(result2, null, 2) }]
@@ -5106,6 +5131,9 @@ function registerAllBacklogTools(server2, ctx) {
         package_id: z3.number().describe("The subscriber package ID (from list_subscriber_packages)"),
         start_date: z3.string().optional().describe("New start date in ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss)"),
         end_date: z3.string().optional().describe("New end date in ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss)"),
+        comment: z3.string().optional().describe(
+          "Audit note stored on the OCS package record. OCS requires this field, so a default is sent when it is omitted."
+        ),
         ...DRY_RUN_FIELD2
       },
       annotations: { destructiveHint: true }
@@ -5115,11 +5143,22 @@ function registerAllBacklogTools(server2, ctx) {
       "modifySubscriberPrepaidPackageActivePeriod",
       BACKLOG_TOOL_SCOPES["modify_subscriber_package_active_period"],
       ctx,
-      async ({ iccid, package_id, start_date, end_date }, token2) => {
-        const params = { subscriber: iccid, packageId: package_id };
-        if (start_date !== void 0) params.startDate = start_date;
-        if (end_date !== void 0) params.endDate = end_date;
+      async ({ iccid, package_id, start_date, end_date, comment }, token2) => {
         const client2 = new OcsClient(ctx.env.CARRIER_OCS_BASE_URL, token2);
+        let current;
+        if (start_date === void 0 || end_date === void 0) {
+          const listed = await client2.call("listSubscriberPrepaidPackages", { iccid });
+          current = activePeriodFromPackages(listed, package_id);
+          if (!current) {
+            throw new Error(`Package ${package_id} is not on subscriber ${iccid}`);
+          }
+        }
+        const params = packageActivePeriodParams(package_id, {
+          startDate: start_date,
+          endDate: end_date,
+          comment,
+          current
+        });
         const result2 = await client2.call(
           "modifySubscriberPrepaidPackageActivePeriod",
           params
@@ -5151,7 +5190,7 @@ function registerAllBacklogTools(server2, ctx) {
         const client2 = new OcsClient(ctx.env.CARRIER_OCS_BASE_URL, token2);
         const result2 = await client2.call(
           "modifySubscriberVoipPlan",
-          { subscriber: iccid, voipPlanId: voip_plan_id }
+          { subscriberId: { iccid }, voipPlanId: voip_plan_id }
         );
         return {
           content: [{ type: "text", text: JSON.stringify(result2, null, 2) }]
@@ -5176,13 +5215,10 @@ function registerAllBacklogTools(server2, ctx) {
       BACKLOG_TOOL_SCOPES["push_steering_to_subscriber"],
       ctx,
       async ({ iccid }, token2) => {
-        const cache = /* @__PURE__ */ new Map();
-        const sub = await resolveSubscriberByIccid(ctx.env, token2, iccid, cache);
-        const subscriberId = sub.id ?? sub.subscriberId ?? iccid;
         const client2 = new OcsClient(ctx.env.CARRIER_OCS_BASE_URL, token2);
         const result2 = await client2.call(
           "pushSteeringToSubs",
-          { subscriber: subscriberId }
+          { iccid }
         );
         return {
           content: [{ type: "text", text: JSON.stringify(result2, null, 2) }]
@@ -5208,7 +5244,7 @@ function registerAllBacklogTools(server2, ctx) {
       ctx,
       async ({ iccid }, token2) => {
         const client2 = new OcsClient(ctx.env.CARRIER_OCS_BASE_URL, token2);
-        const result2 = await client2.call("resetSubsGzCounter", { subscriber: iccid });
+        const result2 = await client2.call("resetSubsGzCounter", { iccid });
         return {
           content: [{ type: "text", text: JSON.stringify(result2, null, 2) }]
         };
@@ -6683,6 +6719,11 @@ async function createTopupCheckout(env, args) {
   const successUrl = args.successUrl ?? env.WALLET_CHECKOUT_SUCCESS_URL ?? DEFAULT_SUCCESS_URL;
   const cancelUrl = args.cancelUrl ?? env.WALLET_CHECKOUT_CANCEL_URL ?? DEFAULT_CANCEL_URL;
   const bonusLabel = bonusCents > 0 ? ` (+\u20AC${(bonusCents / 100).toFixed(2)} bonus)` : "";
+  if (!env.CARRIER_USERS) {
+    throw new Error(
+      "Wallet top-up is not available in local stdio mode: the prepaid wallet is credited by the hosted Carrier service after payment, and this process cannot reach the customer record that crediting depends on. Creating the session here would bill the card against a duplicate Stripe customer and the wallet would never be credited. Top up from the console at https://app.carrier.llc/billing, or connect to the hosted MCP at https://mcp.carrier.llc/mcp, which has the binding. `wallet_balance` still works here if ATLAS_BASE_URL and CARRIER_INTERNAL_API_KEY are set."
+    );
+  }
   const billingSub = await resolveBillingSub(env, args.orgId);
   const existingCustomer = await env.CARRIER_USERS.get(`stripe_customer_id:${billingSub}`).catch(() => null);
   const params = new URLSearchParams({
@@ -6732,7 +6773,7 @@ async function runAutoTopup(env, args) {
   let packCents = args.packCents;
   try {
     const wallet = await getWallet(env, args.orgId);
-    if (packCents === void 0) packCents = wallet.auto_topup_pack_cents;
+    if (packCents === void 0) packCents = wallet.auto_topup_pack_cents ?? void 0;
   } catch (e) {
     if (e instanceof WalletClientError) {
       return { charged: false, creditedCents: 0, reason: `wallet_unreachable: ${e.message}` };
@@ -6838,15 +6879,23 @@ function registerWalletTools(server2, ctx) {
       description: "Read the caller organisation's Carrier prepaid wallet: current balance and auto-top-up settings. The wallet is what Carrier bills your own eSIM spend against \u2014 it is not an OCS balance and not your MCP plan credits. Params: none (the organisation is taken from the session). Returns: { org_id, balance_eur_cents, auto_topup_enabled, auto_topup_threshold_cents, auto_topup_pack_cents } \u2014 all amounts in EUR cents, not euros. Do NOT use this for a reseller account balance in OCS \u2014 use `get_reseller_info` or `list_reseller_accounts`. Do NOT use this for a subscriber's OCS balance \u2014 use `get_subscriber`. Do NOT use this for MCP plan credits \u2014 use `credit_balance`. Do NOT use this for money held at Stripe \u2014 use `stripe_connect_balance`.",
       inputSchema: {},
       // Derived from the object literal this handler builds below, not from the
-      // description. Every field is unconditional on the success path and comes
-      // straight off the Wallet record (wallet-client.ts:31-34), so all five are
-      // required rather than optional.
+      // description. All five keys are always present on the success path, so
+      // none is optional — but the two auto-top-up amounts are nullable, not
+      // just unset. ATLAS types them `number | null` and synthesises an
+      // all-null row for an org with no wallet yet (its toWalletView), so an
+      // org that has never configured auto-top-up — every newly onboarded one
+      // — returns null here. Requiring a number turned that, the most common
+      // state a new operator is in, into an output validation error.
       outputSchema: {
         org_id: z7.string().describe("Carrier organisation the wallet belongs to"),
         balance_eur_cents: z7.number().int().describe("Current balance in EUR cents"),
         auto_topup_enabled: z7.boolean(),
-        auto_topup_threshold_cents: z7.number().int().describe("Balance at or below which an auto top-up fires, EUR cents"),
-        auto_topup_pack_cents: z7.number().int().describe("Amount an auto top-up charges, EUR cents")
+        auto_topup_threshold_cents: z7.number().int().nullable().describe(
+          "Balance at or below which an auto top-up fires, EUR cents. Null when auto-top-up is unconfigured."
+        ),
+        auto_topup_pack_cents: z7.number().int().nullable().describe(
+          "Amount an auto top-up charges, EUR cents. Null when auto-top-up is unconfigured."
+        )
       },
       annotations: annotationsFor("wallet_balance", "read")
     },
@@ -7038,7 +7087,39 @@ function registerWalletTools(server2, ctx) {
 // src/stripe-connect-tools.ts
 import { z as z8 } from "zod";
 import * as Sentry3 from "@sentry/cloudflare";
+
+// src/binding-unavailable.ts
+var HOSTED_MCP_URL = "https://mcp.carrier.llc/mcp";
+var BindingUnavailableError = class extends Error {
+  constructor(tool, binding, message) {
+    super(message);
+    this.tool = tool;
+    this.binding = binding;
+    this.name = "BindingUnavailableError";
+  }
+  tool;
+  binding;
+};
+function requireUserStore(env, tool, subject) {
+  requireBinding(env.CARRIER_USERS, tool, "CARRIER_USERS", subject);
+}
+function requireBinding(binding, tool, name, subject) {
+  if (binding) return;
+  throw new BindingUnavailableError(
+    tool,
+    name,
+    `${tool} cannot answer here: ${subject} is held by the hosted Carrier service, and this local MCP server has no connection to it. There is nothing to set in your environment \u2014 the data does not exist on this machine. Connect to the hosted MCP at ${HOSTED_MCP_URL}, or open the console at https://app.carrier.llc, to use this tool. Every OCS tool in this server works against your own token and is unaffected.`
+  );
+}
+
+// src/stripe-connect-tools.ts
 async function verifyConfirmToken(env, sub, toolName, token2) {
+  requireBinding(
+    env.OAUTH_KV,
+    toolName,
+    "OAUTH_KV",
+    "the short-lived confirmation token this operation requires"
+  );
   const key = `confirm:${sub}:${toolName}`;
   const stored = await env.OAUTH_KV.get(key);
   if (!stored || stored !== token2) return false;
@@ -7046,6 +7127,12 @@ async function verifyConfirmToken(env, sub, toolName, token2) {
   return true;
 }
 async function issueConfirmToken(env, sub, toolName) {
+  requireBinding(
+    env.OAUTH_KV,
+    toolName,
+    "OAUTH_KV",
+    "the short-lived confirmation token this operation requires"
+  );
   const bytes = crypto.getRandomValues(new Uint8Array(16));
   const token2 = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
   const key = `confirm:${sub}:${toolName}`;
@@ -8173,6 +8260,7 @@ var PRICING_TOOLS = [
       required: []
     },
     handler: async (env, props2) => {
+      requireUserStore(env, "credit_balance", "your MCP plan credit ledger");
       const tier = props2.tier;
       const summary = await getCreditSummary(env, props2.sub, tier);
       const creditCheck = await checkCredits(env, props2.sub, tier, "read");
@@ -8254,6 +8342,7 @@ var PRICING_TOOLS = [
       required: []
     },
     handler: async (env, props2, args) => {
+      requireUserStore(env, "configure_billing", "your billing configuration");
       const tier = props2.tier;
       if (tier === "free") {
         return {
@@ -8322,6 +8411,11 @@ var PRICING_TOOLS = [
       required: []
     },
     handler: async (env, props2, args) => {
+      requireUserStore(
+        env,
+        "usage_projection",
+        "the consumption history a projection is drawn from"
+      );
       const tier = props2.tier;
       const summary = await getCreditSummary(env, props2.sub, tier);
       const now = /* @__PURE__ */ new Date();
@@ -8470,6 +8564,7 @@ var PRICING_TOOLS = [
       required: []
     },
     handler: async (env, props2, args) => {
+      requireUserStore(env, "billing_events", "your billing event history");
       const limit = Math.min(
         typeof args.limit === "number" ? args.limit : 20,
         50
@@ -8780,6 +8875,11 @@ var PROJECTS_TOOLS = [
       required: ["new_token", "confirm"]
     },
     handler: async (env, props2, args) => {
+      requireUserStore(
+        env,
+        "rotate_credentials",
+        "the encrypted token vault this writes to"
+      );
       if (!args.confirm) {
         return {
           status: "cancelled",
@@ -8794,7 +8894,9 @@ var PROJECTS_TOOLS = [
       }
       const encryptionKey = env.CARRIER_TOKEN_ENCRYPTION_KEY;
       if (!encryptionKey) {
-        return { error: "Encryption key not configured \u2014 contact support" };
+        throw new Error(
+          "rotate_credentials cannot run here: CARRIER_TOKEN_ENCRYPTION_KEY is a secret of the hosted Carrier service and is not present in a local install, so there is no way to encrypt a token for the vault. Rotate from the console at https://app.carrier.llc, or connect to the hosted MCP at https://mcp.carrier.llc/mcp. In local stdio mode the OCS token comes from CARRIER_OCS_API_TOKEN in your own environment \u2014 change it there and restart, no rotation call needed."
+        );
       }
       const encrypted = await encryptToken(newToken, encryptionKey);
       const orgId = props2.org_id;
@@ -8943,13 +9045,17 @@ var PROJECTS_TOOLS = [
     handler: async (env, props2) => {
       const sub = props2.sub;
       const orgId = props2.org_id;
+      const hasStore = !!env.CARRIER_USERS;
       let orgDetails = null;
-      if (orgId) {
+      if (orgId && hasStore) {
         orgDetails = await env.CARRIER_USERS.get(`org:${orgId}`, "json").catch(() => null);
       }
-      const hasStripe = !!await env.CARRIER_USERS.get(`stripe_customer_id:${sub}`);
-      const hasWebhook = !!await env.CARRIER_USERS.get(`webhook_url:${sub}`);
+      const hasStripe = hasStore ? !!await env.CARRIER_USERS.get(`stripe_customer_id:${sub}`) : null;
+      const hasWebhook = hasStore ? !!await env.CARRIER_USERS.get(`webhook_url:${sub}`) : null;
       return {
+        ...hasStore ? {} : {
+          note: "Running as a local stdio server. Fields reported as null are held by the hosted Carrier service and cannot be read from here; connect to https://mcp.carrier.llc/mcp to see them. Everything else below is this session's own configuration and is accurate."
+        },
         environment: {
           user_sub: sub,
           org_id: orgId ?? null,
@@ -9374,8 +9480,8 @@ var CURATED_ROUTER_TOOLS = [
   },
   {
     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" } } }
+    description: "Move a range of subscribers (by IMSI or ICCID) from one account to another. Intent: 'move subscribers', 'transfer SIMs to account'.",
+    input_schema: { type: "object", properties: { srcAccountId: { type: "number" }, destAccount: { type: "number" }, rangeType: { type: "string" } } }
   },
   {
     name: "hlr_get_bitrate",
@@ -9658,15 +9764,28 @@ var ROUTER_SYSTEM_PROMPT = `You are a carrier fleet operations router. Your job
 
 ${ROUTER_RULES}`;
 var ROUTER_TIMEOUT_MS = 12e3;
+var AskRouterNotConfiguredError = class extends Error {
+  constructor(missing) {
+    super(routerRemediation(missing));
+    this.missing = missing;
+    this.name = "AskRouterNotConfiguredError";
+  }
+  missing;
+};
+function missingRouterCredentials(env) {
+  const missing = [];
+  if (!env.AWS_ACCESS_KEY_ID) missing.push("AWS_ACCESS_KEY_ID");
+  if (!env.AWS_SECRET_ACCESS_KEY) missing.push("AWS_SECRET_ACCESS_KEY");
+  if (env.CARRIER_ASK_ENABLED !== "true") missing.push("CARRIER_ASK_ENABLED=true");
+  return missing;
+}
+function routerRemediation(missing) {
+  return `carrier_ask cannot route: ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not set. Set them in the environment of the process running this MCP server (for Claude Desktop / Cursor / Windsurf, the \`env\` block of the server entry in your MCP config), then restart it. The router calls Amazon Bedrock, so the credentials must belong to an IAM identity with bedrock:InvokeModel. Every other Carrier tool works without this \u2014 carrier_ask only picks which one to call, so you can call the tool you want directly in the meantime.`;
+}
 async function _routeIntent(intent, context, env, opts = {}) {
   const { attribution, onUsage } = opts;
   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"
-    };
+    throw new AskRouterNotConfiguredError(missingRouterCredentials(env));
   }
   const definedContext = Object.fromEntries(
     Object.entries(context).filter(([, value]) => value !== void 0)
@@ -9922,6 +10041,34 @@ function registerAllCarrierAskTools(server2, ctx) {
             }
           });
         } catch (err7) {
+          if (err7 instanceof AskRouterNotConfiguredError) {
+            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,
+              model_id: "none",
+              tier: ctx.props.tier,
+              usage: ZERO_USAGE
+            });
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    error: "router_not_configured",
+                    missing: err7.missing,
+                    message: err7.message
+                  })
+                }
+              ],
+              isError: true
+            };
+          }
           writeCarrierAskAudit(ctx.env, {
             intent_hash: intentHash,
             match: "error",
@@ -10279,6 +10426,12 @@ function registerListRecentOcsEventsTool(server2, ctx) {
             };
           }
         }
+        requireBinding(
+          env.OCS_EVENT_ROUTING,
+          "list_recent_ocs_events",
+          "OCS_EVENT_ROUTING",
+          "the OCS event ring buffer"
+        );
         const result2 = await listRecentOcsEvents2(
           iccid,
           limit,
@@ -10435,7 +10588,7 @@ function registerDepletionEventsTool(server2, ctx) {
       const kv = ctx.env.RATE_LIMIT_KV;
       if (!kv) {
         return err5(
-          "RATE_LIMIT_KV binding is not available in this environment. Add the binding to wrangler.jsonc and redeploy."
+          "subscriber_depletion_events cannot answer here. Depletion events are written by the Carrier webhook receiver as they arrive from the network and kept for 7 days in hosted storage; a local stdio server receives no webhooks and has nowhere to keep them, so there is no history on this machine to read. There is nothing to set in your environment. Use the hosted MCP at https://mcp.carrier.llc/mcp for this tool. To see a subscriber's current bundle state instead of its depletion history, `get_subscriber` and `list_subscriber_packages` query OCS directly and work here."
         );
       }
       const { subscriberId, since } = args;
@@ -12353,7 +12506,23 @@ var stdioEnv = {
   ATLAS_BASE_URL: process.env.ATLAS_BASE_URL,
   CARRIER_INTERNAL_API_KEY: process.env.CARRIER_INTERNAL_API_KEY,
   WALLET_CHECKOUT_SUCCESS_URL: process.env.WALLET_CHECKOUT_SUCCESS_URL,
-  WALLET_CHECKOUT_CANCEL_URL: process.env.WALLET_CHECKOUT_CANCEL_URL
+  WALLET_CHECKOUT_CANCEL_URL: process.env.WALLET_CHECKOUT_CANCEL_URL,
+  // Bedrock credentials for carrier_ask, the natural-language router. None of
+  // these appeared in this shim at all until now, so every read saw `undefined`
+  // and the routing gate in tools-carrier-ask.ts could never open: the flagship
+  // router had routed nothing from npm since it shipped. Same treatment as
+  // STRIPE_SECRET_KEY and the wallet values above — read the environment, and
+  // when absent let the tool refuse out loud rather than pretend it answered.
+  AWS_ACCESS_KEY_ID: process.env.AWS_ACCESS_KEY_ID,
+  AWS_SECRET_ACCESS_KEY: process.env.AWS_SECRET_ACCESS_KEY,
+  AWS_REGION: process.env.AWS_REGION,
+  BEDROCK_MODEL_ID: process.env.BEDROCK_MODEL_ID,
+  // Defaults ON here, unlike the Worker. The flag is the Worker's staged
+  // rollout switch; a local operator who has put AWS credentials on the process
+  // has already opted in, and making them set a second variable they have never
+  // heard of is just the same dead gate one step further along. Setting it to
+  // anything other than "true" still turns the router off.
+  CARRIER_ASK_ENABLED: process.env.CARRIER_ASK_ENABLED ?? "true"
 };
 var props = {
   sub: "stdio@local",