@sentrial/sdk 0.4.0 → 0.4.2

package/dist/index.d.cts

@@ -1,3 +1,194 @@
+/**
+ * Async-safe context variables for the Sentrial SDK.
+ *
+ * In Node.js (>= 18): uses AsyncLocalStorage for true per-request isolation.
+ * In browsers: falls back to a simple variable (safe because browsers have no
+ * concurrent request handling within a single page).
+ *
+ * This is the TypeScript equivalent of Python's `contextvars.ContextVar`.
+ */
+interface ContextToken<T> {
+    /** @internal */
+    readonly _previous: T;
+}
+interface ContextVar<T> {
+    /** Get the current value (returns defaultValue if unset in this context). */
+    get(): T;
+    /** Set a new value. Returns a token that can restore the previous value. */
+    set(value: T): ContextToken<T>;
+    /** Restore the value that was active before the given token's set() call. */
+    reset(token: ContextToken<T>): void;
+}
+/**
+ * Create an async-safe context variable.
+ *
+ * Uses AsyncLocalStorage in Node.js for per-request isolation,
+ * falls back to a simple variable in browsers.
+ *
+ * @param defaultValue - Value returned by get() when nothing has been set.
+ */
+declare function createContextVar<T>(defaultValue: T): ContextVar<T>;
+
+/**
+ * Sentrial LLM Wrappers - Auto-instrument LLM provider SDKs
+ *
+ * These wrappers automatically track all LLM calls with:
+ * - Input messages
+ * - Output responses
+ * - Token counts
+ * - Cost estimation
+ * - Latency
+ *
+ * @example OpenAI
+ * ```ts
+ * import OpenAI from 'openai';
+ * import { wrapOpenAI, configure } from '@sentrial/sdk';
+ *
+ * configure({ apiKey: 'sentrial_live_xxx' });
+ *
+ * const openai = wrapOpenAI(new OpenAI());
+ *
+ * // All calls are now automatically tracked!
+ * const response = await openai.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ * });
+ * ```
+ *
+ * @example Anthropic
+ * ```ts
+ * import Anthropic from '@anthropic-ai/sdk';
+ * import { wrapAnthropic, configure } from '@sentrial/sdk';
+ *
+ * configure({ apiKey: 'sentrial_live_xxx' });
+ *
+ * const anthropic = wrapAnthropic(new Anthropic());
+ *
+ * const response = await anthropic.messages.create({
+ *   model: 'claude-3-5-sonnet-20241022',
+ *   max_tokens: 1024,
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ * });
+ * ```
+ */
+
+/** Tokens for restoring previous session context (used internally by decorators). */
+interface SessionContextTokens {
+    _sessionToken: ContextToken<string | null>;
+    _clientToken: ContextToken<SentrialClient | null>;
+}
+/**
+ * Set the current session context for auto-tracking.
+ *
+ * Call this before making LLM calls to associate them with a session.
+ * This is automatically called when using withSession() or decorators.
+ *
+ * @param sessionId - The session ID to track LLM calls under
+ * @param client - Optional Sentrial client (uses default if not provided)
+ */
+declare function setSessionContext(sessionId: string, client?: SentrialClient): void;
+/**
+ * Clear the current session context.
+ */
+declare function clearSessionContext(): void;
+/**
+ * Get the current session ID.
+ */
+declare function getSessionContext(): string | null;
+/**
+ * Set the default client for wrappers.
+ */
+declare function setDefaultClient(client: SentrialClient): void;
+/**
+ * Wrap an OpenAI client to automatically track all LLM calls.
+ *
+ * @param client - OpenAI client instance
+ * @param options - Wrapper options
+ * @returns The same client, now with auto-tracking enabled
+ *
+ * @example
+ * ```ts
+ * import OpenAI from 'openai';
+ * import { wrapOpenAI, configure } from '@sentrial/sdk';
+ *
+ * configure({ apiKey: 'sentrial_live_xxx' });
+ * const openai = wrapOpenAI(new OpenAI());
+ *
+ * // Now use client normally - all calls are tracked!
+ * const response = await openai.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello' }],
+ * });
+ * ```
+ */
+declare function wrapOpenAI<T extends object>(client: T, options?: {
+    trackWithoutSession?: boolean;
+}): T;
+/**
+ * Wrap an Anthropic client to automatically track all LLM calls.
+ *
+ * @param client - Anthropic client instance
+ * @param options - Wrapper options
+ * @returns The same client, now with auto-tracking enabled
+ *
+ * @example
+ * ```ts
+ * import Anthropic from '@anthropic-ai/sdk';
+ * import { wrapAnthropic, configure } from '@sentrial/sdk';
+ *
+ * configure({ apiKey: 'sentrial_live_xxx' });
+ * const anthropic = wrapAnthropic(new Anthropic());
+ *
+ * const response = await anthropic.messages.create({
+ *   model: 'claude-3-5-sonnet-20241022',
+ *   max_tokens: 1024,
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ * });
+ * ```
+ */
+declare function wrapAnthropic<T extends object>(client: T, options?: {
+    trackWithoutSession?: boolean;
+}): T;
+/**
+ * Wrap a Google GenerativeModel to automatically track all LLM calls.
+ *
+ * @param model - Google GenerativeModel instance
+ * @param options - Wrapper options
+ * @returns The same model, now with auto-tracking enabled
+ *
+ * @example
+ * ```ts
+ * import { GoogleGenerativeAI } from '@google/generative-ai';
+ * import { wrapGoogle, configure } from '@sentrial/sdk';
+ *
+ * configure({ apiKey: 'sentrial_live_xxx' });
+ *
+ * const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY!);
+ * const model = wrapGoogle(genAI.getGenerativeModel({ model: 'gemini-2.0-flash' }));
+ *
+ * const response = await model.generateContent('Hello!');
+ * ```
+ */
+declare function wrapGoogle<T extends object>(model: T, options?: {
+    trackWithoutSession?: boolean;
+}): T;
+/**
+ * Auto-detect and wrap any supported LLM client.
+ *
+ * @param client - Any supported LLM client (OpenAI, Anthropic, Google)
+ * @param provider - Optional provider hint
+ * @returns The wrapped client
+ *
+ * @example
+ * ```ts
+ * import OpenAI from 'openai';
+ * import { wrapLLM } from '@sentrial/sdk';
+ *
+ * const client = wrapLLM(new OpenAI()); // Auto-detected as OpenAI
+ * ```
+ */
+declare function wrapLLM<T extends object>(client: T, provider?: 'openai' | 'anthropic' | 'google'): T;
+
 /**
  * PII Redaction Module
  *
@@ -71,6 +262,68 @@ declare function redactValue(value: unknown, mode: PiiMode, builtinPatterns: Req
  */
 declare function redactPayload(payload: Record<string, unknown>, config: PiiConfig): Record<string, unknown>;
 
+/**
+ * EventBatcher — fire-and-forget event queue with periodic flushing.
+ *
+ * Buffers tracking events (tool calls, decisions, errors, generic events)
+ * and flushes them in batches to reduce HTTP overhead. Session lifecycle
+ * calls (createSession, completeSession) bypass the batcher entirely
+ * because they need synchronous responses.
+ *
+ * Flush triggers:
+ *  1. Timer — every `flushIntervalMs` (default 1 000 ms)
+ *  2. Queue size — when queue reaches `flushThreshold` (default 10)
+ *  3. Manual — `flush()` or `shutdown()`
+ *  4. Process exit — `beforeExit` handler
+ *
+ * Back-pressure: queue is capped at `maxQueueSize` (default 1 000).
+ * When full, oldest events are dropped and a warning is logged.
+ */
+interface BatcherConfig {
+    /** Whether batching is enabled (default: false — all calls are immediate) */
+    enabled?: boolean;
+    /** Milliseconds between automatic flushes (default: 1000) */
+    flushIntervalMs?: number;
+    /** Flush when the queue reaches this many items (default: 10) */
+    flushThreshold?: number;
+    /** Maximum queue size before dropping oldest events (default: 1000) */
+    maxQueueSize?: number;
+}
+/** Signature for the function that actually sends an event to the API. */
+type SendFn = (method: string, url: string, body: unknown) => Promise<unknown>;
+declare class EventBatcher {
+    private readonly queue;
+    private readonly flushIntervalMs;
+    private readonly flushThreshold;
+    private readonly maxQueueSize;
+    private timer;
+    private sendFn;
+    private flushing;
+    private shutdownCalled;
+    private readonly exitHandler;
+    constructor(sendFn: SendFn, config?: BatcherConfig);
+    /**
+     * Enqueue an event for batched delivery.
+     *
+     * If the queue hits `flushThreshold`, an automatic flush is triggered.
+     * If the queue is full (`maxQueueSize`), the oldest event is dropped.
+     */
+    enqueue(method: string, url: string, body: unknown): void;
+    /**
+     * Flush all queued events to the API.
+     *
+     * Drains the queue and fires all requests in parallel. Safe to call
+     * concurrently — only one flush runs at a time.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop the batcher: clear the timer, flush remaining events, remove exit handler.
+     */
+    shutdown(): Promise<void>;
+    /** Number of events currently queued. */
+    get size(): number;
+}
+
 /**
  * Type definitions for the Sentrial TypeScript SDK
  */
@@ -107,6 +360,14 @@ interface SentrialClientConfig {
      * - Pass `true` to fetch the org's PII config from the server automatically.
      */
     pii?: PiiConfig | boolean;
+    /**
+     * Event batching configuration.
+     * When enabled, fire-and-forget tracking calls (trackToolCall, trackDecision,
+     * trackError, trackEvent) are queued and flushed periodically instead of
+     * being sent immediately. Session lifecycle calls (createSession,
+     * completeSession) always bypass the batcher.
+     */
+    batching?: BatcherConfig;
 }
 /**
  * Parameters for creating a new session
@@ -318,6 +579,8 @@ interface FinishParams {
     completionTokens?: number;
     /** Total tokens used */
     totalTokens?: number;
+    /** Duration in milliseconds (auto-calculated from begin/finish if not provided) */
+    durationMs?: number;
 }
 /**
  * Parameters for cost calculation
@@ -454,7 +717,12 @@ declare class SentrialClient {
     private piiConfig?;
     private piiConfigNeedsHydration;
     private piiHydrationPromise?;
-    private currentState;
+    private readonly _stateVar;
+    private readonly batcher?;
+    /** Per-session cost/token accumulator — populated by trackToolCall/trackDecision */
+    private sessionAccumulators;
+    private get currentState();
+    private set currentState(value);
     constructor(config?: SentrialClientConfig);
     /**
      * Fetch the organization's PII config from the server.
@@ -471,6 +739,7 @@ declare class SentrialClient {
      */
     private safeRequest;
     private sleep;
+    private accumulate;
     /**
      * Create a new session
      *
@@ -553,6 +822,19 @@ declare class SentrialClient {
      * ```
      */
     completeSession(params: CompleteSessionParams): Promise<Session | null>;
+    /**
+     * Flush any queued events immediately.
+     *
+     * No-op if batching is not enabled.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shut down the event batcher, flushing remaining events.
+     *
+     * Call this before your process exits for a clean shutdown.
+     * No-op if batching is not enabled.
+     */
+    shutdown(): Promise<void>;
     /**
      * Begin tracking an interaction (simplified API)
      *
@@ -585,6 +867,7 @@ interface InteractionConfig {
     userId: string;
     event: string;
     userInput?: string;
+    sessionTokens?: SessionContextTokens;
 }
 /**
  * Represents an in-progress interaction that can be finished.
@@ -604,12 +887,15 @@ declare class Interaction {
     readonly userId: string;
     /** Event name for this interaction */
     readonly event: string;
+    private readonly startTime;
     private finished;
     private success;
     private failureReason?;
     private output?;
     private readonly userInput?;
     private readonly degraded;
+    /** Context tokens for restoring previous session context on finish() */
+    private sessionTokens?;
     constructor(config: InteractionConfig);
     /**
      * Set the output for this interaction
@@ -703,9 +989,13 @@ declare function begin(params: BeginParams): Promise<Interaction>;
 /**
  * Simple API namespace for module-level usage
  */
+declare function flush(): Promise<void>;
+declare function shutdown(): Promise<void>;
 declare const sentrial: {
     configure: typeof configure;
     begin: typeof begin;
+    flush: typeof flush;
+    shutdown: typeof shutdown;
 };
 
 /**
@@ -960,159 +1250,68 @@ declare function wrapAISDK(ai: AIModule, options?: {
 };
 
 /**
- * Sentrial LLM Wrappers - Auto-instrument LLM provider SDKs
- *
- * These wrappers automatically track all LLM calls with:
- * - Input messages
- * - Output responses
- * - Token counts
- * - Cost estimation
- * - Latency
- *
- * @example OpenAI
- * ```ts
- * import OpenAI from 'openai';
- * import { wrapOpenAI, configure } from '@sentrial/sdk';
- *
- * configure({ apiKey: 'sentrial_live_xxx' });
- *
- * const openai = wrapOpenAI(new OpenAI());
- *
- * // All calls are now automatically tracked!
- * const response = await openai.chat.completions.create({
- *   model: 'gpt-4o',
- *   messages: [{ role: 'user', content: 'Hello!' }],
- * });
- * ```
- *
- * @example Anthropic
- * ```ts
- * import Anthropic from '@anthropic-ai/sdk';
- * import { wrapAnthropic, configure } from '@sentrial/sdk';
- *
- * configure({ apiKey: 'sentrial_live_xxx' });
- *
- * const anthropic = wrapAnthropic(new Anthropic());
- *
- * const response = await anthropic.messages.create({
- *   model: 'claude-3-5-sonnet-20241022',
- *   max_tokens: 1024,
- *   messages: [{ role: 'user', content: 'Hello!' }],
- * });
- * ```
- */
-
-/**
- * Set the current session context for auto-tracking.
- *
- * Call this before making LLM calls to associate them with a session.
- * This is automatically called when using withSession() or decorators.
- *
- * @param sessionId - The session ID to track LLM calls under
- * @param client - Optional Sentrial client (uses default if not provided)
- */
-declare function setSessionContext(sessionId: string, client?: SentrialClient): void;
-/**
- * Clear the current session context.
- */
-declare function clearSessionContext(): void;
-/**
- * Get the current session ID.
- */
-declare function getSessionContext(): string | null;
-/**
- * Set the default client for wrappers.
- */
-declare function setDefaultClient(client: SentrialClient): void;
-/**
- * Wrap an OpenAI client to automatically track all LLM calls.
- *
- * @param client - OpenAI client instance
- * @param options - Wrapper options
- * @returns The same client, now with auto-tracking enabled
- *
- * @example
- * ```ts
- * import OpenAI from 'openai';
- * import { wrapOpenAI, configure } from '@sentrial/sdk';
- *
- * configure({ apiKey: 'sentrial_live_xxx' });
- * const openai = wrapOpenAI(new OpenAI());
- *
- * // Now use client normally - all calls are tracked!
- * const response = await openai.chat.completions.create({
- *   model: 'gpt-4o',
- *   messages: [{ role: 'user', content: 'Hello' }],
- * });
- * ```
- */
-declare function wrapOpenAI<T extends object>(client: T, options?: {
-    trackWithoutSession?: boolean;
-}): T;
-/**
- * Wrap an Anthropic client to automatically track all LLM calls.
+ * Sentrial wrapper for the Claude Agent SDK (Claude Code).
  *
- * @param client - Anthropic client instance
- * @param options - Wrapper options
- * @returns The same client, now with auto-tracking enabled
+ * Wraps the `query()` async generator to automatically track sessions,
+ * tool calls, tokens, and costs to Sentrial.
  *
  * @example
  * ```ts
- * import Anthropic from '@anthropic-ai/sdk';
- * import { wrapAnthropic, configure } from '@sentrial/sdk';
+ * import { query } from '@anthropic-ai/claude-agent-sdk';
+ * import { SentrialClient, wrapClaudeAgent } from '@sentrial/sdk';
  *
- * configure({ apiKey: 'sentrial_live_xxx' });
- * const anthropic = wrapAnthropic(new Anthropic());
+ * const client = new SentrialClient({ apiKey: process.env.SENTRIAL_API_KEY });
  *
- * const response = await anthropic.messages.create({
- *   model: 'claude-3-5-sonnet-20241022',
- *   max_tokens: 1024,
- *   messages: [{ role: 'user', content: 'Hello!' }],
+ * const trackedQuery = wrapClaudeAgent(query, {
+ *   client,
+ *   defaultAgent: 'my-agent',
+ *   userId: 'user-123',
  * });
- * ```
- */
-declare function wrapAnthropic<T extends object>(client: T, options?: {
-    trackWithoutSession?: boolean;
-}): T;
-/**
- * Wrap a Google GenerativeModel to automatically track all LLM calls.
  *
- * @param model - Google GenerativeModel instance
- * @param options - Wrapper options
- * @returns The same model, now with auto-tracking enabled
- *
- * @example
- * ```ts
- * import { GoogleGenerativeAI } from '@google/generative-ai';
- * import { wrapGoogle, configure } from '@sentrial/sdk';
- *
- * configure({ apiKey: 'sentrial_live_xxx' });
- *
- * const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY!);
- * const model = wrapGoogle(genAI.getGenerativeModel({ model: 'gemini-2.0-flash' }));
- *
- * const response = await model.generateContent('Hello!');
+ * for await (const message of trackedQuery({ prompt: 'Fix the tests' })) {
+ *   // Messages pass through unchanged
+ *   console.log(message.type);
+ * }
  * ```
  */
-declare function wrapGoogle<T extends object>(model: T, options?: {
-    trackWithoutSession?: boolean;
-}): T;
+
+type HookCallback = (input: any, toolUseID: string | undefined, options: {
+    signal: AbortSignal;
+}) => Promise<any>;
+interface HookCallbackMatcher {
+    matcher?: string;
+    hooks: HookCallback[];
+}
+interface QueryOptions {
+    hooks?: Record<string, HookCallbackMatcher[]>;
+    [key: string]: unknown;
+}
+interface QueryParams {
+    prompt: string | AsyncIterable<any>;
+    options?: QueryOptions;
+}
+type QueryFunction = (params: QueryParams) => AsyncGenerator<any, void>;
+interface WrapClaudeAgentOptions {
+    /** Sentrial client instance for tracking */
+    client: SentrialClient;
+    /** Default agent name (used in session creation). Defaults to 'claude-agent'. */
+    defaultAgent?: string;
+    /** User ID to associate with sessions. Defaults to 'anonymous'. */
+    userId?: string;
+    /** Conversation ID to group related sessions into a thread. */
+    convoId?: string;
+    /** Extra metadata to include in every session. */
+    extraMetadata?: Record<string, unknown>;
+}
 /**
- * Auto-detect and wrap any supported LLM client.
+ * Wrap the Claude Agent SDK's `query()` function to automatically track
+ * sessions, tool calls, tokens, and costs to Sentrial.
  *
- * @param client - Any supported LLM client (OpenAI, Anthropic, Google)
- * @param provider - Optional provider hint
- * @returns The wrapped client
- *
- * @example
- * ```ts
- * import OpenAI from 'openai';
- * import { wrapLLM } from '@sentrial/sdk';
- *
- * const client = wrapLLM(new OpenAI()); // Auto-detected as OpenAI
- * ```
+ * @param queryFn - The original `query()` function from `@anthropic-ai/claude-agent-sdk`
+ * @param wrapOptions - Configuration for the wrapper
+ * @returns A new function with the same signature as `query()`
  */
-declare function wrapLLM<T extends object>(client: T, provider?: 'openai' | 'anthropic' | 'google'): T;
+declare function wrapClaudeAgent(queryFn: QueryFunction, wrapOptions: WrapClaudeAgentOptions): QueryFunction;
 
 /**
  * Sentrial Decorators - Easy instrumentation for AI agents
@@ -1296,6 +1495,8 @@ declare class SessionContext {
     private readonly client;
     private interaction;
     private output?;
+    private sessionTokens?;
+    private interactionToken?;
     constructor(options: {
         userId: string;
         agent: string;
@@ -1680,4 +1881,4 @@ declare class Experiment {
     getResults(): Promise<ExperimentResults | null>;
 }
 
-export { ApiError, type ApiResponse, type BeginParams, type CompleteSessionParams, type CostParams, type CreateSessionParams, type Event, EventType, Experiment, type ExperimentContext, type ExperimentResults, type ExperimentRunResult, ExperimentRunTracker, type ExperimentTestCase, type ExperimentVariant, type FinishParams, type GenerateTextParams, type GenerateTextResult, Interaction, NetworkError, type PiiBuiltinPatterns, type PiiConfig, type PiiCustomPattern, type PiiField, type PiiMode, SentrialClient, type SentrialClientConfig, SentrialError, type Session, SessionContext, type SessionStatus, type StreamTextResult, Tool, type TrackDecisionParams, type TrackErrorParams, TrackSession, type TrackToolCallParams, ValidationError, begin, calculateAnthropicCost, calculateGoogleCost, calculateOpenAICost, clearExperimentContext, clearSessionContext, configure, configureVercel, getCurrentInteraction, getCurrentSessionId, getExperimentContext, getExperimentId, getSessionContext, getSystemPrompt, getVariantName, hashValue, isExperimentMode, redactPayload, redactString, redactValue, replaceMatch, sentrial, setClient, setDefaultClient, setExperimentContext, setSessionContext, withSession, withTool, wrapAISDK, wrapAnthropic, wrapGoogle, wrapLLM, wrapOpenAI };
+export { ApiError, type ApiResponse, type BatcherConfig, type BeginParams, type CompleteSessionParams, type ContextToken, type ContextVar, type CostParams, type CreateSessionParams, type Event, EventBatcher, EventType, Experiment, type ExperimentContext, type ExperimentResults, type ExperimentRunResult, ExperimentRunTracker, type ExperimentTestCase, type ExperimentVariant, type FinishParams, type GenerateTextParams, type GenerateTextResult, Interaction, NetworkError, type PiiBuiltinPatterns, type PiiConfig, type PiiCustomPattern, type PiiField, type PiiMode, SentrialClient, type SentrialClientConfig, SentrialError, type Session, SessionContext, type SessionStatus, type StreamTextResult, Tool, type TrackDecisionParams, type TrackErrorParams, TrackSession, type TrackToolCallParams, ValidationError, type WrapClaudeAgentOptions, begin, calculateAnthropicCost, calculateGoogleCost, calculateOpenAICost, clearExperimentContext, clearSessionContext, configure, configureVercel, createContextVar, getCurrentInteraction, getCurrentSessionId, getExperimentContext, getExperimentId, getSessionContext, getSystemPrompt, getVariantName, hashValue, isExperimentMode, redactPayload, redactString, redactValue, replaceMatch, sentrial, setClient, setDefaultClient, setExperimentContext, setSessionContext, withSession, withTool, wrapAISDK, wrapAnthropic, wrapClaudeAgent, wrapGoogle, wrapLLM, wrapOpenAI };