@mycadet/assistant 0.12.7 → 0.12.8

package/src/runtime/routes/channel-availability-routes.ts

@@ -41,11 +41,11 @@ const BASE_AVAILABLE_CHANNELS: readonly ChannelId[] = [
 ] as const;
 
 /**
- * Best-effort check that email is configured for this assistant: a managed
- * inbox registered on the platform, or a "your own" provider credential
- * (whose gateway webhook routes carry inbound just as the managed pipeline
+ * Best-effort check that email is configured for this assistant: a cloud
+ * inbox registered on the cloud, or a "your own" provider credential
+ * (whose gateway webhook routes carry inbound just as the cloud pipeline
  * does). An unavailable platform is treated as "no inbox": we prefer to
- * under-report than block the entire Contacts page when the platform is
+ * under-report than block the entire Contacts page when the cloud is
  * briefly unreachable.
  *
  * Fresh, preserving this route's long-standing live-read-per-request

package/src/runtime/routes/client-routes.ts

@@ -95,7 +95,7 @@ export const ROUTES: RouteDefinition[] = [
       // — fail-closed is the right default for this security boundary.
       // Dev-bypass mode (DISABLE_HTTP_AUTH=true, mirroring
       // require-bound-guardian.ts) preserves the previous "return all" behavior
-      // for platform-managed deployments where the platform handles auth.
+      // for cloud-managed deployments where the cloud handles auth.
       const callerPrincipalId = headers?.["x-cadet-actor-principal-id"];
       const filtered = isHttpAuthDisabled()
         ? clients
@@ -274,8 +274,8 @@ export const ROUTES: RouteDefinition[] = [
       // spoof that desktop. Clients with no stored `actorPrincipalId` (legacy
       // SSE subscribers, service-gateway tokens) never match: fail-closed, the
       // same posture as the listing filter above. Dev-bypass mode
-      // (DISABLE_HTTP_AUTH=true) skips the check for platform-managed
-      // deployments where the platform handles auth.
+      // (DISABLE_HTTP_AUTH=true) skips the check for cloud-managed
+      // deployments where the cloud handles auth.
       if (!isHttpAuthDisabled()) {
         const callerPrincipalId = headers?.["x-cadet-actor-principal-id"];
         const ownerPrincipalId = client.actorPrincipalId;
@@ -371,8 +371,8 @@ export const ROUTES: RouteDefinition[] = [
       // spoof that tab. Clients with no stored `actorPrincipalId` (legacy SSE
       // subscribers, service-gateway tokens) never match: fail-closed, the
       // same posture as `report_client_presence`. Dev-bypass mode
-      // (DISABLE_HTTP_AUTH=true) skips the check for platform-managed
-      // deployments where the platform handles auth.
+      // (DISABLE_HTTP_AUTH=true) skips the check for cloud-managed
+      // deployments where the cloud handles auth.
       if (!isHttpAuthDisabled()) {
         const callerPrincipalId = headers?.["x-cadet-actor-principal-id"];
         const ownerPrincipalId = client.actorPrincipalId;

package/src/runtime/routes/cloud-credentials.ts

@@ -0,0 +1,45 @@
+/**
+ * The credential Cadet Cloud provisions onto a cloud assistant pod for
+ * its own use: the API key the daemon authenticates to the cloud LLM proxy
+ * with.
+ *
+ * The cloud writes it over `POST /v1/secrets`, and the daemon, the
+ * gateway, and CES read it straight out of the vault. The user never sets it
+ * through the credentials API and can do nothing useful with it there, so
+ * that API treats it as neither readable nor writable: omitted from listings,
+ * and refused by inspect, reveal, set, and delete, whatever the calling
+ * principal.
+ *
+ * The key spends inference on Cadet's account; the host it is sent to
+ * resolves from config or the `CADET_CLOUD_URL` environment variable, so
+ * there is no stored URL credential to guard alongside it.
+ */
+// The cloud pushes the pre-rebrand display name ("cadet:*"); the
+// canonical storage service is "cadet".
+const MANAGED_PROXY_CREDENTIALS = [
+  { service: "cadet", field: "assistant_api_key" },
+] as const;
+
+export function isPlatformCloudCredential(
+  service: string,
+  field: string,
+): boolean {
+  return MANAGED_PROXY_CREDENTIALS.some(
+    (c) => c.service === service && c.field === field,
+  );
+}
+
+/** What a caller was trying to do with a cloud credential. */
+export type PlatformCloudCredentialAction = "read" | "change";
+
+/** Message the credentials API refuses one of these with. */
+export function platformCloudCredentialRefusal(
+  service: string | undefined,
+  field: string | undefined,
+  action: PlatformCloudCredentialAction,
+): string {
+  const name = service && field ? `${service}:${field}` : "This credential";
+  const verb =
+    action === "read" ? "inspected or revealed" : "changed or deleted";
+  return `${name} is provisioned and owned by Cadet Cloud. It cannot be ${verb} through the credentials API.`;
+}

package/src/runtime/routes/{platform-routes.ts → cloud-routes.ts}

@@ -8,10 +8,10 @@
  *   - platform_connect (POST platform/connect): reports whether the stored
  *     credentials still connect, and when the stored key has been rejected,
  *     says so, so the caller can tell the user what replaces it.
- *   - platform_disconnect (POST platform/disconnect): deletes stored platform
- *     credentials and emits platform_disconnected signal.
+ *   - platform_disconnect (POST platform/disconnect): deletes stored cloud
+ *     credentials and emits cloud_disconnected signal.
  *   - platform_callback_routes_register (POST platform/callback-routes/register):
- *     registers a callback route with the platform gateway.
+ *     registers a callback route with the cloud gateway.
  *   - platform_callback_routes_list (GET platform/callback-routes): lists
  *     registered callback routes for this assistant.
  *   - platform_credits (GET platform/credits): fetches the org's remaining
@@ -27,33 +27,33 @@
  *     invoice list and returns a single invoice by Stripe invoice ID.
  */
 
+import {
+  type CloudCredentialVerificationStatus,
+  type PlatformVerifyCredentialResponse,
+  PlatformVerifyCredentialResponseSchema,
+} from "@mycadet/service-contracts/cloud-credential";
 import {
   type BillingPlanId,
   extraCreditUsd,
   planCreditUsedFraction,
 } from "@mycadet/service-contracts/plan-credit";
-import {
-  type PlatformCredentialVerificationStatus,
-  type PlatformVerifyCredentialResponse,
-  PlatformVerifyCredentialResponseSchema,
-} from "@mycadet/service-contracts/platform-credential";
 import { z } from "zod";
 
 import {
-  setPlatformAssistantId,
-  setPlatformBaseUrl,
-  setPlatformOrganizationId,
-  setPlatformUserId,
-} from "../../config/env.js";
-import { isPlatformRemote } from "../../config/env-registry.js";
+  resolveCloudOrganizationId,
+  resolveCloudUserId,
+} from "../../config/cloud-identity.js";
 import {
-  resolvePlatformOrganizationId,
-  resolvePlatformUserId,
-} from "../../config/platform-identity.js";
+  getCloudBaseUrl,
+  setCloudAssistantId,
+  setCloudOrganizationId,
+  setCloudUserId,
+} from "../../config/env.js";
+import { isCloudRemote } from "../../config/env-registry.js";
 import {
   registerCallbackRoute,
-  resolvePlatformCallbackRegistrationContext,
-} from "../../inbound/platform-callback-registration.js";
+  resolveCloudCallbackRegistrationContext,
+} from "../../inbound/cloud-callback-registration.js";
 import { credentialKey } from "../../security/credential-key.js";
 import {
   deleteSecureKeyAsync,
@@ -75,11 +75,7 @@ import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 // ---------------------------------------------------------------------------
 
 const CREDENTIAL_KEYS = {
-  baseUrl: { service: "cadet", field: "platform_base_url" },
   apiKey: { service: "cadet", field: "assistant_api_key" },
-  assistantId: { service: "cadet", field: "platform_assistant_id" },
-  organizationId: { service: "cadet", field: "platform_organization_id" },
-  userId: { service: "cadet", field: "platform_user_id" },
 } as const;
 
 // ---------------------------------------------------------------------------
@@ -94,7 +90,7 @@ const PlatformStatusResponseSchema = z.object({
     .boolean()
     .nullable()
     .describe(
-      "Whether a managed assistant API key is stored. Null when the credential store could not be read, which is not evidence that no key is stored.",
+      "Whether a cloud assistant API key is stored. Null when the credential store could not be read, which is not evidence that no key is stored.",
     ),
   hasWebhookSecret: z.boolean(),
   clientInstallationId: z.string().nullable(),
@@ -109,7 +105,7 @@ const PlatformConnectResponseSchema = z.object({
   baseUrl: z.string().optional(),
   showPlatformLogin: z.boolean().optional(),
   /**
-   * The stored managed credential exists but the platform rejects it. Distinct
+   * The stored cloud credential exists but the cloud rejects it. Distinct
    * from "nothing stored": the user is not setting up, they are recovering,
    * and what replaces the key is a fresh sign-in, not a first one.
    */
@@ -119,13 +115,11 @@ export type PlatformConnectResponse = z.infer<
   typeof PlatformConnectResponseSchema
 >;
 
-const PlatformDisconnectResponseSchema = z.object({
+const CloudDisconnectResponseSchema = z.object({
   disconnected: z.literal(true),
   previousBaseUrl: z.string().nullable(),
 });
-type PlatformDisconnectResponse = z.infer<
-  typeof PlatformDisconnectResponseSchema
->;
+type CloudDisconnectResponse = z.infer<typeof CloudDisconnectResponseSchema>;
 
 const CallbackRouteRegisterRequestSchema = z.object({
   path: z.string(),
@@ -168,7 +162,7 @@ const PlatformCreditsResponseSchema = z.object({
     .number()
     .nullable()
     .describe(
-      "Today's (UTC) spend counted against the daily credit limit, in USD. Excludes spend covered by plan-included credits (initial credit, Pro credit bundle), so it is not total spend. Null when the platform did not report it.",
+      "Today's (UTC) spend counted against the daily credit limit, in USD. Excludes spend covered by plan-included credits (initial credit, Pro credit bundle), so it is not total spend. Null when the cloud did not report it.",
     ),
   daily_limit: z
     .number()
@@ -197,13 +191,13 @@ const PlatformCreditsResponseSchema = z.object({
     .number()
     .nullable()
     .describe(
-      "Unused credit (USD) remaining on the unexpired plan-included grants (initial credit, Pro credit bundle). Null when the platform did not report grant figures.",
+      "Unused credit (USD) remaining on the unexpired plan-included grants (initial credit, Pro credit bundle). Null when the cloud did not report grant figures.",
     ),
   plan_credit_total: z
     .number()
     .nullable()
     .describe(
-      "Total credit (USD) those plan-included grants were worth, net of refunds. Null when the platform did not report grant figures.",
+      "Total credit (USD) those plan-included grants were worth, net of refunds. Null when the cloud did not report grant figures.",
     ),
   plan_credit_used_fraction: z
     .number()
@@ -227,7 +221,7 @@ const PlatformCreditsResponseSchema = z.object({
     .number()
     .nullable()
     .describe(
-      "Unexpired credit (USD) on grants that expire within the next 30 days. Null when the platform did not report it.",
+      "Unexpired credit (USD) on grants that expire within the next 30 days. Null when the cloud did not report it.",
     ),
   next_credit_expiry_at: z
     .string()
@@ -287,7 +281,7 @@ type PlatformSubscriptionResponse = z.infer<
 
 // The plan catalog is a large, platform-owned structure (base + pro plans, each
 // with machine/storage/credit tiers and packages). The daemon forwards it as a
-// pass-through so the catalog shape stays owned by the platform and additive
+// pass-through so the catalog shape stays owned by the cloud and additive
 // changes there don't require a daemon schema bump; only the top-level `plans`
 // envelope is asserted here.
 const PlatformPlansResponseSchema = z.object({
@@ -302,11 +296,11 @@ type PlatformPlansResponse = z.infer<typeof PlatformPlansResponseSchema>;
 async function handlePlatformStatus(
   _args: RouteHandlerArgs,
 ): Promise<PlatformStatusResponse> {
-  const context = await resolvePlatformCallbackRegistrationContext();
+  const context = await resolveCloudCallbackRegistrationContext();
 
   const [organizationId, userId, webhookSecretRaw] = await Promise.all([
-    resolvePlatformOrganizationId(),
-    resolvePlatformUserId(),
+    resolveCloudOrganizationId(),
+    resolveCloudUserId(),
     getSecureKeyAsync(credentialKey("cadet", "webhook_secret")),
   ]);
 
@@ -314,7 +308,7 @@ async function handlePlatformStatus(
 
   return {
     isPlatform: context.isPlatform,
-    baseUrl: context.platformBaseUrl,
+    baseUrl: context.cloudBaseUrl,
     assistantId: context.assistantId,
     hasAssistantApiKey: context.hasAssistantApiKey,
     hasWebhookSecret,
@@ -329,23 +323,12 @@ async function handlePlatformConnect(
   _args: RouteHandlerArgs,
 ): Promise<PlatformConnectResponse> {
   // Check if already connected
-  const [existingUrl, existingApiKey] = await Promise.all([
-    getSecureKeyAsync(
-      credentialKey(
-        CREDENTIAL_KEYS.baseUrl.service,
-        CREDENTIAL_KEYS.baseUrl.field,
-      ),
-    ),
-    getSecureKeyAsync(
-      credentialKey(
-        CREDENTIAL_KEYS.apiKey.service,
-        CREDENTIAL_KEYS.apiKey.field,
-      ),
-    ),
-  ]);
+  const existingApiKey = await getSecureKeyAsync(
+    credentialKey(CREDENTIAL_KEYS.apiKey.service, CREDENTIAL_KEYS.apiKey.field),
+  );
 
   // Stored credentials only count as a connection while they still
-  // authenticate. Answering "already connected" for a key the platform has
+  // authenticate. Answering "already connected" for a key the cloud has
   // rejected would report nothing to do about the one thing that needs doing,
   // and no client would get the signal to rotate it.
   //
@@ -355,12 +338,12 @@ async function handlePlatformConnect(
   // stored credentials counting as a connection, so a network problem never
   // strands a working install by reporting it disconnected.
   let credentialRejected = false;
-  if (existingUrl && existingApiKey) {
+  if (existingApiKey) {
     const verified = await verifyStoredCredential();
     if (verified !== "rejected") {
       return {
         alreadyConnected: true,
-        baseUrl: existingUrl,
+        baseUrl: getCloudBaseUrl(),
       };
     }
     credentialRejected = true;
@@ -377,7 +360,7 @@ async function handlePlatformConnect(
 }
 
 /**
- * Ask the platform whether the stored managed credential authenticates.
+ * Ask the cloud whether the stored cloud credential authenticates.
  * Nothing is stored: each caller that needs the answer asks, so there is no
  * verdict to go stale.
  *
@@ -385,7 +368,7 @@ async function handlePlatformConnect(
  * about what "connected" means. Never throws: an unsettled answer is
  * `"unknown"`, which no caller treats as evidence of a dead credential.
  */
-async function verifyStoredCredential(): Promise<PlatformCredentialVerificationStatus> {
+async function verifyStoredCredential(): Promise<CloudCredentialVerificationStatus> {
   try {
     const { checkAssistantApiKey } =
       await import("../../credential-health/credential-health-service.js");
@@ -412,47 +395,32 @@ async function handlePlatformVerifyCredential(
   return { status: await verifyStoredCredential() };
 }
 
-async function handlePlatformDisconnect(
+async function handleCloudDisconnect(
   _args: RouteHandlerArgs,
-): Promise<PlatformDisconnectResponse> {
-  // Reject if running inside a platform host
-  if (isPlatformRemote()) {
+): Promise<CloudDisconnectResponse> {
+  // Reject if running inside a cloud host
+  if (isCloudRemote()) {
     throw new UnprocessableEntityError(
-      "Cannot disconnect from the platform on a platform-hosted assistant.",
+      "Cannot disconnect from the cloud on a cloud-hosted assistant.",
     );
   }
 
   // Check if connected
-  const [baseUrl, apiKey] = await Promise.all([
-    getSecureKeyAsync(
-      credentialKey(
-        CREDENTIAL_KEYS.baseUrl.service,
-        CREDENTIAL_KEYS.baseUrl.field,
-      ),
-    ),
-    getSecureKeyAsync(
-      credentialKey(
-        CREDENTIAL_KEYS.apiKey.service,
-        CREDENTIAL_KEYS.apiKey.field,
-      ),
-    ),
-  ]);
+  const apiKey = await getSecureKeyAsync(
+    credentialKey(CREDENTIAL_KEYS.apiKey.service, CREDENTIAL_KEYS.apiKey.field),
+  );
 
-  if (!baseUrl && !apiKey) {
+  if (!apiKey) {
     throw new UnprocessableEntityError(
-      "Not connected to a platform. Nothing to disconnect.\n\n" +
+      "Not connected to a cloud. Nothing to disconnect.\n\n" +
         "Run 'assistant cloud status' to check connection state.",
     );
   }
 
-  // Delete all cloud credentials
-  const keysToDelete = [
-    CREDENTIAL_KEYS.baseUrl,
-    CREDENTIAL_KEYS.apiKey,
-    CREDENTIAL_KEYS.assistantId,
-    CREDENTIAL_KEYS.organizationId,
-    CREDENTIAL_KEYS.userId,
-  ] as const;
+  // Delete the stored cloud credential. The cloud_*_id fields are not
+  // credentials — they resolve from the api key via validate and live only
+  // in the in-memory identity, cleared right below.
+  const keysToDelete = [CREDENTIAL_KEYS.apiKey] as const;
 
   const failedKeys: string[] = [];
   for (const key of keysToDelete) {
@@ -470,17 +438,16 @@ async function handlePlatformDisconnect(
     );
   }
 
-  setPlatformBaseUrl(undefined);
-  setPlatformAssistantId(undefined);
-  setPlatformOrganizationId(undefined);
-  setPlatformUserId(undefined);
+  setCloudAssistantId(undefined);
+  setCloudOrganizationId(undefined);
+  setCloudUserId(undefined);
 
   // Notify connected clients
-  broadcastMessage({ type: "platform_disconnected" });
+  broadcastMessage({ type: "cloud_disconnected" });
 
   return {
     disconnected: true,
-    previousBaseUrl: baseUrl ?? null,
+    previousBaseUrl: null,
   };
 }
 
@@ -499,7 +466,7 @@ async function handleCallbackRoutesRegister(
     throw new BadRequestError("type is required");
   }
 
-  const context = await resolvePlatformCallbackRegistrationContext();
+  const context = await resolveCloudCallbackRegistrationContext();
   if (!context.enabled) {
     throw new UnprocessableEntityError(
       "Platform callbacks not available — missing platform base URL, assistant ID, or API key. Run 'assistant cloud connect' or ensure credentials are configured.",
@@ -656,7 +623,7 @@ interface FetchPlatformJsonOptions {
   badRequestHint?: string;
   /**
    * When set, an upstream HTTP 404 resolves to this value instead of the
-   * generic InternalError path, for resources where the platform signals
+   * generic InternalError path, for resources where the cloud signals
    * "nothing here" with a 404 (e.g. the invoice list for an organization
    * without invoice history). When unset, a 404 stays an InternalError.
    */
@@ -664,7 +631,7 @@ interface FetchPlatformJsonOptions {
 }
 
 /**
- * GET a JSON resource from the platform using the assistant's stored platform
+ * GET a JSON resource from the cloud using the assistant's stored platform
  * credentials. Throws UnprocessableEntityError when credentials are missing and
  * InternalError on transport / non-2xx failures; `label` names the resource in
  * those error messages. See FetchPlatformJsonOptions for per-call overrides.
@@ -674,15 +641,15 @@ async function fetchPlatformJson(
   label: string,
   options?: FetchPlatformJsonOptions,
 ): Promise<unknown> {
-  const context = await resolvePlatformCallbackRegistrationContext();
+  const context = await resolveCloudCallbackRegistrationContext();
 
-  if (!context.platformBaseUrl || !context.authHeader) {
+  if (!context.cloudBaseUrl || !context.authHeader) {
     throw new UnprocessableEntityError(
-      "Cloud credentials not available — run 'assistant cloud connect' or set CADET_PLATFORM_URL",
+      "Cloud credentials not available — run 'assistant cloud connect' or set CADET_CLOUD_URL",
     );
   }
 
-  const url = `${context.platformBaseUrl}${path}`;
+  const url = `${context.cloudBaseUrl}${path}`;
   const timeout = AbortSignal.timeout(
     options?.timeoutMs ?? PLATFORM_FETCH_TIMEOUT_MS,
   );
@@ -788,7 +755,7 @@ async function handlePlatformPlans(
 
 /**
  * Fetch one cursor-paginated page of the org's Stripe invoice history from
- * the platform. Pass the previous page's last invoice id as `startingAfter`
+ * the cloud. Pass the previous page's last invoice id as `startingAfter`
  * to fetch the next (older) page.
  */
 async function fetchPlatformInvoicesPage(
@@ -801,7 +768,7 @@ async function fetchPlatformInvoicesPage(
   }
   return (await fetchPlatformJson(path, "invoices", {
     ...options,
-    // The platform returns 404 for an organization without invoice history;
+    // The cloud returns 404 for an organization without invoice history;
     // the web client treats that as an empty page
     // (clients/web/src/domains/settings/components/invoices-table.tsx) and
     // the daemon matches it.
@@ -815,7 +782,7 @@ async function handlePlatformInvoicesList(
   const startingAfter = args.queryParams?.starting_after;
   return await fetchPlatformInvoicesPage(startingAfter, {
     signal: args.abortSignal,
-    // The platform returns 400 for an invalid or expired starting_after
+    // The cloud returns 400 for an invalid or expired starting_after
     // cursor. Only a caller-supplied cursor is caller-correctable, so the
     // hint (and the BadRequestError it triggers) applies just when one was
     // passed; a 400 on a cursor-less request stays an InternalError.
@@ -827,7 +794,7 @@ async function handlePlatformInvoicesList(
 
 /**
  * Runaway guard for the invoices_get cursor walk: 25 pages is 2,500
- * invoices at the platform's 100-per-page size.
+ * invoices at the cloud's 100-per-page size.
  */
 export const MAX_INVOICE_PAGES = 25;
 
@@ -957,9 +924,9 @@ export const ROUTES: RouteDefinition[] = [
       requiredScopes: ["settings.read"],
       allowedPrincipalTypes: ACTOR_PRINCIPALS,
     },
-    summary: "Verify the Cadet-managed credential against the platform",
+    summary: "Verify the Cadet Cloud credential against the cloud",
     description:
-      "Asks the platform whether the stored assistant API key authenticates. POST because it performs a check; the result is returned, not stored.",
+      "Asks the cloud whether the stored assistant API key authenticates. POST because it performs a check; the result is returned, not stored.",
     tags: ["platform"],
     handler: handlePlatformVerifyCredential,
     responseBody: PlatformVerifyCredentialResponseSchema,
@@ -974,10 +941,10 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Disconnect from Cadet Cloud",
     description:
-      "Deletes stored cloud credentials and emits platform_disconnected signal to connected clients.",
+      "Deletes stored cloud credentials and emits cloud_disconnected signal to connected clients.",
     tags: ["platform"],
-    handler: handlePlatformDisconnect,
-    responseBody: PlatformDisconnectResponseSchema,
+    handler: handleCloudDisconnect,
+    responseBody: CloudDisconnectResponseSchema,
   },
   {
     operationId: "platform_callback_routes_register",
@@ -987,9 +954,9 @@ export const ROUTES: RouteDefinition[] = [
       requiredScopes: ["settings.write"],
       allowedPrincipalTypes: LOCAL_PRINCIPALS,
     },
-    summary: "Register a platform callback route",
+    summary: "Register a cloud callback route",
     description:
-      "Registers a callback route with the platform gateway for inbound provider webhooks.",
+      "Registers a callback route with the cloud gateway for inbound provider webhooks.",
     tags: ["platform"],
     handler: handleCallbackRoutesRegister,
     requestBody: CallbackRouteRegisterRequestSchema,
@@ -1005,7 +972,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "List registered platform callback routes",
     description:
-      "Lists all callback routes registered with the platform for this assistant.",
+      "Lists all callback routes registered with the cloud for this assistant.",
     tags: ["platform"],
     handler: handleCallbackRoutesList,
     responseBody: CallbackRoutesListResponseSchema,
@@ -1021,7 +988,7 @@ export const ROUTES: RouteDefinition[] = [
     summary:
       "Get the organization's credit balance, plan-credit usage, and daily-limit state",
     description:
-      "Fetches the org's settled, pending, and effective (remaining) credit balance in USD from the platform billing summary, plus plan-included credit usage (remaining, total, and the used fraction shown by the in-app usage meter), extra credit bought or earned on top, credit expiring within 30 days, and the daily-limit state: today's spend counted against the daily credit limit (which excludes spend covered by plan-included credits, so it is not total spend), the limit itself, and the low-balance warning state.",
+      "Fetches the org's settled, pending, and effective (remaining) credit balance in USD from the cloud billing summary, plus plan-included credit usage (remaining, total, and the used fraction shown by the in-app usage meter), extra credit bought or earned on top, credit expiring within 30 days, and the daily-limit state: today's spend counted against the daily credit limit (which excludes spend covered by plan-included credits, so it is not total spend), the limit itself, and the low-balance warning state.",
     tags: ["platform"],
     handler: handlePlatformCredits,
     responseBody: PlatformCreditsResponseSchema,
@@ -1036,7 +1003,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Get the organization's current plan and subscription state",
     description:
-      "Fetches the org's plan (base or pro), subscription status, renewal/period-end dates, cancellation state, selected credit tier, package, and plan-gated entitlements from the platform.",
+      "Fetches the org's plan (base or pro), subscription status, renewal/period-end dates, cancellation state, selected credit tier, package, and plan-gated entitlements from the cloud.",
     tags: ["platform"],
     handler: handlePlatformSubscription,
     responseBody: PlatformSubscriptionResponseSchema,
@@ -1051,7 +1018,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Get the plan catalog with pricing",
     description:
-      "Fetches the platform plan catalog: base and pro plans with pricing (in cents), machine/storage/credit tiers, and packages.",
+      "Fetches the cloud plan catalog: base and pro plans with pricing (in cents), machine/storage/credit tiers, and packages.",
     tags: ["platform"],
     handler: handlePlatformPlans,
     responseBody: PlatformPlansResponseSchema,
@@ -1066,7 +1033,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "List one page of the organization's Stripe invoices",
     description:
-      "Fetches one page of the org's Stripe invoice history (newest first) from the platform billing invoices endpoint. Amounts are in the currency's minor units. When has_more is true, pass the last invoice's id as starting_after to fetch the next page.",
+      "Fetches one page of the org's Stripe invoice history (newest first) from the cloud billing invoices endpoint. Amounts are in the currency's minor units. When has_more is true, pass the last invoice's id as starting_after to fetch the next page.",
     tags: ["platform"],
     queryParams: [
       {
@@ -1090,7 +1057,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Get a single Stripe invoice by ID",
     description:
-      "Pages through the org's invoice list from the platform and returns the invoice matching the given Stripe invoice ID (e.g. in_xxx). 404 if no such invoice.",
+      "Pages through the org's invoice list from the cloud and returns the invoice matching the given Stripe invoice ID (e.g. in_xxx). 404 if no such invoice.",
     tags: ["platform"],
     handler: handlePlatformInvoiceGet,
     responseBody: PlatformInvoiceSchema,

package/src/runtime/routes/conversation-compaction-routes.ts

@@ -3,7 +3,7 @@
  *
  *   GET /v1/conversations/:id/compaction?callId=…
  *
- * Reachable via the platform's `RuntimeProxyWildcardView` at
+ * Reachable via the cloud's `RuntimeProxyWildcardView` at
  * `/v1/assistants/{assistantId}/conversations/{conversationId}/compaction/?callId=…`.
  *
  * # Scope