risicare 0.2.1 → 0.3.0

package/dist/index.d.cts

@@ -374,6 +374,7 @@ declare function getMetrics(): {
  * Report a caught exception to the self-healing pipeline.
  *
  * Creates an error span that triggers diagnosis and fix generation.
+ * Deduplicates identical errors within a 5-minute window (SHA256 fingerprint).
  * This function never throws and is non-blocking.
  *
  * @param error - The caught exception (Error object or string)
@@ -638,6 +639,11 @@ interface TraceContext {
 }
 /**
  * Get the current trace context as a serializable object.
+ *
+ * When called inside a span context, returns the active span's IDs.
+ * When called outside a span (e.g. inside session() but before agent()),
+ * pre-allocates a trace ID and stores it in context so the next
+ * startSpan() call inherits it — preventing trace ID mismatch.
  */
 declare function getTraceContext(): TraceContext;
 /**
@@ -728,4 +734,433 @@ declare function suppressProviderInstrumentation<T>(fn: () => T): T;
  */
 declare function isProviderInstrumentationSuppressed(): boolean;
 
-export { type AgentContext, type AgentOptions, AgentRole, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, Tracer, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, shutdown, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, withAgent, withPhase, withSession };
+/**
+ * Fix Runtime Configuration.
+ *
+ * Settings for the fix runtime including caching, refresh intervals,
+ * A/B testing, and fix application behavior.
+ *
+ * Port of Python SDK's runtime/config.py adapted for Node.js patterns.
+ */
+interface FixRuntimeConfig {
+    /** API endpoint URL (e.g., "https://app.risicare.ai") */
+    apiEndpoint: string;
+    /** API key for authentication (format: "rsk-{random}") */
+    apiKey: string;
+    /** Whether the fix runtime is enabled (default: true) */
+    enabled?: boolean;
+    /** Whether caching is enabled (default: true) */
+    cacheEnabled?: boolean;
+    /** Cache entry TTL in milliseconds (default: 300_000 = 5 min) */
+    cacheTtlMs?: number;
+    /** Maximum number of cache entries (default: 1000) */
+    cacheMaxEntries?: number;
+    /** Whether to auto-refresh fixes in background (default: true) */
+    autoRefresh?: boolean;
+    /** Background refresh interval in milliseconds (default: 60_000 = 1 min) */
+    refreshIntervalMs?: number;
+    /** Log but don't apply fixes (default: false) */
+    dryRun?: boolean;
+    /** Whether A/B testing bucketing is active (default: true) */
+    abTestingEnabled?: boolean;
+    /** Timeout for API requests in milliseconds (default: 1000) */
+    timeoutMs?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+type FixType = 'prompt' | 'parameter' | 'retry' | 'fallback' | 'guard' | 'routing' | 'tool';
+interface ActiveFix {
+    fixId: string;
+    deploymentId?: string;
+    errorCode: string;
+    fixType: FixType;
+    config: Record<string, unknown>;
+    trafficPercentage: number;
+    version: number;
+}
+
+/**
+ * Fix Cache — Local cache for active fixes with TTL eviction.
+ *
+ * Provides fast lookup of fixes keyed by error code with exact match
+ * and wildcard fallback. No locks needed — JS is single-threaded.
+ *
+ * Port of Python SDK's runtime/cache.py.
+ */
+
+interface CacheStats {
+    hits: number;
+    misses: number;
+    evictions: number;
+    size: number;
+    lastRefresh: number | null;
+}
+declare class FixCache {
+    private readonly _ttlMs;
+    private readonly _maxEntries;
+    private readonly _enabled;
+    private _cache;
+    private _stats;
+    constructor(config?: Pick<FixRuntimeConfig, 'cacheEnabled' | 'cacheTtlMs' | 'cacheMaxEntries'>);
+    /** Whether caching is enabled. */
+    get enabled(): boolean;
+    /**
+     * Get a fix by error code.
+     *
+     * Checks exact match first, then scans for wildcard matches.
+     * Expired entries are evicted on access.
+     */
+    get(errorCode: string): ActiveFix | null;
+    /**
+     * Add a single fix to the cache.
+     *
+     * Evicts the oldest entry if at capacity.
+     */
+    set(fix: ActiveFix): void;
+    /**
+     * Replace all cached fixes (bulk refresh).
+     *
+     * Clears the cache and populates with the given fixes.
+     */
+    setAll(fixes: ActiveFix[]): void;
+    /**
+     * Get all non-expired fixes.
+     */
+    getAll(): ActiveFix[];
+    /** Clear all cache entries. Returns the number of entries cleared. */
+    clear(): number;
+    /** Get cache statistics. */
+    get stats(): CacheStats;
+    /** Evict the oldest cache entry. */
+    private _evictOldest;
+}
+
+/**
+ * Fix Applier — Applies fixes to agent operations.
+ *
+ * Handles different fix types:
+ * - PromptFix:     Modify system/user prompts (prepend, append, replace, few_shot)
+ * - ParameterFix:  Adjust LLM parameters (temperature, model, etc.)
+ * - RetryFix:      Retry with exponential backoff + jitter
+ * - FallbackFix:   Switch to fallback model or default response
+ * - GuardFix:      Input/output validation (content filter, format check, length)
+ *
+ * Port of Python SDK's runtime/applier.py adapted for Node.js.
+ */
+
+interface ApplyResult {
+    applied: boolean;
+    fixId?: string;
+    deploymentId?: string;
+    fixType?: string;
+    modifications: Record<string, unknown>;
+    error?: string;
+}
+declare class FixApplier {
+    private readonly _config;
+    private readonly _cache;
+    private _applicationLog;
+    constructor(config: FixRuntimeConfig, cache: FixCache);
+    /**
+     * Get applicable fix for an error code.
+     *
+     * Considers A/B testing bucket if sessionId is provided. Uses
+     * crypto.createHash('md5') for deterministic bucketing across restarts.
+     */
+    getFixForError(errorCode: string, sessionId?: string): ActiveFix | null;
+    /**
+     * Apply a prompt fix to messages.
+     *
+     * Supports 4 modification types:
+     * - prepend: Add content before first system message
+     * - append:  Add content after first system message
+     * - replace: Regex replace across all messages
+     * - few_shot: Insert user/assistant example pairs after system message
+     */
+    applyPromptFix(fix: ActiveFix, messages: Record<string, unknown>[]): {
+        messages: Record<string, unknown>[];
+        result: ApplyResult;
+    };
+    /**
+     * Apply a parameter fix — merge config.parameters into params.
+     */
+    applyParameterFix(fix: ActiveFix, params: Record<string, unknown>): {
+        params: Record<string, unknown>;
+        result: ApplyResult;
+    };
+    /**
+     * Apply a retry fix to an async operation.
+     *
+     * Retries with exponential backoff + jitter using
+     * `await new Promise(r => setTimeout(r, delay))`.
+     */
+    applyRetryFix<T>(fix: ActiveFix, operation: () => Promise<T>): Promise<{
+        value: T;
+        result: ApplyResult;
+    }>;
+    /**
+     * Apply a fallback fix.
+     *
+     * - 'model': Replace params.model with the fallback model
+     * - 'default': Set params._fallbackResponse for the caller to use
+     */
+    applyFallbackFix(fix: ActiveFix, params: Record<string, unknown>): {
+        params: Record<string, unknown>;
+        result: ApplyResult;
+    };
+    /**
+     * Apply a guard fix (validation).
+     *
+     * Guard types:
+     * - content_filter: Regex-based blocked patterns
+     * - format_check:   JSON.parse() validity
+     * - input_validation / output_validation: min/max length
+     */
+    applyGuardFix(fix: ActiveFix, content: string, isInput?: boolean): {
+        content: string;
+        passed: boolean;
+        result: ApplyResult;
+    };
+    /** Log a fix application result. */
+    logApplication(result: ApplyResult): void;
+    /** Get the application log. */
+    getApplicationLog(): ApplyResult[];
+    /**
+     * Safely compile a regex pattern from untrusted input.
+     * Returns null if invalid or too long.
+     */
+    private _safeCompileRegex;
+    /** Prepend content to the first message matching the target role. */
+    private _prependToTarget;
+    /** Append content to the first message matching the target role. */
+    private _appendToTarget;
+    /** Regex replace across all messages. */
+    private _replaceInMessages;
+    /** Add few-shot examples after the first system message. */
+    private _addFewShotExamples;
+}
+
+/**
+ * Fix Loader — Fetches active fixes from the Risicare API.
+ *
+ * Handles:
+ * - Initial loading of fixes on startup
+ * - Periodic background refresh via setInterval (unref'd)
+ * - Exponential backoff on failure
+ * - Circuit breaker: after 3 consecutive failures, stop trying for 30s
+ *
+ * Uses native fetch (Node.js 18+) with AbortController for timeouts.
+ *
+ * Port of Python SDK's runtime/loader.py adapted for Node.js.
+ */
+
+declare class FixLoader {
+    private readonly _config;
+    private readonly _cache;
+    private _refreshTimer;
+    private _lastLoadTime;
+    private _consecutiveFailures;
+    private _circuitOpenUntil;
+    private _onLoadCallbacks;
+    private static readonly CIRCUIT_BREAKER_THRESHOLD;
+    private static readonly CIRCUIT_BREAKER_COOLDOWN_MS;
+    constructor(config: FixRuntimeConfig, cache: FixCache);
+    /** Timestamp of last successful load. */
+    get lastLoadTime(): number | null;
+    /**
+     * Start the loader: perform initial load and start background refresh.
+     *
+     * Never throws — failures are logged and the runtime degrades gracefully.
+     */
+    start(): void;
+    /** Stop the loader: clear the refresh interval. */
+    stop(): void;
+    /**
+     * Register a callback invoked after each successful load.
+     */
+    onLoad(callback: (fixes: ActiveFix[]) => void): void;
+    /**
+     * Load fixes from the API.
+     *
+     * Name kept as "loadSync" for parity with the Python SDK, but this
+     * returns a Promise in JS (there's no synchronous fetch in Node.js).
+     */
+    loadSync(): Promise<ActiveFix[]>;
+    /** Get currently cached fixes without hitting the API. */
+    getCached(): ActiveFix[];
+    private _parseResponse;
+    private _onLoadSuccess;
+    private _onLoadFailure;
+    private _startRefreshInterval;
+}
+
+/**
+ * Fix Interceptors — Hook into LLM/tool calls to apply fixes.
+ *
+ * Interceptors are registered with the runtime and called during agent
+ * execution to apply relevant fixes at three interception points:
+ * - preCall:  Before the LLM/tool call (prompt/parameter/fallback fixes)
+ * - postCall: After the call (output guard validation)
+ * - onError:  When an error occurs (retry/fallback decisions)
+ *
+ * Port of Python SDK's runtime/interceptors.py adapted for Node.js.
+ */
+
+interface InterceptContext {
+    /** Type of operation: "llm_call", "tool_call", "agent_delegate" */
+    operationType: string;
+    /** Name of the operation: model name, tool name, agent name */
+    operationName: string;
+    /** Session ID for A/B testing bucketing */
+    sessionId?: string;
+    /** Trace ID for correlation */
+    traceId?: string;
+    /** Error code (set when retrying after error) */
+    errorCode?: string;
+    /** Error message (set when retrying after error) */
+    errorMessage?: string;
+    /** Current attempt number (1-based) */
+    attempt: number;
+    /** Fixes applied during this intercept lifecycle */
+    appliedFixes: ApplyResult[];
+}
+interface FixInterceptor {
+    /**
+     * Called before an LLM/tool call.
+     * Returns modified messages and params.
+     */
+    preCall(ctx: InterceptContext, messages: unknown[] | null, params: Record<string, unknown>): {
+        messages: unknown[] | null;
+        params: Record<string, unknown>;
+    };
+    /**
+     * Called after an LLM/tool call.
+     * Returns modified response and whether to continue.
+     */
+    postCall(ctx: InterceptContext, response: unknown): {
+        response: unknown;
+        shouldContinue: boolean;
+    };
+    /**
+     * Called when an error occurs.
+     * Returns whether to retry and optional modified params.
+     */
+    onError(ctx: InterceptContext, error: Error): {
+        shouldRetry: boolean;
+        modifiedParams: Record<string, unknown> | null;
+    };
+}
+
+/**
+ * Fix Runtime — Main orchestrator for the fix application system.
+ *
+ * Manages:
+ * - Loading active fixes from the API (via FixLoader)
+ * - Caching fixes locally (via FixCache)
+ * - Applying fixes via interceptors (via DefaultFixInterceptor)
+ * - Tracking fix effectiveness
+ *
+ * Singleton management via globalThis (same pattern as the tracer).
+ *
+ * Port of Python SDK's runtime/runtime.py adapted for Node.js.
+ */
+
+declare class FixRuntime {
+    private readonly _config;
+    private readonly _cache;
+    private readonly _loader;
+    private readonly _applier;
+    private readonly _interceptor;
+    private _started;
+    private _fixApplications;
+    private _fixSuccesses;
+    constructor(config: FixRuntimeConfig);
+    /** Runtime configuration (with defaults resolved). */
+    get config(): Required<FixRuntimeConfig>;
+    /** Whether the runtime is enabled and started. */
+    get isEnabled(): boolean;
+    /** The fix cache. */
+    get cache(): FixCache;
+    /** The fix loader. */
+    get loader(): FixLoader;
+    /** The fix applier. */
+    get applier(): FixApplier;
+    /** The interceptor. */
+    get interceptor(): FixInterceptor;
+    /**
+     * Start the runtime.
+     *
+     * Triggers initial fix load and starts background refresh.
+     * Never throws — failures degrade gracefully.
+     */
+    start(): void;
+    /**
+     * Stop the runtime.
+     *
+     * Stops background refresh and clears the cache.
+     * Never throws.
+     */
+    stop(): void;
+    /**
+     * Intercept a call: create context and run preCall fixes.
+     *
+     * Returns modified messages/params and the InterceptContext for
+     * use in subsequent interceptResponse / interceptError calls.
+     */
+    interceptCall(operationType: string, operationName: string, messages: unknown[] | null, params: Record<string, unknown>, options?: {
+        sessionId?: string;
+        traceId?: string;
+        errorCode?: string;
+    }): {
+        messages: unknown[] | null;
+        params: Record<string, unknown>;
+        ctx: InterceptContext;
+    };
+    /**
+     * Intercept a response: run postCall fixes (output validation).
+     */
+    interceptResponse(ctx: InterceptContext, response: unknown): {
+        response: unknown;
+        shouldContinue: boolean;
+    };
+    /**
+     * Intercept an error: decide on retry/fallback.
+     */
+    interceptError(ctx: InterceptContext, error: Error): {
+        shouldRetry: boolean;
+        modifiedParams: Record<string, unknown> | null;
+    };
+    /**
+     * Get applicable fix for an error code.
+     */
+    getFix(errorCode: string, sessionId?: string): ActiveFix | null;
+    /**
+     * Manually refresh fixes from the API.
+     */
+    refreshFixes(): Promise<ActiveFix[]>;
+    /** Get effectiveness statistics for all fixes. */
+    getEffectivenessStats(): Record<string, {
+        applications: number;
+        successes: number;
+        successRate: number;
+    }>;
+    private _trackSuccess;
+    private _trackFailure;
+}
+/** Get the global FixRuntime instance, if initialized. */
+declare function getFixRuntime(): FixRuntime | undefined;
+/**
+ * Initialize and start the global FixRuntime.
+ *
+ * If already initialized, returns the existing instance.
+ * Never throws — initialization failures degrade gracefully.
+ */
+declare function initFixRuntime(config: FixRuntimeConfig): FixRuntime;
+/**
+ * Shutdown and remove the global FixRuntime.
+ *
+ * Never throws.
+ */
+declare function shutdownFixRuntime(): void;
+
+export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, type FixRuntimeConfig, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, Tracer, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getFixRuntime, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, initFixRuntime, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, shutdown, shutdownFixRuntime, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, withAgent, withPhase, withSession };