risicare 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,564 @@
+/**
+ * SDK configuration with environment variable loading.
+ *
+ * Environment variables match the Python SDK exactly:
+ *   RISICARE_API_KEY, RISICARE_ENDPOINT, RISICARE_PROJECT_ID, etc.
+ */
+interface RisicareConfig {
+    /** API key for authentication (format: "rsk-{random}") */
+    apiKey?: string;
+    /** Gateway endpoint URL */
+    endpoint?: string;
+    /** Project ID */
+    projectId?: string;
+    /** Environment name (production, staging, development) */
+    environment?: string;
+    /** Service name for identification */
+    serviceName?: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** Whether tracing is enabled (default: true if apiKey provided) */
+    enabled?: boolean;
+    /** Whether to capture prompt/completion content (default: true) */
+    traceContent?: boolean;
+    /** Sample rate 0.0–1.0 (default: 1.0 = trace all) */
+    sampleRate?: number;
+    /** Batch size threshold before flush (default: 100) */
+    batchSize?: number;
+    /** Batch timeout in ms before flush (default: 1000) */
+    batchTimeoutMs?: number;
+    /** Maximum queue size (default: 10000) */
+    maxQueueSize?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Custom metadata attached to all spans */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Core type definitions for the Risicare SDK.
+ *
+ * These enums and types mirror the Python SDK's risicare-core types
+ * and align with the Rust gateway's SpanData struct.
+ */
+declare enum SpanKind {
+    INTERNAL = "internal",
+    CLIENT = "client",
+    SERVER = "server",
+    PRODUCER = "producer",
+    CONSUMER = "consumer",
+    AGENT = "agent",
+    LLM_CALL = "llm_call",
+    TOOL_CALL = "tool_call",
+    RETRIEVAL = "retrieval",
+    DECISION = "decision",
+    MESSAGE = "message",
+    DELEGATION = "delegation",
+    COORDINATION = "coordination",
+    THINK = "think",
+    DECIDE = "decide",
+    OBSERVE = "observe",
+    REFLECT = "reflect"
+}
+declare enum SpanStatus {
+    UNSET = "unset",
+    OK = "ok",
+    ERROR = "error"
+}
+declare enum SemanticPhase {
+    THINK = "think",
+    DECIDE = "decide",
+    ACT = "act",
+    OBSERVE = "observe"
+}
+declare enum AgentRole {
+    ORCHESTRATOR = "orchestrator",
+    WORKER = "worker",
+    REVIEWER = "reviewer",
+    PLANNER = "planner",
+    EXECUTOR = "executor",
+    CRITIC = "critic",
+    CUSTOM = "custom"
+}
+declare enum MessageType {
+    REQUEST = "request",
+    RESPONSE = "response",
+    DELEGATE = "delegate",
+    COORDINATE = "coordinate",
+    BROADCAST = "broadcast"
+}
+interface SpanEvent {
+    name: string;
+    timestamp: string;
+    attributes?: Record<string, unknown>;
+}
+interface SpanLink {
+    traceId: string;
+    spanId: string;
+    attributes?: Record<string, unknown>;
+}
+interface SpanPayload {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: string;
+    startTime: string;
+    endTime?: string;
+    durationMs?: number;
+    status: string;
+    statusMessage?: string;
+    attributes: Record<string, unknown>;
+    events: SpanEvent[];
+    links: SpanLink[];
+    sessionId?: string;
+    agentId?: string;
+    agentName?: string;
+    agentType?: string;
+    semanticPhase?: string;
+    llmProvider?: string;
+    llmModel?: string;
+    llmPromptTokens?: number;
+    llmCompletionTokens?: number;
+    llmTotalTokens?: number;
+    llmCostUsd?: number;
+    toolName?: string;
+    toolSuccess?: boolean;
+}
+
+/**
+ * Span class — the core unit of tracing.
+ *
+ * A span represents a single operation (LLM call, tool use, agent step).
+ * Spans are mutable: attributes, events, and status can be set after creation.
+ * Call end() to finalize the span and trigger export.
+ */
+
+interface SpanOptions {
+    name: string;
+    kind?: SpanKind;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    attributes?: Record<string, unknown>;
+    links?: SpanLink[];
+    sessionId?: string;
+    agentId?: string;
+    agentName?: string;
+    agentType?: string;
+    semanticPhase?: string;
+}
+type SpanEndCallback = (span: Span) => void;
+declare class Span {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId: string | undefined;
+    readonly name: string;
+    readonly kind: SpanKind;
+    readonly startTime: string;
+    readonly startHrtime: number;
+    endTime: string | undefined;
+    status: SpanStatus;
+    statusMessage: string | undefined;
+    attributes: Record<string, unknown>;
+    events: SpanEvent[];
+    links: SpanLink[];
+    sessionId: string | undefined;
+    agentId: string | undefined;
+    agentName: string | undefined;
+    agentType: string | undefined;
+    semanticPhase: string | undefined;
+    llmProvider: string | undefined;
+    llmModel: string | undefined;
+    llmPromptTokens: number | undefined;
+    llmCompletionTokens: number | undefined;
+    llmTotalTokens: number | undefined;
+    llmCostUsd: number | undefined;
+    toolName: string | undefined;
+    toolSuccess: boolean | undefined;
+    private _ended;
+    private _endHrtime;
+    private _onEnd;
+    constructor(options: SpanOptions, onEnd?: SpanEndCallback);
+    get isEnded(): boolean;
+    get durationMs(): number;
+    setAttribute(key: string, value: unknown): this;
+    setAttributes(attrs: Record<string, unknown>): this;
+    setStatus(status: SpanStatus, message?: string): this;
+    addEvent(name: string, attributes?: Record<string, unknown>): this;
+    addLink(traceId: string, spanId: string, attributes?: Record<string, unknown>): this;
+    recordException(error: Error | string): this;
+    setLlmFields(fields: {
+        provider?: string;
+        model?: string;
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+        costUsd?: number;
+    }): this;
+    setToolFields(fields: {
+        name?: string;
+        success?: boolean;
+    }): this;
+    end(): void;
+    /**
+     * Serialize to the wire format expected by the Rust gateway.
+     */
+    toPayload(): SpanPayload;
+}
+
+/**
+ * Tracer — creates spans with automatic context nesting.
+ *
+ * The Tracer is the primary API for creating spans. It automatically:
+ * - Links child spans to parent spans via parentSpanId
+ * - Propagates the trace ID from the active context
+ * - Injects session/agent/phase context into new spans
+ * - Runs the callback within the span's context scope
+ *
+ * Usage:
+ *   const tracer = new Tracer(processor);
+ *   await tracer.startSpan('my-operation', async (span) => {
+ *     span.setAttribute('key', 'value');
+ *     // Nested spans automatically become children
+ *     await tracer.startSpan('sub-op', async (child) => { ... });
+ *   });
+ */
+
+interface StartSpanOptions {
+    name: string;
+    kind?: SpanKind;
+    attributes?: Record<string, unknown>;
+    /** Override trace ID (default: inherit from parent or generate new) */
+    traceId?: string;
+    /** Override parent span ID (default: current span in context) */
+    parentSpanId?: string;
+}
+interface TracerConfig {
+    /** Called when a span ends (typically feeds into batch processor) */
+    onSpanEnd: SpanEndCallback;
+    /** Sample rate 0.0–1.0 (default: 1.0) */
+    sampleRate?: number;
+    /** Whether tracing is enabled */
+    enabled?: boolean;
+}
+declare class Tracer {
+    private _onSpanEnd;
+    private _sampleRate;
+    private _enabled;
+    constructor(config: TracerConfig);
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    /**
+     * Start a span, run the callback within its context, and auto-end on completion.
+     *
+     * The span is automatically:
+     * - Linked to the current parent span (if any)
+     * - Given the current trace ID (or a new one for root spans)
+     * - Enriched with session/agent/phase context
+     * - Ended when the callback returns (or throws)
+     * - Marked as ERROR if the callback throws
+     *
+     * @returns The callback's return value
+     */
+    startSpan<T>(options: StartSpanOptions | string, fn: (span: Span) => T): T;
+    /**
+     * Create a span without auto-ending. Caller is responsible for calling span.end().
+     *
+     * Useful for long-running operations where you need manual control.
+     * The span is still linked to context and enriched with session/agent/phase.
+     */
+    createSpan(options: StartSpanOptions | string): Span;
+}
+
+/**
+ * RisicareClient — singleton client managing SDK lifecycle.
+ *
+ * Handles initialization, shutdown, and the connection between
+ * the Tracer and the export pipeline (batch processor + HTTP exporter).
+ *
+ * Usage:
+ *   import { init, shutdown } from 'risicare';
+ *   init({ apiKey: 'rsk-...', projectId: 'my-project' });
+ *   // ... instrument code ...
+ *   await shutdown(); // flush remaining spans
+ */
+
+/**
+ * Initialize the Risicare SDK. Call once at application startup.
+ *
+ * @example
+ * import { init } from 'risicare';
+ * init({ apiKey: 'rsk-...', projectId: 'my-project' });
+ */
+declare function init(config?: Partial<RisicareConfig>): void;
+/**
+ * Gracefully shut down the SDK. Flushes pending spans before resolving.
+ */
+declare function shutdown(): Promise<void>;
+/**
+ * Flush all pending spans without shutting down.
+ */
+declare function flush(): Promise<void>;
+/**
+ * Enable tracing at runtime.
+ */
+declare function enable(): void;
+/**
+ * Disable tracing at runtime. Spans will not be created or exported.
+ */
+declare function disable(): void;
+/**
+ * Check whether tracing is currently enabled.
+ */
+declare function isEnabled(): boolean;
+/**
+ * Get the global tracer instance. Returns undefined if not initialized.
+ */
+declare function getTracer(): Tracer | undefined;
+
+/**
+ * Agent context — identifies which agent is executing.
+ * Supports nesting: inner agents automatically track parent.
+ */
+interface AgentOptions {
+    agentId?: string;
+    name?: string;
+    role?: string;
+    agentType?: string;
+    version?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Run a callback within an agent context.
+ * If nested inside another agent, parentAgentId is set automatically.
+ *
+ * @example
+ * await withAgent({ name: 'researcher', role: 'worker' }, async () => {
+ *   const result = await llm.invoke(query);
+ *   return result;
+ * });
+ */
+declare function withAgent<T>(options: AgentOptions, fn: () => T): T;
+
+/**
+ * agent() — Higher-order function wrapper for agent identity (Tier 2).
+ *
+ * Wraps a function to execute within an agent context. All spans created
+ * inside will be tagged with the agent's identity.
+ *
+ * @example
+ * const research = agent({ name: 'researcher', role: 'worker' }, async (query: string) => {
+ *   const result = await openai.chat.completions.create({ ... });
+ *   return result.choices[0].message.content;
+ * });
+ *
+ * const answer = await research('What is quantum computing?');
+ */
+
+/**
+ * Wrap a function with agent context and an automatic span.
+ */
+declare function agent<TArgs extends unknown[], TReturn>(options: AgentOptions, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+
+/**
+ * Session context — groups multiple traces from the same user interaction.
+ */
+interface SessionOptions {
+    sessionId: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    parentSessionId?: string;
+    turnNumber?: number;
+}
+/**
+ * Run a callback within a session context.
+ *
+ * @example
+ * await withSession({ sessionId: 'sess-123', userId: 'user-1' }, async () => {
+ *   const result = await agent.run(query);
+ *   return result;
+ * });
+ */
+declare function withSession<T>(options: SessionOptions, fn: () => T): T;
+
+/**
+ * session() — Higher-order function wrapper for session context (Tier 3).
+ *
+ * Wraps a function to execute within a session context. All spans created
+ * inside will be tagged with the session identity.
+ *
+ * @example
+ * const handleRequest = session(
+ *   (req) => ({ sessionId: req.sessionId, userId: req.userId }),
+ *   async (req: Request) => {
+ *     return await agent.run(req.query);
+ *   },
+ * );
+ */
+
+/**
+ * Wrap a function with session context.
+ *
+ * @param optionsOrResolver - Static session options, or a function that derives them from args
+ * @param fn - The function to wrap
+ */
+declare function session<TArgs extends unknown[], TReturn>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions), fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+
+/**
+ * Phase decorators — decision phase tracking (Tier 4).
+ *
+ * Wraps functions to execute within a semantic phase context (THINK/DECIDE/ACT/OBSERVE).
+ * Each creates a span named after the phase.
+ *
+ * @example
+ * const analyze = traceThink(async (data: string) => {
+ *   return await llm.invoke(`Analyze: ${data}`);
+ * });
+ *
+ * const decide = traceDecide(async (analysis: string) => {
+ *   return await llm.invoke(`Decide action: ${analysis}`);
+ * });
+ */
+/** Wrap a function in a THINK phase context with auto-span. */
+declare function traceThink<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/** Wrap a function in a DECIDE phase context with auto-span. */
+declare function traceDecide<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/** Wrap a function in an ACT phase context with auto-span. */
+declare function traceAct<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/** Wrap a function in an OBSERVE phase context with auto-span. */
+declare function traceObserve<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+
+/**
+ * Phase context — cognitive phase tracking (THINK/DECIDE/ACT/OBSERVE).
+ */
+
+/**
+ * Run a callback within a semantic phase context.
+ */
+declare function withPhase<T>(phase: SemanticPhase, fn: () => T): T;
+
+/**
+ * Multi-agent communication decorators (Tier 5).
+ *
+ * Track inter-agent messages, delegations, and coordination.
+ *
+ * @example
+ * const sendToWorker = traceMessage({ to: 'worker-1', type: MessageType.DELEGATE },
+ *   async (task: string) => { ... }
+ * );
+ */
+
+interface MessageOptions {
+    to: string;
+    type?: MessageType;
+    metadata?: Record<string, unknown>;
+}
+interface DelegateOptions {
+    to: string;
+    metadata?: Record<string, unknown>;
+}
+interface CoordinateOptions {
+    participants: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Wrap a function that sends a message to another agent.
+ */
+declare function traceMessage<TArgs extends unknown[], TReturn>(options: MessageOptions, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/**
+ * Wrap a function that delegates work to a sub-agent.
+ */
+declare function traceDelegate<TArgs extends unknown[], TReturn>(options: DelegateOptions, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+/**
+ * Wrap a function that coordinates multiple agents.
+ */
+declare function traceCoordinate<TArgs extends unknown[], TReturn>(options: CoordinateOptions, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+
+/**
+ * AsyncLocalStorage-based context propagation.
+ *
+ * Uses a single AsyncLocalStorage instance with a composite state object.
+ * This is simpler and more performant than multiple separate stores.
+ *
+ * Node.js AsyncLocalStorage automatically propagates through:
+ * - Promise / async-await
+ * - setTimeout / setImmediate
+ * - EventEmitter callbacks
+ * - process.nextTick
+ * - async generators (unlike Python's contextvars!)
+ */
+
+interface SessionContext {
+    sessionId: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    parentSessionId?: string;
+    turnNumber?: number;
+}
+interface AgentContext {
+    agentId: string;
+    agentName?: string;
+    agentRole?: string;
+    agentType?: string;
+    parentAgentId?: string;
+    version?: number;
+    metadata?: Record<string, unknown>;
+}
+declare function getCurrentSession(): SessionContext | undefined;
+declare function getCurrentAgent(): AgentContext | undefined;
+declare function getCurrentSpan(): Span | undefined;
+declare function getCurrentPhase(): SemanticPhase | undefined;
+declare function getCurrentSessionId(): string | undefined;
+declare function getCurrentAgentId(): string | undefined;
+declare function getCurrentTraceId(): string | undefined;
+declare function getCurrentSpanId(): string | undefined;
+/**
+ * Get all current context as a plain object (for debugging/serialization).
+ */
+declare function getCurrentContext(): Record<string, unknown>;
+
+/**
+ * Serializable trace context + W3C Trace Context headers.
+ *
+ * TraceContext is a plain object that can be passed across process
+ * boundaries (JSON serialization, HTTP headers, message queues).
+ *
+ * W3C Trace Context:
+ *   traceparent: {version}-{trace_id}-{span_id}-{flags}
+ *   tracestate: risicare=session_id={...};agent_id={...}
+ */
+interface TraceContext {
+    traceId: string;
+    spanId: string;
+    sessionId?: string;
+    agentId?: string;
+}
+/**
+ * Get the current trace context as a serializable object.
+ */
+declare function getTraceContext(): TraceContext;
+/**
+ * Inject trace context into HTTP headers (W3C format).
+ */
+declare function injectTraceContext(headers: Record<string, string>): Record<string, string>;
+/**
+ * Extract trace context from HTTP headers (W3C format).
+ */
+declare function extractTraceContext(headers: Record<string, string>): Record<string, string | undefined>;
+
+/**
+ * Span registry — TTL-based span store for edge cases.
+ *
+ * While AsyncLocalStorage handles most context propagation in Node.js,
+ * the registry is useful for:
+ * - Cross-process span tracking
+ * - Explicit span passing via ID
+ * - Long-running operations that outlive their original context
+ */
+
+declare function registerSpan(span: Span, ttlMs?: number): void;
+declare function getSpanById(spanId: string): Span | undefined;
+declare function unregisterSpan(spanId: string): void;
+
+export { type AgentContext, type AgentOptions, AgentRole, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, Tracer, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getSpanById, getTraceContext, getTracer, init, injectTraceContext, isEnabled, registerSpan, session, shutdown, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, unregisterSpan, withAgent, withPhase, withSession };