@sentrial/sdk 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,6 +1,80 @@
+/**
+ * PII Redaction Module
+ *
+ * Automatically detects and redacts personally identifiable information (PII)
+ * from SDK payloads before they are sent to the Sentrial API.
+ */
+/** How redacted values are replaced */
+type PiiMode = 'label' | 'hash' | 'remove';
+/** Fields that can be redacted in SDK payloads */
+type PiiField = 'userInput' | 'assistantOutput' | 'toolInput' | 'toolOutput' | 'metadata' | 'reasoning' | 'failureReason';
+/** A custom regex pattern with a human-readable label */
+interface PiiCustomPattern {
+    pattern: RegExp;
+    label: string;
+}
+/** Toggle individual builtin pattern categories */
+interface PiiBuiltinPatterns {
+    emails?: boolean;
+    phones?: boolean;
+    ssns?: boolean;
+    creditCards?: boolean;
+    ipAddresses?: boolean;
+}
+/** Full PII redaction configuration */
+interface PiiConfig {
+    /** Enable PII redaction (default: false) */
+    enabled: boolean;
+    /** Which payload fields to redact (default: DEFAULT_FIELDS) */
+    fields?: PiiField[];
+    /** Replacement mode (default: 'label') */
+    mode?: PiiMode;
+    /** Enable enhanced detection heuristics (reserved for future use) */
+    enhancedDetection?: boolean;
+    /** Toggle builtin patterns (default: all enabled) */
+    builtinPatterns?: PiiBuiltinPatterns;
+    /** Additional custom patterns to apply */
+    customPatterns?: PiiCustomPattern[];
+}
+/**
+ * Hash a value using SHA-256 and return the first 6 hex characters.
+ * Used in 'hash' mode to produce a short, deterministic pseudonym.
+ */
+declare function hashValue(value: string): string;
+/**
+ * Produce the replacement string for a matched PII value.
+ *
+ * - 'label' mode:  [LABEL]
+ * - 'hash' mode:   [PII:abcdef]
+ * - 'remove' mode: '' (empty string)
+ */
+declare function replaceMatch(match: string, label: string, mode: PiiMode): string;
+/**
+ * Run all enabled builtin and custom patterns against a single string,
+ * replacing every match according to the specified mode.
+ */
+declare function redactString(value: string, mode: PiiMode, builtinPatterns: Required<PiiBuiltinPatterns>, customPatterns: PiiCustomPattern[]): string;
+/**
+ * Recursively redact PII from a value. Handles strings, arrays, plain objects,
+ * and passes through primitives (numbers, booleans, null, undefined) unchanged.
+ */
+declare function redactValue(value: unknown, mode: PiiMode, builtinPatterns: Required<PiiBuiltinPatterns>, customPatterns: PiiCustomPattern[]): unknown;
+/**
+ * Main entry point: redact configured fields in a payload object.
+ *
+ * Only fields listed in the PiiConfig (or DEFAULT_FIELDS) are redacted.
+ * Other fields are returned unchanged.
+ *
+ * @param payload - The data payload (e.g., session params, tool call params)
+ * @param config  - PII configuration from the client
+ * @returns A new payload object with PII redacted from the configured fields
+ */
+declare function redactPayload(payload: Record<string, unknown>, config: PiiConfig): Record<string, unknown>;
+
 /**
  * Type definitions for the Sentrial TypeScript SDK
  */
+
 /**
  * Event types that can be tracked in a session
  */
@@ -27,6 +101,12 @@ interface SentrialClientConfig {
      * Set to false during development to see full errors.
      */
     failSilently?: boolean;
+    /**
+     * PII redaction configuration.
+     * - Pass a PiiConfig object for full control.
+     * - Pass `true` to fetch the org's PII config from the server automatically.
+     */
+    pii?: PiiConfig | boolean;
 }
 /**
  * Parameters for creating a new session
@@ -38,6 +118,10 @@ interface CreateSessionParams {
     agentName: string;
     /** External user ID (for grouping sessions by end-user) */
     userId: string;
+    /** Optional parent session ID for multi-agent hierarchies */
+    parentSessionId?: string;
+    /** Optional conversation ID to group related sessions into a thread */
+    convoId?: string;
     /** Optional metadata */
     metadata?: Record<string, unknown>;
 }
@@ -67,6 +151,8 @@ interface CompleteSessionParams {
     userInput?: string;
     /** The final assistant response for this session */
     assistantOutput?: string;
+    /** Alias for assistantOutput - the final output text */
+    output?: string;
 }
 /**
  * Session data returned from the API
@@ -74,6 +160,8 @@ interface CompleteSessionParams {
 interface Session {
     id: string;
     agentId?: string;
+    parentSessionId?: string;
+    convoId?: string;
     name: string;
     agentName: string;
     userId: string;
@@ -363,12 +451,26 @@ declare class SentrialClient {
     private readonly apiUrl;
     private readonly apiKey?;
     private readonly failSilently;
+    private piiConfig?;
+    private piiConfigNeedsHydration;
+    private piiHydrationPromise?;
     private currentState;
     constructor(config?: SentrialClientConfig);
     /**
-     * Make an HTTP request with graceful error handling
+     * Fetch the organization's PII config from the server.
+     *
+     * Called lazily on the first request when `pii: true` was passed to the constructor.
+     * Uses a single shared promise so concurrent requests don't trigger duplicate fetches.
+     */
+    private hydratePiiConfig;
+    /**
+     * Make an HTTP request with retry logic and exponential backoff.
+     *
+     * Retries on transient failures (network errors, timeouts, 429/5xx).
+     * Up to MAX_RETRIES attempts with exponential backoff.
      */
     private safeRequest;
+    private sleep;
     /**
      * Create a new session
      *
@@ -404,6 +506,26 @@ declare class SentrialClient {
      * @param value - State value
      */
     updateState(key: string, value: unknown): void;
+    /**
+     * Set the user input for a session
+     *
+     * @param sessionId - Session ID
+     * @param input - User input text
+     * @returns Updated session or null on error
+     */
+    setInput(sessionId: string, input: string): Promise<Session | null>;
+    /**
+     * Track a generic event
+     *
+     * @param params - Event parameters
+     * @returns Event data or null on error
+     */
+    trackEvent(params: {
+        sessionId: string;
+        eventType: string;
+        eventData?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+    }): Promise<Event | null>;
     /**
      * Complete a session with performance metrics
      *
@@ -462,6 +584,7 @@ interface InteractionConfig {
     eventId: string;
     userId: string;
     event: string;
+    userInput?: string;
 }
 /**
  * Represents an in-progress interaction that can be finished.
@@ -485,6 +608,7 @@ declare class Interaction {
     private success;
     private failureReason?;
     private output?;
+    private readonly userInput?;
     private readonly degraded;
     constructor(config: InteractionConfig);
     /**
@@ -639,4 +763,921 @@ declare class ValidationError extends SentrialError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
-export { ApiError, type ApiResponse, type BeginParams, type CompleteSessionParams, type CostParams, type CreateSessionParams, type Event, EventType, type FinishParams, Interaction, NetworkError, SentrialClient, type SentrialClientConfig, SentrialError, type Session, type SessionStatus, type TrackDecisionParams, type TrackErrorParams, type TrackToolCallParams, ValidationError, begin, calculateAnthropicCost, calculateGoogleCost, calculateOpenAICost, configure, sentrial };
+/**
+ * Vercel AI SDK Integration for Sentrial
+ *
+ * Automatically traces AI SDK calls with full input/output logging, metrics, and tool execution.
+ * Supports Vercel AI SDK v3, v4, v5, and v6.
+ *
+ * @example Simple Usage
+ * ```ts
+ * import { configureVercel, wrapAISDK } from '@sentrial/sdk';
+ * import * as ai from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * configureVercel({
+ *   apiKey: process.env.SENTRIAL_API_KEY,
+ *   defaultAgent: 'my-ai-agent',
+ * });
+ *
+ * const { generateText } = wrapAISDK(ai);
+ *
+ * // This automatically logs to Sentrial
+ * const { text } = await generateText({
+ *   model: openai('gpt-4'),
+ *   prompt: 'What is the capital of France?',
+ * });
+ * ```
+ *
+ * @example Multi-Turn Conversations
+ * ```ts
+ * const { generateText } = wrapAISDK(ai, { convoId: 'convo_123' });
+ *
+ * // All calls are linked to the same conversation thread
+ * const { text } = await generateText({
+ *   model: openai('gpt-4o'),
+ *   messages: conversationHistory,
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+type AIModule = {
+    generateText?: Function;
+    streamText?: Function;
+    generateObject?: Function;
+    streamObject?: Function;
+    experimental_generateText?: Function;
+    experimental_streamText?: Function;
+};
+type GenerateTextParams = {
+    model: {
+        modelId?: string;
+        provider?: string;
+    } & Record<string, unknown>;
+    prompt?: string;
+    messages?: Array<{
+        role: string;
+        content: string | unknown;
+    }>;
+    system?: string;
+    tools?: Record<string, {
+        execute?: Function;
+    } & Record<string, unknown>>;
+    maxTokens?: number;
+    maxSteps?: number;
+    temperature?: number;
+    [key: string]: unknown;
+};
+type UsageInfo = {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+};
+type StepResult = {
+    text?: string;
+    toolCalls?: Array<{
+        toolName: string;
+        args: unknown;
+    }>;
+    toolResults?: Array<{
+        toolName: string;
+        result: unknown;
+    }>;
+    usage?: UsageInfo;
+    finishReason?: string;
+};
+type GenerateTextResult = {
+    text: string;
+    usage?: UsageInfo;
+    finishReason?: string;
+    toolCalls?: Array<{
+        toolName: string;
+        args: unknown;
+    }>;
+    toolResults?: Array<{
+        toolName: string;
+        result: unknown;
+    }>;
+    response?: {
+        modelId?: string;
+        id?: string;
+    };
+    steps?: StepResult[];
+    reasoning?: unknown;
+    reasoningText?: string;
+    sources?: unknown[];
+    [key: string]: unknown;
+};
+type StreamTextResult = {
+    textStream: AsyncIterable<string>;
+    fullStream?: AsyncIterable<unknown>;
+    text?: string | Promise<string>;
+    usage?: Promise<UsageInfo>;
+    finishReason?: Promise<string>;
+    toolCalls?: Promise<Array<{
+        toolName: string;
+        args: unknown;
+    }>>;
+    toolResults?: Promise<Array<{
+        toolName: string;
+        result: unknown;
+    }>>;
+    steps?: Promise<StepResult[]>;
+    response?: Promise<{
+        modelId?: string;
+        id?: string;
+    }>;
+    [key: string]: unknown;
+};
+/** Per-instance config passed through closures (not global) */
+type WrapperConfig = {
+    defaultAgent?: string;
+    userId?: string;
+    convoId?: string;
+};
+/**
+ * Configure the Sentrial SDK for Vercel AI SDK integration.
+ *
+ * @example
+ * ```ts
+ * import { configureVercel } from '@sentrial/sdk';
+ *
+ * configureVercel({
+ *   apiKey: process.env.SENTRIAL_API_KEY,
+ *   defaultAgent: 'my-chatbot',
+ *   userId: 'user_123',
+ * });
+ * ```
+ */
+declare function configureVercel(config: {
+    apiKey?: string;
+    apiUrl?: string;
+    defaultAgent?: string;
+    userId?: string;
+    convoId?: string;
+    failSilently?: boolean;
+}): void;
+declare function wrapGenerateText(originalFn: Function, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => Promise<GenerateTextResult>;
+declare function wrapStreamText(originalFn: Function, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => StreamTextResult;
+declare function wrapGenerateObject(originalFn: Function, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => Promise<unknown>;
+declare function wrapStreamObject(originalFn: Function, client: SentrialClient, config: WrapperConfig): (params: GenerateTextParams) => unknown;
+/**
+ * Wrap the Vercel AI SDK to automatically trace all AI calls.
+ *
+ * @param ai - The imported `ai` module from the Vercel AI SDK
+ * @param options - Optional configuration (client, defaultAgent, userId, convoId)
+ * @returns Wrapped versions of the AI SDK functions
+ *
+ * @example Using with configureVercel
+ * ```ts
+ * configureVercel({ apiKey: process.env.SENTRIAL_API_KEY, defaultAgent: 'my-agent' });
+ * const { generateText, streamText } = wrapAISDK(ai);
+ * ```
+ *
+ * @example Multi-turn conversations
+ * ```ts
+ * const { generateText } = wrapAISDK(ai, { convoId: 'convo_123' });
+ * ```
+ *
+ * @example Using with existing SentrialClient
+ * ```ts
+ * const client = new SentrialClient({ apiKey: process.env.SENTRIAL_API_KEY });
+ * const { generateText } = wrapAISDK(ai, { client, defaultAgent: 'my-agent' });
+ * ```
+ */
+declare function wrapAISDK(ai: AIModule, options?: {
+    client?: SentrialClient;
+    defaultAgent?: string;
+    userId?: string;
+    convoId?: string;
+}): {
+    generateText: ReturnType<typeof wrapGenerateText>;
+    streamText: ReturnType<typeof wrapStreamText>;
+    generateObject: ReturnType<typeof wrapGenerateObject>;
+    streamObject: ReturnType<typeof wrapStreamObject>;
+};
+
+/**
+ * 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.
+ *
+ * @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;
+
+/**
+ * Sentrial Decorators - Easy instrumentation for AI agents
+ *
+ * Provides decorators and higher-order functions for automatic tracking:
+ * - withTool: Track tool/function calls
+ * - withSession: Create session boundaries around agent runs
+ *
+ * @example Using higher-order functions (works everywhere)
+ * ```ts
+ * import { withTool, withSession, configure } from '@sentrial/sdk';
+ *
+ * configure({ apiKey: 'sentrial_live_xxx' });
+ *
+ * // Wrap a tool function
+ * const searchWeb = withTool('search', async (query: string) => {
+ *   return await fetch(`/search?q=${query}`).then(r => r.json());
+ * });
+ *
+ * // Wrap an agent session
+ * const handleRequest = withSession('support-agent', async (userId: string, message: string) => {
+ *   const results = await searchWeb(message);
+ *   return processResults(results);
+ * });
+ * ```
+ *
+ * @example Using TypeScript decorators (requires experimentalDecorators)
+ * ```ts
+ * import { Tool, Session } from '@sentrial/sdk';
+ *
+ * class MyAgent {
+ *   @Tool('search')
+ *   async searchWeb(query: string) {
+ *     return await fetch(`/search?q=${query}`).then(r => r.json());
+ *   }
+ *
+ *   @Session('support-agent')
+ *   async handleRequest(userId: string, message: string) {
+ *     const results = await this.searchWeb(message);
+ *     return processResults(results);
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Set the default client for decorators
+ */
+declare function setClient(client: SentrialClient): void;
+/**
+ * Get the current session ID (if inside a session context)
+ */
+declare function getCurrentSessionId(): string | null;
+/**
+ * Get the current interaction (if inside a session context)
+ */
+declare function getCurrentInteraction(): Interaction | null;
+type AsyncFunction<TArgs extends unknown[], TReturn> = (...args: TArgs) => Promise<TReturn>;
+type SyncFunction<TArgs extends unknown[], TReturn> = (...args: TArgs) => TReturn;
+/**
+ * Wrap a function to automatically track it as a tool call.
+ *
+ * When called within a session context, automatically tracks:
+ * - tool_input: Function arguments
+ * - tool_output: Return value
+ * - duration: Execution time
+ * - errors: Any exceptions raised
+ *
+ * @param name - Name of the tool
+ * @param fn - The function to wrap
+ * @returns Wrapped function with automatic tracking
+ *
+ * @example
+ * ```ts
+ * const searchWeb = withTool('search', async (query: string) => {
+ *   return await fetch(`/search?q=${query}`).then(r => r.json());
+ * });
+ *
+ * // Use within a session - automatically tracked
+ * const results = await searchWeb('AI agents');
+ * ```
+ */
+declare function withTool<TArgs extends unknown[], TReturn>(name: string, fn: AsyncFunction<TArgs, TReturn>): AsyncFunction<TArgs, TReturn>;
+declare function withTool<TArgs extends unknown[], TReturn>(name: string, fn: SyncFunction<TArgs, TReturn>): SyncFunction<TArgs, TReturn>;
+interface SessionOptions {
+    /** Parameter index or name for user ID (default: looks for 'userId' or first param) */
+    userIdParam?: string | number;
+    /** Parameter index or name for input (default: looks for 'input', 'message', 'query') */
+    inputParam?: string | number;
+}
+/**
+ * Wrap a function to automatically manage a session around it.
+ *
+ * Automatically:
+ * - Creates a session when the function is called
+ * - Sets up context for withTool and wrapped LLM calls
+ * - Captures output from return value
+ * - Completes the session when the function returns
+ * - Marks as failed if an exception is raised
+ *
+ * @param agentName - Name of the agent
+ * @param fn - The function to wrap
+ * @param options - Session options
+ * @returns Wrapped function with automatic session management
+ *
+ * @example
+ * ```ts
+ * const handleRequest = withSession('support-agent', async (userId: string, message: string) => {
+ *   // Session automatically created
+ *   // All withTool calls and wrapped LLM calls are tracked
+ *   const response = await processRequest(message);
+ *   return response; // Captured as output
+ * });
+ *
+ * await handleRequest('user_123', 'Hello!');
+ * ```
+ */
+declare function withSession<TArgs extends unknown[], TReturn>(agentName: string, fn: AsyncFunction<TArgs, TReturn>, options?: SessionOptions): AsyncFunction<TArgs, TReturn>;
+declare function withSession<TArgs extends unknown[], TReturn>(agentName: string, fn: SyncFunction<TArgs, TReturn>, options?: SessionOptions): AsyncFunction<TArgs, TReturn>;
+/**
+ * Method decorator to track a method as a tool call.
+ *
+ * @param name - Name of the tool (optional, defaults to method name)
+ *
+ * @example
+ * ```ts
+ * class MyAgent {
+ *   @Tool('search')
+ *   async searchWeb(query: string) {
+ *     return await fetch(`/search?q=${query}`).then(r => r.json());
+ *   }
+ * }
+ * ```
+ */
+declare function Tool(name?: string): MethodDecorator;
+/**
+ * Method decorator to wrap a method in a session.
+ *
+ * @param agentName - Name of the agent (optional, defaults to class name)
+ * @param options - Session options
+ *
+ * @example
+ * ```ts
+ * class MyAgent {
+ *   @TrackSession('support-agent')
+ *   async handleRequest(userId: string, message: string) {
+ *     // Session automatically created
+ *     const results = await this.searchWeb(message);
+ *     return processResults(results);
+ *   }
+ * }
+ * ```
+ */
+declare function TrackSession(agentName?: string, options?: SessionOptions): MethodDecorator;
+/**
+ * Manual session context for when you need more control.
+ *
+ * @example
+ * ```ts
+ * const ctx = new SessionContext({
+ *   userId: 'user_123',
+ *   agent: 'my-agent',
+ *   input: 'Hello!',
+ * });
+ *
+ * await ctx.start();
+ * try {
+ *   // All tool calls are tracked
+ *   const result = await myTool(...);
+ *   ctx.setOutput(result);
+ *   await ctx.finish();
+ * } catch (error) {
+ *   await ctx.finish({ success: false, error: error.message });
+ * }
+ * ```
+ */
+declare class SessionContext {
+    private readonly userId;
+    private readonly agent;
+    private readonly input?;
+    private readonly client;
+    private interaction;
+    private output?;
+    constructor(options: {
+        userId: string;
+        agent: string;
+        input?: string;
+        client?: SentrialClient;
+    });
+    /**
+     * Start the session
+     */
+    start(): Promise<this>;
+    /**
+     * Set the output for this session
+     */
+    setOutput(output: string): void;
+    /**
+     * Finish the session
+     */
+    finish(options?: {
+        success?: boolean;
+        error?: string;
+    }): Promise<void>;
+    /**
+     * Get the session ID
+     */
+    get sessionId(): string | null;
+}
+
+/**
+ * Sentrial Experiment Context
+ *
+ * Provides context-aware configuration for experiments. When running experiments
+ * via the CLI, the system prompt and other experiment config is automatically
+ * available to your agent code via simple function calls.
+ *
+ * @example
+ * ```ts
+ * import { getSystemPrompt } from '@sentrial/sdk';
+ *
+ * async function myAgent(query: string): Promise<string> {
+ *   // When running normally: returns your default
+ *   // When running experiment: returns the variant's system prompt
+ *   const systemPrompt = getSystemPrompt('You are a helpful assistant.');
+ *
+ *   const response = await openai.chat.completions.create({
+ *     model: 'gpt-4o',
+ *     messages: [
+ *       { role: 'system', content: systemPrompt },
+ *       { role: 'user', content: query },
+ *     ],
+ *   });
+ *
+ *   return response.choices[0].message.content!;
+ * }
+ * ```
+ *
+ * That's it! No other changes needed. The experiment runner handles setting the context.
+ */
+/**
+ * Context for the current experiment run.
+ */
+interface ExperimentContext {
+    /** The system prompt for this variant */
+    systemPrompt: string;
+    /** Name of the variant being tested */
+    variantName: string;
+    /** The experiment ID */
+    experimentId: string;
+    /** The test case session ID (if applicable) */
+    testCaseId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Get the current system prompt.
+ *
+ * When running an experiment, this returns the variant's system prompt.
+ * Otherwise, returns your default.
+ *
+ * @param defaultPrompt - The default system prompt to use when not in experiment mode.
+ *                        This should be your normal production prompt.
+ * @returns The system prompt to use.
+ *
+ * @example
+ * ```ts
+ * import { getSystemPrompt } from '@sentrial/sdk';
+ *
+ * async function myAgent(query: string) {
+ *   // Just wrap your existing prompt with getSystemPrompt()
+ *   const prompt = getSystemPrompt('You are a helpful weather assistant.');
+ *
+ *   const response = await openai.chat.completions.create({
+ *     model: 'gpt-4o',
+ *     messages: [
+ *       { role: 'system', content: prompt },
+ *       { role: 'user', content: query },
+ *     ],
+ *   });
+ *
+ *   return response.choices[0].message.content;
+ * }
+ * ```
+ */
+declare function getSystemPrompt(defaultPrompt?: string): string;
+/**
+ * Get the full experiment context if running in experiment mode.
+ *
+ * Returns null if not running an experiment.
+ *
+ * @returns ExperimentContext with variant info, or null.
+ *
+ * @example
+ * ```ts
+ * import { getExperimentContext } from '@sentrial/sdk';
+ *
+ * const ctx = getExperimentContext();
+ * if (ctx) {
+ *   console.log(`Running variant: ${ctx.variantName}`);
+ * }
+ * ```
+ */
+declare function getExperimentContext(): ExperimentContext | null;
+/**
+ * Check if currently running in experiment mode.
+ *
+ * @returns True if running via experiment runner, false otherwise.
+ */
+declare function isExperimentMode(): boolean;
+/**
+ * Get the current variant name if in experiment mode.
+ *
+ * @returns The variant name (e.g., "Control", "Variant A"), or null.
+ */
+declare function getVariantName(): string | null;
+/**
+ * Get the current experiment ID if in experiment mode.
+ *
+ * @returns The experiment ID, or null.
+ */
+declare function getExperimentId(): string | null;
+/**
+ * Set the experiment context. Called by the experiment runner before running agent.
+ *
+ * @internal This is an internal function - users don't need to call this directly.
+ */
+declare function setExperimentContext(context: ExperimentContext): void;
+/**
+ * Clear the experiment context. Called by the experiment runner after agent completes.
+ *
+ * @internal This is an internal function - users don't need to call this directly.
+ */
+declare function clearExperimentContext(): void;
+
+/**
+ * Sentrial Experiments - Run prompt A/B tests with results synced to Sentrial
+ *
+ * @example
+ * ```ts
+ * import { Experiment } from '@sentrial/sdk';
+ *
+ * const experiment = new Experiment('exp_abc123');
+ *
+ * // Get config
+ * await experiment.load();
+ * console.log(`Testing ${experiment.variants.length} variants on ${experiment.testCases.length} inputs`);
+ *
+ * // Run with your agent function
+ * await experiment.run(async (testCase, variant, tracker) => {
+ *   // Create a session for this run
+ *   const interaction = await client.begin({
+ *     userId: 'experiment',
+ *     event: 'my-agent',
+ *     input: testCase.userInput,
+ *   });
+ *   tracker.setResultSessionId(interaction.getSessionId()!);
+ *
+ *   // Run your agent with the variant's system prompt
+ *   const response = await runAgent(testCase.userInput, variant.systemPrompt);
+ *
+ *   await interaction.finish({ output: response, success: true });
+ * });
+ * ```
+ *
+ * @example Manual run tracking
+ * ```ts
+ * const experiment = new Experiment('exp_abc123');
+ * await experiment.load();
+ *
+ * for (const variant of experiment.variants) {
+ *   for (const testCase of experiment.testCases) {
+ *     const tracker = await experiment.trackRun(variant.name, testCase.sessionId);
+ *     try {
+ *       const sessionId = await runAgent(testCase.userInput, variant.systemPrompt);
+ *       tracker.setResultSessionId(sessionId);
+ *       await tracker.complete();
+ *     } catch (error) {
+ *       await tracker.fail(error.message);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * A prompt variant to test.
+ */
+interface ExperimentVariant {
+    /** Name of the variant */
+    name: string;
+    /** The system prompt for this variant */
+    systemPrompt: string;
+    /** Optional description */
+    description?: string;
+}
+/**
+ * A test case (input) to run against each variant.
+ */
+interface ExperimentTestCase {
+    /** Session ID of the original session */
+    sessionId: string;
+    /** The user input to test */
+    userInput: string;
+}
+/**
+ * Result of a single experiment run.
+ */
+interface ExperimentRunResult {
+    /** Name of the variant */
+    variantName: string;
+    /** Session ID of the original test case */
+    testCaseSessionId: string;
+    /** Session ID of the result session (if created) */
+    resultSessionId?: string;
+    /** Whether the run succeeded */
+    success: boolean;
+    /** Error message if failed */
+    errorMessage?: string;
+}
+/**
+ * Aggregated experiment results.
+ */
+interface ExperimentResults {
+    experimentId: string;
+    status: string;
+    variants: Array<{
+        name: string;
+        successRate: number;
+        avgScore?: number;
+        avgCost?: number;
+        avgDuration?: number;
+        runCount: number;
+    }>;
+    winner?: string;
+}
+/**
+ * Tracks a single experiment run.
+ *
+ * Created by Experiment.trackRun() - use this to manually track runs.
+ */
+declare class ExperimentRunTracker {
+    private readonly experiment;
+    private readonly variantName;
+    private readonly baseSessionId;
+    private runId?;
+    private resultSessionId?;
+    private _success;
+    private _errorMessage?;
+    /** @internal */
+    constructor(experiment: Experiment, variantName: string, baseSessionId: string);
+    /**
+     * Start the run - creates a run record via API.
+     */
+    start(): Promise<this>;
+    /**
+     * Set the session ID of the result session.
+     */
+    setResultSessionId(sessionId: string): void;
+    /**
+     * Mark the run as complete.
+     */
+    complete(): Promise<void>;
+    /**
+     * Mark the run as failed.
+     */
+    fail(errorMessage: string): Promise<void>;
+    /**
+     * Get the result of this run.
+     */
+    getResult(): ExperimentRunResult;
+}
+type AgentFunction = (testCase: ExperimentTestCase, variant: ExperimentVariant, tracker: ExperimentRunTracker) => Promise<void>;
+/**
+ * Run experiments with results synced to Sentrial.
+ *
+ * @example
+ * ```ts
+ * const experiment = new Experiment('exp_abc123');
+ *
+ * await experiment.load();
+ * console.log(`Testing ${experiment.variants.length} variants`);
+ *
+ * await experiment.run(async (testCase, variant, tracker) => {
+ *   const sessionId = await runMyAgent(testCase.userInput, variant.systemPrompt);
+ *   tracker.setResultSessionId(sessionId);
+ * });
+ * ```
+ */
+declare class Experiment {
+    /** The experiment ID */
+    readonly experimentId: string;
+    /** @internal */
+    readonly client: SentrialClient;
+    /** @internal */
+    readonly apiUrl: string;
+    /** @internal */
+    readonly apiKey?: string;
+    private config?;
+    private _variants?;
+    private _testCases?;
+    /**
+     * Create an experiment instance.
+     *
+     * @param experimentId - The experiment ID from Sentrial dashboard
+     * @param options - Configuration options
+     */
+    constructor(experimentId: string, options?: {
+        apiKey?: string;
+        apiUrl?: string;
+    });
+    /**
+     * Make an HTTP request to the API
+     * @internal
+     */
+    request<T>(method: string, path: string, body?: unknown): Promise<T | null>;
+    /**
+     * Load the experiment configuration from the API.
+     */
+    load(): Promise<this>;
+    /**
+     * Get experiment name.
+     */
+    get name(): string;
+    /**
+     * Get experiment status.
+     */
+    get status(): string;
+    /**
+     * Get list of variants to test.
+     */
+    get variants(): ExperimentVariant[];
+    /**
+     * Get list of test cases.
+     */
+    get testCases(): ExperimentTestCase[];
+    /**
+     * Get a specific variant by name.
+     */
+    getVariant(name: string): ExperimentVariant | undefined;
+    /**
+     * Create a run tracker for manual experiment runs.
+     */
+    trackRun(variantName: string, baseSessionId: string): Promise<ExperimentRunTracker>;
+    /**
+     * Run the experiment with all variants and test cases.
+     *
+     * @param agentFn - Function that runs your agent with a test case and variant
+     * @param options - Run options
+     * @returns List of run results
+     */
+    run(agentFn: AgentFunction, options?: {
+        /** Run test cases in parallel */
+        parallel?: boolean;
+        /** Max parallel workers */
+        maxWorkers?: number;
+    }): Promise<ExperimentRunResult[]>;
+    /**
+     * Reset all runs for this experiment (for re-running).
+     */
+    reset(): Promise<boolean>;
+    /**
+     * Fetch aggregated results from the API.
+     */
+    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 };