risicare 0.9.2 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/CHANGELOG.md +254 -0
  2. package/README.md +194 -58
  3. package/dist/frameworks/instructor.cjs +383 -117
  4. package/dist/frameworks/instructor.cjs.map +1 -1
  5. package/dist/frameworks/instructor.js +383 -117
  6. package/dist/frameworks/instructor.js.map +1 -1
  7. package/dist/frameworks/langchain.cjs +396 -130
  8. package/dist/frameworks/langchain.cjs.map +1 -1
  9. package/dist/frameworks/langchain.js +396 -130
  10. package/dist/frameworks/langchain.js.map +1 -1
  11. package/dist/frameworks/langgraph.cjs +396 -130
  12. package/dist/frameworks/langgraph.cjs.map +1 -1
  13. package/dist/frameworks/langgraph.js +396 -130
  14. package/dist/frameworks/langgraph.js.map +1 -1
  15. package/dist/frameworks/llamaindex.cjs +396 -130
  16. package/dist/frameworks/llamaindex.cjs.map +1 -1
  17. package/dist/frameworks/llamaindex.js +396 -130
  18. package/dist/frameworks/llamaindex.js.map +1 -1
  19. package/dist/index.cjs +1136 -240
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.d.cts +151 -26
  22. package/dist/index.d.ts +151 -26
  23. package/dist/index.js +1132 -240
  24. package/dist/index.js.map +1 -1
  25. package/dist/providers/anthropic/index.cjs +467 -137
  26. package/dist/providers/anthropic/index.cjs.map +1 -1
  27. package/dist/providers/anthropic/index.js +467 -137
  28. package/dist/providers/anthropic/index.js.map +1 -1
  29. package/dist/providers/bedrock/index.cjs +409 -128
  30. package/dist/providers/bedrock/index.cjs.map +1 -1
  31. package/dist/providers/bedrock/index.js +409 -128
  32. package/dist/providers/bedrock/index.js.map +1 -1
  33. package/dist/providers/cerebras/index.cjs +414 -133
  34. package/dist/providers/cerebras/index.cjs.map +1 -1
  35. package/dist/providers/cerebras/index.js +414 -133
  36. package/dist/providers/cerebras/index.js.map +1 -1
  37. package/dist/providers/cohere/index.cjs +414 -133
  38. package/dist/providers/cohere/index.cjs.map +1 -1
  39. package/dist/providers/cohere/index.js +414 -133
  40. package/dist/providers/cohere/index.js.map +1 -1
  41. package/dist/providers/google/index.cjs +414 -133
  42. package/dist/providers/google/index.cjs.map +1 -1
  43. package/dist/providers/google/index.js +414 -133
  44. package/dist/providers/google/index.js.map +1 -1
  45. package/dist/providers/groq/index.cjs +414 -133
  46. package/dist/providers/groq/index.cjs.map +1 -1
  47. package/dist/providers/groq/index.js +414 -133
  48. package/dist/providers/groq/index.js.map +1 -1
  49. package/dist/providers/huggingface/index.cjs +414 -133
  50. package/dist/providers/huggingface/index.cjs.map +1 -1
  51. package/dist/providers/huggingface/index.js +414 -133
  52. package/dist/providers/huggingface/index.js.map +1 -1
  53. package/dist/providers/mistral/index.cjs +414 -133
  54. package/dist/providers/mistral/index.cjs.map +1 -1
  55. package/dist/providers/mistral/index.js +414 -133
  56. package/dist/providers/mistral/index.js.map +1 -1
  57. package/dist/providers/ollama/index.cjs +414 -133
  58. package/dist/providers/ollama/index.cjs.map +1 -1
  59. package/dist/providers/ollama/index.js +414 -133
  60. package/dist/providers/ollama/index.js.map +1 -1
  61. package/dist/providers/openai/index.cjs +452 -135
  62. package/dist/providers/openai/index.cjs.map +1 -1
  63. package/dist/providers/openai/index.js +452 -135
  64. package/dist/providers/openai/index.js.map +1 -1
  65. package/dist/providers/together/index.cjs +414 -133
  66. package/dist/providers/together/index.cjs.map +1 -1
  67. package/dist/providers/together/index.js +414 -133
  68. package/dist/providers/together/index.js.map +1 -1
  69. package/dist/providers/vercel-ai/index.cjs +398 -132
  70. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  71. package/dist/providers/vercel-ai/index.js +398 -132
  72. package/dist/providers/vercel-ai/index.js.map +1 -1
  73. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -310,10 +310,17 @@ interface RisicareConfig {
310
310
  /**
311
311
  * Whether prompt/completion content may leave the process.
312
312
  *
313
- * **Default `false` since 0.5.1** (was `true`). When false, every
314
- * content-keyed attribute is replaced with `<risicare:content-omitted>` on
315
- * the export path — including content you set by hand, which 0.5.0 and
316
- * earlier did NOT gate.
313
+ * **Default `true`** (capture is on). Set `false`, or set
314
+ * `RISICARE_TRACE_CONTENT=false`, to stop capture. Capture was on through
315
+ * 0.5.0, off by default from 0.5.2 to 0.9.2, and is on by default again after
316
+ * 0.9.2. When false, every content-keyed attribute is replaced with
317
+ * `<risicare:content-omitted>` on the export path — including content you
318
+ * set by hand, which 0.5.0 and earlier did NOT gate. The project setting in
319
+ * the Risicare dashboard can also turn content off for a project; the
320
+ * gateway then drops it. With `traceContent: false`, the SDK still sends the
321
+ * status message, the exception message, the stack trace (which repeats the
322
+ * message), `error.message` and `exception.message`. Only the project switch
323
+ * masks them, at the gateway.
317
324
  */
318
325
  traceContent?: boolean;
319
326
  /** Sample rate 0.0–1.0 (default: 1.0 = trace all) */
@@ -322,8 +329,26 @@ interface RisicareConfig {
322
329
  batchSize?: number;
323
330
  /** Batch timeout in ms before flush (default: 1000) */
324
331
  batchTimeoutMs?: number;
325
- /** Maximum queue size (default: 10000) */
332
+ /**
333
+ * Maximum queue size (default: 10000). When the queue is full, the OLDEST queued span is
334
+ * dropped (`queue_full`) and the new one is kept.
335
+ */
326
336
  maxQueueSize?: number;
337
+ /**
338
+ * How long the HTTP exporter retries one batch, in seconds from its first attempt (default
339
+ * 300). 408, 429, 500, 502, 503, 504, a connection error and a timeout are retried with
340
+ * full-jitter backoff (base 1 s, cap 30 s; `Retry-After` replaces the wait). A batch that the
341
+ * gateway does not take within the horizon is dropped with the reason `retry_exhausted`: a
342
+ * gateway outage that is longer than the horizon loses spans. 0 sends each batch once. No
343
+ * environment-variable form, as in Python. See `exporters/retry.ts`.
344
+ */
345
+ retryHorizonS?: number;
346
+ /**
347
+ * The budget of `shutdown()` in seconds (default 10), and of the SDK's own teardown at
348
+ * `beforeExit`, SIGTERM and SIGINT. Spans that it cannot send in that time are counted as
349
+ * `shutdown_residue`. No environment-variable form, as in Python.
350
+ */
351
+ shutdownTimeoutS?: number;
327
352
  /** Enable debug logging (default: false) */
328
353
  debug?: boolean;
329
354
  /** Enable gzip compression for HTTP exports (default: false) */
@@ -400,7 +425,9 @@ interface TracerConfig {
400
425
  /** Whether tracing is enabled */
401
426
  enabled?: boolean;
402
427
  /**
403
- * Whether prompt/completion content may leave the process (default: false).
428
+ * Whether prompt/completion content may leave the process. A Tracer built
429
+ * without this value uses `false` (fail-closed); that is NOT the user default,
430
+ * which is `true` in `resolveConfig`.
404
431
  *
405
432
  * ⚠ The Tracer only CARRIES this for the provider patches to read via
406
433
  * `getTraceContent()`. It is NOT the enforcement point — the gate runs in the
@@ -486,10 +513,10 @@ declare function init(config?: Partial<RisicareConfig>): void;
486
513
  /**
487
514
  * Gracefully shut down the SDK. Flushes pending spans before resolving.
488
515
  *
489
- * @param timeoutMs - The shutdown budget in milliseconds (default 5000). It is a
490
- * hard wall-clock bound. A value that is not a finite number (NaN, Infinity, a
491
- * string, null) gives 5000. A negative value gives 0. The largest value is
492
- * 2**31 - 1.
516
+ * @param timeoutMs - The shutdown budget in milliseconds. It is a hard wall-clock
517
+ * bound. Not given, or a value that is not a finite number (NaN, Infinity, a
518
+ * string, null): the `shutdownTimeoutS` of `init()` (default 10 s). A negative
519
+ * value gives 0. The largest value is 2**31 - 1.
493
520
  *
494
521
  * At the deadline, `shutdown()` stops the export in flight. Spans still queued
495
522
  * and spans in the stopped export are counted as `shutdown_residue`, with one
@@ -598,14 +625,18 @@ declare function getMetrics(): {
598
625
  rejectedSpans: number;
599
626
  droppedSpans: number;
600
627
  droppedSpansByReason: {
601
- queue_full: number;
602
628
  transport_refused: number;
629
+ retry_exhausted: number;
603
630
  shutdown_residue: number;
631
+ too_large: number;
632
+ queue_full: number;
604
633
  unacknowledged: number;
605
634
  quota_exceeded: number;
606
635
  };
607
636
  droppedQuota: number;
608
637
  failedExports: number;
638
+ attempts: number;
639
+ oldestPendingAgeS: number;
609
640
  maskErrors: number;
610
641
  queueSize: number;
611
642
  queueCapacity: number;
@@ -613,9 +644,11 @@ declare function getMetrics(): {
613
644
  } | {
614
645
  failedScores: number;
615
646
  droppedSpansByReason: {
616
- queue_full: number;
617
647
  transport_refused: number;
648
+ retry_exhausted: number;
618
649
  shutdown_residue: number;
650
+ too_large: number;
651
+ queue_full: number;
619
652
  unacknowledged: number;
620
653
  quota_exceeded: number;
621
654
  };
@@ -625,6 +658,8 @@ declare function getMetrics(): {
625
658
  droppedSpans: number;
626
659
  droppedQuota: number;
627
660
  failedExports: number;
661
+ attempts: number;
662
+ oldestPendingAgeS: number;
628
663
  maskErrors: number;
629
664
  queueSize: number;
630
665
  queueCapacity: number;
@@ -640,9 +675,13 @@ declare function getMetrics(): {
640
675
  shutdown_residue: number;
641
676
  unacknowledged: number;
642
677
  quota_exceeded: number;
678
+ retry_exhausted: number;
679
+ too_large: number;
643
680
  };
644
681
  droppedQuota: number;
645
682
  failedExports: number;
683
+ attempts: number;
684
+ oldestPendingAgeS: number;
646
685
  queueSize: number;
647
686
  queueCapacity: number;
648
687
  queueUtilization: number;
@@ -662,8 +701,37 @@ declare function reportError(error: unknown, options?: {
662
701
  name?: string;
663
702
  attributes?: Record<string, unknown>;
664
703
  }): void;
704
+ /** What a score's judgment is (score v2, W2-5). See "Scores, feedback and outcomes" in the README. */
705
+ type ScoreKind = 'annotation' | 'eval' | 'feedback' | 'outcome';
706
+ /** The arguments of `score()` (score v2). One of `traceId` and `sessionId` is required. */
707
+ interface ScoreOptions {
708
+ /** Score name, 1 to 128 characters (for example "accuracy", "resolved"). */
709
+ name: string;
710
+ /** A finite number (any range), a string of 1 to 256 characters, or a boolean. */
711
+ value: number | string | boolean;
712
+ /** The trace to score (32 lowercase hex characters). */
713
+ traceId?: string;
714
+ /** A span within the trace (16 lowercase hex characters). Needs `traceId`. */
715
+ spanId?: string;
716
+ /** The session to score (1 to 255 characters), with or instead of a trace. */
717
+ sessionId?: string;
718
+ /** A human-readable explanation, at most 4,096 characters. */
719
+ comment?: string;
720
+ /** What the judgment is. Default `annotation`. */
721
+ kind?: ScoreKind;
722
+ }
665
723
  /**
666
- * Record a custom evaluation score on a trace.
724
+ * Record a score on a trace, a span or a session (score v2, W2-5).
725
+ *
726
+ * `value` is typed, and its type decides how the Risicare server stores it: a finite number (any
727
+ * range) is numeric, a string of 1 to 256 characters is categorical, `true` or `false` is boolean.
728
+ * `kind` says what the judgment is: `annotation` (a person's judgment, the default), `eval` (an
729
+ * evaluator, a model or a rule), `feedback` (the end user's reaction) or `outcome` (a result that
730
+ * your own system knows, such as resolved, refunded or goal met; no model infers it). One of
731
+ * `traceId` and `sessionId` is required; `spanId` needs `traceId`.
732
+ *
733
+ * The positional form of 0.10.0 and earlier, `score(traceId, name, value, { spanId, comment })`,
734
+ * still sends the score, and the first such call writes one WARNING. Use the object form.
667
735
  *
668
736
  * Sends the score in the background. The root `flush()` waits for it.
669
737
  * This function never throws and does not block. At most 50 score requests
@@ -678,21 +746,23 @@ declare function reportError(error: unknown, options?: {
678
746
  * the score name and the status or the error code. Later failures in the next
679
747
  * 10 s are counted, and the next WARNING gives their number. Root `flush()`
680
748
  * waits for pending scores inside its deadline, and returns `false` when a
681
- * score failed since the previous `flush()` returned. An out-of-range value, a
682
- * value that is not a number, or an empty `traceId` or `name` writes one WARNING,
683
- * and the SDK does not send the score. It counts as a failed score, so the next
684
- * `flush()` is false (not when the SDK is not active: then nothing is counted).
685
- * `true` and `false` count as 1 and 0.
749
+ * score failed since the previous `flush()` returned. A score that the SDK refuses at the call
750
+ * (a value that is not a finite number, a string of 1 to 256 characters or a boolean; an empty or
751
+ * too long name; no trace and no session; a span with no trace; an unknown kind) writes one
752
+ * WARNING, and the SDK does not send it. It counts as a failed score, so the next `flush()` is
753
+ * false (not when the SDK is not active: then nothing is counted).
686
754
  *
687
- * If a `mask` is configured on `init()`, `options.comment` is passed to it under
688
- * the key `score.comment` before the request is built. `traceId`, `spanId` and
689
- * `name` are NOT masked — they are identifiers the platform joins and groups on.
755
+ * If a `mask` is configured on `init()`, `comment` is passed to it under the key `score.comment`
756
+ * before the request is built. `traceId`, `spanId`, `sessionId`, `name` and `value` are NOT
757
+ * masked: they are identifiers and the judgment itself, which the platform joins, groups and
758
+ * filters on.
690
759
  *
691
- * @param traceId - The trace to score
692
- * @param name - Score name (e.g., "accuracy", "user_satisfaction")
693
- * @param value - Score value between 0.0 and 1.0 inclusive
694
- * @param options - Optional span_id and comment
760
+ * @example
761
+ * score({ name: 'factual_accuracy', value: 0.92, traceId });
762
+ * score({ name: 'resolved', value: true, sessionId: 'conv-7', kind: 'outcome' });
695
763
  */
764
+ declare function score(options: ScoreOptions): void;
765
+ /** @deprecated Use `score({ name, value, traceId, spanId, comment })`. */
696
766
  declare function score(traceId: string, name: string, value: number, options?: {
697
767
  spanId?: string;
698
768
  comment?: string;
@@ -814,6 +884,61 @@ declare function session(options: SessionOptions): <TArgs extends unknown[], TR>
814
884
  declare function session<TArgs extends unknown[]>(resolver: (...args: TArgs) => SessionOptions): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
815
885
  declare function session<TArgs extends unknown[]>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions)): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
816
886
 
887
+ /**
888
+ * Identity helpers (W2-2): put the user, the session, the release and tags on the current trace.
889
+ *
890
+ * The Python twin is `risicare/identity.py`. Each helper writes one span attribute that the
891
+ * Risicare spans worker reads into a dashboard column (contract spec W2-2, section 6; ANSWER 91):
892
+ *
893
+ * | Helper | Span attribute | Column |
894
+ * |------------------------|----------------------|---------|
895
+ * | `setUser(id)` | `user.id` | User |
896
+ * | `setSession(id)` | `session.id` | Session |
897
+ * | `setRelease(version)` | `risicare.release` | Release |
898
+ * | `addTags([...])` | `tag.tags` | Tags |
899
+ *
900
+ * Scope. The current span gets the attribute at once. Each other span of the same trace that
901
+ * ends after the call gets it when it ends, unless that span has the attribute already (tags are
902
+ * merged, in order, with no repeats). That includes the spans that are open now (for example the
903
+ * root span) and the spans that start later, in any async context of this process. A span of
904
+ * another trace never gets it, so a value cannot pass from one request to the next.
905
+ *
906
+ * Outside a span there is no trace: the helper sets nothing and returns `false`, and the first
907
+ * such call of each helper writes one WARNING. For a value that must apply before the first span,
908
+ * use `withSession({ sessionId, userId }, fn)` or `init({ serviceVersion })`.
909
+ *
910
+ * The values of at most `MAX_TRACES` traces are kept (the oldest is forgotten first), so memory
911
+ * stays bounded in a long-running process. The registry lives on `globalThis`, so that every
912
+ * entry point bundle uses the same one (see `globals.ts`).
913
+ */
914
+
915
+ /**
916
+ * Set the user of the current trace: the span attribute `user.id` (dashboard column User).
917
+ * Returns `true` when it was set. The worker reads `session.user_id` (from `withSession`) and
918
+ * `user_id` before `user.id`, so a session user wins.
919
+ */
920
+ declare function setUser(userId: string | number): boolean;
921
+ /**
922
+ * Set the session of the current trace: the span attribute `session.id` (column Session).
923
+ * Returns `true` when it was set. The worker reads the typed session of a span (from
924
+ * `withSession`) before `session.id`, so a session context wins.
925
+ */
926
+ declare function setSession(sessionId: string | number): boolean;
927
+ /**
928
+ * Set the release of the current trace: the span attribute `risicare.release` (column Release).
929
+ * Returns `true` when it was set. `risicare.release` is the first source of the Release column;
930
+ * the next one is `service.version`, which `init({ serviceVersion })` (or
931
+ * `RISICARE_SERVICE_VERSION`) puts on every span with no other code.
932
+ */
933
+ declare function setRelease(version: string | number): boolean;
934
+ /**
935
+ * Add tags to the current trace: the span attribute `tag.tags`, an array (column Tags). A later
936
+ * call adds to the tags of the earlier ones, in order, with no repeats. Returns `true` when at
937
+ * least one tag was added. An item that is not a non-empty string is left out, with one WARNING.
938
+ * The worker keeps at most 50 tags for each span and cuts each one at 200 characters.
939
+ */
940
+ declare function addTags(tags: readonly string[]): boolean;
941
+
817
942
  /**
818
943
  * Phase decorators — decision phase tracking (Tier 4).
819
944
  *
@@ -1769,4 +1894,4 @@ type Tracer = Tracer$1;
1769
1894
 
1770
1895
  type Span = Span$1;
1771
1896
 
1772
- export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, GuardRejectedError, type HeaderLookup, MASK_ERROR_MARKER, type MaskFn, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, type Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, type Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, 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, verifyWebhookSignature, withAgent, withPhase, withSession };
1897
+ export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, GuardRejectedError, type HeaderLookup, MASK_ERROR_MARKER, type MaskFn, MessageType, type RisicareConfig, type ScoreKind, type ScoreOptions, SemanticPhase, type SessionContext, type SessionOptions, type Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, type Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, addTags, 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, setRelease, setSession, setUser, shutdown, shutdownFixRuntime, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, verifyWebhookSignature, withAgent, withPhase, withSession };
package/dist/index.d.ts CHANGED
@@ -310,10 +310,17 @@ interface RisicareConfig {
310
310
  /**
311
311
  * Whether prompt/completion content may leave the process.
312
312
  *
313
- * **Default `false` since 0.5.1** (was `true`). When false, every
314
- * content-keyed attribute is replaced with `<risicare:content-omitted>` on
315
- * the export path — including content you set by hand, which 0.5.0 and
316
- * earlier did NOT gate.
313
+ * **Default `true`** (capture is on). Set `false`, or set
314
+ * `RISICARE_TRACE_CONTENT=false`, to stop capture. Capture was on through
315
+ * 0.5.0, off by default from 0.5.2 to 0.9.2, and is on by default again after
316
+ * 0.9.2. When false, every content-keyed attribute is replaced with
317
+ * `<risicare:content-omitted>` on the export path — including content you
318
+ * set by hand, which 0.5.0 and earlier did NOT gate. The project setting in
319
+ * the Risicare dashboard can also turn content off for a project; the
320
+ * gateway then drops it. With `traceContent: false`, the SDK still sends the
321
+ * status message, the exception message, the stack trace (which repeats the
322
+ * message), `error.message` and `exception.message`. Only the project switch
323
+ * masks them, at the gateway.
317
324
  */
318
325
  traceContent?: boolean;
319
326
  /** Sample rate 0.0–1.0 (default: 1.0 = trace all) */
@@ -322,8 +329,26 @@ interface RisicareConfig {
322
329
  batchSize?: number;
323
330
  /** Batch timeout in ms before flush (default: 1000) */
324
331
  batchTimeoutMs?: number;
325
- /** Maximum queue size (default: 10000) */
332
+ /**
333
+ * Maximum queue size (default: 10000). When the queue is full, the OLDEST queued span is
334
+ * dropped (`queue_full`) and the new one is kept.
335
+ */
326
336
  maxQueueSize?: number;
337
+ /**
338
+ * How long the HTTP exporter retries one batch, in seconds from its first attempt (default
339
+ * 300). 408, 429, 500, 502, 503, 504, a connection error and a timeout are retried with
340
+ * full-jitter backoff (base 1 s, cap 30 s; `Retry-After` replaces the wait). A batch that the
341
+ * gateway does not take within the horizon is dropped with the reason `retry_exhausted`: a
342
+ * gateway outage that is longer than the horizon loses spans. 0 sends each batch once. No
343
+ * environment-variable form, as in Python. See `exporters/retry.ts`.
344
+ */
345
+ retryHorizonS?: number;
346
+ /**
347
+ * The budget of `shutdown()` in seconds (default 10), and of the SDK's own teardown at
348
+ * `beforeExit`, SIGTERM and SIGINT. Spans that it cannot send in that time are counted as
349
+ * `shutdown_residue`. No environment-variable form, as in Python.
350
+ */
351
+ shutdownTimeoutS?: number;
327
352
  /** Enable debug logging (default: false) */
328
353
  debug?: boolean;
329
354
  /** Enable gzip compression for HTTP exports (default: false) */
@@ -400,7 +425,9 @@ interface TracerConfig {
400
425
  /** Whether tracing is enabled */
401
426
  enabled?: boolean;
402
427
  /**
403
- * Whether prompt/completion content may leave the process (default: false).
428
+ * Whether prompt/completion content may leave the process. A Tracer built
429
+ * without this value uses `false` (fail-closed); that is NOT the user default,
430
+ * which is `true` in `resolveConfig`.
404
431
  *
405
432
  * ⚠ The Tracer only CARRIES this for the provider patches to read via
406
433
  * `getTraceContent()`. It is NOT the enforcement point — the gate runs in the
@@ -486,10 +513,10 @@ declare function init(config?: Partial<RisicareConfig>): void;
486
513
  /**
487
514
  * Gracefully shut down the SDK. Flushes pending spans before resolving.
488
515
  *
489
- * @param timeoutMs - The shutdown budget in milliseconds (default 5000). It is a
490
- * hard wall-clock bound. A value that is not a finite number (NaN, Infinity, a
491
- * string, null) gives 5000. A negative value gives 0. The largest value is
492
- * 2**31 - 1.
516
+ * @param timeoutMs - The shutdown budget in milliseconds. It is a hard wall-clock
517
+ * bound. Not given, or a value that is not a finite number (NaN, Infinity, a
518
+ * string, null): the `shutdownTimeoutS` of `init()` (default 10 s). A negative
519
+ * value gives 0. The largest value is 2**31 - 1.
493
520
  *
494
521
  * At the deadline, `shutdown()` stops the export in flight. Spans still queued
495
522
  * and spans in the stopped export are counted as `shutdown_residue`, with one
@@ -598,14 +625,18 @@ declare function getMetrics(): {
598
625
  rejectedSpans: number;
599
626
  droppedSpans: number;
600
627
  droppedSpansByReason: {
601
- queue_full: number;
602
628
  transport_refused: number;
629
+ retry_exhausted: number;
603
630
  shutdown_residue: number;
631
+ too_large: number;
632
+ queue_full: number;
604
633
  unacknowledged: number;
605
634
  quota_exceeded: number;
606
635
  };
607
636
  droppedQuota: number;
608
637
  failedExports: number;
638
+ attempts: number;
639
+ oldestPendingAgeS: number;
609
640
  maskErrors: number;
610
641
  queueSize: number;
611
642
  queueCapacity: number;
@@ -613,9 +644,11 @@ declare function getMetrics(): {
613
644
  } | {
614
645
  failedScores: number;
615
646
  droppedSpansByReason: {
616
- queue_full: number;
617
647
  transport_refused: number;
648
+ retry_exhausted: number;
618
649
  shutdown_residue: number;
650
+ too_large: number;
651
+ queue_full: number;
619
652
  unacknowledged: number;
620
653
  quota_exceeded: number;
621
654
  };
@@ -625,6 +658,8 @@ declare function getMetrics(): {
625
658
  droppedSpans: number;
626
659
  droppedQuota: number;
627
660
  failedExports: number;
661
+ attempts: number;
662
+ oldestPendingAgeS: number;
628
663
  maskErrors: number;
629
664
  queueSize: number;
630
665
  queueCapacity: number;
@@ -640,9 +675,13 @@ declare function getMetrics(): {
640
675
  shutdown_residue: number;
641
676
  unacknowledged: number;
642
677
  quota_exceeded: number;
678
+ retry_exhausted: number;
679
+ too_large: number;
643
680
  };
644
681
  droppedQuota: number;
645
682
  failedExports: number;
683
+ attempts: number;
684
+ oldestPendingAgeS: number;
646
685
  queueSize: number;
647
686
  queueCapacity: number;
648
687
  queueUtilization: number;
@@ -662,8 +701,37 @@ declare function reportError(error: unknown, options?: {
662
701
  name?: string;
663
702
  attributes?: Record<string, unknown>;
664
703
  }): void;
704
+ /** What a score's judgment is (score v2, W2-5). See "Scores, feedback and outcomes" in the README. */
705
+ type ScoreKind = 'annotation' | 'eval' | 'feedback' | 'outcome';
706
+ /** The arguments of `score()` (score v2). One of `traceId` and `sessionId` is required. */
707
+ interface ScoreOptions {
708
+ /** Score name, 1 to 128 characters (for example "accuracy", "resolved"). */
709
+ name: string;
710
+ /** A finite number (any range), a string of 1 to 256 characters, or a boolean. */
711
+ value: number | string | boolean;
712
+ /** The trace to score (32 lowercase hex characters). */
713
+ traceId?: string;
714
+ /** A span within the trace (16 lowercase hex characters). Needs `traceId`. */
715
+ spanId?: string;
716
+ /** The session to score (1 to 255 characters), with or instead of a trace. */
717
+ sessionId?: string;
718
+ /** A human-readable explanation, at most 4,096 characters. */
719
+ comment?: string;
720
+ /** What the judgment is. Default `annotation`. */
721
+ kind?: ScoreKind;
722
+ }
665
723
  /**
666
- * Record a custom evaluation score on a trace.
724
+ * Record a score on a trace, a span or a session (score v2, W2-5).
725
+ *
726
+ * `value` is typed, and its type decides how the Risicare server stores it: a finite number (any
727
+ * range) is numeric, a string of 1 to 256 characters is categorical, `true` or `false` is boolean.
728
+ * `kind` says what the judgment is: `annotation` (a person's judgment, the default), `eval` (an
729
+ * evaluator, a model or a rule), `feedback` (the end user's reaction) or `outcome` (a result that
730
+ * your own system knows, such as resolved, refunded or goal met; no model infers it). One of
731
+ * `traceId` and `sessionId` is required; `spanId` needs `traceId`.
732
+ *
733
+ * The positional form of 0.10.0 and earlier, `score(traceId, name, value, { spanId, comment })`,
734
+ * still sends the score, and the first such call writes one WARNING. Use the object form.
667
735
  *
668
736
  * Sends the score in the background. The root `flush()` waits for it.
669
737
  * This function never throws and does not block. At most 50 score requests
@@ -678,21 +746,23 @@ declare function reportError(error: unknown, options?: {
678
746
  * the score name and the status or the error code. Later failures in the next
679
747
  * 10 s are counted, and the next WARNING gives their number. Root `flush()`
680
748
  * waits for pending scores inside its deadline, and returns `false` when a
681
- * score failed since the previous `flush()` returned. An out-of-range value, a
682
- * value that is not a number, or an empty `traceId` or `name` writes one WARNING,
683
- * and the SDK does not send the score. It counts as a failed score, so the next
684
- * `flush()` is false (not when the SDK is not active: then nothing is counted).
685
- * `true` and `false` count as 1 and 0.
749
+ * score failed since the previous `flush()` returned. A score that the SDK refuses at the call
750
+ * (a value that is not a finite number, a string of 1 to 256 characters or a boolean; an empty or
751
+ * too long name; no trace and no session; a span with no trace; an unknown kind) writes one
752
+ * WARNING, and the SDK does not send it. It counts as a failed score, so the next `flush()` is
753
+ * false (not when the SDK is not active: then nothing is counted).
686
754
  *
687
- * If a `mask` is configured on `init()`, `options.comment` is passed to it under
688
- * the key `score.comment` before the request is built. `traceId`, `spanId` and
689
- * `name` are NOT masked — they are identifiers the platform joins and groups on.
755
+ * If a `mask` is configured on `init()`, `comment` is passed to it under the key `score.comment`
756
+ * before the request is built. `traceId`, `spanId`, `sessionId`, `name` and `value` are NOT
757
+ * masked: they are identifiers and the judgment itself, which the platform joins, groups and
758
+ * filters on.
690
759
  *
691
- * @param traceId - The trace to score
692
- * @param name - Score name (e.g., "accuracy", "user_satisfaction")
693
- * @param value - Score value between 0.0 and 1.0 inclusive
694
- * @param options - Optional span_id and comment
760
+ * @example
761
+ * score({ name: 'factual_accuracy', value: 0.92, traceId });
762
+ * score({ name: 'resolved', value: true, sessionId: 'conv-7', kind: 'outcome' });
695
763
  */
764
+ declare function score(options: ScoreOptions): void;
765
+ /** @deprecated Use `score({ name, value, traceId, spanId, comment })`. */
696
766
  declare function score(traceId: string, name: string, value: number, options?: {
697
767
  spanId?: string;
698
768
  comment?: string;
@@ -814,6 +884,61 @@ declare function session(options: SessionOptions): <TArgs extends unknown[], TR>
814
884
  declare function session<TArgs extends unknown[]>(resolver: (...args: TArgs) => SessionOptions): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
815
885
  declare function session<TArgs extends unknown[]>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions)): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
816
886
 
887
+ /**
888
+ * Identity helpers (W2-2): put the user, the session, the release and tags on the current trace.
889
+ *
890
+ * The Python twin is `risicare/identity.py`. Each helper writes one span attribute that the
891
+ * Risicare spans worker reads into a dashboard column (contract spec W2-2, section 6; ANSWER 91):
892
+ *
893
+ * | Helper | Span attribute | Column |
894
+ * |------------------------|----------------------|---------|
895
+ * | `setUser(id)` | `user.id` | User |
896
+ * | `setSession(id)` | `session.id` | Session |
897
+ * | `setRelease(version)` | `risicare.release` | Release |
898
+ * | `addTags([...])` | `tag.tags` | Tags |
899
+ *
900
+ * Scope. The current span gets the attribute at once. Each other span of the same trace that
901
+ * ends after the call gets it when it ends, unless that span has the attribute already (tags are
902
+ * merged, in order, with no repeats). That includes the spans that are open now (for example the
903
+ * root span) and the spans that start later, in any async context of this process. A span of
904
+ * another trace never gets it, so a value cannot pass from one request to the next.
905
+ *
906
+ * Outside a span there is no trace: the helper sets nothing and returns `false`, and the first
907
+ * such call of each helper writes one WARNING. For a value that must apply before the first span,
908
+ * use `withSession({ sessionId, userId }, fn)` or `init({ serviceVersion })`.
909
+ *
910
+ * The values of at most `MAX_TRACES` traces are kept (the oldest is forgotten first), so memory
911
+ * stays bounded in a long-running process. The registry lives on `globalThis`, so that every
912
+ * entry point bundle uses the same one (see `globals.ts`).
913
+ */
914
+
915
+ /**
916
+ * Set the user of the current trace: the span attribute `user.id` (dashboard column User).
917
+ * Returns `true` when it was set. The worker reads `session.user_id` (from `withSession`) and
918
+ * `user_id` before `user.id`, so a session user wins.
919
+ */
920
+ declare function setUser(userId: string | number): boolean;
921
+ /**
922
+ * Set the session of the current trace: the span attribute `session.id` (column Session).
923
+ * Returns `true` when it was set. The worker reads the typed session of a span (from
924
+ * `withSession`) before `session.id`, so a session context wins.
925
+ */
926
+ declare function setSession(sessionId: string | number): boolean;
927
+ /**
928
+ * Set the release of the current trace: the span attribute `risicare.release` (column Release).
929
+ * Returns `true` when it was set. `risicare.release` is the first source of the Release column;
930
+ * the next one is `service.version`, which `init({ serviceVersion })` (or
931
+ * `RISICARE_SERVICE_VERSION`) puts on every span with no other code.
932
+ */
933
+ declare function setRelease(version: string | number): boolean;
934
+ /**
935
+ * Add tags to the current trace: the span attribute `tag.tags`, an array (column Tags). A later
936
+ * call adds to the tags of the earlier ones, in order, with no repeats. Returns `true` when at
937
+ * least one tag was added. An item that is not a non-empty string is left out, with one WARNING.
938
+ * The worker keeps at most 50 tags for each span and cuts each one at 200 characters.
939
+ */
940
+ declare function addTags(tags: readonly string[]): boolean;
941
+
817
942
  /**
818
943
  * Phase decorators — decision phase tracking (Tier 4).
819
944
  *
@@ -1769,4 +1894,4 @@ type Tracer = Tracer$1;
1769
1894
 
1770
1895
  type Span = Span$1;
1771
1896
 
1772
- export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, GuardRejectedError, type HeaderLookup, MASK_ERROR_MARKER, type MaskFn, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, type Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, type Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, 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, verifyWebhookSignature, withAgent, withPhase, withSession };
1897
+ export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, GuardRejectedError, type HeaderLookup, MASK_ERROR_MARKER, type MaskFn, MessageType, type RisicareConfig, type ScoreKind, type ScoreOptions, SemanticPhase, type SessionContext, type SessionOptions, type Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, type Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, addTags, 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, setRelease, setSession, setUser, shutdown, shutdownFixRuntime, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, verifyWebhookSignature, withAgent, withPhase, withSession };