risicare 0.10.0 → 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 +76 -5
  2. package/README.md +157 -39
  3. package/dist/frameworks/instructor.cjs +338 -117
  4. package/dist/frameworks/instructor.cjs.map +1 -1
  5. package/dist/frameworks/instructor.js +338 -117
  6. package/dist/frameworks/instructor.js.map +1 -1
  7. package/dist/frameworks/langchain.cjs +351 -130
  8. package/dist/frameworks/langchain.cjs.map +1 -1
  9. package/dist/frameworks/langchain.js +351 -130
  10. package/dist/frameworks/langchain.js.map +1 -1
  11. package/dist/frameworks/langgraph.cjs +351 -130
  12. package/dist/frameworks/langgraph.cjs.map +1 -1
  13. package/dist/frameworks/langgraph.js +351 -130
  14. package/dist/frameworks/langgraph.js.map +1 -1
  15. package/dist/frameworks/llamaindex.cjs +351 -130
  16. package/dist/frameworks/llamaindex.cjs.map +1 -1
  17. package/dist/frameworks/llamaindex.js +351 -130
  18. package/dist/frameworks/llamaindex.js.map +1 -1
  19. package/dist/index.cjs +808 -226
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.d.cts +137 -21
  22. package/dist/index.d.ts +137 -21
  23. package/dist/index.js +804 -226
  24. package/dist/index.js.map +1 -1
  25. package/dist/providers/anthropic/index.cjs +351 -130
  26. package/dist/providers/anthropic/index.cjs.map +1 -1
  27. package/dist/providers/anthropic/index.js +351 -130
  28. package/dist/providers/anthropic/index.js.map +1 -1
  29. package/dist/providers/bedrock/index.cjs +346 -125
  30. package/dist/providers/bedrock/index.cjs.map +1 -1
  31. package/dist/providers/bedrock/index.js +346 -125
  32. package/dist/providers/bedrock/index.js.map +1 -1
  33. package/dist/providers/cerebras/index.cjs +351 -130
  34. package/dist/providers/cerebras/index.cjs.map +1 -1
  35. package/dist/providers/cerebras/index.js +351 -130
  36. package/dist/providers/cerebras/index.js.map +1 -1
  37. package/dist/providers/cohere/index.cjs +351 -130
  38. package/dist/providers/cohere/index.cjs.map +1 -1
  39. package/dist/providers/cohere/index.js +351 -130
  40. package/dist/providers/cohere/index.js.map +1 -1
  41. package/dist/providers/google/index.cjs +351 -130
  42. package/dist/providers/google/index.cjs.map +1 -1
  43. package/dist/providers/google/index.js +351 -130
  44. package/dist/providers/google/index.js.map +1 -1
  45. package/dist/providers/groq/index.cjs +351 -130
  46. package/dist/providers/groq/index.cjs.map +1 -1
  47. package/dist/providers/groq/index.js +351 -130
  48. package/dist/providers/groq/index.js.map +1 -1
  49. package/dist/providers/huggingface/index.cjs +351 -130
  50. package/dist/providers/huggingface/index.cjs.map +1 -1
  51. package/dist/providers/huggingface/index.js +351 -130
  52. package/dist/providers/huggingface/index.js.map +1 -1
  53. package/dist/providers/mistral/index.cjs +351 -130
  54. package/dist/providers/mistral/index.cjs.map +1 -1
  55. package/dist/providers/mistral/index.js +351 -130
  56. package/dist/providers/mistral/index.js.map +1 -1
  57. package/dist/providers/ollama/index.cjs +351 -130
  58. package/dist/providers/ollama/index.cjs.map +1 -1
  59. package/dist/providers/ollama/index.js +351 -130
  60. package/dist/providers/ollama/index.js.map +1 -1
  61. package/dist/providers/openai/index.cjs +351 -130
  62. package/dist/providers/openai/index.cjs.map +1 -1
  63. package/dist/providers/openai/index.js +351 -130
  64. package/dist/providers/openai/index.js.map +1 -1
  65. package/dist/providers/together/index.cjs +351 -130
  66. package/dist/providers/together/index.cjs.map +1 -1
  67. package/dist/providers/together/index.js +351 -130
  68. package/dist/providers/together/index.js.map +1 -1
  69. package/dist/providers/vercel-ai/index.cjs +351 -130
  70. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  71. package/dist/providers/vercel-ai/index.js +351 -130
  72. package/dist/providers/vercel-ai/index.js.map +1 -1
  73. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -329,8 +329,26 @@ interface RisicareConfig {
329
329
  batchSize?: number;
330
330
  /** Batch timeout in ms before flush (default: 1000) */
331
331
  batchTimeoutMs?: number;
332
- /** 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
+ */
333
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;
334
352
  /** Enable debug logging (default: false) */
335
353
  debug?: boolean;
336
354
  /** Enable gzip compression for HTTP exports (default: false) */
@@ -495,10 +513,10 @@ declare function init(config?: Partial<RisicareConfig>): void;
495
513
  /**
496
514
  * Gracefully shut down the SDK. Flushes pending spans before resolving.
497
515
  *
498
- * @param timeoutMs - The shutdown budget in milliseconds (default 5000). It is a
499
- * hard wall-clock bound. A value that is not a finite number (NaN, Infinity, a
500
- * string, null) gives 5000. A negative value gives 0. The largest value is
501
- * 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.
502
520
  *
503
521
  * At the deadline, `shutdown()` stops the export in flight. Spans still queued
504
522
  * and spans in the stopped export are counted as `shutdown_residue`, with one
@@ -607,14 +625,18 @@ declare function getMetrics(): {
607
625
  rejectedSpans: number;
608
626
  droppedSpans: number;
609
627
  droppedSpansByReason: {
610
- queue_full: number;
611
628
  transport_refused: number;
629
+ retry_exhausted: number;
612
630
  shutdown_residue: number;
631
+ too_large: number;
632
+ queue_full: number;
613
633
  unacknowledged: number;
614
634
  quota_exceeded: number;
615
635
  };
616
636
  droppedQuota: number;
617
637
  failedExports: number;
638
+ attempts: number;
639
+ oldestPendingAgeS: number;
618
640
  maskErrors: number;
619
641
  queueSize: number;
620
642
  queueCapacity: number;
@@ -622,9 +644,11 @@ declare function getMetrics(): {
622
644
  } | {
623
645
  failedScores: number;
624
646
  droppedSpansByReason: {
625
- queue_full: number;
626
647
  transport_refused: number;
648
+ retry_exhausted: number;
627
649
  shutdown_residue: number;
650
+ too_large: number;
651
+ queue_full: number;
628
652
  unacknowledged: number;
629
653
  quota_exceeded: number;
630
654
  };
@@ -634,6 +658,8 @@ declare function getMetrics(): {
634
658
  droppedSpans: number;
635
659
  droppedQuota: number;
636
660
  failedExports: number;
661
+ attempts: number;
662
+ oldestPendingAgeS: number;
637
663
  maskErrors: number;
638
664
  queueSize: number;
639
665
  queueCapacity: number;
@@ -649,9 +675,13 @@ declare function getMetrics(): {
649
675
  shutdown_residue: number;
650
676
  unacknowledged: number;
651
677
  quota_exceeded: number;
678
+ retry_exhausted: number;
679
+ too_large: number;
652
680
  };
653
681
  droppedQuota: number;
654
682
  failedExports: number;
683
+ attempts: number;
684
+ oldestPendingAgeS: number;
655
685
  queueSize: number;
656
686
  queueCapacity: number;
657
687
  queueUtilization: number;
@@ -671,8 +701,37 @@ declare function reportError(error: unknown, options?: {
671
701
  name?: string;
672
702
  attributes?: Record<string, unknown>;
673
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
+ }
674
723
  /**
675
- * 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.
676
735
  *
677
736
  * Sends the score in the background. The root `flush()` waits for it.
678
737
  * This function never throws and does not block. At most 50 score requests
@@ -687,21 +746,23 @@ declare function reportError(error: unknown, options?: {
687
746
  * the score name and the status or the error code. Later failures in the next
688
747
  * 10 s are counted, and the next WARNING gives their number. Root `flush()`
689
748
  * waits for pending scores inside its deadline, and returns `false` when a
690
- * score failed since the previous `flush()` returned. An out-of-range value, a
691
- * value that is not a number, or an empty `traceId` or `name` writes one WARNING,
692
- * and the SDK does not send the score. It counts as a failed score, so the next
693
- * `flush()` is false (not when the SDK is not active: then nothing is counted).
694
- * `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).
695
754
  *
696
- * If a `mask` is configured on `init()`, `options.comment` is passed to it under
697
- * the key `score.comment` before the request is built. `traceId`, `spanId` and
698
- * `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.
699
759
  *
700
- * @param traceId - The trace to score
701
- * @param name - Score name (e.g., "accuracy", "user_satisfaction")
702
- * @param value - Score value between 0.0 and 1.0 inclusive
703
- * @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' });
704
763
  */
764
+ declare function score(options: ScoreOptions): void;
765
+ /** @deprecated Use `score({ name, value, traceId, spanId, comment })`. */
705
766
  declare function score(traceId: string, name: string, value: number, options?: {
706
767
  spanId?: string;
707
768
  comment?: string;
@@ -823,6 +884,61 @@ declare function session(options: SessionOptions): <TArgs extends unknown[], TR>
823
884
  declare function session<TArgs extends unknown[]>(resolver: (...args: TArgs) => SessionOptions): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
824
885
  declare function session<TArgs extends unknown[]>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions)): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
825
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
+
826
942
  /**
827
943
  * Phase decorators — decision phase tracking (Tier 4).
828
944
  *
@@ -1778,4 +1894,4 @@ type Tracer = Tracer$1;
1778
1894
 
1779
1895
  type Span = Span$1;
1780
1896
 
1781
- 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
@@ -329,8 +329,26 @@ interface RisicareConfig {
329
329
  batchSize?: number;
330
330
  /** Batch timeout in ms before flush (default: 1000) */
331
331
  batchTimeoutMs?: number;
332
- /** 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
+ */
333
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;
334
352
  /** Enable debug logging (default: false) */
335
353
  debug?: boolean;
336
354
  /** Enable gzip compression for HTTP exports (default: false) */
@@ -495,10 +513,10 @@ declare function init(config?: Partial<RisicareConfig>): void;
495
513
  /**
496
514
  * Gracefully shut down the SDK. Flushes pending spans before resolving.
497
515
  *
498
- * @param timeoutMs - The shutdown budget in milliseconds (default 5000). It is a
499
- * hard wall-clock bound. A value that is not a finite number (NaN, Infinity, a
500
- * string, null) gives 5000. A negative value gives 0. The largest value is
501
- * 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.
502
520
  *
503
521
  * At the deadline, `shutdown()` stops the export in flight. Spans still queued
504
522
  * and spans in the stopped export are counted as `shutdown_residue`, with one
@@ -607,14 +625,18 @@ declare function getMetrics(): {
607
625
  rejectedSpans: number;
608
626
  droppedSpans: number;
609
627
  droppedSpansByReason: {
610
- queue_full: number;
611
628
  transport_refused: number;
629
+ retry_exhausted: number;
612
630
  shutdown_residue: number;
631
+ too_large: number;
632
+ queue_full: number;
613
633
  unacknowledged: number;
614
634
  quota_exceeded: number;
615
635
  };
616
636
  droppedQuota: number;
617
637
  failedExports: number;
638
+ attempts: number;
639
+ oldestPendingAgeS: number;
618
640
  maskErrors: number;
619
641
  queueSize: number;
620
642
  queueCapacity: number;
@@ -622,9 +644,11 @@ declare function getMetrics(): {
622
644
  } | {
623
645
  failedScores: number;
624
646
  droppedSpansByReason: {
625
- queue_full: number;
626
647
  transport_refused: number;
648
+ retry_exhausted: number;
627
649
  shutdown_residue: number;
650
+ too_large: number;
651
+ queue_full: number;
628
652
  unacknowledged: number;
629
653
  quota_exceeded: number;
630
654
  };
@@ -634,6 +658,8 @@ declare function getMetrics(): {
634
658
  droppedSpans: number;
635
659
  droppedQuota: number;
636
660
  failedExports: number;
661
+ attempts: number;
662
+ oldestPendingAgeS: number;
637
663
  maskErrors: number;
638
664
  queueSize: number;
639
665
  queueCapacity: number;
@@ -649,9 +675,13 @@ declare function getMetrics(): {
649
675
  shutdown_residue: number;
650
676
  unacknowledged: number;
651
677
  quota_exceeded: number;
678
+ retry_exhausted: number;
679
+ too_large: number;
652
680
  };
653
681
  droppedQuota: number;
654
682
  failedExports: number;
683
+ attempts: number;
684
+ oldestPendingAgeS: number;
655
685
  queueSize: number;
656
686
  queueCapacity: number;
657
687
  queueUtilization: number;
@@ -671,8 +701,37 @@ declare function reportError(error: unknown, options?: {
671
701
  name?: string;
672
702
  attributes?: Record<string, unknown>;
673
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
+ }
674
723
  /**
675
- * 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.
676
735
  *
677
736
  * Sends the score in the background. The root `flush()` waits for it.
678
737
  * This function never throws and does not block. At most 50 score requests
@@ -687,21 +746,23 @@ declare function reportError(error: unknown, options?: {
687
746
  * the score name and the status or the error code. Later failures in the next
688
747
  * 10 s are counted, and the next WARNING gives their number. Root `flush()`
689
748
  * waits for pending scores inside its deadline, and returns `false` when a
690
- * score failed since the previous `flush()` returned. An out-of-range value, a
691
- * value that is not a number, or an empty `traceId` or `name` writes one WARNING,
692
- * and the SDK does not send the score. It counts as a failed score, so the next
693
- * `flush()` is false (not when the SDK is not active: then nothing is counted).
694
- * `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).
695
754
  *
696
- * If a `mask` is configured on `init()`, `options.comment` is passed to it under
697
- * the key `score.comment` before the request is built. `traceId`, `spanId` and
698
- * `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.
699
759
  *
700
- * @param traceId - The trace to score
701
- * @param name - Score name (e.g., "accuracy", "user_satisfaction")
702
- * @param value - Score value between 0.0 and 1.0 inclusive
703
- * @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' });
704
763
  */
764
+ declare function score(options: ScoreOptions): void;
765
+ /** @deprecated Use `score({ name, value, traceId, spanId, comment })`. */
705
766
  declare function score(traceId: string, name: string, value: number, options?: {
706
767
  spanId?: string;
707
768
  comment?: string;
@@ -823,6 +884,61 @@ declare function session(options: SessionOptions): <TArgs extends unknown[], TR>
823
884
  declare function session<TArgs extends unknown[]>(resolver: (...args: TArgs) => SessionOptions): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
824
885
  declare function session<TArgs extends unknown[]>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions)): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
825
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
+
826
942
  /**
827
943
  * Phase decorators — decision phase tracking (Tier 4).
828
944
  *
@@ -1778,4 +1894,4 @@ type Tracer = Tracer$1;
1778
1894
 
1779
1895
  type Span = Span$1;
1780
1896
 
1781
- 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 };