@zespan/sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,588 @@
+import * as _opentelemetry_api from '@opentelemetry/api';
+import { SpanKind, Tracer, Span, Context } from '@opentelemetry/api';
+export { SpanKind, SpanStatusCode } from '@opentelemetry/api';
+import { ZespanEvent, SpanKind as SpanKind$1, ToolDefinition } from '@zespan/shared';
+export { AgentDelegation, ToolDefinition, SpanKind as ZespanSpanKind } from '@zespan/shared';
+import OpenAI from 'openai';
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { Serialized } from '@langchain/core/load/serializable';
+import { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+interface ZespanOptions {
+    apiKey: string;
+    endpoint?: string;
+    baseURL?: string;
+    environment?: string;
+    storePrompts?: boolean;
+    redactKeys?: string[];
+    sampleRate?: number;
+    debug?: boolean;
+    batchSize?: number;
+    flushInterval?: number;
+    enableOTel?: boolean;
+    otelEndpoint?: string;
+    otelServiceName?: string;
+    enableZespanPilot?: boolean;
+    projectId?: string;
+    autopatch?: boolean;
+}
+
+interface OTelConfig {
+    endpoint?: string;
+    serviceName?: string;
+    sampleRate?: number;
+    apiKey?: string;
+    environment?: string;
+}
+declare function initOTel(config: OTelConfig): {
+    tracer: _opentelemetry_api.Tracer;
+    provider: any;
+};
+declare function getTracer(): _opentelemetry_api.Tracer;
+declare function createSpan(options: {
+    name: string;
+    kind?: SpanKind;
+    attributes?: Record<string, string | number | boolean | string[]>;
+}): _opentelemetry_api.Span;
+declare function withSpan<T>(name: string, fn: (span: any) => Promise<T>, options?: {
+    kind?: SpanKind;
+    attributes?: Record<string, string | number | boolean | string[]>;
+}): Promise<T>;
+
+interface PromptOptions {
+    version?: number;
+    label?: string;
+    cache?: boolean;
+}
+interface Prompt {
+    id: string;
+    name: string;
+    version: number;
+    type: "text" | "chat";
+    prompt: any;
+    config: any;
+    labels: string[];
+    tags: string[];
+    variables: string[];
+    createdAt: string;
+    updatedAt: string;
+    promptHash: string;
+}
+declare class PromptClient {
+    private client;
+    private cache;
+    private cacheTTL;
+    constructor(client: ZespanClient);
+    /**
+     * Get a prompt by name, version, or label
+     */
+    get(name: string, options?: PromptOptions): Promise<Prompt>;
+    /**
+     * List all prompts for the current project
+     */
+    list(nameFilter?: string): Promise<Prompt[]>;
+    /**
+     * Create a new prompt version
+     */
+    create(params: {
+        name: string;
+        type: "text" | "chat";
+        prompt: any;
+        config?: any;
+        labels?: string[];
+        tags?: string[];
+        commitMessage?: string;
+    }): Promise<Prompt>;
+    /**
+     * Update labels for a specific prompt version
+     */
+    updateLabels(name: string, version: number, labels: string[]): Promise<Prompt>;
+    /**
+     * Compile a prompt with variables
+     */
+    compile(prompt: Prompt, variables: Record<string, string>): string;
+    /**
+     * Clear cache for a specific prompt or all prompts
+     */
+    clearCache(name?: string): void;
+    private getCacheKey;
+    private invalidateCache;
+}
+
+/**
+ * SDK ConfigClient — zero-infra runtime configuration client.
+ *
+ * Piggybacks on ingest response `cv` field to detect config staleness.
+ * Fetches full config snapshot from `/v1/sdk/config` only when stale.
+ * No polling, no SSE, no resources requiring cleanup.
+ */
+interface CacheSettings {
+    enabled: boolean;
+    ttlSeconds: number;
+    similarityThreshold: number;
+}
+interface RateLimitSettings {
+    maxRequests: number;
+    windowSeconds: number;
+}
+interface FallbackSettings {
+    model: string;
+    conditions: string[];
+}
+interface RetrySettings {
+    enabled: boolean;
+    maxRetries: number;
+    backoffMultiplier: number;
+    retryOnStatusCodes: number[];
+}
+interface TimeoutSettings {
+    timeoutMs: number;
+}
+interface AbTestSettings {
+    candidateModel: string;
+    splitPercentage: number;
+}
+interface RuntimeConfig {
+    modelOverrides: Map<string, string>;
+    cacheConfig: Map<string, CacheSettings>;
+    rateLimits: Map<string, RateLimitSettings>;
+    guardrailOverrides: Map<string, boolean>;
+    samplingRate: number;
+    promptVersions: Map<string, number>;
+    fallbacks: Map<string, FallbackSettings>;
+    retryPolicies: Map<string, RetrySettings>;
+    timeouts: Map<string, TimeoutSettings>;
+    concurrencyLimits: Map<string, number>;
+    abTests: Map<string, AbTestSettings>;
+}
+type ConfigEventListener = (data: any) => void;
+declare class ConfigClient {
+    private localVersion;
+    private config;
+    private listeners;
+    private fetching;
+    private baseUrl;
+    private apiKey;
+    private projectId;
+    constructor(opts: {
+        baseUrl: string;
+        apiKey: string;
+        projectId: string;
+    });
+    checkVersion(serverVersion: number): void;
+    getModel(operation: string, defaultModel: string): string;
+    getCacheConfig(operation: string): CacheSettings | null;
+    getSamplingRate(): number;
+    getRuntimeConfig(): RuntimeConfig;
+    getLocalVersion(): number;
+    getFallback(operation: string): FallbackSettings | null;
+    getRetryPolicy(operation: string): RetrySettings | null;
+    getTimeout(operation: string): TimeoutSettings | null;
+    getConcurrencyLimit(operation: string): number | null;
+    getAbTest(operation: string): AbTestSettings | null;
+    on(event: string, fn: ConfigEventListener): void;
+    private emit;
+    private fetchConfig;
+    applyFullConfig(snapshot: Record<string, any>): void;
+    private parseSnapshot;
+}
+
+type GuardrailPhase = "pre" | "post";
+interface GuardrailCheckInput {
+    text: string;
+    phase: GuardrailPhase;
+    traceId?: string;
+    spanId?: string;
+    model?: string;
+    operation?: string;
+    estimatedCost?: number;
+    inputTokens?: number;
+    agentName?: string;
+    toolName?: string;
+    recentToolCalls?: Array<{
+        toolName: string;
+        args?: string;
+    }>;
+}
+interface GuardrailResult {
+    guardrailSlug: string;
+    passed: boolean;
+    action: "allowed" | "blocked" | "redacted" | "warned";
+    reason: string | null;
+    modifiedText: string | null;
+    latencyMs: number;
+}
+interface GuardrailCheckResponse {
+    allowed: boolean;
+    results: GuardrailResult[];
+    modifiedText: string | null;
+}
+type WrapperGuardrailsSettings = boolean | {
+    pre?: boolean;
+    post?: boolean;
+    failClosed?: boolean;
+    operation?: string;
+};
+interface WrapperGuardrailsOptions {
+    guardrails?: WrapperGuardrailsSettings;
+}
+interface ResolvedWrapperGuardrailsSettings {
+    pre: boolean;
+    post: boolean;
+    failClosed: boolean;
+    operation?: string;
+}
+declare class GuardrailBlockedError extends Error {
+    readonly phase: GuardrailPhase;
+    readonly results: GuardrailResult[];
+    constructor(phase: GuardrailPhase, results: GuardrailResult[]);
+}
+
+declare class ZespanClient {
+    readonly apiKey: string;
+    readonly endpoint: string;
+    readonly baseURL: string;
+    readonly environment: string;
+    readonly storePrompts: boolean;
+    readonly redactKeys: string[];
+    readonly sampleRate: number;
+    readonly debug: boolean;
+    readonly enableOTel: boolean;
+    readonly prompts: PromptClient;
+    readonly configClient: ConfigClient | null;
+    readonly projectId: string | undefined;
+    private batch;
+    private readonly _storePromptsDefault;
+    private _promptWarningShown;
+    constructor(opts: ZespanOptions);
+    enqueue(event: ZespanEvent): void;
+    redactForStorage(value: unknown): string;
+    private resolveGuardrailsUrl;
+    checkGuardrails(input: GuardrailCheckInput): Promise<GuardrailCheckResponse>;
+    flush(): Promise<void>;
+    createSpan(options: {
+        name: string;
+        kind?: SpanKind;
+        attributes?: Record<string, string | number | boolean | string[]>;
+    }): _opentelemetry_api.Span;
+    withSpan<T>(name: string, fn: (span: unknown) => Promise<T>, options?: {
+        kind?: SpanKind;
+        attributes?: Record<string, string | number | boolean | string[]>;
+    }): Promise<T>;
+}
+declare const initZespan: (o: ZespanOptions) => void;
+declare const getZespanClient: () => ZespanClient;
+
+declare const init: (o: ZespanOptions) => void;
+declare const getLumiqClient: () => ZespanClient;
+
+declare function wrapOpenAI<T extends any>(client: T, options?: WrapperGuardrailsOptions): T;
+
+declare function wrapAnthropic<T extends any>(client: T, options?: WrapperGuardrailsOptions): T;
+
+declare function wrapGoogle<T extends any>(client: T, options?: WrapperGuardrailsOptions): T;
+
+declare function wrapOpenRouter(baseClient: OpenAI, options?: WrapperGuardrailsOptions): OpenAI;
+
+interface WrapBedrockOptions extends WrapperGuardrailsOptions {
+    operation?: string;
+}
+declare function wrapBedrock<T extends any>(client: T, options?: WrapBedrockOptions): T;
+
+interface WrapMistralOptions extends WrapperGuardrailsOptions {
+    operation?: string;
+}
+declare function wrapMistral<T extends any>(client: T, options?: WrapMistralOptions): T;
+
+interface WrapGroqOptions {
+    operation?: string;
+}
+declare function wrapGroq<T extends any>(client: T, options?: WrapGroqOptions): T;
+
+interface LiteLLMOptions {
+    baseURL: string;
+    apiKey?: string;
+    operation?: string;
+}
+declare function wrapLiteLLM(opts: LiteLLMOptions, guardrailOptions?: WrapperGuardrailsOptions): OpenAI;
+
+declare class ZespanCallbackHandler extends BaseCallbackHandler {
+    name: string;
+    private guardrailSettings;
+    private runs;
+    constructor(options?: WrapperGuardrailsOptions);
+    private detectProvider;
+    private extractToolCalls;
+    private detectConversationInfo;
+    private detectAgentFromPrompts;
+    private detectPlanning;
+    private extractCompletion;
+    handleChatModelStart(llm: Serialized, messages: any[][], runId: string, parentRunId?: string, extraParams?: any, _tags?: string[], _metadata?: Record<string, unknown>, _runName?: string): Promise<void>;
+    handleLLMStart(llm: Serialized, prompts: string[], runId: string, parentRunId?: string, extraParams?: any): Promise<void>;
+    handleLLMNewToken(_token: string, _idx: any, runId: string): Promise<void>;
+    handleLLMEnd(output: any, runId: string): Promise<void>;
+    handleLLMError(err: any, runId: string): Promise<void>;
+    handleChainStart(serialized: Serialized, inputs: Record<string, unknown>, runId: string, parentRunId?: string): Promise<void>;
+    handleChainEnd(outputs: Record<string, unknown>, runId: string): Promise<void>;
+    handleChainError(err: any, runId: string): Promise<void>;
+    handleToolStart(tool: Serialized, input: string, runId: string, parentRunId?: string): Promise<void>;
+    handleToolEnd(output: string, runId: string): Promise<void>;
+    handleToolError(err: any, runId: string): Promise<void>;
+    handleAgentAction(action: any, runId: string): Promise<void>;
+    handleRetrieverStart(_retriever: Serialized, query: string, runId: string, parentRunId?: string): Promise<void>;
+    handleRetrieverEnd(documents: any[], runId: string): Promise<void>;
+    handleRetrieverError(err: any, runId: string): Promise<void>;
+}
+declare const LumiqCallbackHandler: typeof ZespanCallbackHandler;
+
+declare class ZespanADKCallbackHandler {
+    private agentStates;
+    private pendingModelCalls;
+    private toolCallStates;
+    private agentKey;
+    private getParentAgentState;
+    beforeAgentCallback: (context: any) => undefined;
+    afterAgentCallback: (context: any) => undefined;
+    beforeModelCallback: ({ context, request: _request }: any) => undefined;
+    afterModelCallback: ({ context, response }: any) => undefined;
+    beforeToolCallback: ({ tool, args, context }: any) => undefined;
+    afterToolCallback: ({ tool: _tool, args: _args, context, response }: any) => undefined;
+    /** Spread into LlmAgent config to wire up all callbacks */
+    get callbacks(): {
+        beforeAgentCallback: (context: any) => undefined;
+        afterAgentCallback: (context: any) => undefined;
+        beforeModelCallback: ({ context, request: _request }: any) => undefined;
+        afterModelCallback: ({ context, response }: any) => undefined;
+        beforeToolCallback: ({ tool, args, context }: any) => undefined;
+        afterToolCallback: ({ tool: _tool, args: _args, context, response }: any) => undefined;
+    };
+}
+
+interface ADKAgentOptions extends WrapperGuardrailsOptions {
+    /** Display name for this agent in traces (defaults to agent.name) */
+    agentName?: string;
+    /** Role label: "coordinator" | "specialist" | "planner" etc. */
+    agentRole?: string;
+    /** Recursively wrap subAgents array on the coordinator (default: true) */
+    traceSubAgents?: boolean;
+    /** Session ID for grouping related traces together */
+    sessionId?: string;
+}
+interface ADKRunnerOptions {
+    /** Name of the root coordinator agent */
+    agentName?: string;
+    /** Role label for the root agent (default: "coordinator") */
+    agentRole?: string;
+    /** Gemini model override — use if ADK doesn't expose model on events */
+    model?: string;
+    /** Session ID for grouping related traces together */
+    sessionId?: string;
+}
+interface InstrumentADKOptions extends ADKAgentOptions, ADKRunnerOptions {
+    coordinator: any;
+    runner: any;
+}
+declare function wrapADKAgent<T>(agent: T, options?: ADKAgentOptions): T;
+declare function wrapADKRunner<T>(runner: T, options?: ADKRunnerOptions): T;
+declare function instrumentADK(options: InstrumentADKOptions): {
+    coordinator: any;
+    runner: any;
+};
+declare const wrapZespanADKAgent: typeof wrapADKAgent;
+
+interface TelemetrySettings {
+    isEnabled: boolean;
+    tracer: Tracer;
+}
+declare function instrumentVercelAI(): {
+    tracer: Tracer;
+    telemetry: TelemetrySettings;
+};
+declare function getLumiqVercelTelemetry(): TelemetrySettings;
+
+declare class LumiqLlamaIndexHandler {
+    private runs;
+    private guardrailSettings;
+    constructor(options?: WrapperGuardrailsOptions);
+    private _onLLMStart;
+    private _onLLMEnd;
+    private _onLLMStream;
+    private _onToolCall;
+    private _onToolResult;
+    private _onAgentStart;
+    private _onAgentEnd;
+    attach(callbackManager: any): void;
+    detach(callbackManager: any): void;
+}
+
+declare function startSpan(opts: {
+    name: string;
+    model?: string;
+    provider?: string;
+    span_kind?: SpanKind$1;
+}): {
+    span: {
+        setEvalScore(name: string, score: number): void;
+        end(endOpts: {
+            status: "success" | "error" | "timeout" | "rate_limited" | "cancelled";
+            input_tokens?: number;
+            output_tokens?: number;
+            cost_usd?: number;
+            error_message?: string;
+        }): Promise<void>;
+    };
+    run: <T>(fn: () => T) => T;
+};
+
+interface ZespanContextOptions {
+    traceId?: string;
+    userId?: string;
+    sessionId?: string;
+    tags?: Record<string, string>;
+    agentId?: string;
+    agentName?: string;
+    agentRole?: string;
+    agentFramework?: string;
+}
+declare function withZespanContext<T>(options: ZespanContextOptions, fn: () => T | Promise<T>): T | Promise<T>;
+declare function withZespanTrace<T>(fn: () => T | Promise<T>, options?: ZespanContextOptions): T | Promise<T>;
+declare const withZespan: typeof withZespanTrace;
+type LumiqContextOptions = ZespanContextOptions;
+declare const withLumiqContext: typeof withZespanContext;
+
+interface AgentOptions {
+    name: string;
+    role?: string;
+    framework?: string;
+    tools?: ToolDefinition[];
+    metadata?: Record<string, unknown>;
+}
+declare class AgentContext {
+    readonly agentId: string;
+    readonly name: string;
+    readonly role: string;
+    readonly framework: string;
+    readonly tools: ToolDefinition[];
+    constructor(agentId: string, options: AgentOptions);
+    logPlan(steps: string[]): void;
+    traceTool<T>(toolName: string, args: Record<string, unknown>, fn: () => T | Promise<T>): Promise<T>;
+    delegateTo(targetAgentName: string, reason?: string): void;
+}
+declare function withAgent<T>(options: AgentOptions, fn: (agent: AgentContext) => T | Promise<T>): T | Promise<T>;
+
+declare function markFrameworkActive(spanId: string): void;
+declare function markFrameworkInactive(spanId: string): void;
+/**
+ * Auto-patch all detected AI provider prototypes.
+ * Called automatically from initZespan() unless autopatch: false.
+ * Safe to call multiple times — guarded by module-level flags.
+ *
+ * Patches are also applied eagerly when this module is first loaded
+ * (via an async IIFE that resolves before test code runs). Calling
+ * autopatch() explicitly is a no-op if already patched.
+ *
+ * Frameworks (LangChain, ADK) are NOT auto-patched here — they use their
+ * native callback/event APIs (ZespanCallbackHandler, instrumentADK).
+ * Those handlers call markFrameworkActive/markFrameworkInactive to suppress
+ * this patcher while a framework trace is running, preventing double-events.
+ */
+declare function autopatch(): void;
+
+declare class BaggageSpanProcessor implements SpanProcessor {
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+
+/**
+ * Inject W3C trace context + agent delegation metadata into outgoing HTTP headers.
+ * Call this before making an HTTP request to a downstream agent.
+ */
+declare function injectAgentContext(headers: Record<string, string>, delegationReason?: string, taskDescription?: string): void;
+/**
+ * Extract W3C trace context from incoming HTTP headers on the receiving agent side.
+ * Pass the returned context to tracer.startSpan() via the third argument.
+ */
+declare function extractAgentContext(headers: Record<string, string>): Context;
+
+/**
+ * CrewAI context bridge for Zespan.
+ *
+ * Python-side: use openinference-instrumentation-crewai (PyPI).
+ * When a CrewAI agent makes an HTTP call to a Node.js service,
+ * the downstream service uses extractAgentContext() to continue the trace.
+ *
+ * Usage in the receiving Node.js service:
+ *   import { extractAgentContext } from '@zespan/sdk';
+ *   const ctx = extractAgentContext(req.headers);
+ *   const span = tracer.startSpan('invoke_agent SubAgent', undefined, ctx);
+ */
+declare const CREWAI_OTEL_ENV: {
+    readonly OTEL_EXPORTER_OTLP_ENDPOINT: "http://localhost:4318";
+    readonly OTEL_SERVICE_NAME: "crewai-agent";
+};
+/**
+ * Configuration guide for CrewAI Python instrumentation.
+ */
+declare function getCrewAIInstrumentationGuide(): string;
+
+/**
+ * Attach trace context to an AutoGen message payload.
+ * Call before sending a message to another AutoGen agent over HTTP.
+ */
+declare function attachTraceToAutoGenMessage<T extends Record<string, unknown>>(message: T, delegationReason?: string): T & {
+    _lumiq_trace: Record<string, string>;
+};
+/**
+ * Extract trace context from an incoming AutoGen message.
+ */
+declare function extractTraceFromAutoGenMessage(message: Record<string, unknown>): _opentelemetry_api.Context;
+
+/**
+ * Pydantic AI / Logfire context bridge for Zespan.
+ *
+ * Pydantic AI uses Logfire (OTel-native) for instrumentation.
+ * Configure the OTLP exporter to point at Zespan's ingest endpoint.
+ *
+ * In your Python environment:
+ *   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+ *   OTEL_SERVICE_NAME=pydantic-ai-agent
+ *
+ * Pydantic AI auto-instruments with:
+ *   import logfire
+ *   logfire.configure(send_to_logfire=False)  # OTel only, no Logfire cloud
+ */
+declare function getPydanticAIConfig(otlpEndpoint: string): Record<string, string>;
+
+declare const zespan: {
+    init: (o: ZespanOptions) => void;
+    getClient: () => ZespanClient;
+    getZespanClient: () => ZespanClient;
+    wrapOpenAI: typeof wrapOpenAI;
+    wrapAnthropic: typeof wrapAnthropic;
+    wrapGoogle: typeof wrapGoogle;
+    wrapOpenRouter: typeof wrapOpenRouter;
+    wrapADKAgent: typeof wrapADKAgent;
+    wrapADKRunner: typeof wrapADKRunner;
+    instrumentADK: typeof instrumentADK;
+    startSpan: typeof startSpan;
+    withContext: typeof withZespanContext;
+    withTrace: typeof withZespanTrace;
+    withAgent: typeof withAgent;
+    initOTel: typeof initOTel;
+    getTracer: typeof getTracer;
+    createSpan: typeof createSpan;
+    withSpan: typeof withSpan;
+    PromptClient: typeof PromptClient;
+    CallbackHandler: typeof ZespanCallbackHandler;
+    ADKCallbackHandler: typeof ZespanADKCallbackHandler;
+    autopatch: typeof autopatch;
+    markFrameworkActive: typeof markFrameworkActive;
+    markFrameworkInactive: typeof markFrameworkInactive;
+    instrumentVercelAI: typeof instrumentVercelAI;
+    getLumiqVercelTelemetry: typeof getLumiqVercelTelemetry;
+    LumiqLlamaIndexHandler: typeof LumiqLlamaIndexHandler;
+};
+
+export { type ADKAgentOptions, type ADKRunnerOptions, AgentContext, type AgentOptions, BaggageSpanProcessor, CREWAI_OTEL_ENV, GuardrailBlockedError, type GuardrailCheckInput, type GuardrailCheckResponse, type GuardrailResult, type InstrumentADKOptions, LumiqCallbackHandler, ZespanClient as LumiqClient, type LumiqContextOptions, LumiqLlamaIndexHandler, type OTelConfig, type Prompt, PromptClient, type PromptOptions, type ResolvedWrapperGuardrailsSettings, type WrapperGuardrailsOptions, type WrapperGuardrailsSettings, ZespanADKCallbackHandler, ZespanCallbackHandler, ZespanClient, type ZespanContextOptions, attachTraceToAutoGenMessage, autopatch, createSpan, extractAgentContext, extractAgentContext as extractAutoGenContext, extractTraceFromAutoGenMessage, getCrewAIInstrumentationGuide, getLumiqClient, getLumiqVercelTelemetry, getPydanticAIConfig, getTracer, getZespanClient, init, initOTel, initZespan, injectAgentContext, injectAgentContext as injectAutoGenContext, instrumentADK, instrumentVercelAI, markFrameworkActive, markFrameworkInactive, startSpan, withAgent, withLumiqContext, withSpan, withZespan, withZespanContext, withZespanTrace, wrapADKAgent, wrapADKRunner, wrapAnthropic, wrapBedrock, wrapGoogle, wrapGroq, wrapLiteLLM, wrapMistral, wrapOpenAI, wrapOpenRouter, wrapZespanADKAgent, zespan };