@copilotkit/runtime/dist/v2/runtime/core/channel-manager.d.mts

<img src="https://github.com/user-attachments/assets/0a6b64d9-e193-4940-a3f6-60334ac34084" alt="banner" style="border-radius: 12px; border: 2px solid #d6d4fa;" />

import "reflect-metadata";
import { index_d_exports } from "../../../channels/dist/index.mjs";
import { ChannelActivationConfig } from "./channel-activation-config.mjs";

//#region src/v2/runtime/core/channel-manager.d.ts
/**
 * Lifecycle status of a single Channel activation, or of the manager overall.
 *
 * - `connecting`: activation in flight, not yet settled.
 * - `online`: activation resolved AND the managed session can currently send.
 *   A drop moves the Channel to `reconnecting` (not `online`); a successful
 *   rejoin restores `online`.
 * - `setup_required`: the Channel is declared but has no managed provider yet —
 *   a valid degraded state, not a failure.
 * - `reconnecting`: the managed session dropped and Phoenix is retrying — not
 *   currently sendable. The manager does NOT re-activate (reconnection is
 *   delegated to the Phoenix connection layer); it only reflects the health the
 *   session reports via its `onStateChange` observer.
 * - `stopped`: {@link ChannelManager.stop} has torn the Channel down.
 * - `unmanaged`: the Channel carries a developer-supplied direct adapter, so this
 *   handler does NOT own its lifecycle — the developer starts it via
 *   `channel.start()`. The manager records the Channel with this status purely so
 *   its presence is observable and never misreported as `online`. It is neither
 *   activated, awaited, nor stopped here. Real routing of direct channels is
 *   deferred (tracked in OSS-486).
 * - `error`: activation rejected with a non-setup error, OR a previously-online
 *   session gave up reconnecting after its bounded reconnect window.
 */
type ChannelStatus = "connecting" | "online" | "setup_required" | "reconnecting" | "stopped" | "unmanaged" | "error";
/**
 * The lifecycle control surface a Channel host uses to drive and observe
 * managed Channel activation.
 */
interface ChannelsControl {
  /**
   * Resolve once every declared Channel has settled to a terminal, non-connecting
   * state (`online` or `setup_required`). Rejects if any Channel is in `error`,
   * or — when `timeoutMs` is given — if the whole set has not settled in time.
   */
  ready(opts?: {
    timeoutMs?: number;
  }): Promise<void>;
  /** Snapshot the overall status and the per-Channel status map. */
  status(): {
    overall: ChannelStatus;
    channels: Record<string, ChannelStatus>;
  };
  /** Tear down every activated Channel. Idempotent. */
  stop(): Promise<void>;
}
/**
 * The activation engine: given a resolved {@link ChannelActivationConfig} and
 * the declared {@link Channel}, bring the Channel online and return its handle.
 * Injected in tests (a fake engine); defaults to the Realtime Gateway launcher.
 */
type ActivateChannelEngine = (config: ChannelActivationConfig, channel: index_d_exports.Channel) => Promise<ChannelsHandle>;
/**
 * Minimal structural view of the `@copilotkit/channels-intelligence`
 * `ChannelsHandle`. Declared locally (not imported) because the runtime is a
 * CJS package that must not take a static dependency on the pure-ESM
 * channels-intelligence package — the default engine reaches its launcher
 * through a dynamic `import()` instead. The manager only ever needs `stop()`.
 */
interface ChannelsHandle {
  /** Activation metadata declared to Intelligence. Unused by the manager. */
  metadata: unknown;
  /** Stop the underlying Channel(s) and release transports. */
  stop(): Promise<void>;
  /**
   * Optional seam: register a callback the handle fires when its managed
   * session drops. Retained as a per-episode drop breadcrumb; the manager drives
   * status from {@link ChannelsHandle.onStateChange} instead. Present on the
   * Realtime Gateway launcher handle; optional for non-gateway/test handles.
   */
  onClose?(cb: () => void): void;
  /**
   * Optional seam: register a connection-health observer the handle fires as its
   * managed session moves between `online` (sendable), `reconnecting` (dropped,
   * Phoenix retrying), and `gave_up` (dead after the bounded reconnect window).
   * The manager uses this to keep {@link ChannelManager.status} honest — it does
   * NOT re-activate on a drop (reconnection is delegated to the Phoenix
   * connection layer; see {@link ChannelManager}). Optional so non-gateway or
   * test handles that do not implement it are always invoked as
   * `handle.onStateChange?.(cb)`.
   */
  onStateChange?(cb: (state: "online" | "reconnecting" | "gave_up") => void): void;
}
//#endregion
export { ActivateChannelEngine, ChannelStatus, ChannelsControl };
//# sourceMappingURL=channel-manager.d.mts.map