@copilotkit/runtime 1.83.0 → 2.0.0-rc.0

package/dist/runtime/core/channel-manager.cjs

@@ -0,0 +1,973 @@
+const require_runtime = require('../../_virtual/_rolldown/runtime.cjs');
+const require_learning = require('./learning.cjs');
+const require_client = require('../intelligence-platform/client.cjs');
+const require_telemetry_client = require('../telemetry/telemetry-client.cjs');
+const require_channel_activation_config = require('./channel-activation-config.cjs');
+const require_thread_lock_heartbeat = require('../intelligence-platform/thread-lock-heartbeat.cjs');
+let rxjs = require("rxjs");
+let _ag_ui_client = require("@ag-ui/client");
+let node_crypto = require("node:crypto");
+let _ag_ui_mcp_middleware = require("@ag-ui/mcp-middleware");
+
+//#region src/runtime/core/channel-manager.ts
+/**
+* Recognised provider states, used to validate what crosses the seam.
+*
+* Deliberately duplicates `PROVIDER_STATES` in
+* `@copilotkit/channels-intelligence`'s `realtime-gateway.ts` rather than
+* importing it: this package must not take a static dependency on
+* channels-intelligence (it is reached only through a dynamic import), so the
+* `providerStates` seam is duck-typed as `Record<string, string>`.
+*
+* A state added there needs adding here too, plus a `case` in
+* {@link foldChannelLegs}. Until both land it fails OPEN — an unrecognised state
+* becomes `unknown` and the Channel keeps its transport-derived status, rather
+* than being wrongly certified or condemned.
+*/
+const PROVIDER_LEGS = new Set([
+	"attached",
+	"unhealthy",
+	"not_attached",
+	"disabled",
+	"channel_not_declared"
+]);
+/**
+* Fold a Channel's transport and provider legs into its single status.
+*
+* The transport leg dominates whenever it is not `online`: while the control
+* socket is connecting, retrying, stopped, or failed, whatever the gateway last
+* said about the provider is stale or irrelevant — the Channel cannot serve a
+* turn either way, and reporting `setup_required` for a Channel that is actually
+* mid-reconnect would hide the outage.
+*
+* Once the transport is `online` the provider leg decides, which is the whole
+* point of the split: a joined socket with no provider bound is
+* `setup_required`, not `online`.
+*
+* `unknown` keeps the transport-derived answer. That is what makes an older
+* gateway (or a gateway whose lookup failed) behave exactly as it did before
+* provider states existed, instead of turning every Channel into
+* `setup_required`.
+*
+* @param transport - Control-socket status for the Channel.
+* @param provider - Reported provider attachment state.
+* @returns The folded Channel status.
+*/
+function foldChannelLegs(transport, provider) {
+	if (transport !== "online") return transport;
+	switch (provider) {
+		case "attached":
+		case "unknown": return "online";
+		case "unhealthy": return "error";
+		case "not_attached":
+		case "disabled":
+		case "channel_not_declared": return "setup_required";
+	}
+}
+/**
+* Signals that a declared Channel cannot be activated because no managed
+* provider exists for it yet. The engine throws this (or any error whose
+* `code === "SETUP_REQUIRED"`) to move a Channel to `setup_required` rather
+* than `error` — a declared-but-unprovisioned Channel is a valid degraded
+* state, not a failure.
+*/
+var ChannelSetupRequiredError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ChannelSetupRequiredError";
+	}
+};
+/**
+* Runtime installs this pure-ESM package as a direct dependency, but the
+* specifier must stay non-literal so it never becomes a static dependency of
+* the runtime's CJS build. The packed-consumer contract is enforced by
+* `scripts/release/verify-runtime-package.ts`.
+*/
+const CHANNELS_INTELLIGENCE_SPECIFIER = "@copilotkit/channels-intelligence";
+/**
+* Default engine: wrap the channels-intelligence Realtime Gateway launcher.
+*
+* The module is reached through an injectable importer that defaults to a
+* dynamic `import()` of a non-literal specifier, so the pure-ESM
+* `@copilotkit/channels-intelligence` never becomes a static dependency of this
+* CJS package (mirrors the runtime's other channels seams). The `import`
+* seam is a parameter purely so this function's config→opts mapping and its
+* module-not-found / generic-error branches are unit-testable WITHOUT the real
+* package installed; production always uses the default importer.
+*
+* Passes NO `org`/`channelId` — the launcher's realtime scope treats them as
+* optional.
+*
+* @param config - Resolved activation config for the Channel.
+* @param channel - The Channel to activate.
+* @param importChannelsIntelligence - Test seam; loads the channels-intelligence
+*   module. Defaults to a dynamic import of the real package.
+* @param log - Optional diagnostic sink forwarded to the launcher/transport so
+*   transport-level drop diagnostics are not silent in the managed path.
+* @returns The launcher's {@link ChannelsHandle}.
+*/
+async function defaultActivateChannel(config, channel, importChannelsIntelligence = () => import(CHANNELS_INTELLIGENCE_SPECIFIER), log, services) {
+	let mod;
+	try {
+		mod = await importChannelsIntelligence();
+	} catch (err) {
+		if (isModuleNotFound(err)) throw new Error("Managed Channels require '@copilotkit/channels-intelligence' to be installed. Add it to your app's dependencies.", { cause: err });
+		throw err;
+	}
+	if (!services) throw new Error("Managed Channels require the runtime AgentRunner and Intelligence client");
+	return mod.startChannelsOverRealtimeGateway([channel], {
+		wsUrl: config.wsUrl,
+		apiKey: config.apiKey,
+		scope: {
+			projectId: config.projectId,
+			channelName: config.channelName
+		},
+		runtimeInstanceId: config.runtimeInstanceId,
+		...config.showToolStatus !== void 0 ? { showToolStatus: config.showToolStatus } : {},
+		...config.replyContinuation !== void 0 ? { replyContinuation: config.replyContinuation } : {},
+		appApiBaseUrl: config.apiUrl,
+		...log ? { log } : {},
+		runCanonical: (args) => runCanonicalChannelAgent(services.runner, services.intelligence, services.lockTtlSeconds ?? 20, services.lockHeartbeatIntervalSeconds ?? 15, args, services.lockKeyPrefix, services.learning),
+		loadHistory: async ({ deliveryId, threadId, appUserId }) => {
+			const history = await services.intelligence.getThreadMessages({
+				threadId,
+				userId: appUserId,
+				channelDeliveryId: deliveryId
+			});
+			return Promise.all(history.messages.map((message) => toAgentMessage(message, services.intelligence)));
+		}
+	});
+}
+/** Builds the AG-UI input used to select and execute one Channel run. */
+function buildCanonicalChannelRunInput(args) {
+	return {
+		threadId: args.threadId,
+		runId: args.runId,
+		messages: args.agent.messages,
+		state: args.agent.state,
+		tools: [...args.tools],
+		context: [...args.context],
+		forwardedProps: void 0
+	};
+}
+/** Attach grant-scoped Intelligence Memory tools to one isolated Channel agent. */
+function attachChannelMemory(agent, intelligence, memory) {
+	if (!memory) return;
+	const middlewareAgent = agent;
+	if (typeof middlewareAgent.use !== "function") {
+		const error = /* @__PURE__ */ new Error("Channel Memory requires an agent with middleware support");
+		error.name = "ChannelMemoryAgentUnsupportedError";
+		error.code = "channel_memory_agent_unsupported";
+		throw error;
+	}
+	middlewareAgent.use(new _ag_ui_mcp_middleware.MCPMiddleware([{
+		type: "http",
+		url: `${intelligence.ɵgetApiUrl()}/mcp`,
+		serverId: "intelligence",
+		headers: {
+			Authorization: `Bearer ${intelligence.ɵgetApiKey()}`,
+			[require_client.INTELLIGENCE_MEMORY_GRANT_HEADER]: JSON.stringify(memory.grant),
+			...memory.user ? { [require_client.INTELLIGENCE_USER_ID_HEADER]: memory.user.id } : {}
+		}
+	}]));
+}
+/** One outer agent that lets the standard runner own the whole local tool loop. */
+var ChannelOuterAgent = class extends _ag_ui_client.AbstractAgent {
+	constructor(inner, canonicalThreadId, executeLoop) {
+		super({
+			threadId: inner.threadId,
+			initialMessages: inner.messages,
+			initialState: inner.state,
+			...inner.agentId ? { agentId: inner.agentId } : {}
+		});
+		this.inner = inner;
+		this.canonicalThreadId = canonicalThreadId;
+		this.executeLoop = executeLoop;
+	}
+	run() {
+		return rxjs.EMPTY;
+	}
+	async runAgent(parameters, subscriber) {
+		if (!parameters?.runId) throw new Error("Canonical Channel run requires a runId");
+		return {
+			result: await this.executeLoop(subscriber ?? {}, {
+				threadId: this.canonicalThreadId,
+				runId: parameters.runId
+			}),
+			newMessages: []
+		};
+	}
+	abortRun() {
+		this.inner.abortRun();
+	}
+};
+/** Drive one public Channel run through the runtime's existing AgentRunner. */
+async function runCanonicalChannelAgent(runner, intelligence, lockTtlSeconds, lockHeartbeatIntervalSeconds, args, lockKeyPrefix, learning) {
+	const input = buildCanonicalChannelRunInput(args);
+	const selector = intelligence.ɵgetLearningContainerId?.();
+	const learningContainerId = selector ? await require_learning.resolveLearningContainerSelector(selector, {
+		surface: "channel",
+		user: args.user ?? null,
+		agentId: args.agentId,
+		input
+	}) : await require_learning.resolveLearningContainerId(learning, {
+		surface: "channel",
+		threadId: args.threadId,
+		runId: args.runId,
+		agentId: args.agentId,
+		userId: args.userId,
+		deliveryId: args.deliveryId
+	});
+	const lockRequestedAt = Date.now();
+	const lock = await intelligence.ɵacquireThreadLock({
+		threadId: args.threadId,
+		runId: args.runId,
+		userId: args.userId,
+		agentId: args.agentId,
+		channelDeliveryId: args.deliveryId,
+		requestId: args.deliveryId,
+		...learningContainerId !== void 0 ? { learningContainerId } : {},
+		ttlSeconds: lockTtlSeconds,
+		...lockKeyPrefix !== void 0 ? { lockKeyPrefix } : {}
+	});
+	const canonicalThreadId = lock.threadId;
+	const canonicalRunId = lock.runId;
+	let result = {
+		iterations: 0,
+		interrupted: false
+	};
+	attachChannelMemory(args.agent, intelligence, args.memory);
+	const outer = new ChannelOuterAgent(args.agent, canonicalThreadId, async (subscriber, canonicalRun) => {
+		result = await args.execute(subscriber, canonicalRun);
+		return result;
+	});
+	let stopPromise;
+	let heartbeatError;
+	const stopCanonicalRun = () => {
+		stopPromise ??= Promise.resolve().then(() => runner.stop({
+			threadId: canonicalThreadId,
+			runId: canonicalRunId
+		})).catch(() => false);
+	};
+	const abortCanonicalRun = () => {
+		try {
+			args.agent.abortRun();
+		} catch {}
+		stopCanonicalRun();
+	};
+	args.signal?.addEventListener("abort", abortCanonicalRun, { once: true });
+	const heartbeat = require_thread_lock_heartbeat.startThreadLockHeartbeat({
+		renew: (signal) => intelligence.ɵrenewThreadLock({
+			threadId: canonicalThreadId,
+			runId: canonicalRunId,
+			ttlSeconds: lockTtlSeconds,
+			...lockKeyPrefix !== void 0 ? { lockKeyPrefix } : {},
+			signal
+		}),
+		intervalMs: lockHeartbeatIntervalSeconds * 1e3,
+		fallbackTtlSeconds: lockTtlSeconds,
+		initialTtlSeconds: lock.ttlSeconds === void 0 ? void 0 : lock.ttlSeconds - (Date.now() - lockRequestedAt) / 1e3,
+		unref: true,
+		onLost: (error) => {
+			heartbeatError = error;
+			try {
+				args.agent.abortRun();
+			} catch {}
+			stopCanonicalRun();
+		}
+	});
+	try {
+		await new Promise((resolve, reject) => {
+			let terminalError;
+			runner.run({
+				threadId: canonicalThreadId,
+				agent: outer,
+				input: {
+					...input,
+					threadId: canonicalThreadId,
+					runId: canonicalRunId
+				},
+				persistedInputMessages: args.persistedInputMessages
+			}).subscribe({
+				next: (event) => {
+					if (event.type !== _ag_ui_client.EventType.RUN_ERROR || terminalError) return;
+					const message = "message" in event && typeof event.message === "string" ? event.message : "Canonical Channel agent run failed";
+					const details = safeChannelRunErrorDetails(event);
+					terminalError = new Error(message, details ? { cause: details } : void 0);
+					terminalError.name = "ChannelCanonicalRunError";
+					if ("code" in event && typeof event.code === "string" && event.code.length > 0) terminalError.code = event.code;
+					if (details) {
+						terminalError.category = details.category;
+						terminalError.provider = details.provider;
+						terminalError.operation = details.operation;
+						terminalError.effectKind = details.effectKind;
+						terminalError.providerCode = details.providerCode;
+						terminalError.validationMessages = details.validationMessages;
+						terminalError.retryable = details.retryable;
+						terminalError.deliveryId = details.deliveryId;
+						terminalError.details = details;
+					}
+				},
+				error: reject,
+				complete: () => {
+					if (terminalError) reject(terminalError);
+					else resolve();
+				}
+			});
+			if (args.signal?.aborted) abortCanonicalRun();
+		});
+	} finally {
+		args.signal?.removeEventListener("abort", abortCanonicalRun);
+		heartbeat.stop();
+		await intelligence.ɵcleanupThreadLock({
+			threadId: canonicalThreadId,
+			runId: canonicalRunId
+		}).catch(() => void 0);
+	}
+	if (heartbeatError !== void 0) {
+		await stopPromise;
+		throw heartbeatError;
+	}
+	return result;
+}
+function safeChannelRunErrorDetails(event) {
+	if (!("details" in event) || typeof event.details !== "object" || event.details === null || Array.isArray(event.details)) return;
+	const details = event.details;
+	const allowed = new Set([
+		"category",
+		"provider",
+		"operation",
+		"effectKind",
+		"providerCode",
+		"validationMessages",
+		"retryable",
+		"deliveryId"
+	]);
+	if (!Object.keys(details).every((field) => allowed.has(field)) || details.category !== "validation" || details.provider !== "slack" && details.provider !== "teams" || !boundedString(details.operation, 80) || !boundedString(details.effectKind, 80) || details.providerCode !== "invalid_arguments" && details.providerCode !== "invalid_blocks" || details.retryable !== false || !boundedString(details.deliveryId, 512) || !Array.isArray(details.validationMessages) || details.validationMessages.length > 5 || !details.validationMessages.every((validationMessage) => typeof validationMessage === "string" && validationMessage.length <= 256 && validationMessage.startsWith("invalid field at /"))) return;
+	return details;
+}
+function boundedString(value, maxLength) {
+	return typeof value === "string" && value.length > 0 && value.length <= maxLength;
+}
+/** Convert canonical Intelligence history into AG-UI messages. */
+async function toAgentMessage(message, intelligence) {
+	const content = await hydrateManagedContent(message.content, intelligence);
+	return {
+		id: message.id,
+		role: message.role,
+		content: content ?? "",
+		...message.activityType ? { activityType: message.activityType } : {},
+		...message.toolCalls ? { toolCalls: message.toolCalls.map((call) => ({
+			id: call.id,
+			type: "function",
+			function: {
+				name: call.name,
+				arguments: call.args
+			}
+		})) } : {},
+		...message.toolCallId ? { toolCallId: message.toolCallId } : {}
+	};
+}
+/** Resolves managed asset references only at the authorized Runtime boundary. */
+async function hydrateManagedContent(content, intelligence) {
+	if (Array.isArray(content)) return Promise.all(content.map(async (part) => {
+		if (typeof part !== "object" || part === null || !("source" in part) || typeof part.source !== "object" || part.source === null || !("value" in part.source) || typeof part.source.value !== "string" || !part.source.value.startsWith("cpki-asset://")) return part;
+		const assetId = part.source.value.slice(13);
+		const asset = await intelligence.ɵgetManagedChannelAsset(assetId);
+		return {
+			...part,
+			source: {
+				type: "data",
+				value: Buffer.from(asset.bytes).toString("base64"),
+				mimeType: asset.mimeType ?? ("mimeType" in part.source && typeof part.source.mimeType === "string" ? part.source.mimeType : "application/octet-stream")
+			}
+		};
+	}));
+	if (typeof content === "object" && content !== null && "assetId" in content && typeof content.assetId === "string") {
+		const asset = await intelligence.ɵgetManagedChannelAsset(content.assetId);
+		return {
+			...content,
+			source: {
+				type: "data",
+				value: Buffer.from(asset.bytes).toString("base64"),
+				mimeType: asset.mimeType ?? ("mimeType" in content && typeof content.mimeType === "string" ? content.mimeType : "application/octet-stream")
+			}
+		};
+	}
+	return content;
+}
+/** Whether `err` signals a missing managed provider rather than a hard failure. */
+function isSetupRequired(err) {
+	return err instanceof ChannelSetupRequiredError || typeof err === "object" && err !== null && err.code === "SETUP_REQUIRED";
+}
+/** Whether a failed initial activation can recover without new configuration. */
+function isRetryableActivationError(err) {
+	if (typeof err !== "object" || err === null) return false;
+	const value = err;
+	return (value.code === "GATEWAY_UNREACHABLE" || value.code === "GATEWAY_JOIN_FAILED") && value.retryable === true;
+}
+/**
+* Whether `err` is a Node/runtime module-resolution failure — i.e. the error
+* a dynamic `import()` throws when the target package is not installed.
+* Exported so the friendly-error path in {@link defaultActivateChannel} can be
+* unit-tested without forcing a real failing import.
+*/
+function isModuleNotFound(err) {
+	if (typeof err !== "object" || err === null) return false;
+	const code = err.code;
+	return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+/** Default deadline (ms) for a single `handle.stop()` during teardown. */
+const DEFAULT_STOP_HANDLE_TIMEOUT_MS = 5e3;
+/** First delay (ms) before logging that a dropped session is still down. */
+const DEFAULT_RECONNECT_LOG_INTERVAL_MS = 3e4;
+/** Longest delay (ms) between reminders during one continuous outage. */
+const DEFAULT_RECONNECT_LOG_MAX_INTERVAL_MS = 15 * 6e4;
+/** First delay (ms) before retrying a transient initial activation failure. */
+const DEFAULT_ACTIVATION_RETRY_DELAY_MS = 1e3;
+/** Longest delay (ms) between transient initial activation attempts. */
+const DEFAULT_ACTIVATION_RETRY_MAX_DELAY_MS = 3e4;
+/**
+* Reject with `timeoutMessage` after `timeoutMs` if `inner` has not settled,
+* otherwise pass `inner` through. When `timeoutMs` is undefined, `inner` is
+* returned unchanged. The timer is `unref`'d so a pending deadline never keeps
+* the process alive, and `inner` always has a settle handler attached, so a
+* timed-out promise that later settles never surfaces as unhandled.
+*/
+function withTimeout(inner, timeoutMs, timeoutMessage) {
+	if (timeoutMs === void 0) return inner;
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+		timer.unref?.();
+		inner.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+/**
+* Drives Channel activation for an Intelligence runtime: lazily activates each
+* declared Channel through the managed engine, tracks per-Channel lifecycle
+* status, exposes readiness, and tears everything down. Existing direct
+* adapters remain on the Channel; the launcher attaches the one managed
+* adapter before starting the combined adapter array.
+*
+* Activation is lazy and idempotent — constructing the manager does nothing;
+* {@link activate} starts it and a second call is a no-op. Activation throws
+* SYNCHRONOUSLY (a {@link ChannelConfigError}) only for a misconfiguration it
+* can detect up front — a duplicate or missing Channel name. Every OTHER
+* permanent activation failure is recorded as the Channel's status (`error`,
+* or `setup_required` for a missing provider) and surfaced through
+* {@link status} and {@link ready} rather than thrown. A retryable initial
+* gateway outage stays unsettled and retries until it connects or the manager
+* stops.
+*
+* Established-session reconnection is delegated to the Phoenix connection
+* layer that backs the launcher. When a managed control socket drops, Phoenix's
+* `Socket` reconnects and rejoins with the same Runtime declaration. The manager
+* never re-activates an already-started Channel. It does retry a transient
+* INITIAL gateway activation failure: that happens before the launcher adds or
+* starts the managed adapter, so a later attempt is safe.
+*
+* It DOES, however, reflect real connection health through the session's
+* `onStateChange` observer so {@link ChannelManager.status} stays honest rather
+* than reporting `online` forever after a drop: a drop moves the Channel to
+* `reconnecting`, a successful rejoin restores `online`, and a bounded give-up
+* (Phoenix would otherwise retry forever) moves it to `error`.
+*/
+var ChannelManager = class {
+	/** @param args - See {@link ChannelManagerArgs}. */
+	constructor(args) {
+		this.entries = /* @__PURE__ */ new Map();
+		this.activated = false;
+		this.stopped = false;
+		this.intelligence = args.intelligence;
+		this.runner = args.runner;
+		this.learning = args.learning;
+		this.lockTtlSeconds = args.lockTtlSeconds ?? 20;
+		this.lockHeartbeatIntervalSeconds = args.lockHeartbeatIntervalSeconds ?? 15;
+		this.lockKeyPrefix = args.lockKeyPrefix;
+		this.channels = args.channels;
+		this.log = args.log;
+		this.telemetry = args.telemetry ?? require_telemetry_client.default;
+		this.activateChannel = args.activateChannel ?? ((config, channel) => defaultActivateChannel(config, channel, void 0, this.log, this.runner ? {
+			runner: this.runner,
+			intelligence: this.intelligence,
+			...this.learning !== void 0 ? { learning: this.learning } : {},
+			lockTtlSeconds: this.lockTtlSeconds,
+			lockHeartbeatIntervalSeconds: this.lockHeartbeatIntervalSeconds,
+			...this.lockKeyPrefix !== void 0 ? { lockKeyPrefix: this.lockKeyPrefix } : {}
+		} : void 0));
+		this.mintRuntimeInstanceId = args.mintRuntimeInstanceId ?? (() => `rti_${(0, node_crypto.randomUUID)().replace(/-/g, "")}`);
+		this.stopHandleTimeoutMs = args.stopHandleTimeoutMs ?? DEFAULT_STOP_HANDLE_TIMEOUT_MS;
+		this.reconnectLogIntervalMs = args.reconnectLogIntervalMs ?? DEFAULT_RECONNECT_LOG_INTERVAL_MS;
+	}
+	/**
+	* Start activation of every declared Channel (lazy + idempotent). Mints a
+	* distinct runtime instance id per Channel, derives its activation config,
+	* and calls the engine. Transient gateway failures retry with exponential
+	* backoff; other outcomes transition to `online`/`setup_required`/`error`.
+	*/
+	activate() {
+		if (this.activated || this.stopped) return;
+		this.assertUniqueChannelNames();
+		this.activated = true;
+		for (const channel of this.channels) {
+			channel.ɵruntime.enableIntelligenceMemory();
+			const name = channel.name;
+			const runtimeInstanceId = this.mintRuntimeInstanceId();
+			let resolveSettled;
+			let rejectSettled;
+			const settled = new Promise((resolve, reject) => {
+				resolveSettled = resolve;
+				rejectSettled = reject;
+			});
+			settled.catch(() => {});
+			const entry = {
+				status: "connecting",
+				handle: void 0,
+				handleStopped: false,
+				settled
+			};
+			let activation;
+			try {
+				const config = require_channel_activation_config.deriveChannelActivationConfig({
+					intelligence: this.intelligence,
+					channel,
+					runtimeInstanceId
+				});
+				activation = this.activateWithRetry(config, channel, name, entry);
+			} catch (err) {
+				activation = Promise.reject(err);
+			}
+			activation.then(async (handle) => {
+				entry.handle = handle;
+				if (this.stopped) {
+					await this.stopEntry(entry);
+					resolveSettled();
+					return;
+				}
+				entry.status = "online";
+				this.registerConnectionObserver(name, entry);
+				resolveSettled();
+			}, async (err) => {
+				if (this.stopped) {
+					await this.stopEntry(entry);
+					resolveSettled();
+					return;
+				}
+				if (isSetupRequired(err)) {
+					if (channel.adapters.some((adapter) => !adapter.__intelligenceChannel)) try {
+						await channel.ɵruntime.start();
+						entry.handle = {
+							metadata: {},
+							stop: () => channel.ɵruntime.stop()
+						};
+						if (this.stopped) {
+							await this.stopEntry(entry);
+							resolveSettled();
+							return;
+						}
+					} catch (directError) {
+						if (this.stopped) {
+							await this.stopEntry(entry);
+							resolveSettled();
+							return;
+						}
+						entry.status = "error";
+						this.log?.(`channel "${name}" failed to start its direct adapters while managed setup is incomplete`, directError);
+						rejectSettled(directError);
+						return;
+					}
+					entry.status = "setup_required";
+					this.log?.(`channel "${name}" requires setup`, err);
+					resolveSettled();
+				} else {
+					entry.status = "error";
+					this.log?.(`channel "${name}" failed to activate`, err);
+					rejectSettled(err);
+				}
+			}).catch(() => {});
+			this.entries.set(name, entry);
+		}
+	}
+	/**
+	* Retry only transient failures from the pre-adapter gateway connection.
+	* Permanent errors reject on the first attempt; teardown cancels a pending
+	* timer while preserving the existing late-settle handling for in-flight work.
+	*/
+	activateWithRetry(config, channel, name, entry) {
+		return new Promise((resolve, reject) => {
+			const attempt = () => {
+				let activation;
+				try {
+					activation = this.activateChannel(config, channel);
+				} catch (err) {
+					activation = Promise.reject(err);
+				}
+				activation.then((handle) => {
+					this.clearActivationRetry(entry);
+					resolve(handle);
+				}, (err) => {
+					if (this.stopped || !isRetryableActivationError(err)) {
+						this.clearActivationRetry(entry);
+						reject(err);
+						return;
+					}
+					const delayMs = entry.activationRetryDelayMs ?? DEFAULT_ACTIVATION_RETRY_DELAY_MS;
+					entry.status = "reconnecting";
+					entry.activationRetryDelayMs = Math.min(delayMs * 2, DEFAULT_ACTIVATION_RETRY_MAX_DELAY_MS);
+					this.log?.(`channel "${name}" failed to activate; retrying in ${delayMs}ms`, err);
+					const timer = setTimeout(() => {
+						entry.activationRetryTimer = void 0;
+						entry.cancelActivationRetry = void 0;
+						if (this.stopped || entry.status === "stopped") {
+							reject(err);
+							return;
+						}
+						entry.status = "connecting";
+						attempt();
+					}, delayMs);
+					timer.unref?.();
+					entry.activationRetryTimer = timer;
+					entry.cancelActivationRetry = () => {
+						this.clearActivationRetry(entry);
+						reject(err);
+					};
+				});
+			};
+			attempt();
+		});
+	}
+	/**
+	* Throw if two declared Channels share a `name`. `entries` is keyed by name,
+	* so a duplicate would overwrite the first Channel's entry and leak its live
+	* session. Called at the very start of {@link activate}, before any engine
+	* call, so a misconfiguration fails loud instead of silently.
+	*
+	* @throws {ChannelConfigError} If any Channel is missing a name, or if any
+	*   name appears more than once.
+	*/
+	assertUniqueChannelNames() {
+		const seen = /* @__PURE__ */ new Set();
+		for (const channel of this.channels) {
+			const name = channel.name;
+			if (!name) throw new require_channel_activation_config.ChannelConfigError("A managed Channel is missing a `name` — every declared Channel must have a unique, non-empty name (pass createChannel({ name })).");
+			if (seen.has(name)) throw new require_channel_activation_config.ChannelConfigError(`Duplicate managed Channel name "${name}" — every declared Channel must have a unique name.`);
+			seen.add(name);
+		}
+	}
+	/**
+	* Resolve when every declared Channel has settled to
+	* `online`/`setup_required` through its managed activation.
+	*
+	* Activates lazily if not already started — so a first call rejects with the
+	* same {@link ChannelConfigError} as the synchronous throw from
+	* {@link activate} for an up-front misconfiguration (duplicate/missing Channel
+	* names). Once activation has been kicked off, all OTHER failures are surfaced
+	* here instead: this rejects with an `AggregateError` if any Channel settled
+	* to `error` OR — when `timeoutMs` is given — did not settle in time. The
+	* `timeoutMs` deadline is applied PER CHANNEL, so the aggregate carries each
+	* failed Channel's real reason AND a named timeout for each Channel still
+	* hanging: a genuine activation error is never masked by a sibling that hangs
+	* (a pre-fix set-wide timeout discarded the real reason in that case).
+	*
+	* A STOPPED manager short-circuits and resolves: a Channel that settled to
+	* `error` BEFORE {@link stop} already rejected its `settled` promise, so
+	* awaiting it here would throw an `AggregateError` even though
+	* {@link status}.overall is `"stopped"` — inconsistent with the case where the
+	* Channel was still online at stop() (which resolves). A stopped manager has
+	* nothing left to be ready for, so resolve uniformly.
+	*
+	* `ready()` is ONE-SHOT: it settles on the INITIAL activation outcome. Later
+	* connection-health transitions (a live Channel dropping to `reconnecting`, or
+	* giving up to `error`) are reported through {@link status} — where `online`
+	* means currently-sendable — but do NOT re-arm or re-reject an already-settled
+	* `ready()`.
+	*/
+	async ready(opts) {
+		if (this.stopped) return;
+		this.activate();
+		const entries = [...this.entries.entries()];
+		const errors = (await Promise.allSettled(entries.map(([name, e]) => withTimeout(e.settled, opts?.timeoutMs, `channel "${name}" did not settle within ${opts?.timeoutMs}ms`)))).filter((r) => r.status === "rejected").map((r) => r.reason);
+		if (errors.length > 0) throw new AggregateError(errors, `ChannelManager.ready: ${errors.length} channel(s) failed to activate or settle in time`);
+	}
+	/**
+	* Snapshot status. Every declared Channel appears keyed by name in
+	* `channels` after its combined adapter lifecycle starts.
+	*
+	* Each Channel's entry is the fold of its transport and provider legs (see
+	* {@link foldChannelLegs}), and `detail` reports those legs separately so a
+	* caller can assert the one it cares about.
+	*
+	* `overall` is folded over ALL declared Channels (see {@link computeOverall}),
+	* by precedence `error` > `reconnecting` > `setup_required` > `connecting` >
+	* `online`. `online` means every Channel can currently send AND none was
+	* reported as missing its managed provider. `reconnecting` outranks
+	* `setup_required` because a dropped-but-retrying Channel is an active outage,
+	* louder than a steadily-degraded unprovisioned one. With no declared Channels
+	* at all, `overall` is `online` (nothing is degraded); once every Channel has
+	* been stopped, `overall` is `stopped`.
+	*
+	* `overall === "online"` is only end-to-end proof when every Channel's
+	* `provider` leg is `attached`. A gateway that reports no provider state leaves
+	* the legs `unknown` and `overall` transport-derived, exactly as before this
+	* contract existed — so a caller that must be certain checks `detail`.
+	*/
+	status() {
+		const channels = {};
+		const detail = {};
+		for (const [name, entry] of this.entries) {
+			const transport = entry.status;
+			const provider = this.providerLeg(name, entry);
+			const status = foldChannelLegs(transport, provider);
+			channels[name] = status;
+			detail[name] = {
+				status,
+				transport,
+				provider
+			};
+		}
+		if (this.stopped) return {
+			overall: "stopped",
+			channels,
+			detail
+		};
+		if (!this.activated && this.channels.length > 0) return {
+			overall: "connecting",
+			channels,
+			detail
+		};
+		return {
+			overall: this.computeOverall(Object.values(channels)),
+			channels,
+			detail
+		};
+	}
+	/**
+	* Read one Channel's provider leg from its handle.
+	*
+	* Defensive on every axis, because a wrong answer here silently changes what
+	* `status()` certifies: a handle without the seam, a gateway that reported
+	* nothing, a name the gateway did not mention, an unrecognised value, or a
+	* throwing getter all yield `unknown` — which {@link foldChannelLegs} treats as
+	* "keep the transport-derived status", i.e. pre-provider-state behaviour.
+	*
+	* @param name - The Channel name (map key).
+	* @param entry - The Channel's activation entry.
+	* @returns The provider leg, or `"unknown"` when it cannot be established.
+	*/
+	providerLeg(name, entry) {
+		let states;
+		try {
+			states = entry.handle?.providerStates?.();
+		} catch {
+			return "unknown";
+		}
+		const reported = states?.[name];
+		return reported !== void 0 && PROVIDER_LEGS.has(reported) ? reported : "unknown";
+	}
+	/**
+	* Fold per-Channel statuses into a single overall status (see {@link status}).
+	*
+	* Every declared Channel participates. Statuses are ranked
+	* `error` > `reconnecting` > `setup_required` > `connecting` > `online`, so a
+	* genuine failure still dominates a healthy sibling.
+	* The empty-input case (no declared Channels at all) stays `online` (nothing is
+	* degraded).
+	*/
+	computeOverall(values) {
+		if (values.length === 0) return "online";
+		if (values.every((v) => v === "stopped")) return "stopped";
+		if (values.includes("error")) return "error";
+		if (values.includes("reconnecting")) return "reconnecting";
+		if (values.includes("setup_required")) return "setup_required";
+		if (values.includes("connecting")) return "connecting";
+		return "online";
+	}
+	/**
+	* Wire the Channel's connection-health observer (if the handle exposes the
+	* optional `onStateChange` seam) so {@link ChannelManager.status} reflects real
+	* health instead of reporting `online` forever after a drop:
+	*
+	* - `reconnecting` → status `reconnecting` (dropped, Phoenix retrying);
+	* - `online` → status `online` (rejoined, sendable again);
+	* - `gave_up` → status `error` (dead after the bounded reconnect window).
+	*
+	* Makes NO re-activation — reconnection is delegated to the Phoenix connection
+	* layer (see {@link ChannelManager}), which auto-rejoins under the persistent
+	* adapter. A STOPPED manager (or an already-stopped entry) ignores late
+	* connection events, so a drop that fires after {@link ChannelManager.stop}
+	* never resurrects the Channel out of `stopped`.
+	*
+	* @param name - The Channel name (map key).
+	* @param entry - The Channel's activation entry.
+	*/
+	registerConnectionObserver(name, entry) {
+		entry.handle?.onStateChange?.((state, detail) => {
+			if (this.stopped || entry.status === "stopped") return;
+			const cause = detail?.reason ?? detail?.code;
+			const because = cause !== void 0 ? ` — ${cause}` : "";
+			if (state === "reconnecting") {
+				entry.status = "reconnecting";
+				entry.downSince ??= Date.now();
+				if (cause !== void 0) entry.downCause = cause;
+				this.log?.(`channel "${name}" managed session dropped; reconnecting (Phoenix auto-rejoin)${because}`);
+				this.captureChannelTelemetry("oss.runtime.channel_session_dropped", {
+					...detail?.reason !== void 0 ? { reason: detail.reason } : {},
+					...detail?.code !== void 0 ? { code: detail.code } : {}
+				});
+				this.startReconnectLog(name, entry);
+			} else if (state === "online") {
+				entry.status = "online";
+				this.clearReconnectLog(entry);
+				const downSince = entry.downSince;
+				entry.downSince = void 0;
+				entry.downCause = void 0;
+				this.log?.(`channel "${name}" managed session back online`);
+				if (downSince !== void 0) this.captureChannelTelemetry("oss.runtime.channel_session_recovered", { downForMs: Date.now() - downSince });
+			} else if (state === "gave_up") {
+				entry.status = "error";
+				this.log?.(`channel "${name}" managed session gave up reconnecting after ${this.downFor(entry)}; marking error (still retrying — a successful rejoin restores online)${because}`);
+			}
+		});
+	}
+	/**
+	* Report a Channel connection event. A managed session that drops is
+	* otherwise invisible outside the host process — the `log` seam reaches only
+	* whoever reads that process's stdout, which for a self-hosted runtime is
+	* nobody who can act on it.
+	*
+	* Fire-and-forget, and failures are swallowed: telemetry must never break a
+	* live session. Same contract as `fireInstanceCreatedTelemetry`. The `try`
+	* also covers a `capture` that throws synchronously or returns no promise.
+	*/
+	captureChannelTelemetry(event, props) {
+		try {
+			this.telemetry.capture(event, props).catch(() => {});
+		} catch {}
+	}
+	/** Rendered downtime for this outage episode (`"45s"`), or `"unknown"`. */
+	downFor(entry) {
+		return entry.downSince === void 0 ? "unknown" : `${Math.round((Date.now() - entry.downSince) / 1e3)}s`;
+	}
+	/**
+	* Repeat a "still down" line for as long as this outage lasts, with an
+	* exponential delay capped at 15 minutes. Runs THROUGH `gave_up` on purpose:
+	* that transition is where the old behavior went quiet, and an operator
+	* watching a silent process cannot tell a dead bot from an idle one.
+	*/
+	startReconnectLog(name, entry) {
+		if (entry.reconnectLogTimer !== void 0) return;
+		const delayMs = entry.reconnectLogDelayMs ?? this.reconnectLogIntervalMs;
+		const timer = setTimeout(() => {
+			entry.reconnectLogTimer = void 0;
+			if (this.stopped || entry.status === "stopped") {
+				this.clearReconnectLog(entry);
+				return;
+			}
+			this.log?.(`channel "${name}" managed session still down after ${this.downFor(entry)}; Phoenix is retrying` + (entry.downCause !== void 0 ? ` — ${entry.downCause}` : ""));
+			entry.reconnectLogDelayMs = Math.min(delayMs * 2, Math.max(this.reconnectLogIntervalMs, DEFAULT_RECONNECT_LOG_MAX_INTERVAL_MS));
+			this.startReconnectLog(name, entry);
+		}, delayMs);
+		timer.unref?.();
+		entry.reconnectLogTimer = timer;
+	}
+	/** Stop this entry's "still down" repeat, if one is running. */
+	clearReconnectLog(entry) {
+		if (entry.reconnectLogTimer !== void 0) {
+			clearTimeout(entry.reconnectLogTimer);
+			entry.reconnectLogTimer = void 0;
+		}
+		entry.reconnectLogDelayMs = void 0;
+	}
+	/** Cancel a pending transient activation retry and reset its backoff. */
+	clearActivationRetry(entry) {
+		if (entry.activationRetryTimer !== void 0) {
+			clearTimeout(entry.activationRetryTimer);
+			entry.activationRetryTimer = void 0;
+		}
+		entry.activationRetryDelayMs = void 0;
+		entry.cancelActivationRetry = void 0;
+	}
+	/** Cancel a scheduled activation retry and settle its wrapper. */
+	cancelActivationRetry(entry) {
+		const cancel = entry.cancelActivationRetry;
+		if (cancel) cancel();
+		else this.clearActivationRetry(entry);
+	}
+	/**
+	* Drive a single entry to its terminal `stopped` state, tearing down its
+	* handle AT MOST ONCE. Idempotent: it always sets `status = "stopped"`, and
+	* only calls `handle.stop()` on the first invocation that sees a live,
+	* not-yet-stopped handle (gated by {@link ChannelEntry.handleStopped}).
+	*
+	* This is the ONE guarded teardown path shared by both `stop()` and the
+	* post-settle guard in {@link activate}. Because the
+	* guard is per-entry and idempotent, a handle assigned in the same tick as
+	* `stop()` is stopped exactly once even when both callers reach the entry, and a
+	* late settle can never resurrect a `stopped` entry. The activation handle
+	* releases the gateway session and stops the Channel's combined adapter array.
+	*
+	* `handle.stop()` failures are logged (via {@link ChannelManager.log}) but NOT
+	* rethrown: the real launcher's `stop()` rethrows after `session.disconnect()`,
+	* and teardown must still complete for every other entry. The call is wrapped
+	* in `Promise.resolve().then(...)` so a foreign/injected handle whose `stop()`
+	* throws SYNCHRONOUSLY (before any promise is created) is caught by the same
+	* `.catch` — otherwise the sync throw would escape, skip `resolveSettled()` in
+	* the fulfilled-then-stopped branch of {@link activate}, and hang `settled`.
+	*
+	* An entry with no handle yet (a still-`connecting` Channel whose transport has
+	* not come up) is only marked `stopped`: there is nothing to tear down, and the
+	* post-settle guard releases the transport if it arrives after `stop()`.
+	*
+	* A WEDGED `handle.stop()` (one that never settles) is bounded by
+	* {@link ChannelManagerArgs.stopHandleTimeoutMs}: after the deadline the call
+	* is logged and abandoned so it can't hang `stop()` — and thus SIGTERM
+	* shutdown — forever.
+	*
+	* @param entry - The Channel entry to stop.
+	*/
+	async stopEntry(entry) {
+		entry.status = "stopped";
+		this.clearReconnectLog(entry);
+		this.cancelActivationRetry(entry);
+		if (entry.handle && !entry.handleStopped) {
+			entry.handleStopped = true;
+			const handle = entry.handle;
+			await withTimeout(Promise.resolve().then(() => handle.stop()), this.stopHandleTimeoutMs, `channel handle stop() timed out after ${this.stopHandleTimeoutMs}ms during teardown`).catch((err) => this.log?.("channel handle stop() failed during teardown", err));
+		}
+	}
+	/**
+	* Stop every activated Channel exactly once and mark all statuses `stopped`.
+	* Idempotent — a second call is a no-op.
+	*
+	* Resolves promptly: {@link stopEntry} stops only the handles that already
+	* exist and never blocks on activations that have not settled. A hung connect
+	* (which `ready({ timeoutMs })` tolerates) has no handle to stop yet, and
+	* awaiting it here would hang teardown — and thus SIGTERM shutdown — forever.
+	* Any handle that arrives after this point is torn down by the post-settle
+	* guard in {@link activate}, which routes through the same idempotent
+	* {@link stopEntry}, so nothing leaks and nothing double-stops.
+	*
+	* Teardown is resilient to a throwing `handle.stop()`: `Promise.allSettled`
+	* over the per-entry `stopEntry` calls guarantees one rejection can't abort
+	* the rest, so every entry reaches `stopped` and `stop()` always resolves.
+	* It is equally resilient to a WEDGED `handle.stop()` that never settles: each
+	* is bounded by {@link ChannelManagerArgs.stopHandleTimeoutMs} inside
+	* {@link stopEntry}, so a single hung handle can't hang SIGTERM shutdown.
+	*/
+	async stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		const entries = [...this.entries.values()];
+		await Promise.allSettled(entries.map((entry) => this.stopEntry(entry)));
+	}
+};
+
+//#endregion
+exports.ChannelManager = ChannelManager;
+//# sourceMappingURL=channel-manager.cjs.map