autotel-cloudflare 3.0.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel-cloudflare",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "The #1 OpenTelemetry package for Cloudflare Workers - complete bindings coverage, native CF OTel integration, advanced sampling",
   "type": "module",
   "main": "./dist/index.js",

package/src/agents/agent.ts

@@ -0,0 +1,327 @@
+import type { BaseEvent } from './base';
+
+/**
+ * Agent-specific observability events.
+ */
+export 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 }
+    >;

package/src/agents/base.ts

@@ -0,0 +1,26 @@
+/**
+ * Base event structure for all Cloudflare Agents observability events.
+ */
+export 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;
+};

package/src/agents/index.ts

@@ -17,7 +17,8 @@
  *
  *   @callable()
  *   async doSomething() {
- *     // This RPC call will be automatically traced
+ *     // RPC, chat recovery, queue/schedule, workflow, MCP, and lifecycle
+ *     // events emitted by the Agents SDK will be converted into spans.
  *     return 'done'
  *   }
  * }
@@ -31,12 +32,15 @@ export {
   createOtelObservabilityFromEnv,
   OtelObservability,
 } from './otel-observability';
+export { channels, genericObservability, subscribe } from './observability';
 export type {
+  BaseEvent,
   OtelObservabilityConfig,
   AgentObservabilityEvent,
   MCPObservabilityEvent,
   ObservabilityEvent,
   Observability,
+  ChannelEventMap,
   AgentInstrumentationOptions,
   AgentSpanAttributes,
 } from './types';

package/src/agents/mcp.ts

@@ -0,0 +1,38 @@
+import type { BaseEvent } from './base';
+
+/**
+ * MCP-specific observability events.
+ */
+export 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';
+      }
+    >;

package/src/agents/observability.ts

@@ -0,0 +1,145 @@
+import type { AgentObservabilityEvent } from './agent';
+import type { MCPObservabilityEvent } from './mcp';
+
+export type ObservabilityEvent = AgentObservabilityEvent | MCPObservabilityEvent;
+
+export interface Observability {
+  emit(event: ObservabilityEvent, ctx?: DurableObjectState | ExecutionContext): void;
+}
+
+type ChannelKey =
+  | 'state'
+  | 'rpc'
+  | 'message'
+  | 'chat'
+  | 'transcript'
+  | 'fiber'
+  | 'agentTool'
+  | 'schedule'
+  | 'lifecycle'
+  | 'workflow'
+  | 'mcp'
+  | 'email';
+
+export 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}` }>;
+};
+
+export interface ObservabilityChannel<TEvent extends ObservabilityEvent = ObservabilityEvent> {
+  name: string;
+  publish(event: TEvent): void;
+}
+
+const listeners: {
+  [K in ChannelKey]: Set<(event: ChannelEventMap[K]) => void>;
+} = {
+  state: new Set(),
+  rpc: new Set(),
+  message: new Set(),
+  chat: new Set(),
+  transcript: new Set(),
+  fiber: new Set(),
+  agentTool: new Set(),
+  schedule: new Set(),
+  lifecycle: new Set(),
+  workflow: new Set(),
+  mcp: new Set(),
+  email: new Set(),
+};
+
+function createChannel<K extends ChannelKey>(
+  key: K,
+  name: string,
+): ObservabilityChannel<ChannelEventMap[K]> {
+  return {
+    name,
+    publish(event) {
+      for (const callback of listeners[key]) {
+        callback(event);
+      }
+    },
+  };
+}
+
+export const channels = {
+  state: createChannel('state', 'agents:state'),
+  rpc: createChannel('rpc', 'agents:rpc'),
+  message: createChannel('message', 'agents:message'),
+  chat: createChannel('chat', 'agents:chat'),
+  transcript: createChannel('transcript', 'agents:transcript'),
+  fiber: createChannel('fiber', 'agents:fiber'),
+  agentTool: createChannel('agentTool', 'agents:agent_tool'),
+  schedule: createChannel('schedule', 'agents:schedule'),
+  lifecycle: createChannel('lifecycle', 'agents:lifecycle'),
+  workflow: createChannel('workflow', 'agents:workflow'),
+  mcp: createChannel('mcp', 'agents:mcp'),
+  email: createChannel('email', 'agents:email'),
+} as const;
+
+function getChannel(type: string): ObservabilityChannel {
+  if (type.startsWith('mcp:')) return channels.mcp;
+  if (type.startsWith('workflow:')) return channels.workflow;
+  if (type.startsWith('fiber:')) return channels.fiber;
+  if (type.startsWith('transcript:') || type.startsWith('chat:transcript:')) {
+    return channels.transcript;
+  }
+  if (type.startsWith('chat:')) return channels.chat;
+  if (type.startsWith('agent_tool:')) return channels.agentTool;
+  if (type.startsWith('schedule:') || type.startsWith('queue:')) {
+    return channels.schedule;
+  }
+  if (
+    type.startsWith('message:') ||
+    type.startsWith('tool:') ||
+    type.startsWith('submission:')
+  ) {
+    return channels.message;
+  }
+  if (type === 'rpc' || type.startsWith('rpc:')) return channels.rpc;
+  if (type.startsWith('state:')) return channels.state;
+  if (type.startsWith('email:')) return channels.email;
+  return channels.lifecycle;
+}
+
+export const genericObservability: Observability = {
+  emit(event) {
+    getChannel(event.type).publish(event);
+  },
+};
+
+export function subscribe<K extends keyof ChannelEventMap>(
+  channelKey: K,
+  callback: (event: ChannelEventMap[K]) => void,
+): () => void {
+  const bucket = listeners[channelKey];
+  bucket.add(callback);
+  return () => {
+    bucket.delete(callback);
+  };
+}