autotel-cloudflare/dist/agents.d.ts

The #1 OpenTelemetry package for Cloudflare Workers - complete bindings coverage, native CF OTel integration, advanced sampling

import { t as UnknownRecord } from "./values-CRvW9g6_.js";
import { ConfigurationOption } from "autotel-edge";
import { Attributes } from "@opentelemetry/api";
//#region src/agents/base.d.ts
/**
 * Base event structure for all Cloudflare Agents observability events.
 */
type BaseEvent<T extends string, Payload extends Record<string, unknown> = Record<string, never>> = {
  type: T;
  /**
   * The class name of the agent that emitted this event
   * (e.g. "MyChatAgent").
   */
  agent?: string;
  /**
   * The instance name (Durable Object ID name) of the agent.
   */
  name?: string;
  /**
   * Optional legacy fields accepted by the Cloudflare adapter so older
   * examples can still be observed without reshaping the event.
   */
  id?: string;
  displayMessage?: string;
  payload: Payload;
  timestamp: number;
};
//#endregion
//#region src/agents/agent.d.ts
/**
 * Agent-specific observability events.
 */
type AgentObservabilityEvent = BaseEvent<'state:update'> | BaseEvent<'rpc', {
  method: string;
  streaming?: boolean;
}> | BaseEvent<'rpc:error', {
  method: string;
  error: string;
}> | BaseEvent<'message:request'> | BaseEvent<'message:response'> | BaseEvent<'message:clear'> | BaseEvent<'message:cancel', {
  requestId: string;
}> | BaseEvent<'message:error', {
  error: string;
}> | BaseEvent<'tool:result', {
  toolCallId: string;
  toolName: string;
}> | BaseEvent<'tool:approval', {
  toolCallId: string;
  approved: boolean;
}> | BaseEvent<'schedule:create', {
  callback: string;
  id: string;
}> | BaseEvent<'schedule:execute', {
  callback: string;
  id: string;
}> | BaseEvent<'schedule:cancel', {
  callback: string;
  id: string;
}> | BaseEvent<'schedule:retry', {
  callback: string;
  id: string;
  attempt: number;
  maxAttempts: number;
}> | BaseEvent<'schedule:error', {
  callback: string;
  id: string;
  error: string;
  attempts: number;
}> | BaseEvent<'schedule:duplicate_warning', {
  callback: string;
  count: number;
  type: string;
}> | BaseEvent<'queue:create', {
  callback: string;
  id: string;
}> | BaseEvent<'queue:retry', {
  callback: string;
  id: string;
  attempt: number;
  maxAttempts: number;
}> | BaseEvent<'queue:error', {
  callback: string;
  id: string;
  error: string;
  attempts: number;
}> | BaseEvent<'submission:create', {
  submissionId: string;
  requestId?: string;
  idempotencyKey?: string;
}> | BaseEvent<'submission:status', {
  submissionId: string;
  requestId?: string;
  status: string;
}> | BaseEvent<'submission:error', {
  submissionId: string;
  requestId?: string;
  error: string;
}> | BaseEvent<'fiber:run:started', {
  fiberId: string;
  fiberName: string;
  managed?: boolean;
}> | BaseEvent<'fiber:run:completed', {
  fiberId: string;
  fiberName: string;
  elapsedMs?: number;
  managed?: boolean;
}> | BaseEvent<'fiber:run:failed', {
  fiberId: string;
  fiberName: string;
  error: string;
  elapsedMs?: number;
  managed?: boolean;
}> | BaseEvent<'fiber:run:interrupted', {
  fiberId: string;
  fiberName: string;
  elapsedMs?: number;
  managed?: boolean;
  recoveryReason: 'interrupted';
}> | BaseEvent<'fiber:recovery:detected', {
  fiberId: string;
  fiberName: string;
  elapsedMs?: number;
  managed?: boolean;
  recoveryReason: 'interrupted';
}> | BaseEvent<'fiber:recovery:attempt', {
  fiberId: string;
  fiberName: string;
  managed?: boolean;
  recoveryReason: 'interrupted';
}> | BaseEvent<'fiber:recovery:handled', {
  fiberId: string;
  fiberName: string;
  status?: string;
  elapsedMs?: number;
  managed?: boolean;
}> | BaseEvent<'fiber:recovery:skipped', {
  fiberId: string;
  fiberName: string;
  reason: string;
  elapsedMs?: number;
  managed?: boolean;
}> | BaseEvent<'fiber:recovery:failed', {
  fiberId: string;
  fiberName: string;
  error: string;
  elapsedMs?: number;
  reason?: string;
}> | BaseEvent<'chat:request:failed', {
  requestId?: string;
  stage: 'parse' | 'persist' | 'turn' | 'stream' | 'recovery' | 'transcript';
  messagesPersisted?: boolean;
  error: string;
}> | BaseEvent<'chat:recovery:detected', {
  incidentId: string;
  requestId: string;
  attempt: number;
  maxAttempts: number;
  recoveryKind: 'retry' | 'continue';
}> | BaseEvent<'chat:recovery:scheduled', {
  incidentId: string;
  requestId: string;
  attempt: number;
  maxAttempts: number;
  recoveryKind: 'retry' | 'continue';
}> | BaseEvent<'chat:recovery:attempt', {
  incidentId: string;
  requestId: string;
  attempt: number;
  maxAttempts: number;
  recoveryKind: 'retry' | 'continue';
}> | BaseEvent<'chat:recovery:completed', {
  incidentId: string;
  requestId: string;
  attempt: number;
  maxAttempts: number;
  recoveryKind: 'retry' | 'continue';
}> | BaseEvent<'chat:recovery:skipped', {
  incidentId: string;
  requestId: string;
  attempt: number;
  maxAttempts: number;
  recoveryKind: 'retry' | 'continue';
  reason?: string;
}> | BaseEvent<'chat:recovery:exhausted', {
  incidentId: string;
  requestId: string;
  attempt: number;
  maxAttempts: number;
  recoveryKind: 'retry' | 'continue';
  reason: string;
}> | BaseEvent<'chat:recovery:failed', {
  incidentId: string;
  requestId: string;
  attempt: number;
  maxAttempts: number;
  recoveryKind: 'retry' | 'continue';
  reason?: string;
}> | BaseEvent<'chat:transcript:repaired', {
  requestId?: string;
  removedToolCalls: number;
  normalizedInputs: number;
  toolCallIds?: string[];
}> | BaseEvent<'chat:onstart:degraded', {
  step: 'transcript-hydration' | 'scheduled-task-reconcile' | 'durable-work-recovery';
  error: string;
}> | BaseEvent<'chat:hydration:windowed', {
  totalContentBytes: number;
  budgetBytes: number;
  hydratedMessages: number;
}> | BaseEvent<'chat:media:evicted', {
  messages: number;
  parts: number;
  bytes: number;
  externalizedBytes: number;
}> | BaseEvent<'chat:stream:stalled', {
  requestId: string;
  timeoutMs: number;
}> | BaseEvent<'chat:context:compacted', {
  reason: 'proactive' | 'reactive';
  shortened: boolean;
  requestId?: string;
  attempt?: number;
}> | BaseEvent<'agent_tool:recovery:begin', {
  runCount: number;
  totalTimeoutMs?: number;
}> | BaseEvent<'agent_tool:recovery:row', {
  runId: string;
  agentType: string;
  status: string;
  reason?: string;
  elapsedMs?: number;
}> | BaseEvent<'agent_tool:recovery:deadline', {
  runId: string;
  agentType: string;
  elapsedMs?: number;
}> | BaseEvent<'agent_tool:recovery:reattach', {
  runId: string;
  agentType: string;
  budgetMs: number;
}> | BaseEvent<'agent_tool:recovery:complete', {
  runCount: number;
  elapsedMs?: number;
}> | BaseEvent<'agent_tool:recovery:failed', {
  error: string;
}> | BaseEvent<'destroy'> | BaseEvent<'connect', {
  connectionId: string;
}> | BaseEvent<'disconnect', {
  connectionId: string;
  code: number;
  reason: string;
}> | BaseEvent<'email:receive', {
  from: string;
  to: string;
  subject?: string;
}> | BaseEvent<'email:reply', {
  from: string;
  to: string;
  subject?: string;
}> | BaseEvent<'email:send', {
  from: string;
  to: string | string[];
  subject: string;
}> | BaseEvent<'workflow:start', {
  workflowId: string;
  workflowName?: string;
}> | BaseEvent<'workflow:event', {
  workflowId: string;
  eventType?: string;
}> | BaseEvent<'workflow:approved', {
  workflowId: string;
  reason?: string;
}> | BaseEvent<'workflow:rejected', {
  workflowId: string;
  reason?: string;
}> | BaseEvent<'workflow:terminated', {
  workflowId: string;
  workflowName?: string;
}> | BaseEvent<'workflow:paused', {
  workflowId: string;
  workflowName?: string;
}> | BaseEvent<'workflow:resumed', {
  workflowId: string;
  workflowName?: string;
}> | BaseEvent<'workflow:restarted', {
  workflowId: string;
  workflowName?: string;
}>;
//#endregion
//#region src/agents/mcp.d.ts
/**
 * MCP-specific observability events.
 */
type MCPObservabilityEvent = BaseEvent<'mcp:client:preconnect', {
  serverId: string;
}> | BaseEvent<'mcp:client:connect', {
  url: string;
  transport: string;
  state: string;
  error?: string;
}> | BaseEvent<'mcp:client:authorize', {
  serverId: string;
  authUrl: string;
  clientId?: string;
}> | BaseEvent<'mcp:client:discover', {
  url?: string;
  state?: string;
  error?: string;
  capability?: string;
}> | BaseEvent<'mcp:client:close', {
  url: string;
  transport?: string;
  state: string;
  error?: string;
  phase?: 'terminate-session' | 'client-close';
}>;
//#endregion
//#region src/agents/observability.d.ts
type ObservabilityEvent = AgentObservabilityEvent | MCPObservabilityEvent;
interface Observability {
  emit(event: ObservabilityEvent, ctx?: DurableObjectState | ExecutionContext): void;
}
type ChannelEventMap = {
  state: Extract<ObservabilityEvent, {
    type: `state:${string}`;
  }>;
  rpc: Extract<ObservabilityEvent, {
    type: 'rpc' | `rpc:${string}`;
  }>;
  message: Extract<ObservabilityEvent, {
    type: `message:${string}` | `tool:${string}` | `submission:${string}`;
  }>;
  chat: Exclude<Extract<ObservabilityEvent, {
    type: `chat:${string}`;
  }>, {
    type: `chat:transcript:${string}`;
  }>;
  transcript: Extract<ObservabilityEvent, {
    type: `transcript:${string}` | `chat:transcript:${string}`;
  }>;
  fiber: Extract<ObservabilityEvent, {
    type: `fiber:${string}`;
  }>;
  agentTool: Extract<ObservabilityEvent, {
    type: `agent_tool:${string}`;
  }>;
  schedule: Extract<ObservabilityEvent, {
    type: `schedule:${string}` | `queue:${string}`;
  }>;
  lifecycle: Extract<ObservabilityEvent, {
    type: 'connect' | 'disconnect' | 'destroy';
  }>;
  workflow: Extract<ObservabilityEvent, {
    type: `workflow:${string}`;
  }>;
  mcp: Extract<ObservabilityEvent, {
    type: `mcp:${string}`;
  }>;
  email: Extract<ObservabilityEvent, {
    type: `email:${string}`;
  }>;
};
interface ObservabilityChannel<TEvent extends ObservabilityEvent = ObservabilityEvent> {
  name: string;
  publish(event: TEvent): void;
}
declare const channels: {
  readonly state: ObservabilityChannel<BaseEvent<"state:update">>;
  readonly rpc: ObservabilityChannel<BaseEvent<"rpc", {
    method: string;
    streaming?: boolean;
  }> | BaseEvent<"rpc:error", {
    method: string;
    error: string;
  }>>;
  readonly message: ObservabilityChannel<BaseEvent<"message:request"> | BaseEvent<"message:response"> | BaseEvent<"message:clear"> | BaseEvent<"message:cancel", {
    requestId: string;
  }> | BaseEvent<"message:error", {
    error: string;
  }> | BaseEvent<"tool:result", {
    toolCallId: string;
    toolName: string;
  }> | BaseEvent<"tool:approval", {
    toolCallId: string;
    approved: boolean;
  }> | BaseEvent<"submission:create", {
    submissionId: string;
    requestId?: string;
    idempotencyKey?: string;
  }> | BaseEvent<"submission:status", {
    submissionId: string;
    requestId?: string;
    status: string;
  }> | BaseEvent<"submission:error", {
    submissionId: string;
    requestId?: string;
    error: string;
  }>>;
  readonly chat: ObservabilityChannel<BaseEvent<"chat:request:failed", {
    requestId?: string;
    stage: "parse" | "persist" | "turn" | "stream" | "recovery" | "transcript";
    messagesPersisted?: boolean;
    error: string;
  }> | BaseEvent<"chat:recovery:detected", {
    incidentId: string;
    requestId: string;
    attempt: number;
    maxAttempts: number;
    recoveryKind: "retry" | "continue";
  }> | BaseEvent<"chat:recovery:scheduled", {
    incidentId: string;
    requestId: string;
    attempt: number;
    maxAttempts: number;
    recoveryKind: "retry" | "continue";
  }> | BaseEvent<"chat:recovery:attempt", {
    incidentId: string;
    requestId: string;
    attempt: number;
    maxAttempts: number;
    recoveryKind: "retry" | "continue";
  }> | BaseEvent<"chat:recovery:completed", {
    incidentId: string;
    requestId: string;
    attempt: number;
    maxAttempts: number;
    recoveryKind: "retry" | "continue";
  }> | BaseEvent<"chat:recovery:skipped", {
    incidentId: string;
    requestId: string;
    attempt: number;
    maxAttempts: number;
    recoveryKind: "retry" | "continue";
    reason?: string;
  }> | BaseEvent<"chat:recovery:exhausted", {
    incidentId: string;
    requestId: string;
    attempt: number;
    maxAttempts: number;
    recoveryKind: "retry" | "continue";
    reason: string;
  }> | BaseEvent<"chat:recovery:failed", {
    incidentId: string;
    requestId: string;
    attempt: number;
    maxAttempts: number;
    recoveryKind: "retry" | "continue";
    reason?: string;
  }> | BaseEvent<"chat:onstart:degraded", {
    step: "transcript-hydration" | "scheduled-task-reconcile" | "durable-work-recovery";
    error: string;
  }> | BaseEvent<"chat:hydration:windowed", {
    totalContentBytes: number;
    budgetBytes: number;
    hydratedMessages: number;
  }> | BaseEvent<"chat:media:evicted", {
    messages: number;
    parts: number;
    bytes: number;
    externalizedBytes: number;
  }> | BaseEvent<"chat:stream:stalled", {
    requestId: string;
    timeoutMs: number;
  }> | BaseEvent<"chat:context:compacted", {
    reason: "proactive" | "reactive";
    shortened: boolean;
    requestId?: string;
    attempt?: number;
  }>>;
  readonly transcript: ObservabilityChannel<BaseEvent<"chat:transcript:repaired", {
    requestId?: string;
    removedToolCalls: number;
    normalizedInputs: number;
    toolCallIds?: string[];
  }>>;
  readonly fiber: ObservabilityChannel<BaseEvent<"fiber:run:started", {
    fiberId: string;
    fiberName: string;
    managed?: boolean;
  }> | BaseEvent<"fiber:run:completed", {
    fiberId: string;
    fiberName: string;
    elapsedMs?: number;
    managed?: boolean;
  }> | BaseEvent<"fiber:run:failed", {
    fiberId: string;
    fiberName: string;
    error: string;
    elapsedMs?: number;
    managed?: boolean;
  }> | BaseEvent<"fiber:run:interrupted", {
    fiberId: string;
    fiberName: string;
    elapsedMs?: number;
    managed?: boolean;
    recoveryReason: "interrupted";
  }> | BaseEvent<"fiber:recovery:detected", {
    fiberId: string;
    fiberName: string;
    elapsedMs?: number;
    managed?: boolean;
    recoveryReason: "interrupted";
  }> | BaseEvent<"fiber:recovery:attempt", {
    fiberId: string;
    fiberName: string;
    managed?: boolean;
    recoveryReason: "interrupted";
  }> | BaseEvent<"fiber:recovery:handled", {
    fiberId: string;
    fiberName: string;
    status?: string;
    elapsedMs?: number;
    managed?: boolean;
  }> | BaseEvent<"fiber:recovery:skipped", {
    fiberId: string;
    fiberName: string;
    reason: string;
    elapsedMs?: number;
    managed?: boolean;
  }> | BaseEvent<"fiber:recovery:failed", {
    fiberId: string;
    fiberName: string;
    error: string;
    elapsedMs?: number;
    reason?: string;
  }>>;
  readonly agentTool: ObservabilityChannel<BaseEvent<"agent_tool:recovery:begin", {
    runCount: number;
    totalTimeoutMs?: number;
  }> | BaseEvent<"agent_tool:recovery:row", {
    runId: string;
    agentType: string;
    status: string;
    reason?: string;
    elapsedMs?: number;
  }> | BaseEvent<"agent_tool:recovery:deadline", {
    runId: string;
    agentType: string;
    elapsedMs?: number;
  }> | BaseEvent<"agent_tool:recovery:reattach", {
    runId: string;
    agentType: string;
    budgetMs: number;
  }> | BaseEvent<"agent_tool:recovery:complete", {
    runCount: number;
    elapsedMs?: number;
  }> | BaseEvent<"agent_tool:recovery:failed", {
    error: string;
  }>>;
  readonly schedule: ObservabilityChannel<BaseEvent<"schedule:create", {
    callback: string;
    id: string;
  }> | BaseEvent<"schedule:execute", {
    callback: string;
    id: string;
  }> | BaseEvent<"schedule:cancel", {
    callback: string;
    id: string;
  }> | BaseEvent<"schedule:retry", {
    callback: string;
    id: string;
    attempt: number;
    maxAttempts: number;
  }> | BaseEvent<"schedule:error", {
    callback: string;
    id: string;
    error: string;
    attempts: number;
  }> | BaseEvent<"schedule:duplicate_warning", {
    callback: string;
    count: number;
    type: string;
  }> | BaseEvent<"queue:create", {
    callback: string;
    id: string;
  }> | BaseEvent<"queue:retry", {
    callback: string;
    id: string;
    attempt: number;
    maxAttempts: number;
  }> | BaseEvent<"queue:error", {
    callback: string;
    id: string;
    error: string;
    attempts: number;
  }>>;
  readonly lifecycle: ObservabilityChannel<BaseEvent<"destroy"> | BaseEvent<"connect", {
    connectionId: string;
  }> | BaseEvent<"disconnect", {
    connectionId: string;
    code: number;
    reason: string;
  }>>;
  readonly workflow: ObservabilityChannel<BaseEvent<"workflow:start", {
    workflowId: string;
    workflowName?: string;
  }> | BaseEvent<"workflow:event", {
    workflowId: string;
    eventType?: string;
  }> | BaseEvent<"workflow:approved", {
    workflowId: string;
    reason?: string;
  }> | BaseEvent<"workflow:rejected", {
    workflowId: string;
    reason?: string;
  }> | BaseEvent<"workflow:terminated", {
    workflowId: string;
    workflowName?: string;
  }> | BaseEvent<"workflow:paused", {
    workflowId: string;
    workflowName?: string;
  }> | BaseEvent<"workflow:resumed", {
    workflowId: string;
    workflowName?: string;
  }> | BaseEvent<"workflow:restarted", {
    workflowId: string;
    workflowName?: string;
  }>>;
  readonly mcp: ObservabilityChannel<MCPObservabilityEvent>;
  readonly email: ObservabilityChannel<BaseEvent<"email:receive", {
    from: string;
    to: string;
    subject?: string;
  }> | BaseEvent<"email:reply", {
    from: string;
    to: string;
    subject?: string;
  }> | BaseEvent<"email:send", {
    from: string;
    to: string | string[];
    subject: string;
  }>>;
};
declare const genericObservability: Observability;
declare function subscribe<K extends keyof ChannelEventMap>(channelKey: K, callback: (event: ChannelEventMap[K]) => void): () => void;
//#endregion
//#region src/agents/types.d.ts
type ObservabilityExecutionContext = DurableObjectState | ExecutionContext;
interface AgentInstrumentationOptions {
  traceRpc?: boolean;
  traceSchedule?: boolean;
  traceQueue?: boolean;
  traceSubmissions?: boolean;
  traceMcp?: boolean;
  traceStateUpdates?: boolean;
  traceMessages?: boolean;
  traceLifecycle?: boolean;
  traceChat?: boolean;
  traceTranscripts?: boolean;
  traceFibers?: boolean;
  traceToolRecovery?: boolean;
  traceWorkflow?: boolean;
  traceEmail?: boolean;
  attributeExtractor?: (event: ObservabilityEvent) => Attributes;
  spanNameFormatter?: (event: ObservabilityEvent) => string;
}
type OtelObservabilityConfig = ConfigurationOption & {
  agents?: AgentInstrumentationOptions;
};
interface AgentSpanAttributes {
  'agent.event.type': string;
  'agent.event.id'?: string;
  'agent.class'?: string;
  'agent.instance.name'?: string;
  'agent.display_message'?: string;
  'agent.framework'?: string;
  'gen_ai.agent.name'?: string;
  'agent.rpc.method'?: string;
  'agent.rpc.streaming'?: boolean;
  'agent.schedule.callback'?: string;
  'agent.schedule.id'?: string;
  'agent.connection.id'?: string;
  'agent.mcp.server_id'?: string;
  'agent.mcp.url'?: string;
  'agent.mcp.transport'?: string;
  'agent.mcp.state'?: string;
}
//#endregion
//#region src/agents/otel-observability.d.ts
/**
 * OpenTelemetry-based Observability implementation
 *
 * Implements the Agents SDK Observability interface and converts
 * events into OpenTelemetry spans.
 */
declare class OtelObservability implements Observability {
  private readonly config;
  private readonly options;
  private initialized;
  constructor(config: OtelObservabilityConfig);
  private initialize;
  emit(event: ObservabilityEvent, ctx?: ObservabilityExecutionContext): void;
}
declare function createOtelObservability(config: OtelObservabilityConfig): OtelObservability;
declare function createOtelObservabilityFromEnv(env: UnknownRecord, options?: AgentInstrumentationOptions): OtelObservability;
//#endregion
export { type AgentInstrumentationOptions, type AgentObservabilityEvent, type AgentSpanAttributes, type BaseEvent, type ChannelEventMap, type MCPObservabilityEvent, type Observability, type ObservabilityEvent, OtelObservability, type OtelObservabilityConfig, channels, createOtelObservability, createOtelObservabilityFromEnv, genericObservability, subscribe };