@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 "../runner/agent-runner.mjs";
import { index_d_exports } from "../../../channels/dist/index.mjs";
import { ChannelActivationConfig } from "./channel-activation-config.mjs";
import { AbstractAgent, Message } from "@ag-ui/client";

//#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.
 * - `error`: activation rejected with a non-setup error, or a previously-online
 *   control link gave up reconnecting after its bounded reconnect window.
 *
 * Both MANAGED (Intelligence-gateway) and DIRECT (developer-supplied adapter)
 * Channels move through these states. A direct Channel is driven by the manager
 * too — it is started via {@link Channel.ɵruntime}`.start()` and reaches `online`
 * once its own transport is up — but it is NOT wired into the Intelligence
 * gateway/canonical/reliability layer: it simply runs its own adapter transport,
 * started and stopped by the manager. A direct Channel has no managed-session
 * drop signal, so it never reports `reconnecting`.
 *
 * That gap is BY DESIGN, not a deferral. Run-correctness (canonical
 * cross-surface history, one outer run and one terminal outcome, durable
 * HITL-resume-across-restart, selection pinning) and the reliability layer are
 * Intelligence-side only — see OSS-599's boundary discipline. A direct Channel's
 * ceiling is the SDK's in-process run loop. Do not "finish" this by pulling the
 * canonical/reliability layer down into the SDK: that is explicitly the thing
 * OSS-599 forbids.
 */
type ChannelStatus = "connecting" | "online" | "setup_required" | "reconnecting" | "stopped" | "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", detail?: {
    reason?: string;
    code?: string;
  }) => void): void;
}
//#endregion
export { ActivateChannelEngine, ChannelStatus, ChannelsControl };
//# sourceMappingURL=channel-manager.d.mts.map