{"version":3,"file":"event.cjs","names":[],"sources":["../../src/language_models/event.ts"],"sourcesContent":["/**\n * Chat model streaming event protocol.\n *\n * Defines a content-block-centric event model for streaming chat model responses.\n * Events carry LangChain {@link ContentBlock} types on lifecycle boundaries\n * and explicit delta variants for incremental updates during streaming.\n *\n * ## Design Principles\n *\n * 1. **Content-block deltas have explicit merge semantics.** Text,\n *    reasoning, and data deltas append to named fields. Generic block deltas\n *    shallow-merge fields onto the active content block.\n *\n * 2. **Lifecycle completeness.** Every streamable entity has explicit start and finish\n *    events. Consumers never need to infer boundaries from absence of events.\n *\n * 3. **Interleaving allowed.** Content blocks may interleave (e.g., parallel tool calls).\n *    The only invariant: a block's start precedes its deltas, and its deltas precede\n *    its finish. No ordering constraint between different blocks.\n *\n * 4. **Provider passthrough.** Native provider events that don't map to standard types\n *    are forwarded as {@link ProviderEvent} rather than silently dropped.\n *\n * ## Lifecycle Contract\n *\n * ```\n * MessageStart\n *   -> ContentBlockStart(index=0, content=...)\n *   -> ContentBlockDelta(index=0, delta={ type: \"text-delta\", text: \"Hello\" })\n *   -> ContentBlockDelta(index=0, delta={ type: \"text-delta\", text: \" world\" })\n *   -> ContentBlockFinish(index=0, content=...)\n *   -> UsageUpdate(...)\n * -> MessageFinish(reason, usage?)\n * ```\n *\n * @module\n */\n\nimport type { ContentBlock } from \"../messages/content/index.js\";\nimport type { UsageMetadata } from \"../messages/metadata.js\";\n\n// ─── Message Lifecycle ──────────────────────────────────────────\n\n/**\n * Emitted once at the start of a model response.\n */\nexport interface MessageStartEvent {\n  event: \"message-start\";\n  /** Optional message ID assigned by the provider. */\n  id?: string;\n  /**\n   * Initial usage snapshot, if the provider reports input token counts\n   * before content begins streaming (e.g., Anthropic's `message_start`).\n   */\n  usage?: Partial<UsageMetadata>;\n}\n\n/**\n * Finish reason for a model response.\n *\n * - `\"stop\"`: Natural end of generation.\n * - `\"length\"`: Hit max token limit.\n * - `\"tool_use\"`: Model is requesting tool execution.\n * - `\"content_filter\"`: Content was filtered by safety systems.\n */\nexport type FinishReason = \"stop\" | \"length\" | \"tool_use\" | \"content_filter\";\n\n/**\n * Emitted once when the model response is complete.\n */\nexport interface MessageFinishEvent {\n  event: \"message-finish\";\n  /** Why the model stopped generating. */\n  reason?: FinishReason;\n  /** Final usage snapshot. */\n  usage?: Partial<UsageMetadata>;\n  /** Provider-specific response metadata (model name, response ID, headers, etc.). */\n  responseMetadata?: Record<string, unknown>;\n}\n\n// ─── Content Block Lifecycle ────────────────────────────────────\n// See https://github.com/langchain-ai/agent-protocol/blob/main/streaming/protocol.cddl\n\n/**\n * Emitted when a new content block begins streaming.\n *\n * @example\n * ```ts\n * { event: \"content-block-start\", index: 0,\n *   content: { type: \"text\", text: \"\" } }\n * ```\n */\nexport interface ContentBlockStartEvent {\n  event: \"content-block-start\";\n  /** Positional index of this block within the message. */\n  index: number;\n  /** Initial state of the content block. */\n  content: ContentBlock;\n}\n\n// ─── Content Block Deltas ───────────────────────────────────────\n\n/**\n * Incremental text content. Append `text` to the active block's `text` field.\n */\nexport interface TextDelta {\n  type: \"text-delta\";\n  /** The new text to append. */\n  text: string;\n}\n\n/**\n * Incremental reasoning content. Append `reasoning` to the active block's\n * `reasoning` field.\n */\nexport interface ReasoningDelta {\n  type: \"reasoning-delta\";\n  /** The new reasoning text to append. */\n  reasoning: string;\n}\n\n/**\n * Incremental encoded data. Append `data` to the active multimodal block's\n * data field.\n */\nexport interface DataDelta {\n  type: \"data-delta\";\n  /** Encoded data chunk to append. */\n  data: string;\n  /** Encoding for the data chunk. Defaults to `\"base64\"` when omitted. */\n  encoding?: \"base64\";\n}\n\n/**\n * Generic content block field update. Shallow-merge `fields` onto the active\n * content block.\n */\nexport interface BlockDelta {\n  type: \"block-delta\";\n  /** Fields to shallow-merge onto the active content block. */\n  fields: { type: string } & Record<string, unknown>;\n}\n\n/**\n * Union of all content block delta types.\n */\nexport type ContentBlockDelta =\n  | TextDelta\n  | ReasoningDelta\n  | DataDelta\n  | BlockDelta;\n\n/**\n * Emitted for each incremental update within a content block.\n *\n * The `delta` field carries the incremental content block update.\n * Accumulation rules:\n * - `text-delta` → append `text` to the active block's text field\n * - `reasoning-delta` → append `reasoning` to the active block's reasoning field\n * - `data-delta` → append `data` to the active block's data field\n * - `block-delta` → shallow-merge `fields` onto the active block\n *\n * @example\n * ```ts\n * // Text token\n * { event: \"content-block-delta\", index: 0,\n *   delta: { type: \"text-delta\", text: \" world\" } }\n *\n * // Tool call args snapshot\n * { event: \"content-block-delta\", index: 1,\n *   delta: { type: \"block-delta\",\n *     fields: { type: \"tool_call_chunk\", args: '{\"q\":\"wea' } } } }\n *\n * // Provider-specific field (e.g., signature)\n * { event: \"content-block-delta\", index: 0,\n *   delta: { type: \"block-delta\",\n *     fields: { type: \"reasoning\", signature: \"sig_abc\" } } }\n * ```\n */\nexport interface ContentBlockDeltaEvent {\n  event: \"content-block-delta\";\n  /** Positional index of the block being updated. */\n  index: number;\n  /** Incremental content block delta. */\n  delta: ContentBlockDelta;\n}\n\n/**\n * Emitted when a content block is complete.\n *\n * @example\n * ```ts\n * { event: \"content-block-finish\", index: 0,\n *   content: { type: \"text\", text: \"Hello world\" } }\n * ```\n */\nexport interface ContentBlockFinishEvent {\n  event: \"content-block-finish\";\n  /** Positional index of the completed block. */\n  index: number;\n  /** Finalized content block. */\n  content: ContentBlock;\n}\n\n// ─── Usage ──────────────────────────────────────────────────────\n\n/**\n * Emitted whenever the provider reports updated usage information.\n * Each event carries a **running snapshot** (not an additive delta).\n */\nexport interface UsageUpdateEvent {\n  event: \"usage\";\n  /** Current usage snapshot. */\n  usage: Partial<UsageMetadata>;\n}\n\n// ─── Provider Passthrough ───────────────────────────────────────\n\n/**\n * Passthrough for native provider events that don't map to standard types.\n */\nexport interface ProviderEvent {\n  event: \"provider\";\n  /** Provider identifier (e.g., `\"openai\"`, `\"anthropic\"`, `\"google\"`). */\n  provider: string;\n  /** Raw event type name from the provider SDK. */\n  name: string;\n  /** Raw event payload from the provider SDK. */\n  payload: unknown;\n}\n\n// ─── Error ──────────────────────────────────────────────────────\n\n/**\n * Emitted on unrecoverable stream errors.\n */\nexport interface StreamErrorEvent {\n  event: \"error\";\n  /** Human-readable error message. */\n  message: string;\n  /** Optional error code for programmatic handling. */\n  code?: string;\n}\n\n// ─── Union ──────────────────────────────────────────────────────\n\n/**\n * Union of all chat model stream event types.\n */\nexport type ChatModelStreamEvent =\n  | MessageStartEvent\n  | MessageFinishEvent\n  | ContentBlockStartEvent\n  | ContentBlockDeltaEvent\n  | ContentBlockFinishEvent\n  | UsageUpdateEvent\n  | ProviderEvent\n  | StreamErrorEvent;\n"],"mappings":""}