agents/dist/experimental/channels/web/index.d.ts

A home for your AI agents

import {
  d as ChannelUpgradeMatch,
  m as ParticipantResult,
  n as Channel,
  t as Awaitable
} from "../../../channel-Bak_6zDP.js";
import {
  _ as TranscriptMessage,
  c as InboundEvent,
  i as ConversationSnapshot,
  m as ResponseChunk,
  n as ConversationInfo,
  p as Participant,
  r as ConversationOperation,
  y as TurnStatus
} from "../../../protocol-CukuI73M.js";
import { i as WebSockets } from "../../../index-CBt8oRJt.js";
import {
  a as ConversationChannel,
  o as ConversationUpdate,
  r as ChannelsHost
} from "../../../conversations-FjHDRZyD.js";

//#region src/experimental/channels/web/channel.d.ts
type WebChannelOptions = {
  /**
   * The connections to serve conversations on, for an agent sharing its own.
   * Default: the WebSockets Channels shares, created on first use.
   */
  websockets?: WebSockets;
};
/**
 * Serves conversations over the agent's WebSockets connections, to clients
 * the gateway has resolved. Frames are
 * namespaced `channels:`, so a connection can carry other protocols too.
 */
declare class WebChannel implements ConversationChannel {
  #private;
  constructor(options?: WebChannelOptions);
  mount(host: ChannelsHost): void;
  publish(conversationId: string, update: ConversationUpdate): void;
}
//#endregion
//#region src/experimental/channels/web/ingress.d.ts
/** How the gateway takes the Web Channel's WebSocket upgrades. */
type WebIngressOptions = {
  /**
   * Who is connecting, from request data you can verify, such as a session
   * cookie or an Access JWT. Return null to refuse the upgrade.
   */
  participant(request: Request): Awaitable<ParticipantResult>;
  /**
   * The agent object the participant reaches, or null to refuse them. That
   * object is the authorization boundary: whoever reaches it may use every
   * conversation in it. Default: an agent object of the participant's own.
   */
  route?(request: Request, participant: Participant): Awaitable<string | null>;
  /**
   * Which upgrades are for the Web Channel, and the conversation each
   * follows. Return undefined for one that is not. Default: `/channels`,
   * or `/channels/<conversation>`.
   */
  match?(request: Request): ChannelUpgradeMatch | undefined;
};
/**
 * The Web Channel's side in the gateway: it resolves each WebSocket upgrade
 * and forwards it to the agent, whose `WebChannel` serves the connection.
 *
 * ```ts
 * new ChannelGateway({
 *   agent: (route) => env.SupportAgent.getByName(route),
 *   channels: {
 *     web: web({
 *       participant: async (request) =>
 *         (await verifySession(request, env))?.id ?? null
 *     })
 *   }
 * });
 * ```
 */
declare function web(options: WebIngressOptions): Channel;
//#endregion
//#region src/experimental/channels/web/protocol.d.ts
/** Who a connection is: set by the gateway, read by the Web Channel. */
type WebIdentity = {
  /** The route that picked the agent. */ route: string /** The conversation to follow. Default: the agent's default for the route. */;
  conversationId?: string;
  participant: Participant;
};
/**
 * The header carrying a connection's WebIdentity from the gateway to the
 * agent. The gateway always sets it, so a client cannot supply its own; an
 * agent must not take WebSocket upgrades from any other route.
 */
declare const WEB_IDENTITY_HEADER = "x-channels-identity";
type ClientFrame =
  | {
      type: "channels:event";
      event: InboundEvent;
    }
  | {
      type: "channels:subscribe";
      responseId: string;
      from?: number;
    } /** Ask for the agent's conversations; answered by `channels:conversations`. */
  | {
      type: "channels:list-conversations";
      requestId: string;
    };
type ServerFrame = {
  conversationId: string;
} &
  /**
   * On connect, after a reset (empty), and when the connection follows
   * another conversation. `you` is this connection's participant;
   * `operations` are the conversation operations it may send.
   */
  (
    | ({
        type: "channels:snapshot";
        you: Participant;
        operations: ConversationOperation[];
      } & ConversationSnapshot)
    | {
        type: "channels:turn";
        turn: TurnStatus;
      } /** Upserts by id; an unknown id appends. */
    | {
        type: "channels:messages";
        messages: TranscriptMessage[];
      }
    | {
        type: "channels:chunks";
        responseId: string /** Seq of the first chunk. */;
        from: number;
        chunks: ResponseChunk[];
      } /** Everything before this was replay; what follows is live. */
    | {
        type: "channels:caught-up";
        responseId: string;
        cursor: number;
      }
    | {
        type: "channels:end";
        responseId: string;
        state: "ended" | "interrupted" | "not-found";
      }
    /**
     * The agent's conversations: the answer to a list request, carrying its
     * `requestId`, or pushed when one is created or forked.
     */
    | {
        type: "channels:conversations";
        requestId?: string;
        conversations?: ConversationInfo[];
        error?: string;
      } /** `conversationId` is the one a create or fork started, when it did. */
    | {
        type: "channels:ack";
        eventId: string;
        error?: string;
      }
  );
/** A frame that names a Channels type but is malformed. */
type InvalidClientFrame = {
  invalid: string;
  eventId?: string;
};
/**
 * Parse a text frame. Returns undefined for anything that is not a Channels
 * frame, so the socket's other protocols keep working.
 */
declare function parseClientFrame(
  text: string
): ClientFrame | InvalidClientFrame | undefined;
//#endregion
export {
  ClientFrame,
  InvalidClientFrame,
  ServerFrame,
  WEB_IDENTITY_HEADER,
  WebChannel,
  WebChannelOptions,
  WebIdentity,
  WebIngressOptions,
  parseClientFrame,
  web
};
//# sourceMappingURL=index.d.ts.map