@cloudbase/agent-observability 0.0.16 → 0.0.18

package/dist/index.d.mts

@@ -1,18 +1,18 @@
 import * as _opentelemetry_api from '@opentelemetry/api';
-import { Span, TimeInput, Attributes, TracerProvider, SpanContext } from '@opentelemetry/api';
+import { Span, TimeInput, SpanStatus, Attributes, TracerProvider, Link, SpanContext } from '@opentelemetry/api';
 
 /**
- * Types of observations (spans) supported by AG-Kit observability.
+ * Types of observations (spans) supported by observability.
  *
  * These types align with OpenInference semantic conventions:
  * https://github.com/Arize-ai/openinference/tree/main/spec
  *
- * - `span`: General-purpose operations (OpenInference: internal/span)
+ * All types map directly to OpenInference span kinds:
+ * - `chain`: Multi-step workflows (OpenInference: CHAIN) - **default for generic operations**
  * - `llm`: Language model calls (OpenInference: LLM)
  * - `embedding`: Text embedding operations (OpenInference: EMBEDDING)
  * - `agent`: AI agent workflows (OpenInference: AGENT)
  * - `tool`: Tool/function calls (OpenInference: TOOL)
- * - `chain`: Multi-step workflows (OpenInference: CHAIN)
  * - `retriever`: Document retrieval (OpenInference: RETRIEVER)
  * - `reranker`: Result reranking (OpenInference: RERANKER)
  * - `guardrail`: Safety checks (OpenInference: GUARDRAIL)
@@ -20,7 +20,7 @@ import { Span, TimeInput, Attributes, TracerProvider, SpanContext } from '@opent
  *
  * @public
  */
-type ObservationType = "span" | "llm" | "embedding" | "agent" | "tool" | "chain" | "retriever" | "reranker" | "guardrail" | "evaluator";
+type ObservationType = "chain" | "llm" | "embedding" | "agent" | "tool" | "retriever" | "reranker" | "guardrail" | "evaluator";
 /**
  * Severity levels for observations.
  *
@@ -45,6 +45,69 @@ type TokenUsage = {
     /** Total number of tokens */
     totalTokens?: number;
 };
+/**
+ * LLM message for input/output tracking.
+ *
+ * Follows OpenInference semantic convention:
+ * - llm.input_messages.{i}.message.role
+ * - llm.input_messages.{i}.message.content
+ * - llm.output_messages.{i}.message.role
+ * - llm.output_messages.{i}.message.content
+ *
+ * @public
+ */
+type LLMMessage = {
+    /** Message role (e.g., 'user', 'assistant', 'system', 'tool') */
+    role: string;
+    /** Message content */
+    content?: string;
+    /** Tool calls for assistant messages */
+    toolCalls?: ToolCall[];
+    /** Tool call ID for tool messages */
+    toolCallId?: string;
+};
+/**
+ * Tool call details.
+ *
+ * Follows OpenInference semantic convention:
+ * - tool_call.id
+ * - tool_call.function.name
+ * - tool_call.function.arguments
+ *
+ * @public
+ */
+type ToolCall = {
+    /** Tool call ID */
+    id: string;
+    /** Function name */
+    function: {
+        /** Function name */
+        name: string;
+        /** Function arguments as JSON string */
+        arguments: string;
+    };
+};
+/**
+ * Document for retrieval tracking.
+ *
+ * Follows OpenInference semantic convention:
+ * - retrieval.documents.{i}.document.id
+ * - retrieval.documents.{i}.document.content
+ * - retrieval.documents.{i}.document.score
+ * - retrieval.documents.{i}.document.metadata
+ *
+ * @public
+ */
+type Document = {
+    /** Document ID */
+    id?: string;
+    /** Document content */
+    content?: string;
+    /** Relevance score */
+    score?: number;
+    /** Document metadata */
+    metadata?: Record<string, unknown>;
+};
 /**
  * Base attributes for all observation types.
  *
@@ -69,13 +132,18 @@ type BaseSpanAttributes = {
     version?: string;
     /** Environment where the operation is running (e.g., 'production', 'staging') */
     environment?: string;
+    /** Allow additional custom attributes (e.g., http.*, agui.*) */
+    [key: string]: unknown;
 };
 /**
  * LLM-specific attributes following OpenInference semantic conventions.
  *
  * Uses attributes like:
  * - llm.model_name
- * - llm.parameters.*
+ * - llm.system
+ * - llm.provider
+ * - llm.input_messages
+ * - llm.output_messages
  * - llm.token_count.*
  * - llm.invocation_parameters
  *
@@ -86,10 +154,22 @@ type LLMAttributes = BaseSpanAttributes & {
     completionStartTime?: Date;
     /** Name of the language model (e.g., 'gpt-4', 'claude-3-opus') */
     model?: string;
+    /** AI system/vendor identifier (e.g., 'openai', 'anthropic') */
+    system?: string;
+    /** Hosting provider (e.g., 'openai', 'azure', 'aws') */
+    provider?: string;
     /** Parameters passed to the model (temperature, max_tokens, etc.) */
     modelParameters?: Record<string, string | number>;
     /** Token usage metrics */
     usageDetails?: TokenUsage | Record<string, number>;
+    /** Input messages for chat completions */
+    inputMessages?: LLMMessage[];
+    /** Output messages from the model */
+    outputMessages?: LLMMessage[];
+    /** MIME type of input (e.g., 'application/json') */
+    inputMimeType?: string;
+    /** MIME type of output (e.g., 'application/json') */
+    outputMimeType?: string;
 };
 /**
  * Embedding-specific attributes following OpenInference semantic conventions.
@@ -108,10 +188,22 @@ type EmbeddingAttributes = LLMAttributes;
  * - tool.name
  * - tool.description
  * - tool.parameters
+ * - tool_call.id
+ * - tool_call.function.name
+ * - tool_call.function.arguments
  *
  * @public
  */
-type ToolAttributes = BaseSpanAttributes;
+type ToolAttributes = BaseSpanAttributes & {
+    /** Tool name */
+    toolName?: string;
+    /** Tool description */
+    toolDescription?: string;
+    /** Tool parameters schema */
+    toolParameters?: Record<string, unknown>;
+    /** Tool call details */
+    toolCall?: ToolCall;
+};
 /**
  * Agent-specific attributes following OpenInference semantic conventions.
  *
@@ -121,7 +213,10 @@ type ToolAttributes = BaseSpanAttributes;
  *
  * @public
  */
-type AgentAttributes = BaseSpanAttributes;
+type AgentAttributes = BaseSpanAttributes & {
+    /** Agent name */
+    agentName?: string;
+};
 /**
  * Chain-specific attributes following OpenInference semantic conventions.
  *
@@ -138,11 +233,16 @@ type ChainAttributes = BaseSpanAttributes;
  * Uses attributes like:
  * - retriever.name
  * - retriever.query
- * - retriever.*
+ * - retrieval.documents
  *
  * @public
  */
-type RetrieverAttributes = BaseSpanAttributes;
+type RetrieverAttributes = BaseSpanAttributes & {
+    /** Retrieved documents */
+    documents?: Document[];
+    /** Query used for retrieval */
+    query?: string;
+};
 /**
  * Reranker-specific attributes following OpenInference semantic conventions.
  *
@@ -214,7 +314,7 @@ type TraceAttributes = {
  *
  * @public
  */
-type Observation = ObservationSpan | ObservationLLM | ObservationEmbedding | ObservationAgent | ObservationTool | ObservationChain | ObservationRetriever | ObservationReranker | ObservationEvaluator | ObservationGuardrail;
+type Observation = ObservationLLM | ObservationEmbedding | ObservationAgent | ObservationTool | ObservationChain | ObservationRetriever | ObservationReranker | ObservationEvaluator | ObservationGuardrail;
 /**
  * Parameters for creating an observation wrapper.
  *
@@ -247,7 +347,7 @@ declare abstract class BaseObservation {
     /** The trace ID from the OpenTelemetry span context */
     traceId: string;
     constructor(params: ObservationParams);
-    /** Gets the AG-Kit OpenTelemetry tracer instance */
+    /** Gets the OpenTelemetry tracer instance */
     protected get tracer(): _opentelemetry_api.Tracer;
     /**
      * Ends the observation, marking it as complete.
@@ -255,6 +355,20 @@ declare abstract class BaseObservation {
      * @param endTime - Optional end time, defaults to current time
      */
     end(endTime?: TimeInput): void;
+    /**
+     * Sets the span status.
+     *
+     * @param status - The status to set on the span
+     */
+    setStatus(status: SpanStatus): void;
+    /**
+     * Sets the span status to ERROR.
+     *
+     * Convenience method for marking the span as failed.
+     *
+     * @param message - Error description message
+     */
+    setErrorStatus(message: string): void;
     /**
      * Updates the OTEL span attributes.
      *
@@ -305,21 +419,8 @@ declare abstract class BaseObservation {
         asType: "guardrail";
     }): ObservationGuardrail;
     startObservation(name: string, attributes?: BaseSpanAttributes, options?: {
-        asType?: "span";
-    }): ObservationSpan;
-}
-type ObservationSpanParams = {
-    otelSpan: Span;
-    attributes?: BaseSpanAttributes;
-};
-/**
- * General-purpose observation for tracking operations.
- *
- * @public
- */
-declare class ObservationSpan extends BaseObservation {
-    constructor(params: ObservationSpanParams);
-    update(attributes: BaseSpanAttributes): ObservationSpan;
+        asType?: "chain";
+    }): ObservationChain;
 }
 type ObservationLLMParams = {
     otelSpan: Span;
@@ -468,7 +569,7 @@ declare function createTraceAttributes({ name, userId, sessionId, version, relea
  * - Uses `openinference.span.kind` for span type
  * - Uses `llm.*` for LLM-specific attributes
  * - Uses `tool.*` for tool-specific attributes
- * - Falls back to `agkit.observation.*` for non-standard attributes
+ * - Uses `observation.*` for non-standard attributes
  *
  * @param type - Observation type (llm, tool, chain, etc.)
  * @param attributes - Observation attributes to convert
@@ -541,6 +642,240 @@ declare function getTracerProvider(): TracerProvider;
  */
 declare function getTracer(): _opentelemetry_api.Tracer;
 
+/**
+ * Trace context extraction and validation utilities.
+ *
+ * This module provides utilities for extracting and validating W3C-compatible
+ * trace context from HTTP headers, supporting external trace inheritance.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Result of trace context validation.
+ */
+interface TraceContextValidation {
+    traceId?: string;
+    parentSpanId?: string;
+    errors: string[];
+    isValid: boolean;
+    hasTraceId: boolean;
+    hasParentSpanId: boolean;
+}
+/**
+ * Processed trace context result with all necessary data for span creation.
+ *
+ * This encapsulates the complete result of extracting, validating, and processing
+ * external trace context from HTTP headers.
+ */
+interface ProcessedTraceContext {
+    /** Validated trace ID (undefined if invalid or not provided) */
+    traceId?: string;
+    /** Validated parent span ID (undefined if invalid or not provided) */
+    parentSpanId?: string;
+    /** Whether external trace context was successfully inherited */
+    isInherited: boolean;
+    /** Whether parent span link was created */
+    hasParentLink: boolean;
+    /** Span attributes ready to merge into span attributes object */
+    spanAttributes: Record<string, any>;
+    /** Span links ready to pass to start_observation */
+    links: Link[];
+}
+/**
+ * Validate W3C Trace Context trace-id format.
+ *
+ * Must be 32 hex characters (128-bit) and not all zeros.
+ *
+ * Performance: Uses parseInt() instead of regex for 45% faster validation
+ * and better handling of edge cases (extremely long strings).
+ *
+ * @param traceId - The trace ID string to validate
+ * @returns True if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * validateTraceId('7EBd0D2dd5A198C3Cc66a51EeEcdd0F4') // true
+ * validateTraceId('invalid') // false
+ * validateTraceId('00000000000000000000000000000000') // false
+ * ```
+ *
+ * @public
+ */
+declare function validateTraceId(traceId: string): boolean;
+/**
+ * Validate W3C Trace Context span-id format.
+ *
+ * Must be 16 hex characters (64-bit) and not all zeros.
+ *
+ * Performance: Uses parseInt() instead of regex for 45% faster validation
+ * and better handling of edge cases (extremely long strings).
+ *
+ * @param spanId - The span ID string to validate
+ * @returns True if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * validateSpanId('00f067aa0ba902b7') // true
+ * validateSpanId('invalid') // false
+ * validateSpanId('0000000000000000') // false
+ * ```
+ *
+ * @public
+ */
+declare function validateSpanId(spanId: string): boolean;
+/**
+ * Validate and normalize external trace context.
+ *
+ * Supports four scenarios:
+ * 1. Both missing → Valid (generate new trace)
+ * 2. Only traceId → Valid (inherit trace, new root span)
+ * 3. Both provided → Valid (inherit trace + parent link)
+ * 4. Only parentSpanId → Invalid (parent without trace)
+ *
+ * @param traceId - External trace ID from x-trace-id header
+ * @param parentSpanId - External parent span ID from x-parent-span-id header
+ * @returns Validation result with normalized values and any errors
+ *
+ * @example
+ * ```typescript
+ * // Scenario 1: Generate new trace
+ * const result = validateTraceContext(undefined, undefined);
+ * result.isValid // true
+ * result.hasTraceId // false
+ *
+ * // Scenario 2: Inherit trace only
+ * const result = validateTraceContext('9bBab669fdD6eAEB3Ac0A522f5DeE0BF', undefined);
+ * result.isValid // true
+ * result.traceId // '9bbab669fdd6eaeb3ac0a522f5dee0bf'
+ *
+ * // Scenario 3: Inherit trace + parent
+ * const result = validateTraceContext(
+ *   '9bBab669fdD6eAEB3Ac0A522f5DeE0BF',
+ *   '00f067aa0ba902b7'
+ * );
+ * result.isValid // true
+ * result.hasParentSpanId // true
+ *
+ * // Scenario 4: Invalid - parent without trace
+ * const result = validateTraceContext(undefined, '00f067aa0ba902b7');
+ * result.isValid // false
+ * result.errors.length > 0 // true
+ * ```
+ *
+ * @public
+ */
+declare function validateTraceContext(traceId?: string, parentSpanId?: string): TraceContextValidation;
+/**
+ * Create an OpenTelemetry Link to an external span.
+ *
+ * This creates a loose coupling to an external span, avoiding the
+ * "orphaned span" problem when the parent span data is not available
+ * in the current tracing backend.
+ *
+ * @param traceId - External trace ID (32 hex chars)
+ * @param parentSpanId - External parent span ID (16 hex chars)
+ * @param linkType - Semantic relationship type (default: "follows_from")
+ * @param sourceSystem - Name of the external system (default: "gateway")
+ * @returns OpenTelemetry Link object
+ *
+ * @example
+ * ```typescript
+ * const link = createSpanLinkFromContext(
+ *   '9bBab669fdD6eAEB3Ac0A522f5DeE0BF',
+ *   '00f067aa0ba902b7'
+ * );
+ * // Use link when creating span
+ * const span = tracer.startSpan('my-operation', { links: [link] });
+ * ```
+ *
+ * @public
+ */
+declare function createSpanLinkFromContext(traceId: string, parentSpanId: string, linkType?: string, sourceSystem?: string): Link;
+/**
+ * Extract trace context from HTTP headers.
+ *
+ * Only supports custom x-trace-id and x-parent-span-id headers.
+ * Does not support W3C traceparent header.
+ *
+ * @param headers - HTTP headers (case-insensitive)
+ * @param traceIdHeader - Header name for trace ID (default: "x-trace-id")
+ * @param parentSpanIdHeader - Header name for parent span ID (default: "x-parent-span-id")
+ * @returns Tuple of [traceId, parentSpanId], both may be undefined
+ *
+ * @example
+ * ```typescript
+ * const headers = new Headers({
+ *   'x-trace-id': '9bBab669fdD6eAEB3Ac0A522f5DeE0BF',
+ *   'x-parent-span-id': '00f067aa0ba902b7'
+ * });
+ * const [traceId, parentSpanId] = extractTraceContextFromHeaders(headers);
+ * ```
+ *
+ * @public
+ */
+declare function extractTraceContextFromHeaders(headers: Headers | Record<string, string>, traceIdHeader?: string, parentSpanIdHeader?: string): [string | undefined, string | undefined];
+/**
+ * Extract, validate, and process trace context from HTTP headers.
+ *
+ * This is a high-level convenience method that combines extraction, validation,
+ * link creation, and attribute preparation into a single call. It handles all
+ * error cases and returns a ready-to-use ProcessedTraceContext object.
+ *
+ * @param headers - HTTP headers (case-insensitive)
+ * @param logger - Optional logger for validation errors
+ * @param linkType - Semantic relationship type for SpanLink (default: "follows_from")
+ * @param sourceSystem - Name of the external system (default: "gateway")
+ * @returns ProcessedTraceContext with all processed data ready for span creation
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = processTraceContextFromHeaders(request.headers, logger);
+ * if (result.isInherited) {
+ *   Object.assign(spanAttributes, result.spanAttributes);
+ * }
+ * const serverSpan = startObservation(
+ *   "AG-UI.Server",
+ *   spanAttributes,
+ *   { links: result.links.length > 0 ? result.links : undefined }
+ * );
+ *
+ * // Scenario 1: No headers
+ * const result = processTraceContextFromHeaders(new Headers());
+ * result.isInherited // false
+ * result.links // []
+ *
+ * // Scenario 2: Only trace_id
+ * const headers = new Headers({ 'x-trace-id': '9bBab669fdD6eAEB3Ac0A522f5DeE0BF' });
+ * const result = processTraceContextFromHeaders(headers);
+ * result.isInherited // true
+ * result.hasParentLink // false
+ * result.spanAttributes['trace.external_trace_id'] // '7ebd0d2dd5a198c3cc66a51eeecdd0f4'
+ *
+ * // Scenario 3: Both headers
+ * const headers = new Headers({
+ *   'x-trace-id': '9bBab669fdD6eAEB3Ac0A522f5DeE0BF',
+ *   'x-parent-span-id': '00f067aa0ba902b7'
+ * });
+ * const result = processTraceContextFromHeaders(headers);
+ * result.isInherited // true
+ * result.hasParentLink // true
+ * result.links.length // 1
+ *
+ * // Scenario 4: Invalid (only parent_span_id)
+ * const headers = new Headers({ 'x-parent-span-id': '00f067aa0ba902b7' });
+ * const result = processTraceContextFromHeaders(headers);
+ * result.isInherited // false
+ * result.links // []
+ * ```
+ *
+ * @public
+ */
+declare function processTraceContextFromHeaders(headers: Headers | Record<string, string>, logger?: {
+    warn?: (msg: string) => void;
+}, linkType?: string, sourceSystem?: string): ProcessedTraceContext;
+
 /**
  * Observability - OpenTelemetry-based tracing with OpenInference semantic conventions
  *
@@ -557,6 +892,8 @@ type StartObservationOptions = {
     startTime?: Date;
     /** Parent span context to attach this observation to */
     parentSpanContext?: SpanContext;
+    /** Optional links to external or related spans */
+    links?: Link[];
 };
 /**
  * Options for startObservation function.
@@ -564,7 +901,7 @@ type StartObservationOptions = {
  * @public
  */
 type StartObservationOpts = StartObservationOptions & {
-    /** Type of observation to create. Defaults to 'span' */
+    /** Type of observation to create. Defaults to 'chain' */
     asType?: ObservationType;
 };
 declare function startObservation(name: string, attributes?: BaseSpanAttributes, options?: StartObservationOpts & {
@@ -598,8 +935,8 @@ declare function startObservation(name: string, attributes: GuardrailAttributes,
     asType: "guardrail";
 }): ObservationGuardrail;
 declare function startObservation(name: string, attributes?: BaseSpanAttributes, options?: StartObservationOpts & {
-    asType?: "span";
-}): ObservationSpan;
+    asType?: "chain";
+}): ObservationChain;
 /**
  * Updates the currently active trace with new attributes.
  *
@@ -644,7 +981,6 @@ type StartActiveObservationOpts = StartObservationOpts & {
     /** Whether to automatically end the observation when the function exits. Default: true */
     endOnExit?: boolean;
 };
-declare function startActiveObservation<F extends (observation: ObservationSpan) => unknown>(name: string, fn: F, options?: StartActiveObservationOpts): ReturnType<F>;
 declare function startActiveObservation<F extends (observation: ObservationLLM) => unknown>(name: string, fn: F, options?: StartActiveObservationOpts): ReturnType<F>;
 declare function startActiveObservation<F extends (observation: ObservationEmbedding) => unknown>(name: string, fn: F, options?: StartActiveObservationOpts): ReturnType<F>;
 declare function startActiveObservation<F extends (observation: ObservationAgent) => unknown>(name: string, fn: F, options?: StartActiveObservationOpts): ReturnType<F>;
@@ -725,4 +1061,4 @@ type ObserveOptions = Omit<StartObservationOpts, "name"> & {
  */
 declare function observe<T extends (...args: any[]) => any>(fn: T, options?: ObserveOptions): T;
 
-export { type AgentAttributes, type BaseSpanAttributes, type ChainAttributes, type EmbeddingAttributes, type EvaluatorAttributes, type GuardrailAttributes, type LLMAttributes, type Observation, ObservationAgent, type ObservationAttributes, ObservationChain, ObservationEmbedding, ObservationEvaluator, ObservationGuardrail, ObservationLLM, type ObservationLevel, ObservationReranker, ObservationRetriever, ObservationSpan, ObservationTool, type ObservationType, type ObserveOptions, type RerankerAttributes, type RetrieverAttributes, type StartActiveObservationOpts, type StartObservationOptions, type StartObservationOpts, type ToolAttributes, type TraceAttributes, createObservationAttributes, createTraceAttributes, getActiveSpanId, getActiveTraceId, getTracer, getTracerProvider, observe, setTracerProvider, startActiveObservation, startObservation, updateActiveObservation, updateActiveTrace };
+export { type AgentAttributes, type BaseSpanAttributes, type ChainAttributes, type Document, type EmbeddingAttributes, type EvaluatorAttributes, type GuardrailAttributes, type LLMAttributes, type LLMMessage, type Observation, ObservationAgent, type ObservationAttributes, ObservationChain, ObservationEmbedding, ObservationEvaluator, ObservationGuardrail, ObservationLLM, type ObservationLevel, ObservationReranker, ObservationRetriever, ObservationTool, type ObservationType, type ObserveOptions, type ProcessedTraceContext, type RerankerAttributes, type RetrieverAttributes, type StartActiveObservationOpts, type StartObservationOptions, type StartObservationOpts, type ToolAttributes, type ToolCall, type TraceAttributes, type TraceContextValidation, createObservationAttributes, createSpanLinkFromContext, createTraceAttributes, extractTraceContextFromHeaders, getActiveSpanId, getActiveTraceId, getTracer, getTracerProvider, observe, processTraceContextFromHeaders, setTracerProvider, startActiveObservation, startObservation, updateActiveObservation, updateActiveTrace, validateSpanId, validateTraceContext, validateTraceId };