@copilotkit/runtime 2.0.0-next.1 → 2.0.0-rc.0

package/dist/runtime/intelligence-platform/client.mjs

@@ -0,0 +1,1334 @@
+import { learningCandidateDetailSchema, learningCandidateReviewSchema, learningCandidateSchema, learningContainerPageSchema, learningContainerPath, learningContainerSchema, learningInsightEvidenceSchema, learningObjectId, learningRunSchema, readLearningJson } from "./learning-management.mjs";
+import { resolveTrajectoryLearningContainerIds } from "../core/learning.mjs";
+import { TrajectoryConnectionError, parseTrajectoryConnectionGrant, trajectoryResponseError } from "./trajectories.mjs";
+import { LearnedSkillsError, learnedSkillsResponseError, parseLearnedSkillsBatch } from "./learned-skills.mjs";
+import { logger, parseInspectorLearningSnapshotV1, parseInspectorMetadataV1 } from "@copilotkit/shared";
+import { z } from "zod";
+import { randomUUID as randomUUID$1 } from "crypto";
+
+//#region src/runtime/intelligence-platform/client.ts
+/** Let a confirmed HTTP denial survive an error body that never completes. */
+async function learnedSkillsErrorBody(response, signal) {
+	if (!signal) return response.json();
+	let onAbort;
+	try {
+		return await new Promise((resolve, reject) => {
+			onAbort = () => reject(signal.reason);
+			signal.addEventListener("abort", onAbort, { once: true });
+			if (signal.aborted) onAbort();
+			else response.json().then(resolve, reject);
+		});
+	} finally {
+		if (onAbort) signal.removeEventListener("abort", onAbort);
+	}
+}
+const RUNTIME_ENTITLEMENTS_REQUEST_TIMEOUT_MS = 1500;
+const RUNTIME_ENTITLEMENTS_SUCCESS_TTL_MS = 3e4;
+const RUNTIME_ENTITLEMENTS_NEGATIVE_TTL_MS = 5e3;
+/** Whether a response grants Runtime access and therefore cannot be served stale. */
+function grantsRuntimeAccess(response) {
+	return response.status === "ready" && response.entitlement.active;
+}
+/** Whether an HTTP status can recover without changing Runtime configuration. */
+function isRetryableRuntimeEntitlementStatus(status) {
+	return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+const runtimeEntitlementSchema = z.object({
+	active: z.boolean(),
+	source: z.enum([
+		"managedOrgSubscription",
+		"selfHostedDeploymentLicense",
+		"awsMarketplaceDeploymentLicense"
+	]),
+	features: z.record(z.string(), z.boolean()),
+	limits: z.record(z.string(), z.number()),
+	planCode: z.string().optional(),
+	entitlementSource: z.string().optional()
+}).strict();
+const runtimeEntitlementResponseSchema = z.discriminatedUnion("status", [z.object({
+	status: z.literal("ready"),
+	entitlement: runtimeEntitlementSchema
+}).strict(), z.object({
+	status: z.enum([
+		"degraded",
+		"misconfigured",
+		"unavailable"
+	]),
+	error: z.object({
+		code: z.string(),
+		message: z.string(),
+		retryable: z.boolean(),
+		requestId: z.string().optional(),
+		traceId: z.string().optional()
+	}).strict()
+}).strict()]);
+const legacyRuntimeEntitlementTransportSchema = runtimeEntitlementSchema.extend({ organizationId: z.string() });
+/** Check the published App API response union without widening its type. */
+function isPublishedRuntimeEntitlementResponse(value) {
+	return runtimeEntitlementResponseSchema.safeParse(value).success;
+}
+/**
+* Validate the published App API response union, with flat-response support
+* during mixed-version rollouts.
+*/
+function normalizeRuntimeEntitlementTransport(value) {
+	if (isPublishedRuntimeEntitlementResponse(value)) return value;
+	const legacyResponse = legacyRuntimeEntitlementTransportSchema.safeParse(value);
+	if (!legacyResponse.success) return;
+	const transport = legacyResponse.data;
+	return {
+		status: "ready",
+		entitlement: {
+			active: transport.active,
+			source: transport.source,
+			features: transport.features,
+			limits: transport.limits,
+			...transport.planCode !== void 0 ? { planCode: transport.planCode } : {},
+			...transport.entitlementSource !== void 0 ? { entitlementSource: transport.entitlementSource } : {}
+		}
+	};
+}
+/**
+* Header name carrying the per-call end-user identity that the CopilotKit
+* Intelligence `/mcp` endpoint requires. Internal CopilotKit machinery —
+* `attachIntelligenceEnterpriseLearning` resolves the user via `identifyUser`
+* and bakes this header onto the `MCPMiddleware`'s transport config, so every
+* outbound MCP request stamps `X-Cpki-User-Id: <userId>`. Not part of the
+* public user API.
+*
+* @internal
+*/
+const INTELLIGENCE_USER_ID_HEADER = "x-cpki-user-id";
+/** Immutable user/project Memory grant forwarded to Intelligence. */
+const INTELLIGENCE_MEMORY_GRANT_HEADER = "x-cpki-memory-grant";
+const memoryRequestHeaders = (userId, grant) => ({
+	[INTELLIGENCE_USER_ID_HEADER]: userId,
+	...grant ? { [INTELLIGENCE_MEMORY_GRANT_HEADER]: JSON.stringify(grant) } : {}
+});
+/**
+* REST base URL of cloud-hosted CopilotKit Intelligence — the default
+* when {@link CopilotKitIntelligenceConfig.apiUrl} is omitted.
+*/
+const MANAGED_INTELLIGENCE_API_URL = "https://api.intelligence.copilotkit.ai";
+/**
+* Websocket base URL of cloud-hosted CopilotKit Intelligence — the
+* default when {@link CopilotKitIntelligenceConfig.wsUrl} is omitted.
+*
+* A different host from {@link MANAGED_INTELLIGENCE_API_URL}: the API and
+* realtime planes are deployed separately.
+*/
+const MANAGED_INTELLIGENCE_WS_URL = "wss://realtime.intelligence.copilotkit.ai";
+/** Maximum time spent on the optional Inspector metadata provider request. */
+const INSPECTOR_METADATA_REQUEST_TIMEOUT_MS = 5e3;
+const INSPECTOR_LEARNING_REQUEST_TIMEOUT_MS = 5e3;
+/** A 404 the caller expects: a thread lookup made before the thread exists. */
+const NOT_FOUND = new Set([404]);
+/** A 409 the caller expects: another request created the thread first. */
+const CONFLICT = new Set([409]);
+/**
+* Error thrown when a CopilotKit Intelligence HTTP request returns a non-2xx
+* status. Carries the HTTP {@link status} code so callers can branch on
+* specific failures (e.g. 404 for "not found", 409 for "conflict") without
+* parsing the error message string.
+*
+* @example
+* ```ts
+* try {
+*   await intelligence.getThread({ threadId, userId });
+* } catch (error) {
+*   if (error instanceof PlatformRequestError && error.status === 404) {
+*     // thread does not exist yet
+*   }
+* }
+* ```
+*/
+var PlatformRequestError = class extends Error {
+	constructor(message, status, retryable, code) {
+		super(message);
+		this.status = status;
+		this.retryable = retryable;
+		this.code = code;
+		this.name = "PlatformRequestError";
+	}
+};
+/**
+* Read the platform's `retryable` hint from an error response body. The
+* platform sends `{ error: { code, message, category, retryable } }`; anything
+* else (non-JSON, proxies, older platforms) yields `undefined`.
+*/
+function readErrorBodyRetryable(text) {
+	if (!text) return void 0;
+	try {
+		const body = JSON.parse(text);
+		if (typeof body !== "object" || body === null) return void 0;
+		const error = body.error;
+		if (typeof error !== "object" || error === null) return void 0;
+		const retryable = error.retryable;
+		return typeof retryable === "boolean" ? retryable : void 0;
+	} catch {
+		return;
+	}
+}
+/** Copy a public Runtime entitlement so callers cannot mutate cached authority. */
+function cloneRuntimeEntitlementResponse(response) {
+	if (response.status === "ready") return {
+		status: "ready",
+		entitlement: {
+			...response.entitlement,
+			features: { ...response.entitlement.features },
+			limits: { ...response.entitlement.limits }
+		}
+	};
+	return {
+		status: response.status,
+		error: { ...response.error }
+	};
+}
+/** Copy a cached Error while preserving its concrete type and own fields. */
+function cloneRuntimeEntitlementError(error) {
+	if (!(error instanceof Error)) return error;
+	return Object.create(Object.getPrototypeOf(error), Object.getOwnPropertyDescriptors(error));
+}
+/**
+* Client for the CopilotKit Intelligence REST API.
+*
+* Construct the client once and pass it to any consumers that need it
+* (e.g. `CopilotRuntime`, `IntelligenceAgentRunner`):
+*
+* ```ts
+* import { CopilotKitIntelligence, CopilotRuntime } from "@copilotkit/runtime";
+*
+* const intelligence = new CopilotKitIntelligence({
+*   apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
+* });
+*
+* const runtime = new CopilotRuntime({
+*   agents,
+*   intelligence,
+* });
+* ```
+*
+* `apiUrl` and `wsUrl` default to cloud-hosted CopilotKit Intelligence —
+* `https://api.intelligence.copilotkit.ai` and
+* `wss://realtime.intelligence.copilotkit.ai`. Those are the values for the
+* managed service; leaving both unset is always correct against it.
+*
+* Override both together to target a non-production or future self-hosted
+* deployment (the hosts below are placeholders — substitute your own):
+*
+* ```ts
+* const intelligence = new CopilotKitIntelligence({
+*   apiUrl: "https://api.intelligence.example.com",
+*   wsUrl: "wss://realtime.intelligence.example.com",
+*   apiKey: process.env.CPK_INTELLIGENCE_API_KEY!,
+* });
+* ```
+*/
+/**
+* The thread events and state reads are scoped to one end user. A caller
+* that omits `userId` (a JS caller, or one built against the earlier
+* signature) would otherwise send the literal string "undefined" as the user.
+*/
+function requireThreadReadUserId(method, userId) {
+	if (typeof userId !== "string" || userId === "") throw new TypeError(`${method} requires a non-empty userId: the id identifyUser returned`);
+}
+var CopilotKitIntelligence = class {
+	#apiUrl;
+	#runnerWsUrl;
+	#clientWsUrl;
+	#channelsWsUrl;
+	#apiKey;
+	#enterpriseLearningEnabled;
+	#getLearningContainerId;
+	#getTrajectoryLearningContainerIds;
+	#runtimeEntitlementsCache;
+	#runtimeEntitlementsFailure;
+	#runtimeEntitlementsInFlight;
+	#threadCreatedListeners = /* @__PURE__ */ new Set();
+	#threadUpdatedListeners = /* @__PURE__ */ new Set();
+	#threadDeletedListeners = /* @__PURE__ */ new Set();
+	constructor(config) {
+		this.experimental = { learning: {
+			listLearningContainers: this.#listLearningContainers.bind(this),
+			getLearningContainer: this.#getLearningContainer.bind(this),
+			listLearningRuns: this.#listLearningRuns.bind(this),
+			startLearningRun: this.#startLearningRun.bind(this),
+			listLearningCandidates: this.#listLearningCandidates.bind(this),
+			getLearningCandidate: this.#getLearningCandidate.bind(this),
+			getLearningInsightEvidence: this.#getLearningInsightEvidence.bind(this),
+			reviewLearningCandidate: this.#reviewLearningCandidate.bind(this)
+		} };
+		if (config.getLearningContainerId !== void 0 && typeof config.getLearningContainerId !== "function") throw new Error("CopilotKitIntelligence `getLearningContainerId` must be a callback");
+		assertConfiguredApiKey(config.apiKey);
+		if (config.getTrajectoryLearningContainerIds !== void 0 && typeof config.getTrajectoryLearningContainerIds !== "function") throw new Error("CopilotKitIntelligence `getTrajectoryLearningContainerIds` must be a callback");
+		const configuredApiUrl = configuredUrl(config.apiUrl);
+		const configuredWsUrl = configuredUrl(config.wsUrl);
+		warnOnPartialHostOverride(configuredApiUrl, configuredWsUrl);
+		const intelligenceWsUrl = normalizeIntelligenceWsUrl(configuredWsUrl ?? MANAGED_INTELLIGENCE_WS_URL);
+		this.#apiUrl = (configuredApiUrl ?? MANAGED_INTELLIGENCE_API_URL).replace(/\/$/, "");
+		this.#runnerWsUrl = deriveRunnerWsUrl(intelligenceWsUrl);
+		this.#clientWsUrl = deriveClientWsUrl(intelligenceWsUrl);
+		this.#channelsWsUrl = deriveChannelsWsUrl(intelligenceWsUrl);
+		this.#apiKey = config.apiKey;
+		this.#enterpriseLearningEnabled = config.enableEnterpriseLearning ?? false;
+		this.#getLearningContainerId = config.getLearningContainerId;
+		this.#getTrajectoryLearningContainerIds = config.getTrajectoryLearningContainerIds;
+		if (config.onThreadCreated) this.onThreadCreated(config.onThreadCreated);
+		if (config.onThreadUpdated) this.onThreadUpdated(config.onThreadUpdated);
+		if (config.onThreadDeleted) this.onThreadDeleted(config.onThreadDeleted);
+	}
+	/**
+	* Register a listener invoked whenever a thread is created.
+	*
+	* Multiple listeners can be registered. Each call returns an unsubscribe
+	* function that removes the listener when called.
+	*
+	* @param callback - Receives the newly created {@link ThreadSummary}.
+	* @returns A function that removes this listener when called.
+	*
+	* @example
+	* ```ts
+	* const unsubscribe = intelligence.onThreadCreated((thread) => {
+	*   console.log("Thread created:", thread.id);
+	* });
+	* // later…
+	* unsubscribe();
+	* ```
+	*/
+	onThreadCreated(callback) {
+		this.#threadCreatedListeners.add(callback);
+		return () => {
+			this.#threadCreatedListeners.delete(callback);
+		};
+	}
+	/**
+	* Register a listener invoked whenever a thread is updated (including archive).
+	*
+	* Multiple listeners can be registered. Each call returns an unsubscribe
+	* function that removes the listener when called.
+	*
+	* @param callback - Receives the updated {@link ThreadSummary}.
+	* @returns A function that removes this listener when called.
+	*/
+	onThreadUpdated(callback) {
+		this.#threadUpdatedListeners.add(callback);
+		return () => {
+			this.#threadUpdatedListeners.delete(callback);
+		};
+	}
+	/**
+	* Register a listener invoked whenever a thread is deleted.
+	*
+	* Multiple listeners can be registered. Each call returns an unsubscribe
+	* function that removes the listener when called.
+	*
+	* @param callback - Receives the {@link ThreadDeletedPayload} identifying
+	*   the deleted thread.
+	* @returns A function that removes this listener when called.
+	*/
+	onThreadDeleted(callback) {
+		this.#threadDeletedListeners.add(callback);
+		return () => {
+			this.#threadDeletedListeners.delete(callback);
+		};
+	}
+	ɵgetApiUrl() {
+		return this.#apiUrl;
+	}
+	ɵgetRunnerWsUrl() {
+		return this.#runnerWsUrl;
+	}
+	ɵgetClientWsUrl() {
+		return this.#clientWsUrl;
+	}
+	ɵgetChannelsWsUrl() {
+		return this.#channelsWsUrl;
+	}
+	ɵgetRunnerAuthToken() {
+		return this.#apiKey;
+	}
+	/** @internal Used by `attachIntelligenceEnterpriseLearning` to populate `Authorization`. */
+	ɵgetApiKey() {
+		return this.#apiKey;
+	}
+	/** @internal Used by the Intelligence runtime to assign Learning Containers. */
+	ɵgetLearningContainerId() {
+		return this.#getLearningContainerId;
+	}
+	/** @internal Used by `attachIntelligenceEnterpriseLearning` to gate MCP attachment. */
+	ɵisEnterpriseLearningEnabled() {
+		return this.#enterpriseLearningEnabled;
+	}
+	/**
+	* Fetch one authorized learned-skills ZIP with this client's project key.
+	* No retries, archive parsing, or cache. A caller signal bounds the request
+	* and body read. Native cancellation is preserved; deadline failures use
+	* {@link LearnedSkillsError} with code `TIMEOUT`.
+	*/
+	async getLearnedSkillsSnapshot(params) {
+		try {
+			params.signal?.throwIfAborted();
+			if (typeof params.containerId !== "string" || !params.containerId.trim() || params.revision !== void 0 && (typeof params.revision !== "string" || !params.revision.length) || params.ifNoneMatch !== void 0 && (typeof params.ifNoneMatch !== "string" || !params.ifNoneMatch.length || /[\r\n]/.test(params.ifNoneMatch))) throw new LearnedSkillsError("INVALID_CONFIG", false);
+			let url;
+			try {
+				url = new URL(`${this.#apiUrl}/api/v1/learning/containers/${encodeURIComponent(params.containerId)}/skills`);
+				if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) throw new Error("Invalid API URL");
+				if (params.revision !== void 0) url.searchParams.set("revision", params.revision);
+			} catch {
+				throw new LearnedSkillsError("INVALID_CONFIG", false);
+			}
+			const response = await fetch(url.toString(), {
+				method: "GET",
+				headers: {
+					Authorization: `Bearer ${this.#apiKey}`,
+					Accept: "application/zip",
+					...params.ifNoneMatch !== void 0 ? { "If-None-Match": params.ifNoneMatch } : {}
+				},
+				signal: params.signal,
+				redirect: "error"
+			});
+			if (response.status === 401) {
+				response.body?.cancel().catch(() => {});
+				throw new LearnedSkillsError("AUTHENTICATION_FAILED", false);
+			}
+			if (response.status !== 403) params.signal?.throwIfAborted();
+			if (response.status !== 200 && response.status !== 304) {
+				const denialCode = response.status === 403 ? "AUTHORIZATION_FAILED" : void 0;
+				let body;
+				try {
+					body = await learnedSkillsErrorBody(response, params.signal);
+				} catch (error) {
+					if (denialCode) throw new LearnedSkillsError(denialCode, false, error instanceof SyntaxError ? void 0 : error);
+					params.signal?.throwIfAborted();
+					if (!(error instanceof SyntaxError)) throw error;
+				}
+				const responseError = learnedSkillsResponseError(body);
+				if (response.status === 403 && ![
+					"AUTHENTICATION_FAILED",
+					"AUTHORIZATION_FAILED",
+					"ENTITLEMENT_REQUIRED",
+					"DELIVERY_DISABLED",
+					"CONTAINER_NOT_FOUND",
+					"REVISION_NOT_FOUND",
+					"REVISION_REVOKED"
+				].includes(responseError.code)) throw new LearnedSkillsError(denialCode, false);
+				throw responseError;
+			}
+			const revision = response.headers.get("X-CopilotKit-Skills-Revision");
+			const etag = response.headers.get("ETag");
+			if (!revision || !etag || !/^"[a-f0-9]{64}"$/.test(etag) || params.revision !== void 0 && revision !== params.revision) throw new LearnedSkillsError("INVALID_SNAPSHOT", false);
+			if (response.status === 304) {
+				if (params.ifNoneMatch === void 0) throw new LearnedSkillsError("INVALID_SNAPSHOT", false);
+				return {
+					status: "unchanged",
+					revision,
+					etag
+				};
+			}
+			const contentType = response.headers.get("Content-Type");
+			if (!contentType || contentType.split(";", 1)[0].trim().toLowerCase() !== "application/zip") throw new LearnedSkillsError("INVALID_SNAPSHOT", false);
+			const bytes = new Uint8Array(await response.arrayBuffer());
+			params.signal?.throwIfAborted();
+			return {
+				status: "snapshot",
+				bytes,
+				revision,
+				etag,
+				contentType
+			};
+		} catch (error) {
+			if (error instanceof LearnedSkillsError) throw error;
+			const cause = params.signal?.aborted ? params.signal.reason : error;
+			if (cause instanceof Error && cause.name === "TimeoutError") throw new LearnedSkillsError("TIMEOUT", true, cause);
+			if (params.signal?.aborted || cause instanceof Error && cause.name === "AbortError") throw cause;
+			throw new LearnedSkillsError("NETWORK_ERROR", true, error);
+		}
+	}
+	/** Fetch all requested containers in one authorized request, without retries. */
+	async getLearnedSkillsSnapshots(params) {
+		try {
+			params.signal?.throwIfAborted();
+			const containers = params.containers;
+			if (!Array.isArray(containers) || containers.length < 1 || containers.length > 50 || new Set(containers.map((item) => item?.containerId)).size !== containers.length) throw new LearnedSkillsError("INVALID_CONFIG", false);
+			for (const item of containers) {
+				if (!item || typeof item.containerId !== "string" || !item.containerId.trim() || /[\u0000-\u001f\u007f]/.test(item.containerId) || item.revision !== void 0 && (typeof item.revision !== "string" || !item.revision.trim()) || item.ifNoneMatch !== void 0 && (typeof item.ifNoneMatch !== "string" || !/^"[a-f0-9]{64}"$/.test(item.ifNoneMatch))) throw new LearnedSkillsError("INVALID_CONFIG", false);
+				try {
+					encodeURIComponent(item.containerId);
+				} catch {
+					throw new LearnedSkillsError("INVALID_CONFIG", false);
+				}
+			}
+			let url;
+			try {
+				url = new URL(`${this.#apiUrl}/api/v1/learning/skills/batch`);
+				if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) throw new Error();
+			} catch {
+				throw new LearnedSkillsError("INVALID_CONFIG", false);
+			}
+			const response = await fetch(url.toString(), {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${this.#apiKey}`,
+					Accept: "application/json",
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify({ containers: containers.map(({ containerId, revision, ifNoneMatch }) => ({
+					containerId,
+					...revision !== void 0 ? { revision } : {},
+					...ifNoneMatch !== void 0 ? { ifNoneMatch } : {}
+				})) }),
+				signal: params.signal,
+				redirect: "error"
+			});
+			if (response.status === 401) {
+				response.body?.cancel().catch(() => {});
+				throw new LearnedSkillsError("AUTHENTICATION_FAILED", false);
+			}
+			if (response.status !== 403) params.signal?.throwIfAborted();
+			if (response.status !== 200) {
+				let body;
+				try {
+					body = await learnedSkillsErrorBody(response, params.signal);
+				} catch (error) {
+					if (response.status === 403) throw new LearnedSkillsError("AUTHORIZATION_FAILED", false);
+					params.signal?.throwIfAborted();
+					if (!(error instanceof SyntaxError)) throw error;
+				}
+				const error = learnedSkillsResponseError(body);
+				if (response.status === 403 && ![
+					"AUTHENTICATION_FAILED",
+					"AUTHORIZATION_FAILED",
+					"ENTITLEMENT_REQUIRED",
+					"DELIVERY_DISABLED",
+					"CONTAINER_NOT_FOUND",
+					"REVISION_NOT_FOUND",
+					"REVISION_REVOKED"
+				].includes(error.code)) throw new LearnedSkillsError("AUTHORIZATION_FAILED", false);
+				throw error;
+			}
+			if (response.headers.get("Content-Type")?.split(";", 1)[0].trim().toLowerCase() !== "application/json") throw new LearnedSkillsError("INVALID_SNAPSHOT", false);
+			let body;
+			try {
+				body = await learnedSkillsErrorBody(response, params.signal);
+			} catch (error) {
+				if (error instanceof SyntaxError) throw new LearnedSkillsError("INVALID_SNAPSHOT", false);
+				throw error;
+			}
+			params.signal?.throwIfAborted();
+			return parseLearnedSkillsBatch(body, containers);
+		} catch (error) {
+			if (error instanceof LearnedSkillsError) throw error;
+			const cause = params.signal?.aborted ? params.signal.reason : error;
+			if (cause instanceof Error && cause.name === "TimeoutError") throw new LearnedSkillsError("TIMEOUT", true, cause);
+			if (params.signal?.aborted || cause instanceof Error && cause.name === "AbortError") throw cause;
+			throw new LearnedSkillsError("NETWORK_ERROR", true, error);
+		}
+	}
+	/**
+	* Fetch trusted Inspector metadata for this runtime's Intelligence project.
+	*
+	* The request always uses the server-configured Intelligence API key. A 404
+	* is treated as compatible absence so runtimes can work with older App API
+	* deployments that do not expose this endpoint yet.
+	*
+	* @returns Sanitized V1 metadata, or `undefined` when the provider has no
+	*   supported metadata.
+	* @throws {@link PlatformRequestError} for provider failures other than 404.
+	*/
+	async getInspectorMetadata() {
+		const path = "/api/inspector/metadata";
+		const abortController = new AbortController();
+		const timeoutError = /* @__PURE__ */ new Error("Intelligence inspector metadata request timed out");
+		let timeoutId;
+		const timeout = new Promise((_, reject) => {
+			timeoutId = setTimeout(() => {
+				reject(timeoutError);
+				abortController.abort(timeoutError);
+			}, INSPECTOR_METADATA_REQUEST_TIMEOUT_MS);
+		});
+		try {
+			const response = await Promise.race([fetch(`${this.#apiUrl}${path}`, {
+				method: "GET",
+				headers: { Authorization: `Bearer ${this.#apiKey}` },
+				signal: abortController.signal
+			}), timeout]);
+			if (response.status === 204 || response.status === 404) return;
+			if (!response.ok) {
+				logger.error({
+					status: response.status,
+					path
+				}, "Intelligence platform request failed");
+				throw new PlatformRequestError(`Intelligence platform error ${response.status}`, response.status);
+			}
+			const body = await Promise.race([response.text(), timeout]);
+			return parseInspectorMetadataV1(JSON.parse(body));
+		} catch (error) {
+			if (error === timeoutError) logger.warn({
+				path,
+				timeoutMs: INSPECTOR_METADATA_REQUEST_TIMEOUT_MS
+			}, "Intelligence inspector metadata request timed out");
+			throw error;
+		} finally {
+			if (timeoutId !== void 0) clearTimeout(timeoutId);
+		}
+	}
+	/** Lists a bounded page of Learning spaces owned by this server's project key. */
+	async #listLearningContainers(options = {}) {
+		const query = options.cursor === void 0 ? "" : `?cursor=${encodeURIComponent(z.string().min(1).max(128).parse(options.cursor))}`;
+		return this.#learningRequest("GET", `/api/v1/learning/containers${query}`, learningContainerPageSchema, options.signal);
+	}
+	/** Reads one Learning space; this does not assign or move any conversations. */
+	async #getLearningContainer(options) {
+		return (await this.#learningRequest("GET", learningContainerPath(options.containerId), z.object({ container: learningContainerSchema }), options.signal)).container;
+	}
+	/** Reads the latest 100 Learning runs; queue admission is not completion. */
+	async #listLearningRuns(options) {
+		return (await this.#learningRequest("GET", `${learningContainerPath(options.containerId)}/runs`, z.object({ runs: z.array(learningRunSchema).max(100) }), options.signal)).runs;
+	}
+	/** Starts or recovers a manual run for all eligible evidence in this space. Never retries automatically. */
+	async #startLearningRun(options) {
+		return (await this.#learningRequest("POST", `${learningContainerPath(options.containerId)}/runs`, z.object({ run: learningRunSchema }), options.signal)).run;
+	}
+	/** Reads the latest 500 proposed Skill changes, including completed reviews. */
+	async #listLearningCandidates(options) {
+		return (await this.#learningRequest("GET", `${learningContainerPath(options.containerId)}/candidates`, z.object({ candidates: z.array(learningCandidateSchema).max(500) }), options.signal)).candidates;
+	}
+	/** Reads proposed files and supporting Insights for an explicit review decision. */
+	async #getLearningCandidate(options) {
+		return (await this.#learningRequest("GET", `${learningContainerPath(options.containerId)}/candidates/${learningObjectId(options.candidateId)}`, z.object({ candidate: learningCandidateDetailSchema }), options.signal)).candidate;
+	}
+	/** Reads scoped source evidence, including unavailable-source reasons. */
+	async #getLearningInsightEvidence(options) {
+		return (await this.#learningRequest("GET", `${learningContainerPath(options.containerId)}/insights/${learningObjectId(options.insightId)}/evidence`, z.object({ evidence: z.array(learningInsightEvidenceSchema) }), options.signal)).evidence;
+	}
+	/** Publishes or rejects a proposal. The application must authorize its reviewer before calling. */
+	async #reviewLearningCandidate(options) {
+		const action = z.enum(["approve", "reject"]).parse(options.action);
+		return (await this.#learningRequest("POST", `${learningContainerPath(options.containerId)}/candidates/${learningObjectId(options.candidateId)}/${action}`, z.object({ review: learningCandidateReviewSchema }), options.signal)).review;
+	}
+	/** Uses server credentials, bounded JSON, and a deadline without retrying mutations. */
+	async #learningRequest(method, path, schema, signal) {
+		signal?.throwIfAborted();
+		const controller = new AbortController();
+		const abort = () => controller.abort(signal?.reason);
+		signal?.addEventListener("abort", abort, { once: true });
+		const timeout = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("Learning request timed out")), 3e4);
+		try {
+			const response = await fetch(`${this.#apiUrl}${path}`, {
+				method,
+				headers: {
+					Authorization: `Bearer ${this.#apiKey}`,
+					"Content-Type": "application/json"
+				},
+				...method === "POST" ? { body: "{}" } : {},
+				signal: controller.signal
+			});
+			if (!response.ok) {
+				const body = await readLearningJson(response, 64 * 1024, controller.signal).catch(() => void 0);
+				controller.signal.throwIfAborted();
+				const error = z.object({ error: z.object({
+					code: z.string().regex(/^[A-Z][A-Z0-9_]{0,99}$/),
+					retryable: z.boolean()
+				}) }).safeParse(body);
+				throw new PlatformRequestError(`Learning request failed (${response.status}).`, response.status, error.success ? error.data.error.retryable : response.status === 429 || response.status >= 500, error.success ? error.data.error.code : void 0);
+			}
+			try {
+				return schema.parse(await readLearningJson(response, void 0, controller.signal));
+			} catch {
+				if (controller.signal.aborted) throw controller.signal.reason;
+				throw new PlatformRequestError("Invalid Learning response.", 502, true);
+			}
+		} finally {
+			clearTimeout(timeout);
+			signal?.removeEventListener("abort", abort);
+		}
+	}
+	/** Fetches one credential-scoped, bounded Learning projection for Inspector. */
+	async getInspectorLearning(request) {
+		const url = new URL(`${this.#apiUrl}/api/inspector/learning`);
+		if (request.agentId) url.searchParams.set("agentId", request.agentId);
+		if (request.skillsPage) url.searchParams.set("skillsPage", String(request.skillsPage));
+		if (request.insightsPage) url.searchParams.set("insightsPage", String(request.insightsPage));
+		if (request.runtimeContainerId) url.searchParams.set("runtimeContainerId", request.runtimeContainerId);
+		const controller = new AbortController();
+		const timeoutError = /* @__PURE__ */ new Error("Intelligence Inspector Learning request timed out");
+		const timeout = setTimeout(() => controller.abort(timeoutError), INSPECTOR_LEARNING_REQUEST_TIMEOUT_MS);
+		try {
+			const response = await fetch(url, {
+				method: "GET",
+				headers: { Authorization: `Bearer ${this.#apiKey}` },
+				signal: controller.signal
+			});
+			if (!response.ok) throw new PlatformRequestError(`Intelligence platform error ${response.status}`, response.status, response.status === 429 || response.status >= 500);
+			const snapshot = parseInspectorLearningSnapshotV1(await response.json());
+			if (!snapshot) throw new PlatformRequestError("Invalid Inspector Learning response", 502, true);
+			return snapshot;
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+	/**
+	* Resolve the Runtime entitlement projection for this project.
+	*
+	* Concurrent calls share one request. Active grants cache for 30 seconds;
+	* inactive results and failures cache for 5 seconds. Callers receive copies
+	* so they cannot mutate cached authority.
+	*/
+	async getRuntimeEntitlements() {
+		const now = Date.now();
+		if (this.#runtimeEntitlementsCache && now < this.#runtimeEntitlementsCache.expiresAt) return cloneRuntimeEntitlementResponse(this.#runtimeEntitlementsCache.response);
+		if (this.#runtimeEntitlementsFailure && now < this.#runtimeEntitlementsFailure.expiresAt) throw cloneRuntimeEntitlementError(this.#runtimeEntitlementsFailure.error);
+		const request = this.#runtimeEntitlementsInFlight ?? this.#fetchRuntimeEntitlements().then((response) => {
+			this.#runtimeEntitlementsFailure = void 0;
+			this.#runtimeEntitlementsCache = {
+				response,
+				expiresAt: Date.now() + (grantsRuntimeAccess(response) ? RUNTIME_ENTITLEMENTS_SUCCESS_TTL_MS : RUNTIME_ENTITLEMENTS_NEGATIVE_TTL_MS)
+			};
+			return response;
+		}).catch((error) => {
+			this.#runtimeEntitlementsFailure = {
+				error,
+				expiresAt: Date.now() + RUNTIME_ENTITLEMENTS_NEGATIVE_TTL_MS
+			};
+			throw error;
+		});
+		this.#runtimeEntitlementsInFlight = request;
+		try {
+			return cloneRuntimeEntitlementResponse(await request);
+		} catch (error) {
+			throw cloneRuntimeEntitlementError(error);
+		} finally {
+			if (this.#runtimeEntitlementsInFlight === request) this.#runtimeEntitlementsInFlight = void 0;
+		}
+	}
+	/** Perform one bounded Runtime entitlement request without caching. */
+	async #fetchRuntimeEntitlements() {
+		const path = "/api/entitlements/runtime";
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), RUNTIME_ENTITLEMENTS_REQUEST_TIMEOUT_MS);
+		try {
+			const response = await fetch(`${this.#apiUrl}${path}`, {
+				method: "GET",
+				headers: {
+					Authorization: `Bearer ${this.#apiKey}`,
+					"Content-Type": "application/json"
+				},
+				signal: controller.signal
+			});
+			if (!response.ok) {
+				await response.body?.cancel();
+				logger.error({
+					status: response.status,
+					path
+				}, "Runtime entitlement request failed");
+				throw new PlatformRequestError(`Runtime entitlement request failed with status ${response.status}`, response.status, isRetryableRuntimeEntitlementStatus(response.status));
+			}
+			let payload;
+			try {
+				payload = await response.json();
+			} catch (error) {
+				if (controller.signal.aborted) throw error;
+				throw new PlatformRequestError("Runtime entitlement response was malformed", 502, false);
+			}
+			const normalized = normalizeRuntimeEntitlementTransport(payload);
+			if (!normalized) throw new PlatformRequestError("Runtime entitlement response was malformed", 502, false);
+			return normalized;
+		} catch (error) {
+			if (error instanceof PlatformRequestError) throw error;
+			if (controller.signal.aborted || error instanceof DOMException && error.name === "AbortError") throw new PlatformRequestError("Runtime entitlement request timed out", 504, true);
+			throw new PlatformRequestError("Runtime entitlement request failed", 502, true);
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+	/**
+	* Mint a browser capture grant using only the Runtime's project and user.
+	*
+	* Learning Container assignment never stops capture: a failed selection or
+	* an unknown Container is logged, and the Trajectory connects without
+	* assignments.
+	*/
+	async ɵconnectTrajectory(params) {
+		let learningContainerIds;
+		try {
+			learningContainerIds = await resolveTrajectoryLearningContainerIds(this.#getTrajectoryLearningContainerIds, {
+				trajectoryId: params.trajectoryId,
+				user: params.user
+			}, params.signal);
+		} catch (error) {
+			if (params.signal?.aborted) throw params.signal.reason;
+			logger.error({
+				err: error,
+				trajectoryId: params.trajectoryId
+			}, "Failed to resolve Trajectory Learning Containers; connecting the Trajectory without Learning Container assignments");
+		}
+		params.signal?.throwIfAborted();
+		try {
+			return await this.#joinTrajectory(params, learningContainerIds);
+		} catch (error) {
+			if (learningContainerIds === void 0 || !(error instanceof TrajectoryConnectionError) || error.code !== "LEARNING_CONTAINER_NOT_FOUND") throw error;
+			params.signal?.throwIfAborted();
+			logger.warn({
+				trajectoryId: params.trajectoryId,
+				learningContainerIds
+			}, "A selected Learning Container does not exist in this project; connecting the Trajectory without Learning Container assignments");
+			return this.#joinTrajectory(params, void 0);
+		}
+	}
+	/** Requests one Trajectory join token, optionally with Container assignments. */
+	async #joinTrajectory(params, learningContainerIds) {
+		let response;
+		try {
+			response = await fetch(`${this.#apiUrl}/api/trajectories/join`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${this.#apiKey}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify({
+					trajectoryId: params.trajectoryId,
+					appUserId: params.user.id,
+					...learningContainerIds === void 0 ? {} : { learningContainerIds }
+				}),
+				signal: params.signal,
+				redirect: "error"
+			});
+		} catch (error) {
+			if (!params.signal?.aborted) logger.warn({
+				error: error instanceof Error ? error.name : typeof error,
+				causeCode: networkErrorCode(error instanceof Error ? error.cause : void 0),
+				host: urlHost(this.#apiUrl)
+			}, "Could not reach Intelligence to connect a Trajectory");
+			throw error;
+		}
+		const payload = await response.json().catch(() => void 0);
+		if (!response.ok) throw trajectoryResponseError(payload, response.status, this.#apiKey);
+		return parseTrajectoryConnectionGrant(payload, params.trajectoryId, this.ɵgetClientWsUrl());
+	}
+	/**
+	* Sends one request to the platform and parses its JSON body.
+	*
+	* @param expectedStatuses - Non-2xx statuses the caller handles as a normal
+	*   outcome, such as the 404 of a thread that does not exist yet. They are
+	*   logged at debug instead of error, and still throw.
+	* @throws {@link PlatformRequestError} on every non-2xx response.
+	*/
+	async #request(method, path, body, extraHeaders, signal, expectedStatuses) {
+		const url = `${this.#apiUrl}${path}`;
+		const headers = {
+			Authorization: `Bearer ${this.#apiKey}`,
+			"Content-Type": "application/json",
+			...extraHeaders
+		};
+		const response = await fetch(url, {
+			method,
+			headers,
+			body: body ? JSON.stringify(body) : void 0,
+			signal
+		});
+		if (!response.ok) {
+			const text = await response.text().catch(() => "");
+			if (expectedStatuses?.has(response.status)) logger.debug({
+				status: response.status,
+				path
+			}, "Intelligence platform request returned an expected status");
+			else logger.error({
+				status: response.status,
+				body: text,
+				path
+			}, "Intelligence platform request failed");
+			throw new PlatformRequestError(`Intelligence platform error ${response.status}: ${text || response.statusText}`, response.status, readErrorBodyRetryable(text));
+		}
+		const text = await response.text();
+		if (!text) return;
+		return JSON.parse(text);
+	}
+	#invokeLifecycleCallback(callbackName, payload) {
+		const listeners = callbackName === "onThreadCreated" ? this.#threadCreatedListeners : callbackName === "onThreadUpdated" ? this.#threadUpdatedListeners : this.#threadDeletedListeners;
+		for (const callback of listeners) try {
+			callback(payload);
+		} catch (error) {
+			logger.error({
+				err: error,
+				callbackName,
+				payload
+			}, "Intelligence lifecycle callback failed");
+		}
+	}
+	/**
+	* List all non-archived threads for a given user and agent.
+	*
+	* @param params.userId - User whose threads to list.
+	* @param params.agentId - Agent whose threads to list.
+	* @returns The thread list along with realtime subscription credentials.
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async listThreads(params) {
+		const query = {
+			userId: params.userId,
+			agentId: params.agentId
+		};
+		if (params.includeArchived) query.includeArchived = "true";
+		if (params.limit != null) query.limit = String(params.limit);
+		if (params.cursor) query.cursor = params.cursor;
+		const qs = new URLSearchParams(query).toString();
+		return this.#request("GET", `/api/threads?${qs}`);
+	}
+	/**
+	* List the given user's long-term memories, newest first.
+	*
+	* The platform scopes by the opaque app user supplied in the
+	* `x-cpki-user-id` header (resolved by the runtime via `identifyUser`),
+	* not a query param. Pass `includeInvalidated` to also return retired rows.
+	*
+	* @returns The `{ memories }` envelope the client memory store consumes.
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async listMemories(params) {
+		const qs = params.includeInvalidated ? "?includeInvalidated=true" : "";
+		return this.#request("GET", `/api/memories${qs}`, void 0, memoryRequestHeaders(params.userId, params.memoryGrant));
+	}
+	/**
+	* Create a memory for the given user (platform `POST /api/memories`).
+	* @returns The stored memory; `absorbed` is true if the content was merged
+	*   into a near-duplicate rather than inserted as a new row.
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async createMemory(params) {
+		return this.#request("POST", `/api/memories`, {
+			content: params.content,
+			kind: params.kind,
+			...params.scope !== void 0 ? { scope: params.scope } : {},
+			sourceThreadIds: params.sourceThreadIds ?? []
+		}, memoryRequestHeaders(params.userId, params.memoryGrant));
+	}
+	/**
+	* Supersede an existing memory (platform `PATCH /api/memories/:id`). The
+	* `:id` row is retired and a new memory with the supplied content is
+	* inserted atomically.
+	* @returns The new memory plus `retiredId` (the id of the retired row).
+	* @throws {@link PlatformRequestError} on non-2xx responses (e.g. 404 when
+	*   `:id` is not a live, same-scope memory for this user).
+	*/
+	async updateMemory(params) {
+		return this.#request("PATCH", `/api/memories/${encodeURIComponent(params.id)}`, {
+			content: params.content,
+			kind: params.kind,
+			...params.scope !== void 0 ? { scope: params.scope } : {},
+			sourceThreadIds: params.sourceThreadIds ?? []
+		}, memoryRequestHeaders(params.userId, params.memoryGrant));
+	}
+	/**
+	* Non-lossily retire (forget) a memory (platform `DELETE /api/memories/:id`).
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async removeMemory(params) {
+		await this.#request("DELETE", `/api/memories/${encodeURIComponent(params.id)}`, void 0, memoryRequestHeaders(params.userId, params.memoryGrant));
+	}
+	/**
+	* Semantically recall the given user's memories (platform `POST
+	* /api/memories/recall`, hybrid RAG). Each returned memory carries a
+	* relevance `score`. `scope` narrows to `"user"`/`"project"`; omitted → platform default.
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async recallMemories(params) {
+		return this.#request("POST", `/api/memories/recall`, {
+			query: params.query,
+			...params.limit !== void 0 ? { limit: params.limit } : {},
+			...params.scope !== void 0 ? { scope: params.scope } : {}
+		}, memoryRequestHeaders(params.userId, params.memoryGrant));
+	}
+	async ɵsubscribeToThreads(params) {
+		return this.#request("POST", "/api/threads/subscribe", { userId: params.userId });
+	}
+	/**
+	* Mint memory-realtime join credentials (platform `POST
+	* /api/memories/subscribe`). Returns both the single-use `joinToken` and the
+	* per-user `joinCode` the client needs to build the
+	* `user_meta:memories:<joinCode>` channel topic. When the platform also
+	* resolves a project scope it returns optional `projectJoinToken` /
+	* `projectJoinCode`; both are passed through verbatim (omitted when absent,
+	* the silent-degrade contract).
+	*
+	* The user is supplied via the `x-cpki-user-id` header — the same way every
+	* other memory endpoint (`listMemories`/`createMemory`/…) identifies the app
+	* user — because the platform's memory routes resolve identity from that
+	* header, not the body. (This differs from `ɵsubscribeToThreads`, whose
+	* platform endpoint reads `userId` from the body.)
+	*
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async ɵsubscribeToMemories(params) {
+		return this.#request("POST", "/api/memories/subscribe", void 0, memoryRequestHeaders(params.userId, params.memoryGrant));
+	}
+	/**
+	* Update thread metadata (e.g. name).
+	*
+	* Fields in updates take precedence, preserving the server-side SDK contract.
+	* HTTP handlers must remove untrusted identity fields before calling this method.
+	*
+	* Triggers the `onThreadUpdated` lifecycle callback on success.
+	*
+	* @returns The updated thread summary.
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async updateThread(params) {
+		const response = await this.#request("PATCH", `/api/threads/${encodeURIComponent(params.threadId)}`, {
+			userId: params.userId,
+			agentId: params.agentId,
+			...params.updates
+		});
+		this.#invokeLifecycleCallback("onThreadUpdated", response.thread);
+		return response.thread;
+	}
+	/**
+	* Create a new thread on the platform.
+	*
+	* Triggers the `onThreadCreated` lifecycle callback on success.
+	*
+	* @returns The newly created thread summary.
+	* @throws {@link PlatformRequestError} with status 409 if a thread with the
+	*   same `threadId` already exists.
+	*/
+	async createThread(params) {
+		return this.#createThread(params);
+	}
+	/**
+	* Creates a thread. {@link getOrCreateThread} passes 409 as expected,
+	* because there it means another request created the thread first.
+	*/
+	async #createThread(params, expectedStatuses) {
+		const response = await this.#request("POST", `/api/threads`, {
+			threadId: params.threadId,
+			userId: params.userId,
+			agentId: params.agentId,
+			...params.name !== void 0 ? { name: params.name } : {},
+			...params.learningContainerId !== void 0 ? { learningContainerId: params.learningContainerId } : {}
+		}, void 0, void 0, expectedStatuses);
+		this.#invokeLifecycleCallback("onThreadCreated", response.thread);
+		return response.thread;
+	}
+	/**
+	* Fetch a single thread by ID.
+	*
+	* @returns The thread summary.
+	* @throws {@link PlatformRequestError} with status 404 if the thread does
+	*   not exist.
+	*/
+	async getThread(params) {
+		return this.#getThread(params);
+	}
+	/**
+	* Fetches a thread. {@link getOrCreateThread} passes 404 as expected,
+	* because there it means the thread is about to be created (PE-678).
+	*/
+	async #getThread(params, expectedStatuses) {
+		const qs = new URLSearchParams({ userId: params.userId }).toString();
+		return (await this.#request("GET", `/api/threads/${encodeURIComponent(params.threadId)}?${qs}`, void 0, void 0, void 0, expectedStatuses)).thread;
+	}
+	/**
+	* Get an existing thread or create it if it does not exist.
+	*
+	* Handles the race where a concurrent request creates the thread between
+	* the initial 404 and the subsequent `createThread` call by catching the
+	* 409 Conflict and retrying the get.
+	*
+	* Triggers the `onThreadCreated` lifecycle callback when a new thread is
+	* created.
+	*
+	* @returns An object containing the thread and a `created` flag indicating
+	*   whether the thread was newly created (`true`) or already existed (`false`).
+	* @throws {@link PlatformRequestError} on non-2xx responses other than
+	*   404 (get) and 409 (create race).
+	*/
+	async getOrCreateThread(params) {
+		try {
+			return {
+				thread: await this.#getThread({
+					threadId: params.threadId,
+					userId: params.userId
+				}, NOT_FOUND),
+				created: false
+			};
+		} catch (error) {
+			if (!(error instanceof PlatformRequestError && error.status === 404)) throw error;
+		}
+		try {
+			return {
+				thread: await this.#createThread(params, CONFLICT),
+				created: true
+			};
+		} catch (error) {
+			if (error instanceof PlatformRequestError && error.status === 409) return {
+				thread: await this.getThread({
+					threadId: params.threadId,
+					userId: params.userId
+				}),
+				created: false
+			};
+			throw error;
+		}
+	}
+	/**
+	* Fetch the full message history for a thread.
+	*
+	* @returns All persisted messages in chronological order.
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async getThreadMessages(params) {
+		const qs = new URLSearchParams({ userId: params.userId }).toString();
+		return this.#request("GET", `/api/threads/${encodeURIComponent(params.threadId)}/messages?${qs}`, void 0, params.channelDeliveryId ? { "X-Cpki-Channel-Delivery-Id": params.channelDeliveryId } : void 0);
+	}
+	/**
+	* @internal Fetch only the ids of a thread's persisted messages.
+	*
+	* Sends `fields=id` so the platform can omit message content. Platform
+	* versions that do not know the parameter ignore it and return the full
+	* transcript; ids are read from `messages[].id` either way.
+	*
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async ɵgetThreadMessageIds(params) {
+		const qs = new URLSearchParams({
+			userId: params.userId,
+			fields: "id"
+		}).toString();
+		return (await this.#request("GET", `/api/threads/${encodeURIComponent(params.threadId)}/messages?${qs}`, void 0, params.channelDeliveryId ? { "X-Cpki-Channel-Delivery-Id": params.channelDeliveryId } : void 0)).messages.map((message) => message.id);
+	}
+	/** @internal Fetches one authorized managed Channel asset for history hydration. */
+	async ɵgetManagedChannelAsset(assetId) {
+		const path = `/api/channels/files/${encodeURIComponent(assetId)}`;
+		const response = await fetch(`${this.#apiUrl}${path}`, {
+			method: "GET",
+			headers: { Authorization: `Bearer ${this.#apiKey}` }
+		});
+		if (!response.ok) {
+			const text = await response.text().catch(() => "");
+			throw new PlatformRequestError(`Intelligence platform error ${response.status}: ${text || response.statusText}`, response.status);
+		}
+		const bytes = new Uint8Array(await response.arrayBuffer());
+		const mimeType = response.headers.get("content-type") ?? void 0;
+		return {
+			bytes,
+			...mimeType ? { mimeType } : {}
+		};
+	}
+	/**
+	* Fetch the persisted AG-UI event stream for a thread.
+	*
+	* Backed by the platform's `GET /api/_inspect/threads/:id/events`
+	* introspection endpoint (see Intelligence PR #144). Events are returned
+	* in replay order across every run that targeted the thread. The
+	* `_inspect/` prefix flags this as debug-only — production code paths
+	* must not depend on it.
+	*
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async getThreadEvents(params) {
+		requireThreadReadUserId("getThreadEvents", params.userId);
+		const qs = new URLSearchParams({ userId: params.userId }).toString();
+		return this.#request("GET", `/api/_inspect/threads/${encodeURIComponent(params.threadId)}/events?${qs}`);
+	}
+	/**
+	* Fetch the current agent state for a thread.
+	*
+	* Backed by the platform's `GET /api/_inspect/threads/:id/state`
+	* introspection endpoint (see Intelligence PR #144). The platform folds
+	* RFC 6902 STATE_DELTA events on top of the latest STATE_SNAPSHOT, so
+	* the returned state reflects the thread's current state — not just the
+	* last snapshot. The discriminated response distinguishes "no snapshot
+	* persisted yet" from "snapshot present" so consumers can render the
+	* correct empty state.
+	*
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async getThreadState(params) {
+		requireThreadReadUserId("getThreadState", params.userId);
+		const qs = new URLSearchParams({ userId: params.userId }).toString();
+		return this.#request("GET", `/api/_inspect/threads/${encodeURIComponent(params.threadId)}/state?${qs}`);
+	}
+	/**
+	* Mark a thread as archived.
+	*
+	* Archived threads are excluded from {@link listThreads} results.
+	* Triggers the `onThreadUpdated` lifecycle callback on success.
+	*
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async archiveThread(params) {
+		const response = await this.#request("PATCH", `/api/threads/${encodeURIComponent(params.threadId)}`, {
+			userId: params.userId,
+			agentId: params.agentId,
+			archived: true
+		});
+		this.#invokeLifecycleCallback("onThreadUpdated", response.thread);
+	}
+	/**
+	* Permanently delete a thread and its message history.
+	*
+	* This is irreversible. Triggers the `onThreadDeleted` lifecycle callback
+	* on success.
+	*
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async deleteThread(params) {
+		await this.#request("DELETE", `/api/threads/${encodeURIComponent(params.threadId)}`, {
+			userId: params.userId,
+			agentId: params.agentId,
+			reason: `Deleted via CopilotKit runtime (userId=${params.userId}, agentId=${params.agentId})`
+		});
+		this.#invokeLifecycleCallback("onThreadDeleted", params);
+	}
+	/**
+	* Annotate a thread event on CopilotKit Intelligence's general annotation
+	* endpoint (`PUT /connector/annotate/:clientEventId`).
+	*
+	* This is the generalized replacement for the old
+	* `PUT /connector/user-actions/record/:clientEventId` endpoint. It supports
+	* multiple annotation types via the `type` discriminator. The
+	* `"user_action"` type records a user UI interaction for the self-learning
+	* loop.
+	*
+	* `userId` must be resolved on the runtime side before calling this — the
+	* platform prefixes it with the project id from the API key.
+	*
+	* Always hits the idempotent `PUT /connector/annotate/:clientEventId`
+	* endpoint. A retry with the same `clientEventId` returns
+	* `{ id: <original>, duplicate: true }` instead of creating a new row.
+	* When `clientEventId` is omitted, a UUID is auto-generated for this call.
+	*
+	* @throws {@link PlatformRequestError} on non-2xx responses, OR when the
+	*   platform returns an empty 2xx body (which would otherwise corrupt the
+	*   caller's typed result).
+	*/
+	async annotate(params) {
+		const clientEventId = params.clientEventId ?? randomUUID$1();
+		const path = `/connector/annotate/${encodeURIComponent(clientEventId)}`;
+		const body = {
+			type: params.type,
+			userId: params.userId,
+			threadId: params.threadId
+		};
+		if (params.payload !== void 0) body.payload = params.payload;
+		if (params.occurredAt !== void 0) body.occurredAt = params.occurredAt;
+		const response = await this.#request("PUT", path, body);
+		if (response == null) {
+			logger.error({ path }, "annotate: Intelligence platform returned 200 with empty or null body");
+			throw new PlatformRequestError("annotate: empty or null response body from Intelligence platform", 502);
+		}
+		return response;
+	}
+	async ɵacquireThreadLock(params) {
+		return this.#request("POST", `/api/threads/${encodeURIComponent(params.threadId)}/lock`, {
+			runId: params.runId,
+			userId: params.userId,
+			agentId: params.agentId,
+			...params.supportsBackendThreadId === void 0 ? {} : { supportsBackendThreadId: params.supportsBackendThreadId },
+			...params.learningContainerId !== void 0 ? { learningContainerId: params.learningContainerId } : {},
+			...params.requestId !== void 0 ? { requestId: params.requestId } : {},
+			...params.lockKeyPrefix !== void 0 ? { lockKeyPrefix: params.lockKeyPrefix } : {},
+			...params.ttlSeconds !== void 0 ? { ttlSeconds: params.ttlSeconds } : {}
+		}, params.channelDeliveryId ? { "X-Cpki-Channel-Delivery-Id": params.channelDeliveryId } : void 0);
+	}
+	async ɵcleanupThreadLock(params) {
+		return this.#request("DELETE", `/api/threads/${encodeURIComponent(params.threadId)}/lock`, { runId: params.runId });
+	}
+	async ɵrenewThreadLock(params) {
+		return this.#request("PATCH", `/api/threads/${encodeURIComponent(params.threadId)}/lock`, {
+			runId: params.runId,
+			ttlSeconds: params.ttlSeconds,
+			...params.lockKeyPrefix !== void 0 ? { lockKeyPrefix: params.lockKeyPrefix } : {}
+		}, void 0, params.signal);
+	}
+	async ɵgetActiveJoinCode(params) {
+		const qs = new URLSearchParams({ userId: params.userId }).toString();
+		return this.#request("GET", `/api/threads/${encodeURIComponent(params.threadId)}/join-code?${qs}`);
+	}
+	async ɵconnectThread(params) {
+		return await this.#request("POST", `/api/threads/${encodeURIComponent(params.threadId)}/connect`, {
+			userId: params.userId,
+			agentId: params.agentId
+		}) ?? null;
+	}
+};
+/**
+* Normalize a configured URL to "provided" or "not provided". A blank string
+* counts as not provided: these URLs are typically wired from environment
+* variables, and a declared-but-empty variable (`COPILOTKIT_INTELLIGENCE_URL=`,
+* common in generated `.env` files and container configs) arrives as `""`. Left
+* as-is it would produce host-relative requests instead of falling back to the
+* managed platform.
+*/
+function configuredUrl(url) {
+	const trimmed = url?.trim();
+	return trimmed ? trimmed : void 0;
+}
+/**
+* Reject an Intelligence project API key that carries no credential.
+*
+* `apiKey` is required on the config type, so TypeScript catches an absent
+* property. It does not catch an empty one, and the common shape is a
+* `process.env` read that TypeScript is told to trust — `?? ""` in the starter
+* wiring block, `!` in this file's own examples. When the variable is unset,
+* both produce a blank key that is sent verbatim as `Authorization: Bearer `
+* and fails much later as a 401 that points at nothing.
+*
+* A runtime with no credential cannot serve managed Intelligence, so this
+* throws at construction: callers build the client during boot, which puts the
+* error at startup rather than on a user's first message.
+*/
+function assertConfiguredApiKey(apiKey) {
+	if (typeof apiKey === "string" && apiKey.trim() !== "") return;
+	throw new Error("CopilotKitIntelligence `apiKey` is required and cannot be blank. It is the CopilotKit Intelligence project API key, normally read from the CPK_INTELLIGENCE_API_KEY environment variable. Run `copilotkit project select` to provision one for your project.");
+}
+/**
+* Warn when exactly one of `apiUrl`/`wsUrl` is configured. The API and realtime
+* planes are separate hosts, so a lone override silently leaves the other plane
+* on CopilotKit's managed platform — a self-hosted API paired with the managed
+* gateway (or vice versa), which fails as a hang rather than an error.
+*/
+function warnOnPartialHostOverride(apiUrl, wsUrl) {
+	if (apiUrl && !wsUrl) {
+		logger.warn(`CopilotKitIntelligence: apiUrl is set to "${apiUrl}" but wsUrl is not, so wsUrl falls back to the managed default "${MANAGED_INTELLIGENCE_WS_URL}". The API and realtime planes are separate hosts — set both when pointing at a self-hosted deployment.`);
+		return;
+	}
+	if (wsUrl && !apiUrl) logger.warn(`CopilotKitIntelligence: wsUrl is set to "${wsUrl}" but apiUrl is not, so apiUrl falls back to the managed default "${MANAGED_INTELLIGENCE_API_URL}". The API and realtime planes are separate hosts — set both when pointing at a self-hosted deployment.`);
+}
+function normalizeIntelligenceWsUrl(wsUrl) {
+	return wsUrl.replace(/\/$/, "");
+}
+function deriveRunnerWsUrl(wsUrl) {
+	if (wsUrl.endsWith("/runner")) return wsUrl;
+	if (wsUrl.endsWith("/client")) return `${wsUrl.slice(0, -7)}/runner`;
+	if (wsUrl.endsWith("/channels")) return `${wsUrl.slice(0, -9)}/runner`;
+	return `${wsUrl}/runner`;
+}
+/** A system error code such as ECONNREFUSED, or undefined for anything else. */
+function networkErrorCode(cause) {
+	const code = typeof cause === "object" && cause !== null && "code" in cause ? cause.code : void 0;
+	return typeof code === "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(code) ? code : void 0;
+}
+/** The host of a URL without its credentials, path or query. */
+function urlHost(url) {
+	try {
+		return new URL(url).host;
+	} catch {
+		return;
+	}
+}
+function deriveClientWsUrl(wsUrl) {
+	if (wsUrl.endsWith("/client")) return wsUrl;
+	if (wsUrl.endsWith("/runner")) return `${wsUrl.slice(0, -7)}/client`;
+	if (wsUrl.endsWith("/channels")) return `${wsUrl.slice(0, -9)}/client`;
+	return `${wsUrl}/client`;
+}
+function deriveChannelsWsUrl(wsUrl) {
+	if (wsUrl.endsWith("/channels")) return wsUrl;
+	if (wsUrl.endsWith("/runner")) return `${wsUrl.slice(0, -7)}/channels`;
+	if (wsUrl.endsWith("/client")) return `${wsUrl.slice(0, -7)}/channels`;
+	return `${wsUrl}/channels`;
+}
+
+//#endregion
+export { CopilotKitIntelligence, INTELLIGENCE_MEMORY_GRANT_HEADER, INTELLIGENCE_USER_ID_HEADER, PlatformRequestError };
+//# sourceMappingURL=client.mjs.map