@copilotkit/runtime 1.63.2 → 1.64.0

package/skills/runtime/references/intelligence-mode.md

@@ -11,20 +11,35 @@ Obtain `apiKey` and `organizationId` from the CopilotKit Intelligence dashboard.
 
 ### URL format
 
-The client prepends `/api/...` and the Intelligence websocket layer derives `/runner`
-or `/client` suffixes internally. Pass the bare base URLs — do NOT append `/api`,
+**Omit `apiUrl` and `wsUrl`.** Both default to the managed platform
+(`https://api.intelligence.copilotkit.ai` and
+`wss://realtime.intelligence.copilotkit.ai`), so `apiKey` is the only URL-related
+config you need. Never invent or guess these values — leaving them unset is always
+correct against the managed service.
+
+If you do set them (non-production or a future self-hosted deployment), the client
+prepends `/api/...` and the Intelligence websocket layer derives `/runner` or
+`/client` suffixes internally. Pass the bare base URLs — do NOT append `/api`,
 `/socket`, `/runner`, or `/client` yourself:
 
 ```typescript
-// Correct — bare base URLs
-apiUrl: "https://api.copilotkit.ai",
-wsUrl:  "wss://api.copilotkit.ai",
+// Correct — bare base URLs, and note the two planes are DIFFERENT hosts
+apiUrl: "https://api.intelligence.copilotkit.ai",
+wsUrl:  "wss://realtime.intelligence.copilotkit.ai",
 
 // Wrong — adding /api produces /api/api/... on every REST call; /socket/runner is not a real path
-apiUrl: "https://api.copilotkit.ai/api",
-wsUrl:  "wss://api.copilotkit.ai/socket",
+apiUrl: "https://api.intelligence.copilotkit.ai/api",
+wsUrl:  "wss://realtime.intelligence.copilotkit.ai/socket",
 ```
 
+`apiUrl` and `wsUrl` are **separate hosts** (`api.…` vs `realtime.…`), so you cannot
+produce one from the other by swapping the scheme. Deriving `wsUrl` as
+`apiUrl.replace(/^http/, "ws")` yields `wss://api.intelligence.copilotkit.ai`, which
+serves no socket — and the resulting failure is a silent hang, not an error, because
+the socket layer treats an unreachable host as a retryable reconnect. For the same
+reason, override the two together or not at all: setting one alone leaves the other
+plane on the managed host, which the client warns about at construction.
+
 Source: `packages/runtime/src/v2/runtime/intelligence-platform/client.ts:41-46, 259,
 356-357, 437, 468, 682-708`.
 
@@ -38,8 +53,7 @@ import {
 } from "@copilotkit/runtime/v2";
 
 const intelligence = new CopilotKitIntelligence({
-  apiUrl: "https://api.copilotkit.ai",
-  wsUrl: "wss://api.copilotkit.ai",
+  // apiUrl / wsUrl default to the managed Intelligence platform — leave them unset.
   apiKey: process.env.COPILOTKIT_INTELLIGENCE_API_KEY!,
   organizationId: process.env.COPILOTKIT_INTELLIGENCE_ORG_ID!,
 });
@@ -167,14 +181,22 @@ scoped to a user ID.
 
 Source: `packages/runtime/src/v2/runtime/core/runtime.ts:156-160`.
 
-### CRITICAL Adding /api or /socket suffixes, or pointing at an unsupported self-hosted server
+### CRITICAL Deriving wsUrl from apiUrl, adding /api or /socket suffixes, or pointing at an unsupported self-hosted server
 
 Wrong:
 
 ```typescript
 new CopilotKitIntelligence({
-  apiUrl: "https://api.copilotkit.ai/api", // double /api prefix
-  wsUrl: "wss://api.copilotkit.ai/socket", // /socket is not a real path
+  apiUrl: "https://api.intelligence.copilotkit.ai",
+  // Scheme-swapped from apiUrl — WRONG HOST. Serves no socket; hangs instead of erroring.
+  wsUrl: apiUrl.replace(/^http/, "ws"),
+  apiKey,
+  organizationId,
+});
+
+new CopilotKitIntelligence({
+  apiUrl: "https://api.intelligence.copilotkit.ai/api", // double /api prefix
+  wsUrl: "wss://realtime.intelligence.copilotkit.ai/socket", // /socket is not a real path
   apiKey,
   organizationId,
 });
@@ -185,27 +207,38 @@ new CopilotKitIntelligence({
   apiKey,
   organizationId,
 });
+
+new CopilotKitIntelligence({
+  // Only one plane overridden — wsUrl silently stays on the managed host. Warns, then hangs.
+  apiUrl: "https://api.intelligence.copilotkit.ai",
+  apiKey,
+  organizationId,
+});
 ```
 
 Correct:
 
 ```typescript
 new CopilotKitIntelligence({
-  apiUrl: "https://api.copilotkit.ai",
-  wsUrl: "wss://api.copilotkit.ai",
+  // No apiUrl / wsUrl — they default to the managed platform.
   apiKey: process.env.COPILOTKIT_INTELLIGENCE_API_KEY!,
   organizationId: process.env.COPILOTKIT_INTELLIGENCE_ORG_ID!,
 });
 // For on-prem durability without Intelligence: SSE mode + SqliteAgentRunner.
 ```
 
-Two failure modes to avoid:
+Three failure modes to avoid:
 
-1. The client prepends `/api/...` to every REST call (`#request` at line 356-357) and
+1. The API and realtime planes are **different hosts**, so `wsUrl` cannot be derived
+   from `apiUrl`. A scheme-only swap keeps the API host (and port) and produces a URL
+   that serves no socket. This one is expensive to debug: a wrong `apiUrl` fails fast
+   with an HTTP error, while a wrong `wsUrl` sits in `connecting` until the settle
+   timeout and reports only "did not settle in time".
+2. The client prepends `/api/...` to every REST call (`#request` at line 356-357) and
    the websocket layer derives `/runner` / `/client` suffixes from `wsUrl` internally.
    Passing `apiUrl: ".../api"` produces double-prefixed `/api/api/threads`; passing
    `wsUrl: ".../socket"` produces a broken `.../socket/runner` upgrade path.
-2. Self-hosting Intelligence is not yet supported. The `ɵ`-prefixed runtime internals
+3. Self-hosting Intelligence is not yet supported. The `ɵ`-prefixed runtime internals
    and REST/WebSocket contract are still stabilizing. `organizationId` is reserved for
    future self-hosted instances. For on-prem durable threads today, use SSE mode +
    `SqliteAgentRunner` (see `copilotkit/agent-runners`).