@prefactor/core 0.1.0

package/dist/index.js.map

@@ -0,0 +1,17 @@
+{
+  "version": 3,
+  "sources": ["../src/config.ts", "../src/tracing/context.ts", "../src/tracing/span.ts", "../src/tracing/tracer.ts", "../src/utils/logging.ts", "../src/transport/http.ts", "../src/utils/serialization.ts", "../src/transport/stdio.ts"],
+  "sourcesContent": [
+    "import { z } from 'zod';\n\n/**\n * Configuration schema for HTTP transport\n */\nexport const HttpTransportConfigSchema = z.object({\n  /** API endpoint URL */\n  apiUrl: z.string().url(),\n\n  /** Authentication token */\n  apiToken: z.string().min(1),\n\n  /** Optional agent identifier */\n  agentId: z.string().optional(),\n\n  /** Optional agent version */\n  agentVersion: z.string().optional(),\n\n  /** Optional agent name */\n  agentName: z.string().optional(),\n\n  /** Optional agent description */\n  agentDescription: z.string().optional(),\n\n  /** Optional agent schema for validation (full schema object) */\n  agentSchema: z.record(z.unknown()).optional(),\n\n  /** Optional agent schema version identifier (string) */\n  agentSchemaVersion: z.string().optional(),\n\n  /** Skip schema validation */\n  skipSchema: z.boolean().default(false),\n\n  /** Request timeout in milliseconds */\n  requestTimeout: z.number().positive().default(30000),\n\n  /** Connection timeout in milliseconds */\n  connectTimeout: z.number().positive().default(10000),\n\n  /** Maximum number of retry attempts */\n  maxRetries: z.number().int().nonnegative().default(3),\n\n  /** Initial delay between retries in milliseconds */\n  initialRetryDelay: z.number().positive().default(1000),\n\n  /** Maximum delay between retries in milliseconds */\n  maxRetryDelay: z.number().positive().default(60000),\n\n  /** Multiplier for exponential backoff */\n  retryMultiplier: z.number().positive().default(2.0),\n});\n\nexport type HttpTransportConfig = z.infer<typeof HttpTransportConfigSchema>;\n\n/**\n * Partial HTTP config schema for user input (before defaults are applied)\n */\nexport const PartialHttpConfigSchema = z.object({\n  apiUrl: z.string().url(),\n  apiToken: z.string().min(1),\n  agentId: z.string().optional(),\n  agentVersion: z.string().optional(),\n  agentName: z.string().optional(),\n  agentDescription: z.string().optional(),\n  agentSchema: z.record(z.unknown()).optional(),\n  agentSchemaVersion: z.string().optional(),\n  skipSchema: z.boolean().optional(),\n  requestTimeout: z.number().positive().optional(),\n  connectTimeout: z.number().positive().optional(),\n  maxRetries: z.number().int().nonnegative().optional(),\n  initialRetryDelay: z.number().positive().optional(),\n  maxRetryDelay: z.number().positive().optional(),\n  retryMultiplier: z.number().positive().optional(),\n});\n\nexport type PartialHttpConfig = z.infer<typeof PartialHttpConfigSchema>;\n\n/**\n * Main SDK configuration schema\n */\nexport const ConfigSchema = z.object({\n  /** Transport type to use for span emission */\n  transportType: z.enum(['stdio', 'http']).default('stdio'),\n\n  /** Sampling rate (0.0 to 1.0) */\n  sampleRate: z.number().min(0).max(1).default(1.0),\n\n  /** Whether to capture span inputs */\n  captureInputs: z.boolean().default(true),\n\n  /** Whether to capture span outputs */\n  captureOutputs: z.boolean().default(true),\n\n  /** Maximum length for input strings */\n  maxInputLength: z.number().int().positive().default(10000),\n\n  /** Maximum length for output strings */\n  maxOutputLength: z.number().int().positive().default(10000),\n\n  /** HTTP transport configuration (required if transportType is 'http') */\n  httpConfig: PartialHttpConfigSchema.optional(),\n});\n\nexport type Config = z.infer<typeof ConfigSchema>;\n\n/**\n * Creates a validated configuration object by merging provided options with\n * environment variables and defaults.\n *\n * @param options - Partial configuration options\n * @returns Validated configuration object\n * @throws {z.ZodError} If configuration is invalid\n *\n * @example\n * ```typescript\n * const config = createConfig({\n *   transportType: 'http',\n *   httpConfig: {\n *     apiUrl: 'https://api.prefactor.ai',\n *     apiToken: process.env.PREFACTOR_API_TOKEN!,\n *   }\n * });\n * ```\n */\nexport function createConfig(options?: Partial<Config>): Config {\n  const config = {\n    transportType:\n      options?.transportType ??\n      (process.env.PREFACTOR_TRANSPORT as 'stdio' | 'http' | undefined) ??\n      'stdio',\n    sampleRate: options?.sampleRate ?? parseFloat(process.env.PREFACTOR_SAMPLE_RATE ?? '1.0'),\n    captureInputs: options?.captureInputs ?? process.env.PREFACTOR_CAPTURE_INPUTS !== 'false',\n    captureOutputs: options?.captureOutputs ?? process.env.PREFACTOR_CAPTURE_OUTPUTS !== 'false',\n    maxInputLength:\n      options?.maxInputLength ?? parseInt(process.env.PREFACTOR_MAX_INPUT_LENGTH ?? '10000', 10),\n    maxOutputLength:\n      options?.maxOutputLength ?? parseInt(process.env.PREFACTOR_MAX_OUTPUT_LENGTH ?? '10000', 10),\n    httpConfig: options?.httpConfig,\n  };\n\n  // Validate and return\n  return ConfigSchema.parse(config);\n}\n",
+    "import { AsyncLocalStorage } from 'node:async_hooks';\nimport type { Span } from './span.js';\n\n/**\n * Storage for the current span in async context\n */\nconst spanStorage = new AsyncLocalStorage<Span>();\n\n/**\n * SpanContext manages the current span in async execution contexts.\n * This enables automatic parent-child span relationships without manual tracking.\n *\n * Uses Node.js AsyncLocalStorage which provides async-safe context propagation.\n *\n * @example\n * ```typescript\n * const span = tracer.startSpan({ name: 'parent', ... });\n *\n * await SpanContext.runAsync(span, async () => {\n *   // Inside this function, getCurrent() returns the parent span\n *   const parent = SpanContext.getCurrent();\n *\n *   const child = tracer.startSpan({\n *     name: 'child',\n *     parentSpanId: parent?.spanId,\n *     traceId: parent?.traceId,\n *   });\n *   // ...\n * });\n * ```\n */\n// biome-ignore lint/complexity/noStaticOnlyClass: Intentional API design for namespacing context operations\nexport class SpanContext {\n  /**\n   * Get the current span from the async context\n   *\n   * @returns The current span, or undefined if no span is active\n   */\n  static getCurrent(): Span | undefined {\n    return spanStorage.getStore();\n  }\n\n  /**\n   * Run a synchronous function with the given span as the current context\n   *\n   * @param span - The span to set as current\n   * @param fn - The function to execute\n   * @returns The return value of the function\n   */\n  static run<T>(span: Span, fn: () => T): T {\n    return spanStorage.run(span, fn);\n  }\n\n  /**\n   * Run an asynchronous function with the given span as the current context\n   *\n   * @param span - The span to set as current\n   * @param fn - The async function to execute\n   * @returns A promise resolving to the return value of the function\n   */\n  static async runAsync<T>(span: Span, fn: () => Promise<T>): Promise<T> {\n    return spanStorage.run(span, fn);\n  }\n\n  /**\n   * Clear the current context (primarily for testing)\n   */\n  static clear(): void {\n    spanStorage.disable();\n  }\n}\n",
+    "/**\n * Types of spans that can be traced\n */\nexport enum SpanType {\n  AGENT = 'agent',\n  LLM = 'llm',\n  TOOL = 'tool',\n  CHAIN = 'chain',\n  RETRIEVER = 'retriever',\n}\n\n/**\n * Status of a span\n */\nexport enum SpanStatus {\n  RUNNING = 'running',\n  SUCCESS = 'success',\n  ERROR = 'error',\n}\n\n/**\n * Token usage information for LLM calls\n */\nexport interface TokenUsage {\n  promptTokens: number;\n  completionTokens: number;\n  totalTokens: number;\n}\n\n/**\n * Error information captured when a span fails\n */\nexport interface ErrorInfo {\n  errorType: string;\n  message: string;\n  stacktrace: string;\n}\n\n/**\n * A span represents a single operation in a trace\n */\nexport interface Span {\n  /** Unique identifier for this span */\n  spanId: string;\n\n  /** ID of the parent span, or null if this is a root span */\n  parentSpanId: string | null;\n\n  /** Trace ID shared by all spans in a single trace */\n  traceId: string;\n\n  /** Human-readable name for this span */\n  name: string;\n\n  /** Type of operation this span represents */\n  spanType: SpanType;\n\n  /** Start time in milliseconds since Unix epoch */\n  startTime: number;\n\n  /** End time in milliseconds since Unix epoch, or null if still running */\n  endTime: number | null;\n\n  /** Current status of the span */\n  status: SpanStatus;\n\n  /** Input data for this operation */\n  inputs: Record<string, unknown>;\n\n  /** Output data from this operation, or null if not completed */\n  outputs: Record<string, unknown> | null;\n\n  /** Token usage for LLM calls, or null if not applicable */\n  tokenUsage: TokenUsage | null;\n\n  /** Error information if the span failed, or null if successful */\n  error: ErrorInfo | null;\n\n  /** Additional metadata about this span */\n  metadata: Record<string, unknown>;\n\n  /** Tags for categorizing and filtering spans */\n  tags: string[];\n}\n",
+    "import { generate, generatePartition, type Partition } from '@prefactor/pfid';\nimport type { Transport } from '../transport/base.js';\nimport type { Span, SpanType, TokenUsage } from './span.js';\nimport { SpanStatus } from './span.js';\n\n/**\n * Options for starting a new span\n */\nexport interface StartSpanOptions {\n  /** Name of the span */\n  name: string;\n\n  /** Type of operation this span represents */\n  spanType: SpanType;\n\n  /** Input data for this operation */\n  inputs: Record<string, unknown>;\n\n  /** ID of the parent span (optional) */\n  parentSpanId?: string;\n\n  /** Trace ID to use (optional, will generate if not provided) */\n  traceId?: string;\n\n  /** Additional metadata (optional) */\n  metadata?: Record<string, unknown>;\n\n  /** Tags for categorizing the span (optional) */\n  tags?: string[];\n}\n\n/**\n * Options for ending a span\n */\nexport interface EndSpanOptions {\n  /** Output data from the operation */\n  outputs?: Record<string, unknown>;\n\n  /** Error that occurred (if any) */\n  error?: Error;\n\n  /** Token usage information (for LLM calls) */\n  tokenUsage?: TokenUsage;\n}\n\n/**\n * Tracer manages the lifecycle of spans.\n *\n * The tracer is responsible for:\n * - Creating spans with unique IDs\n * - Managing span lifecycle (start/end)\n * - Delegating to the transport layer for span emission\n * - Handling agent instance lifecycle\n *\n * @example\n * ```typescript\n * const tracer = new Tracer(transport);\n *\n * const span = tracer.startSpan({\n *   name: 'llm-call',\n *   spanType: SpanType.LLM,\n *   inputs: { prompt: 'Hello' }\n * });\n *\n * try {\n *   // ... do work ...\n *   tracer.endSpan(span, { outputs: { response: 'Hi!' } });\n * } catch (error) {\n *   tracer.endSpan(span, { error });\n * }\n * ```\n */\nexport class Tracer {\n  private partition: Partition;\n\n  /**\n   * Initialize the tracer.\n   *\n   * @param transport - The transport to use for emitting spans\n   * @param partition - The partition for ID generation. If not provided, a random partition will be generated.\n   */\n  constructor(\n    private transport: Transport,\n    partition?: Partition\n  ) {\n    this.partition = partition ?? generatePartition();\n  }\n\n  /**\n   * Start a new span\n   *\n   * @param options - Span configuration options\n   * @returns The created span\n   */\n  startSpan(options: StartSpanOptions): Span {\n    const spanId = generate(this.partition);\n    const traceId = options.traceId ?? generate(this.partition);\n\n    const span: Span = {\n      spanId,\n      parentSpanId: options.parentSpanId ?? null,\n      traceId,\n      name: options.name,\n      spanType: options.spanType,\n      startTime: Date.now(),\n      endTime: null,\n      status: SpanStatus.RUNNING,\n      inputs: options.inputs,\n      outputs: null,\n      tokenUsage: null,\n      error: null,\n      metadata: options.metadata ?? {},\n      tags: options.tags ?? [],\n    };\n\n    // AGENT spans are emitted immediately for real-time tracking\n    // They will be finished later with finishSpan()\n    if (options.spanType === 'agent') {\n      try {\n        this.transport.emit(span);\n      } catch (error) {\n        console.error('Failed to emit agent span:', error);\n      }\n    }\n\n    return span;\n  }\n\n  /**\n   * End a span and emit it to the transport\n   *\n   * @param span - The span to end\n   * @param options - End span options (outputs, error, token usage)\n   */\n  endSpan(span: Span, options?: EndSpanOptions): void {\n    span.endTime = Date.now();\n    span.outputs = options?.outputs ?? null;\n    span.tokenUsage = options?.tokenUsage ?? null;\n\n    if (options?.error) {\n      span.status = SpanStatus.ERROR;\n      span.error = {\n        errorType: options.error.constructor.name,\n        message: options.error.message,\n        stacktrace: options.error.stack ?? '',\n      };\n    } else {\n      span.status = SpanStatus.SUCCESS;\n    }\n\n    try {\n      // AGENT spans use finishSpan API (they were already emitted on start)\n      // Other span types are emitted here\n      if (span.spanType === 'agent') {\n        this.transport.finishSpan(span.spanId, span.endTime);\n      } else {\n        this.transport.emit(span);\n      }\n    } catch (error) {\n      console.error('Failed to emit/finish span:', error);\n    }\n  }\n\n  /**\n   * Signal the start of an agent instance execution\n   */\n  startAgentInstance(): void {\n    try {\n      this.transport.startAgentInstance();\n    } catch (error) {\n      console.error('Failed to start agent instance:', error);\n    }\n  }\n\n  /**\n   * Signal the completion of an agent instance execution\n   */\n  finishAgentInstance(): void {\n    try {\n      this.transport.finishAgentInstance();\n    } catch (error) {\n      console.error('Failed to finish agent instance:', error);\n    }\n  }\n\n  /**\n   * Close the tracer and flush any pending spans\n   *\n   * @returns Promise that resolves when the tracer is closed\n   */\n  async close(): Promise<void> {\n    try {\n      await this.transport.close();\n    } catch (error) {\n      console.error('Failed to close transport:', error);\n    }\n  }\n}\n",
+    "/**\n * Log levels for the SDK\n */\nenum LogLevel {\n  DEBUG = 0,\n  INFO = 1,\n  WARN = 2,\n  ERROR = 3,\n}\n\n/**\n * Logger class for the Prefactor SDK\n */\nclass Logger {\n  private static level: LogLevel = LogLevel.INFO;\n\n  constructor(private namespace: string) {}\n\n  debug(message: string, ...args: unknown[]): void {\n    if (Logger.level <= LogLevel.DEBUG) {\n      console.debug(`[prefactor:${this.namespace}] ${message}`, ...args);\n    }\n  }\n\n  info(message: string, ...args: unknown[]): void {\n    if (Logger.level <= LogLevel.INFO) {\n      console.info(`[prefactor:${this.namespace}] ${message}`, ...args);\n    }\n  }\n\n  warn(message: string, ...args: unknown[]): void {\n    if (Logger.level <= LogLevel.WARN) {\n      console.warn(`[prefactor:${this.namespace}] ${message}`, ...args);\n    }\n  }\n\n  error(message: string, ...args: unknown[]): void {\n    if (Logger.level <= LogLevel.ERROR) {\n      console.error(`[prefactor:${this.namespace}] ${message}`, ...args);\n    }\n  }\n\n  /**\n   * Set the global log level\n   */\n  static setLevel(level: 'debug' | 'info' | 'warn' | 'error'): void {\n    const levelMap = {\n      debug: LogLevel.DEBUG,\n      info: LogLevel.INFO,\n      warn: LogLevel.WARN,\n      error: LogLevel.ERROR,\n    };\n    Logger.level = levelMap[level];\n  }\n}\n\n/**\n * Get a logger instance for a specific namespace\n *\n * @param namespace - The namespace for this logger\n * @returns Logger instance\n */\nexport function getLogger(namespace: string): Logger {\n  return new Logger(namespace);\n}\n\n/**\n * Configure logging based on environment variables\n */\nexport function configureLogging(): void {\n  const level = process.env.PREFACTOR_LOG_LEVEL?.toLowerCase() as\n    | 'debug'\n    | 'info'\n    | 'warn'\n    | 'error'\n    | undefined;\n\n  if (level) {\n    Logger.setLevel(level);\n  }\n}\n",
+    "import type { HttpTransportConfig } from '../config.js';\nimport type { Span } from '../tracing/span.js';\nimport { getLogger } from '../utils/logging.js';\nimport type { Transport } from './base.js';\n\nconst logger = getLogger('http-transport');\n\n/**\n * Queue item types for background processing\n */\ninterface QueueItem {\n  type: 'span' | 'finish_span' | 'start_agent' | 'finish_agent';\n  data: unknown;\n}\n\n/**\n * HTTP transport sends spans to a remote API endpoint.\n *\n * Features:\n * - Queue-based async processing\n * - Exponential backoff retry logic\n * - Span ID mapping (SDK ID → backend ID)\n * - Agent instance lifecycle management\n * - Graceful shutdown with timeout\n *\n * @example\n * ```typescript\n * const transport = new HttpTransport({\n *   apiUrl: 'https://api.prefactor.ai',\n *   apiToken: process.env.PREFACTOR_API_TOKEN!,\n * });\n * ```\n */\nexport class HttpTransport implements Transport {\n  private queue: QueueItem[] = [];\n  private processing = false;\n  private closed = false;\n  private agentInstanceId: string | null = null;\n  private spanIdMap = new Map<string, string>();\n\n  constructor(private config: HttpTransportConfig) {\n    this.startProcessing();\n  }\n\n  /**\n   * Emit a span (adds to queue for async processing)\n   *\n   * @param span - The span to emit\n   */\n  emit(span: Span): void {\n    if (this.closed) {\n      return;\n    }\n    this.queue.push({ type: 'span', data: span });\n  }\n\n  /**\n   * Finish a previously emitted span (for AGENT spans)\n   *\n   * @param spanId - ID of the span to finish\n   * @param endTime - End time in milliseconds since Unix epoch\n   */\n  finishSpan(spanId: string, endTime: number): void {\n    if (this.closed) {\n      return;\n    }\n    const timestamp = new Date(endTime).toISOString();\n    this.queue.push({ type: 'finish_span', data: { spanId, timestamp } });\n  }\n\n  /**\n   * Signal the start of an agent instance execution\n   */\n  startAgentInstance(): void {\n    if (this.closed) {\n      return;\n    }\n    this.queue.push({ type: 'start_agent', data: null });\n  }\n\n  /**\n   * Signal the completion of an agent instance execution\n   */\n  finishAgentInstance(): void {\n    if (this.closed) {\n      return;\n    }\n    this.queue.push({ type: 'finish_agent', data: null });\n  }\n\n  /**\n   * Start background queue processing\n   */\n  private async startProcessing(): Promise<void> {\n    this.processing = true;\n\n    while (!this.closed || this.queue.length > 0) {\n      if (this.queue.length === 0) {\n        await new Promise((resolve) => setTimeout(resolve, 100));\n        continue;\n      }\n\n      const item = this.queue.shift();\n      if (!item) continue;\n\n      try {\n        // Ensure agent is registered before processing spans\n        if (!this.agentInstanceId && item.type !== 'start_agent') {\n          await this.ensureAgentRegistered();\n        }\n\n        switch (item.type) {\n          case 'span':\n            await this.sendSpan(item.data as Span);\n            break;\n          case 'finish_span':\n            await this.finishSpanHttp(item.data as { spanId: string; timestamp: string });\n            break;\n          case 'start_agent':\n            await this.startAgentInstanceHttp();\n            break;\n          case 'finish_agent':\n            await this.finishAgentInstanceHttp();\n            break;\n        }\n      } catch (error) {\n        logger.error('Error processing queue item:', error);\n      }\n    }\n\n    this.processing = false;\n  }\n\n  /**\n   * Send a span to the API\n   */\n  private async sendSpan(span: Span, retry = 0): Promise<void> {\n    const url = `${this.config.apiUrl}/api/v1/agent_spans`;\n    const payload = this.transformSpanToApiFormat(span);\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${this.config.apiToken}`,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify(payload),\n        signal: AbortSignal.timeout(this.config.requestTimeout),\n      });\n\n      if (response.ok) {\n        const data = (await response.json()) as { details?: { id?: string } };\n        const backendSpanId = data?.details?.id;\n        if (backendSpanId) {\n          this.spanIdMap.set(span.spanId, backendSpanId);\n        }\n        return;\n      }\n\n      // Retry on server errors or rate limiting\n      if ((response.status >= 500 || response.status === 429) && retry < this.config.maxRetries) {\n        const delay = Math.min(\n          this.config.initialRetryDelay * this.config.retryMultiplier ** retry,\n          this.config.maxRetryDelay\n        );\n        logger.debug(`Retrying span send after ${delay}ms (attempt ${retry + 1})`);\n        await new Promise((resolve) => setTimeout(resolve, delay));\n        return this.sendSpan(span, retry + 1);\n      }\n\n      logger.error(`Failed to send span: ${response.status} ${response.statusText}`);\n    } catch (error) {\n      logger.error('Error sending span:', error);\n\n      // Retry on network errors\n      if (retry < this.config.maxRetries) {\n        const delay = Math.min(\n          this.config.initialRetryDelay * this.config.retryMultiplier ** retry,\n          this.config.maxRetryDelay\n        );\n        await new Promise((resolve) => setTimeout(resolve, delay));\n        return this.sendSpan(span, retry + 1);\n      }\n    }\n  }\n\n  /**\n   * Transform span to backend API format with nested details/payload structure\n   */\n  private transformSpanToApiFormat(span: Span): Record<string, unknown> {\n    const startedAt = new Date(span.startTime).toISOString();\n    const finishedAt = span.endTime ? new Date(span.endTime).toISOString() : null;\n\n    // Build payload with span data\n    const payload: Record<string, unknown> = {\n      span_id: span.spanId,\n      trace_id: span.traceId,\n      name: span.name,\n      status: span.status,\n      inputs: span.inputs,\n      outputs: span.outputs,\n      metadata: span.metadata,\n      tags: span.tags,\n      token_usage: null,\n      error: null,\n    };\n\n    // Add optional token_usage\n    if (span.tokenUsage) {\n      payload.token_usage = {\n        prompt_tokens: span.tokenUsage.promptTokens,\n        completion_tokens: span.tokenUsage.completionTokens,\n        total_tokens: span.tokenUsage.totalTokens,\n      };\n    }\n\n    // Add optional error\n    if (span.error) {\n      payload.error = {\n        error_type: span.error.errorType,\n        message: span.error.message,\n        stacktrace: span.error.stacktrace,\n      };\n    }\n\n    // Resolve parent span ID to backend ID\n    const parentSpanId = span.parentSpanId ? (this.spanIdMap.get(span.parentSpanId) ?? null) : null;\n\n    return {\n      details: {\n        agent_instance_id: this.agentInstanceId,\n        schema_name: span.spanType,\n        payload,\n        parent_span_id: parentSpanId,\n        started_at: startedAt,\n        finished_at: finishedAt,\n      },\n    };\n  }\n\n  /**\n   * Get default schema (v1.0.0) with span schemas for all supported types\n   */\n  private getDefaultSchema(): Record<string, unknown> {\n    return {\n      external_identifier: '1.0.0',\n      span_schemas: {\n        agent: {\n          type: 'object',\n          properties: { type: { type: 'string', const: 'agent' } },\n        },\n        llm: {\n          type: 'object',\n          properties: { type: { type: 'string', const: 'llm' } },\n        },\n        tool: {\n          type: 'object',\n          properties: { type: { type: 'string', const: 'tool' } },\n        },\n        chain: {\n          type: 'object',\n          properties: { type: { type: 'string', const: 'chain' } },\n        },\n        retriever: {\n          type: 'object',\n          properties: { type: { type: 'string', const: 'retriever' } },\n        },\n      },\n    };\n  }\n\n  /**\n   * Ensure an agent instance is registered\n   */\n  private async ensureAgentRegistered(): Promise<void> {\n    if (this.agentInstanceId) {\n      return;\n    }\n\n    const url = `${this.config.apiUrl}/api/v1/agent_instance/register`;\n    const payload: Record<string, unknown> = {};\n\n    if (this.config.agentId) payload.agent_id = this.config.agentId;\n    if (this.config.agentVersion) {\n      payload.agent_version = {\n        external_identifier: this.config.agentVersion,\n        name: this.config.agentName || 'Agent',\n        description: this.config.agentDescription || '',\n      };\n    }\n\n    // Schema handling - four modes:\n    // 1. skipSchema=true: No schema in payload (pre-registered on backend)\n    // 2. agentSchema provided: Use full custom schema object\n    // 3. agentSchemaVersion provided: Use version identifier only\n    // 4. None of above: Use default v1.0.0 schema\n    if (this.config.skipSchema) {\n      logger.debug('Skipping schema in registration (skipSchema=true)');\n      // Do not add agent_schema_version key\n    } else if (this.config.agentSchema) {\n      logger.debug('Using custom agent schema');\n      payload.agent_schema_version = this.config.agentSchema;\n    } else if (this.config.agentSchemaVersion) {\n      logger.debug(`Using schema version: ${this.config.agentSchemaVersion}`);\n      payload.agent_schema_version = {\n        external_identifier: this.config.agentSchemaVersion,\n      };\n    } else {\n      logger.debug('Using default hardcoded schema (v1.0.0)');\n      payload.agent_schema_version = this.getDefaultSchema();\n    }\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${this.config.apiToken}`,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify(payload),\n        signal: AbortSignal.timeout(this.config.requestTimeout),\n      });\n\n      if (response.ok) {\n        const data = (await response.json()) as { details?: { id?: string } };\n        this.agentInstanceId = data?.details?.id ?? null;\n        logger.debug(`Registered agent instance: ${this.agentInstanceId}`);\n      } else {\n        logger.error(`Failed to register agent: ${response.status} ${response.statusText}`);\n      }\n    } catch (error) {\n      logger.error('Error registering agent:', error);\n    }\n  }\n\n  /**\n   * Start agent instance execution\n   */\n  private async startAgentInstanceHttp(): Promise<void> {\n    await this.ensureAgentRegistered();\n\n    if (!this.agentInstanceId) {\n      logger.error('Cannot start agent instance: not registered');\n      return;\n    }\n\n    const url = `${this.config.apiUrl}/api/v1/agent_instance/${this.agentInstanceId}/start`;\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${this.config.apiToken}`,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({}),\n        signal: AbortSignal.timeout(this.config.requestTimeout),\n      });\n\n      if (!response.ok) {\n        logger.error(`Failed to start agent instance: ${response.status} ${response.statusText}`);\n      }\n    } catch (error) {\n      logger.error('Error starting agent instance:', error);\n    }\n  }\n\n  /**\n   * Finish agent instance execution\n   */\n  private async finishAgentInstanceHttp(): Promise<void> {\n    if (!this.agentInstanceId) {\n      logger.error('Cannot finish agent instance: not registered');\n      return;\n    }\n\n    const url = `${this.config.apiUrl}/api/v1/agent_instance/${this.agentInstanceId}/finish`;\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${this.config.apiToken}`,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({}),\n        signal: AbortSignal.timeout(this.config.requestTimeout),\n      });\n\n      if (!response.ok) {\n        logger.error(`Failed to finish agent instance: ${response.status} ${response.statusText}`);\n      }\n    } catch (error) {\n      logger.error('Error finishing agent instance:', error);\n    }\n  }\n\n  /**\n   * Finish a span via HTTP\n   */\n  private async finishSpanHttp(data: { spanId: string; timestamp: string }): Promise<void> {\n    const backendSpanId = this.spanIdMap.get(data.spanId);\n    if (!backendSpanId) {\n      logger.warn(`Cannot finish span ${data.spanId}: backend ID not found`);\n      return;\n    }\n\n    const url = `${this.config.apiUrl}/api/v1/agent_spans/${backendSpanId}/finish`;\n\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${this.config.apiToken}`,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({ timestamp: data.timestamp }),\n        signal: AbortSignal.timeout(this.config.requestTimeout),\n      });\n\n      if (!response.ok) {\n        logger.error(`Failed to finish span: ${response.status} ${response.statusText}`);\n      }\n    } catch (error) {\n      logger.error('Error finishing span:', error);\n    }\n  }\n\n  /**\n   * Close the transport and wait for queue to drain\n   *\n   * @returns Promise that resolves when transport is closed\n   */\n  async close(): Promise<void> {\n    this.closed = true;\n\n    // Wait for queue to drain (with timeout)\n    const timeout = 10000;\n    const start = Date.now();\n    while (this.processing && Date.now() - start < timeout) {\n      await new Promise((resolve) => setTimeout(resolve, 100));\n    }\n\n    if (this.processing) {\n      logger.warn('Transport closed with pending queue items');\n    }\n  }\n}\n",
+    "/**\n * Truncate a string to a maximum length, adding an ellipsis if truncated\n *\n * @param value - The string to truncate\n * @param maxLength - Maximum length\n * @returns Truncated string\n */\nexport function truncateString(value: string, maxLength: number): string {\n  if (value.length <= maxLength) {\n    return value;\n  }\n  return `${value.slice(0, maxLength)}... [truncated]`;\n}\n\n/**\n * Serialize a value for JSON output, handling non-serializable types and\n * truncating long strings\n *\n * @param value - Value to serialize\n * @param maxLength - Maximum length for strings (null for no truncation)\n * @returns Serialized value\n *\n * @example\n * ```typescript\n * const serialized = serializeValue({ message: 'Hello'.repeat(1000) }, 100);\n * // Result: { message: 'HelloHelloHello... [truncated]' }\n * ```\n */\nexport function serializeValue(value: unknown, maxLength: number | null = 10000): unknown {\n  // Handle primitives that don't need serialization\n  if (value === null || value === undefined) {\n    return value;\n  }\n\n  if (typeof value === 'boolean' || typeof value === 'number') {\n    return value;\n  }\n\n  // Handle strings with truncation\n  if (typeof value === 'string') {\n    return maxLength !== null ? truncateString(value, maxLength) : value;\n  }\n\n  // Handle arrays\n  if (Array.isArray(value)) {\n    return value.map((item) => serializeValue(item, maxLength));\n  }\n\n  // Handle objects\n  if (typeof value === 'object') {\n    const result: Record<string, unknown> = {};\n    for (const [key, val] of Object.entries(value)) {\n      result[key] = serializeValue(val, maxLength);\n    }\n    return result;\n  }\n\n  // Handle other types by converting to string\n  try {\n    return String(value);\n  } catch {\n    return `<${typeof value} object>`;\n  }\n}\n",
+    "import type { Span } from '../tracing/span.js';\nimport { serializeValue } from '../utils/serialization.js';\nimport type { Transport } from './base.js';\n\n/**\n * STDIO transport emits spans as newline-delimited JSON to stdout.\n *\n * This is the default transport and requires no configuration.\n * It's useful for local development and for piping span data to other tools.\n *\n * Features:\n * - Newline-delimited JSON output\n * - Promise-based write locking for ordering\n * - Graceful error handling\n *\n * @example\n * ```typescript\n * const transport = new StdioTransport();\n * const tracer = new Tracer(transport);\n * ```\n */\nexport class StdioTransport implements Transport {\n  private closed = false;\n  private writeLock = Promise.resolve();\n\n  /**\n   * Emit a span to stdout as JSON\n   *\n   * @param span - The span to emit\n   */\n  emit(span: Span): void {\n    if (this.closed) {\n      return;\n    }\n\n    // Queue write to maintain ordering\n    this.writeLock = this.writeLock.then(async () => {\n      try {\n        const serialized = serializeValue(span);\n        const json = JSON.stringify(serialized);\n        await Bun.write(Bun.stdout, `${json}\\n`);\n      } catch (error) {\n        console.error('Failed to emit span to stdout:', error);\n      }\n    });\n  }\n\n  /**\n   * No-op for stdio transport (not applicable)\n   */\n  finishSpan(): void {\n    // No-op for stdio transport\n  }\n\n  /**\n   * No-op for stdio transport (not applicable)\n   */\n  startAgentInstance(): void {\n    // No-op for stdio transport\n  }\n\n  /**\n   * No-op for stdio transport (not applicable)\n   */\n  finishAgentInstance(): void {\n    // No-op for stdio transport\n  }\n\n  /**\n   * Close the transport and wait for pending writes to complete\n   *\n   * @returns Promise that resolves when all writes are complete\n   */\n  async close(): Promise<void> {\n    this.closed = true;\n    await this.writeLock;\n  }\n}\n"
+  ],
+  "mappings": ";AAAA;AAKO,IAAM,4BAA4B,EAAE,OAAO;AAAA,EAEhD,QAAQ,EAAE,OAAO,EAAE,IAAI;AAAA,EAGvB,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EAG1B,SAAS,EAAE,OAAO,EAAE,SAAS;AAAA,EAG7B,cAAc,EAAE,OAAO,EAAE,SAAS;AAAA,EAGlC,WAAW,EAAE,OAAO,EAAE,SAAS;AAAA,EAG/B,kBAAkB,EAAE,OAAO,EAAE,SAAS;AAAA,EAGtC,aAAa,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS;AAAA,EAG5C,oBAAoB,EAAE,OAAO,EAAE,SAAS;AAAA,EAGxC,YAAY,EAAE,QAAQ,EAAE,QAAQ,KAAK;AAAA,EAGrC,gBAAgB,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,KAAK;AAAA,EAGnD,gBAAgB,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,GAAK;AAAA,EAGnD,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,CAAC;AAAA,EAGpD,mBAAmB,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,IAAI;AAAA,EAGrD,eAAe,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,KAAK;AAAA,EAGlD,iBAAiB,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAG;AACpD,CAAC;AAOM,IAAM,0BAA0B,EAAE,OAAO;AAAA,EAC9C,QAAQ,EAAE,OAAO,EAAE,IAAI;AAAA,EACvB,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EAC1B,SAAS,EAAE,OAAO,EAAE,SAAS;AAAA,EAC7B,cAAc,EAAE,OAAO,EAAE,SAAS;AAAA,EAClC,WAAW,EAAE,OAAO,EAAE,SAAS;AAAA,EAC/B,kBAAkB,EAAE,OAAO,EAAE,SAAS;AAAA,EACtC,aAAa,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS;AAAA,EAC5C,oBAAoB,EAAE,OAAO,EAAE,SAAS;AAAA,EACxC,YAAY,EAAE,QAAQ,EAAE,SAAS;AAAA,EACjC,gBAAgB,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS;AAAA,EAC/C,gBAAgB,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS;AAAA,EAC/C,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS;AAAA,EACpD,mBAAmB,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS;AAAA,EAClD,eAAe,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS;AAAA,EAC9C,iBAAiB,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS;AAClD,CAAC;AAOM,IAAM,eAAe,EAAE,OAAO;AAAA,EAEnC,eAAe,EAAE,KAAK,CAAC,SAAS,MAAM,CAAC,EAAE,QAAQ,OAAO;AAAA,EAGxD,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAG;AAAA,EAGhD,eAAe,EAAE,QAAQ,EAAE,QAAQ,IAAI;AAAA,EAGvC,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,IAAI;AAAA,EAGxC,gBAAgB,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,GAAK;AAAA,EAGzD,iBAAiB,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,GAAK;AAAA,EAG1D,YAAY,wBAAwB,SAAS;AAC/C,CAAC;AAuBM,SAAS,YAAY,CAAC,SAAmC;AAAA,EAC9D,MAAM,SAAS;AAAA,IACb,eACE,SAAS,iBACR,QAAQ,IAAI,uBACb;AAAA,IACF,YAAY,SAAS,cAAc,WAAW,QAAQ,IAAI,yBAAyB,KAAK;AAAA,IACxF,eAAe,SAAS,iBAAiB,QAAQ,IAAI,6BAA6B;AAAA,IAClF,gBAAgB,SAAS,kBAAkB,QAAQ,IAAI,8BAA8B;AAAA,IACrF,gBACE,SAAS,kBAAkB,SAAS,QAAQ,IAAI,8BAA8B,SAAS,EAAE;AAAA,IAC3F,iBACE,SAAS,mBAAmB,SAAS,QAAQ,IAAI,+BAA+B,SAAS,EAAE;AAAA,IAC7F,YAAY,SAAS;AAAA,EACvB;AAAA,EAGA,OAAO,aAAa,MAAM,MAAM;AAAA;;AC7IlC;AAMA,IAAM,cAAc,IAAI;AAAA;AA0BjB,MAAM,YAAY;AAAA,SAMhB,UAAU,GAAqB;AAAA,IACpC,OAAO,YAAY,SAAS;AAAA;AAAA,SAUvB,GAAM,CAAC,MAAY,IAAgB;AAAA,IACxC,OAAO,YAAY,IAAI,MAAM,EAAE;AAAA;AAAA,cAUpB,SAAW,CAAC,MAAY,IAAkC;AAAA,IACrE,OAAO,YAAY,IAAI,MAAM,EAAE;AAAA;AAAA,SAM1B,KAAK,GAAS;AAAA,IACnB,YAAY,QAAQ;AAAA;AAExB;;ACnEO,IAAK;AAAA,CAAL,CAAK,cAAL;AAAA,EACL,qBAAQ;AAAA,EACR,mBAAM;AAAA,EACN,oBAAO;AAAA,EACP,qBAAQ;AAAA,EACR,yBAAY;AAAA,GALF;AAWL,IAAK;AAAA,CAAL,CAAK,gBAAL;AAAA,EACL,yBAAU;AAAA,EACV,yBAAU;AAAA,EACV,uBAAQ;AAAA,GAHE;;ACdZ;AAwEO,MAAM,OAAO;AAAA,EAUR;AAAA,EATF;AAAA,EAQR,WAAW,CACD,WACR,WACA;AAAA,IAFQ;AAAA,IAGR,KAAK,YAAY,aAAa,kBAAkB;AAAA;AAAA,EASlD,SAAS,CAAC,SAAiC;AAAA,IACzC,MAAM,SAAS,SAAS,KAAK,SAAS;AAAA,IACtC,MAAM,UAAU,QAAQ,WAAW,SAAS,KAAK,SAAS;AAAA,IAE1D,MAAM,OAAa;AAAA,MACjB;AAAA,MACA,cAAc,QAAQ,gBAAgB;AAAA,MACtC;AAAA,MACA,MAAM,QAAQ;AAAA,MACd,UAAU,QAAQ;AAAA,MAClB,WAAW,KAAK,IAAI;AAAA,MACpB,SAAS;AAAA,MACT;AAAA,MACA,QAAQ,QAAQ;AAAA,MAChB,SAAS;AAAA,MACT,YAAY;AAAA,MACZ,OAAO;AAAA,MACP,UAAU,QAAQ,YAAY,CAAC;AAAA,MAC/B,MAAM,QAAQ,QAAQ,CAAC;AAAA,IACzB;AAAA,IAIA,IAAI,QAAQ,aAAa,SAAS;AAAA,MAChC,IAAI;AAAA,QACF,KAAK,UAAU,KAAK,IAAI;AAAA,QACxB,OAAO,OAAO;AAAA,QACd,QAAQ,MAAM,8BAA8B,KAAK;AAAA;AAAA,IAErD;AAAA,IAEA,OAAO;AAAA;AAAA,EAST,OAAO,CAAC,MAAY,SAAgC;AAAA,IAClD,KAAK,UAAU,KAAK,IAAI;AAAA,IACxB,KAAK,UAAU,SAAS,WAAW;AAAA,IACnC,KAAK,aAAa,SAAS,cAAc;AAAA,IAEzC,IAAI,SAAS,OAAO;AAAA,MAClB,KAAK;AAAA,MACL,KAAK,QAAQ;AAAA,QACX,WAAW,QAAQ,MAAM,YAAY;AAAA,QACrC,SAAS,QAAQ,MAAM;AAAA,QACvB,YAAY,QAAQ,MAAM,SAAS;AAAA,MACrC;AAAA,IACF,EAAO;AAAA,MACL,KAAK;AAAA;AAAA,IAGP,IAAI;AAAA,MAGF,IAAI,KAAK,aAAa,SAAS;AAAA,QAC7B,KAAK,UAAU,WAAW,KAAK,QAAQ,KAAK,OAAO;AAAA,MACrD,EAAO;AAAA,QACL,KAAK,UAAU,KAAK,IAAI;AAAA;AAAA,MAE1B,OAAO,OAAO;AAAA,MACd,QAAQ,MAAM,+BAA+B,KAAK;AAAA;AAAA;AAAA,EAOtD,kBAAkB,GAAS;AAAA,IACzB,IAAI;AAAA,MACF,KAAK,UAAU,mBAAmB;AAAA,MAClC,OAAO,OAAO;AAAA,MACd,QAAQ,MAAM,mCAAmC,KAAK;AAAA;AAAA;AAAA,EAO1D,mBAAmB,GAAS;AAAA,IAC1B,IAAI;AAAA,MACF,KAAK,UAAU,oBAAoB;AAAA,MACnC,OAAO,OAAO;AAAA,MACd,QAAQ,MAAM,oCAAoC,KAAK;AAAA;AAAA;AAAA,OASrD,MAAK,GAAkB;AAAA,IAC3B,IAAI;AAAA,MACF,MAAM,KAAK,UAAU,MAAM;AAAA,MAC3B,OAAO,OAAO;AAAA,MACd,QAAQ,MAAM,8BAA8B,KAAK;AAAA;AAAA;AAGvD;;ACxLA,MAAM,OAAO;AAAA,EAGS;AAAA,SAFL,QAAkB;AAAA,EAEjC,WAAW,CAAS,WAAmB;AAAA,IAAnB;AAAA;AAAA,EAEpB,KAAK,CAAC,YAAoB,MAAuB;AAAA,IAC/C,IAAI,OAAO,SAAS,eAAgB;AAAA,MAClC,QAAQ,MAAM,cAAc,KAAK,cAAc,WAAW,GAAG,IAAI;AAAA,IACnE;AAAA;AAAA,EAGF,IAAI,CAAC,YAAoB,MAAuB;AAAA,IAC9C,IAAI,OAAO,SAAS,cAAe;AAAA,MACjC,QAAQ,KAAK,cAAc,KAAK,cAAc,WAAW,GAAG,IAAI;AAAA,IAClE;AAAA;AAAA,EAGF,IAAI,CAAC,YAAoB,MAAuB;AAAA,IAC9C,IAAI,OAAO,SAAS,cAAe;AAAA,MACjC,QAAQ,KAAK,cAAc,KAAK,cAAc,WAAW,GAAG,IAAI;AAAA,IAClE;AAAA;AAAA,EAGF,KAAK,CAAC,YAAoB,MAAuB;AAAA,IAC/C,IAAI,OAAO,SAAS,eAAgB;AAAA,MAClC,QAAQ,MAAM,cAAc,KAAK,cAAc,WAAW,GAAG,IAAI;AAAA,IACnE;AAAA;AAAA,SAMK,QAAQ,CAAC,OAAkD;AAAA,IAChE,MAAM,WAAW;AAAA,MACf,OAAO;AAAA,MACP,MAAM;AAAA,MACN,MAAM;AAAA,MACN,OAAO;AAAA,IACT;AAAA,IACA,OAAO,QAAQ,SAAS;AAAA;AAE5B;AAQO,SAAS,SAAS,CAAC,WAA2B;AAAA,EACnD,OAAO,IAAI,OAAO,SAAS;AAAA;AAMtB,SAAS,gBAAgB,GAAS;AAAA,EACvC,MAAM,QAAQ,QAAQ,IAAI,qBAAqB,YAAY;AAAA,EAO3D,IAAI,OAAO;AAAA,IACT,OAAO,SAAS,KAAK;AAAA,EACvB;AAAA;;;AC1EF,IAAM,SAAS,UAAU,gBAAgB;AAAA;AA4BlC,MAAM,cAAmC;AAAA,EAO1B;AAAA,EANZ,QAAqB,CAAC;AAAA,EACtB,aAAa;AAAA,EACb,SAAS;AAAA,EACT,kBAAiC;AAAA,EACjC,YAAY,IAAI;AAAA,EAExB,WAAW,CAAS,QAA6B;AAAA,IAA7B;AAAA,IAClB,KAAK,gBAAgB;AAAA;AAAA,EAQvB,IAAI,CAAC,MAAkB;AAAA,IACrB,IAAI,KAAK,QAAQ;AAAA,MACf;AAAA,IACF;AAAA,IACA,KAAK,MAAM,KAAK,EAAE,MAAM,QAAQ,MAAM,KAAK,CAAC;AAAA;AAAA,EAS9C,UAAU,CAAC,QAAgB,SAAuB;AAAA,IAChD,IAAI,KAAK,QAAQ;AAAA,MACf;AAAA,IACF;AAAA,IACA,MAAM,YAAY,IAAI,KAAK,OAAO,EAAE,YAAY;AAAA,IAChD,KAAK,MAAM,KAAK,EAAE,MAAM,eAAe,MAAM,EAAE,QAAQ,UAAU,EAAE,CAAC;AAAA;AAAA,EAMtE,kBAAkB,GAAS;AAAA,IACzB,IAAI,KAAK,QAAQ;AAAA,MACf;AAAA,IACF;AAAA,IACA,KAAK,MAAM,KAAK,EAAE,MAAM,eAAe,MAAM,KAAK,CAAC;AAAA;AAAA,EAMrD,mBAAmB,GAAS;AAAA,IAC1B,IAAI,KAAK,QAAQ;AAAA,MACf;AAAA,IACF;AAAA,IACA,KAAK,MAAM,KAAK,EAAE,MAAM,gBAAgB,MAAM,KAAK,CAAC;AAAA;AAAA,OAMxC,gBAAe,GAAkB;AAAA,IAC7C,KAAK,aAAa;AAAA,IAElB,OAAO,CAAC,KAAK,UAAU,KAAK,MAAM,SAAS,GAAG;AAAA,MAC5C,IAAI,KAAK,MAAM,WAAW,GAAG;AAAA,QAC3B,MAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,GAAG,CAAC;AAAA,QACvD;AAAA,MACF;AAAA,MAEA,MAAM,OAAO,KAAK,MAAM,MAAM;AAAA,MAC9B,IAAI,CAAC;AAAA,QAAM;AAAA,MAEX,IAAI;AAAA,QAEF,IAAI,CAAC,KAAK,mBAAmB,KAAK,SAAS,eAAe;AAAA,UACxD,MAAM,KAAK,sBAAsB;AAAA,QACnC;AAAA,QAEA,QAAQ,KAAK;AAAA,eACN;AAAA,YACH,MAAM,KAAK,SAAS,KAAK,IAAY;AAAA,YACrC;AAAA,eACG;AAAA,YACH,MAAM,KAAK,eAAe,KAAK,IAA6C;AAAA,YAC5E;AAAA,eACG;AAAA,YACH,MAAM,KAAK,uBAAuB;AAAA,YAClC;AAAA,eACG;AAAA,YACH,MAAM,KAAK,wBAAwB;AAAA,YACnC;AAAA;AAAA,QAEJ,OAAO,OAAO;AAAA,QACd,OAAO,MAAM,gCAAgC,KAAK;AAAA;AAAA,IAEtD;AAAA,IAEA,KAAK,aAAa;AAAA;AAAA,OAMN,SAAQ,CAAC,MAAY,QAAQ,GAAkB;AAAA,IAC3D,MAAM,MAAM,GAAG,KAAK,OAAO;AAAA,IAC3B,MAAM,UAAU,KAAK,yBAAyB,IAAI;AAAA,IAElD,IAAI;AAAA,MACF,MAAM,WAAW,MAAM,MAAM,KAAK;AAAA,QAChC,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,eAAe,UAAU,KAAK,OAAO;AAAA,UACrC,gBAAgB;AAAA,QAClB;AAAA,QACA,MAAM,KAAK,UAAU,OAAO;AAAA,QAC5B,QAAQ,YAAY,QAAQ,KAAK,OAAO,cAAc;AAAA,MACxD,CAAC;AAAA,MAED,IAAI,SAAS,IAAI;AAAA,QACf,MAAM,OAAQ,MAAM,SAAS,KAAK;AAAA,QAClC,MAAM,gBAAgB,MAAM,SAAS;AAAA,QACrC,IAAI,eAAe;AAAA,UACjB,KAAK,UAAU,IAAI,KAAK,QAAQ,aAAa;AAAA,QAC/C;AAAA,QACA;AAAA,MACF;AAAA,MAGA,KAAK,SAAS,UAAU,OAAO,SAAS,WAAW,QAAQ,QAAQ,KAAK,OAAO,YAAY;AAAA,QACzF,MAAM,QAAQ,KAAK,IACjB,KAAK,OAAO,oBAAoB,KAAK,OAAO,mBAAmB,OAC/D,KAAK,OAAO,aACd;AAAA,QACA,OAAO,MAAM,4BAA4B,oBAAoB,QAAQ,IAAI;AAAA,QACzE,MAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,KAAK,CAAC;AAAA,QACzD,OAAO,KAAK,SAAS,MAAM,QAAQ,CAAC;AAAA,MACtC;AAAA,MAEA,OAAO,MAAM,wBAAwB,SAAS,UAAU,SAAS,YAAY;AAAA,MAC7E,OAAO,OAAO;AAAA,MACd,OAAO,MAAM,uBAAuB,KAAK;AAAA,MAGzC,IAAI,QAAQ,KAAK,OAAO,YAAY;AAAA,QAClC,MAAM,QAAQ,KAAK,IACjB,KAAK,OAAO,oBAAoB,KAAK,OAAO,mBAAmB,OAC/D,KAAK,OAAO,aACd;AAAA,QACA,MAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,KAAK,CAAC;AAAA,QACzD,OAAO,KAAK,SAAS,MAAM,QAAQ,CAAC;AAAA,MACtC;AAAA;AAAA;AAAA,EAOI,wBAAwB,CAAC,MAAqC;AAAA,IACpE,MAAM,YAAY,IAAI,KAAK,KAAK,SAAS,EAAE,YAAY;AAAA,IACvD,MAAM,aAAa,KAAK,UAAU,IAAI,KAAK,KAAK,OAAO,EAAE,YAAY,IAAI;AAAA,IAGzE,MAAM,UAAmC;AAAA,MACvC,SAAS,KAAK;AAAA,MACd,UAAU,KAAK;AAAA,MACf,MAAM,KAAK;AAAA,MACX,QAAQ,KAAK;AAAA,MACb,QAAQ,KAAK;AAAA,MACb,SAAS,KAAK;AAAA,MACd,UAAU,KAAK;AAAA,MACf,MAAM,KAAK;AAAA,MACX,aAAa;AAAA,MACb,OAAO;AAAA,IACT;AAAA,IAGA,IAAI,KAAK,YAAY;AAAA,MACnB,QAAQ,cAAc;AAAA,QACpB,eAAe,KAAK,WAAW;AAAA,QAC/B,mBAAmB,KAAK,WAAW;AAAA,QACnC,cAAc,KAAK,WAAW;AAAA,MAChC;AAAA,IACF;AAAA,IAGA,IAAI,KAAK,OAAO;AAAA,MACd,QAAQ,QAAQ;AAAA,QACd,YAAY,KAAK,MAAM;AAAA,QACvB,SAAS,KAAK,MAAM;AAAA,QACpB,YAAY,KAAK,MAAM;AAAA,MACzB;AAAA,IACF;AAAA,IAGA,MAAM,eAAe,KAAK,eAAgB,KAAK,UAAU,IAAI,KAAK,YAAY,KAAK,OAAQ;AAAA,IAE3F,OAAO;AAAA,MACL,SAAS;AAAA,QACP,mBAAmB,KAAK;AAAA,QACxB,aAAa,KAAK;AAAA,QAClB;AAAA,QACA,gBAAgB;AAAA,QAChB,YAAY;AAAA,QACZ,aAAa;AAAA,MACf;AAAA,IACF;AAAA;AAAA,EAMM,gBAAgB,GAA4B;AAAA,IAClD,OAAO;AAAA,MACL,qBAAqB;AAAA,MACrB,cAAc;AAAA,QACZ,OAAO;AAAA,UACL,MAAM;AAAA,UACN,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,OAAO,QAAQ,EAAE;AAAA,QACzD;AAAA,QACA,KAAK;AAAA,UACH,MAAM;AAAA,UACN,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,OAAO,MAAM,EAAE;AAAA,QACvD;AAAA,QACA,MAAM;AAAA,UACJ,MAAM;AAAA,UACN,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,OAAO,OAAO,EAAE;AAAA,QACxD;AAAA,QACA,OAAO;AAAA,UACL,MAAM;AAAA,UACN,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,OAAO,QAAQ,EAAE;AAAA,QACzD;AAAA,QACA,WAAW;AAAA,UACT,MAAM;AAAA,UACN,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,OAAO,YAAY,EAAE;AAAA,QAC7D;AAAA,MACF;AAAA,IACF;AAAA;AAAA,OAMY,sBAAqB,GAAkB;AAAA,IACnD,IAAI,KAAK,iBAAiB;AAAA,MACxB;AAAA,IACF;AAAA,IAEA,MAAM,MAAM,GAAG,KAAK,OAAO;AAAA,IAC3B,MAAM,UAAmC,CAAC;AAAA,IAE1C,IAAI,KAAK,OAAO;AAAA,MAAS,QAAQ,WAAW,KAAK,OAAO;AAAA,IACxD,IAAI,KAAK,OAAO,cAAc;AAAA,MAC5B,QAAQ,gBAAgB;AAAA,QACtB,qBAAqB,KAAK,OAAO;AAAA,QACjC,MAAM,KAAK,OAAO,aAAa;AAAA,QAC/B,aAAa,KAAK,OAAO,oBAAoB;AAAA,MAC/C;AAAA,IACF;AAAA,IAOA,IAAI,KAAK,OAAO,YAAY;AAAA,MAC1B,OAAO,MAAM,mDAAmD;AAAA,IAElE,EAAO,SAAI,KAAK,OAAO,aAAa;AAAA,MAClC,OAAO,MAAM,2BAA2B;AAAA,MACxC,QAAQ,uBAAuB,KAAK,OAAO;AAAA,IAC7C,EAAO,SAAI,KAAK,OAAO,oBAAoB;AAAA,MACzC,OAAO,MAAM,yBAAyB,KAAK,OAAO,oBAAoB;AAAA,MACtE,QAAQ,uBAAuB;AAAA,QAC7B,qBAAqB,KAAK,OAAO;AAAA,MACnC;AAAA,IACF,EAAO;AAAA,MACL,OAAO,MAAM,yCAAyC;AAAA,MACtD,QAAQ,uBAAuB,KAAK,iBAAiB;AAAA;AAAA,IAGvD,IAAI;AAAA,MACF,MAAM,WAAW,MAAM,MAAM,KAAK;AAAA,QAChC,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,eAAe,UAAU,KAAK,OAAO;AAAA,UACrC,gBAAgB;AAAA,QAClB;AAAA,QACA,MAAM,KAAK,UAAU,OAAO;AAAA,QAC5B,QAAQ,YAAY,QAAQ,KAAK,OAAO,cAAc;AAAA,MACxD,CAAC;AAAA,MAED,IAAI,SAAS,IAAI;AAAA,QACf,MAAM,OAAQ,MAAM,SAAS,KAAK;AAAA,QAClC,KAAK,kBAAkB,MAAM,SAAS,MAAM;AAAA,QAC5C,OAAO,MAAM,8BAA8B,KAAK,iBAAiB;AAAA,MACnE,EAAO;AAAA,QACL,OAAO,MAAM,6BAA6B,SAAS,UAAU,SAAS,YAAY;AAAA;AAAA,MAEpF,OAAO,OAAO;AAAA,MACd,OAAO,MAAM,4BAA4B,KAAK;AAAA;AAAA;AAAA,OAOpC,uBAAsB,GAAkB;AAAA,IACpD,MAAM,KAAK,sBAAsB;AAAA,IAEjC,IAAI,CAAC,KAAK,iBAAiB;AAAA,MACzB,OAAO,MAAM,6CAA6C;AAAA,MAC1D;AAAA,IACF;AAAA,IAEA,MAAM,MAAM,GAAG,KAAK,OAAO,gCAAgC,KAAK;AAAA,IAEhE,IAAI;AAAA,MACF,MAAM,WAAW,MAAM,MAAM,KAAK;AAAA,QAChC,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,eAAe,UAAU,KAAK,OAAO;AAAA,UACrC,gBAAgB;AAAA,QAClB;AAAA,QACA,MAAM,KAAK,UAAU,CAAC,CAAC;AAAA,QACvB,QAAQ,YAAY,QAAQ,KAAK,OAAO,cAAc;AAAA,MACxD,CAAC;AAAA,MAED,IAAI,CAAC,SAAS,IAAI;AAAA,QAChB,OAAO,MAAM,mCAAmC,SAAS,UAAU,SAAS,YAAY;AAAA,MAC1F;AAAA,MACA,OAAO,OAAO;AAAA,MACd,OAAO,MAAM,kCAAkC,KAAK;AAAA;AAAA;AAAA,OAO1C,wBAAuB,GAAkB;AAAA,IACrD,IAAI,CAAC,KAAK,iBAAiB;AAAA,MACzB,OAAO,MAAM,8CAA8C;AAAA,MAC3D;AAAA,IACF;AAAA,IAEA,MAAM,MAAM,GAAG,KAAK,OAAO,gCAAgC,KAAK;AAAA,IAEhE,IAAI;AAAA,MACF,MAAM,WAAW,MAAM,MAAM,KAAK;AAAA,QAChC,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,eAAe,UAAU,KAAK,OAAO;AAAA,UACrC,gBAAgB;AAAA,QAClB;AAAA,QACA,MAAM,KAAK,UAAU,CAAC,CAAC;AAAA,QACvB,QAAQ,YAAY,QAAQ,KAAK,OAAO,cAAc;AAAA,MACxD,CAAC;AAAA,MAED,IAAI,CAAC,SAAS,IAAI;AAAA,QAChB,OAAO,MAAM,oCAAoC,SAAS,UAAU,SAAS,YAAY;AAAA,MAC3F;AAAA,MACA,OAAO,OAAO;AAAA,MACd,OAAO,MAAM,mCAAmC,KAAK;AAAA;AAAA;AAAA,OAO3C,eAAc,CAAC,MAA4D;AAAA,IACvF,MAAM,gBAAgB,KAAK,UAAU,IAAI,KAAK,MAAM;AAAA,IACpD,IAAI,CAAC,eAAe;AAAA,MAClB,OAAO,KAAK,sBAAsB,KAAK,8BAA8B;AAAA,MACrE;AAAA,IACF;AAAA,IAEA,MAAM,MAAM,GAAG,KAAK,OAAO,6BAA6B;AAAA,IAExD,IAAI;AAAA,MACF,MAAM,WAAW,MAAM,MAAM,KAAK;AAAA,QAChC,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,eAAe,UAAU,KAAK,OAAO;AAAA,UACrC,gBAAgB;AAAA,QAClB;AAAA,QACA,MAAM,KAAK,UAAU,EAAE,WAAW,KAAK,UAAU,CAAC;AAAA,QAClD,QAAQ,YAAY,QAAQ,KAAK,OAAO,cAAc;AAAA,MACxD,CAAC;AAAA,MAED,IAAI,CAAC,SAAS,IAAI;AAAA,QAChB,OAAO,MAAM,0BAA0B,SAAS,UAAU,SAAS,YAAY;AAAA,MACjF;AAAA,MACA,OAAO,OAAO;AAAA,MACd,OAAO,MAAM,yBAAyB,KAAK;AAAA;AAAA;AAAA,OASzC,MAAK,GAAkB;AAAA,IAC3B,KAAK,SAAS;AAAA,IAGd,MAAM,UAAU;AAAA,IAChB,MAAM,QAAQ,KAAK,IAAI;AAAA,IACvB,OAAO,KAAK,cAAc,KAAK,IAAI,IAAI,QAAQ,SAAS;AAAA,MACtD,MAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,GAAG,CAAC;AAAA,IACzD;AAAA,IAEA,IAAI,KAAK,YAAY;AAAA,MACnB,OAAO,KAAK,2CAA2C;AAAA,IACzD;AAAA;AAEJ;;ACzbO,SAAS,cAAc,CAAC,OAAe,WAA2B;AAAA,EACvE,IAAI,MAAM,UAAU,WAAW;AAAA,IAC7B,OAAO;AAAA,EACT;AAAA,EACA,OAAO,GAAG,MAAM,MAAM,GAAG,SAAS;AAAA;AAiB7B,SAAS,cAAc,CAAC,OAAgB,YAA2B,KAAgB;AAAA,EAExF,IAAI,UAAU,QAAQ,UAAU,WAAW;AAAA,IACzC,OAAO;AAAA,EACT;AAAA,EAEA,IAAI,OAAO,UAAU,aAAa,OAAO,UAAU,UAAU;AAAA,IAC3D,OAAO;AAAA,EACT;AAAA,EAGA,IAAI,OAAO,UAAU,UAAU;AAAA,IAC7B,OAAO,cAAc,OAAO,eAAe,OAAO,SAAS,IAAI;AAAA,EACjE;AAAA,EAGA,IAAI,MAAM,QAAQ,KAAK,GAAG;AAAA,IACxB,OAAO,MAAM,IAAI,CAAC,SAAS,eAAe,MAAM,SAAS,CAAC;AAAA,EAC5D;AAAA,EAGA,IAAI,OAAO,UAAU,UAAU;AAAA,IAC7B,MAAM,SAAkC,CAAC;AAAA,IACzC,YAAY,KAAK,QAAQ,OAAO,QAAQ,KAAK,GAAG;AAAA,MAC9C,OAAO,OAAO,eAAe,KAAK,SAAS;AAAA,IAC7C;AAAA,IACA,OAAO;AAAA,EACT;AAAA,EAGA,IAAI;AAAA,IACF,OAAO,OAAO,KAAK;AAAA,IACnB,MAAM;AAAA,IACN,OAAO,IAAI,OAAO;AAAA;AAAA;;;ACxCf,MAAM,eAAoC;AAAA,EACvC,SAAS;AAAA,EACT,YAAY,QAAQ,QAAQ;AAAA,EAOpC,IAAI,CAAC,MAAkB;AAAA,IACrB,IAAI,KAAK,QAAQ;AAAA,MACf;AAAA,IACF;AAAA,IAGA,KAAK,YAAY,KAAK,UAAU,KAAK,YAAY;AAAA,MAC/C,IAAI;AAAA,QACF,MAAM,aAAa,eAAe,IAAI;AAAA,QACtC,MAAM,OAAO,KAAK,UAAU,UAAU;AAAA,QACtC,MAAM,IAAI,MAAM,IAAI,QAAQ,GAAG;AAAA,CAAQ;AAAA,QACvC,OAAO,OAAO;AAAA,QACd,QAAQ,MAAM,kCAAkC,KAAK;AAAA;AAAA,KAExD;AAAA;AAAA,EAMH,UAAU,GAAS;AAAA,EAOnB,kBAAkB,GAAS;AAAA,EAO3B,mBAAmB,GAAS;AAAA,OAStB,MAAK,GAAkB;AAAA,IAC3B,KAAK,SAAS;AAAA,IACd,MAAM,KAAK;AAAA;AAEf;",
+  "debugId": "48E67D6DE4160D4864756E2164756E21",
+  "names": []
+}

package/dist/tracing/context.d.ts

@@ -0,0 +1,53 @@
+import type { Span } from './span.js';
+/**
+ * SpanContext manages the current span in async execution contexts.
+ * This enables automatic parent-child span relationships without manual tracking.
+ *
+ * Uses Node.js AsyncLocalStorage which provides async-safe context propagation.
+ *
+ * @example
+ * ```typescript
+ * const span = tracer.startSpan({ name: 'parent', ... });
+ *
+ * await SpanContext.runAsync(span, async () => {
+ *   // Inside this function, getCurrent() returns the parent span
+ *   const parent = SpanContext.getCurrent();
+ *
+ *   const child = tracer.startSpan({
+ *     name: 'child',
+ *     parentSpanId: parent?.spanId,
+ *     traceId: parent?.traceId,
+ *   });
+ *   // ...
+ * });
+ * ```
+ */
+export declare class SpanContext {
+    /**
+     * Get the current span from the async context
+     *
+     * @returns The current span, or undefined if no span is active
+     */
+    static getCurrent(): Span | undefined;
+    /**
+     * Run a synchronous function with the given span as the current context
+     *
+     * @param span - The span to set as current
+     * @param fn - The function to execute
+     * @returns The return value of the function
+     */
+    static run<T>(span: Span, fn: () => T): T;
+    /**
+     * Run an asynchronous function with the given span as the current context
+     *
+     * @param span - The span to set as current
+     * @param fn - The async function to execute
+     * @returns A promise resolving to the return value of the function
+     */
+    static runAsync<T>(span: Span, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Clear the current context (primarily for testing)
+     */
+    static clear(): void;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/tracing/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/tracing/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAOtC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,qBAAa,WAAW;IACtB;;;;OAIG;IACH,MAAM,CAAC,UAAU,IAAI,IAAI,GAAG,SAAS;IAIrC;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAIzC;;;;;;OAMG;WACU,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAItE;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;CAGrB"}

package/dist/tracing/context.js

@@ -0,0 +1,66 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Storage for the current span in async context
+ */
+const spanStorage = new AsyncLocalStorage();
+/**
+ * SpanContext manages the current span in async execution contexts.
+ * This enables automatic parent-child span relationships without manual tracking.
+ *
+ * Uses Node.js AsyncLocalStorage which provides async-safe context propagation.
+ *
+ * @example
+ * ```typescript
+ * const span = tracer.startSpan({ name: 'parent', ... });
+ *
+ * await SpanContext.runAsync(span, async () => {
+ *   // Inside this function, getCurrent() returns the parent span
+ *   const parent = SpanContext.getCurrent();
+ *
+ *   const child = tracer.startSpan({
+ *     name: 'child',
+ *     parentSpanId: parent?.spanId,
+ *     traceId: parent?.traceId,
+ *   });
+ *   // ...
+ * });
+ * ```
+ */
+// biome-ignore lint/complexity/noStaticOnlyClass: Intentional API design for namespacing context operations
+export class SpanContext {
+    /**
+     * Get the current span from the async context
+     *
+     * @returns The current span, or undefined if no span is active
+     */
+    static getCurrent() {
+        return spanStorage.getStore();
+    }
+    /**
+     * Run a synchronous function with the given span as the current context
+     *
+     * @param span - The span to set as current
+     * @param fn - The function to execute
+     * @returns The return value of the function
+     */
+    static run(span, fn) {
+        return spanStorage.run(span, fn);
+    }
+    /**
+     * Run an asynchronous function with the given span as the current context
+     *
+     * @param span - The span to set as current
+     * @param fn - The async function to execute
+     * @returns A promise resolving to the return value of the function
+     */
+    static async runAsync(span, fn) {
+        return spanStorage.run(span, fn);
+    }
+    /**
+     * Clear the current context (primarily for testing)
+     */
+    static clear() {
+        spanStorage.disable();
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/tracing/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/tracing/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD;;GAEG;AACH,MAAM,WAAW,GAAG,IAAI,iBAAiB,EAAQ,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4GAA4G;AAC5G,MAAM,OAAO,WAAW;IACtB;;;;OAIG;IACH,MAAM,CAAC,UAAU;QACf,OAAO,WAAW,CAAC,QAAQ,EAAE,CAAC;IAChC,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAI,IAAU,EAAE,EAAW;QACnC,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAI,IAAU,EAAE,EAAoB;QACvD,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK;QACV,WAAW,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;CACF"}

package/dist/tracing/span.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Types of spans that can be traced
+ */
+export declare enum SpanType {
+    AGENT = "agent",
+    LLM = "llm",
+    TOOL = "tool",
+    CHAIN = "chain",
+    RETRIEVER = "retriever"
+}
+/**
+ * Status of a span
+ */
+export declare enum SpanStatus {
+    RUNNING = "running",
+    SUCCESS = "success",
+    ERROR = "error"
+}
+/**
+ * Token usage information for LLM calls
+ */
+export interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * Error information captured when a span fails
+ */
+export interface ErrorInfo {
+    errorType: string;
+    message: string;
+    stacktrace: string;
+}
+/**
+ * A span represents a single operation in a trace
+ */
+export interface Span {
+    /** Unique identifier for this span */
+    spanId: string;
+    /** ID of the parent span, or null if this is a root span */
+    parentSpanId: string | null;
+    /** Trace ID shared by all spans in a single trace */
+    traceId: string;
+    /** Human-readable name for this span */
+    name: string;
+    /** Type of operation this span represents */
+    spanType: SpanType;
+    /** Start time in milliseconds since Unix epoch */
+    startTime: number;
+    /** End time in milliseconds since Unix epoch, or null if still running */
+    endTime: number | null;
+    /** Current status of the span */
+    status: SpanStatus;
+    /** Input data for this operation */
+    inputs: Record<string, unknown>;
+    /** Output data from this operation, or null if not completed */
+    outputs: Record<string, unknown> | null;
+    /** Token usage for LLM calls, or null if not applicable */
+    tokenUsage: TokenUsage | null;
+    /** Error information if the span failed, or null if successful */
+    error: ErrorInfo | null;
+    /** Additional metadata about this span */
+    metadata: Record<string, unknown>;
+    /** Tags for categorizing and filtering spans */
+    tags: string[];
+}
+//# sourceMappingURL=span.d.ts.map

package/dist/tracing/span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.d.ts","sourceRoot":"","sources":["../../src/tracing/span.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,QAAQ;IAClB,KAAK,UAAU;IACf,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,KAAK,UAAU;IACf,SAAS,cAAc;CACxB;AAED;;GAEG;AACH,oBAAY,UAAU;IACpB,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,KAAK,UAAU;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IAEf,4DAA4D;IAC5D,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAEhB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb,6CAA6C;IAC7C,QAAQ,EAAE,QAAQ,CAAC;IAEnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAElB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvB,iCAAiC;IACjC,MAAM,EAAE,UAAU,CAAC;IAEnB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAExC,2DAA2D;IAC3D,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAE9B,kEAAkE;IAClE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAExB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC,gDAAgD;IAChD,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB"}

package/dist/tracing/span.js

@@ -0,0 +1,21 @@
+/**
+ * Types of spans that can be traced
+ */
+export var SpanType;
+(function (SpanType) {
+    SpanType["AGENT"] = "agent";
+    SpanType["LLM"] = "llm";
+    SpanType["TOOL"] = "tool";
+    SpanType["CHAIN"] = "chain";
+    SpanType["RETRIEVER"] = "retriever";
+})(SpanType || (SpanType = {}));
+/**
+ * Status of a span
+ */
+export var SpanStatus;
+(function (SpanStatus) {
+    SpanStatus["RUNNING"] = "running";
+    SpanStatus["SUCCESS"] = "success";
+    SpanStatus["ERROR"] = "error";
+})(SpanStatus || (SpanStatus = {}));
+//# sourceMappingURL=span.js.map

package/dist/tracing/span.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.js","sourceRoot":"","sources":["../../src/tracing/span.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAN,IAAY,QAMX;AAND,WAAY,QAAQ;IAClB,2BAAe,CAAA;IACf,uBAAW,CAAA;IACX,yBAAa,CAAA;IACb,2BAAe,CAAA;IACf,mCAAuB,CAAA;AACzB,CAAC,EANW,QAAQ,KAAR,QAAQ,QAMnB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,UAIX;AAJD,WAAY,UAAU;IACpB,iCAAmB,CAAA;IACnB,iCAAmB,CAAA;IACnB,6BAAe,CAAA;AACjB,CAAC,EAJW,UAAU,KAAV,UAAU,QAIrB"}

package/dist/tracing/tracer.d.ts

@@ -0,0 +1,100 @@
+import { type Partition } from '@prefactor/pfid';
+import type { Transport } from '../transport/base.js';
+import type { Span, SpanType, TokenUsage } from './span.js';
+/**
+ * Options for starting a new span
+ */
+export interface StartSpanOptions {
+    /** Name of the span */
+    name: string;
+    /** Type of operation this span represents */
+    spanType: SpanType;
+    /** Input data for this operation */
+    inputs: Record<string, unknown>;
+    /** ID of the parent span (optional) */
+    parentSpanId?: string;
+    /** Trace ID to use (optional, will generate if not provided) */
+    traceId?: string;
+    /** Additional metadata (optional) */
+    metadata?: Record<string, unknown>;
+    /** Tags for categorizing the span (optional) */
+    tags?: string[];
+}
+/**
+ * Options for ending a span
+ */
+export interface EndSpanOptions {
+    /** Output data from the operation */
+    outputs?: Record<string, unknown>;
+    /** Error that occurred (if any) */
+    error?: Error;
+    /** Token usage information (for LLM calls) */
+    tokenUsage?: TokenUsage;
+}
+/**
+ * Tracer manages the lifecycle of spans.
+ *
+ * The tracer is responsible for:
+ * - Creating spans with unique IDs
+ * - Managing span lifecycle (start/end)
+ * - Delegating to the transport layer for span emission
+ * - Handling agent instance lifecycle
+ *
+ * @example
+ * ```typescript
+ * const tracer = new Tracer(transport);
+ *
+ * const span = tracer.startSpan({
+ *   name: 'llm-call',
+ *   spanType: SpanType.LLM,
+ *   inputs: { prompt: 'Hello' }
+ * });
+ *
+ * try {
+ *   // ... do work ...
+ *   tracer.endSpan(span, { outputs: { response: 'Hi!' } });
+ * } catch (error) {
+ *   tracer.endSpan(span, { error });
+ * }
+ * ```
+ */
+export declare class Tracer {
+    private transport;
+    private partition;
+    /**
+     * Initialize the tracer.
+     *
+     * @param transport - The transport to use for emitting spans
+     * @param partition - The partition for ID generation. If not provided, a random partition will be generated.
+     */
+    constructor(transport: Transport, partition?: Partition);
+    /**
+     * Start a new span
+     *
+     * @param options - Span configuration options
+     * @returns The created span
+     */
+    startSpan(options: StartSpanOptions): Span;
+    /**
+     * End a span and emit it to the transport
+     *
+     * @param span - The span to end
+     * @param options - End span options (outputs, error, token usage)
+     */
+    endSpan(span: Span, options?: EndSpanOptions): void;
+    /**
+     * Signal the start of an agent instance execution
+     */
+    startAgentInstance(): void;
+    /**
+     * Signal the completion of an agent instance execution
+     */
+    finishAgentInstance(): void;
+    /**
+     * Close the tracer and flush any pending spans
+     *
+     * @returns Promise that resolves when the tracer is closed
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=tracer.d.ts.map

package/dist/tracing/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/tracing/tracer.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IAEb,6CAA6C;IAC7C,QAAQ,EAAE,QAAQ,CAAC;IAEnB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC,mCAAmC;IACnC,KAAK,CAAC,EAAE,KAAK,CAAC;IAEd,8CAA8C;IAC9C,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,MAAM;IAUf,OAAO,CAAC,SAAS;IATnB,OAAO,CAAC,SAAS,CAAY;IAE7B;;;;;OAKG;gBAEO,SAAS,EAAE,SAAS,EAC5B,SAAS,CAAC,EAAE,SAAS;IAKvB;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAkC1C;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI;IA6BnD;;OAEG;IACH,kBAAkB,IAAI,IAAI;IAQ1B;;OAEG;IACH,mBAAmB,IAAI,IAAI;IAQ3B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}

package/dist/tracing/tracer.js

@@ -0,0 +1,151 @@
+import { generate, generatePartition } from '@prefactor/pfid';
+import { SpanStatus } from './span.js';
+/**
+ * Tracer manages the lifecycle of spans.
+ *
+ * The tracer is responsible for:
+ * - Creating spans with unique IDs
+ * - Managing span lifecycle (start/end)
+ * - Delegating to the transport layer for span emission
+ * - Handling agent instance lifecycle
+ *
+ * @example
+ * ```typescript
+ * const tracer = new Tracer(transport);
+ *
+ * const span = tracer.startSpan({
+ *   name: 'llm-call',
+ *   spanType: SpanType.LLM,
+ *   inputs: { prompt: 'Hello' }
+ * });
+ *
+ * try {
+ *   // ... do work ...
+ *   tracer.endSpan(span, { outputs: { response: 'Hi!' } });
+ * } catch (error) {
+ *   tracer.endSpan(span, { error });
+ * }
+ * ```
+ */
+export class Tracer {
+    transport;
+    partition;
+    /**
+     * Initialize the tracer.
+     *
+     * @param transport - The transport to use for emitting spans
+     * @param partition - The partition for ID generation. If not provided, a random partition will be generated.
+     */
+    constructor(transport, partition) {
+        this.transport = transport;
+        this.partition = partition ?? generatePartition();
+    }
+    /**
+     * Start a new span
+     *
+     * @param options - Span configuration options
+     * @returns The created span
+     */
+    startSpan(options) {
+        const spanId = generate(this.partition);
+        const traceId = options.traceId ?? generate(this.partition);
+        const span = {
+            spanId,
+            parentSpanId: options.parentSpanId ?? null,
+            traceId,
+            name: options.name,
+            spanType: options.spanType,
+            startTime: Date.now(),
+            endTime: null,
+            status: SpanStatus.RUNNING,
+            inputs: options.inputs,
+            outputs: null,
+            tokenUsage: null,
+            error: null,
+            metadata: options.metadata ?? {},
+            tags: options.tags ?? [],
+        };
+        // AGENT spans are emitted immediately for real-time tracking
+        // They will be finished later with finishSpan()
+        if (options.spanType === 'agent') {
+            try {
+                this.transport.emit(span);
+            }
+            catch (error) {
+                console.error('Failed to emit agent span:', error);
+            }
+        }
+        return span;
+    }
+    /**
+     * End a span and emit it to the transport
+     *
+     * @param span - The span to end
+     * @param options - End span options (outputs, error, token usage)
+     */
+    endSpan(span, options) {
+        span.endTime = Date.now();
+        span.outputs = options?.outputs ?? null;
+        span.tokenUsage = options?.tokenUsage ?? null;
+        if (options?.error) {
+            span.status = SpanStatus.ERROR;
+            span.error = {
+                errorType: options.error.constructor.name,
+                message: options.error.message,
+                stacktrace: options.error.stack ?? '',
+            };
+        }
+        else {
+            span.status = SpanStatus.SUCCESS;
+        }
+        try {
+            // AGENT spans use finishSpan API (they were already emitted on start)
+            // Other span types are emitted here
+            if (span.spanType === 'agent') {
+                this.transport.finishSpan(span.spanId, span.endTime);
+            }
+            else {
+                this.transport.emit(span);
+            }
+        }
+        catch (error) {
+            console.error('Failed to emit/finish span:', error);
+        }
+    }
+    /**
+     * Signal the start of an agent instance execution
+     */
+    startAgentInstance() {
+        try {
+            this.transport.startAgentInstance();
+        }
+        catch (error) {
+            console.error('Failed to start agent instance:', error);
+        }
+    }
+    /**
+     * Signal the completion of an agent instance execution
+     */
+    finishAgentInstance() {
+        try {
+            this.transport.finishAgentInstance();
+        }
+        catch (error) {
+            console.error('Failed to finish agent instance:', error);
+        }
+    }
+    /**
+     * Close the tracer and flush any pending spans
+     *
+     * @returns Promise that resolves when the tracer is closed
+     */
+    async close() {
+        try {
+            await this.transport.close();
+        }
+        catch (error) {
+            console.error('Failed to close transport:', error);
+        }
+    }
+}
+//# sourceMappingURL=tracer.js.map

package/dist/tracing/tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.js","sourceRoot":"","sources":["../../src/tracing/tracer.ts"],"names":[],"mappings":"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"}

package/dist/transport/base.d.ts

@@ -0,0 +1,38 @@
+import type { Span } from '../tracing/span.js';
+/**
+ * Transport interface for emitting spans to different backends
+ *
+ * Transports are responsible for sending span data to a destination
+ * (e.g., stdout, HTTP API). They implement the strategy pattern to allow
+ * pluggable backends.
+ */
+export interface Transport {
+    /**
+     * Emit a span to the transport destination
+     *
+     * @param span - The span to emit
+     */
+    emit(span: Span): void;
+    /**
+     * Finish a previously emitted span (for long-running spans like AGENT spans)
+     *
+     * @param spanId - ID of the span to finish
+     * @param endTime - End time in milliseconds since Unix epoch
+     */
+    finishSpan(spanId: string, endTime: number): void;
+    /**
+     * Signal the start of an agent instance execution
+     */
+    startAgentInstance(): void;
+    /**
+     * Signal the completion of an agent instance execution
+     */
+    finishAgentInstance(): void;
+    /**
+     * Close the transport and flush any pending data
+     *
+     * @returns Promise that resolves when the transport is fully closed
+     */
+    close(): void | Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map