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

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

require("reflect-metadata");
import "../runner/agent-runner.cjs";
import { index_d_exports } from "../../../channels/dist/index.cjs";
import { ChannelActivationConfig } from "./channel-activation-config.cjs";
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, the managed session can currently send, AND
 *   the gateway did not report the Channel as missing a managed provider. 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. Reached when the gateway reports the
 *   provider as unattached/disabled/undeclared on the control join reply (see
 *   {@link ChannelLegs}), or when the activation engine throws a
 *   `SETUP_REQUIRED` error.
 *
 *   NOTE: between the 2026-07-29 realtime-boundary cutover and the introduction
 *   of {@link ChannelLegs}, this state had NO producer — the engine stopped
 *   classifying it and nothing else set it, so a Channel with no Slack app at
 *   all reported `online`. Do not reintroduce a code path that describes
 *   `setup_required` without one that can actually emit it.
 * - `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.
 *
 * A Channel may carry developer-supplied direct adapters alongside the managed
 * Intelligence adapter. The managed engine owns the shared Channel lifecycle;
 * each adapter still receives only its own ingress and sends only its own
 * provider output.
 */
type ChannelStatus = "connecting" | "online" | "setup_required" | "reconnecting" | "stopped" | "error";
/**
 * Managed provider attachment state for one Channel, as reported by the gateway
 * on the control join reply.
 *
 * `unknown` is this package's own value for "the gateway did not tell us" — a
 * gateway predating the provider-state contract, one whose lookup failed, or a
 * non-gateway handle. It must never be read as "no provider attached".
 */
type ChannelProviderLeg = "attached" | "unhealthy" | "not_attached" | "disabled" | "channel_not_declared" | "unknown";
/**
 * The two independent things that have to be true for a managed Channel to
 * work, reported separately so a caller can assert the one it cares about.
 *
 * `status` is the fold of the two and matches this Channel's entry in
 * {@link ChannelsControl.status}'s `channels` map.
 *
 * The legs exist because they are genuinely separable: the control socket can be
 * joined and sendable while no Slack/Teams app is bound to the Channel at all.
 * Before they were split, `overall: "online"` proved only the socket, and
 * onboarding guidance used it to certify end-to-end success.
 */
interface ChannelLegs {
  /** Fold of {@link transport} and {@link provider}. */
  status: ChannelStatus;
  /** Runtime ⇄ Gateway control socket for this Channel. */
  transport: ChannelStatus;
  /** Whether a managed provider is bound to this Channel. */
  provider: ChannelProviderLeg;
}
/**
 * The lifecycle control surface a Channel host uses to drive and observe
 * managed Channel activation.
 */
interface ChannelsControl {
  /**
   * Resolve once every declared Channel has settled its ACTIVATION — that is,
   * each Channel either activated or failed to. Rejects if any Channel failed to
   * activate, or — when `timeoutMs` is given — if the whole set has not settled
   * in time.
   *
   * Readiness is about activation, NOT about provider health: a Channel whose
   * transport joined but whose provider leg is `unhealthy` folds to a status of
   * `error` (see {@link foldChannelLegs}) while its activation settled normally.
   * So `ready()` resolving and `status().overall === "error"` can both be true at
   * once, by design — provider attachment is the Gateway's answer to a question
   * asked after activation, and it can change at any later rejoin. Assert
   * end-to-end reachability with {@link ChannelsControl.status}, not here.
   */
  ready(opts?: {
    timeoutMs?: number;
  }): Promise<void>;
  /**
   * Snapshot the overall status, the per-Channel status map, and the per-Channel
   * transport/provider legs.
   *
   * `overall === "online"` does NOT by itself prove a Channel can receive
   * provider traffic unless the provider leg is `attached`: read `detail` when
   * you need to assert that a Channel is genuinely reachable from Slack/Teams,
   * because a `provider` of `unknown` leaves `status` transport-derived.
   */
  status(): {
    overall: ChannelStatus;
    channels: Record<string, ChannelStatus>;
    detail: Record<string, ChannelLegs>;
  };
  /** 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;
  /**
   * Optional seam: managed provider attachment state per declared Channel, as
   * reported on the newest gateway control join reply.
   *
   * A getter, so each read reflects the current join reply — the gateway's join
   * hooks re-fire on every auto-rejoin, so a Channel provisioned while the
   * runtime was disconnected is picked up without re-activating.
   *
   * `undefined` (or an absent method) means "not reported", NOT "no provider".
   * A gateway predating this contract, a gateway whose database read failed, and
   * a non-gateway/test handle all land here, and all must fall back to
   * transport-only status rather than claim a Channel is unprovisioned.
   */
  providerStates?(): Readonly<Record<string, string>> | undefined;
}
//#endregion
export { ActivateChannelEngine, ChannelStatus, ChannelsControl };
//# sourceMappingURL=channel-manager.d.cts.map