risicare 0.1.4 → 0.2.0

package/dist/frameworks/langgraph.js

@@ -0,0 +1,269 @@
+// src/ids.ts
+import { randomBytes } from "crypto";
+
+// src/noop.ts
+var NOOP_SPAN = Object.freeze({
+  traceId: "00000000000000000000000000000000",
+  spanId: "0000000000000000",
+  parentSpanId: void 0,
+  name: "noop",
+  kind: "internal" /* INTERNAL */,
+  startTime: "",
+  startHrtime: 0,
+  endTime: void 0,
+  status: "unset" /* UNSET */,
+  statusMessage: void 0,
+  attributes: Object.freeze({}),
+  events: Object.freeze([]),
+  links: Object.freeze([]),
+  sessionId: void 0,
+  agentId: void 0,
+  agentName: void 0,
+  semanticPhase: void 0,
+  llmProvider: void 0,
+  llmModel: void 0,
+  llmPromptTokens: void 0,
+  llmCompletionTokens: void 0,
+  llmTotalTokens: void 0,
+  llmCostUsd: void 0,
+  toolName: void 0,
+  toolSuccess: void 0,
+  isEnded: true,
+  durationMs: 0,
+  setAttribute() {
+    return this;
+  },
+  setAttributes() {
+    return this;
+  },
+  setStatus() {
+    return this;
+  },
+  addEvent() {
+    return this;
+  },
+  addLink() {
+    return this;
+  },
+  recordException() {
+    return this;
+  },
+  setLlmFields() {
+    return this;
+  },
+  setToolFields() {
+    return this;
+  },
+  end() {
+  },
+  toPayload() {
+    return {
+      traceId: this.traceId,
+      spanId: this.spanId,
+      name: this.name,
+      kind: this.kind,
+      startTime: this.startTime,
+      status: this.status,
+      attributes: {},
+      events: [],
+      links: []
+    };
+  }
+});
+
+// src/globals.ts
+import { AsyncLocalStorage } from "async_hooks";
+var G = globalThis;
+var PREFIX = "__risicare_";
+function getTracer() {
+  return G[PREFIX + "tracer"];
+}
+
+// src/client.ts
+function getTracer2() {
+  return getTracer();
+}
+
+// src/frameworks/langchain.ts
+var RisicareCallbackHandler = class {
+  name = "RisicareCallbackHandler";
+  _spans = /* @__PURE__ */ new Map();
+  // ── Chain lifecycle ────────────────────────────────────────────────────────
+  handleChainStart(chain, _inputs, runId, parentRunId) {
+    const tracer = getTracer2();
+    if (!tracer?.enabled) return;
+    const parentEntry = parentRunId ? this._spans.get(parentRunId) : void 0;
+    const span = tracer.createSpan({
+      name: chain.name || chain._type || "chain",
+      kind: "internal" /* INTERNAL */,
+      parentSpanId: parentEntry?.span.spanId,
+      traceId: parentEntry?.span.traceId,
+      attributes: {
+        "framework": "langchain",
+        "langchain.run_id": runId,
+        ...parentRunId ? { "langchain.parent_run_id": parentRunId } : {},
+        ...chain._type ? { "langchain.chain_type": chain._type } : {}
+      }
+    });
+    this._spans.set(runId, { span, startTime: Date.now() });
+  }
+  handleChainEnd(_outputs, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    entry.span.setAttribute("gen_ai.latency_ms", Date.now() - entry.startTime);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+  handleChainError(error, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    entry.span.recordException(error);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+  // ── LLM lifecycle ─────────────────────────────────────────────────────────
+  handleLLMStart(llm, _prompts, runId, parentRunId) {
+    const tracer = getTracer2();
+    if (!tracer?.enabled) return;
+    const parentEntry = parentRunId ? this._spans.get(parentRunId) : void 0;
+    const span = tracer.createSpan({
+      name: llm.name || llm._type || "llm",
+      kind: "llm_call" /* LLM_CALL */,
+      parentSpanId: parentEntry?.span.spanId,
+      traceId: parentEntry?.span.traceId,
+      attributes: {
+        "framework": "langchain",
+        "langchain.run_id": runId,
+        "gen_ai.system": "langchain",
+        "gen_ai.prompt.count": _prompts.length
+      }
+    });
+    this._spans.set(runId, { span, startTime: Date.now() });
+  }
+  handleLLMEnd(output, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    const usage = output.llmOutput?.tokenUsage;
+    if (usage) {
+      entry.span.setLlmFields({
+        promptTokens: usage.promptTokens ?? usage.prompt_tokens,
+        completionTokens: usage.completionTokens ?? usage.completion_tokens,
+        totalTokens: usage.totalTokens ?? usage.total_tokens
+      });
+    }
+    const model = output.llmOutput?.model ?? output.llmOutput?.modelName;
+    if (model) {
+      entry.span.setLlmFields({ model });
+    }
+    entry.span.setAttribute("gen_ai.latency_ms", Date.now() - entry.startTime);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+  handleLLMError(error, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    entry.span.recordException(error);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+  // ── Tool lifecycle ────────────────────────────────────────────────────────
+  handleToolStart(tool, input, runId, parentRunId) {
+    const tracer = getTracer2();
+    if (!tracer?.enabled) return;
+    const parentEntry = parentRunId ? this._spans.get(parentRunId) : void 0;
+    const span = tracer.createSpan({
+      name: tool.name || "tool",
+      kind: "tool_call" /* TOOL_CALL */,
+      parentSpanId: parentEntry?.span.spanId,
+      traceId: parentEntry?.span.traceId,
+      attributes: {
+        "framework": "langchain",
+        "langchain.run_id": runId,
+        "tool.name": tool.name || "unknown",
+        "tool.input_length": input?.length ?? 0
+      }
+    });
+    this._spans.set(runId, { span, startTime: Date.now() });
+  }
+  handleToolEnd(output, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    entry.span.setAttribute("tool.output_length", output?.length ?? 0);
+    entry.span.setAttribute("gen_ai.latency_ms", Date.now() - entry.startTime);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+  handleToolError(error, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    entry.span.recordException(error);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+  // ── Retriever lifecycle ───────────────────────────────────────────────────
+  handleRetrieverStart(retriever, _query, runId, parentRunId) {
+    const tracer = getTracer2();
+    if (!tracer?.enabled) return;
+    const parentEntry = parentRunId ? this._spans.get(parentRunId) : void 0;
+    const span = tracer.createSpan({
+      name: retriever.name || "retriever",
+      kind: "retrieval" /* RETRIEVAL */,
+      parentSpanId: parentEntry?.span.spanId,
+      traceId: parentEntry?.span.traceId,
+      attributes: {
+        "framework": "langchain",
+        "langchain.run_id": runId
+      }
+    });
+    this._spans.set(runId, { span, startTime: Date.now() });
+  }
+  handleRetrieverEnd(documents, runId) {
+    const entry = this._spans.get(runId);
+    if (!entry) return;
+    entry.span.setAttribute(
+      "retriever.document_count",
+      documents?.length ?? 0
+    );
+    entry.span.setAttribute("gen_ai.latency_ms", Date.now() - entry.startTime);
+    entry.span.end();
+    this._spans.delete(runId);
+  }
+};
+
+// src/frameworks/langgraph.ts
+function instrumentLangGraph(graph) {
+  return new Proxy(graph, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if ((prop === "invoke" || prop === "stream") && typeof value === "function") {
+        return function patchedMethod(...args) {
+          const tracer = getTracer2();
+          if (!tracer?.enabled) return value.apply(this, args);
+          return tracer.startSpan(
+            {
+              name: `langgraph.${String(prop)}`,
+              kind: "agent" /* AGENT */,
+              attributes: { framework: "langgraph" }
+            },
+            (_span) => {
+              const config = args[1] ?? {};
+              const callbacks = config.callbacks ?? [];
+              callbacks.push(new RisicareCallbackHandler());
+              args[1] = { ...config, callbacks };
+              const result = value.apply(this, args);
+              if (result && typeof result.then === "function") {
+                return result.then((r) => r);
+              }
+              return result;
+            }
+          );
+        };
+      }
+      return value;
+    }
+  });
+}
+export {
+  instrumentLangGraph
+};
+//# sourceMappingURL=langgraph.js.map

package/dist/frameworks/langgraph.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ids.ts","../../src/noop.ts","../../src/globals.ts","../../src/client.ts","../../src/frameworks/langchain.ts","../../src/frameworks/langgraph.ts"],"sourcesContent":["/**\n * ID generation for traces and spans.\n *\n * Trace IDs: 32 lowercase hex characters (16 random bytes)\n * Span IDs:  16 lowercase hex characters (8 random bytes)\n *\n * Uses crypto.randomBytes for cryptographically secure randomness.\n */\n\nimport { randomBytes } from 'node:crypto';\n\nconst HEX_REGEX_32 = /^[0-9a-f]{32}$/;\nconst HEX_REGEX_16 = /^[0-9a-f]{16}$/;\n\nexport function generateTraceId(): string {\n  return randomBytes(16).toString('hex');\n}\n\nexport function generateSpanId(): string {\n  return randomBytes(8).toString('hex');\n}\n\nexport function generateAgentId(prefix?: string): string {\n  const suffix = randomBytes(8).toString('hex');\n  return prefix ? `${prefix}-${suffix}` : suffix;\n}\n\nexport function validateTraceId(id: string): boolean {\n  return HEX_REGEX_32.test(id);\n}\n\nexport function validateSpanId(id: string): boolean {\n  return HEX_REGEX_16.test(id);\n}\n","/**\n * No-op implementations for the disabled path.\n *\n * When tracing is disabled, all operations return these no-op objects\n * to maintain zero overhead. No allocations, no side effects.\n */\n\nimport { SpanKind, SpanStatus, type SpanPayload } from './types.js';\n\n/**\n * A frozen no-op span that silently ignores all operations.\n * Used when SDK is disabled to avoid overhead.\n */\nexport const NOOP_SPAN = Object.freeze({\n  traceId: '00000000000000000000000000000000',\n  spanId: '0000000000000000',\n  parentSpanId: undefined,\n  name: 'noop',\n  kind: SpanKind.INTERNAL,\n  startTime: '',\n  startHrtime: 0,\n  endTime: undefined,\n  status: SpanStatus.UNSET,\n  statusMessage: undefined,\n  attributes: Object.freeze({}) as Record<string, unknown>,\n  events: Object.freeze([]) as readonly [],\n  links: Object.freeze([]) as readonly [],\n  sessionId: undefined,\n  agentId: undefined,\n  agentName: undefined,\n  semanticPhase: undefined,\n  llmProvider: undefined,\n  llmModel: undefined,\n  llmPromptTokens: undefined,\n  llmCompletionTokens: undefined,\n  llmTotalTokens: undefined,\n  llmCostUsd: undefined,\n  toolName: undefined,\n  toolSuccess: undefined,\n  isEnded: true,\n  durationMs: 0,\n\n  setAttribute() { return this; },\n  setAttributes() { return this; },\n  setStatus() { return this; },\n  addEvent() { return this; },\n  addLink() { return this; },\n  recordException() { return this; },\n  setLlmFields() { return this; },\n  setToolFields() { return this; },\n  end() {},\n  toPayload(): SpanPayload {\n    return {\n      traceId: this.traceId,\n      spanId: this.spanId,\n      name: this.name,\n      kind: this.kind,\n      startTime: this.startTime,\n      status: this.status,\n      attributes: {},\n      events: [],\n      links: [],\n    };\n  },\n});\n\nexport type NoopSpan = typeof NOOP_SPAN;\n","/**\n * Shared state via globalThis — ensures all entry point bundles share\n * the same singleton instances.\n *\n * Problem: tsup with `splitting: false` gives each entry point (index,\n * openai, anthropic, vercel-ai) its own copy of module-level variables.\n * This means `init()` from 'risicare' sets a tracer that 'risicare/openai'\n * can't see — breaking all provider instrumentation silently.\n *\n * Solution: Store all mutable singletons on globalThis with a namespaced\n * prefix. Every bundle reads/writes the same global slots.\n *\n * This pattern is used by React, OpenTelemetry, and other SDKs that must\n * share state across independently bundled entry points.\n *\n * @internal\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst G = globalThis as any;\nconst PREFIX = '__risicare_';\n\n// ─── Client & Tracer ────────────────────────────────────────────────────────\n\nexport function getClient(): unknown {\n  return G[PREFIX + 'client'];\n}\n\nexport function setClient(client: unknown): void {\n  G[PREFIX + 'client'] = client;\n}\n\nexport function getTracer(): unknown {\n  return G[PREFIX + 'tracer'];\n}\n\nexport function setTracer(tracer: unknown): void {\n  G[PREFIX + 'tracer'] = tracer;\n}\n\n// ─── Context Storage ────────────────────────────────────────────────────────\n\nexport function getContextStorage(): AsyncLocalStorage<unknown> {\n  if (!G[PREFIX + 'ctx']) {\n    G[PREFIX + 'ctx'] = new AsyncLocalStorage();\n  }\n  return G[PREFIX + 'ctx'];\n}\n\n// ─── Span Registry ──────────────────────────────────────────────────────────\n\nexport function getRegistry(): Map<string, unknown> {\n  if (!G[PREFIX + 'registry']) {\n    G[PREFIX + 'registry'] = new Map();\n  }\n  return G[PREFIX + 'registry'];\n}\n\nexport function getOpCount(): number {\n  return G[PREFIX + 'opcount'] ?? 0;\n}\n\nexport function setOpCount(n: number): void {\n  G[PREFIX + 'opcount'] = n;\n}\n\n// ─── Debug Flag ─────────────────────────────────────────────────────────────\n\nexport function getDebug(): boolean {\n  return G[PREFIX + 'debug'] ?? false;\n}\n\nexport function setDebugFlag(enabled: boolean): void {\n  G[PREFIX + 'debug'] = enabled;\n}\n","/**\n * RisicareClient — singleton client managing SDK lifecycle.\n *\n * Handles initialization, shutdown, and the connection between\n * the Tracer and the export pipeline (batch processor + HTTP exporter).\n *\n * Usage:\n *   import { init, shutdown } from 'risicare';\n *   init({ apiKey: 'rsk-...' }); // API key determines project\n *   // ... instrument code ...\n *   await shutdown(); // flush remaining spans\n */\n\nimport { type RisicareConfig, resolveConfig } from './config.js';\nimport { Tracer } from './tracer.js';\nimport { BatchSpanProcessor } from './exporters/batch.js';\nimport { HttpExporter } from './exporters/http.js';\nimport { ConsoleExporter } from './exporters/console.js';\nimport { SpanKind, SpanStatus } from './types.js';\nimport type { SpanExporter } from './exporters/base.js';\nimport { setDebug, debug } from './utils/log.js';\nimport {\n  getClient as getGlobalClient,\n  setClient as setGlobalClient,\n  getTracer as getGlobalTracer,\n  setTracer as setGlobalTracer,\n} from './globals.js';\n\n// ─── Client Class ───────────────────────────────────────────────────────────\n\nclass RisicareClient {\n  readonly config: ReturnType<typeof resolveConfig>;\n  readonly processor: BatchSpanProcessor;\n  readonly tracer: Tracer;\n  private _shutdownPromise: Promise<void> | undefined;\n  private _shutdownHandlers: { signal: string; handler: () => void }[] = [];\n\n  constructor(config?: Partial<RisicareConfig>) {\n    this.config = resolveConfig(config);\n\n    // API key format validation\n    if (this.config.apiKey && !this.config.apiKey.startsWith('rsk-')) {\n      debug('Warning: API key should start with \"rsk-\". Got: ' + this.config.apiKey.slice(0, 4) + '...');\n    }\n\n    // Build exporter chain\n    let exporter: SpanExporter;\n    if (this.config.debug && !this.config.apiKey) {\n      exporter = new ConsoleExporter();\n    } else if (this.config.apiKey) {\n      exporter = new HttpExporter({\n        endpoint: this.config.endpoint,\n        apiKey: this.config.apiKey,\n        projectId: this.config.projectId || undefined,\n        environment: this.config.environment || undefined,\n        compress: this.config.compress,\n      });\n    } else {\n      // No API key and not debug — use console as fallback\n      exporter = new ConsoleExporter();\n    }\n\n    this.processor = new BatchSpanProcessor({\n      exporters: [exporter],\n      batchSize: this.config.batchSize,\n      batchTimeoutMs: this.config.batchTimeoutMs,\n      maxQueueSize: this.config.maxQueueSize,\n      debug: this.config.debug,\n    });\n\n    this.tracer = new Tracer({\n      onSpanEnd: (span) => this.processor.onSpanEnd(span),\n      sampleRate: this.config.sampleRate,\n      enabled: this.config.enabled,\n      traceContent: this.config.traceContent,\n    });\n\n    // Start the batch processor (enables span queuing and periodic flushing)\n    this.processor.start();\n\n    // Register shutdown hooks\n    this._registerShutdownHooks();\n\n    // Enable internal debug logging if configured\n    setDebug(this.config.debug);\n    debug(`Initialized: enabled=${this.config.enabled}, endpoint=${this.config.endpoint}`);\n  }\n\n  get enabled(): boolean {\n    return this.tracer.enabled;\n  }\n\n  set enabled(value: boolean) {\n    this.tracer.enabled = value;\n  }\n\n  // Audit #6: Promise-based shutdown dedup (fixes TOCTOU race condition)\n  async shutdown(): Promise<void> {\n    if (this._shutdownPromise) return this._shutdownPromise;\n    this._shutdownPromise = this._doShutdown();\n    return this._shutdownPromise;\n  }\n\n  private async _doShutdown(): Promise<void> {\n    debug('Shutting down...');\n\n    // Audit #3: Remove process listeners to prevent leak\n    for (const { signal, handler } of this._shutdownHandlers) {\n      process.removeListener(signal, handler);\n    }\n    this._shutdownHandlers = [];\n\n    await this.processor.shutdown();\n  }\n\n  async flush(): Promise<void> {\n    await this.processor.flush();\n  }\n\n  private _registerShutdownHooks(): void {\n    const onShutdown = () => {\n      // Audit #3: Add 5s timeout to prevent hanging on signal\n      const timeout = setTimeout(() => process.exit(1), 5000);\n      timeout.unref();\n      this.shutdown().catch(() => {}).finally(() => clearTimeout(timeout));\n    };\n\n    const signals = ['beforeExit', 'SIGTERM', 'SIGINT'];\n    for (const signal of signals) {\n      process.once(signal, onShutdown);\n      this._shutdownHandlers.push({ signal, handler: onShutdown });\n    }\n  }\n}\n\n// ─── Public API ─────────────────────────────────────────────────────────────\n\n/**\n * Initialize the Risicare SDK. Call once at application startup.\n *\n * @example\n * import { init } from 'risicare';\n * init({ apiKey: 'rsk-...', serviceName: 'my-agent', environment: 'production' });\n */\nexport function init(config?: Partial<RisicareConfig>): void {\n  if (getGlobalClient()) {\n    debug('Already initialized. Call shutdown() first to re-initialize.');\n    return;\n  }\n\n  const client = new RisicareClient(config);\n  setGlobalClient(client);\n  setGlobalTracer(client.tracer);\n}\n\n/**\n * Gracefully shut down the SDK. Flushes pending spans before resolving.\n */\nexport async function shutdown(): Promise<void> {\n  const client = getGlobalClient() as RisicareClient | undefined;\n  if (!client) return;\n  await client.shutdown();\n  setGlobalClient(undefined);\n  setGlobalTracer(undefined);\n}\n\n/**\n * Flush all pending spans without shutting down.\n */\nexport async function flush(): Promise<void> {\n  const client = getGlobalClient() as RisicareClient | undefined;\n  if (!client) return;\n  await client.flush();\n}\n\n/**\n * Enable tracing at runtime.\n */\nexport function enable(): void {\n  const client = getGlobalClient() as RisicareClient | undefined;\n  if (client) client.enabled = true;\n}\n\n/**\n * Disable tracing at runtime. Spans will not be created or exported.\n */\nexport function disable(): void {\n  const client = getGlobalClient() as RisicareClient | undefined;\n  if (client) client.enabled = false;\n}\n\n/**\n * Check whether tracing is currently enabled.\n */\nexport function isEnabled(): boolean {\n  const client = getGlobalClient() as RisicareClient | undefined;\n  return client?.enabled ?? false;\n}\n\n/**\n * Get the global tracer instance. Returns undefined if not initialized.\n */\nexport function getTracer(): Tracer | undefined {\n  return getGlobalTracer() as Tracer | undefined;\n}\n\n/**\n * Get the global tracer, or throw if not initialized.\n * @internal Used by decorators and providers that require an active tracer.\n */\nexport function requireTracer(): Tracer {\n  const tracer = getGlobalTracer() as Tracer | undefined;\n  if (!tracer) {\n    throw new Error(\n      'Risicare SDK not initialized. Call init() before using tracing features.',\n    );\n  }\n  return tracer;\n}\n\n/**\n * Check whether content tracing (prompt/completion capture) is enabled.\n */\nexport function getTraceContent(): boolean {\n  const tracer = getGlobalTracer() as Tracer | undefined;\n  return tracer?.traceContent ?? true;\n}\n\n/**\n * Get SDK metrics: exported spans, dropped spans, failed exports, queue stats.\n * Returns zero-valued metrics if SDK is not initialized.\n */\nexport function getMetrics() {\n  const client = getGlobalClient() as RisicareClient | undefined;\n  return client?.processor.getMetrics() ?? {\n    exportedSpans: 0,\n    droppedSpans: 0,\n    failedExports: 0,\n    queueSize: 0,\n    queueCapacity: 0,\n    queueUtilization: 0,\n  };\n}\n\n// ─── reportError ──────────────────────────────────────────────────────────\n\n/**\n * Report a caught exception to the self-healing pipeline.\n *\n * Creates an error span that triggers diagnosis and fix generation.\n * This function never throws and is non-blocking.\n *\n * @param error - The caught exception (Error object or string)\n * @param options - Optional attributes and context overrides\n */\nexport function reportError(\n  error: unknown,\n  options?: { name?: string; attributes?: Record<string, unknown> },\n): void {\n  try {\n    const tracer = getTracer();\n    if (!tracer) return;\n\n    const err = error instanceof Error ? error : new Error(String(error));\n    const spanName = options?.name ?? `error:${err.constructor.name}`;\n\n    tracer.startSpan({ name: spanName, kind: SpanKind.INTERNAL }, (span) => {\n      span.setStatus(SpanStatus.ERROR, err.message);\n      span.setAttribute('error', true);\n      span.setAttribute('error.type', err.constructor.name);\n      span.setAttribute('error.message', err.message.slice(0, 2000));\n      if (err.stack) span.setAttribute('error.stack', err.stack.slice(0, 4000));\n      span.setAttribute('risicare.reported_error', true);\n      if (options?.attributes) {\n        for (const [k, v] of Object.entries(options.attributes)) {\n          span.setAttribute(k, v);\n        }\n      }\n    });\n  } catch {\n    // Never crash the host application\n    debug('reportError failed');\n  }\n}\n\n// ─── score ─────────────────────────────────────────────────────────────────\n\n/**\n * Record a custom evaluation score on a trace.\n *\n * Sends the score to the server in a fire-and-forget fashion.\n * This function never throws and is non-blocking.\n *\n * @param traceId - The trace to score\n * @param name - Score name (e.g., \"accuracy\", \"user_satisfaction\")\n * @param value - Score value between 0.0 and 1.0 inclusive\n * @param options - Optional span_id and comment\n */\nexport function score(\n  traceId: string,\n  name: string,\n  value: number,\n  options?: { spanId?: string; comment?: string },\n): void {\n  try {\n    if (typeof value !== 'number' || value < 0.0 || value > 1.0) {\n      debug(`score: value must be in [0.0, 1.0], got ${value}. Score not sent.`);\n      return;\n    }\n    if (!traceId || !name) {\n      debug('score: traceId and name are required');\n      return;\n    }\n\n    const client = getGlobalClient() as RisicareClient | undefined;\n    if (!client?.enabled || !client.config.apiKey) return;\n\n    const endpoint = client.config.endpoint.replace(/\\/$/, '');\n    const url = `${endpoint}/api/v1/scores`;\n    const body = JSON.stringify({\n      trace_id: traceId,\n      name,\n      score: value,\n      source: 'sdk',\n      ...(options?.spanId && { span_id: options.spanId }),\n      ...(options?.comment && { comment: options.comment }),\n    });\n\n    // Fire-and-forget — never blocks caller\n    fetch(url, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        'Authorization': `Bearer ${client.config.apiKey}`,\n      },\n      body,\n    }).catch((err) => debug(`score: send failed: ${err}`));\n  } catch {\n    // Never crash the host application\n    debug('score failed');\n  }\n}\n","/**\n * LangChain.js integration via callback handler.\n *\n * LangChain.js uses BaseCallbackHandler from @langchain/core/callbacks/base.\n * This handler receives lifecycle events (handleChainStart, handleLLMEnd, etc.)\n * with a runId (UUID string) for parent-child correlation.\n *\n * Usage:\n *   import { RisicareCallbackHandler } from 'risicare/frameworks/langchain';\n *   const handler = new RisicareCallbackHandler();\n *   const result = await chain.invoke(input, { callbacks: [handler] });\n *\n * Does NOT suppress provider instrumentation -- LangChain callbacks are\n * supplementary to the underlying LLM provider spans.\n */\n\nimport { getTracer } from '../client.js';\nimport { SpanKind } from '../types.js';\nimport type { Span } from '../span.js';\n\ninterface SpanEntry {\n  span: Span;\n  startTime: number;\n}\n\nexport class RisicareCallbackHandler {\n  name = 'RisicareCallbackHandler';\n\n  private _spans = new Map<string, SpanEntry>();\n\n  // ── Chain lifecycle ────────────────────────────────────────────────────────\n\n  handleChainStart(\n    chain: { name?: string; _type?: string },\n    _inputs: Record<string, unknown>,\n    runId: string,\n    parentRunId?: string,\n  ): void {\n    const tracer = getTracer();\n    if (!tracer?.enabled) return;\n\n    const parentEntry = parentRunId ? this._spans.get(parentRunId) : undefined;\n    const span = tracer.createSpan({\n      name: chain.name || chain._type || 'chain',\n      kind: SpanKind.INTERNAL,\n      parentSpanId: parentEntry?.span.spanId,\n      traceId: parentEntry?.span.traceId,\n      attributes: {\n        'framework': 'langchain',\n        'langchain.run_id': runId,\n        ...(parentRunId ? { 'langchain.parent_run_id': parentRunId } : {}),\n        ...(chain._type ? { 'langchain.chain_type': chain._type } : {}),\n      },\n    });\n\n    this._spans.set(runId, { span, startTime: Date.now() });\n  }\n\n  handleChainEnd(_outputs: Record<string, unknown>, runId: string): void {\n    const entry = this._spans.get(runId);\n    if (!entry) return;\n    entry.span.setAttribute('gen_ai.latency_ms', Date.now() - entry.startTime);\n    entry.span.end();\n    this._spans.delete(runId);\n  }\n\n  handleChainError(error: Error, runId: string): void {\n    const entry = this._spans.get(runId);\n    if (!entry) return;\n    entry.span.recordException(error);\n    entry.span.end();\n    this._spans.delete(runId);\n  }\n\n  // ── LLM lifecycle ─────────────────────────────────────────────────────────\n\n  handleLLMStart(\n    llm: { name?: string; _type?: string },\n    _prompts: string[],\n    runId: string,\n    parentRunId?: string,\n  ): void {\n    const tracer = getTracer();\n    if (!tracer?.enabled) return;\n\n    const parentEntry = parentRunId ? this._spans.get(parentRunId) : undefined;\n    const span = tracer.createSpan({\n      name: llm.name || llm._type || 'llm',\n      kind: SpanKind.LLM_CALL,\n      parentSpanId: parentEntry?.span.spanId,\n      traceId: parentEntry?.span.traceId,\n      attributes: {\n        'framework': 'langchain',\n        'langchain.run_id': runId,\n        'gen_ai.system': 'langchain',\n        'gen_ai.prompt.count': _prompts.length,\n      },\n    });\n\n    this._spans.set(runId, { span, startTime: Date.now() });\n  }\n\n  handleLLMEnd(\n    output: {\n      generations?: unknown[][];\n      llmOutput?: Record<string, unknown>;\n    },\n    runId: string,\n  ): void {\n    const entry = this._spans.get(runId);\n    if (!entry) return;\n\n    // Extract token usage from llmOutput\n    const usage = output.llmOutput?.tokenUsage as\n      | Record<string, number>\n      | undefined;\n    if (usage) {\n      entry.span.setLlmFields({\n        promptTokens: usage.promptTokens ?? usage.prompt_tokens,\n        completionTokens: usage.completionTokens ?? usage.completion_tokens,\n        totalTokens: usage.totalTokens ?? usage.total_tokens,\n      });\n    }\n\n    const model = (output.llmOutput?.model ??\n      output.llmOutput?.modelName) as string | undefined;\n    if (model) {\n      entry.span.setLlmFields({ model });\n    }\n\n    entry.span.setAttribute('gen_ai.latency_ms', Date.now() - entry.startTime);\n    entry.span.end();\n    this._spans.delete(runId);\n  }\n\n  handleLLMError(error: Error, runId: string): void {\n    const entry = this._spans.get(runId);\n    if (!entry) return;\n    entry.span.recordException(error);\n    entry.span.end();\n    this._spans.delete(runId);\n  }\n\n  // ── Tool lifecycle ────────────────────────────────────────────────────────\n\n  handleToolStart(\n    tool: { name?: string },\n    input: string,\n    runId: string,\n    parentRunId?: string,\n  ): void {\n    const tracer = getTracer();\n    if (!tracer?.enabled) return;\n\n    const parentEntry = parentRunId ? this._spans.get(parentRunId) : undefined;\n    const span = tracer.createSpan({\n      name: tool.name || 'tool',\n      kind: SpanKind.TOOL_CALL,\n      parentSpanId: parentEntry?.span.spanId,\n      traceId: parentEntry?.span.traceId,\n      attributes: {\n        'framework': 'langchain',\n        'langchain.run_id': runId,\n        'tool.name': tool.name || 'unknown',\n        'tool.input_length': input?.length ?? 0,\n      },\n    });\n\n    this._spans.set(runId, { span, startTime: Date.now() });\n  }\n\n  handleToolEnd(output: string, runId: string): void {\n    const entry = this._spans.get(runId);\n    if (!entry) return;\n    entry.span.setAttribute('tool.output_length', output?.length ?? 0);\n    entry.span.setAttribute('gen_ai.latency_ms', Date.now() - entry.startTime);\n    entry.span.end();\n    this._spans.delete(runId);\n  }\n\n  handleToolError(error: Error, runId: string): void {\n    const entry = this._spans.get(runId);\n    if (!entry) return;\n    entry.span.recordException(error);\n    entry.span.end();\n    this._spans.delete(runId);\n  }\n\n  // ── Retriever lifecycle ───────────────────────────────────────────────────\n\n  handleRetrieverStart(\n    retriever: { name?: string },\n    _query: string,\n    runId: string,\n    parentRunId?: string,\n  ): void {\n    const tracer = getTracer();\n    if (!tracer?.enabled) return;\n\n    const parentEntry = parentRunId ? this._spans.get(parentRunId) : undefined;\n    const span = tracer.createSpan({\n      name: retriever.name || 'retriever',\n      kind: SpanKind.RETRIEVAL,\n      parentSpanId: parentEntry?.span.spanId,\n      traceId: parentEntry?.span.traceId,\n      attributes: {\n        'framework': 'langchain',\n        'langchain.run_id': runId,\n      },\n    });\n\n    this._spans.set(runId, { span, startTime: Date.now() });\n  }\n\n  handleRetrieverEnd(documents: unknown[], runId: string): void {\n    const entry = this._spans.get(runId);\n    if (!entry) return;\n    entry.span.setAttribute(\n      'retriever.document_count',\n      documents?.length ?? 0,\n    );\n    entry.span.setAttribute('gen_ai.latency_ms', Date.now() - entry.startTime);\n    entry.span.end();\n    this._spans.delete(runId);\n  }\n}\n","/**\n * LangGraph.js integration via Proxy wrapping.\n *\n * LangGraph uses LangChain callbacks under the hood. This integration wraps\n * a compiled graph's invoke/stream methods to:\n *   1. Create a parent \"langgraph.invoke\" or \"langgraph.stream\" span\n *   2. Inject a RisicareCallbackHandler into the config so all internal\n *      chain/LLM/tool calls are also traced\n *\n * Usage:\n *   import { instrumentLangGraph } from 'risicare/frameworks/langgraph';\n *   const graph = instrumentLangGraph(compiledGraph);\n *   const result = await graph.invoke(input);\n *\n * Does NOT suppress provider instrumentation.\n */\n\nimport { getTracer } from '../client.js';\nimport { SpanKind } from '../types.js';\nimport { RisicareCallbackHandler } from './langchain.js';\n\n/**\n * Wrap a compiled LangGraph graph with Risicare tracing.\n *\n * Returns a Proxy that intercepts `invoke` and `stream` calls to create\n * a parent span and inject the LangChain callback handler.\n *\n * @param graph - A compiled LangGraph graph object with invoke/stream methods\n * @returns A proxied graph with tracing enabled\n */\nexport function instrumentLangGraph<T extends object>(graph: T): T {\n  return new Proxy(graph, {\n    get(target, prop, receiver) {\n      const value = Reflect.get(target, prop, receiver);\n\n      if (\n        (prop === 'invoke' || prop === 'stream') &&\n        typeof value === 'function'\n      ) {\n        return function patchedMethod(\n          this: unknown,\n          ...args: unknown[]\n        ): unknown {\n          const tracer = getTracer();\n          if (!tracer?.enabled) return value.apply(this, args);\n\n          return tracer.startSpan(\n            {\n              name: `langgraph.${String(prop)}`,\n              kind: SpanKind.AGENT,\n              attributes: { framework: 'langgraph' },\n            },\n            (_span) => {\n              // Inject RisicareCallbackHandler into config (second argument)\n              const config = (args[1] ?? {}) as Record<string, unknown>;\n              const callbacks = (config.callbacks ?? []) as unknown[];\n              callbacks.push(new RisicareCallbackHandler());\n              args[1] = { ...config, callbacks };\n\n              const result = value.apply(this, args);\n\n              // Handle async results (Promises)\n              if (\n                result &&\n                typeof (result as Promise<unknown>).then === 'function'\n              ) {\n                return (result as Promise<unknown>).then((r) => r);\n              }\n              return result;\n            },\n          );\n        };\n      }\n\n      return value;\n    },\n  });\n}\n"],"mappings":"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","names":["getTracer","getTracer","getTracer"]}

package/dist/frameworks/llamaindex.cjs

@@ -0,0 +1,239 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/frameworks/llamaindex.ts
+var llamaindex_exports = {};
+__export(llamaindex_exports, {
+  RisicareLlamaIndexHandler: () => RisicareLlamaIndexHandler
+});
+module.exports = __toCommonJS(llamaindex_exports);
+
+// src/ids.ts
+var import_node_crypto = require("crypto");
+
+// src/noop.ts
+var NOOP_SPAN = Object.freeze({
+  traceId: "00000000000000000000000000000000",
+  spanId: "0000000000000000",
+  parentSpanId: void 0,
+  name: "noop",
+  kind: "internal" /* INTERNAL */,
+  startTime: "",
+  startHrtime: 0,
+  endTime: void 0,
+  status: "unset" /* UNSET */,
+  statusMessage: void 0,
+  attributes: Object.freeze({}),
+  events: Object.freeze([]),
+  links: Object.freeze([]),
+  sessionId: void 0,
+  agentId: void 0,
+  agentName: void 0,
+  semanticPhase: void 0,
+  llmProvider: void 0,
+  llmModel: void 0,
+  llmPromptTokens: void 0,
+  llmCompletionTokens: void 0,
+  llmTotalTokens: void 0,
+  llmCostUsd: void 0,
+  toolName: void 0,
+  toolSuccess: void 0,
+  isEnded: true,
+  durationMs: 0,
+  setAttribute() {
+    return this;
+  },
+  setAttributes() {
+    return this;
+  },
+  setStatus() {
+    return this;
+  },
+  addEvent() {
+    return this;
+  },
+  addLink() {
+    return this;
+  },
+  recordException() {
+    return this;
+  },
+  setLlmFields() {
+    return this;
+  },
+  setToolFields() {
+    return this;
+  },
+  end() {
+  },
+  toPayload() {
+    return {
+      traceId: this.traceId,
+      spanId: this.spanId,
+      name: this.name,
+      kind: this.kind,
+      startTime: this.startTime,
+      status: this.status,
+      attributes: {},
+      events: [],
+      links: []
+    };
+  }
+});
+
+// src/globals.ts
+var import_node_async_hooks = require("async_hooks");
+var G = globalThis;
+var PREFIX = "__risicare_";
+function getTracer() {
+  return G[PREFIX + "tracer"];
+}
+function getContextStorage() {
+  if (!G[PREFIX + "ctx"]) {
+    G[PREFIX + "ctx"] = new import_node_async_hooks.AsyncLocalStorage();
+  }
+  return G[PREFIX + "ctx"];
+}
+
+// src/context/storage.ts
+function storage() {
+  return getContextStorage();
+}
+function getContext() {
+  return storage().getStore() ?? {};
+}
+function runWithContext(overrides, fn) {
+  const parent = getContext();
+  const merged = { ...parent, ...overrides };
+  return storage().run(merged, fn);
+}
+
+// src/client.ts
+function getTracer2() {
+  return getTracer();
+}
+
+// src/context/dedup.ts
+function suppressProviderInstrumentation(fn) {
+  return runWithContext({ _suppressProviderInstrumentation: true }, fn);
+}
+
+// src/frameworks/llamaindex.ts
+var RisicareLlamaIndexHandler = class {
+  _spans = /* @__PURE__ */ new Map();
+  /**
+   * Handle a LlamaIndex lifecycle event.
+   *
+   * Events follow the convention:
+   *   - `*.start` / `*.begin` -- component starts
+   *   - `*.end` / `*.complete` -- component finishes
+   *   - `*.error` -- component failed
+   */
+  onEvent(event) {
+    const tracer = getTracer2();
+    if (!tracer?.enabled) return;
+    if (event.type.endsWith(".start") || event.type.endsWith(".begin")) {
+      this._handleStart(event);
+    } else if (event.type.endsWith(".end") || event.type.endsWith(".complete")) {
+      this._handleEnd(event);
+    } else if (event.type.endsWith(".error")) {
+      this._handleError(event);
+    }
+  }
+  /**
+   * Run a function with provider instrumentation suppressed.
+   *
+   * LlamaIndex handler creates its own LLM spans, so provider spans
+   * (patchOpenAI, patchAnthropic, etc.) should be suppressed to avoid
+   * double-tracing.
+   */
+  withSuppression(fn) {
+    return suppressProviderInstrumentation(fn);
+  }
+  // ── Internal event handlers ───────────────────────────────────────────────
+  _handleStart(event) {
+    const tracer = getTracer2();
+    if (!tracer?.enabled) return;
+    const componentKind = this._classifyComponent(event.type);
+    const parentEntry = event.parentId ? this._spans.get(event.parentId) : void 0;
+    const spanKind = componentKind === "llm" ? "llm_call" /* LLM_CALL */ : componentKind === "retrieval" ? "retrieval" /* RETRIEVAL */ : componentKind === "embedding" ? "llm_call" /* LLM_CALL */ : "internal" /* INTERNAL */;
+    const span = tracer.createSpan({
+      name: event.type.replace(/\.(start|begin)$/, ""),
+      kind: spanKind,
+      parentSpanId: parentEntry?.span.spanId,
+      traceId: parentEntry?.span.traceId,
+      attributes: {
+        framework: "llamaindex",
+        "framework.span_kind": componentKind,
+        ...event.data?.model ? { "gen_ai.request.model": event.data.model } : {}
+      }
+    });
+    this._spans.set(event.id, { span, startTime: Date.now(), componentKind });
+  }
+  _handleEnd(event) {
+    const entry = this._spans.get(event.id);
+    if (!entry) return;
+    entry.span.setAttribute(
+      "gen_ai.latency_ms",
+      Date.now() - entry.startTime
+    );
+    const usage = event.data?.usage;
+    if (usage) {
+      entry.span.setLlmFields({
+        promptTokens: usage.promptTokens ?? usage.prompt_tokens,
+        completionTokens: usage.completionTokens ?? usage.completion_tokens
+      });
+    }
+    if (event.data?.documentCount != null) {
+      entry.span.setAttribute(
+        "retriever.document_count",
+        event.data.documentCount
+      );
+    }
+    entry.span.end();
+    this._spans.delete(event.id);
+  }
+  _handleError(event) {
+    const entry = this._spans.get(event.id);
+    if (!entry) return;
+    const error = event.data?.error;
+    entry.span.recordException(
+      error instanceof Error ? error : String(error ?? "Unknown error")
+    );
+    entry.span.end();
+    this._spans.delete(event.id);
+  }
+  /**
+   * Classify a LlamaIndex event type into a component kind.
+   */
+  _classifyComponent(eventType) {
+    const lower = eventType.toLowerCase();
+    if (lower.includes("llm") || lower.includes("chat")) return "llm";
+    if (lower.includes("embed")) return "embedding";
+    if (lower.includes("retriev") || lower.includes("vector")) return "retrieval";
+    if (lower.includes("synth") || lower.includes("response")) return "synthesis";
+    if (lower.includes("query")) return "query";
+    return "component";
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RisicareLlamaIndexHandler
+});
+//# sourceMappingURL=llamaindex.cjs.map

package/dist/frameworks/llamaindex.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/frameworks/llamaindex.ts","../../src/ids.ts","../../src/noop.ts","../../src/globals.ts","../../src/context/storage.ts","../../src/client.ts","../../src/context/dedup.ts"],"sourcesContent":["/**\n * LlamaIndex.TS integration via event handler.\n *\n * LlamaIndex uses a span handler / callback event pattern. This handler\n * receives events with { type, id, parentId, data } and manages the\n * span lifecycle accordingly.\n *\n * Usage:\n *   import { RisicareLlamaIndexHandler } from 'risicare/frameworks/llamaindex';\n *   const handler = new RisicareLlamaIndexHandler();\n *\n *   // Register with LlamaIndex's event system\n *   Settings.callbackManager.on('*', (event) => handler.onEvent(event));\n *\n *   // For LLM/embedding calls, suppress provider instrumentation:\n *   const result = handler.withSuppression(() => query(...));\n *\n * SUPPRESSES provider instrumentation -- LlamaIndex creates its own LLM spans,\n * so provider-level spans (patchOpenAI, etc.) would duplicate.\n */\n\nimport { getTracer } from '../client.js';\nimport { SpanKind } from '../types.js';\nimport { suppressProviderInstrumentation } from '../context/dedup.js';\nimport type { Span } from '../span.js';\n\ninterface SpanEntry {\n  span: Span;\n  startTime: number;\n  componentKind: string;\n}\n\nexport interface LlamaIndexEvent {\n  type: string;\n  id: string;\n  parentId?: string;\n  data?: Record<string, unknown>;\n}\n\nexport class RisicareLlamaIndexHandler {\n  private _spans = new Map<string, SpanEntry>();\n\n  /**\n   * Handle a LlamaIndex lifecycle event.\n   *\n   * Events follow the convention:\n   *   - `*.start` / `*.begin` -- component starts\n   *   - `*.end` / `*.complete` -- component finishes\n   *   - `*.error` -- component failed\n   */\n  onEvent(event: LlamaIndexEvent): void {\n    const tracer = getTracer();\n    if (!tracer?.enabled) return;\n\n    if (event.type.endsWith('.start') || event.type.endsWith('.begin')) {\n      this._handleStart(event);\n    } else if (\n      event.type.endsWith('.end') ||\n      event.type.endsWith('.complete')\n    ) {\n      this._handleEnd(event);\n    } else if (event.type.endsWith('.error')) {\n      this._handleError(event);\n    }\n  }\n\n  /**\n   * Run a function with provider instrumentation suppressed.\n   *\n   * LlamaIndex handler creates its own LLM spans, so provider spans\n   * (patchOpenAI, patchAnthropic, etc.) should be suppressed to avoid\n   * double-tracing.\n   */\n  withSuppression<T>(fn: () => T): T {\n    return suppressProviderInstrumentation(fn);\n  }\n\n  // ── Internal event handlers ───────────────────────────────────────────────\n\n  private _handleStart(event: LlamaIndexEvent): void {\n    const tracer = getTracer();\n    if (!tracer?.enabled) return;\n\n    const componentKind = this._classifyComponent(event.type);\n    const parentEntry = event.parentId\n      ? this._spans.get(event.parentId)\n      : undefined;\n\n    const spanKind =\n      componentKind === 'llm'\n        ? SpanKind.LLM_CALL\n        : componentKind === 'retrieval'\n          ? SpanKind.RETRIEVAL\n          : componentKind === 'embedding'\n            ? SpanKind.LLM_CALL\n            : SpanKind.INTERNAL;\n\n    const span = tracer.createSpan({\n      name: event.type.replace(/\\.(start|begin)$/, ''),\n      kind: spanKind,\n      parentSpanId: parentEntry?.span.spanId,\n      traceId: parentEntry?.span.traceId,\n      attributes: {\n        framework: 'llamaindex',\n        'framework.span_kind': componentKind,\n        ...(event.data?.model\n          ? { 'gen_ai.request.model': event.data.model }\n          : {}),\n      },\n    });\n\n    this._spans.set(event.id, { span, startTime: Date.now(), componentKind });\n  }\n\n  private _handleEnd(event: LlamaIndexEvent): void {\n    const entry = this._spans.get(event.id);\n    if (!entry) return;\n\n    entry.span.setAttribute(\n      'gen_ai.latency_ms',\n      Date.now() - entry.startTime,\n    );\n\n    // Extract token usage if available\n    const usage = event.data?.usage as Record<string, number> | undefined;\n    if (usage) {\n      entry.span.setLlmFields({\n        promptTokens: usage.promptTokens ?? usage.prompt_tokens,\n        completionTokens: usage.completionTokens ?? usage.completion_tokens,\n      });\n    }\n\n    if (event.data?.documentCount != null) {\n      entry.span.setAttribute(\n        'retriever.document_count',\n        event.data.documentCount,\n      );\n    }\n\n    entry.span.end();\n    this._spans.delete(event.id);\n  }\n\n  private _handleError(event: LlamaIndexEvent): void {\n    const entry = this._spans.get(event.id);\n    if (!entry) return;\n\n    const error = event.data?.error;\n    entry.span.recordException(\n      error instanceof Error ? error : String(error ?? 'Unknown error'),\n    );\n    entry.span.end();\n    this._spans.delete(event.id);\n  }\n\n  /**\n   * Classify a LlamaIndex event type into a component kind.\n   */\n  private _classifyComponent(eventType: string): string {\n    const lower = eventType.toLowerCase();\n    if (lower.includes('llm') || lower.includes('chat')) return 'llm';\n    if (lower.includes('embed')) return 'embedding';\n    if (lower.includes('retriev') || lower.includes('vector')) return 'retrieval';\n    if (lower.includes('synth') || lower.includes('response')) return 'synthesis';\n    if (lower.includes('query')) return 'query';\n    return 'component';\n  }\n}\n","/**\n * ID generation for traces and spans.\n *\n * Trace IDs: 32 lowercase hex characters (16 random bytes)\n * Span IDs:  16 lowercase hex characters (8 random bytes)\n *\n * Uses crypto.randomBytes for cryptographically secure randomness.\n */\n\nimport { randomBytes } from 'node:crypto';\n\nconst HEX_REGEX_32 = /^[0-9a-f]{32}$/;\nconst HEX_REGEX_16 = /^[0-9a-f]{16}$/;\n\nexport function generateTraceId(): string {\n  return randomBytes(16).toString('hex');\n}\n\nexport function generateSpanId(): string {\n  return randomBytes(8).toString('hex');\n}\n\nexport function generateAgentId(prefix?: string): string {\n  const suffix = randomBytes(8).toString('hex');\n  return prefix ? `${prefix}-${suffix}` : suffix;\n}\n\nexport function validateTraceId(id: string): boolean {\n  return HEX_REGEX_32.test(id);\n}\n\nexport function validateSpanId(id: string): boolean {\n  return HEX_REGEX_16.test(id);\n}\n","/**\n * No-op implementations for the disabled path.\n *\n * When tracing is disabled, all operations return these no-op objects\n * to maintain zero overhead. No allocations, no side effects.\n */\n\nimport { SpanKind, SpanStatus, type SpanPayload } from './types.js';\n\n/**\n * A frozen no-op span that silently ignores all operations.\n * Used when SDK is disabled to avoid overhead.\n */\nexport const NOOP_SPAN = Object.freeze({\n  traceId: '00000000000000000000000000000000',\n  spanId: '0000000000000000',\n  parentSpanId: undefined,\n  name: 'noop',\n  kind: SpanKind.INTERNAL,\n  startTime: '',\n  startHrtime: 0,\n  endTime: undefined,\n  status: SpanStatus.UNSET,\n  statusMessage: undefined,\n  attributes: Object.freeze({}) as Record<string, unknown>,\n  events: Object.freeze([]) as readonly [],\n  links: Object.freeze([]) as readonly [],\n  sessionId: undefined,\n  agentId: undefined,\n  agentName: undefined,\n  semanticPhase: undefined,\n  llmProvider: undefined,\n  llmModel: undefined,\n  llmPromptTokens: undefined,\n  llmCompletionTokens: undefined,\n  llmTotalTokens: undefined,\n  llmCostUsd: undefined,\n  toolName: undefined,\n  toolSuccess: undefined,\n  isEnded: true,\n  durationMs: 0,\n\n  setAttribute() { return this; },\n  setAttributes() { return this; },\n  setStatus() { return this; },\n  addEvent() { return this; },\n  addLink() { return this; },\n  recordException() { return this; },\n  setLlmFields() { return this; },\n  setToolFields() { return this; },\n  end() {},\n  toPayload(): SpanPayload {\n    return {\n      traceId: this.traceId,\n      spanId: this.spanId,\n      name: this.name,\n      kind: this.kind,\n      startTime: this.startTime,\n      status: this.status,\n      attributes: {},\n      events: [],\n      links: [],\n    };\n  },\n});\n\nexport type NoopSpan = typeof NOOP_SPAN;\n","/**\n * Shared state via globalThis — ensures all entry point bundles share\n * the same singleton instances.\n *\n * Problem: tsup with `splitting: false` gives each entry point (index,\n * openai, anthropic, vercel-ai) its own copy of module-level variables.\n * This means `init()` from 'risicare' sets a tracer that 'risicare/openai'\n * can't see — breaking all provider instrumentation silently.\n *\n * Solution: Store all mutable singletons on globalThis with a namespaced\n * prefix. Every bundle reads/writes the same global slots.\n *\n * This pattern is used by React, OpenTelemetry, and other SDKs that must\n * share state across independently bundled entry points.\n *\n * @internal\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst G = globalThis as any;\nconst PREFIX = '__risicare_';\n\n// ─── Client & Tracer ────────────────────────────────────────────────────────\n\nexport function getClient(): unknown {\n  return G[PREFIX + 'client'];\n}\n\nexport function setClient(client: unknown): void {\n  G[PREFIX + 'client'] = client;\n}\n\nexport function getTracer(): unknown {\n  return G[PREFIX + 'tracer'];\n}\n\nexport function setTracer(tracer: unknown): void {\n  G[PREFIX + 'tracer'] = tracer;\n}\n\n// ─── Context Storage ────────────────────────────────────────────────────────\n\nexport function getContextStorage(): AsyncLocalStorage<unknown> {\n  if (!G[PREFIX + 'ctx']) {\n    G[PREFIX + 'ctx'] = new AsyncLocalStorage();\n  }\n  return G[PREFIX + 'ctx'];\n}\n\n// ─── Span Registry ──────────────────────────────────────────────────────────\n\nexport function getRegistry(): Map<string, unknown> {\n  if (!G[PREFIX + 'registry']) {\n    G[PREFIX + 'registry'] = new Map();\n  }\n  return G[PREFIX + 'registry'];\n}\n\nexport function getOpCount(): number {\n  return G[PREFIX + 'opcount'] ?? 0;\n}\n\nexport function setOpCount(n: number): void {\n  G[PREFIX + 'opcount'] = n;\n}\n\n// ─── Debug Flag ─────────────────────────────────────────────────────────────\n\nexport function getDebug(): boolean {\n  return G[PREFIX + 'debug'] ?? false;\n}\n\nexport function setDebugFlag(enabled: boolean): void {\n  G[PREFIX + 'debug'] = enabled;\n}\n","/**\n * AsyncLocalStorage-based context propagation.\n *\n * Uses a single AsyncLocalStorage instance with a composite state object.\n * This is simpler and more performant than multiple separate stores.\n *\n * Node.js AsyncLocalStorage automatically propagates through:\n * - Promise / async-await\n * - setTimeout / setImmediate\n * - EventEmitter callbacks\n * - process.nextTick\n * - async generators (unlike Python's contextvars!)\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport type { Span } from '../span.js';\nimport type { SemanticPhase } from '../types.js';\nimport { getContextStorage } from '../globals.js';\n\n// ─── Context Types ───────────────────────────────────────────────────────────\n\nexport interface SessionContext {\n  sessionId: string;\n  userId?: string;\n  metadata?: Record<string, unknown>;\n  parentSessionId?: string;\n  turnNumber?: number;\n}\n\nexport interface AgentContext {\n  agentId: string;\n  agentName?: string;\n  agentRole?: string;\n  agentType?: string;\n  parentAgentId?: string;\n  version?: number;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface ContextState {\n  session?: SessionContext;\n  agent?: AgentContext;\n  span?: Span;\n  phase?: SemanticPhase;\n  /** When true, provider instrumentors skip span creation (framework is handling it). */\n  _suppressProviderInstrumentation?: boolean;\n}\n\n// ─── Storage Accessor ────────────────────────────────────────────────────────\n\nfunction storage(): AsyncLocalStorage<ContextState> {\n  return getContextStorage() as AsyncLocalStorage<ContextState>;\n}\n\n// ─── Core Operations ─────────────────────────────────────────────────────────\n\n/**\n * Get the current context state, or empty object if outside any context.\n */\nexport function getContext(): ContextState {\n  return storage().getStore() ?? {};\n}\n\n/**\n * Run a callback within a new context scope.\n * The new scope inherits from the parent, with overrides applied.\n */\nexport function runWithContext<T>(overrides: Partial<ContextState>, fn: () => T): T {\n  const parent = getContext();\n  const merged: ContextState = { ...parent, ...overrides };\n  return storage().run(merged, fn);\n}\n\n/**\n * Run an async callback within a new context scope.\n */\nexport function runWithContextAsync<T>(overrides: Partial<ContextState>, fn: () => Promise<T>): Promise<T> {\n  const parent = getContext();\n  const merged: ContextState = { ...parent, ...overrides };\n  return storage().run(merged, fn);\n}\n\n// ─── Context Accessors ───────────────────────────────────────────────────────\n\nexport function getCurrentSession(): SessionContext | undefined {\n  return getContext().session;\n}\n\nexport function getCurrentAgent(): AgentContext | undefined {\n  return getContext().agent;\n}\n\nexport function getCurrentSpan(): Span | undefined {\n  return getContext().span;\n}\n\nexport function getCurrentPhase(): SemanticPhase | undefined {\n  return getContext().phase;\n}\n\nexport function getCurrentSessionId(): string | undefined {\n  return getContext().session?.sessionId;\n}\n\nexport function getCurrentAgentId(): string | undefined {\n  return getContext().agent?.agentId;\n}\n\nexport function getCurrentTraceId(): string | undefined {\n  return getContext().span?.traceId;\n}\n\nexport function getCurrentSpanId(): string | undefined {\n  return getContext().span?.spanId;\n}\n\nexport function getCurrentParentSpanId(): string | undefined {\n  return getContext().span?.parentSpanId;\n}\n\n/**\n * Get all current context as a plain object (for debugging/serialization).\n */\nexport function getCurrentContext(): Record<string, unknown> {\n  const ctx = getContext();\n  return {\n    session: ctx.session ? {\n      sessionId: ctx.session.sessionId,\n      userId: ctx.session.userId,\n      ...(ctx.session.parentSessionId !== undefined ? { parentSessionId: ctx.session.parentSessionId } : {}),\n      ...(ctx.session.turnNumber !== undefined ? { turnNumber: ctx.session.turnNumber } : {}),\n      ...(ctx.session.metadata !== undefined ? { metadata: ctx.session.metadata } : {}),\n    } : null,\n    agent: ctx.agent ? {\n      agentId: ctx.agent.agentId,\n      agentName: ctx.agent.agentName,\n      agentRole: ctx.agent.agentRole,\n      agentType: ctx.agent.agentType,\n      ...(ctx.agent.parentAgentId !== undefined ? { parentAgentId: ctx.agent.parentAgentId } : {}),\n      ...(ctx.agent.version !== undefined ? { version: ctx.agent.version } : {}),\n      ...(ctx.agent.metadata !== undefined ? { metadata: ctx.agent.metadata } : {}),\n    } : null,\n    span: ctx.span ? { spanId: ctx.span.spanId, traceId: ctx.span.traceId } : null,\n    phase: ctx.phase ?? null,\n  };\n}\n","/**\n * RisicareClient — singleton client managing SDK lifecycle.\n *\n * Handles initialization, shutdown, and the connection between\n * the Tracer and the export pipeline (batch processor + HTTP exporter).\n *\n * Usage:\n *   import { init, shutdown } from 'risicare';\n *   init({ apiKey: 'rsk-...' }); // API key determines project\n *   // ... instrument code ...\n *   await shutdown(); // flush remaining spans\n */\n\nimport { type RisicareConfig, resolveConfig } from './config.js';\nimport { Tracer } from './tracer.js';\nimport { BatchSpanProcessor } from './exporters/batch.js';\nimport { HttpExporter } from './exporters/http.js';\nimport { ConsoleExporter } from './exporters/console.js';\nimport { SpanKind, SpanStatus } from './types.js';\nimport type { SpanExporter } from './exporters/base.js';\nimport { setDebug, debug } from './utils/log.js';\nimport {\n  getClient as getGlobalClient,\n  setClient as setGlobalClient,\n  getTracer as getGlobalTracer,\n  setTracer as setGlobalTracer,\n} from './globals.js';\n\n// ─── Client Class ───────────────────────────────────────────────────────────\n\nclass RisicareClient {\n  readonly config: ReturnType<typeof resolveConfig>;\n  readonly processor: BatchSpanProcessor;\n  readonly tracer: Tracer;\n  private _shutdownPromise: Promise<void> | undefined;\n  private _shutdownHandlers: { signal: string; handler: () => void }[] = [];\n\n  constructor(config?: Partial<RisicareConfig>) {\n    this.config = resolveConfig(config);\n\n    // API key format validation\n    if (this.config.apiKey && !this.config.apiKey.startsWith('rsk-')) {\n      debug('Warning: API key should start with \"rsk-\". Got: ' + this.config.apiKey.slice(0, 4) + '...');\n    }\n\n    // Build exporter chain\n    let exporter: SpanExporter;\n    if (this.config.debug && !this.config.apiKey) {\n      exporter = new ConsoleExporter();\n    } else if (this.config.apiKey) {\n      exporter = new HttpExporter({\n        endpoint: this.config.endpoint,\n        apiKey: this.config.apiKey,\n        projectId: this.config.projectId || undefined,\n        environment: this.config.environment || undefined,\n        compress: this.config.compress,\n      });\n    } else {\n      // No API key and not debug — use console as fallback\n      exporter = new ConsoleExporter();\n    }\n\n    this.processor = new BatchSpanProcessor({\n      exporters: [exporter],\n      batchSize: this.config.batchSize,\n      batchTimeoutMs: this.config.batchTimeoutMs,\n      maxQueueSize: this.config.maxQueueSize,\n      debug: this.config.debug,\n    });\n\n    this.tracer = new Tracer({\n      onSpanEnd: (span) => this.processor.onSpanEnd(span),\n      sampleRate: this.config.sampleRate,\n      enabled: this.config.enabled,\n      traceContent: this.config.traceContent,\n    });\n\n    // Start the batch processor (enables span queuing and periodic flushing)\n    this.processor.start();\n\n    // Register shutdown hooks\n    this._registerShutdownHooks();\n\n    // Enable internal debug logging if configured\n    setDebug(this.config.debug);\n    debug(`Initialized: enabled=${this.config.enabled}, endpoint=${this.config.endpoint}`);\n  }\n\n  get enabled(): boolean {\n    return this.tracer.enabled;\n  }\n\n  set enabled(value: boolean) {\n    this.tracer.enabled = value;\n  }\n\n  // Audit #6: Promise-based shutdown dedup (fixes TOCTOU race condition)\n  async shutdown(): Promise<void> {\n    if (this._shutdownPromise) return this._shutdownPromise;\n    this._shutdownPromise = this._doShutdown();\n    return this._shutdownPromise;\n  }\n\n  private async _doShutdown(): Promise<void> {\n    debug('Shutting down...');\n\n    // Audit #3: Remove process listeners to prevent leak\n    for (const { signal, handler } of this._shutdownHandlers) {\n      process.removeListener(signal, handler);\n    }\n    this._shutdownHandlers = [];\n\n    await this.processor.shutdown();\n  }\n\n  async flush(): Promise<void> {\n    await this.processor.flush();\n  }\n\n  private _registerShutdownHooks(): void {\n    const onShutdown = () => {\n      // Audit #3: Add 5s timeout to prevent hanging on signal\n      const timeout = setTimeout(() => process.exit(1), 5000);\n      timeout.unref();\n      this.shutdown().catch(() => {}).finally(() => clearTimeout(timeout));\n    };\n\n    const signals = ['beforeExit', 'SIGTERM', 'SIGINT'];\n    for (const signal of signals) {\n      process.once(signal, onShutdown);\n      this._shutdownHandlers.push({ signal, handler: onShutdown });\n    }\n  }\n}\n\n// ─── Public API ─────────────────────────────────────────────────────────────\n\n/**\n * Initialize the Risicare SDK. Call once at application startup.\n *\n * @example\n * import { init } from 'risicare';\n * init({ apiKey: 'rsk-...', serviceName: 'my-agent', environment: 'production' });\n */\nexport function init(config?: Partial<RisicareConfig>): void {\n  if (getGlobalClient()) {\n    debug('Already initialized. Call shutdown() first to re-initialize.');\n    return;\n  }\n\n  const client = new RisicareClient(config);\n  setGlobalClient(client);\n  setGlobalTracer(client.tracer);\n}\n\n/**\n * Gracefully shut down the SDK. Flushes pending spans before resolving.\n */\nexport async function shutdown(): Promise<void> {\n  const client = getGlobalClient() as RisicareClient | undefined;\n  if (!client) return;\n  await client.shutdown();\n  setGlobalClient(undefined);\n  setGlobalTracer(undefined);\n}\n\n/**\n * Flush all pending spans without shutting down.\n */\nexport async function flush(): Promise<void> {\n  const client = getGlobalClient() as RisicareClient | undefined;\n  if (!client) return;\n  await client.flush();\n}\n\n/**\n * Enable tracing at runtime.\n */\nexport function enable(): void {\n  const client = getGlobalClient() as RisicareClient | undefined;\n  if (client) client.enabled = true;\n}\n\n/**\n * Disable tracing at runtime. Spans will not be created or exported.\n */\nexport function disable(): void {\n  const client = getGlobalClient() as RisicareClient | undefined;\n  if (client) client.enabled = false;\n}\n\n/**\n * Check whether tracing is currently enabled.\n */\nexport function isEnabled(): boolean {\n  const client = getGlobalClient() as RisicareClient | undefined;\n  return client?.enabled ?? false;\n}\n\n/**\n * Get the global tracer instance. Returns undefined if not initialized.\n */\nexport function getTracer(): Tracer | undefined {\n  return getGlobalTracer() as Tracer | undefined;\n}\n\n/**\n * Get the global tracer, or throw if not initialized.\n * @internal Used by decorators and providers that require an active tracer.\n */\nexport function requireTracer(): Tracer {\n  const tracer = getGlobalTracer() as Tracer | undefined;\n  if (!tracer) {\n    throw new Error(\n      'Risicare SDK not initialized. Call init() before using tracing features.',\n    );\n  }\n  return tracer;\n}\n\n/**\n * Check whether content tracing (prompt/completion capture) is enabled.\n */\nexport function getTraceContent(): boolean {\n  const tracer = getGlobalTracer() as Tracer | undefined;\n  return tracer?.traceContent ?? true;\n}\n\n/**\n * Get SDK metrics: exported spans, dropped spans, failed exports, queue stats.\n * Returns zero-valued metrics if SDK is not initialized.\n */\nexport function getMetrics() {\n  const client = getGlobalClient() as RisicareClient | undefined;\n  return client?.processor.getMetrics() ?? {\n    exportedSpans: 0,\n    droppedSpans: 0,\n    failedExports: 0,\n    queueSize: 0,\n    queueCapacity: 0,\n    queueUtilization: 0,\n  };\n}\n\n// ─── reportError ──────────────────────────────────────────────────────────\n\n/**\n * Report a caught exception to the self-healing pipeline.\n *\n * Creates an error span that triggers diagnosis and fix generation.\n * This function never throws and is non-blocking.\n *\n * @param error - The caught exception (Error object or string)\n * @param options - Optional attributes and context overrides\n */\nexport function reportError(\n  error: unknown,\n  options?: { name?: string; attributes?: Record<string, unknown> },\n): void {\n  try {\n    const tracer = getTracer();\n    if (!tracer) return;\n\n    const err = error instanceof Error ? error : new Error(String(error));\n    const spanName = options?.name ?? `error:${err.constructor.name}`;\n\n    tracer.startSpan({ name: spanName, kind: SpanKind.INTERNAL }, (span) => {\n      span.setStatus(SpanStatus.ERROR, err.message);\n      span.setAttribute('error', true);\n      span.setAttribute('error.type', err.constructor.name);\n      span.setAttribute('error.message', err.message.slice(0, 2000));\n      if (err.stack) span.setAttribute('error.stack', err.stack.slice(0, 4000));\n      span.setAttribute('risicare.reported_error', true);\n      if (options?.attributes) {\n        for (const [k, v] of Object.entries(options.attributes)) {\n          span.setAttribute(k, v);\n        }\n      }\n    });\n  } catch {\n    // Never crash the host application\n    debug('reportError failed');\n  }\n}\n\n// ─── score ─────────────────────────────────────────────────────────────────\n\n/**\n * Record a custom evaluation score on a trace.\n *\n * Sends the score to the server in a fire-and-forget fashion.\n * This function never throws and is non-blocking.\n *\n * @param traceId - The trace to score\n * @param name - Score name (e.g., \"accuracy\", \"user_satisfaction\")\n * @param value - Score value between 0.0 and 1.0 inclusive\n * @param options - Optional span_id and comment\n */\nexport function score(\n  traceId: string,\n  name: string,\n  value: number,\n  options?: { spanId?: string; comment?: string },\n): void {\n  try {\n    if (typeof value !== 'number' || value < 0.0 || value > 1.0) {\n      debug(`score: value must be in [0.0, 1.0], got ${value}. Score not sent.`);\n      return;\n    }\n    if (!traceId || !name) {\n      debug('score: traceId and name are required');\n      return;\n    }\n\n    const client = getGlobalClient() as RisicareClient | undefined;\n    if (!client?.enabled || !client.config.apiKey) return;\n\n    const endpoint = client.config.endpoint.replace(/\\/$/, '');\n    const url = `${endpoint}/api/v1/scores`;\n    const body = JSON.stringify({\n      trace_id: traceId,\n      name,\n      score: value,\n      source: 'sdk',\n      ...(options?.spanId && { span_id: options.spanId }),\n      ...(options?.comment && { comment: options.comment }),\n    });\n\n    // Fire-and-forget — never blocks caller\n    fetch(url, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        'Authorization': `Bearer ${client.config.apiKey}`,\n      },\n      body,\n    }).catch((err) => debug(`score: send failed: ${err}`));\n  } catch {\n    // Never crash the host application\n    debug('score failed');\n  }\n}\n","/**\n * Double-tracing prevention for framework integrations.\n *\n * When a framework integration (e.g., LlamaIndex handler) creates its own\n * LLM span, the underlying provider proxy (e.g., patchOpenAI) would also\n * create a duplicate span. This module provides suppression:\n *\n * - Framework integrations SET suppression via suppressProviderInstrumentation()\n * - Provider proxies CHECK via isProviderInstrumentationSuppressed() and skip\n *\n * Scoped to AsyncLocalStorage — concurrent calls are independent.\n */\n\nimport { getContext, runWithContext } from './storage.js';\n\n/**\n * Run a callback with provider instrumentation suppressed.\n *\n * During this callback, all provider instrumentors (patchOpenAI, etc.) will\n * skip span creation. The framework is responsible for creating the span.\n *\n * @param fn - The function to run with suppression active\n * @returns The function's return value\n */\nexport function suppressProviderInstrumentation<T>(fn: () => T): T {\n  return runWithContext({ _suppressProviderInstrumentation: true }, fn);\n}\n\n/**\n * Check if provider instrumentation should be suppressed.\n *\n * Called by provider instrumentors as an early-exit guard. When true,\n * the provider calls the original method directly without creating a span.\n */\nexport function isProviderInstrumentationSuppressed(): boolean {\n  return getContext()._suppressProviderInstrumentation === true;\n}\n"],"mappings":"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","names":["getTracer","getTracer"]}