@lynxops/sdk 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,601 @@
+/**
+ * Execution context stored for the active Lynx trace.
+ */
+interface LynxContext {
+    runId: string;
+    agentName: string;
+    spanId?: string;
+    parentSpanId?: string;
+    sampled?: boolean;
+    workspaceId?: string;
+    agentId?: string;
+    sessionId?: string;
+    eventCounts?: Record<string, number>;
+    attributes?: Record<string, any>;
+}
+/**
+ * Options used when starting an agent run.
+ */
+interface LynxRunOptions {
+    agentName: string;
+    workspaceId?: string;
+    agentId?: string;
+    sessionId?: string;
+    runId?: string;
+}
+/**
+ * Configuration options for the Lynx SDK runtime.
+ */
+interface LynxConfig {
+    clientId: string;
+    endpoint?: string;
+    workspaceId?: string;
+    agentId?: string;
+    apiKey?: string;
+    appVersion?: string;
+    deploymentId?: string;
+    environment?: string;
+    policyVersion?: string;
+    /**
+     * Telemetry sampling ratio between 0.0 and 1.0.
+     *
+     * For example, `0.1` captures roughly 10% of traces. When omitted, all traces
+     * are captured unless a runtime context overrides sampling.
+     */
+    sampleRate?: number;
+    /**
+     * Whether request/input payloads should be captured.
+     */
+    captureInput?: boolean;
+    /**
+     * Whether response/output payloads should be captured.
+     */
+    captureOutput?: boolean;
+    /**
+     * Maximum serialized payload length for a single event.
+     */
+    maxPayloadLength?: number;
+    /**
+     * Telemetry capture and retention mode.
+     *
+     * - `full`: Capture full input/output payloads.
+     * - `metadata-only`: Capture structure, timing, usage, status, and error
+     *   metadata without raw content.
+     * - `smart`: Prefer metadata for normal events while preserving richer
+     *   details for failures, policy violations, and abnormal latency.
+     */
+    captureMode?: "full" | "metadata-only" | "smart";
+    /**
+     * Structured telemetry delivery configuration.
+     */
+    delivery?: {
+        mode?: "BLOCKING" | "BACKGROUND";
+        timeoutMs?: number;
+        flushOnRunEnd?: boolean;
+        flushIntervalMs?: number;
+        batchSize?: number;
+        maxQueueSize?: number;
+        overflowStrategy?: "DROP_OLDEST" | "DROP_NEWEST";
+    };
+    /**
+     * Circuit breaker configuration for telemetry export only.
+     */
+    circuitBreaker?: {
+        enabled?: boolean;
+        failureThreshold?: number;
+        cooldownMs?: number;
+    };
+}
+/**
+ * Token usage returned by an LLM provider.
+ */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+type LynxSessionStatus = "COMPLETED" | "FAILED" | "CANCELLED";
+type LynxBusinessStatus = "SUCCEEDED" | "FAILED" | "PARTIAL" | "UNKNOWN";
+type LynxRiskLevel = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+type LynxPolicyAction = "ALLOW" | "BLOCK" | "WARN" | "REQUIRE_APPROVAL" | "REDACT" | "MODIFY";
+type LynxGuardFailureMode = "FAIL_OPEN" | "FAIL_CLOSED" | "REQUIRE_APPROVAL";
+interface LynxOutcomeOptions {
+    status: LynxSessionStatus;
+    businessStatus?: LynxBusinessStatus;
+    reason?: string;
+    userImpact?: LynxRiskLevel;
+    metadata?: Record<string, any>;
+}
+interface LynxDecisionOptions {
+    name: string;
+    description?: string;
+    selected?: string;
+    alternatives?: string[];
+    confidence?: number;
+    reason?: string;
+    metadata?: Record<string, any>;
+}
+interface LynxToolMetadata {
+    toolVersion?: string;
+    sideEffect?: boolean;
+    riskLevel?: LynxRiskLevel;
+    externalTarget?: string;
+    idempotencyKey?: string;
+    failureMode?: LynxGuardFailureMode;
+    [key: string]: any;
+}
+interface LynxPolicyDecision {
+    allow?: boolean;
+    action?: LynxPolicyAction;
+    policyId?: string;
+    policyVersion?: string;
+    reason?: string;
+    severity?: LynxRiskLevel;
+    metadata?: Record<string, any>;
+}
+interface LynxGuardToolOptions<TArgs extends any[] = any[]> extends LynxToolMetadata {
+    beforeCall?: (context: {
+        toolName: string;
+        input: TArgs[0];
+        args: TArgs;
+        metadata?: LynxToolMetadata;
+    }) => LynxPolicyDecision | Promise<LynxPolicyDecision>;
+}
+interface LynxShutdownOptions {
+    timeoutMs?: number;
+}
+interface LynxStatus {
+    queueSize: number;
+    droppedEvents: number;
+    circuitState: "CLOSED" | "OPEN" | "HALF_OPEN" | "DISABLED";
+    lastDeliveryAt?: string;
+    lastError?: string;
+    pendingTransmissions: number;
+}
+/**
+ * Custom instrumentation rule for wrapping an LLM client method.
+ */
+interface LlmInstrumentationRule {
+    /**
+     * Returns whether the current method path should be instrumented.
+     */
+    isTargetMethod: (path: string[]) => boolean;
+    /**
+     * Extracts prompt or input data from the intercepted method arguments.
+     */
+    extractInput?: (args: any[]) => any;
+    /**
+     * Extracts response content or structured output from the method result.
+     */
+    extractOutput?: (result: any) => any;
+    /**
+     * Extracts token usage from the method result.
+     */
+    extractUsage?: (result: any) => TokenUsage | undefined;
+    /**
+     * Estimates call cost from model and token usage.
+     */
+    estimateCost?: (model: string, promptTokens: number, completionTokens: number) => number;
+}
+/**
+ * Event types captured by the Lynx SDK.
+ */
+type LynxEventType = "USER_INPUT" | "AGENT_DECISION" | "LLM_CALL" | "LLM_REASONING" | "TOOL_CALL" | "TOOL_RESULT" | "CALL_TOOLS" | "MEMORY_ACCESS" | "CONTEXT_RETRIEVAL" | "POLICY_EVALUATION" | "POLICY_VIOLATION" | "GUARDRAIL_ACTIVATED" | "SESSION_OUTCOME" | "LOOP_DETECTED" | "ERROR" | "CONTEXT_ALERT";
+/**
+ * Event payload schema used for trace, replay, and root-cause analysis.
+ */
+interface LynxEventPayloadDto {
+    input?: any;
+    output?: any;
+    error?: string;
+    arguments?: any;
+    spanId?: string;
+    parentSpanId?: string;
+    latency?: number;
+    usage?: TokenUsage;
+    cost?: number;
+    provider?: string;
+    model?: string;
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    seed?: number | string;
+    promptVersion?: string;
+    systemPromptHash?: string;
+    userPromptHash?: string;
+    messageCount?: number;
+    contextLength?: number;
+    sdkVersion?: string;
+    droppedEventCount?: number;
+    appVersion?: string;
+    deploymentId?: string;
+    environment?: string;
+    policyVersion?: string;
+    toolName?: string;
+    toolVersion?: string;
+    args?: any;
+    argsHash?: string;
+    result?: any;
+    resultSummary?: string;
+    sideEffect?: boolean;
+    riskLevel?: LynxRiskLevel;
+    externalTarget?: string;
+    retryCount?: number;
+    idempotencyKey?: string;
+    loopDetected?: boolean;
+    loopCount?: number;
+    repeatedLabel?: string;
+    isPolluted?: boolean;
+    pollutionReason?: string;
+    [key: string]: any;
+}
+interface LynxEventDto {
+    eventId?: string;
+    clientId: string;
+    runId: string;
+    agentName: string;
+    eventType: LynxEventType;
+    label: string;
+    payload: LynxEventPayloadDto;
+    timestamp: number;
+    workspaceId?: string;
+    agentId?: string;
+    sessionId?: string;
+    schemaVersion?: string;
+}
+
+declare const DEFAULT_ENDPOINT = "https://api.lynxops.co";
+declare class LynxPolicyError extends Error {
+    readonly action: Extract<LynxPolicyAction, "BLOCK" | "REQUIRE_APPROVAL">;
+    readonly policyId?: string | undefined;
+    readonly severity?: LynxToolMetadata["riskLevel"];
+    readonly reason?: string | undefined;
+    readonly metadata?: Record<string, any> | undefined;
+    constructor(message: string, action: Extract<LynxPolicyAction, "BLOCK" | "REQUIRE_APPROVAL">, policyId?: string | undefined, severity?: LynxToolMetadata["riskLevel"], reason?: string | undefined, metadata?: Record<string, any> | undefined);
+}
+/**
+ * Main telemetry collector for Lynx-instrumented AI agent runtimes.
+ *
+ * `LynxTracer` owns the active async execution context, captures semantic
+ * agent events, batches telemetry, retries failed deliveries, and provides
+ * helpers for LLM/tool instrumentation. In most applications, use the shared
+ * `lynx` instance exported from `@lynxops/sdk`; create a new instance only when
+ * you need custom configuration per process or per test.
+ *
+ * @example
+ * ```ts
+ * const tracer = new LynxTracer({
+ *   clientId: "support-service",
+ *   apiKey: process.env.LYNX_API_KEY,
+ * });
+ *
+ * await tracer.run("SupportAgent", async () => {
+ *   tracer.userInput("refund my last order");
+ *   tracer.decision("selected refund workflow");
+ * });
+ * ```
+ */
+declare class LynxTracer {
+    private static readonly storage;
+    private static readonly instances;
+    private static beforeExitHookRegistered;
+    private readonly config;
+    private readonly pendingPromises;
+    private readonly eventQueue;
+    private readonly retryQueue;
+    private lastFailureTime;
+    private backoffDelayMs;
+    private flushTimer;
+    private isShuttingDown;
+    private isFlushInProgress;
+    private consecutiveFlushFailures;
+    private circuitOpenedAt;
+    private droppedEventCount;
+    private lastDeliveryAt?;
+    private lastError?;
+    /**
+     * Creates a tracer with the provided Lynx telemetry configuration.
+     *
+     * The constructor starts a background flush timer. The timer is unref'ed in
+     * Node.js so it will not keep the process alive by itself. Call `shutdown()`
+     * in tests, short-lived scripts, or server shutdown hooks to flush remaining
+     * telemetry and clear the timer.
+     *
+     * @param config Runtime configuration for telemetry capture and delivery.
+     */
+    constructor(config: LynxConfig);
+    private static shutdownAll;
+    /**
+     * Returns the current Lynx async execution context, if one is active.
+     *
+     * This is mainly useful for advanced instrumentation helpers that need to
+     * attach their own telemetry to the currently running `run()` context.
+     *
+     * @returns The current context, or `undefined` when called outside `run()`.
+     */
+    static getStore(): LynxContext | undefined;
+    private getFlushOnRunEnd;
+    private getRequestTimeoutMs;
+    private isBackgroundOnly;
+    private getMaxQueueSize;
+    private getOverflowStrategy;
+    private enqueueEvent;
+    private enqueueRetryEvent;
+    /**
+     * Flushes queued telemetry events to the Lynx ingestion endpoint.
+     *
+     * Events are sent in a single batch request. If delivery fails, the batch is
+     * moved into an in-memory retry queue and future flushes are delayed with
+     * exponential backoff. Normal applications usually do not need to call this
+     * manually because the tracer flushes on an interval.
+     *
+     * @returns A promise that resolves after the current flush attempt completes.
+     */
+    flush(): Promise<void>;
+    private flushInternal;
+    /**
+     * Returns a lightweight snapshot of SDK delivery health.
+     *
+     * Use this for readiness diagnostics, operational dashboards, or tests. The
+     * status reflects local SDK state only; it does not perform a network request.
+     *
+     * @returns Current queue, circuit breaker, and delivery state.
+     */
+    getStatus(): LynxStatus;
+    /**
+     * Flushes queued telemetry and releases SDK timers.
+     *
+     * Use this for graceful process shutdown, tests, CLI scripts, and serverless
+     * handlers where the runtime may terminate before the background interval
+     * fires. Calling `shutdown()` more than once is safe.
+     *
+     * @returns A promise that resolves after pending telemetry transmissions settle.
+     */
+    shutdown(options?: LynxShutdownOptions): Promise<void>;
+    private isCircuitBreakerEnabled;
+    private isCircuitOpen;
+    private getCircuitState;
+    private handleSuccessfulFlush;
+    private handleFailedEvents;
+    /**
+     * Runs code inside a Lynx trace context.
+     *
+     * Every semantic event, instrumented LLM call, and instrumented tool call made
+     * inside `executionBlock` will be associated with the same run/session. Nested
+     * `run()` calls automatically inherit the parent run id and create a child
+     * span relationship.
+     *
+     * @typeParam T The value returned by the wrapped execution block.
+     * @param optionsOrAgentName Agent name or detailed run options.
+     * @param executionBlock Function to execute while the Lynx context is active.
+     * @returns The original return value of `executionBlock`.
+     *
+     * @example
+     * ```ts
+     * await lynx.run({ agentName: "SupportAgent", sessionId: "s-123" }, async () => {
+     *   lynx.userInput("I need a refund");
+     *   return await agent.handle();
+     * });
+     * ```
+     */
+    run<T>(optionsOrAgentName: string | LynxRunOptions, executionBlock: () => Promise<T> | T): Promise<T>;
+    /**
+     * Captures a custom context event for the active run.
+     *
+     * Prefer semantic helpers such as `userInput()`, `decision()`, `context()`,
+     * `memory()`, and `outcome()` when the event has a clear meaning. Use `log()`
+     * for compatibility or for ad-hoc diagnostic payloads.
+     *
+     * @param label Human-readable event label.
+     * @param payload JSON-serializable diagnostic payload.
+     */
+    log(label: string, payload: any): void;
+    /**
+     * Captures the user input that started or influenced the current agent run.
+     *
+     * This event gives root-cause analysis a clear starting point and separates
+     * user intent from prompts, tool results, and internal agent state.
+     *
+     * @param input Raw or structured user input.
+     * @param metadata Optional metadata such as `userId`, `channel`, or `locale`.
+     */
+    userInput(input: any, metadata?: Record<string, any>): void;
+    /**
+     * Captures an agent decision and the reason behind it.
+     *
+     * Use this when the agent chooses a workflow, tool, policy branch, or final
+     * action. The `options` object can include candidates, confidence scores, or
+     * any domain-specific reasoning metadata.
+     *
+     * @param reason Short explanation of the selected action.
+     * @param options Optional structured metadata about the decision.
+     */
+    decision(reasonOrDecision: string | LynxDecisionOptions, options?: Record<string, any>): void;
+    /**
+     * Captures retrieved or constructed context used by the agent.
+     *
+     * Use this for RAG results, conversation summaries, selected documents,
+     * request-scoped state, or any context that may have influenced the next LLM
+     * or tool call.
+     *
+     * @param data Context data or a summary of the context.
+     * @param metadata Optional metadata such as source, query, score, or label.
+     */
+    context(labelOrData: string | any, dataOrMetadata?: any, metadata?: Record<string, any>): void;
+    /**
+     * Adds attributes to the current run context.
+     *
+     * Attributes are attached to subsequent events captured in the same async
+     * context. Use this for stable request or business identifiers such as
+     * `orderId`, `tenantId`, or `workflowId`.
+     *
+     * @param attributes Key-value attributes to merge into the active context.
+     */
+    setAttributes(attributes: Record<string, any>): void;
+    /**
+     * Captures access to short-term or long-term agent memory.
+     *
+     * This helps identify stale memory, missing memory, or memory values that
+     * influenced an incorrect action.
+     *
+     * @param operation Memory operation name, such as `read`, `write`, or `search`.
+     * @param data Memory key/value, query result, or a safe summary.
+     * @param metadata Optional metadata such as hit/miss, store name, or freshness.
+     */
+    memory(operation: string, data: any, metadata?: Record<string, any>): void;
+    /**
+     * Captures the final technical and business outcome of the current session.
+     *
+     * Use this to distinguish "the code ran successfully" from "the business task
+     * succeeded." That distinction is central for detecting AI failures that do
+     * not throw runtime exceptions.
+     *
+     * @param options Outcome status, business status, reason, impact, and metadata.
+     */
+    outcome(options: LynxOutcomeOptions): void;
+    /**
+     * Captures a human-readable annotation for the active run.
+     *
+     * `annotate()` is intended for breadcrumbs that help operators understand the
+     * trace but do not fit one of the stricter semantic event helpers.
+     *
+     * @param label Annotation label.
+     * @param payload JSON-serializable annotation payload.
+     */
+    annotate(label: string, payload: any): void;
+    /**
+     * Captures a semantic event for the active Lynx run context.
+     */
+    private capture;
+    /**
+     * Captures an event using an explicit Lynx context.
+     *
+     * This method is public for low-level instrumentation modules, but application
+     * code should usually call the semantic helpers or `instrumentLLM()` /
+     * `instrumentTool()` instead. Payloads are processed for PII masking,
+     * capture-mode filtering, runtime metadata, and loop detection before they are
+     * queued for delivery.
+     *
+     * @param eventType Lynx event type to record.
+     * @param label Human-readable event label.
+     * @param payload JSON-serializable event payload.
+     * @param context Explicit Lynx trace context.
+     */
+    captureInternal(eventType: LynxEventDto["eventType"], label: string, payload: any, context: LynxContext): void;
+    /**
+     * Wraps an LLM client with automatic Lynx telemetry.
+     *
+     * The returned proxy preserves the original client shape while intercepting
+     * supported generation methods such as OpenAI `chat.completions.create`,
+     * Anthropic `messages.create`, Google `generateContent`, Vercel AI SDK
+     * `generateText`, LangChain `invoke`, and similar methods. Captured telemetry
+     * includes input/output, provider, model, generation config, latency, token
+     * usage, span ids, and errors.
+     *
+     * @typeParam T LLM client object type.
+     * @param instance LLM client instance to wrap.
+     * @param optionsOrLabel Event label or custom extraction/interception rules.
+     * @returns A proxy with the same public interface as `instance`.
+     */
+    instrumentLLM<T extends object>(instance: T, optionsOrLabel?: string | {
+        modelLabel?: string;
+        customRule?: Partial<LlmInstrumentationRule>;
+    }): T;
+    /**
+     * Wraps a tool function with automatic Lynx telemetry.
+     *
+     * The wrapped function emits `TOOL_CALL` before execution and `TOOL_RESULT`
+     * after success. Errors are captured as `ERROR` and then rethrown. Use
+     * `metadata` to describe side effects, risk level, external targets, or tool
+     * version so debugging and governance views can reason about the call.
+     *
+     * @typeParam T Tool function type.
+     * @param toolName Stable tool name shown in traces and analytics.
+     * @param fn Tool function to execute.
+     * @param metadata Optional tool metadata for governance and RCA.
+     * @returns A wrapped function with the same call signature as `fn`.
+     */
+    instrumentTool<T extends (...args: any[]) => any>(toolName: string, fn: T, metadata?: LynxToolMetadata): T;
+    private getDefaultFailureMode;
+    private normalizePolicyDecision;
+    private decisionFromPolicyError;
+    /**
+     * Wraps a tool with a local policy check before execution.
+     *
+     * `guardTool()` emits a `POLICY_EVALUATION` event before the tool runs. When
+     * `beforeCall` returns `{ allow: false }`, Lynx also emits
+     * `POLICY_VIOLATION` and `GUARDRAIL_ACTIVATED`, then throws before executing
+     * the original tool. This provides the SDK-side hook needed for "observe first,
+     * then prevent recurrence" workflows.
+     *
+     * @typeParam T Tool function type.
+     * @param toolName Stable tool name shown in traces and policy events.
+     * @param fn Tool function to guard.
+     * @param options Tool metadata and an optional `beforeCall` policy callback.
+     * @returns A guarded function with the same call signature as `fn`.
+     */
+    guardTool<T extends (...args: any[]) => any>(toolName: string, fn: T, options?: LynxGuardToolOptions<Parameters<T>>): T;
+    private detectLoop;
+}
+
+/**
+ * Default Lynx tracer instance configured from environment variables.
+ *
+ * This is the recommended entry point for most applications. Configure it with
+ * `LYNX_CLIENT_ID`, `LYNX_API_KEY`, and optional endpoint, capture,
+ * delivery, and deployment metadata variables before importing the SDK.
+ *
+ * @example
+ * ```ts
+ * import { lynx } from "@lynxops/sdk";
+ *
+ * await lynx.run("SupportAgent", async () => {
+ *   lynx.userInput("Where is my order?");
+ * });
+ * ```
+ */
+declare const lynx: LynxTracer;
+
+/**
+ * Wraps an LLM client object with Lynx telemetry instrumentation.
+ *
+ * This low-level helper is used by `LynxTracer.instrumentLLM()`. It returns a
+ * recursive proxy that preserves the original client API and intercepts known
+ * generation methods. Each intercepted call emits start/end `LLM_CALL` events,
+ * token usage when available, model configuration metadata, latency, span ids,
+ * and errors.
+ *
+ * Most application code should call `lynx.instrumentLLM(client, options)`
+ * instead of importing this helper directly.
+ *
+ * @typeParam T LLM client object type.
+ * @param tracer Tracer that receives captured telemetry.
+ * @param instance LLM client instance to wrap.
+ * @param optionsOrLabel Event label or custom extraction/interception rules.
+ * @returns A proxy with the same public shape as `instance`.
+ */
+declare function instrumentLLM<T extends object>(tracer: LynxTracer, instance: T, optionsOrLabel?: string | {
+    modelLabel?: string;
+    customRule?: Partial<LlmInstrumentationRule>;
+}): T;
+/**
+ * Wraps a tool function with Lynx telemetry instrumentation.
+ *
+ * This low-level helper is used by `LynxTracer.instrumentTool()`. The wrapped
+ * function emits `TOOL_CALL` before execution and `TOOL_RESULT` after success.
+ * If the tool throws, an `ERROR` event is captured and the original error is
+ * rethrown.
+ *
+ * Most application code should call `lynx.instrumentTool(name, fn, metadata)`
+ * instead of importing this helper directly.
+ *
+ * @typeParam T Tool function type.
+ * @param tracer Tracer that receives captured telemetry.
+ * @param toolName Stable tool name shown in traces and analytics.
+ * @param fn Tool function to execute.
+ * @param metadata Optional tool metadata such as risk level or side effects.
+ * @returns A wrapped function with the same call signature as `fn`.
+ */
+declare function instrumentTool<T extends (...args: any[]) => any>(tracer: LynxTracer, toolName: string, fn: T, metadata?: LynxToolMetadata): T;
+
+export { DEFAULT_ENDPOINT, type LlmInstrumentationRule, type LynxBusinessStatus, type LynxConfig, type LynxContext, type LynxDecisionOptions, type LynxEventDto, type LynxEventPayloadDto, type LynxEventType, type LynxGuardFailureMode, type LynxGuardToolOptions, type LynxOutcomeOptions, type LynxPolicyAction, type LynxPolicyDecision, LynxPolicyError, type LynxRiskLevel, type LynxRunOptions, type LynxSessionStatus, type LynxShutdownOptions, type LynxStatus, type LynxToolMetadata, LynxTracer, type TokenUsage, instrumentLLM, instrumentTool, lynx };