autotel-cloudflare 3.0.0 → 3.1.0

package/src/agents/types.ts

@@ -2,159 +2,53 @@
  * Type definitions for Cloudflare Agents SDK observability integration
  */
 
-import type { ConfigurationOption } from 'autotel-edge';
 import type { Attributes } from '@opentelemetry/api';
+import type { ConfigurationOption } from 'autotel-edge';
+import type { AgentObservabilityEvent } from './agent';
+import type { BaseEvent } from './base';
+import type { MCPObservabilityEvent } from './mcp';
+import type {
+  ChannelEventMap,
+  Observability,
+  ObservabilityEvent,
+} from './observability';
 
-/**
- * Base event structure from Agents SDK (mirrors agents/src/observability/base.ts)
- */
-export interface BaseAgentEvent<
-  T extends string,
-  Payload extends Record<string, unknown> = Record<string, unknown>
-> {
-  type: T;
-  /** Unique identifier for the event */
-  id: string;
-  /** Human-readable message for logging */
-  displayMessage: string;
-  /** Event payload with type-specific data */
-  payload: Payload & Record<string, unknown>;
-  /** Timestamp in milliseconds since epoch */
-  timestamp: number;
-}
-
-/**
- * Agent-specific observability events
- */
-export type AgentObservabilityEvent =
-  | BaseAgentEvent<'state:update', Record<string, unknown>>
-  | BaseAgentEvent<
-      'rpc',
-      {
-        method: string;
-        streaming?: boolean;
-      }
-    >
-  | BaseAgentEvent<'message:request' | 'message:response', Record<string, unknown>>
-  | BaseAgentEvent<'message:clear'>
-  | BaseAgentEvent<
-      'schedule:create' | 'schedule:execute' | 'schedule:cancel',
-      {
-        callback: string;
-        id: string;
-      }
-    >
-  | BaseAgentEvent<'destroy'>
-  | BaseAgentEvent<
-      'connect',
-      {
-        connectionId: string;
-      }
-    >;
-
-/**
- * MCP-specific observability events
- */
-export type MCPObservabilityEvent =
-  | BaseAgentEvent<'mcp:client:preconnect', { serverId: string }>
-  | BaseAgentEvent<
-      'mcp:client:connect',
-      { url: string; transport: string; state: string; error?: string }
-    >
-  | BaseAgentEvent<
-      'mcp:client:authorize',
-      {
-        serverId: string;
-        authUrl: string;
-        clientId?: string;
-      }
-    >
-  | BaseAgentEvent<'mcp:client:discover', Record<string, unknown>>;
+export type { BaseEvent, AgentObservabilityEvent, MCPObservabilityEvent };
+export type { Observability, ObservabilityEvent, ChannelEventMap };
 
-/**
- * Union of all observability event types
- */
-export type ObservabilityEvent = AgentObservabilityEvent | MCPObservabilityEvent;
-
-/**
- * Observability interface from Agents SDK
- */
-export interface Observability {
-  /**
-   * Emit an event for the Agent's observability implementation to handle.
-   * @param event - The event to emit
-   * @param ctx - The execution context of the invocation (optional)
-   */
-  emit(event: ObservabilityEvent, ctx?: DurableObjectState): void;
-}
+export type ObservabilityExecutionContext = DurableObjectState | ExecutionContext;
 
-/**
- * Agent-specific instrumentation options
- */
 export interface AgentInstrumentationOptions {
-  /**
-   * Whether to create spans for RPC calls
-   * @default true
-   */
   traceRpc?: boolean;
-
-  /**
-   * Whether to create spans for schedule operations
-   * @default true
-   */
   traceSchedule?: boolean;
-
-  /**
-   * Whether to create spans for MCP operations
-   * @default true
-   */
+  traceQueue?: boolean;
+  traceSubmissions?: boolean;
   traceMcp?: boolean;
-
-  /**
-   * Whether to create spans for state updates
-   * @default false (can be noisy)
-   */
   traceStateUpdates?: boolean;
-
-  /**
-   * Whether to create spans for message events
-   * @default true
-   */
   traceMessages?: boolean;
-
-  /**
-   * Whether to create spans for connect/destroy lifecycle events
-   * @default true
-   */
   traceLifecycle?: boolean;
-
-  /**
-   * Custom attribute extractor for events
-   */
+  traceChat?: boolean;
+  traceTranscripts?: boolean;
+  traceFibers?: boolean;
+  traceToolRecovery?: boolean;
+  traceWorkflow?: boolean;
+  traceEmail?: boolean;
   attributeExtractor?: (event: ObservabilityEvent) => Attributes;
-
-  /**
-   * Custom span name formatter
-   */
   spanNameFormatter?: (event: ObservabilityEvent) => string;
 }
 
-/**
- * Configuration for OtelObservability
- */
 export type OtelObservabilityConfig = ConfigurationOption & {
-  /**
-   * Agent-specific instrumentation options
-   */
   agents?: AgentInstrumentationOptions;
 };
 
-/**
- * Semantic attributes for Agent spans
- */
 export interface AgentSpanAttributes {
   'agent.event.type': string;
-  'agent.event.id': 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;

package/src/agents.ts

@@ -47,12 +47,20 @@
  * const observability = createOtelObservability({
  *   service: { name: 'my-agent' },
  *   agents: {
- *     traceRpc: true,           // Trace RPC calls (default: true)
- *     traceSchedule: true,      // Trace scheduled tasks (default: true)
- *     traceMcp: true,           // Trace MCP operations (default: true)
- *     traceStateUpdates: false, // Skip state updates (default: false, can be noisy)
- *     traceMessages: true,      // Trace message events (default: true)
- *     traceLifecycle: true,     // Trace connect/destroy (default: true)
+ *     traceRpc: true,            // RPC and rpc:error
+ *     traceSchedule: true,       // schedule:* events
+ *     traceQueue: true,          // queue:* events
+ *     traceSubmissions: true,    // submission:* events
+ *     traceMcp: true,            // mcp:* events
+ *     traceStateUpdates: false,  // state:update (off by default; noisy)
+ *     traceMessages: true,       // message:* and tool:* events
+ *     traceChat: true,           // chat:* recovery/stream/context events
+ *     traceTranscripts: true,    // chat:transcript:* events
+ *     traceFibers: true,         // fiber:* events
+ *     traceToolRecovery: true,   // agent_tool:* recovery events
+ *     traceWorkflow: true,       // workflow:* events
+ *     traceEmail: true,          // email:* events
+ *     traceLifecycle: true,      // connect/disconnect/destroy
  *   }
  * })
  * ```
@@ -65,12 +73,15 @@ export {
   createOtelObservabilityFromEnv,
   OtelObservability,
 } from './agents/otel-observability';
+export { channels, genericObservability, subscribe } from './agents/observability';
 export type {
+  BaseEvent,
   OtelObservabilityConfig,
   AgentObservabilityEvent,
   MCPObservabilityEvent,
   ObservabilityEvent,
   Observability,
+  ChannelEventMap,
   AgentInstrumentationOptions,
   AgentSpanAttributes,
 } from './agents/types';