risicare 0.7.0 → 0.8.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 (84) hide show
  1. package/README.md +282 -63
  2. package/dist/frameworks/instructor.cjs +790 -5
  3. package/dist/frameworks/instructor.cjs.map +1 -1
  4. package/dist/frameworks/instructor.js +780 -5
  5. package/dist/frameworks/instructor.js.map +1 -1
  6. package/dist/frameworks/langchain.cjs +790 -5
  7. package/dist/frameworks/langchain.cjs.map +1 -1
  8. package/dist/frameworks/langchain.d.cts +3 -2
  9. package/dist/frameworks/langchain.d.ts +3 -2
  10. package/dist/frameworks/langchain.js +780 -5
  11. package/dist/frameworks/langchain.js.map +1 -1
  12. package/dist/frameworks/langgraph.cjs +790 -5
  13. package/dist/frameworks/langgraph.cjs.map +1 -1
  14. package/dist/frameworks/langgraph.js +780 -5
  15. package/dist/frameworks/langgraph.js.map +1 -1
  16. package/dist/frameworks/llamaindex.cjs +801 -5
  17. package/dist/frameworks/llamaindex.cjs.map +1 -1
  18. package/dist/frameworks/llamaindex.d.cts +3 -2
  19. package/dist/frameworks/llamaindex.d.ts +3 -2
  20. package/dist/frameworks/llamaindex.js +791 -5
  21. package/dist/frameworks/llamaindex.js.map +1 -1
  22. package/dist/index.cjs +1113 -176
  23. package/dist/index.cjs.map +1 -1
  24. package/dist/index.d.cts +234 -42
  25. package/dist/index.d.ts +234 -42
  26. package/dist/index.js +1113 -176
  27. package/dist/index.js.map +1 -1
  28. package/dist/providers/anthropic/index.cjs +1601 -36
  29. package/dist/providers/anthropic/index.cjs.map +1 -1
  30. package/dist/providers/anthropic/index.d.cts +3 -1
  31. package/dist/providers/anthropic/index.d.ts +3 -1
  32. package/dist/providers/anthropic/index.js +1591 -36
  33. package/dist/providers/anthropic/index.js.map +1 -1
  34. package/dist/providers/bedrock/index.cjs +850 -32
  35. package/dist/providers/bedrock/index.cjs.map +1 -1
  36. package/dist/providers/bedrock/index.js +840 -32
  37. package/dist/providers/bedrock/index.js.map +1 -1
  38. package/dist/providers/cerebras/index.cjs +1534 -30
  39. package/dist/providers/cerebras/index.cjs.map +1 -1
  40. package/dist/providers/cerebras/index.js +1524 -30
  41. package/dist/providers/cerebras/index.js.map +1 -1
  42. package/dist/providers/cohere/index.cjs +1557 -102
  43. package/dist/providers/cohere/index.cjs.map +1 -1
  44. package/dist/providers/cohere/index.js +1547 -102
  45. package/dist/providers/cohere/index.js.map +1 -1
  46. package/dist/providers/google/index.cjs +1562 -60
  47. package/dist/providers/google/index.cjs.map +1 -1
  48. package/dist/providers/google/index.js +1552 -60
  49. package/dist/providers/google/index.js.map +1 -1
  50. package/dist/providers/groq/index.cjs +1534 -30
  51. package/dist/providers/groq/index.cjs.map +1 -1
  52. package/dist/providers/groq/index.js +1524 -30
  53. package/dist/providers/groq/index.js.map +1 -1
  54. package/dist/providers/huggingface/index.cjs +1622 -25
  55. package/dist/providers/huggingface/index.cjs.map +1 -1
  56. package/dist/providers/huggingface/index.d.cts +0 -9
  57. package/dist/providers/huggingface/index.d.ts +0 -9
  58. package/dist/providers/huggingface/index.js +1612 -25
  59. package/dist/providers/huggingface/index.js.map +1 -1
  60. package/dist/providers/mistral/index.cjs +1535 -54
  61. package/dist/providers/mistral/index.cjs.map +1 -1
  62. package/dist/providers/mistral/index.js +1525 -54
  63. package/dist/providers/mistral/index.js.map +1 -1
  64. package/dist/providers/ollama/index.cjs +1559 -93
  65. package/dist/providers/ollama/index.cjs.map +1 -1
  66. package/dist/providers/ollama/index.js +1549 -93
  67. package/dist/providers/ollama/index.js.map +1 -1
  68. package/dist/providers/openai/index.cjs +1598 -61
  69. package/dist/providers/openai/index.cjs.map +1 -1
  70. package/dist/providers/openai/index.d.cts +6 -1
  71. package/dist/providers/openai/index.d.ts +6 -1
  72. package/dist/providers/openai/index.js +1588 -61
  73. package/dist/providers/openai/index.js.map +1 -1
  74. package/dist/providers/together/index.cjs +1534 -30
  75. package/dist/providers/together/index.cjs.map +1 -1
  76. package/dist/providers/together/index.js +1524 -30
  77. package/dist/providers/together/index.js.map +1 -1
  78. package/dist/providers/vercel-ai/index.cjs +1288 -17
  79. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  80. package/dist/providers/vercel-ai/index.d.cts +0 -6
  81. package/dist/providers/vercel-ai/index.d.ts +0 -6
  82. package/dist/providers/vercel-ai/index.js +1278 -17
  83. package/dist/providers/vercel-ai/index.js.map +1 -1
  84. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -139,8 +139,8 @@ interface SpanOptions {
139
139
  agentType?: string;
140
140
  semanticPhase?: string;
141
141
  }
142
- type SpanEndCallback = (span: Span) => void;
143
- declare class Span {
142
+ type SpanEndCallback = (span: Span$1) => void;
143
+ declare class Span$1 {
144
144
  readonly traceId: string;
145
145
  readonly spanId: string;
146
146
  readonly parentSpanId: string | undefined;
@@ -277,9 +277,16 @@ interface RisicareConfig {
277
277
  /** Ingest gateway URL. It receives spans only. */
278
278
  endpoint?: string;
279
279
  /**
280
- * Api URL. It serves active-fix reads and scores.
281
- * Falls back to `endpoint` when only that one is given, so a single-host
282
- * deployment keeps every URL shape on the one host.
280
+ * Api URL. It serves active-fix reads and scores. The order is:
281
+ * 1. this option;
282
+ * 2. the `endpoint` option, when it is given and it is not the default ingest host;
283
+ * 3. `RISICARE_API_ENDPOINT`;
284
+ * 4. `RISICARE_ENDPOINT`, when no `endpoint` option is given and it is not the
285
+ * default ingest host;
286
+ * 5. the default api host.
287
+ * The default ingest host (`https://ingest.risicare.ai`) never names an api
288
+ * host. `RISICARE_ENDPOINT` alone keeps every URL shape on that one host. Each
289
+ * value is trimmed of ASCII whitespace, and an empty value is not given.
283
290
  */
284
291
  apiEndpoint?: string;
285
292
  /**
@@ -307,7 +314,7 @@ interface RisicareConfig {
307
314
  traceContent?: boolean;
308
315
  /** Sample rate 0.0–1.0 (default: 1.0 = trace all) */
309
316
  sampleRate?: number;
310
- /** Batch size threshold before flush (default: 100) */
317
+ /** Batch size threshold before flush (default: 500) */
311
318
  batchSize?: number;
312
319
  /** Batch timeout in ms before flush (default: 1000) */
313
320
  batchTimeoutMs?: number;
@@ -321,8 +328,12 @@ interface RisicareConfig {
321
328
  * Whether FixRuntime starts (or `RISICARE_FIX_RUNTIME=true`).
322
329
  *
323
330
  * **Default `false` since 0.7.0** (it started whenever an `apiKey` was set).
324
- * When true, the SDK polls `/fixes/active` every 60 s and applies the active
325
- * fixes to LLM calls. When false, nothing polls and nothing is applied.
331
+ * During the beta, the Risicare service does not give fixes to customer
332
+ * projects, so FixRuntime has no effect for them. When true, the SDK polls
333
+ * `/fixes/active` every 60 s. The interceptor then enforces guard fixes on
334
+ * the paths that call it, and a failed guard throws `GuardRejectedError`.
335
+ * The provider path does not apply prompt, parameter or fallback fixes.
336
+ * When false, nothing polls and nothing is applied.
326
337
  */
327
338
  fixRuntime?: boolean;
328
339
  /** Custom metadata attached to all spans */
@@ -414,7 +425,7 @@ interface TracerConfig {
414
425
  */
415
426
  serviceVersion?: string;
416
427
  }
417
- declare class Tracer {
428
+ declare class Tracer$1 {
418
429
  private _onSpanEnd;
419
430
  private _sampleRate;
420
431
  private _enabled;
@@ -437,14 +448,14 @@ declare class Tracer {
437
448
  *
438
449
  * @returns The callback's return value
439
450
  */
440
- startSpan<T>(options: StartSpanOptions | string, fn: (span: Span) => T): T;
451
+ startSpan<T>(options: StartSpanOptions | string, fn: (span: Span$1) => T): T;
441
452
  /**
442
453
  * Create a span without auto-ending. Caller is responsible for calling span.end().
443
454
  *
444
455
  * Useful for long-running operations where you need manual control.
445
456
  * The span is still linked to context and enriched with session/agent/phase.
446
457
  */
447
- createSpan(options: StartSpanOptions | string): Span;
458
+ createSpan(options: StartSpanOptions | string): Span$1;
448
459
  }
449
460
 
450
461
  /**
@@ -470,20 +481,57 @@ declare class Tracer {
470
481
  declare function init(config?: Partial<RisicareConfig>): void;
471
482
  /**
472
483
  * Gracefully shut down the SDK. Flushes pending spans before resolving.
484
+ *
485
+ * @param timeoutMs - The shutdown budget in milliseconds (default 5000). It is a
486
+ * hard wall-clock bound. A value that is not a finite number (NaN, Infinity, a
487
+ * string, null) gives 5000. A negative value gives 0. The largest value is
488
+ * 2**31 - 1.
489
+ *
490
+ * At the deadline, `shutdown()` stops the export in flight. Spans still queued
491
+ * and spans in the stopped export are counted as `shutdown_residue`, with one
492
+ * WARNING: they were not confirmed as delivered. The server may have received
493
+ * the spans of the stopped export. Each exporter's own `shutdown()` gets only
494
+ * the time that is left of the budget.
495
+ *
496
+ * Limit: the stop does not end a TLS handshake that stalls. Such a handshake
497
+ * can keep the process alive about 10 s after `shutdown()` returns.
473
498
  */
474
- declare function shutdown(): Promise<void>;
499
+ declare function shutdown(timeoutMs?: number): Promise<void>;
475
500
  /**
476
501
  * Flush all pending spans without shutting down.
477
502
  *
478
- * @returns `true` only if everything queued at entry was DELIVERED — `false`
479
- * if the deadline expired with spans still queued, or if any span was
480
- * discarded during the window (F-SDKCB-001 §6). An uninitialised SDK returns
481
- * `true`: it was handed nothing, and it lost nothing.
503
+ * @param timeoutMs - The budget in milliseconds (default 5000). It is a hard
504
+ * wall-clock bound on the wait: at the deadline `flush()` resolves `false`.
505
+ * A value that is not a finite number (NaN, Infinity, a string, null) gives
506
+ * 5000. A negative value gives 0. The largest value is 2**31 - 1.
507
+ * @returns `true` only if everything queued at entry was DELIVERED and no span
508
+ * was lost since the previous `flush()` returned. A loss is reported by the next
509
+ * `flush()`, one time. It returns `false` in these cases:
510
+ * - the deadline expired with spans still queued or in flight;
511
+ * - a span was discarded since the previous flush returned (F-SDKCB-001 §6);
512
+ * - the backend rejected a span since the previous flush returned, or its ack
513
+ * did not account for a span;
514
+ * - it is called after a `shutdown()` that left spans undelivered
515
+ * (`shutdown_residue`).
516
+ * An uninitialised SDK returns `true`: it was handed nothing, and it lost nothing.
517
+ *
518
+ * `flush()` never stops a request that is already sent. At the deadline it stops
519
+ * waiting; the export in flight continues and ends by its own rules.
520
+ *
521
+ * Limit: that export can keep the process alive after `flush()` returns `false`,
522
+ * until its own timeouts end (measured on a silent server: 22 s). To end a
523
+ * process within a bound, call `await shutdown(timeoutMs)`. It stops the export
524
+ * in flight.
525
+ *
526
+ * Scores: `flush()` also waits, inside the same deadline, for each `score()`
527
+ * request that is not complete. It returns `false` when a score is not complete
528
+ * at the deadline, or when a score failed since the previous `flush()` returned.
529
+ * Each failed score makes one flush `false`, as each lost span does.
482
530
  *
483
531
  * ⚠ Signature change in 0.5.0 — was `Promise<void>`. Existing callers that
484
532
  * ignore the result keep working unchanged.
485
533
  */
486
- declare function flush(): Promise<boolean>;
534
+ declare function flush(timeoutMs?: number): Promise<boolean>;
487
535
  /**
488
536
  * Enable tracing at runtime.
489
537
  */
@@ -499,13 +547,16 @@ declare function isEnabled(): boolean;
499
547
  /**
500
548
  * Get the global tracer instance. Returns undefined if not initialized.
501
549
  */
502
- declare function getTracer(): Tracer | undefined;
550
+ declare function getTracer(): Tracer$1 | undefined;
503
551
  /**
504
552
  * Check whether content tracing (prompt/completion capture) is enabled.
505
553
  */
506
554
  declare function getTraceContent(): boolean;
507
555
  /**
508
- * Get SDK metrics: exported spans, dropped spans, failed exports, queue stats.
556
+ * Get SDK metrics: exported spans (accepted by the backend), `rejectedSpans`,
557
+ * dropped spans and their reasons (`unacknowledged` included), failed exports,
558
+ * queue stats, and `failedScores` (`score()` requests that failed since
559
+ * `init()`).
509
560
  *
510
561
  * `sdkState` — SDK-RELEASE-RULING.md §5 — says WHICH of three different facts
511
562
  * the numbers are, because before it all three rendered as the same zeros:
@@ -529,13 +580,16 @@ declare function getTraceContent(): boolean;
529
580
  * and the WARNING together. The WARNING remains the primary signal.
530
581
  */
531
582
  declare function getMetrics(): {
583
+ failedScores: number;
532
584
  sdkState: "running";
533
585
  exportedSpans: number;
586
+ rejectedSpans: number;
534
587
  droppedSpans: number;
535
588
  droppedSpansByReason: {
536
589
  queue_full: number;
537
590
  transport_refused: number;
538
591
  shutdown_residue: number;
592
+ unacknowledged: number;
539
593
  };
540
594
  failedExports: number;
541
595
  maskErrors: number;
@@ -543,13 +597,16 @@ declare function getMetrics(): {
543
597
  queueCapacity: number;
544
598
  queueUtilization: number;
545
599
  } | {
600
+ failedScores: number;
546
601
  droppedSpansByReason: {
547
602
  queue_full: number;
548
603
  transport_refused: number;
549
604
  shutdown_residue: number;
605
+ unacknowledged: number;
550
606
  };
551
607
  sdkState: "shutdown";
552
608
  exportedSpans: number;
609
+ rejectedSpans: number;
553
610
  droppedSpans: number;
554
611
  failedExports: number;
555
612
  maskErrors: number;
@@ -558,11 +615,14 @@ declare function getMetrics(): {
558
615
  queueUtilization: number;
559
616
  } | {
560
617
  exportedSpans: number;
618
+ rejectedSpans: number;
619
+ failedScores: number;
561
620
  droppedSpans: number;
562
621
  droppedSpansByReason: {
563
622
  queue_full: number;
564
623
  transport_refused: number;
565
624
  shutdown_residue: number;
625
+ unacknowledged: number;
566
626
  };
567
627
  failedExports: number;
568
628
  queueSize: number;
@@ -587,8 +647,22 @@ declare function reportError(error: unknown, options?: {
587
647
  /**
588
648
  * Record a custom evaluation score on a trace.
589
649
  *
590
- * Sends the score to the server in a fire-and-forget fashion.
591
- * This function never throws and is non-blocking.
650
+ * Sends the score in the background. The root `flush()` waits for it.
651
+ * This function never throws and does not block. At most 50 score requests
652
+ * are in flight at once. Up to 1,000 scores wait for a free slot, with no timer;
653
+ * the 2000 ms bound of a score starts when its request starts. A score that
654
+ * comes when 1,000 already wait fails at once and is counted. When a `flush()`
655
+ * or `shutdown()` bound ends, the scores that still wait fail and are not sent.
656
+ *
657
+ * Delivery: the request stops after 2000 ms and never follows a redirect. A
658
+ * status of 300 or more, an error or the timeout is a failure, and it adds 1
659
+ * to `failedScores` in `getMetrics()`. The first failure writes a WARNING with
660
+ * the score name and the status or the error code. Later failures in the next
661
+ * 10 s are counted, and the next WARNING gives their number. Root `flush()`
662
+ * waits for pending scores inside its deadline, and returns `false` when a
663
+ * score failed since the previous `flush()` returned. An out-of-range value, or an empty `traceId`
664
+ * or `name`, writes one WARNING, and the SDK does not send the score. `true`
665
+ * and `false` count as 1 and 0.
592
666
  *
593
667
  * If a `mask` is configured on `init()`, `options.comment` is passed to it under
594
668
  * the key `score.comment` before the request is built. `traceId`, `spanId` and
@@ -693,6 +767,14 @@ declare function withSession<T>(options: SessionOptions, fn: () => T): T;
693
767
  * );
694
768
  */
695
769
 
770
+ /**
771
+ * Blocks inference from the resolver, so that the target function alone
772
+ * decides `TArgs` (F-020). The resolver may declare fewer parameters than the
773
+ * target, as the documented `(sessionId, userId) => ...` resolver does.
774
+ * Written without the built-in `NoInfer` (TypeScript 5.4+) because the
775
+ * package supports TypeScript 5.0.
776
+ */
777
+ type NoInferArgs<T> = [T][T extends unknown ? 0 : never];
696
778
  /**
697
779
  * Wrap a function with session context.
698
780
  *
@@ -707,14 +789,18 @@ declare function withSession<T>(options: SessionOptions, fn: () => T): T;
707
789
  * @param optionsOrResolver - Static session options, or a function that derives them from args
708
790
  * @param fn - The function to wrap. If omitted, returns a decorator factory.
709
791
  */
710
- declare function session<TArgs extends unknown[], TReturn>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions), fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
792
+ declare function session<TArgs extends unknown[], TReturn>(optionsOrResolver: SessionOptions | ((...args: NoInferArgs<TArgs>) => SessionOptions), fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
793
+ declare function session(options: SessionOptions): <TArgs extends unknown[], TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
794
+ declare function session<TArgs extends unknown[]>(resolver: (...args: TArgs) => SessionOptions): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
711
795
  declare function session<TArgs extends unknown[]>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions)): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
712
796
 
713
797
  /**
714
798
  * Phase decorators — decision phase tracking (Tier 4).
715
799
  *
716
800
  * Wraps functions to execute within a semantic phase context (THINK/DECIDE/ACT/OBSERVE).
717
- * Each creates a span named after the phase.
801
+ * Each creates a span. The named form uses the given name. The bare form uses
802
+ * `<phase>:<function name>` (for example `think:analyzeQuery`), as the Python
803
+ * SDK does; an anonymous function gives `phase:<phase>` (for example `phase:think`).
718
804
  *
719
805
  * @example
720
806
  * const analyze = traceThink(async (data: string) => {
@@ -832,16 +918,48 @@ interface AgentContext {
832
918
  }
833
919
  declare function getCurrentSession(): SessionContext | undefined;
834
920
  declare function getCurrentAgent(): AgentContext | undefined;
835
- declare function getCurrentSpan(): Span | undefined;
921
+ declare function getCurrentSpan(): Span$1 | undefined;
836
922
  declare function getCurrentPhase(): SemanticPhase | undefined;
837
923
  declare function getCurrentSessionId(): string | undefined;
838
924
  declare function getCurrentAgentId(): string | undefined;
839
925
  declare function getCurrentTraceId(): string | undefined;
840
926
  declare function getCurrentSpanId(): string | undefined;
927
+ /**
928
+ * A plain-object snapshot of the current context, as `getCurrentContext()`
929
+ * returns it. `session`, `agent` and `span` are `null` when not set.
930
+ *
931
+ * This is a type alias, not an interface, so that a value of this type is
932
+ * still assignable to `Record<string, unknown>` (the return type through 0.7.1).
933
+ * `getCurrentContext()` returns it joined with `Record<string, unknown>`, so
934
+ * code that writes or reads other keys still compiles.
935
+ */
936
+ type ContextSnapshot = {
937
+ session: {
938
+ sessionId: string;
939
+ userId?: string;
940
+ parentSessionId?: string;
941
+ turnNumber?: number;
942
+ metadata?: Record<string, unknown>;
943
+ } | null;
944
+ agent: {
945
+ agentId: string;
946
+ agentName?: string;
947
+ agentRole?: string;
948
+ agentType?: string;
949
+ parentAgentId?: string;
950
+ version?: number;
951
+ metadata?: Record<string, unknown>;
952
+ } | null;
953
+ span: {
954
+ spanId: string;
955
+ traceId: string;
956
+ } | null;
957
+ phase: SemanticPhase | null;
958
+ };
841
959
  /**
842
960
  * Get all current context as a plain object (for debugging/serialization).
843
961
  */
844
- declare function getCurrentContext(): Record<string, unknown>;
962
+ declare function getCurrentContext(): ContextSnapshot & Record<string, unknown>;
845
963
 
846
964
  /**
847
965
  * Serializable trace context + W3C Trace Context headers.
@@ -863,9 +981,15 @@ interface TraceContext {
863
981
  * Get the current trace context as a serializable object.
864
982
  *
865
983
  * When called inside a span context, returns the active span's IDs.
866
- * When called outside a span (e.g. inside session() but before agent()),
867
- * pre-allocates a trace ID and stores it in context so the next
868
- * startSpan() call inherits it — preventing trace ID mismatch.
984
+ * When called outside a span but inside a context scope (for example inside
985
+ * `withSession()`, `withAgent()` or `withPhase()`), pre-allocates a trace ID
986
+ * and stores it in that scope. The ID stays in the scope. EVERY later root
987
+ * span in that scope uses it: the next span, each span after it, and spans
988
+ * that start at the same time (for example in `Promise.all`). So all root
989
+ * spans of the scope are in one trace. Later calls return the same ID.
990
+ *
991
+ * Outside every context scope there is no place to store the ID: each call
992
+ * returns a new trace ID, and the next span does not use it.
869
993
  */
870
994
  declare function getTraceContext(): TraceContext;
871
995
  /**
@@ -874,8 +998,12 @@ declare function getTraceContext(): TraceContext;
874
998
  declare function injectTraceContext(headers: Record<string, string>): Record<string, string>;
875
999
  /**
876
1000
  * Extract trace context from HTTP headers (W3C format).
1001
+ *
1002
+ * Accepts a plain string record or Node's `IncomingHttpHeaders`
1003
+ * (`req.headers`). For a header with several values (`string[]`) the first
1004
+ * value is used. An `undefined` value is ignored.
877
1005
  */
878
- declare function extractTraceContext(headers: Record<string, string>): Record<string, string | undefined>;
1006
+ declare function extractTraceContext(headers: Record<string, string | string[] | undefined>): Record<string, string | undefined>;
879
1007
 
880
1008
  /**
881
1009
  * Span registry — TTL-based span store for edge cases.
@@ -887,8 +1015,8 @@ declare function extractTraceContext(headers: Record<string, string>): Record<st
887
1015
  * - Long-running operations that outlive their original context
888
1016
  */
889
1017
 
890
- declare function registerSpan(span: Span, ttlMs?: number): void;
891
- declare function getSpanById(spanId: string): Span | undefined;
1018
+ declare function registerSpan(span: Span$1, ttlMs?: number): void;
1019
+ declare function getSpanById(spanId: string): Span$1 | undefined;
892
1020
  declare function unregisterSpan(spanId: string): void;
893
1021
 
894
1022
  /**
@@ -897,8 +1025,9 @@ declare function unregisterSpan(spanId: string): void;
897
1025
  * Creates a span that starts when iteration begins and ends when
898
1026
  * iteration completes (or errors). Chunks pass through UNCHANGED.
899
1027
  *
900
- * This is the user-level streaming utility. For provider-level streaming
901
- * enrichment (token counts, cost), see individual provider instrumentors.
1028
+ * This is the user-level streaming utility. The OpenAI, Anthropic, Groq,
1029
+ * Cerebras and Together patches do not read a stream; the Google, Cohere,
1030
+ * Mistral and Ollama patches do (see each provider's patch).
902
1031
  *
903
1032
  * Usage:
904
1033
  * const stream = await openai.chat.completions.create({ stream: true, ... });
@@ -1144,6 +1273,26 @@ declare class FixApplier {
1144
1273
  * - content_filter: Regex-based blocked patterns
1145
1274
  * - format_check: JSON.parse() validity
1146
1275
  * - input_validation / output_validation: min/max length
1276
+ *
1277
+ * `content_filter` searches the content for each entry of `blocked_patterns`
1278
+ * (case-insensitive, after `translatePythonPattern`). It fails CLOSED: when
1279
+ * `blocked_patterns` is not a list, or an entry is empty, is not a string,
1280
+ * is longer than 500 characters or cannot be used, the guard does not pass.
1281
+ * One WARNING names the fix id and the pattern index, once for each pair in
1282
+ * the process. The reason names the pattern index, never the pattern or the
1283
+ * content.
1284
+ *
1285
+ * Limits:
1286
+ * - The interceptor runs only on the OpenAI chat patch (input guards) and on
1287
+ * `interceptCall` / `interceptResponse`. It does not run when a framework
1288
+ * integration suppresses provider instrumentation.
1289
+ * - Each SDK uses its own regular-expression engine. These constructs can
1290
+ * give a different result in JavaScript and Python: `$` before a final
1291
+ * newline, Unicode case folding, `\d` and `\w` on non-ASCII text,
1292
+ * `\N{...}` and `\U........` (JavaScript fails closed), and a `]` first
1293
+ * in a class.
1294
+ * - A pattern has no time bound. A pattern with nested repeats can take a
1295
+ * very long time on a long input.
1147
1296
  */
1148
1297
  applyGuardFix(fix: ActiveFix, content: string, isInput?: boolean): {
1149
1298
  content: string;
@@ -1157,6 +1306,11 @@ declare class FixApplier {
1157
1306
  /**
1158
1307
  * Safely compile a regex pattern from untrusted input.
1159
1308
  * Returns null if invalid or too long.
1309
+ *
1310
+ * F-029: the fix patterns are written for Python `re`. Before it compiles
1311
+ * the pattern, this function translates the Python forms that have an exact
1312
+ * JavaScript equivalent (see `translatePythonPattern`). The `i` flag is
1313
+ * always on, as in the Python applier.
1160
1314
  */
1161
1315
  private _safeCompileRegex;
1162
1316
  /** Prepend content to the first message matching the target role. */
@@ -1191,9 +1345,18 @@ declare class FixLoader {
1191
1345
  private _consecutiveFailures;
1192
1346
  private _circuitOpenUntil;
1193
1347
  private _onLoadCallbacks;
1348
+ private _lastStatus;
1194
1349
  private static readonly CIRCUIT_BREAKER_THRESHOLD;
1195
1350
  private static readonly CIRCUIT_BREAKER_COOLDOWN_MS;
1196
1351
  constructor(config: FixRuntimeConfig, cache: FixCache);
1352
+ /** Error text for a log line: one line, the api endpoint as `safeUrl` gives it, no key. */
1353
+ private _scrub;
1354
+ /**
1355
+ * The WARNING for a failed first load: the request URL with no userinfo, no
1356
+ * query and no key, the HTTP status or the error class, and that tracing is
1357
+ * not affected. Never the error text: it can echo the URL with its query.
1358
+ */
1359
+ private _firstLoadWarning;
1197
1360
  /** Timestamp of last successful load. */
1198
1361
  get lastLoadTime(): number | null;
1199
1362
  /**
@@ -1226,9 +1389,16 @@ declare class FixLoader {
1226
1389
  /**
1227
1390
  * Fix Interceptors — Hook into LLM/tool calls to apply fixes.
1228
1391
  *
1229
- * Interceptors are registered with the runtime and called during agent
1230
- * execution to apply relevant fixes at three interception points:
1231
- * - preCall: Before the LLM/tool call (prompt/parameter/fallback fixes)
1392
+ * FixRuntime is off by default. During the beta, the Risicare service does not
1393
+ * give fixes to customer projects, so FixRuntime has no effect for them.
1394
+ *
1395
+ * The interceptor enforces guard fixes only on the paths that call it:
1396
+ * `interceptCall` and `interceptResponse` on `FixRuntime`, and the OpenAI chat
1397
+ * patch (input guards only). Three interception points:
1398
+ * - preCall: Before the LLM/tool call. Input guards always; prompt,
1399
+ * parameter and fallback fixes only when the context has an
1400
+ * `errorCode`. The provider path supplies none, so it does not
1401
+ * apply them.
1232
1402
  * - postCall: After the call (output guard validation)
1233
1403
  * - onError: When an error occurs (retry/fallback decisions)
1234
1404
  *
@@ -1244,10 +1414,10 @@ declare class FixLoader {
1244
1414
  * LLM with the attacker payload anyway. The `fail-CLOSED` was advisory only.
1245
1415
  *
1246
1416
  * Now the interceptor THROWS this error on both pre-call and post-call
1247
- * guard rejection. The provider patcher's surrounding span.startSpan
1248
- * already catches and records exceptions, so the customer sees a
1417
+ * guard rejection. The OpenAI patcher calls the interceptor BEFORE it starts
1418
+ * the LLM span and re-throws this error, so the customer sees a
1249
1419
  * `GuardRejectedError` propagated out of their `openai.chat.completions.create`
1250
- * call — the LLM is NEVER invoked.
1420
+ * call, and the LLM does not receive the call. No span records the rejection.
1251
1421
  *
1252
1422
  * Customers who want to handle rejection gracefully can:
1253
1423
  * try { await openai.chat.completions.create({ ... }); }
@@ -1310,12 +1480,19 @@ interface FixInterceptor {
1310
1480
  /**
1311
1481
  * Fix Runtime — Main orchestrator for the fix application system.
1312
1482
  *
1313
- * Manages:
1483
+ * FixRuntime is off by default (`init({ fixRuntime: true })` turns it on).
1484
+ * During the beta, the Risicare service does not give fixes to customer
1485
+ * projects, so FixRuntime has no effect for them. Manages:
1314
1486
  * - Loading active fixes from the API (via FixLoader)
1315
1487
  * - Caching fixes locally (via FixCache)
1316
- * - Applying fixes via interceptors (via DefaultFixInterceptor)
1488
+ * - Running fixes via interceptors on the paths that call them
1317
1489
  * - Tracking fix effectiveness
1318
1490
  *
1491
+ * The interceptor enforces guard fixes on the paths that call it. The
1492
+ * interceptor applies prompt, parameter and fallback fixes only when the call
1493
+ * has an `errorCode`. The provider path does not supply one, so it does not
1494
+ * apply them.
1495
+ *
1319
1496
  * Singleton management via globalThis (same pattern as the tracer).
1320
1497
  *
1321
1498
  * Port of Python SDK's runtime/runtime.py adapted for Node.js.
@@ -1557,4 +1734,19 @@ type WebhookPayload = Uint8Array | ArrayBuffer | string;
1557
1734
  */
1558
1735
  declare function verifyWebhookSignature(payload: WebhookPayload, headers: HeaderLookup, secret: string, opts?: VerifyWebhookOptions): void;
1559
1736
 
1560
- 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, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, 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 };
1737
+ /**
1738
+ * Risicare SDK for JavaScript/TypeScript — Public API.
1739
+ *
1740
+ * Progressive integration tiers:
1741
+ * Tier 1: init() + patchOpenAI() (minimum setup)
1742
+ * Tier 2: agent() wrapper (agent identity)
1743
+ * Tier 3: session() / withSession() (user sessions)
1744
+ * Tier 4: traceThink/Decide/Act/Observe (decision phases)
1745
+ * Tier 5: traceMessage/Delegate/Coordinate (multi-agent)
1746
+ */
1747
+
1748
+ type Tracer = Tracer$1;
1749
+
1750
+ type Span = Span$1;
1751
+
1752
+ 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 };