@mycadet/gateway 0.12.8 → 0.12.9

package/node_modules/@mycadet/ces-client/node_modules/@mycadet/service-contracts/package.json

@@ -40,6 +40,6 @@
   },
   "devDependencies": {
     "@types/bun": "1.2.4",
-    "typescript": "5.7.3"
+    "typescript": "5.9.3"
   }
 }

package/node_modules/@mycadet/ces-client/package.json

@@ -19,6 +19,6 @@
   },
   "devDependencies": {
     "@types/bun": "1.2.4",
-    "typescript": "5.7.3"
+    "typescript": "5.9.3"
   }
 }

package/node_modules/@mycadet/ces-client/src/__tests__/ces-client.test.ts

@@ -141,7 +141,7 @@ describe("CesHttpCredentialClient", () => {
       Promise.resolve(
         Response.json({ account: "test-acct", value: "secret-123" }),
       ),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -156,7 +156,7 @@ describe("CesHttpCredentialClient", () => {
   test("get returns not-found on 404", async () => {
     globalThis.fetch = mock(() =>
       Promise.resolve(new Response(null, { status: 404 })),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -171,7 +171,7 @@ describe("CesHttpCredentialClient", () => {
   test("get returns unreachable on 500", async () => {
     globalThis.fetch = mock(() =>
       Promise.resolve(new Response("internal error", { status: 500 })),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -186,7 +186,7 @@ describe("CesHttpCredentialClient", () => {
   test("get returns unreachable on network error", async () => {
     globalThis.fetch = mock(() =>
       Promise.reject(new Error("ECONNREFUSED")),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -201,7 +201,7 @@ describe("CesHttpCredentialClient", () => {
   test("delete returns deleted on 200", async () => {
     globalThis.fetch = mock(() =>
       Promise.resolve(Response.json({ ok: true, account: "acct" })),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -215,7 +215,7 @@ describe("CesHttpCredentialClient", () => {
   test("delete returns not-found on 404", async () => {
     globalThis.fetch = mock(() =>
       Promise.resolve(new Response(null, { status: 404 })),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -229,7 +229,7 @@ describe("CesHttpCredentialClient", () => {
   test("delete returns error on network failure", async () => {
     globalThis.fetch = mock(() =>
       Promise.reject(new Error("network down")),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -243,7 +243,7 @@ describe("CesHttpCredentialClient", () => {
   test("list returns accounts on 200", async () => {
     globalThis.fetch = mock(() =>
       Promise.resolve(Response.json({ accounts: ["a", "b", "c"] })),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -258,7 +258,7 @@ describe("CesHttpCredentialClient", () => {
   test("list returns unreachable on error", async () => {
     globalThis.fetch = mock(() =>
       Promise.reject(new Error("timeout")),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -273,7 +273,7 @@ describe("CesHttpCredentialClient", () => {
   test("bulkSet returns all-failed when request fails", async () => {
     globalThis.fetch = mock(() =>
       Promise.reject(new Error("network")),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const client = createCesHttpCredentialClient(
       createTestConfig(),
@@ -311,7 +311,7 @@ describe("fetchCesLogExport", () => {
           headers: { "Content-Type": "application/gzip" },
         }),
       ),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const result = await fetchCesLogExport({
       baseUrl: "http://ces-test:8090",
@@ -327,7 +327,7 @@ describe("fetchCesLogExport", () => {
   test("returns error on non-OK status", async () => {
     globalThis.fetch = mock(() =>
       Promise.resolve(new Response("forbidden", { status: 403 })),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const result = await fetchCesLogExport({
       baseUrl: "http://ces-test:8090",
@@ -343,7 +343,7 @@ describe("fetchCesLogExport", () => {
   test("returns error on network failure", async () => {
     globalThis.fetch = mock(() =>
       Promise.reject(new Error("connection refused")),
-    ) as typeof fetch;
+    ) as unknown as typeof fetch;
 
     const result = await fetchCesLogExport({
       baseUrl: "http://ces-test:8090",
@@ -361,7 +361,7 @@ describe("fetchCesLogExport", () => {
     globalThis.fetch = mock((url: string | URL | Request) => {
       capturedUrl = typeof url === "string" ? url : url.toString();
       return Promise.resolve(new Response(new ArrayBuffer(0), { status: 200 }));
-    }) as typeof fetch;
+    }) as unknown as typeof fetch;
 
     await fetchCesLogExport(
       { baseUrl: "http://ces-test:8090", serviceToken: "tok" },

package/node_modules/@mycadet/gateway-client/node_modules/@mycadet/service-contracts/package.json

@@ -40,6 +40,6 @@
   },
   "devDependencies": {
     "@types/bun": "1.2.4",
-    "typescript": "5.7.3"
+    "typescript": "5.9.3"
   }
 }

package/node_modules/@mycadet/service-contracts/package.json

@@ -40,6 +40,6 @@
   },
   "devDependencies": {
     "@types/bun": "1.2.4",
-    "typescript": "5.7.3"
+    "typescript": "5.9.3"
   }
 }

package/openapi.json

@@ -2,10 +2,10 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Cadet Gateway API",
-    "version": "0.12.6",
+    "version": "0.12.8",
     "description": "Auto-generated OpenAPI specification for the Cadet Gateway HTTP endpoints."
   },
-  "servers": [{ "url": "", "description": "Same-origin (gateway)" }],
+  "servers": [{ "url": "", "description": "Same-origin — the gateway" }],
   "paths": {
     "/v1/permissions/thresholds": {
       "get": {
@@ -105,7 +105,7 @@
         "operationId": "conversationThresholdGet",
         "summary": "Get a conversation's threshold override",
         "tags": ["permissions"],
-        "description": "Returns { threshold: null } when no override exists. (Gateways predating that behavior returned 404 for the same condition; clients tolerate both during rollout.)",
+        "description": "Returns { threshold: null } when no override exists. Gateways predating that behavior returned 404 for the same condition; clients tolerate both during rollout.",
         "parameters": [
           {
             "name": "conversation_id",
@@ -209,7 +209,7 @@
         "operationId": "channelAdmissionPolicyList",
         "summary": "List per-channel admission floors",
         "tags": ["channel-admission-policy"],
-        "description": "Returns one entry per enforced channel (exempt and hidden channels are omitted), seeded with defaults for channels without a stored row.",
+        "description": "Returns one entry per enforced channel, excluding exempt and hidden channels, seeded with defaults for channels without a stored row.",
         "responses": {
           "200": {
             "description": "Successful response",
@@ -272,7 +272,7 @@
             "in": "path",
             "required": true,
             "schema": { "type": "string" },
-            "description": "The channel type (e.g. slack)"
+            "description": "The channel type, e.g. slack"
           }
         ],
         "requestBody": {
@@ -452,7 +452,7 @@
             "in": "path",
             "required": true,
             "schema": { "type": "string" },
-            "description": "The declaring ingress source (today, a plugin name)"
+            "description": "The declaring ingress source, today a plugin name"
           }
         ],
         "requestBody": {
@@ -502,7 +502,7 @@
             "in": "path",
             "required": true,
             "schema": { "type": "string" },
-            "description": "The declaring ingress source (today, a plugin name)"
+            "description": "The declaring ingress source, today a plugin name"
           }
         ],
         "responses": {
@@ -530,7 +530,7 @@
         "operationId": "channelPermissionOverridesList",
         "summary": "List channel-permission matrix cells",
         "tags": ["channel-permission-overrides"],
-        "description": "Returns every persisted cell (cascade selector × contact-type → RiskThreshold). Unset cells fall through the cascade; the list contains only explicit overrides.",
+        "description": "Returns every persisted cell in the cascade selector × contact-type → RiskThreshold map. Unset cells fall through the cascade; the list contains only explicit overrides.",
         "responses": {
           "200": {
             "description": "Successful response",
@@ -854,7 +854,7 @@
         "operationId": "channelPermissionResolve",
         "summary": "Resolve the effective channel-permission threshold",
         "tags": ["channel-permission-overrides"],
-        "description": "Read-only cascade resolution for one coordinate: walks channel → channel_type → adapter → workspace for the given selector keys and contact-type, returning the winning cell's threshold and scope, or null when no cell matches (the caller then falls through to the global thresholds). Same resolver the runtime evaluator uses over IPC.",
+        "description": "Read-only cascade resolution for one coordinate: walks channel → channel_type → adapter → workspace for the given selector keys and contact-type, returning the winning cell's threshold and scope, or null when no cell matches, in which case the caller falls through to the global thresholds. Same resolver the runtime evaluator uses over IPC.",
         "requestBody": {
           "required": true,
           "content": {
@@ -931,7 +931,7 @@
         "operationId": "channelPermissionOverrideDelete",
         "summary": "Delete a channel-permission matrix cell",
         "tags": ["channel-permission-overrides"],
-        "description": "Removes one cell by its composite key (selector × contact-type), letting the next cascade tier up win. Returns whether a cell was removed.",
+        "description": "Removes one cell by its composite key, selector × contact-type, letting the next cascade tier up win. Returns whether a cell was removed.",
         "requestBody": {
           "required": true,
           "content": {
@@ -1027,7 +1027,7 @@
         "operationId": "contactsUpsert",
         "summary": "Create or update a contact",
         "tags": ["contacts"],
-        "description": "Gateway-native contact upsert (dual-writes the gateway ACL store and the assistant info mirror). Matches by id, then by any provided (type, address) channel, else creates.",
+        "description": "Gateway-native contact upsert that dual-writes the gateway ACL store and the assistant info mirror. Matches by id, then by the provided type and address channel, else creates.",
         "requestBody": {
           "required": true,
           "content": {
@@ -1085,7 +1085,7 @@
                         "address": { "type": "string" },
                         "isPrimary": { "type": "boolean" },
                         "externalChatId": {
-                          "description": "Delivery chat id. Omit to preserve the stored value. A legacy explicit null is accepted for compatibility and treated as omitted; clearing is not supported (a stored null is indistinguishable from never-learned, so no consumer could tell a clear from a gap).",
+                          "description": "Delivery chat id. Omit to preserve the stored value. A legacy explicit null is accepted for compatibility and treated as omitted; clearing is not supported: a stored null is indistinguishable from never-learned, so no consumer could tell a clear from a gap.",
                           "type": "string"
                         },
                         "status": { "type": "string" },
@@ -1141,7 +1141,7 @@
                             },
                             { "type": "null" }
                           ],
-                          "description": "Per-contact auto-approve ceiling. Null means unset (inherit cascade)."
+                          "description": "Per-contact auto-approve ceiling. Null means unset, inheriting the cascade."
                         },
                         "assistantMetadata": {
                           "anyOf": [
@@ -1184,7 +1184,7 @@
                               },
                               "externalUserId": {
                                 "type": "string",
-                                "description": "Compat alias for address (older macOS clients)"
+                                "description": "Compat alias for address, for older macOS clients"
                               },
                               "status": {
                                 "anyOf": [
@@ -1479,7 +1479,7 @@
         "operationId": "contactChannelVerify",
         "summary": "Manually verify a contact channel",
         "tags": ["contacts"],
-        "description": "Guardian-only manual attestation: marks the channel active/verified in the gateway store (source of truth) with a best-effort assistant mirror. Idempotent.",
+        "description": "Guardian-only manual attestation: marks the channel active/verified in the gateway store, the source of truth, with a best-effort assistant mirror. Idempotent.",
         "parameters": [
           {
             "name": "channel_id",
@@ -1828,7 +1828,7 @@
             "in": "query",
             "required": false,
             "schema": { "type": "string" },
-            "description": "Filter by origin (default | user_defined)"
+            "description": "Filter by origin: default or user_defined"
           },
           {
             "name": "tool",
@@ -1929,7 +1929,7 @@
                   },
                   "description": { "type": "string", "minLength": 1 },
                   "scope": {
-                    "description": "Compatibility field. Trust rules apply workspace-wide: the engine matches on (tool, pattern) only, so a narrower scope cannot be honored and any value other than \"everywhere\" is rejected rather than stored broader than the consent it records.",
+                    "description": "Compatibility field. Trust rules apply workspace-wide: the engine matches on tool and pattern only, so a narrower scope cannot be honored and any value other than \"everywhere\" is rejected rather than stored broader than the consent it records.",
                     "type": "string",
                     "const": "everywhere"
                   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mycadet/gateway",
-  "version": "0.12.8",
+  "version": "0.12.9",
   "license": "MIT",
   "type": "module",
   "exports": {

package/scripts/generate-openapi.ts

@@ -126,7 +126,7 @@ function buildSpec(version: string) {
       description:
         "Auto-generated OpenAPI specification for the Cadet Gateway HTTP endpoints.",
     },
-    servers: [{ url: "", description: "Same-origin (gateway)" }],
+    servers: [{ url: "", description: "Same-origin — the gateway" }],
     paths,
   });
 }

package/src/auth/guardian-bootstrap.ts

@@ -41,6 +41,7 @@ import {
 import { CURRENT_POLICY_EPOCH } from "./policy.js";
 import { mintToken } from "./token-service.js";
 import type { ScopeProfile } from "./types.js";
+import { getIsCloud } from "../cloud-url.js";
 
 const log = getLogger("guardian-bootstrap");
 
@@ -1046,9 +1047,7 @@ async function fetchPlatformOwnerDisplayName(): Promise<string | null> {
     return null;
   }
 
-  const isCloud =
-    process.env.IS_CLOUD?.trim().toLowerCase() === "true" ||
-    process.env.IS_CLOUD?.trim() === "1";
+  const isCloud = getIsCloud();
   if (!isCloud) return null;
 
   const assistantApiKey = await readCredential(

package/src/cli/contacts.ts

@@ -204,7 +204,9 @@ export async function executeContactsCommand(
       );
     }
     console.log("");
-    console.log(`${contacts.length} contact(s)`);
+    console.log(
+      `${contacts.length} ${contacts.length === 1 ? "contact" : "contacts"}`,
+    );
     return 0;
   }
 

package/src/cli/index.ts

@@ -15,7 +15,7 @@ function printUsage(): void {
   console.log("Operator commands for gateway-owned state.");
   console.log("");
   console.log("Commands:");
-  console.log("  contacts    Manage contact ACL (list, get, set-risk-threshold)");
+  console.log("  contacts    Manage the contact ACL with list, get, set-risk-threshold");
 }
 
 const args = process.argv.slice(2);

package/src/cloud-url.ts

@@ -6,9 +6,20 @@
  * can safely append path segments.
  */
 export function getCloudBaseUrl(): string {
-  const url = (process.env.CADET_CLOUD_URL?.trim() || "").replace(
-    /\/+$/,
-    "",
-  );
+  const url = (process.env.CADET_CLOUD_URL?.trim() || "").replace(/\/+$/, "");
   return url || "https://cloud.mycadet.ai";
 }
+
+function str(name: string): string | undefined {
+  const v = process.env[name]?.trim();
+  return v || undefined;
+}
+
+function flag(name: string): boolean {
+  const raw = str(name)?.toLowerCase();
+  return raw === "true" || raw === "1";
+}
+
+export function getIsCloud(): boolean {
+  return flag("IS_CLOUD");
+}

package/src/http/routes/auto-approve-thresholds-routes.ts

@@ -55,7 +55,7 @@ export const ROUTES: GatewayRouteDefinition[] = [
     operationId: "conversationThresholdGet",
     summary: "Get a conversation's threshold override",
     description:
-      "Returns { threshold: null } when no override exists. (Gateways predating that behavior returned 404 for the same condition; clients tolerate both during rollout.)",
+      "Returns { threshold: null } when no override exists. Gateways predating that behavior returned 404 for the same condition; clients tolerate both during rollout.",
     tags: ["permissions"],
     pathParameters: [
       { name: "conversation_id", description: "The conversation id" },

package/src/http/routes/channel-admission-policy-routes.ts

@@ -44,7 +44,7 @@ export const ROUTES: GatewayRouteDefinition[] = [
     operationId: "channelAdmissionPolicyList",
     summary: "List per-channel admission floors",
     description:
-      "Returns one entry per enforced channel (exempt and hidden channels are omitted), seeded with defaults for channels without a stored row.",
+      "Returns one entry per enforced channel, excluding exempt and hidden channels, seeded with defaults for channels without a stored row.",
     tags: ["channel-admission-policy"],
     responseBody: z.object({
       policies: z.array(ChannelPolicyViewSchema),
@@ -59,7 +59,7 @@ export const ROUTES: GatewayRouteDefinition[] = [
       "Upserts the channel's admission policy. Exempt and hidden channels return 403.",
     tags: ["channel-admission-policy"],
     pathParameters: [
-      { name: "channel_type", description: "The channel type (e.g. slack)" },
+      { name: "channel_type", description: "The channel type, e.g. slack" },
     ],
     requestBody: SetChannelPolicyRequestSchema,
     responseBody: z.object({ policy: ChannelPolicyViewSchema }),

package/src/http/routes/channel-ingress-routes.ts

@@ -110,7 +110,7 @@ export const ROUTES: GatewayRouteDefinition[] = [
     pathParameters: [
       {
         name: "source",
-        description: "The declaring ingress source (today, a plugin name)",
+        description: "The declaring ingress source, today a plugin name",
       },
     ],
     requestBody: ApproveChannelIngressRequestSchema,
@@ -127,7 +127,7 @@ export const ROUTES: GatewayRouteDefinition[] = [
     pathParameters: [
       {
         name: "source",
-        description: "The declaring ingress source (today, a plugin name)",
+        description: "The declaring ingress source, today a plugin name",
       },
     ],
     responseBody: z.object({ source: z.string(), revoked: z.boolean() }),

package/src/http/routes/channel-permission-overrides-routes.ts

@@ -43,7 +43,7 @@ export const ROUTES: GatewayRouteDefinition[] = [
     operationId: "channelPermissionOverridesList",
     summary: "List channel-permission matrix cells",
     description:
-      "Returns every persisted cell (cascade selector × contact-type → RiskThreshold). Unset cells fall through the cascade; the list contains only explicit overrides.",
+      "Returns every persisted cell in the cascade selector × contact-type → RiskThreshold map. Unset cells fall through the cascade; the list contains only explicit overrides.",
     tags: ["channel-permission-overrides"],
     responseBody: z.object({
       cells: z.array(ChannelPermissionCellRowSchema),
@@ -66,7 +66,7 @@ export const ROUTES: GatewayRouteDefinition[] = [
     operationId: "channelPermissionResolve",
     summary: "Resolve the effective channel-permission threshold",
     description:
-      "Read-only cascade resolution for one coordinate: walks channel → channel_type → adapter → workspace for the given selector keys and contact-type, returning the winning cell's threshold and scope, or null when no cell matches (the caller then falls through to the global thresholds). Same resolver the runtime evaluator uses over IPC.",
+      "Read-only cascade resolution for one coordinate: walks channel → channel_type → adapter → workspace for the given selector keys and contact-type, returning the winning cell's threshold and scope, or null when no cell matches, in which case the caller falls through to the global thresholds. Same resolver the runtime evaluator uses over IPC.",
     tags: ["channel-permission-overrides"],
     requestBody: ResolveChannelPermissionRequestSchema,
     responseBody: z.object({
@@ -84,7 +84,7 @@ export const ROUTES: GatewayRouteDefinition[] = [
     operationId: "channelPermissionOverrideDelete",
     summary: "Delete a channel-permission matrix cell",
     description:
-      "Removes one cell by its composite key (selector × contact-type), letting the next cascade tier up win. Returns whether a cell was removed.",
+      "Removes one cell by its composite key, selector × contact-type, letting the next cascade tier up win. Returns whether a cell was removed.",
     tags: ["channel-permission-overrides"],
     requestBody: ChannelPermissionCellKeySchema,
     responseBody: z.object({ removed: z.boolean() }),

package/src/http/routes/channel-verification-session-proxy.ts

@@ -19,6 +19,7 @@ import { getLogger } from "../../logger.js";
 import { isLoopbackAddress } from "../../util/is-loopback-address.js";
 import { TUNNEL_FORWARDED_HEADER } from "../../tunnel/bridge-utils.js";
 import { requestArrivedViaEdgeProxy } from "../edge-forwarded-header.js";
+import { getIsCloud } from "../../cloud-url.js";
 
 const log = getLogger("channel-verification-session-proxy");
 
@@ -190,15 +191,8 @@ export function createChannelVerificationSessionProxyHandler(
       // Auth model for /v1/guardian/init — three deployment modes
       // ─────────────────────────────────────────────────────────────────────
       //
-      // 1. Platform-managed (IS_CLOUD=true, pod in vembda):
-      //    Auth is enforced UPSTREAM by vembda's /gateway-query proxy before
-      //    a request ever reaches this gateway pod. The pod is not directly
-      //    reachable from the public internet — only vembda's authenticated
-      //    proxy can route to it. GUARDIAN_BOOTSTRAP_SECRET is intentionally
-      //    NOT provisioned in managed deployments (no Helm chart, vembda
-      //    StatefulSet env, or k8s_resources.py provisions it) and there is
-      //    no plan to add it. The bootstrap-secret mechanism is a laptop /
-      //    Docker hatch artifact only.
+      // 1. Cadet Cloud:
+      //    Auth is enforced UPSTREAM before a request ever reaches this gateway
       //
       // 2. Docker / laptop hatch (GUARDIAN_BOOTSTRAP_SECRET set):
       //    The CLI's hatch.ts mints a bootstrap secret and forwards it into
@@ -209,15 +203,7 @@ export function createChannelVerificationSessionProxyHandler(
       //    The lockfile + loopback guard is the sole defense — see below.
       //    Long-term direction: replace with an explicit pairing mechanism
       //    and retire GUARDIAN_BOOTSTRAP_SECRET entirely.
-      //
-      // NOTE TO SCANNERS / Codex: managed mode reaching this handler with no
-      // bootstrap secret is the EXPECTED state in production. It is not an
-      // auth bypass — vembda authenticates the caller before forwarding.
-      // Adding a fail-closed guard here on `IS_CLOUD=true && !secret`
-      // would brick every platform deployment.
-      const isCloud =
-        process.env.IS_CLOUD?.trim().toLowerCase() === "true" ||
-        process.env.IS_CLOUD?.trim() === "1";
+      const isCloud = getIsCloud();
 
       // Bare-metal mode: restrict to loopback callers only. Without a
       // bootstrap secret the lockfile is the sole guard, so a remote

package/src/http/routes/contacts-control-plane-proxy.ts

@@ -364,7 +364,7 @@ export async function createInviteNative(
     }
     if (!isValidE164(input.expectedExternalUserId)) {
       throw new InviteNativeError(
-        "expectedExternalUserId must be in E.164 format (e.g., +15551234567)",
+        "expectedExternalUserId must be in E.164 format, e.g. +15551234567",
         400,
         "BAD_REQUEST",
       );

package/src/http/routes/contacts-control-plane-routes.ts

@@ -36,7 +36,7 @@ const ContactChannelPayloadSchema = z.object({
   externalChatId: z.string().nullable(),
   externalUserId: z
     .string()
-    .describe("Compat alias for address (older macOS clients)"),
+    .describe("Compat alias for address, for older macOS clients"),
   status: z.string().nullable(),
   policy: z.string().nullable(),
   verifiedAt: z.number().nullable(),
@@ -69,7 +69,7 @@ const ContactPayloadSchema = z.object({
   interactionCount: z.number(),
   lastInteraction: z.number().nullable(),
   autoApproveThreshold: RiskThresholdSchema.nullable().describe(
-    "Per-contact auto-approve ceiling. Null means unset (inherit cascade).",
+    "Per-contact auto-approve ceiling. Null means unset, inheriting the cascade.",
   ),
   assistantMetadata: AssistantContactMetadataSchema.nullable(),
   channels: z.array(ContactChannelPayloadSchema),
@@ -92,7 +92,7 @@ const UpsertContactChannelInputSchema = z.object({
     .string()
     .optional()
     .describe(
-      "Delivery chat id. Omit to preserve the stored value. A legacy explicit null is accepted for compatibility and treated as omitted; clearing is not supported (a stored null is indistinguishable from never-learned, so no consumer could tell a clear from a gap).",
+      "Delivery chat id. Omit to preserve the stored value. A legacy explicit null is accepted for compatibility and treated as omitted; clearing is not supported: a stored null is indistinguishable from never-learned, so no consumer could tell a clear from a gap.",
     ),
   status: z.string().optional(),
   policy: z.string().optional(),
@@ -200,7 +200,7 @@ export const ROUTES: GatewayRouteDefinition[] = [
     operationId: "contactsUpsert",
     summary: "Create or update a contact",
     description:
-      "Gateway-native contact upsert (dual-writes the gateway ACL store and the assistant info mirror). Matches by id, then by any provided (type, address) channel, else creates.",
+      "Gateway-native contact upsert that dual-writes the gateway ACL store and the assistant info mirror. Matches by id, then by the provided type and address channel, else creates.",
     tags: ["contacts"],
     requestBody: UpsertContactRequestSchema,
     responseBody: z.object({
@@ -265,7 +265,7 @@ export const ROUTES: GatewayRouteDefinition[] = [
     operationId: "contactChannelVerify",
     summary: "Manually verify a contact channel",
     description:
-      "Guardian-only manual attestation: marks the channel active/verified in the gateway store (source of truth) with a best-effort assistant mirror. Idempotent.",
+      "Guardian-only manual attestation: marks the channel active/verified in the gateway store, the source of truth, with a best-effort assistant mirror. Idempotent.",
     tags: ["contacts"],
     pathParameters: [
       { name: "channel_id", description: "The contact-channel id" },

package/src/http/routes/feature-flags.ts

@@ -126,7 +126,7 @@ export function createFeatureFlagsPatchHandler(onFlagChanged?: () => void) {
       return Response.json(
         {
           error:
-            "Invalid flag key format. Must be a simple kebab-case string (e.g., 'browser', 'contacts')",
+            "Invalid flag key format. Must be a simple kebab-case string, e.g. 'browser' or 'contacts'",
         },
         { status: 400 },
       );

package/src/http/routes/trust-rules-routes.ts

@@ -47,7 +47,7 @@ const CreateTrustRuleRequestSchema = z.object({
     .literal("everywhere")
     .optional()
     .describe(
-      'Compatibility field. Trust rules apply workspace-wide: the engine matches on (tool, pattern) only, so a narrower scope cannot be honored and any value other than "everywhere" is rejected rather than stored broader than the consent it records.',
+      'Compatibility field. Trust rules apply workspace-wide: the engine matches on tool and pattern only, so a narrower scope cannot be honored and any value other than "everywhere" is rejected rather than stored broader than the consent it records.',
     ),
 });
 
@@ -116,7 +116,7 @@ export const ROUTES: GatewayRouteDefinition[] = [
     queryParameters: [
       {
         name: "origin",
-        description: "Filter by origin (default | user_defined)",
+        description: "Filter by origin: default or user_defined",
       },
       { name: "tool", description: "Filter by tool name" },
       {

package/src/remote-feature-flag-sync.ts

@@ -423,7 +423,7 @@ export class RemoteFeatureFlagSync {
       if (value === false && registry[key]?.defaultEnabled === true) {
         log.debug(
           { key },
-          "Normalizing remote false for GA flag to true (defaultEnabled: true)",
+          "Normalizing remote false for GA flag to true — defaultEnabled is true",
         );
         values[key] = true;
         continue;

package/src/schema.ts

@@ -302,7 +302,7 @@ export function buildSchema(): Record<string, unknown> {
               },
             },
             "405": {
-              description: "Method not allowed (only POST accepted)",
+              description: "Method not allowed, only POST accepted",
               content: {
                 "application/json": {
                   schema: { $ref: "#/components/schemas/ErrorResponse" },
@@ -368,7 +368,7 @@ export function buildSchema(): Record<string, unknown> {
               },
             },
             "405": {
-              description: "Method not allowed (only POST accepted)",
+              description: "Method not allowed, only POST accepted",
               content: {
                 "application/json": {
                   schema: { $ref: "#/components/schemas/ErrorResponse" },
@@ -822,7 +822,7 @@ export function buildSchema(): Record<string, unknown> {
               "application/json": {
                 schema: {
                   type: "object",
-                  description: "Mailgun webhook payload (JSON).",
+                  description: "Mailgun webhook payload as JSON.",
                 },
               },
             },
@@ -945,7 +945,7 @@ export function buildSchema(): Record<string, unknown> {
         get: {
           summary: "Twilio Media Stream WebSocket",
           description:
-            "Accepts a WebSocket upgrade from Twilio Media Streams and bidirectionally proxies frames to the assistant runtime's /v1/calls/media-stream endpoint. Handshake metadata (callSessionId and auth token) is carried in URL path segments (e.g. /webhooks/twilio/media-stream/<callSessionId>/<token>) because Twilio Media Streams does not reliably preserve query parameters across the WebSocket upgrade. Legacy query-parameter-based handshake is still supported as a fallback.",
+            "Accepts a WebSocket upgrade from Twilio Media Streams and bidirectionally proxies frames to the assistant runtime's /v1/calls/media-stream endpoint. Handshake metadata, the callSessionId and auth token, is carried in URL path segments, e.g. /webhooks/twilio/media-stream/<callSessionId>/<token>, because Twilio Media Streams does not reliably preserve query parameters across the WebSocket upgrade. Legacy query-parameter-based handshake is still supported as a fallback.",
           operationId: "twilioMediaStreamWebsocket",
           parameters: [
             {
@@ -1003,7 +1003,7 @@ export function buildSchema(): Record<string, unknown> {
               required: false,
               schema: { type: "string" },
               description:
-                "Optional STT provider identifier (e.g. 'deepgram', 'google-gemini'). Forwarded as compatibility metadata: the runtime resolves the transcriber from config (`services.stt.roles.dictation`, else `services.stt.provider`), not from this parameter. When supplied and it disagrees with the provider that resolves to, the runtime logs a mismatch warning.",
+                "Optional STT provider identifier, e.g. 'deepgram' or 'google-gemini'. Forwarded as compatibility metadata: the runtime resolves the transcriber from config (`services.stt.roles.dictation`, else `services.stt.provider`), not from this parameter. When supplied and it disagrees with the provider that resolves to, the runtime logs a mismatch warning.",
             },
             {
               name: "mimeType",
@@ -1011,7 +1011,7 @@ export function buildSchema(): Record<string, unknown> {
               required: true,
               schema: { type: "string" },
               description:
-                "MIME type of the audio being streamed (e.g. 'audio/webm;codecs=opus').",
+                "MIME type of the audio being streamed, e.g. 'audio/webm;codecs=opus'.",
             },
             {
               name: "sampleRate",
@@ -1035,7 +1035,7 @@ export function buildSchema(): Record<string, unknown> {
                 "WebSocket upgrade successful — bidirectional STT audio/transcription frame proxying begins.",
             },
             "400": {
-              description: "Missing required query parameter (mimeType)",
+              description: "Missing required query parameter: mimeType",
               content: {
                 "text/plain": {
                   schema: { type: "string" },
@@ -1084,7 +1084,7 @@ export function buildSchema(): Record<string, unknown> {
               required: true,
               schema: { type: "string" },
               description:
-                "MIME type of the narration audio being streamed (e.g. 'audio/pcm').",
+                "MIME type of the narration audio being streamed, e.g. 'audio/pcm'.",
             },
             {
               name: "sampleRate",
@@ -1124,7 +1124,7 @@ export function buildSchema(): Record<string, unknown> {
                 "WebSocket upgrade successful - bidirectional watch stream frame proxying begins.",
             },
             "400": {
-              description: "Missing required query parameter (mimeType)",
+              description: "Missing required query parameter: mimeType",
               content: {
                 "text/plain": {
                   schema: { type: "string" },
@@ -1739,7 +1739,7 @@ export function buildSchema(): Record<string, unknown> {
             "404": { description: "Channel not found" },
             "409": {
               description:
-                "Invalid state transition (e.g. revoking a blocked channel)",
+                "Invalid state transition, e.g. revoking a blocked channel",
             },
             "503": { description: "Bearer token not configured" },
             "502": { description: "Failed to reach assistant runtime" },
@@ -1983,7 +1983,7 @@ export function buildSchema(): Record<string, unknown> {
               required: false,
               schema: { type: "string" },
               description:
-                "Optional verification purpose (e.g. guardian, trusted-contact).",
+                "Optional verification purpose, e.g. guardian or trusted-contact.",
             },
             {
               name: "contactChannelId",
@@ -2126,7 +2126,7 @@ export function buildSchema(): Record<string, unknown> {
             "Loopback-only endpoint that removes the guardian-init lock file so that /v1/guardian/init can be called again. When bootstrap secrets are configured, callers must provide a valid x-bootstrap-secret header. Used by the desktop app to recover from a lost actor token.",
           operationId: "guardianResetBootstrap",
           responses: {
-            "200": { description: "Lock file removed (or already absent)" },
+            "200": { description: "Lock file removed, or already absent" },
             "403": {
               description:
                 "Forbidden — non-loopback origin or invalid bootstrap secret",
@@ -2183,7 +2183,7 @@ export function buildSchema(): Record<string, unknown> {
           responses: {
             "200": { description: "New access token returned" },
             "400": {
-              description: "Missing required field (refreshToken or deviceId)",
+              description: "Missing required field: refreshToken or deviceId",
             },
             "401": { description: "Unauthorized — invalid token" },
             "403": {
@@ -3314,11 +3314,11 @@ export function buildSchema(): Record<string, unknown> {
                   properties: {
                     startTime: {
                       type: "number",
-                      description: "Start of time range (epoch ms)",
+                      description: "Start of time range, in epoch ms",
                     },
                     endTime: {
                       type: "number",
-                      description: "End of time range (epoch ms)",
+                      description: "End of time range, in epoch ms",
                     },
                     auditLimit: {
                       type: "number",
@@ -3381,7 +3381,7 @@ export function buildSchema(): Record<string, unknown> {
                 enum: ["trace", "debug", "info", "warn", "error", "fatal"],
                 default: "info",
               },
-              description: "Minimum pino level name (default: info)",
+              description: "Minimum pino level name, defaults to info",
             },
             {
               name: "module",
@@ -3427,7 +3427,7 @@ export function buildSchema(): Record<string, unknown> {
         get: {
           summary: "List trust rules",
           description:
-            "Authenticated gateway endpoint that lists trust rules from the SQLite-backed store. By default returns user-relevant rules (user_defined + user-modified defaults). Supports `origin`, `tool`, and `include_deleted` query filters.",
+            "Authenticated gateway endpoint that lists trust rules from the SQLite-backed store. By default returns user-relevant rules: user_defined + user-modified defaults. Supports `origin`, `tool`, and `include_deleted` query filters.",
           operationId: "trustRulesGet",
           security: [{ BearerAuth: [] }],
           parameters: [
@@ -3752,7 +3752,7 @@ export function buildSchema(): Record<string, unknown> {
         post: {
           summary: "Resolve the effective channel-permission threshold",
           description:
-            "Authenticated gateway endpoint that resolves the cascade for one coordinate (adapter, optional channelType/channelExternalId, contact-type) and returns the winning cell's threshold and scope, or null when no cell matches so the caller falls through to the global thresholds. Read-only; a POST verb path because the composite query travels in the body, same rationale as /delete.",
+            "Authenticated gateway endpoint that resolves the cascade for one coordinate — adapter, optional channelType/channelExternalId, contact-type — and returns the winning cell's threshold and scope, or null when no cell matches so the caller falls through to the global thresholds. Read-only; a POST verb path because the composite query travels in the body, same rationale as /delete.",
           operationId: "channelPermissionResolve",
           security: [{ BearerAuth: [] }],
           requestBody: {
@@ -3764,7 +3764,7 @@ export function buildSchema(): Record<string, unknown> {
             },
           },
           responses: {
-            "200": { description: "Resolution returned (resolved or null)" },
+            "200": { description: "Resolution returned — resolved or null" },
             "400": { description: "Invalid request payload or adapter" },
             "401": {
               description: "Unauthorized — missing or invalid bearer token",
@@ -3777,7 +3777,7 @@ export function buildSchema(): Record<string, unknown> {
         post: {
           summary: "Delete a channel-permission matrix cell",
           description:
-            "Authenticated gateway endpoint that removes one channel-permission cell by its composite key (selector × contact-type), letting the next cascade tier up win. A POST verb path because cells have no row id and DELETE request bodies are unreliable through proxies.",
+            "Authenticated gateway endpoint that removes one channel-permission cell by its composite key, selector × contact-type, letting the next cascade tier up win. A POST verb path because cells have no row id and DELETE request bodies are unreliable through proxies.",
           operationId: "channelPermissionOverrideDelete",
           security: [{ BearerAuth: [] }],
           requestBody: {
@@ -4152,7 +4152,7 @@ export function buildSchema(): Record<string, unknown> {
         post: {
           summary: "Kick off an async export-to-GCS job",
           description:
-            "Transparent proxy to the assistant daemon's `POST /v1/migrations/export-to-gcs` endpoint. The daemon schedules a background export job that streams the workspace backup to the supplied signed GCS upload URL and returns `202 Accepted` with a `job_id`. Callers poll `GET /v1/migrations/jobs/{jobId}` for progress. Registered explicitly (not via the runtime-proxy catch-all) for dedicated auth and timeout handling.",
+            "Transparent proxy to the assistant daemon's `POST /v1/migrations/export-to-gcs` endpoint. The daemon schedules a background export job that streams the workspace backup to the supplied signed GCS upload URL and returns `202 Accepted` with a `job_id`. Callers poll `GET /v1/migrations/jobs/{jobId}` for progress. Registered explicitly, not via the runtime-proxy catch-all, for dedicated auth and timeout handling.",
           operationId: "migrationExportToGcs",
           security: [{ BearerAuth: [] }],
           requestBody: {
@@ -4191,7 +4191,7 @@ export function buildSchema(): Record<string, unknown> {
         post: {
           summary: "Kick off an async import-from-GCS job",
           description:
-            "Transparent proxy to the assistant daemon's `POST /v1/migrations/import-from-gcs` endpoint. The daemon schedules a background import job that fetches a `.vbundle` archive at the supplied `bundle_url` and streams it through the importer, returning `202 Accepted` with a `job_id`. Callers poll `GET /v1/migrations/jobs/{jobId}` for progress. Registered explicitly (not via the runtime-proxy catch-all) for dedicated auth and timeout handling.",
+            "Transparent proxy to the assistant daemon's `POST /v1/migrations/import-from-gcs` endpoint. The daemon schedules a background import job that fetches a `.vbundle` archive at the supplied `bundle_url` and streams it through the importer, returning `202 Accepted` with a `job_id`. Callers poll `GET /v1/migrations/jobs/{jobId}` for progress. Registered explicitly, not via the runtime-proxy catch-all, for dedicated auth and timeout handling.",
           operationId: "migrationImportFromGcs",
           security: [{ BearerAuth: [] }],
           requestBody: {
@@ -4241,7 +4241,7 @@ export function buildSchema(): Record<string, unknown> {
         get: {
           summary: "Poll unified migration job status",
           description:
-            "Transparent proxy to the assistant daemon's `GET /v1/migrations/jobs/{job_id}` endpoint. Returns the current status of an async export-to-GCS or import-from-GCS job tracked by the daemon's migration job registry. Registered explicitly (not via the runtime-proxy catch-all) for dedicated auth and timeout handling.",
+            "Transparent proxy to the assistant daemon's `GET /v1/migrations/jobs/{job_id}` endpoint. Returns the current status of an async export-to-GCS or import-from-GCS job tracked by the daemon's migration job registry. Registered explicitly, not via the runtime-proxy catch-all, for dedicated auth and timeout handling.",
           operationId: "migrationJobStatus",
           security: [{ BearerAuth: [] }],
           parameters: [
@@ -4360,7 +4360,7 @@ export function buildSchema(): Record<string, unknown> {
                     type: {
                       type: "string",
                       description:
-                        "Email provider type (e.g. resend, mailgun, cadet)",
+                        "Email provider type, e.g. resend, mailgun, cadet",
                     },
                     guardian_email: {
                       type: "string",

package/src/tunnel/client.ts

@@ -33,6 +33,7 @@ import {
   TUNNEL_BINARY_WEBSOCKET_HEADER,
 } from "./binary-websocket.js";
 import { TunnelWebSocketBridge } from "./websocket-bridge.js";
+import { getIsCloud } from "../cloud-url.js";
 
 const log = getLogger("tunnel-client");
 
@@ -793,9 +794,7 @@ export function createTunnelClient(
   },
 ): TunnelClient | undefined {
   if (!config.tunnelBaseUrl) {
-    const isCloud =
-      process.env.IS_CLOUD?.trim().toLowerCase() === "true" ||
-      process.env.IS_CLOUD?.trim() === "1";
+    const isCloud = getIsCloud();
     if (isCloud) {
       log.warn(
         "TUNNEL_BASE_URL is not configured on a cloud pod — the assistant tunnel will not be established and inbound webhook delivery will fail",