@carrierllc/mcp 0.9.2 → 0.9.3

package/dist/index.js

@@ -1,25 +1,32 @@
 #!/usr/bin/env node
 import {
   CARRIER_VERSION,
+  OCS_MAX_USAGE_WINDOW_DAYS,
   ROUTER_RULES,
   TARGET_IDS,
   acquireEndpointSlot,
+  applyParamRenames,
   applySubscriberFilters,
   buildListSubscriberParams,
   buildRouterCatalog,
   buildSite,
   clerkCliDeps,
   configureClerkInstance,
+  daysUntil,
   deploySite,
   esimStatusPerAccountParams,
+  extractDailyUsage,
   extractEsimStatusCounts,
+  filterActiveSubscribers,
   fleetScreen,
+  formatBytes,
   formatProbes,
   generateStorefrontLogo,
   getLimitForEndpoint,
   getRateLimitWindowCounts,
   imsiFromSubscriberRecord,
   isTargetId,
+  lastNDaysPeriod,
   loadStorefrontBrand,
   locationParams,
   mergeEnvLocal,
@@ -33,11 +40,14 @@ import {
   recurringPackageParams,
   renderHtml,
   repairPlanFor,
+  runWithBudget,
   storefrontClerkUrls,
   subscriberIdParams,
+  subscriberRows,
   usageOverPeriodParams,
-  verifyStorefront
-} from "./chunk-4XHSOF62.js";
+  verifyStorefront,
+  withOcsListSummary
+} from "./chunk-KHNJNJX3.js";
 import "./chunk-SHKKVIIA.js";
 
 // src/index.ts
@@ -69,32 +79,35 @@ var OcsClient = class {
   async call(method, params = {}) {
     await acquireEndpointSlot(this.token, method, "interactive");
     const url = `${this.baseUrl}/v1?token=${this.token}`;
-    const body2 = JSON.stringify({ [method]: params });
-    const res = await fetch(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: body2
-    });
-    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;
+    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);
       }
-      if (json["subscriberLocation"] !== void 0) {
-        return json["subscriberLocation"];
+      const json = await res.json();
+      if (json.status?.code !== 0) {
+        throw new OcsApiError(json.status?.code ?? -1, json.status?.msg ?? "Unknown error", method);
       }
-    }
-    return json[method] ?? json;
+      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;
+    });
   }
 };
 
@@ -189,6 +202,9 @@ function estimateCostUsd(u, rates = HAIKU_RATES) {
 var DEFAULT_BEDROCK_REGION = "us-east-1";
 var DEFAULT_MODEL_ID = "us.anthropic.claude-haiku-4-5-20251001-v1:0";
 var BEDROCK_TIMEOUT_MS = 3e4;
+var MAX_ATTEMPTS = 4;
+var INITIAL_RETRY_MS = 100;
+var MIN_ATTEMPT_BUDGET_MS = 250;
 var BedrockRateLimitError = class extends Error {
   isRateLimit = true;
   /**
@@ -218,7 +234,11 @@ function client(creds) {
       secretAccessKey: creds.secretAccessKey,
       ...creds.sessionToken ? { sessionToken: creds.sessionToken } : {},
       region,
-      service: "bedrock"
+      service: "bedrock",
+      // See MAX_ATTEMPTS. aws4fetch's retry loop cannot be cancelled, so this
+      // layer owns the policy instead. Changing this back to the default 10
+      // silently restores the ~50s stall that timeoutMs is supposed to prevent.
+      retries: 0
     }),
     region,
     modelId: creds.modelId ?? DEFAULT_MODEL_ID
@@ -260,6 +280,47 @@ async function fail(resp) {
   }
   throw new BedrockError(text || `Bedrock returned HTTP ${resp.status}`, resp.status);
 }
+function timedOut() {
+  const err7 = new Error("Bedrock call timed out before a usable response");
+  err7.name = "TimeoutError";
+  return err7;
+}
+function sleep(ms, signal) {
+  if (signal.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal.addEventListener("abort", done, { once: true });
+  });
+}
+function retryable(status) {
+  return status === 429 || status >= 500;
+}
+async function sendWithRetry(aws, url, init, signal, deadlineAt) {
+  let throttled = null;
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    if (signal.aborted) break;
+    let resp;
+    try {
+      resp = await aws.fetch(url, init);
+    } catch (err7) {
+      if (signal.aborted && throttled) return throttled;
+      throw err7;
+    }
+    if (!retryable(resp.status)) return resp;
+    throttled = resp;
+    if (attempt === MAX_ATTEMPTS - 1) break;
+    const backoff = Math.random() * INITIAL_RETRY_MS * 2 ** attempt;
+    if (Date.now() + backoff + MIN_ATTEMPT_BUDGET_MS > deadlineAt) break;
+    await sleep(backoff, signal);
+  }
+  if (throttled) return throttled;
+  throw timedOut();
+}
 async function invokeTool(creds, req, signal) {
   const json = await invokeModelRaw(
     creds,
@@ -273,19 +334,24 @@ async function invokeTool(creds, req, signal) {
 }
 async function invokeModelRaw(creds, payload, opts = {}, signal) {
   const { aws, region, modelId } = client(creds);
+  const timeoutMs = opts.timeoutMs ?? BEDROCK_TIMEOUT_MS;
+  const deadlineAt = Date.now() + timeoutMs;
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? BEDROCK_TIMEOUT_MS);
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
   const onAbort = () => controller.abort();
   signal?.addEventListener("abort", onAbort, { once: true });
   try {
-    const resp = await aws.fetch(
+    const resp = await sendWithRetry(
+      aws,
       `https://bedrock-runtime.${region}.amazonaws.com/model/${encodeURIComponent(modelId)}/invoke`,
       {
         method: "POST",
         headers: headersFor(opts.attribution, "application/json"),
         body: JSON.stringify(payload),
         signal: controller.signal
-      }
+      },
+      controller.signal,
+      deadlineAt
     );
     if (!resp.ok) await fail(resp);
     return await resp.json();
@@ -769,11 +835,12 @@ function wrapHandler(toolName, ocsMethod, requiredScope, ctx, handler) {
     return result2;
   };
 }
-async function ocsCall(env, token2, method, params = {}) {
+async function ocsCall(env, token2, method, params = {}, listKind) {
   const client2 = new OcsClient(env.CARRIER_OCS_BASE_URL, token2);
   const result2 = await client2.call(method, params);
+  const payload = listKind ? withOcsListSummary(result2, listKind) : result2;
   return {
-    content: [{ type: "text", text: JSON.stringify(result2, null, 2) }]
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
   };
 }
 async function resolveSubscriberByIccid(env, token2, iccid, cache) {
@@ -803,7 +870,7 @@ function registerAllTools(server2, ctx) {
     "list_reseller_accounts",
     {
       title: "List Reseller Accounts",
-      description: "Use this to enumerate the accounts (sub-resellers or customer accounts) BELOW a reseller. Params: `resellerId` (integer, optional \u2014 omit to list accounts under the token owner's reseller). Returns: `{ reseller: [ { id, name, account: [ { id, name, balance, packageOnly } ] } ] }` \u2014 the accounts are NESTED under each reseller, not a flat top-level array. Do NOT use this to fetch a single subscriber's details \u2014 use `get_subscriber` instead. Do NOT use this to check eSIM activation counts \u2014 use `esim_status_per_account` for that. Do NOT use this to find a reseller's PARENT, balance or charging plans \u2014 those are above or on the reseller itself, not in this list; use `get_reseller_info`.",
+      description: "Use this to enumerate the accounts (sub-resellers or customer accounts) BELOW a reseller. Params: `resellerId` (integer, optional \u2014 omit to list accounts under the token owner's reseller). Returns: `{ summary, reseller: [ { id, name, account: [ { id, name, balance, packageOnly } ] } ] }` \u2014 the accounts are NESTED under each reseller, not a flat top-level array. `summary.total` therefore counts RESELLERS; the account count is `summary.nested.accounts`. For any question about accounts use that, never `total`. Do NOT use this to fetch a single subscriber's details \u2014 use `get_subscriber` instead. Do NOT use this to check eSIM activation counts \u2014 use `esim_status_per_account` for that. Do NOT use this to find a reseller's PARENT, balance or charging plans \u2014 those are above or on the reseller itself, not in this list; use `get_reseller_info`.",
       inputSchema: {
         resellerId: z.number().optional().describe("Filter to a specific reseller by ID (omit for token owner's reseller)")
       },
@@ -817,7 +884,7 @@ function registerAllTools(server2, ctx) {
       async ({ resellerId }, token2) => {
         const params = {};
         if (resellerId !== void 0) params.resellerId = resellerId;
-        return ocsCall(ctx.env, token2, "listResellerAccount", params);
+        return ocsCall(ctx.env, token2, "listResellerAccount", params, "resellers");
       }
     )
   );
@@ -965,7 +1032,7 @@ function registerAllTools(server2, ctx) {
     "list_subscribers",
     {
       title: "List Subscribers",
-      description: "Use this to list subscribers with optional filters and pagination. Good for fleet enumeration, bulk status checks, and finding subscribers by account or status. OCS REQUIRES at least one search key \u2014 provide exactly one of: `imsi`, `iccid`, `activationCode`, `accountId`, or `msisdn`. Calling with no key will be rejected before reaching OCS. Params: `imsi` (string), `iccid` (string), `activationCode` (string), `accountId` (integer), `msisdn` (string), `status` (string, e.g. 'ACTIVE'/'SUSPENDED'), `offset` (integer, pagination \u2014 default 0), `limit` (integer, max results \u2014 always set to avoid unbounded fetches; recommended max 100 per call). Returns: array of subscriber summary records with ICCID, status, and account. Do NOT use this to fetch full details for a specific subscriber \u2014 use `get_subscriber` for that.",
+      description: "Use this to list subscribers with optional filters and pagination. Good for fleet enumeration, bulk status checks, and finding subscribers by account or status. OCS REQUIRES at least one search key \u2014 provide exactly one of: `imsi`, `iccid`, `activationCode`, `accountId`, or `msisdn`. Calling with no key will be rejected before reaching OCS. Params: `imsi` (string), `iccid` (string), `activationCode` (string), `accountId` (integer), `msisdn` (string), `status` (string, e.g. 'ACTIVE'/'SUSPENDED'), `offset` (integer, pagination \u2014 default 0), `limit` (integer, max results \u2014 always set to avoid unbounded fetches; recommended max 100 per call). Returns: `{ summary, subscriberList: [...] }` \u2014 subscriber summary records with ICCID, status and account, behind a server-counted `summary.total` (rows returned) and `summary.breakdown.status`. Answer 'how many' from `summary`, not by counting rows \u2014 but when `summary.moreAvailable` is set this is one page, so report `summary.upstreamTotal` for the fleet-wide figure, never `total`. Do NOT use this to fetch full details for a specific subscriber \u2014 use `get_subscriber` for that.",
       inputSchema: z.object({
         imsi: z.string().optional().describe("Filter by IMSI"),
         iccid: z.string().optional().describe("Filter by ICCID"),
@@ -994,7 +1061,12 @@ function registerAllTools(server2, ctx) {
         const raw = await client2.call("listSubscriber", params);
         const payload = applySubscriberFilters(raw, args);
         return {
-          content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(withOcsListSummary(payload, "subscribers"), null, 2)
+            }
+          ]
         };
       }
     )
@@ -1321,7 +1393,7 @@ function registerAllTools(server2, ctx) {
     "list_subscriber_packages",
     {
       title: "List Subscriber Packages",
-      description: "Use this to retrieve all prepaid packages currently assigned to a subscriber. Returns each package's allowance (data/voice/SMS), consumed usage, expiry date, status, and packageId. Always call this before any package modification tool (`modify_package_limits`, `modify_package_expiry`, `modify_package_status`, `delete_subscriber_package`) to confirm the correct packageId and current state. Params: `iccid` (subscriber identifier). Returns: array of package records with `packageId`, `name`, `status`, `dataLimit`, `dataUsed`, `expirationDate`, `recurring` flag. Do NOT use this to browse the product catalog \u2014 use `list_package_templates` for that.",
+      description: "Use this to retrieve all prepaid packages currently assigned to a subscriber. Returns each package's allowance (data/voice/SMS), consumed usage, expiry date, status, and packageId. Always call this before any package modification tool (`modify_package_limits`, `modify_package_expiry`, `modify_package_status`, `delete_subscriber_package`) to confirm the correct packageId and current state. Params: `iccid` (subscriber identifier). Returns: `{ summary, prepaidPackage: [...] }` \u2014 package records with `packageId`, `name`, `status`, `dataLimit`, `dataUsed`, `expirationDate` and a `recurring` flag, behind a server-counted `summary.total` and a `summary.breakdown` over status and recurring. Answer 'how many' from `summary`, not by counting rows. Do NOT use this to browse the product catalog \u2014 use `list_package_templates` for that.",
       inputSchema: { iccid: z.string().describe("The subscriber ICCID") },
       annotations: { readOnlyHint: true }
     },
@@ -1330,7 +1402,7 @@ function registerAllTools(server2, ctx) {
       "listSubscriberPrepaidPackages",
       TOOL_SCOPES["list_subscriber_packages"],
       ctx,
-      async ({ iccid }, token2) => ocsCall(ctx.env, token2, "listSubscriberPrepaidPackages", { iccid })
+      async ({ iccid }, token2) => ocsCall(ctx.env, token2, "listSubscriberPrepaidPackages", { iccid }, "packages")
     )
   );
   server2.registerTool(
@@ -1563,10 +1635,11 @@ function registerAllTools(server2, ctx) {
     "list_package_templates",
     {
       title: "List Package Templates",
-      description: "Use this to browse the product catalog of prepaid package templates available for assignment. Returns each template's name, data/voice/SMS limits, pricing, validity period, location zone, and recurring configuration. Call this before `assign_package` or `assign_recurring_package` to obtain valid `packageTemplateId` values. Params: `accountId` (integer, optional \u2014 filter templates visible to a specific account). Returns: array of template records with `templateId`, `name`, `dataLimit`, `price`, `validityDays`, `locationZoneId`, `recurring`. Do NOT use this to list packages assigned to a specific subscriber \u2014 use `list_subscriber_packages`.",
-      inputSchema: {
-        accountId: z.number().optional().describe("Filter templates by account ID")
-      },
+      description: "Use this to browse the product catalog of prepaid package templates available for assignment. Returns each template's name, data/voice/SMS limits, pricing, validity period, location zone, and recurring configuration. Call this before `assign_package` or `assign_recurring_package` to obtain valid `packageTemplateId` values. Params: none \u2014 returns the whole catalog for the token owner's reseller. Returns: `{ summary, template: [...] }`. `summary.total` is the number of templates, counted by the server over the complete catalog, and `summary.breakdown` counts the templates per `recurring` value and per location zone. Answer any 'how many' question from `summary` \u2014 it is authoritative, and counting the rows yourself gets it wrong. Each row carries `prepaidpackagetemplateid`, `prepaidpackagetemplatename`, `databyte` (bytes), `cost`, `perioddays`, `locationzoneid`, `rdbLocationZones.locationzonename` and `recurring`. Do NOT use this to list packages assigned to a specific subscriber \u2014 use `list_subscriber_packages`.",
+      // No `accountId` — see the matching note in apps/mcp-server/src/tools.ts.
+      // OCS rejected every call that carried it, and it is not a rename of any
+      // of the five properties OCS does accept.
+      inputSchema: {},
       annotations: { readOnlyHint: true }
     },
     wrapHandler(
@@ -1574,11 +1647,7 @@ function registerAllTools(server2, ctx) {
       "listPrepaidPackageTemplate",
       TOOL_SCOPES["list_package_templates"],
       ctx,
-      async ({ accountId }, token2) => {
-        const params = {};
-        if (accountId !== void 0) params.accountId = accountId;
-        return ocsCall(ctx.env, token2, "listPrepaidPackageTemplate", params);
-      }
+      async (_args, token2) => ocsCall(ctx.env, token2, "listPrepaidPackageTemplate", {}, "templates")
     )
   );
   server2.registerTool(
@@ -1831,7 +1900,7 @@ function registerAllTools(server2, ctx) {
     "get_tariff",
     {
       title: "Get Customer Tariff",
-      description: `Use this to retrieve the tariff table for a reseller: per-country, per-operator wholesale data/voice/SMS rates. Useful for cost analysis, margin calculations, and identifying expensive roaming countries before steering decisions. Params: \`resellerId\` (integer, optional \u2014 omit to use the token owner's reseller); \`country\` (optional, ISO-3166 alpha-2 such as "nl" OR a full country name such as "Netherlands", case-insensitive); \`trafficType\` (optional, "data" | "voice" | "sms" \u2014 keeps only rules whose corresponding rate is greater than zero); \`verbose\` (optional boolean, default false \u2014 returns the full untouched OCS rule shape, capped at ${TARIFF_VERBOSE_MAX_RULES} rows, so combine it with the filters). Returns BY DEFAULT a projected result: \`totalRules\`, \`matchedRules\`, \`returnedRules\`, \`truncated\`, a hoisted \`currency\`, a \`fields\` legend and \`rules[]\` of short-keyed rows (\`iso\`, \`op\`, \`data\`, \`moCall\`, \`mtCall\`, \`moSms\`, \`mtSms\`, \`active\`). Zero rates and inactive flags are omitted per row. Nested operator detail (mccMncs, tadigs, continent, countryCode, utcOffset), the sponsor object, plan ids and the validity/discount flags are dropped unless \`verbose\` is true. Rows are capped at ${TARIFF_MAX_RULES}; when the cap bites, \`truncated\` is true and \`note\` says so explicitly and names the filter params \u2014 the result is never silently shortened. Filtering happens server-side on the complete OCS table, so a filtered call sees every matching rule. Response key in OCS is \`listTariffRule\`. Do NOT use this to assign a pricing plan to a subscriber \u2014 use \`modify_subscriber_mobile_plan\`. This shows the RESELLER's wholesale cost, not what end-users are charged.`,
+      description: `Use this to retrieve the tariff table for a reseller: per-country, per-operator wholesale data/voice/SMS rates. Useful for cost analysis, margin calculations, and identifying expensive roaming countries before steering decisions. Params: \`resellerId\` (integer, optional \u2014 omit to use the token owner's reseller); \`country\` (optional, ISO-3166 alpha-2 such as "nl" OR a full country name such as "Netherlands", case-insensitive); \`trafficType\` (optional, "data" | "voice" | "sms" \u2014 keeps only rules whose corresponding rate is greater than zero); \`verbose\` (optional boolean, default false \u2014 returns the full untouched OCS rule shape, capped at ${TARIFF_VERBOSE_MAX_RULES} rows, so combine it with the filters). Returns BY DEFAULT a projected result: \`totalRules\`, \`matchedRules\`, \`returnedRules\`, \`truncated\`, a hoisted \`currency\`, a \`fields\` legend and \`rules[]\` of short-keyed rows (\`iso\`, \`op\`, \`data\`, \`moCall\`, \`mtCall\`, \`moSms\`, \`mtSms\`, \`active\`). Zero rates and inactive flags are omitted per row. Nested operator detail (mccMncs, tadigs, continent, countryCode, utcOffset), the sponsor object, plan ids and the validity/discount flags are dropped unless \`verbose\` is true. Rows are capped at ${TARIFF_MAX_RULES}; when the cap bites, \`truncated\` is true and \`note\` says so explicitly and names the filter params \u2014 the result is never silently shortened. Filtering happens server-side on the complete OCS table, so a filtered call sees every matching rule. Response key in OCS is \`listTariffRule\`. This is the slowest tool on the platform: the OCS table is ~3.4 MB and takes 3 s in a fast window and up to ~2 minutes in a slow one, so the call carries a 180 s budget. Expect to wait, and do not call it in a loop. Do NOT use this to assign a pricing plan to a subscriber \u2014 use \`modify_subscriber_mobile_plan\`. This shows the RESELLER's wholesale cost, not what end-users are charged.`,
       inputSchema: {
         resellerId: z.number().optional().describe("Reseller ID (omit to use token owner's reseller)"),
         country: z.string().optional().describe(
@@ -1957,8 +2026,9 @@ var ocs_methods_default = {
       scope: "read",
       description: "Retrieve reseller details",
       params: {
-        resellerId: { type: "number", required: false }
+        resellerId: { type: "number", required: false, ocs_field: "id" }
       },
+      params_note: "`resellerId` is the MCP-facing name. OCS getResellerInfo accepts exactly one property, `id`; @carrier/ocs-client translates it at the serialisation chokepoint (OCS_PARAM_RENAMES).",
       response: {},
       annotations: "readOnlyHint",
       verified_against_server: true,
@@ -2363,9 +2433,8 @@ var ocs_methods_default = {
       category: "templates",
       scope: "read",
       description: "List all prepaid package templates",
-      params: {
-        accountId: { type: "number", required: false }
-      },
+      params: {},
+      params_note: "No account filter. OCS listPrepaidPackageTemplate accepts only locationZoneId, templateId, destinationListId, resellerId, sponsorId. The former `accountId` param was rejected by OCS on every call and is not a rename of any of those five: accounts are a different id space from resellers and sponsors.",
       response: {},
       annotations: "readOnlyHint",
       verified_against_server: true,
@@ -3499,26 +3568,9 @@ async function fetchActiveSubscribers(env, token2, accountId, resellerId) {
       { accountId: acctId }
     );
     if (subResult.error) return { data: null, error: subResult.error };
-    const raw = subResult.data;
-    const list = Array.isArray(raw) ? raw : raw?.subscriberList ?? [];
-    aggregated.push(...list);
+    aggregated.push(...subscriberRows(subResult.data));
   }
-  const active = aggregated.filter((s) => String(s.status ?? "").toUpperCase() === "ACTIVE");
-  return { data: active, error: null };
-}
-function formatBytes(bytes) {
-  if (bytes === 0) return "0 B";
-  const units = ["B", "KB", "MB", "GB", "TB"];
-  const i = Math.floor(Math.log(bytes) / Math.log(1024));
-  return `${(bytes / Math.pow(1024, i)).toFixed(2)} ${units[i]}`;
-}
-function daysUntil(dateStr) {
-  const now = /* @__PURE__ */ new Date();
-  const target = new Date(dateStr);
-  return Math.ceil((target.getTime() - now.getTime()) / (1e3 * 60 * 60 * 24));
-}
-function toISODate(d) {
-  return d.toISOString().split("T")[0];
+  return { data: filterActiveSubscribers(aggregated), error: null };
 }
 function result(text, isError = false) {
   return { content: [{ type: "text", text }], ...isError ? { isError: true } : {} };
@@ -3598,10 +3650,10 @@ function registerIntelligenceTools(server2, ctx) {
       }
     }
     const now = /* @__PURE__ */ new Date();
-    const twoDaysAgo = new Date(now.getTime() - 2 * 24 * 60 * 60 * 1e3);
+    const eventWindow = lastNDaysPeriod(3, now);
     const events = await safeCall(ctx.env, token2, "subscriberNetworkEventsOverPeriod", {
       subscriber: { iccid },
-      period: { start: toISODate(twoDaysAgo), end: toISODate(now) }
+      period: eventWindow
     });
     if (events.data && Array.isArray(events.data)) {
       if (events.data.length === 0) {
@@ -3778,11 +3830,11 @@ Package-only accounts at 0 balance require no action.`);
   }, async ({ iccid }) => {
     const token2 = await ctx.getUserToken(ctx.props.sub);
     const now = /* @__PURE__ */ new Date();
-    const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1e3);
+    const usagePeriod = lastNDaysPeriod(OCS_MAX_USAGE_WINDOW_DAYS, now);
     const [usageResult, pkgResult] = await Promise.all([
       safeCall(ctx.env, token2, "subscriberUsageOverPeriod", {
         subscriber: { iccid },
-        period: { start: toISODate(weekAgo), end: toISODate(now) }
+        period: usagePeriod
       }),
       safeCall(ctx.env, token2, "listSubscriberPrepaidPackages", { iccid })
     ]);
@@ -3790,13 +3842,8 @@ Package-only accounts at 0 balance require no action.`);
     const sections = [`# Usage Anomaly Report: ${iccid}
 `];
     const anomalies = [];
-    if (usageResult.data && Array.isArray(usageResult.data) && usageResult.data.length > 0) {
-      const dailyData = [];
-      for (const entry of usageResult.data) {
-        const bytes = Number(entry.dataBytes ?? entry.dataVolume ?? entry.totalData ?? 0);
-        const date = String(entry.date ?? entry.day ?? "?");
-        dailyData.push({ date, bytes });
-      }
+    const dailyData = extractDailyUsage(usageResult.data);
+    if (dailyData.length > 0) {
       if (dailyData.length >= 2) {
         const volumes = dailyData.map((d) => d.bytes);
         const mean = volumes.reduce((a, b) => a + b, 0) / volumes.length;
@@ -3864,24 +3911,21 @@ Package-only accounts at 0 balance require no action.`);
   }, async ({ iccid }) => {
     const token2 = await ctx.getUserToken(ctx.props.sub);
     const now = /* @__PURE__ */ new Date();
-    const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1e3);
+    const usagePeriod = lastNDaysPeriod(OCS_MAX_USAGE_WINDOW_DAYS, now);
     const [usageResult, pkgResult, templatesResult] = await Promise.all([
       safeCall(ctx.env, token2, "subscriberUsageOverPeriod", {
         subscriber: { iccid },
-        period: { start: toISODate(weekAgo), end: toISODate(now) }
+        period: usagePeriod
       }),
       safeCall(ctx.env, token2, "listSubscriberPrepaidPackages", { iccid }),
       safeCall(ctx.env, token2, "listPrepaidPackageTemplate", {})
     ]);
     const sections = [`# Package Optimization: ${iccid}
 `];
+    const optimizeRows = extractDailyUsage(usageResult.data);
     let avgDailyData = 0;
-    if (usageResult.data && Array.isArray(usageResult.data) && usageResult.data.length > 0) {
-      const totalData = usageResult.data.reduce(
-        (sum, e) => sum + Number(e.dataBytes ?? e.dataVolume ?? e.totalData ?? 0),
-        0
-      );
-      avgDailyData = totalData / usageResult.data.length;
+    if (optimizeRows.length > 0) {
+      avgDailyData = optimizeRows.reduce((sum, r) => sum + r.bytes, 0) / optimizeRows.length;
       sections.push(`## Current Usage Pattern`);
       sections.push(`- Average daily data: ${formatBytes(avgDailyData)}`);
       sections.push(`- Projected monthly: ${formatBytes(avgDailyData * 30)}`);
@@ -3952,22 +3996,21 @@ Package-only accounts at 0 balance require no action.`);
   }, async ({ iccid }) => {
     const token2 = await ctx.getUserToken(ctx.props.sub);
     const now = /* @__PURE__ */ new Date();
-    const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1e3);
+    const usagePeriod = lastNDaysPeriod(OCS_MAX_USAGE_WINDOW_DAYS, now);
     const [subResult, usageResult, pkgResult, activeResult] = await Promise.all([
       safeCall(ctx.env, token2, "getSingleSubscriber", { iccid }),
       safeCall(ctx.env, token2, "subscriberUsageOverPeriod", {
         subscriber: { iccid },
-        period: { start: toISODate(weekAgo), end: toISODate(now) }
+        period: usagePeriod
       }),
       safeCall(ctx.env, token2, "listSubscriberPrepaidPackages", { iccid }),
       safeCall(ctx.env, token2, "getSubscriberActivePeriod", { iccid })
     ]);
     let riskScore = 0;
     const factors = [];
-    if (usageResult.data && Array.isArray(usageResult.data) && usageResult.data.length >= 3) {
-      const volumes = usageResult.data.map(
-        (e) => Number(e.dataBytes ?? e.dataVolume ?? e.totalData ?? 0)
-      );
+    const churnRows = extractDailyUsage(usageResult.data);
+    if (churnRows.length >= 3) {
+      const volumes = churnRows.map((r) => r.bytes);
       const firstHalf = volumes.slice(0, Math.floor(volumes.length / 2));
       const secondHalf = volumes.slice(Math.floor(volumes.length / 2));
       const avgFirst = firstHalf.reduce((a, b) => a + b, 0) / firstHalf.length;
@@ -3984,7 +4027,7 @@ Package-only accounts at 0 balance require no action.`);
           factors.push({ factor: "Moderately declining usage", impact, detail: `Usage dropped ${Math.abs(trend * 100).toFixed(0)}%` });
         }
       }
-    } else if (!usageResult.data || Array.isArray(usageResult.data) && usageResult.data.length === 0) {
+    } else if (churnRows.length === 0) {
       riskScore += 25;
       factors.push({ factor: "No recent usage", impact: 25, detail: "Zero data activity in last 7 days" });
     }
@@ -4279,7 +4322,7 @@ ${networksSorted.length} different networks in ${country} \u2014 possible steeri
     const sections = [`# High Cost Subscriber Report
 `];
     const now = /* @__PURE__ */ new Date();
-    const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1e3);
+    const usagePeriod = lastNDaysPeriod(OCS_MAX_USAGE_WINDOW_DAYS, now);
     const highCostSubs = [];
     const batchSize = 5;
     const subs = subsResult.data.slice(0, sampleSize);
@@ -4291,19 +4334,13 @@ ${networksSorted.length} different networks in ${country} \u2014 possible steeri
           const [usage, pkgs, loc] = await Promise.all([
             safeCall(ctx.env, token2, "subscriberUsageOverPeriod", {
               subscriber: { iccid },
-              period: { start: toISODate(weekAgo), end: toISODate(now) }
+              period: usagePeriod
             }),
             safeCall(ctx.env, token2, "listSubscriberPrepaidPackages", { iccid }),
             safeCall(ctx.env, token2, "getSubscriberLocation", { iccid })
           ]);
-          let dailyAvgBytes = 0;
-          if (usage.data && Array.isArray(usage.data) && usage.data.length > 0) {
-            const totalBytes = usage.data.reduce(
-              (sum, e) => sum + Number(e.dataBytes ?? e.dataVolume ?? e.totalData ?? 0),
-              0
-            );
-            dailyAvgBytes = totalBytes / usage.data.length;
-          }
+          const dailyRows = extractDailyUsage(usage.data);
+          const dailyAvgBytes = dailyRows.length > 0 ? dailyRows.reduce((sum, r) => sum + r.bytes, 0) / dailyRows.length : 0;
           if (pkgs.data && Array.isArray(pkgs.data)) {
             const activePkg = pkgs.data.find(
               (p) => String(p.status ?? "").toUpperCase() === "ACTIVE"
@@ -4378,7 +4415,7 @@ ${networksSorted.length} different networks in ${country} \u2014 possible steeri
   });
   server2.registerTool("detect_country_entry", {
     title: "Detect Country Entry",
-    description: "Detects when a subscriber has entered a new country by reading networkInfo.lastMcc from getSingleSubscriber (one cheap OCS call \u2014 avoids the per-call cost of getSubscriberLocationByCellId). Resolves MCC \u2192 ISO 3166-1 alpha-2 and optionally diffs against a caller-supplied expectedCountry to return countryChanged. Designed for downstream country-entry upsell workflows (e.g. mango.talk SMS/push offers). COST NOTE: This tool makes exactly one OCS call per invocation. Consumers running polling crons MUST enforce their own rate floor \u2014 this layer provides no throttle.",
+    description: "Detects when a subscriber has entered a new country by reading networkInfo.lastMcc from getSingleSubscriber (one cheap OCS call \u2014 avoids the per-call cost of getSubscriberLocationByCellId). Resolves MCC \u2192 ISO 3166-1 alpha-2 and optionally diffs against a caller-supplied expectedCountry to return countryChanged. Designed for downstream country-entry upsell workflows (e.g. mango.talk SMS/push offers). NOT AN AI TOOL: this is a deterministic MCC lookup and returns no model-written analysis, unlike the eight intelligence composites. COST NOTE: This tool makes exactly one OCS call per invocation. Consumers running polling crons MUST enforce their own rate floor \u2014 this layer provides no throttle.",
     inputSchema: {
       subscriber: z2.union([
         z2.object({ subscriberId: z2.number() }).describe("Internal subscriber ID"),
@@ -6925,8 +6962,11 @@ var WALLET_TOOL_SCOPES = {
   wallet_topup_checkout: "write",
   wallet_auto_topup: "write"
 };
-function ok(text) {
-  return { content: [{ type: "text", text }] };
+function okStructured(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload) }],
+    structuredContent: payload
+  };
 }
 function err(text) {
   return { isError: true, content: [{ type: "text", text }] };
@@ -6940,6 +6980,17 @@ function registerWalletTools(server2, ctx) {
       title: "Wallet Balance",
       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.
+      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")
+      },
       annotations: annotationsFor("wallet_balance", "read")
     },
     async () => {
@@ -6958,15 +7009,13 @@ function registerWalletTools(server2, ctx) {
           sub: props2.sub,
           reseller_id: props2.reseller_id
         });
-        return ok(
-          JSON.stringify({
-            org_id: orgId,
-            balance_eur_cents: wallet.balance_eur_cents,
-            auto_topup_enabled: wallet.auto_topup_enabled,
-            auto_topup_threshold_cents: wallet.auto_topup_threshold_cents,
-            auto_topup_pack_cents: wallet.auto_topup_pack_cents
-          })
-        );
+        return okStructured({
+          org_id: orgId,
+          balance_eur_cents: wallet.balance_eur_cents,
+          auto_topup_enabled: wallet.auto_topup_enabled,
+          auto_topup_threshold_cents: wallet.auto_topup_threshold_cents,
+          auto_topup_pack_cents: wallet.auto_topup_pack_cents
+        });
       } catch (e) {
         if (e instanceof WalletClientError) return err(`Wallet error: ${e.message}`);
         Sentry2.captureException(e);
@@ -6984,6 +7033,31 @@ function registerWalletTools(server2, ctx) {
           "Pack id (pack_500/pack_1000/pack_2500/pack_5000) or exact EUR-cents amount. Omit to list packs."
         )
       },
+      /**
+       * This tool really does return two different shapes, so the schema says
+       * so rather than pretending otherwise. `pack` omitted returns the
+       * catalogue arm (`packs`); `pack` supplied returns the session arm. An
+       * `outputSchema` is an object shape, not a union type, so the two arms
+       * are expressed as mutually exclusive optional groups and the pairing is
+       * documented here. Marking either arm required would break the other.
+       */
+      outputSchema: {
+        packs: z7.array(
+          z7.object({
+            id: z7.string(),
+            eur_cents: z7.number().int(),
+            bonus_pct: z7.number(),
+            bonus_eur_cents: z7.number().int(),
+            credited_eur_cents: z7.number().int()
+          })
+        ).optional().describe("Catalogue arm \u2014 present only when `pack` was omitted."),
+        org_id: z7.string().optional().describe("Session arm."),
+        pack_id: z7.string().optional().describe("Session arm."),
+        pack_eur_cents: z7.number().int().optional().describe("Session arm."),
+        bonus_eur_cents: z7.number().int().optional().describe("Session arm."),
+        checkout_session_id: z7.string().optional().describe("Session arm."),
+        checkout_url: z7.string().nullable().optional().describe("Session arm. Stripe may return null for a session URL.")
+      },
       annotations: annotationsFor("wallet_topup_checkout", "write")
     },
     async ({ pack }) => {
@@ -6992,17 +7066,15 @@ function registerWalletTools(server2, ctx) {
       const orgId = defaultOrgId;
       const start = Date.now();
       if (!pack) {
-        return ok(
-          JSON.stringify({
-            packs: PACKS.map((p) => ({
-              id: p.id,
-              eur_cents: p.eurCents,
-              bonus_pct: p.bonusPct,
-              bonus_eur_cents: bonusCentsFor(p),
-              credited_eur_cents: p.eurCents + bonusCentsFor(p)
-            }))
-          })
-        );
+        return okStructured({
+          packs: PACKS.map((p) => ({
+            id: p.id,
+            eur_cents: p.eurCents,
+            bonus_pct: p.bonusPct,
+            bonus_eur_cents: bonusCentsFor(p),
+            credited_eur_cents: p.eurCents + bonusCentsFor(p)
+          }))
+        });
       }
       const selected = resolvePack(pack);
       if (!selected) {
@@ -7021,16 +7093,14 @@ function registerWalletTools(server2, ctx) {
           sub: props2.sub,
           reseller_id: props2.reseller_id
         });
-        return ok(
-          JSON.stringify({
-            org_id: orgId,
-            pack_id: selected.id,
-            pack_eur_cents: selected.eurCents,
-            bonus_eur_cents: bonusCentsFor(selected),
-            checkout_session_id: session.id,
-            checkout_url: session.url
-          })
-        );
+        return okStructured({
+          org_id: orgId,
+          pack_id: selected.id,
+          pack_eur_cents: selected.eurCents,
+          bonus_eur_cents: bonusCentsFor(selected),
+          checkout_session_id: session.id,
+          checkout_url: session.url
+        });
       } catch (e) {
         Sentry2.captureException(e);
         return err(`Error: ${e instanceof Error ? e.message : "unknown"}`);
@@ -7045,6 +7115,26 @@ function registerWalletTools(server2, ctx) {
       inputSchema: {
         pack_cents: z7.number().int().positive().optional().describe("Override pack amount in EUR cents (must match a catalog pack).")
       },
+      /**
+       * Only the charged arm is described here — `charged: false` returns
+       * through `err()`, and the SDK skips output validation on an `isError`
+       * result.
+       *
+       * `balance_after_cents` is optional and the description above is wrong to
+       * promise it. runAutoTopup has a second success arm (wallet-tools.ts:337)
+       * where the card was charged but crediting Atlas failed: it carries
+       * `paymentIntentId` and a `reason`, and no balance. Requiring the field
+       * would turn that arm — a real charge the caller must be told about —
+       * into a validation error.
+       */
+      outputSchema: {
+        org_id: z7.string(),
+        charged: z7.literal(true),
+        credited_eur_cents: z7.number().int(),
+        balance_after_cents: z7.number().int().optional().describe("Absent when the charge succeeded but crediting is pending."),
+        payment_intent_id: z7.string().optional(),
+        note: z7.string().optional().describe("Present when the charge landed but the credit is still pending.")
+      },
       annotations: annotationsFor("wallet_auto_topup", "write")
     },
     async ({ pack_cents }) => {
@@ -7068,16 +7158,18 @@ function registerWalletTools(server2, ctx) {
             JSON.stringify({ org_id: orgId, charged: false, reason: result2.reason })
           );
         }
-        return ok(
-          JSON.stringify({
-            org_id: orgId,
-            charged: true,
-            credited_eur_cents: result2.creditedCents,
-            balance_after_cents: result2.balanceAfterCents,
-            payment_intent_id: result2.paymentIntentId,
-            ...result2.reason ? { note: result2.reason } : {}
-          })
-        );
+        return okStructured({
+          org_id: orgId,
+          charged: true,
+          credited_eur_cents: result2.creditedCents,
+          // Spread rather than assign, so the key is absent instead of set to
+          // `undefined`. JSON.stringify drops an undefined value anyway, so
+          // assigning it would make `content` and `structuredContent` disagree
+          // about whether the field is there.
+          ...result2.balanceAfterCents !== void 0 ? { balance_after_cents: result2.balanceAfterCents } : {},
+          ...result2.paymentIntentId !== void 0 ? { payment_intent_id: result2.paymentIntentId } : {},
+          ...result2.reason ? { note: result2.reason } : {}
+        });
       } catch (e) {
         Sentry2.captureException(e);
         return err(`Error: ${e instanceof Error ? e.message : "unknown"}`);
@@ -7103,25 +7195,30 @@ async function issueConfirmToken(env, sub, toolName) {
   await env.OAUTH_KV.put(key, token2, { expirationTtl: 300 });
   return token2;
 }
-function ok2(text) {
+function ok(text) {
   return { content: [{ type: "text", text }] };
 }
 function err2(text) {
   return { isError: true, content: [{ type: "text", text }] };
 }
 async function stripeGet(stripeKey, path, connectedAccountId) {
-  const headers = { Authorization: `Bearer ${stripeKey}` };
+  const headers = {
+    Authorization: `Bearer ${stripeKey}`,
+    "Stripe-Version": "2025-08-27.basil"
+  };
   if (connectedAccountId) headers["Stripe-Account"] = connectedAccountId;
   const res = await fetch(`https://api.stripe.com${path}`, { headers });
   const data = await res.json();
   return { ok: res.ok, status: res.status, data };
 }
-async function stripePost(stripeKey, path, params, connectedAccountId) {
+async function stripePost(stripeKey, path, params, connectedAccountId, idempotencyKey) {
   const headers = {
     Authorization: `Bearer ${stripeKey}`,
+    "Stripe-Version": "2025-08-27.basil",
     "Content-Type": "application/x-www-form-urlencoded"
   };
   if (connectedAccountId) headers["Stripe-Account"] = connectedAccountId;
+  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
   const res = await fetch(`https://api.stripe.com${path}`, {
     method: "POST",
     headers,
@@ -7130,6 +7227,9 @@ async function stripePost(stripeKey, path, params, connectedAccountId) {
   const data = await res.json();
   return { ok: res.ok, status: res.status, data };
 }
+function refundIdempotencyKey(sub, charge, amount, reason) {
+  return `carrier-refund:${sub}:${charge}:${amount ?? "full"}:${reason ?? "none"}`;
+}
 var STRIPE_CONNECT_TOOL_SCOPES = {
   stripe_connect_status: "read",
   stripe_connect_payouts: "read",
@@ -7177,7 +7277,7 @@ function registerStripeConnectTools(server2, ctx) {
         if (!stripeKey) return err2("Stripe not configured");
         const accountId = await env.CARRIER_USERS.get(opKvKey);
         if (!accountId) {
-          return ok2(JSON.stringify({ status: "not_connected", operator_id: opId }));
+          return ok(JSON.stringify({ status: "not_connected", operator_id: opId }));
         }
         const result2 = await stripeGet(stripeKey, `/v1/accounts/${accountId}`);
         if (!result2.ok) return err2(`Stripe error: ${JSON.stringify(result2.data)}`);
@@ -7192,7 +7292,7 @@ function registerStripeConnectTools(server2, ctx) {
           sub: props2.sub,
           reseller_id: props2.reseller_id
         });
-        return ok2(JSON.stringify({
+        return ok(JSON.stringify({
           status,
           operator_id: opId,
           account_id: accountId,
@@ -7243,7 +7343,7 @@ function registerStripeConnectTools(server2, ctx) {
           sub: props2.sub,
           reseller_id: props2.reseller_id
         });
-        return ok2(JSON.stringify({ payouts: result2.data.data, has_more: result2.data.has_more }));
+        return ok(JSON.stringify({ payouts: result2.data.data, has_more: result2.data.has_more }));
       } catch (e) {
         Sentry3.captureException(e);
         return err2(`Error: ${e instanceof Error ? e.message : "unknown"}`);
@@ -7278,7 +7378,7 @@ function registerStripeConnectTools(server2, ctx) {
           sub: props2.sub,
           reseller_id: props2.reseller_id
         });
-        return ok2(JSON.stringify({
+        return ok(JSON.stringify({
           account_id: accountId,
           available: result2.data.available ?? [],
           pending: result2.data.pending ?? []
@@ -7309,7 +7409,7 @@ function registerStripeConnectTools(server2, ctx) {
       const toolName = "stripe_connect_refund";
       if (!confirm_token) {
         const token2 = await issueConfirmToken(env, props2.sub, toolName);
-        return ok2(
+        return ok(
           `HARD_BLOCK: Refund ${amount_cents ? `${amount_cents} cents on` : "(full) on"} charge ${charge_id} requires confirmation.
 confirm_token: ${token2}
 Call again with confirm_token="${token2}" to execute. Token expires in 5 minutes.`
@@ -7327,7 +7427,13 @@ Call again with confirm_token="${token2}" to execute. Token expires in 5 minutes
         const params = { charge: charge_id };
         if (amount_cents) params.amount = String(amount_cents);
         if (reason) params.reason = reason;
-        const result2 = await stripePost(stripeKey, "/v1/refunds", params, accountId);
+        const result2 = await stripePost(
+          stripeKey,
+          "/v1/refunds",
+          params,
+          accountId,
+          refundIdempotencyKey(props2.sub, charge_id, amount_cents, reason)
+        );
         if (!result2.ok) return err2(`Stripe error: ${JSON.stringify(result2.data)}`);
         writeAudit(env, {
           tool_name: toolName,
@@ -7338,7 +7444,7 @@ Call again with confirm_token="${token2}" to execute. Token expires in 5 minutes
           sub: props2.sub,
           reseller_id: props2.reseller_id
         });
-        return ok2(`Refund issued: ${result2.data.id} \u2014 status: ${result2.data.status}`);
+        return ok(`Refund issued: ${result2.data.id} \u2014 status: ${result2.data.status}`);
       } catch (e) {
         Sentry3.captureException(e);
         return err2(`Error: ${e instanceof Error ? e.message : "unknown"}`);
@@ -7378,7 +7484,7 @@ Call again with confirm_token="${token2}" to execute. Token expires in 5 minutes
           sub: props2.sub,
           reseller_id: props2.reseller_id
         });
-        return ok2(JSON.stringify({ disputes: result2.data.data, has_more: result2.data.has_more }));
+        return ok(JSON.stringify({ disputes: result2.data.data, has_more: result2.data.has_more }));
       } catch (e) {
         Sentry3.captureException(e);
         return err2(`Error: ${e instanceof Error ? e.message : "unknown"}`);
@@ -7421,7 +7527,7 @@ Call again with confirm_token="${token2}" to execute. Token expires in 5 minutes
           sub: props2.sub,
           reseller_id: props2.reseller_id
         });
-        return ok2(JSON.stringify({ reviews: result2.data.data, has_more: result2.data.has_more }));
+        return ok(JSON.stringify({ reviews: result2.data.data, has_more: result2.data.has_more }));
       } catch (e) {
         Sentry3.captureException(e);
         return err2(`Error: ${e instanceof Error ? e.message : "unknown"}`);
@@ -7451,7 +7557,7 @@ Call again with confirm_token="${token2}" to execute. Token expires in 5 minutes
       const start = Date.now();
       if (!confirm_token) {
         const token2 = await issueConfirmToken(env, props2.sub, toolName);
-        return ok2(
+        return ok(
           `HARD_BLOCK: Approving review ${review_id} allows the charge to proceed.
 confirm_token: ${token2}
 Call again with confirm_token="${token2}" to execute. Expires in 5 minutes.`
@@ -7477,7 +7583,7 @@ Call again with confirm_token="${token2}" to execute. Expires in 5 minutes.`
           sub: props2.sub,
           reseller_id: props2.reseller_id
         });
-        return ok2(`Review ${review_id} approved. Charge will proceed.`);
+        return ok(`Review ${review_id} approved. Charge will proceed.`);
       } catch (e) {
         Sentry3.captureException(e);
         return err2(`Error: ${e instanceof Error ? e.message : "unknown"}`);
@@ -7507,7 +7613,7 @@ Call again with confirm_token="${token2}" to execute. Expires in 5 minutes.`
       const start = Date.now();
       if (!confirm_token) {
         const token2 = await issueConfirmToken(env, props2.sub, toolName);
-        return ok2(
+        return ok(
           `HARD_BLOCK: Declining review ${review_id} will close/block the charge.
 confirm_token: ${token2}
 Expires in 5 minutes.`
@@ -7533,7 +7639,7 @@ Expires in 5 minutes.`
           sub: props2.sub,
           reseller_id: props2.reseller_id
         });
-        return ok2(`Review ${review_id} declined.`);
+        return ok(`Review ${review_id} declined.`);
       } catch (e) {
         Sentry3.captureException(e);
         return err2(`Error: ${e instanceof Error ? e.message : "unknown"}`);
@@ -7564,7 +7670,7 @@ Expires in 5 minutes.`
       const start = Date.now();
       if (!confirm_token) {
         const token2 = await issueConfirmToken(env, props2.sub, toolName);
-        return ok2(
+        return ok(
           `HARD_BLOCK: Adding "${value}" to list ${value_list_id} will affect future charge decisions.
 confirm_token: ${token2}
 Expires in 5 minutes.`
@@ -7590,7 +7696,7 @@ Expires in 5 minutes.`
           sub: props2.sub,
           reseller_id: props2.reseller_id
         });
-        return ok2(`Added "${value}" to Radar list ${value_list_id}.`);
+        return ok(`Added "${value}" to Radar list ${value_list_id}.`);
       } catch (e) {
         Sentry3.captureException(e);
         return err2(`Error: ${e instanceof Error ? e.message : "unknown"}`);
@@ -7616,7 +7722,7 @@ Expires in 5 minutes.`
           "This tool acts on Carrier's platform Stripe account and is restricted to Carrier's own organization."
         );
       }
-      return ok2(
+      return ok(
         `Stripe Radar does not expose rule enable/disable via the public API.
 To ${enabled ? "enable" : "disable"} rule ${rule_id}:
 1. Open https://dashboard.stripe.com/radar/rules
@@ -7633,9 +7739,9 @@ import { z as z9 } from "zod";
 var STOREFRONT_LOGO_TOOL_SCOPES = {
   generate_storefront_logo: "read"
 };
-var ok3 = (text) => ({ content: [{ type: "text", text }] });
+var ok2 = (text) => ({ content: [{ type: "text", text }] });
 var err3 = (text) => ({ isError: true, content: [{ type: "text", text }] });
-function registerStorefrontLogoTools(server2, env = {}) {
+function registerStorefrontLogoTools(server2, env = {}, props2) {
   server2.registerTool(
     "generate_storefront_logo",
     {
@@ -7649,6 +7755,8 @@ function registerStorefrontLogoTools(server2, env = {}) {
       annotations: annotationsFor("generate_storefront_logo", "read")
     },
     async ({ name, accent, tagline }) => {
+      const denied = denyUnlessScoped(props2, "generate_storefront_logo", STOREFRONT_LOGO_TOOL_SCOPES);
+      if (denied) return denied;
       try {
         const hex = accent ? accent.startsWith("#") ? accent : `#${accent}` : void 0;
         const logo = await generateStorefrontLogo({
@@ -7657,7 +7765,7 @@ function registerStorefrontLogoTools(server2, env = {}) {
           tagline,
           env: { ...env, ...process.env }
         });
-        return ok3(
+        return ok2(
           JSON.stringify({
             brand: name,
             source: logo.source,
@@ -7682,11 +7790,11 @@ var STOREFRONT_DEPLOY_TOOL_SCOPES = {
   deploy_storefront: "write",
   provision_storefront_clerk: "write"
 };
-var ok4 = (value) => ({
+var ok3 = (value) => ({
   content: [{ type: "text", text: JSON.stringify(value) }]
 });
 var err4 = (text) => ({ isError: true, content: [{ type: "text", text }] });
-function registerStorefrontDeployTools(server2) {
+function registerStorefrontDeployTools(server2, props2) {
   server2.registerTool(
     "list_deploy_targets",
     {
@@ -7698,10 +7806,12 @@ function registerStorefrontDeployTools(server2) {
       annotations: annotationsFor("list_deploy_targets", "read")
     },
     async ({ dir }) => {
+      const denied = denyUnlessScoped(props2, "list_deploy_targets", STOREFRONT_DEPLOY_TOOL_SCOPES);
+      if (denied) return denied;
       try {
         const statuses = await probeAll(dir);
         const ranked = rankTargets(statuses);
-        return ok4({
+        return ok3({
           targets: statuses,
           default: ranked[0]?.id ?? null,
           reason: ranked.length ? void 0 : "No host is installed and logged in."
@@ -7728,6 +7838,8 @@ function registerStorefrontDeployTools(server2) {
       annotations: annotationsFor("deploy_storefront", "write")
     },
     async ({ dir, target, name, skip_build, push_secrets, verify, domain }) => {
+      const denied = denyUnlessScoped(props2, "deploy_storefront", STOREFRONT_DEPLOY_TOOL_SCOPES);
+      if (denied) return denied;
       try {
         if (target && !isTargetId(target)) return err4(`Unknown target "${target}".`);
         const brand = await loadStorefrontBrand(dir, name ? { name } : void 0);
@@ -7747,7 +7859,7 @@ function registerStorefrontDeployTools(server2) {
           return err4(result2.reason ?? "Deploy failed.");
         }
         const verification = verify !== false && result2.url ? await verifyStorefront(result2.url, dir, process.env) : void 0;
-        return ok4({
+        return ok3({
           deployed: true,
           target: result2.target,
           project: result2.projectName,
@@ -7780,6 +7892,12 @@ function registerStorefrontDeployTools(server2) {
       annotations: annotationsFor("provision_storefront_clerk", "write")
     },
     async ({ dir, name, production, no_create, url }) => {
+      const denied = denyUnlessScoped(
+        props2,
+        "provision_storefront_clerk",
+        STOREFRONT_DEPLOY_TOOL_SCOPES
+      );
+      if (denied) return denied;
       try {
         const brand = await loadStorefrontBrand(dir, name ? { name } : void 0);
         const result2 = await provisionClerk({
@@ -7792,7 +7910,7 @@ function registerStorefrontDeployTools(server2) {
           cli: clerkCliDeps()
         });
         if (!result2.ok || !result2.credentials) {
-          return ok4({
+          return ok3({
             provisioned: false,
             tier: result2.tier,
             reason: result2.reason,
@@ -7808,7 +7926,7 @@ function registerStorefrontDeployTools(server2) {
           allowedOrigins,
           redirectUrls
         });
-        return ok4({
+        return ok3({
           provisioned: true,
           tier: result2.tier,
           application_id: result2.credentials.applicationId ?? null,
@@ -10415,7 +10533,7 @@ function registerRateLimitStatusTool(server2, ctx) {
 
 // src/tools-depletion-events.ts
 import { z as z14 } from "zod";
-function ok5(payload) {
+function ok4(payload) {
   return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
 }
 function err5(message) {
@@ -10475,7 +10593,7 @@ function registerDepletionEventsTool(server2, ctx) {
       if (subscriberId) {
         const raw = await kv.get(`bundle-depleted:${subscriberId}`, "text");
         if (!raw) {
-          return ok5({
+          return ok4({
             subscriber_id: subscriberId,
             depleted: false,
             event: null,
@@ -10486,7 +10604,7 @@ function registerDepletionEventsTool(server2, ctx) {
         try {
           event = JSON.parse(raw);
         } catch {
-          return ok5({
+          return ok4({
             subscriber_id: subscriberId,
             depleted: false,
             event: null,
@@ -10494,7 +10612,7 @@ function registerDepletionEventsTool(server2, ctx) {
           });
         }
         if (!await ownsEvent(ctx, scopeToken, event.iccid)) {
-          return ok5({
+          return ok4({
             subscriber_id: subscriberId,
             depleted: false,
             event: null,
@@ -10502,14 +10620,14 @@ function registerDepletionEventsTool(server2, ctx) {
           });
         }
         if (since && event.depletedAt < since) {
-          return ok5({
+          return ok4({
             subscriber_id: subscriberId,
             depleted: false,
             event: null,
             note: `No bundle depletion after ${since}.`
           });
         }
-        return ok5({
+        return ok4({
           subscriber_id: subscriberId,
           depleted: true,
           event: {
@@ -10523,7 +10641,7 @@ function registerDepletionEventsTool(server2, ctx) {
       }
       const listResult = await kv.list({ prefix: "bundle-depleted:", limit: 20 });
       if (listResult.keys.length === 0) {
-        return ok5({
+        return ok4({
           depletions: [],
           total: 0,
           note: "No bundle depletion events in the last 7 days."
@@ -10550,7 +10668,7 @@ function registerDepletionEventsTool(server2, ctx) {
         })
       );
       events.sort((a, b) => b.depleted_at.localeCompare(a.depleted_at));
-      return ok5({
+      return ok4({
         depletions: events,
         total: events.length,
         list_truncated: !listResult.list_complete
@@ -11926,7 +12044,7 @@ function resolvePortalBaseUrl(env) {
 function getGreenzoneKv(env) {
   return env.GREENZONE_STATE_KV ?? null;
 }
-function ok6(payload) {
+function ok5(payload) {
   return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
 }
 function err6(message) {
@@ -11962,7 +12080,7 @@ function registerGreenzoneTools(server2, ctx) {
         ...ip ? buildAddIpSteps(portalBaseUrl, ip) : []
       ];
       if (dry_run) {
-        return ok6({
+        return ok5({
           dry_run: true,
           message: "Would execute the following Kapture steps against the OCS portal:",
           kapture_steps: steps,
@@ -11985,7 +12103,7 @@ function registerGreenzoneTools(server2, ctx) {
       } else {
         kvWarning = "GREENZONE_STATE_KV not bound in stdio mode \u2014 state not persisted.";
       }
-      return ok6({
+      return ok5({
         requires_kapture: true,
         message: "Execute the Kapture steps below to apply the change in the OCS portal. " + KAPTURE_UNAVAILABLE_MSG,
         kapture_steps: steps,
@@ -12023,7 +12141,7 @@ function registerGreenzoneTools(server2, ctx) {
         ...ip ? buildRemoveIpSteps(portalBaseUrl, ip) : []
       ];
       if (dry_run) {
-        return ok6({
+        return ok5({
           dry_run: true,
           message: "Would execute the following Kapture steps to remove from OCS portal:",
           kapture_steps: steps,
@@ -12046,7 +12164,7 @@ function registerGreenzoneTools(server2, ctx) {
       } else {
         kvWarning = "GREENZONE_STATE_KV not bound in stdio mode \u2014 state not persisted.";
       }
-      return ok6({
+      return ok5({
         requires_kapture: true,
         message: "Execute the Kapture steps below to apply the removal in the OCS portal. " + KAPTURE_UNAVAILABLE_MSG,
         kapture_steps: steps,
@@ -12077,7 +12195,7 @@ function registerGreenzoneTools(server2, ctx) {
       const { from_portal } = args;
       if (from_portal) {
         const portalBaseUrl = resolvePortalBaseUrl(ctx.env);
-        return ok6({
+        return ok5({
           requires_kapture: true,
           message: "Execute the Kapture steps below to read live Greenzone whitelist state from the OCS portal.",
           kapture_steps: buildListSteps(portalBaseUrl),
@@ -12086,7 +12204,7 @@ function registerGreenzoneTools(server2, ctx) {
       }
       const kv = getGreenzoneKv(ctx.env);
       if (!kv) {
-        return ok6({
+        return ok5({
           source: "kv_cache",
           hosts: [],
           ips: [],
@@ -12098,7 +12216,7 @@ function registerGreenzoneTools(server2, ctx) {
       }
       try {
         const state = await readState(kv);
-        return ok6({
+        return ok5({
           source: "kv_cache",
           hosts: state.hosts,
           ips: state.ips,
@@ -12229,8 +12347,12 @@ registerStripeConnectTools(server, { env: stdioEnv, props });
 registerWalletTools(server, { env: stdioEnv, props });
 registerGreenzoneTools(server, toolCtx);
 registerUiAgentGenericTools(server, toolCtx);
-registerStorefrontLogoTools(server, stdioEnv);
-registerStorefrontDeployTools(server);
+registerStorefrontLogoTools(
+  server,
+  stdioEnv,
+  props
+);
+registerStorefrontDeployTools(server, props);
 registerAllPrompts(server);
 var transport = new StdioServerTransport();
 await server.connect(transport);