risicare 0.6.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 (85) hide show
  1. package/LICENSE +26 -0
  2. package/README.md +308 -61
  3. package/dist/frameworks/instructor.cjs +790 -5
  4. package/dist/frameworks/instructor.cjs.map +1 -1
  5. package/dist/frameworks/instructor.js +780 -5
  6. package/dist/frameworks/instructor.js.map +1 -1
  7. package/dist/frameworks/langchain.cjs +790 -5
  8. package/dist/frameworks/langchain.cjs.map +1 -1
  9. package/dist/frameworks/langchain.d.cts +3 -2
  10. package/dist/frameworks/langchain.d.ts +3 -2
  11. package/dist/frameworks/langchain.js +780 -5
  12. package/dist/frameworks/langchain.js.map +1 -1
  13. package/dist/frameworks/langgraph.cjs +790 -5
  14. package/dist/frameworks/langgraph.cjs.map +1 -1
  15. package/dist/frameworks/langgraph.js +780 -5
  16. package/dist/frameworks/langgraph.js.map +1 -1
  17. package/dist/frameworks/llamaindex.cjs +801 -5
  18. package/dist/frameworks/llamaindex.cjs.map +1 -1
  19. package/dist/frameworks/llamaindex.d.cts +3 -2
  20. package/dist/frameworks/llamaindex.d.ts +3 -2
  21. package/dist/frameworks/llamaindex.js +791 -5
  22. package/dist/frameworks/llamaindex.js.map +1 -1
  23. package/dist/index.cjs +1259 -175
  24. package/dist/index.cjs.map +1 -1
  25. package/dist/index.d.cts +245 -39
  26. package/dist/index.d.ts +245 -39
  27. package/dist/index.js +1259 -175
  28. package/dist/index.js.map +1 -1
  29. package/dist/providers/anthropic/index.cjs +1601 -36
  30. package/dist/providers/anthropic/index.cjs.map +1 -1
  31. package/dist/providers/anthropic/index.d.cts +3 -1
  32. package/dist/providers/anthropic/index.d.ts +3 -1
  33. package/dist/providers/anthropic/index.js +1591 -36
  34. package/dist/providers/anthropic/index.js.map +1 -1
  35. package/dist/providers/bedrock/index.cjs +850 -32
  36. package/dist/providers/bedrock/index.cjs.map +1 -1
  37. package/dist/providers/bedrock/index.js +840 -32
  38. package/dist/providers/bedrock/index.js.map +1 -1
  39. package/dist/providers/cerebras/index.cjs +1534 -30
  40. package/dist/providers/cerebras/index.cjs.map +1 -1
  41. package/dist/providers/cerebras/index.js +1524 -30
  42. package/dist/providers/cerebras/index.js.map +1 -1
  43. package/dist/providers/cohere/index.cjs +1557 -102
  44. package/dist/providers/cohere/index.cjs.map +1 -1
  45. package/dist/providers/cohere/index.js +1547 -102
  46. package/dist/providers/cohere/index.js.map +1 -1
  47. package/dist/providers/google/index.cjs +1562 -60
  48. package/dist/providers/google/index.cjs.map +1 -1
  49. package/dist/providers/google/index.js +1552 -60
  50. package/dist/providers/google/index.js.map +1 -1
  51. package/dist/providers/groq/index.cjs +1534 -30
  52. package/dist/providers/groq/index.cjs.map +1 -1
  53. package/dist/providers/groq/index.js +1524 -30
  54. package/dist/providers/groq/index.js.map +1 -1
  55. package/dist/providers/huggingface/index.cjs +1622 -25
  56. package/dist/providers/huggingface/index.cjs.map +1 -1
  57. package/dist/providers/huggingface/index.d.cts +0 -9
  58. package/dist/providers/huggingface/index.d.ts +0 -9
  59. package/dist/providers/huggingface/index.js +1612 -25
  60. package/dist/providers/huggingface/index.js.map +1 -1
  61. package/dist/providers/mistral/index.cjs +1535 -54
  62. package/dist/providers/mistral/index.cjs.map +1 -1
  63. package/dist/providers/mistral/index.js +1525 -54
  64. package/dist/providers/mistral/index.js.map +1 -1
  65. package/dist/providers/ollama/index.cjs +1559 -93
  66. package/dist/providers/ollama/index.cjs.map +1 -1
  67. package/dist/providers/ollama/index.js +1549 -93
  68. package/dist/providers/ollama/index.js.map +1 -1
  69. package/dist/providers/openai/index.cjs +1598 -61
  70. package/dist/providers/openai/index.cjs.map +1 -1
  71. package/dist/providers/openai/index.d.cts +6 -1
  72. package/dist/providers/openai/index.d.ts +6 -1
  73. package/dist/providers/openai/index.js +1588 -61
  74. package/dist/providers/openai/index.js.map +1 -1
  75. package/dist/providers/together/index.cjs +1534 -30
  76. package/dist/providers/together/index.cjs.map +1 -1
  77. package/dist/providers/together/index.js +1524 -30
  78. package/dist/providers/together/index.js.map +1 -1
  79. package/dist/providers/vercel-ai/index.cjs +1288 -17
  80. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  81. package/dist/providers/vercel-ai/index.d.cts +0 -6
  82. package/dist/providers/vercel-ai/index.d.ts +0 -6
  83. package/dist/providers/vercel-ai/index.js +1278 -17
  84. package/dist/providers/vercel-ai/index.js.map +1 -1
  85. package/package.json +5 -12
package/dist/index.cjs CHANGED
@@ -134,6 +134,29 @@ function getDebug() {
134
134
  function setDebugFlag(enabled) {
135
135
  G[PREFIX + "debug"] = enabled;
136
136
  }
137
+ var PROVIDER_SPANS = /* @__PURE__ */ Symbol.for("risicare.providerSpans");
138
+ function usableProviderSpanState(s) {
139
+ if (!s || typeof s !== "object") return false;
140
+ const { version, open, registry } = s;
141
+ const o = open;
142
+ return version === 1 && !!o && typeof o.add === "function" && typeof o.delete === "function" && typeof o[Symbol.iterator] === "function" && (registry === void 0 || typeof registry.register === "function");
143
+ }
144
+ function getProviderSpanState() {
145
+ const found = G[PROVIDER_SPANS];
146
+ if (found === void 0) {
147
+ const s = {
148
+ version: 1,
149
+ open: /* @__PURE__ */ new Set(),
150
+ registry: typeof FinalizationRegistry === "function" ? new FinalizationRegistry((o) => o.release()) : void 0
151
+ };
152
+ G[PROVIDER_SPANS] = s;
153
+ return s;
154
+ }
155
+ if (!usableProviderSpanState(found)) {
156
+ throw new TypeError("the shared provider span state is not version 1");
157
+ }
158
+ return found;
159
+ }
137
160
 
138
161
  // src/utils/log.ts
139
162
  function setDebug(enabled) {
@@ -150,6 +173,73 @@ function warn(msg) {
150
173
  `);
151
174
  }
152
175
 
176
+ // src/utils/text.ts
177
+ function cutCodePoints(text, max) {
178
+ if (text.length <= max) return text;
179
+ let units = 0;
180
+ for (let points = 0; points < max && units < text.length; points++) {
181
+ units += text.codePointAt(units) > 65535 ? 2 : 1;
182
+ }
183
+ return text.slice(0, units);
184
+ }
185
+
186
+ // src/utils/scrub.ts
187
+ var KEY_MARKER = "[REDACTED-KEY]";
188
+ var CONTROL = new RegExp("[\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]", "g");
189
+ function escapeRegExp(text) {
190
+ return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
191
+ }
192
+ function percentDecode(text) {
193
+ try {
194
+ return decodeURIComponent(text);
195
+ } catch {
196
+ return text.replace(/%([0-9A-Fa-f]{2})/g, (_m, hex) => String.fromCharCode(parseInt(hex, 16)));
197
+ }
198
+ }
199
+ function keyPattern(keys) {
200
+ const values = /* @__PURE__ */ new Set();
201
+ for (const k of [...keys, process.env.RISICARE_API_KEY]) if (k) values.add(k);
202
+ if (values.size === 0) return null;
203
+ const ordered = [...values].sort((a, b) => b.length - a.length);
204
+ return new RegExp(ordered.map(escapeRegExp).join("|"), "gi");
205
+ }
206
+ function scrubText(text, keys, limit = 200) {
207
+ let out;
208
+ try {
209
+ out = text instanceof Error ? `${text.name}: ${text.message}` : String(text);
210
+ } catch {
211
+ out = typeof text;
212
+ }
213
+ const pattern = keyPattern(keys);
214
+ if (pattern !== null) {
215
+ if (out.includes("%")) {
216
+ const decoded = percentDecode(out);
217
+ pattern.lastIndex = 0;
218
+ if (decoded !== out && pattern.test(decoded)) out = decoded;
219
+ }
220
+ pattern.lastIndex = 0;
221
+ out = out.replace(pattern, KEY_MARKER);
222
+ }
223
+ return cutCodePoints(out.replace(CONTROL, " "), limit);
224
+ }
225
+ function safeUrl(url) {
226
+ try {
227
+ const u = new URL(url);
228
+ const path = u.pathname === "/" && !/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*\//i.test(url) ? "" : u.pathname;
229
+ return `${u.protocol}//${u.host}${path}`;
230
+ } catch {
231
+ return url.split("?")[0].split("#")[0].replace(/\/\/[^/@]*@/, "//");
232
+ }
233
+ }
234
+ function hasCredentials(url) {
235
+ try {
236
+ const u = new URL(url);
237
+ return u.username !== "" || u.password !== "";
238
+ } catch {
239
+ return false;
240
+ }
241
+ }
242
+
153
243
  // src/masking.ts
154
244
  var MASK_ERROR_MARKER = "<risicare:mask-error>";
155
245
  var MASK_BUDGET_MS_PER_SPAN = 1;
@@ -216,15 +306,124 @@ function applyMask(span, mask, onError) {
216
306
  markMasked(span);
217
307
  }
218
308
  var CONTENT_KEYS_EXACT = /* @__PURE__ */ new Set([
309
+ // spec v1
219
310
  "gen_ai.system_prompt",
220
- "gen_ai.prompt.message"
311
+ // anthropic, bedrock
312
+ "gen_ai.prompt.message",
313
+ // cohere
314
+ "gen_ai.prompt",
315
+ // OTel GenAI (deprecated form)
316
+ "gen_ai.completion",
317
+ "gen_ai.input.messages",
318
+ // OTel GenAI
319
+ "gen_ai.output.messages",
320
+ "gen_ai.system_instructions",
321
+ "gen_ai.tool.call.arguments",
322
+ // Corpus v2: the list of tool definitions of a request. The names,
323
+ // descriptions and schemas in it are text that the customer wrote.
324
+ "gen_ai.tool.definitions",
325
+ "gen_ai.tool.call.result",
326
+ "input.value",
327
+ // OpenInference
328
+ "output.value",
329
+ "llm.prompts",
330
+ "llm.prompt_template.template",
331
+ "llm.prompt_template.variables",
332
+ "task_description",
333
+ // CrewAI
334
+ // ⚠ EXTENSION to spec v1: content keys that the Python SDK's integrations emit
335
+ // and that no v1 rule strips. Kept here too, so the two SDKs agree on the rule.
336
+ "framework.crewai.task_description",
337
+ "framework.crewai.agent_goal",
338
+ "framework.crewai.agent_output",
339
+ "framework.crewai.result",
340
+ "framework.autogen.last_message",
341
+ "framework.autogen.reply",
342
+ "framework.autogen.response",
343
+ "framework.openai_agents.input",
344
+ "framework.openai_agents.output",
345
+ "framework.dspy.signature",
346
+ "gen_ai.request.messages",
347
+ "agent.action.input",
348
+ "agent.action.log",
349
+ "agent.finish.output",
350
+ "tool.input",
351
+ "tool.output",
352
+ "retriever.query",
353
+ "retriever.first_doc",
354
+ // ⚠ FAIL CLOSED: third-party content keys that no other rule strips.
355
+ "gen_ai.retrieval.query.text",
356
+ // OTel GenAI
357
+ "gen_ai.retrieval.documents",
358
+ "gen_ai.evaluation.explanation",
359
+ "llm.function_call",
360
+ // OpenInference
361
+ "llm.choices",
362
+ "reranker.query",
363
+ "audio.transcript",
364
+ "traceloop.entity.input",
365
+ // OpenLLMetry
366
+ "traceloop.entity.output"
367
+ ]);
368
+ var CONTENT_LAST_SEGMENT_IN_CONTEXT = /* @__PURE__ */ new Map([
369
+ ["function_call_arguments_json", /* @__PURE__ */ new Set()],
370
+ // OpenInference `message.*`
371
+ ["data", /* @__PURE__ */ new Set(["message_content"])],
372
+ ["url", /* @__PURE__ */ new Set(["image"])],
373
+ // `image.url` can hold base64 data
374
+ ["metadata", /* @__PURE__ */ new Set(["document", "documents"])]
221
375
  ]);
376
+ var CONTENT_CONTAINER_SEGMENTS = /* @__PURE__ */ new Set([
377
+ "message",
378
+ "messages",
379
+ "message_content",
380
+ "contents",
381
+ "embedding",
382
+ "embeddings",
383
+ "document",
384
+ "documents",
385
+ "tool_call",
386
+ "tool_calls",
387
+ "function"
388
+ ]);
389
+ var CONTENT_KEYS_KEEP_EXACT = /* @__PURE__ */ new Set([
390
+ "gen_ai.response.content_type",
391
+ "gen_ai.response.content_blocks",
392
+ "gen_ai.prompt.parts",
393
+ "gen_ai.prompt.count",
394
+ "gen_ai.response.choices",
395
+ "gen_ai.completion.tool_calls"
396
+ ]);
397
+ var KEEP_LAST_SEGMENTS = /* @__PURE__ */ new Set([
398
+ "role",
399
+ "name",
400
+ "id",
401
+ "type",
402
+ "count",
403
+ "index",
404
+ "model",
405
+ "finish_reason",
406
+ "mime_type"
407
+ ]);
408
+ var KEEP_LAST_SUFFIXES = ["_length", "_tokens", "_count"];
222
409
  var CONTENT_OMITTED_MARKER = "<risicare:content-omitted>";
223
410
  function isContentKey(key) {
224
- if (CONTENT_KEYS_EXACT.has(key)) return true;
225
- const lastSegment = key.slice(key.lastIndexOf(".") + 1);
226
- if (lastSegment === "content") return true;
227
- return key.endsWith("_content");
411
+ if (CONTENT_KEYS_KEEP_EXACT.has(key)) return false;
412
+ if (CONTENT_KEYS_EXACT.has(key) || key.endsWith("_content")) return true;
413
+ const segments = key.split(".");
414
+ const last = segments[segments.length - 1];
415
+ const context = CONTENT_LAST_SEGMENT_IN_CONTEXT.get(last);
416
+ if (context && (context.size === 0 || segments.slice(0, -1).some((s) => context.has(s)))) {
417
+ return true;
418
+ }
419
+ if (KEEP_LAST_SEGMENTS.has(last) || KEEP_LAST_SUFFIXES.some((x) => last.endsWith(x))) {
420
+ return false;
421
+ }
422
+ if (last === "content") return true;
423
+ if (last === "text" || last === "arguments") {
424
+ return segments.slice(0, -1).some((s) => CONTENT_CONTAINER_SEGMENTS.has(s));
425
+ }
426
+ return false;
228
427
  }
229
428
  function stripAttributes(attrs) {
230
429
  let n = 0;
@@ -286,7 +485,13 @@ function applyMaskBatch(spans, mask, onError) {
286
485
  }
287
486
  const elapsedMs = Date.now() - started;
288
487
  if (errors > 0 && firstKey !== void 0) {
289
- debug(`mask threw on ${errors} field(s); first: key=${firstKey} ${String(firstError)}`);
488
+ let detail;
489
+ try {
490
+ detail = String(firstError);
491
+ } catch {
492
+ detail = typeof firstError;
493
+ }
494
+ debug(`mask threw on ${errors} field(s); first: key=${firstKey} ${detail}`);
290
495
  }
291
496
  return { errors, elapsedMs };
292
497
  }
@@ -302,8 +507,37 @@ function warnMaskSlow(spanCount, elapsedMs) {
302
507
  }
303
508
 
304
509
  // src/exporters/batch.ts
510
+ var DEADLINE = /* @__PURE__ */ Symbol("deadline");
511
+ async function raceDeadline(p, ms) {
512
+ let timer;
513
+ const deadline = new Promise((resolve) => {
514
+ timer = setTimeout(() => resolve(DEADLINE), Math.max(0, ms));
515
+ });
516
+ try {
517
+ return await Promise.race([p, deadline]);
518
+ } finally {
519
+ clearTimeout(timer);
520
+ }
521
+ }
522
+ function describeThrown(e) {
523
+ return scrubText(e, []);
524
+ }
525
+ async function shutdownExporter(exporter, ms) {
526
+ try {
527
+ const outcome = await raceDeadline(Promise.resolve().then(() => exporter.shutdown()), ms);
528
+ if (outcome === DEADLINE) debug(`${exporter.name}.shutdown() did not finish within ${ms} ms`);
529
+ } catch (e) {
530
+ debug(`Error shutting down ${exporter.name}: ${describeThrown(e)}`);
531
+ }
532
+ }
305
533
  var SHUTDOWN_RESERVE_MS = 100;
306
534
  var SHUTDOWN_BUDGET_MS = 5e3;
535
+ var MAX_TIMEOUT_MS = 2 ** 31 - 1;
536
+ function normalizeTimeoutMs(value) {
537
+ if (typeof value !== "number" || !Number.isFinite(value)) return SHUTDOWN_BUDGET_MS;
538
+ if (value < 0) return 0;
539
+ return Math.min(value, MAX_TIMEOUT_MS);
540
+ }
307
541
  var REFUSAL_WARN_WINDOW_MS = 3e5;
308
542
  var DEFAULT_BATCH_SIZE = 500;
309
543
  var MAX_ATTRIBUTE_PAIRS_PER_BATCH = 24e3;
@@ -392,11 +626,18 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
392
626
  _timer = null;
393
627
  _started = false;
394
628
  _flushing = false;
629
+ _inFlight = null;
395
630
  _beforeExitHandler = null;
396
631
  // Retry tracking for failed batches (Audit #5)
397
632
  _retryCounts = /* @__PURE__ */ new Map();
398
633
  static MAX_RETRIES = 3;
399
634
  _lastRefusalWarnAt = Number.NEGATIVE_INFINITY;
635
+ _lastUnackWarnAt = Number.NEGATIVE_INFINITY;
636
+ /**
637
+ * The loss total (dropped + rejected) that the last finished `flush()` saw.
638
+ * A flush reports a loss that is new since then, one time.
639
+ */
640
+ _lossMark = 0;
400
641
  // ── Masking (see `../masking.ts`) ──────────────────────────────────────────
401
642
  _mask;
402
643
  // ── Content capture gate (see `../masking.ts`) ─────────────────────────────
@@ -418,9 +659,15 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
418
659
  droppedSpansByReason = {
419
660
  queue_full: 0,
420
661
  transport_refused: 0,
421
- shutdown_residue: 0
662
+ shutdown_residue: 0,
663
+ unacknowledged: 0
422
664
  };
423
665
  exportedSpans = 0;
666
+ /**
667
+ * Spans that the backend acknowledged as REJECTED (the ack's `rejected`). They
668
+ * are not stored and are not retried. An exporter without an ack adds nothing.
669
+ */
670
+ rejectedSpans = 0;
424
671
  /** Export ATTEMPTS, not a span count. */
425
672
  failedExports = 0;
426
673
  /**
@@ -505,13 +752,32 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
505
752
  * NO progress and abandons the queue exactly as before — measured at 900 of
506
753
  * 1,000. We await a tick instead, the shape `flush()` already models.
507
754
  *
508
- * Anything still queued when the loop stops is COUNTED as `shutdown_residue`
509
- * and announced with a WARNING. The warning is the primary signal, not the
510
- * counter: a counter incremented inside `shutdown()` is written to memory
511
- * about to be freed and has no reader (RULING §2 / §8.2).
755
+ * The deadline is a hard wall-clock bound. Each round is raced against the
756
+ * budget that remains. At the deadline, `shutdown()` stops the round in flight
757
+ * through the exporter's optional `abort()`. That stopped round changes no
758
+ * counter, does not move the circuit breaker and re-queues nothing. Through
759
+ * 0.7.1 the deadline was checked only between rounds, so one round against a
760
+ * silent server (3 attempts x 5 s) held a 5,000 ms shutdown for 15 s.
761
+ *
762
+ * Anything still queued when the loop stops, AND a batch whose export was
763
+ * stopped, is COUNTED as `shutdown_residue` and announced with ONE WARNING
764
+ * that gives both numbers. The server may have received the spans of the
765
+ * stopped export. The warning is the primary signal, not the counter: a
766
+ * counter incremented inside `shutdown()` is written to memory about to be
767
+ * freed and has no reader (RULING §2 / §8.2).
768
+ *
769
+ * Each exporter's own `shutdown()` gets the time that is left of the budget.
770
+ * An exporter that does not finish in that time is not awaited.
771
+ *
772
+ * Limit: the abort does not stop a TLS handshake that stalls. Measured, such a
773
+ * handshake kept the process alive about 10 s after `shutdown()` returned.
774
+ *
775
+ * @param timeoutMs - The budget (default 5000). See `normalizeTimeoutMs` for
776
+ * the values that are not a finite number.
512
777
  */
513
778
  async shutdown(timeoutMs = SHUTDOWN_BUDGET_MS) {
514
779
  if (!this._started) return;
780
+ timeoutMs = normalizeTimeoutMs(timeoutMs);
515
781
  this._started = false;
516
782
  if (this._timer) {
517
783
  clearInterval(this._timer);
@@ -522,10 +788,13 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
522
788
  this._beforeExitHandler = null;
523
789
  }
524
790
  const reserveMs = Math.min(SHUTDOWN_RESERVE_MS, timeoutMs / 2);
525
- const drainDeadline = Date.now() + Math.max(0, timeoutMs - reserveMs);
791
+ const shutdownDeadline = Date.now() + timeoutMs;
792
+ const drainDeadline = shutdownDeadline - reserveMs;
526
793
  while (this._queue.length > 0 || this._flushing) {
527
- if (Date.now() >= drainDeadline) break;
528
- const outcome = await this._exportBatch();
794
+ const remaining = drainDeadline - Date.now();
795
+ if (remaining <= 0) break;
796
+ const outcome = await raceDeadline(this._exportBatch(), remaining);
797
+ if (outcome === DEADLINE) break;
529
798
  if (outcome === 3 /* Busy */) {
530
799
  await new Promise((r) => setTimeout(r, 1));
531
800
  continue;
@@ -534,20 +803,29 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
534
803
  break;
535
804
  }
536
805
  }
537
- const residue = this._queue.length;
806
+ const queued = this._queue.length;
807
+ const flight = this._inFlight;
808
+ const inFlight = flight !== null && !flight.abandoned ? flight.size : 0;
809
+ if (flight !== null && !flight.abandoned) {
810
+ flight.abandoned = true;
811
+ for (const exporter of this._exporters) {
812
+ try {
813
+ exporter.abort?.(flight.spans);
814
+ } catch (e) {
815
+ debug(`Error aborting ${exporter.name}: ${describeThrown(e)}`);
816
+ }
817
+ }
818
+ }
819
+ const residue = queued + inFlight;
538
820
  if (residue > 0) {
539
821
  this._queue.length = 0;
540
822
  this._recordDropped("shutdown_residue", residue);
541
823
  warn(
542
- `shutdown() gave up with ${residue} span(s) still queued (reason=shutdown_residue) \u2014 they were NOT delivered. The ${timeoutMs} ms shutdown budget expired or the transport stopped accepting. Raise the shutdown timeout, or your container's termination grace period, to lose less.`
824
+ `shutdown() gave up with ${residue} span(s) (reason=shutdown_residue): ${queued} still queued and ${inFlight} in an export that shutdown() stopped. ` + (inFlight > 0 ? `The server may have received the ${inFlight} span(s) of the stopped export. ` : "") + `All ${residue} were not confirmed as delivered, and are counted as dropped. The ${timeoutMs} ms shutdown budget expired or the transport stopped accepting. Pass a larger timeout to shutdown(timeoutMs), or raise your container's termination grace period, to lose less.`
543
825
  );
544
826
  }
545
827
  for (const exporter of this._exporters) {
546
- try {
547
- await exporter.shutdown();
548
- } catch (e) {
549
- debug(`Error shutting down ${exporter.name}: ${e}`);
550
- }
828
+ await shutdownExporter(exporter, Math.max(0, shutdownDeadline - Date.now()));
551
829
  }
552
830
  this._retryCounts.clear();
553
831
  debug(
@@ -571,7 +849,8 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
571
849
  /**
572
850
  * Flush pending spans.
573
851
  *
574
- * @returns `true` only if everything queued at entry was DELIVERED.
852
+ * @returns `true` only if everything queued at entry was DELIVERED and no
853
+ * span was lost since the previous flush returned.
575
854
  *
576
855
  * RULING §6. This used to answer a different question — "is the queue
577
856
  * empty?" — and those two diverge in exactly one case: when spans left the
@@ -580,35 +859,76 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
580
859
  * everything right; silence lets them discover the problem, a false
581
860
  * affirmative forecloses it.
582
861
  *
583
- * Returns `false` when (a) the deadline expires with spans still queued,
584
- * (b) any span was discarded during the window — breaker refusal or retry
585
- * exhaustion — or (c) it is called after `shutdown()` and the shutdown
586
- * residue was non-zero.
862
+ * A LOSS IS REPORTED BY THE NEXT `flush()`, ONE TIME (design section 0,
863
+ * third revision). Returns `true` only when, at the moment it returns, the
864
+ * queue is empty, no batch is in flight, and no span was discarded or
865
+ * rejected since the previous `flush()` returned (or since start, for the
866
+ * first call). Through 0.7.1 only a loss during the call counted: a script
867
+ * whose spans the batch timer had discarded against a 401 sink got `true`
868
+ * with nothing delivered. A failure that a retry repairs does not make it
869
+ * `false`.
870
+ *
871
+ * Mechanics: the processor keeps a loss mark, the loss total (dropped +
872
+ * rejected) that the last finished flush saw. A flush compares the total
873
+ * with the mark it read at its start, then raises the mark to the total
874
+ * (never lowers it). Two flushes that overlap both answer `false` for one
875
+ * loss. The flush after that answers `true` when nothing new was lost.
876
+ *
877
+ * Returns `false` in these cases:
878
+ * (a) the deadline expires with spans still queued or in flight;
879
+ * (b) a span was discarded since the previous flush returned: queue full,
880
+ * breaker refusal, retry exhaustion, or an ack that did not account
881
+ * for it or a span that could not be serialized (`unacknowledged`);
882
+ * (c) the backend rejected a span since the previous flush returned;
883
+ * (d) it is called after `shutdown()`, and the shutdown residue was not 0.
884
+ *
885
+ * The deadline is a hard wall-clock bound on the WAIT. At the deadline
886
+ * `flush()` returns `false`. Through 0.7.1 the deadline was checked only
887
+ * between rounds.
888
+ *
889
+ * ⚠ `flush()` never stops a request that is already sent. The export round in
890
+ * flight continues and ends by its own rules: its request timeout, its
891
+ * retries, the circuit breaker. A short flush budget therefore costs no retry,
892
+ * moves no breaker and sends nothing twice. Its result still counts.
893
+ *
894
+ * Limit: that round can keep the process alive after `flush()` returns
895
+ * `false`, until its own timeouts end. Measured on a silent server: 22 s. To
896
+ * end a process within a bound, call `await shutdown(timeoutMs)`: it stops
897
+ * the round in flight.
587
898
  *
588
899
  * ⚠ (b) reads the flat total, so a concurrent `queue_full` drop of a span
589
- * that arrived DURING the window also answers `false`. That is the
900
+ * that arrived during the call also answers `false`. That is the
590
901
  * conservative direction on purpose: a false negative costs a caller one
591
902
  * more flush, a false positive is the defect being fixed.
592
903
  */
593
904
  async flush(timeoutMs = SHUTDOWN_BUDGET_MS) {
905
+ timeoutMs = normalizeTimeoutMs(timeoutMs);
594
906
  if (!this._started) {
595
907
  return this._queue.length === 0 && this.droppedSpansByReason.shutdown_residue === 0;
596
908
  }
597
- const start = Date.now();
598
- const discardedAtEntry = this.droppedSpans;
909
+ const deadline = Date.now() + timeoutMs;
910
+ const mark = this._lossMark;
911
+ const finish = (settled) => {
912
+ const lost = this.droppedSpans + this.rejectedSpans;
913
+ this._lossMark = Math.max(this._lossMark, lost);
914
+ return settled && lost === mark;
915
+ };
599
916
  while (this._queue.length > 0 || this._flushing) {
917
+ const remaining = deadline - Date.now();
918
+ if (remaining <= 0) return finish(false);
600
919
  if (!this._flushing && this._queue.length > 0) {
601
- await this._exportBatch();
920
+ const outcome = await raceDeadline(this._exportBatch(), remaining);
921
+ if (outcome === DEADLINE) return finish(false);
602
922
  } else {
603
923
  await new Promise((r) => setTimeout(r, 1));
604
924
  }
605
- if (Date.now() - start > timeoutMs) return false;
606
925
  }
607
- return this.droppedSpans === discardedAtEntry;
926
+ return finish(true);
608
927
  }
609
928
  getMetrics() {
610
929
  return {
611
930
  exportedSpans: this.exportedSpans,
931
+ rejectedSpans: this.rejectedSpans,
612
932
  droppedSpans: this.droppedSpans,
613
933
  droppedSpansByReason: { ...this.droppedSpansByReason },
614
934
  failedExports: this.failedExports,
@@ -618,10 +938,56 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
618
938
  queueUtilization: this._queue.length / this._maxQueueSize
619
939
  };
620
940
  }
941
+ /**
942
+ * Count a delivered batch of `n` spans from the exporter's ack.
943
+ *
944
+ * The ack is not trusted. With r = min(rejected, n), a = min(accepted, n - r)
945
+ * and u = n - a - r: `exportedSpans` rises by a, `rejectedSpans` by r, and the
946
+ * u spans that no ack accounts for are dropped as `unacknowledged`, with one
947
+ * rate-limited WARNING. Without an ack (console, custom exporter), the whole
948
+ * batch counts as exported, as before. Python twin: the same clamp.
949
+ */
950
+ _countDelivered(n, ack) {
951
+ if (ack === null) {
952
+ this.exportedSpans += n;
953
+ return;
954
+ }
955
+ const rejected = Math.min(ack.rejected, n);
956
+ const accepted = Math.min(ack.accepted, n - rejected);
957
+ const unacknowledged = n - accepted - rejected;
958
+ this.exportedSpans += accepted;
959
+ this.rejectedSpans += rejected;
960
+ if (unacknowledged > 0) {
961
+ this._recordDropped("unacknowledged", unacknowledged);
962
+ const now = Date.now();
963
+ if (now - this._lastUnackWarnAt > REFUSAL_WARN_WINDOW_MS) {
964
+ this._lastUnackWarnAt = now;
965
+ warn(
966
+ `Risicare: the backend's ack accounts for ${accepted + rejected} of ${n} span(s) in this batch. The other ${unacknowledged} are counted as dropped (reason=unacknowledged): they may not be stored. ${this.droppedSpansByReason.unacknowledged} span(s) counted this way so far in this process.`
967
+ );
968
+ }
969
+ }
970
+ }
971
+ /** The requests in one export round, when every exporter that delivers states it. */
972
+ _requestsPerRound() {
973
+ const delivering = this._exporters.filter((e) => e.countsAsDelivery !== false);
974
+ if (delivering.length !== 1) return void 0;
975
+ const n = delivering[0].attemptsPerExport;
976
+ return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : void 0;
977
+ }
978
+ /**
979
+ * One export round.
980
+ *
981
+ * Which results decide delivery: an exporter that only shows spans locally
982
+ * (`countsAsDelivery === false`, the console exporter) decides only when no
983
+ * other kind of exporter is present. Among the exporters that deliver, ANY
984
+ * success counts the batch as delivered, once.
985
+ */
621
986
  async _exportBatch() {
622
987
  if (this._flushing) return 3 /* Busy */;
623
988
  if (this._queue.length === 0) return 0 /* Empty */;
624
989
  this._flushing = true;
990
+ let flight = null;
625
991
  try {
626
992
  let take = 0;
627
993
  let pairs = 0;
@@ -640,6 +1006,8 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
640
1006
  }
641
1007
  const batch = this._queue.splice(0, take);
642
1008
  if (batch.length === 0) return 0 /* Empty */;
1009
+ flight = { spans: batch, size: batch.length, abandoned: false };
1010
+ this._inFlight = flight;
643
1011
  if (!this._traceContent) {
644
1012
  const stripped = stripContentBatch(batch);
645
1013
  if (stripped > 0) {
@@ -653,12 +1021,19 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
653
1021
  }
654
1022
  debug(`Exporting batch of ${batch.length} spans`);
655
1023
  let batchExported = false;
1024
+ const anyDelivers = this._exporters.some((e) => e.countsAsDelivery !== false);
1025
+ const unserializable = /* @__PURE__ */ new Set();
656
1026
  for (const exporter of this._exporters) {
1027
+ const decides = !anyDelivers || exporter.countsAsDelivery !== false;
657
1028
  try {
658
1029
  const result = await exporter.export(batch);
1030
+ if (flight.abandoned) return 2 /* Failed */;
1031
+ if (!decides) continue;
1032
+ for (const span of exporter.takeUnserializable?.(batch) ?? []) unserializable.add(span);
659
1033
  if (result === "success" /* SUCCESS */) {
1034
+ const ack = exporter.takeAck?.(batch) ?? null;
660
1035
  if (!batchExported) {
661
- this.exportedSpans += batch.length;
1036
+ this._countDelivered(batch.length - unserializable.size, ack);
662
1037
  batchExported = true;
663
1038
  for (const span of batch) {
664
1039
  this._retryCounts.delete(span.spanId);
@@ -668,13 +1043,17 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
668
1043
  this.failedExports++;
669
1044
  }
670
1045
  } catch (e) {
1046
+ if (flight.abandoned) return 2 /* Failed */;
1047
+ if (!decides) continue;
671
1048
  this.failedExports++;
672
- debug(`Export to ${exporter.name} failed: ${e}`);
1049
+ debug(`Export to ${exporter.name} failed: ${describeThrown(e)}`);
673
1050
  }
674
1051
  }
1052
+ if (unserializable.size > 0) this._recordDropped("unacknowledged", unserializable.size);
675
1053
  if (!batchExported) {
676
1054
  let dropped = 0;
677
1055
  const retryable = batch.filter((span) => {
1056
+ if (unserializable.has(span)) return false;
678
1057
  const count = (this._retryCounts.get(span.spanId) ?? 0) + 1;
679
1058
  if (count > _BatchSpanProcessor.MAX_RETRIES) {
680
1059
  this._retryCounts.delete(span.spanId);
@@ -693,38 +1072,72 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
693
1072
  const now = Date.now();
694
1073
  if (now - this._lastRefusalWarnAt > REFUSAL_WARN_WINDOW_MS) {
695
1074
  this._lastRefusalWarnAt = now;
1075
+ const rounds = _BatchSpanProcessor.MAX_RETRIES + 1;
1076
+ const perRound = this._requestsPerRound();
696
1077
  warn(
697
- `${dropped} span(s) DISCARDED (reason=transport_refused) after ${_BatchSpanProcessor.MAX_RETRIES} failed export attempts each \u2014 the endpoint is not accepting spans and the retry budget is spent. ${this.droppedSpansByReason.transport_refused} span(s) discarded this way so far in this process. This data is gone; check the apiKey and the endpoint.`
1078
+ `${dropped} span(s) DISCARDED (reason=transport_refused) after ${rounds} failed export rounds each` + (perRound !== void 0 ? ` (up to ${rounds * perRound} HTTP requests: ${perRound} in each round)` : "") + ` \u2014 the endpoint is not accepting spans and the retry budget is spent. ${this.droppedSpansByReason.transport_refused} span(s) discarded this way so far in this process. This data is gone; check the apiKey and the endpoint.`
698
1079
  );
699
1080
  }
700
1081
  }
701
1082
  }
702
1083
  return batchExported ? 1 /* Delivered */ : 2 /* Failed */;
703
1084
  } finally {
1085
+ if (this._inFlight === flight) this._inFlight = null;
704
1086
  this._flushing = false;
705
1087
  }
706
1088
  }
707
1089
  };
708
1090
 
709
1091
  // src/config.ts
710
- var DEFAULT_ENDPOINT = "https://app.risicare.ai";
1092
+ var DEFAULT_ENDPOINT = "https://ingest.risicare.ai";
1093
+ var DEFAULT_API_ENDPOINT = "https://api.risicare.ai";
1094
+ var ASCII_WS_EDGES = /^[ \t\n\r\f\v]+|[ \t\n\r\f\v]+$/g;
1095
+ function given(value) {
1096
+ if (typeof value !== "string") return void 0;
1097
+ const trimmed = value.replace(ASCII_WS_EDGES, "");
1098
+ return trimmed === "" ? void 0 : trimmed;
1099
+ }
1100
+ var DEFAULT_INGEST_PATTERN = /^https:\/\/ingest\.risicare\.ai(?::443)?\/*$/i;
1101
+ function isDefaultIngest(value) {
1102
+ return DEFAULT_INGEST_PATTERN.test(value);
1103
+ }
1104
+ function resolveEndpoints(endpointOption, apiEndpointOption, envEndpoint, envApiEndpoint) {
1105
+ const e = given(endpointOption);
1106
+ const a = given(apiEndpointOption);
1107
+ const ee = given(envEndpoint);
1108
+ const ea = given(envApiEndpoint);
1109
+ const endpoint = e ?? ee ?? DEFAULT_ENDPOINT;
1110
+ let apiEndpoint;
1111
+ if (a !== void 0) apiEndpoint = a;
1112
+ else if (e !== void 0 && !isDefaultIngest(e)) apiEndpoint = e;
1113
+ else if (ea !== void 0) apiEndpoint = ea;
1114
+ else if (e === void 0 && ee !== void 0 && !isDefaultIngest(ee)) apiEndpoint = ee;
1115
+ else apiEndpoint = DEFAULT_API_ENDPOINT;
1116
+ return { endpoint, apiEndpoint };
1117
+ }
711
1118
  function resolveConfig(config) {
712
1119
  const env = process.env;
713
1120
  const apiKey = config?.apiKey ?? env.RISICARE_API_KEY;
714
- const endpoint = config?.endpoint ?? env.RISICARE_ENDPOINT ?? DEFAULT_ENDPOINT;
1121
+ const { endpoint, apiEndpoint } = resolveEndpoints(
1122
+ config?.endpoint,
1123
+ config?.apiEndpoint,
1124
+ env.RISICARE_ENDPOINT,
1125
+ env.RISICARE_API_ENDPOINT
1126
+ );
715
1127
  const projectId = config?.projectId ?? env.RISICARE_PROJECT_ID;
716
1128
  if (config?.projectId || env.RISICARE_PROJECT_ID) {
717
1129
  console.warn(
718
1130
  "[risicare] projectId is deprecated and ignored by the gateway. Your API key determines the project. Use serviceName and environment for within-project organization. projectId will be removed in v1.0."
719
1131
  );
720
1132
  }
721
- const environment = config?.environment ?? env.RISICARE_ENVIRONMENT ?? "development";
1133
+ const environment = config?.environment || env.RISICARE_ENVIRONMENT || "development";
722
1134
  const serviceName = config?.serviceName ?? env.RISICARE_SERVICE_NAME;
723
1135
  const serviceVersion = config?.serviceVersion ?? env.RISICARE_SERVICE_VERSION;
724
1136
  const traceContent = config?.traceContent ?? parseBool(env.RISICARE_TRACE_CONTENT, false);
725
1137
  const sampleRateRaw = config?.sampleRate ?? parseFloat(env.RISICARE_SAMPLE_RATE ?? "1.0");
726
1138
  const debug2 = config?.debug ?? parseBool(env.RISICARE_DEBUG, false);
727
1139
  const compress = config?.compress ?? parseBool(env.RISICARE_COMPRESS, false);
1140
+ const fixRuntime = config?.fixRuntime ?? parseBool(env.RISICARE_FIX_RUNTIME, false);
728
1141
  const batchSizeRaw = config?.batchSize ?? parseNumericEnv(env.RISICARE_BATCH_SIZE, DEFAULT_BATCH_SIZE);
729
1142
  const batchTimeoutMsRaw = config?.batchTimeoutMs ?? parseNumericEnv(env.RISICARE_BATCH_TIMEOUT_MS, 1e3);
730
1143
  const maxQueueSizeRaw = config?.maxQueueSize ?? parseNumericEnv(env.RISICARE_MAX_QUEUE_SIZE, 1e4);
@@ -738,16 +1151,18 @@ function resolveConfig(config) {
738
1151
  const batchTimeoutMs = validatePositiveInt("batchTimeoutMs", batchTimeoutMsRaw, 1e3, 1, 6e5);
739
1152
  const maxQueueSize = validatePositiveInt("maxQueueSize", maxQueueSizeRaw, 1e4, 1, 1e6);
740
1153
  let enabled;
1154
+ const tracingEnv = config?.enabled === void 0 ? tracingFromEnv(env.RISICARE_TRACING) : void 0;
741
1155
  if (config?.enabled !== void 0) {
742
1156
  enabled = config.enabled;
743
- } else if (env.RISICARE_TRACING !== void 0) {
744
- enabled = parseBool(env.RISICARE_TRACING, false);
1157
+ } else if (tracingEnv !== void 0) {
1158
+ enabled = tracingEnv;
745
1159
  } else {
746
1160
  enabled = !!apiKey;
747
1161
  }
748
- return {
1162
+ return hideKeyFromInspect({
749
1163
  apiKey: apiKey ?? "",
750
1164
  endpoint,
1165
+ apiEndpoint,
751
1166
  projectId: projectId ?? "",
752
1167
  environment,
753
1168
  serviceName: serviceName ?? "",
@@ -760,16 +1175,40 @@ function resolveConfig(config) {
760
1175
  maxQueueSize,
761
1176
  debug: debug2,
762
1177
  compress,
1178
+ fixRuntime,
763
1179
  metadata: config?.metadata ?? {},
764
1180
  // No env fallback — see the field's note on RisicareConfig.
765
1181
  mask: config?.mask
766
- };
1182
+ });
1183
+ }
1184
+ function hideKeyFromInspect(config) {
1185
+ Object.defineProperty(config, /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom"), {
1186
+ enumerable: false,
1187
+ value(_depth, options, inspect) {
1188
+ const { apiKey, ...rest } = this;
1189
+ return `RisicareConfig ${inspect({ ...rest, apiKey: apiKey ? "<redacted>" : "" }, options)}`;
1190
+ }
1191
+ });
1192
+ return config;
767
1193
  }
768
1194
  function parseBool(value, defaultValue) {
769
1195
  if (value === void 0) return defaultValue;
770
1196
  const lower = value.toLowerCase();
771
1197
  return lower === "true" || lower === "1" || lower === "yes";
772
1198
  }
1199
+ var TRACING_ON = /* @__PURE__ */ new Set(["true", "1", "yes", "on"]);
1200
+ var TRACING_OFF = /* @__PURE__ */ new Set(["false", "0", "no", "off"]);
1201
+ function tracingFromEnv(value) {
1202
+ if (value === void 0) return void 0;
1203
+ const v = value.trim().toLowerCase();
1204
+ if (v === "") return void 0;
1205
+ if (TRACING_ON.has(v)) return true;
1206
+ if (TRACING_OFF.has(v)) return false;
1207
+ warn(
1208
+ `RISICARE_TRACING=${JSON.stringify(value.slice(0, 40))} is not a recognised value, so tracing is OFF. Use one of: true, 1, yes, on (tracing on) or false, 0, no, off (tracing off). Leave it unset or empty to use the default.`
1209
+ );
1210
+ return false;
1211
+ }
773
1212
  function parseNumericEnv(value, defaultValue) {
774
1213
  if (value === void 0) return defaultValue;
775
1214
  const n = Number(value);
@@ -1375,12 +1814,31 @@ var CANONICAL_ERROR_CODES = /* @__PURE__ */ new Set([
1375
1814
  "TOOL.RESULT.UNEXPECTED_FORMAT",
1376
1815
  "TOOL.RESULT.UNPARSEABLE"
1377
1816
  ]);
1817
+ var CORE_RULES = [
1818
+ { re: new RegExp("json", "u"), code: "PERCEPTION.PARSING.JSON_INVALID" },
1819
+ { re: new RegExp("encoding", "u"), code: "PERCEPTION.INPUT.ENCODING" },
1820
+ { re: new RegExp("injection", "u"), code: "PERCEPTION.INPUT.INJECTION" },
1821
+ { re: new RegExp("malformed", "u"), code: "PERCEPTION.INPUT.MALFORMED" },
1822
+ { re: new RegExp("hallucin", "u"), code: "REASONING.HALLUCINATION.FACTUAL" },
1823
+ { re: new RegExp("contradict", "u"), code: "REASONING.LOGIC.CONTRADICTION" },
1824
+ { re: new RegExp("timeout", "u"), code: "TOOL.EXECUTION.TIMEOUT" },
1825
+ { re: new RegExp("rate[^\\n]?limit", "u"), code: "TOOL.EXECUTION.RATE_LIMITED" },
1826
+ { re: new RegExp("permission", "u"), code: "TOOL.INVOCATION.PERMISSION_DENIED" },
1827
+ { re: new RegExp("context[^\\n]+overflow", "u"), code: "MEMORY.CONTEXT_WINDOW.EXCEEDED" },
1828
+ { re: new RegExp("state[^\\n]+corrupt", "u"), code: "MEMORY.STATE.CORRUPTED" },
1829
+ { re: new RegExp("pii", "u"), code: "OUTPUT.SAFETY.PII_LEAK" },
1830
+ { re: new RegExp("deadlock", "u"), code: "COORDINATION.WORKFLOW.DEADLOCK" },
1831
+ { re: new RegExp("undeliverable", "u"), code: "COMMUNICATION.DELIVERY.UNDELIVERABLE" },
1832
+ { re: new RegExp("crash", "u"), code: "ORCHESTRATION.LIFECYCLE.CRASHED" },
1833
+ { re: new RegExp("quorum", "u"), code: "CONSENSUS.AGREEMENT.QUORUM_FAILED" },
1834
+ { re: new RegExp("quota[^\\n]+exceed", "u"), code: "RESOURCES.QUOTA.EXCEEDED" }
1835
+ ];
1378
1836
  var SUPPLEMENTAL_RULES = [
1379
- { re: new RegExp("timeout|timedout|aborted", "i"), code: "TOOL.EXECUTION.TIMEOUT" },
1380
- { re: new RegExp("rate.?limit|\\b429\\b|too many requests", "i"), code: "TOOL.EXECUTION.RATE_LIMITED" },
1381
- { re: new RegExp("connection|econnrefused|econnreset|enotfound|fetch failed|unreachable|broken pipe", "i"), code: "TOOL.EXECUTION.DEPENDENCY_FAILED" },
1382
- { re: new RegExp("\\bauth|unauthorized|forbidden|permission|\\b401\\b|\\b403\\b", "i"), code: "TOOL.INVOCATION.PERMISSION_DENIED" },
1383
- { re: new RegExp("json|syntaxerror|unexpected token|decodeerror", "i"), code: "PERCEPTION.PARSING.JSON_INVALID" }
1837
+ { re: new RegExp("timeout|timedout|aborted", "u"), code: "TOOL.EXECUTION.TIMEOUT" },
1838
+ { re: new RegExp("rate[^\\n]?limit|(?<![\\p{L}\\p{N}_])429(?![\\p{L}\\p{N}_])|too many requests", "u"), code: "TOOL.EXECUTION.RATE_LIMITED" },
1839
+ { re: new RegExp("connection|econnrefused|econnreset|enotfound|fetch failed|unreachable|broken pipe", "u"), code: "TOOL.EXECUTION.DEPENDENCY_FAILED" },
1840
+ { re: new RegExp("(?<![\\p{L}\\p{N}_])auth|unauthorized|forbidden|permission|(?<![\\p{L}\\p{N}_])401(?![\\p{L}\\p{N}_])|(?<![\\p{L}\\p{N}_])403(?![\\p{L}\\p{N}_])", "u"), code: "TOOL.INVOCATION.PERMISSION_DENIED" },
1841
+ { re: new RegExp("json|syntaxerror|unexpected token|decodeerror", "u"), code: "PERCEPTION.PARSING.JSON_INVALID" }
1384
1842
  ];
1385
1843
  var GENERIC_FALLBACK = "TOOL.EXECUTION.CRASHED";
1386
1844
 
@@ -1397,6 +1855,16 @@ var GuardRejectedError = class extends Error {
1397
1855
  this.phase = phase;
1398
1856
  }
1399
1857
  };
1858
+ function guardText(message) {
1859
+ if (!message || typeof message !== "object") return null;
1860
+ const content = message.content;
1861
+ if (typeof content === "string") return content === "" ? null : content;
1862
+ if (Array.isArray(content)) {
1863
+ const texts = content.filter((p) => !!p && typeof p === "object" && p.type === "text" && typeof p.text === "string").map((p) => p.text);
1864
+ if (texts.length > 0) return texts.join("\n");
1865
+ }
1866
+ return null;
1867
+ }
1400
1868
  function createInterceptContext(operationType, operationName, options) {
1401
1869
  return {
1402
1870
  operationType,
@@ -1456,8 +1924,8 @@ var DefaultFixInterceptor = class {
1456
1924
  }
1457
1925
  if (modifiedMessages && this._config.enabled) {
1458
1926
  for (const msg of modifiedMessages) {
1459
- const content = msg.content;
1460
- if (typeof content === "string") {
1927
+ const content = guardText(msg);
1928
+ if (content !== null) {
1461
1929
  for (const fix of this._cache.getAll()) {
1462
1930
  if (fix.fixType === "guard") {
1463
1931
  const { passed, result } = this._applier.applyGuardFix(
@@ -1602,7 +2070,13 @@ var DefaultFixInterceptor = class {
1602
2070
  }
1603
2071
  };
1604
2072
  function classifyError(error) {
1605
- const haystack = `${error?.constructor?.name ?? "Error"} ${error?.message ?? ""}`;
2073
+ const message = String(error?.message ?? "").toLowerCase();
2074
+ for (const rule of CORE_RULES) {
2075
+ if (rule.re.test(message)) {
2076
+ return CANONICAL_ERROR_CODES.has(rule.code) ? rule.code : GENERIC_FALLBACK;
2077
+ }
2078
+ }
2079
+ const haystack = `${error?.constructor?.name ?? "Error"} ${String(error?.message ?? "")}`.toLowerCase();
1606
2080
  for (const rule of SUPPLEMENTAL_RULES) {
1607
2081
  if (rule.re.test(haystack)) {
1608
2082
  return CANONICAL_ERROR_CODES.has(rule.code) ? rule.code : GENERIC_FALLBACK;
@@ -1618,6 +2092,9 @@ function storage() {
1618
2092
  function getContext() {
1619
2093
  return storage().getStore() ?? {};
1620
2094
  }
2095
+ function hasContextScope() {
2096
+ return storage().getStore() !== void 0;
2097
+ }
1621
2098
  function runWithContext(overrides, fn) {
1622
2099
  const parent = getContext();
1623
2100
  const merged = { ...parent, ...overrides };
@@ -1674,7 +2151,8 @@ function getCurrentContext() {
1674
2151
  // src/tracer.ts
1675
2152
  function attachErrorCode(span, error) {
1676
2153
  try {
1677
- const err = error instanceof Error ? error : new Error(String(error));
2154
+ const ownMessage = error !== null && typeof error === "object" ? error.message : void 0;
2155
+ const err = error instanceof Error ? error : new Error(typeof ownMessage === "string" ? ownMessage : String(error));
1678
2156
  const code = classifyError(err);
1679
2157
  if (code) {
1680
2158
  span.setAttribute("error.code", code);
@@ -1776,6 +2254,7 @@ var Tracer = class {
1776
2254
  (error) => {
1777
2255
  span.recordException(error instanceof Error ? error : String(error));
1778
2256
  attachErrorCode(span, error);
2257
+ markCancel(span, error);
1779
2258
  span.end();
1780
2259
  throw error;
1781
2260
  }
@@ -1786,6 +2265,7 @@ var Tracer = class {
1786
2265
  } catch (error) {
1787
2266
  span.recordException(error instanceof Error ? error : String(error));
1788
2267
  attachErrorCode(span, error);
2268
+ markCancel(span, error);
1789
2269
  span.end();
1790
2270
  throw error;
1791
2271
  }
@@ -1805,7 +2285,7 @@ var Tracer = class {
1805
2285
  const session2 = getCurrentSession();
1806
2286
  const agent2 = getCurrentAgent();
1807
2287
  const phase = getCurrentPhase();
1808
- const traceId = opts.traceId ?? parentSpan?.traceId ?? generateTraceId();
2288
+ const traceId = opts.traceId ?? parentSpan?.traceId ?? getContext()._rootTraceId ?? generateTraceId();
1809
2289
  if (!parentSpan) {
1810
2290
  if (getContext()._traceSampled === false) {
1811
2291
  return NOOP_SPAN;
@@ -1841,15 +2321,24 @@ var Tracer = class {
1841
2321
  );
1842
2322
  }
1843
2323
  };
2324
+ function markCancel(span, error) {
2325
+ if (error instanceof Error && error.name === "AbortError") {
2326
+ span.setAttribute("risicare.cancelled", true);
2327
+ span.setAttribute("risicare.cancel_type", "AbortError");
2328
+ }
2329
+ }
1844
2330
 
1845
2331
  // src/version.ts
1846
- var SDK_VERSION = "0.6.0";
2332
+ var SDK_VERSION = "0.8.0";
1847
2333
 
1848
2334
  // src/exporters/http.ts
1849
2335
  var CAPACITY_REFUSAL_STATUSES = /* @__PURE__ */ new Set([429, 503]);
1850
2336
  var RETRY_AFTER_CEILING_MS = 1e4;
1851
2337
  var REFUSAL_BACKOFF_BASE_MS = 1e3;
1852
2338
  var REFUSAL_NO_HINT = -1;
2339
+ var MISROUTE_WARN_WINDOW_MS = 3e5;
2340
+ var AUTH_REFUSAL_STATUSES = /* @__PURE__ */ new Set([401, 403]);
2341
+ var FAILURE_WARN_WINDOW_MS = 3e5;
1853
2342
  var HttpExporter = class {
1854
2343
  name = "http";
1855
2344
  _endpoint;
@@ -1865,18 +2354,24 @@ var HttpExporter = class {
1865
2354
  // cooldown gives the gateway time to come back before the half-open
1866
2355
  // probe fires. Lower numbers (was 3@30s) tripped on transient blips.
1867
2356
  _consecutiveFailures = 0;
2357
+ _lastMisrouteWarnAt = -Infinity;
2358
+ _lastFailureWarnAt = -Infinity;
1868
2359
  /**
1869
- * F-SDK503-001. Set by `_sendRequest` when a response is a CAPACITY REFUSAL, read by the
1870
- * retry loop and the breaker. `null` = not a refusal; `REFUSAL_NO_HINT` = refused with no
1871
- * `Retry-After`; otherwise the honoured delay in ms.
1872
- *
1873
- * ⚠ Node has ONE thread and `export()` is `async`, so two concurrent exports interleave on
1874
- * this field at every `await`. It is written immediately after the awaited `fetch` resolves
1875
- * and read on the very next statement, with no `await` between — so the value cannot be
1876
- * clobbered mid-decision. The Python twin carries the same per-call state on `self` for the
1877
- * same reason (its `_send_request` signature is pin-locked).
2360
+ * The kind of failure that the last outage WARNING named ('auth', 'http', 'none',
2361
+ * 'unknown'). `null` after a success. A new kind in the same outage writes one more
2362
+ * WARNING, also inside the window.
1878
2363
  */
1879
- _lastRefusalAfterMs = null;
2364
+ _failureKind = null;
2365
+ /** The endpoint as a log line may show it: no userinfo, no query (see `safeUrl`). */
2366
+ _safeEndpoint;
2367
+ /** The endpoint holds userinfo. `fetch` refuses such a URL. */
2368
+ _endpointHasCredentials;
2369
+ /** The calls in progress, by their batch, so that `abort(spans)` stops the right one. */
2370
+ _calls = /* @__PURE__ */ new Map();
2371
+ /** The ack of each finished call, by its batch. Read once by `takeAck(spans)`. */
2372
+ _acks = /* @__PURE__ */ new WeakMap();
2373
+ /** The spans of each finished call that could not be serialized, by its batch. */
2374
+ _unserializable = /* @__PURE__ */ new WeakMap();
1880
2375
  _circuitOpenUntil = 0;
1881
2376
  _circuitBreakerThreshold = 5;
1882
2377
  _circuitBreakerCooldownMs = 6e4;
@@ -1888,9 +2383,105 @@ var HttpExporter = class {
1888
2383
  this._timeoutMs = options.timeoutMs ?? 5e3;
1889
2384
  this._maxRetries = options.maxRetries ?? 3;
1890
2385
  this._compress = options.compress ?? false;
2386
+ this._safeEndpoint = safeUrl(this._endpoint);
2387
+ this._endpointHasCredentials = hasCredentials(this._endpoint);
1891
2388
  }
2389
+ /**
2390
+ * Network or error text for a log line: the endpoint as `safeUrl` gives it, and no
2391
+ * form of the API key (`utils/scrub.ts`).
2392
+ */
2393
+ _scrub(text, limit = 200) {
2394
+ let out;
2395
+ try {
2396
+ out = text instanceof Error ? `${text.name}: ${text.message}` : String(text);
2397
+ } catch {
2398
+ out = typeof text;
2399
+ }
2400
+ if (this._safeEndpoint !== this._endpoint) out = out.split(this._endpoint).join(this._safeEndpoint);
2401
+ return scrubText(out, [this._apiKey], limit);
2402
+ }
2403
+ /** Hide the key from `util.inspect` and `console.log` of the exporter. */
2404
+ [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
2405
+ return `HttpExporter { endpoint: '${this._safeEndpoint}' }`;
2406
+ }
2407
+ /** The most requests that one `export()` call sends (`maxRetries`). */
2408
+ get attemptsPerExport() {
2409
+ return this._maxRetries;
2410
+ }
2411
+ /**
2412
+ * Returns the counts of the ack that the `export()` call for `spans` received, and clears
2413
+ * them. The answer is kept per batch, not on the instance: two processors that share this
2414
+ * exporter cannot read each other's ack across an `await`.
2415
+ */
2416
+ takeAck(spans) {
2417
+ const ack = this._acks.get(spans) ?? null;
2418
+ this._acks.delete(spans);
2419
+ return ack;
2420
+ }
2421
+ /** Returns the spans of `spans` that could not be serialized and were not sent, and clears them. */
2422
+ takeUnserializable(spans) {
2423
+ const bad = this._unserializable.get(spans) ?? [];
2424
+ this._unserializable.delete(spans);
2425
+ return bad;
2426
+ }
2427
+ /**
2428
+ * Cancel the `export()` call for `spans` (all calls when `spans` is not given): its
2429
+ * request, its retries and its backoff sleep. The batch processor calls it when
2430
+ * `shutdown()` abandons the batch, so that the call does not keep the process alive. The
2431
+ * cancelled call returns FAILURE, changes no counter (the circuit breaker included) and
2432
+ * logs no WARNING.
2433
+ */
2434
+ abort(spans) {
2435
+ if (spans !== void 0) this._calls.get(spans)?.cancel.abort();
2436
+ else for (const call of this._calls.values()) call.cancel.abort();
2437
+ }
2438
+ /**
2439
+ * Send one batch. The limits are the request timeout and `maxRetries`.
2440
+ *
2441
+ * ⚠ NO CALLER BUDGET. `flush(timeoutMs)` only stops WAITING at its deadline; it never
2442
+ * cuts a request that is already sent. A short flush budget that cut the request made a
2443
+ * healthy, slow server look like a failure: the span used a retry, the breaker moved, and
2444
+ * the server stored the same spans again. Only `abort()` stops the call, and only
2445
+ * `shutdown()` calls it.
2446
+ */
1892
2447
  async export(spans) {
1893
2448
  if (spans.length === 0) return "success" /* SUCCESS */;
2449
+ const call = {
2450
+ cancel: new AbortController(),
2451
+ refusalAfterMs: null,
2452
+ misroute: null,
2453
+ noRetry: false,
2454
+ status: null,
2455
+ error: null
2456
+ };
2457
+ this._calls.set(spans, call);
2458
+ try {
2459
+ return await this._export(spans, call);
2460
+ } finally {
2461
+ this._calls.delete(spans);
2462
+ }
2463
+ }
2464
+ async _export(spans, call) {
2465
+ const cancelled = call.cancel.signal;
2466
+ const parts = [];
2467
+ const bad = [];
2468
+ let errorClass = "";
2469
+ for (const span of spans) {
2470
+ try {
2471
+ parts.push(JSON.stringify(span.toPayload()));
2472
+ } catch (e) {
2473
+ bad.push(span);
2474
+ errorClass ||= e instanceof Error ? e.name : typeof e;
2475
+ }
2476
+ }
2477
+ if (bad.length > 0) {
2478
+ this._unserializable.set(spans, bad);
2479
+ warn(
2480
+ `Risicare: ${bad.length} of ${spans.length} span(s) in this batch could not be serialized (${errorClass}), for example an attribute with a BigInt or a circular reference. They are not sent and are counted as dropped (reason=unacknowledged).`
2481
+ );
2482
+ }
2483
+ if (parts.length === 0) return "success" /* SUCCESS */;
2484
+ const payload = `{"spans":[${parts.join(",")}]` + (this._projectId ? `,"projectId":${JSON.stringify(this._projectId)}` : "") + (this._environment ? `,"environment":${JSON.stringify(this._environment)}` : "") + "}";
1894
2485
  const now = Date.now();
1895
2486
  let isHalfOpen = false;
1896
2487
  if (this._consecutiveFailures >= this._circuitBreakerThreshold) {
@@ -1899,34 +2490,64 @@ var HttpExporter = class {
1899
2490
  }
1900
2491
  isHalfOpen = true;
1901
2492
  }
1902
- const body = {
1903
- spans: spans.map((s) => s.toPayload())
1904
- };
1905
- if (this._projectId) body.projectId = this._projectId;
1906
- if (this._environment) body.environment = this._environment;
1907
2493
  const maxAttempts = isHalfOpen ? 1 : this._maxRetries;
2494
+ let attempts = 0;
1908
2495
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
1909
- this._lastRefusalAfterMs = null;
1910
- const result = await this._sendRequest(body);
2496
+ call.refusalAfterMs = null;
2497
+ call.misroute = null;
2498
+ call.noRetry = false;
2499
+ call.status = null;
2500
+ call.error = null;
2501
+ attempts++;
2502
+ const result = await this._sendRequest(payload, parts.length, call, spans);
2503
+ if (cancelled.aborted) {
2504
+ this._acks.delete(spans);
2505
+ return "failure" /* FAILURE */;
2506
+ }
1911
2507
  if (result === "success" /* SUCCESS */) {
1912
2508
  this._consecutiveFailures = 0;
2509
+ this._failureKind = null;
1913
2510
  return result;
1914
2511
  }
2512
+ if (call.misroute !== null || call.noRetry) break;
2513
+ if (call.status !== null && AUTH_REFUSAL_STATUSES.has(call.status)) break;
1915
2514
  if (attempt < maxAttempts - 1) {
1916
- const refusal = this._lastRefusalAfterMs;
2515
+ const refusal = call.refusalAfterMs;
1917
2516
  const delay = refusal === null ? 100 * Math.pow(2, attempt) : refusal === REFUSAL_NO_HINT ? REFUSAL_BACKOFF_BASE_MS * Math.pow(2, attempt) : refusal;
1918
- await sleep(delay);
2517
+ await sleep(delay, cancelled);
2518
+ if (cancelled.aborted) return "failure" /* FAILURE */;
1919
2519
  }
1920
2520
  }
1921
- const refusedForCapacity = this._lastRefusalAfterMs !== null;
1922
- this._lastRefusalAfterMs = null;
1923
- if (refusedForCapacity) {
2521
+ if (call.refusalAfterMs !== null) {
1924
2522
  warn(
1925
- `Risicare: the ingest endpoint refused this batch for capacity (HTTP 429/503) after ${maxAttempts} attempt(s). This is a healthy server shedding load, not an outage \u2014 the batch is dropped but the exporter keeps sending. Reduce batch size or export rate if it persists.`
2523
+ `Risicare: the ingest endpoint refused this batch for capacity (HTTP 429/503) after ${attempts} attempt(s). This is a healthy server shedding load, not an outage. This export of the batch failed; the circuit breaker does not count it. Reduce batch size or export rate if it persists.`
1926
2524
  );
1927
2525
  return "failure" /* FAILURE */;
1928
2526
  }
2527
+ const misroute = call.misroute;
2528
+ if (misroute !== null && Date.now() - this._lastMisrouteWarnAt > MISROUTE_WARN_WINDOW_MS) {
2529
+ this._lastMisrouteWarnAt = Date.now();
2530
+ warn(
2531
+ `Risicare: spans are NOT reaching ${this._safeEndpoint}. It answered POST /v1/spans with ${misroute}. That is not the Risicare ingest gateway, so the endpoint is probably wrong (for example the dashboard URL instead of the ingest gateway URL). The SDK does not follow redirects, and this batch is counted as NOT delivered. Set endpoint or RISICARE_ENDPOINT to the ingest gateway URL.`
2532
+ );
2533
+ }
1929
2534
  this._consecutiveFailures++;
2535
+ if (misroute === null && !call.noRetry) {
2536
+ const status = call.status;
2537
+ const kind = status !== null && AUTH_REFUSAL_STATUSES.has(status) ? "auth" : status !== null ? "http" : call.error !== null ? "none" : "unknown";
2538
+ let write = false;
2539
+ if (this._consecutiveFailures === 1 || this._failureKind === null) {
2540
+ if (Date.now() - this._lastFailureWarnAt > FAILURE_WARN_WINDOW_MS) {
2541
+ this._lastFailureWarnAt = Date.now();
2542
+ write = true;
2543
+ }
2544
+ this._failureKind = kind;
2545
+ } else if (kind !== this._failureKind) {
2546
+ this._failureKind = kind;
2547
+ write = true;
2548
+ }
2549
+ if (write) this._warnOutage(kind, status, call.error);
2550
+ }
1930
2551
  if (this._consecutiveFailures >= this._circuitBreakerThreshold) {
1931
2552
  this._circuitOpenUntil = Date.now() + this._circuitBreakerCooldownMs;
1932
2553
  warn(
@@ -1935,6 +2556,38 @@ var HttpExporter = class {
1935
2556
  }
1936
2557
  return "failure" /* FAILURE */;
1937
2558
  }
2559
+ /** The outage WARNING for one kind of failure. */
2560
+ _warnOutage(kind, status, error) {
2561
+ const where = `Risicare: spans are NOT reaching ${this._safeEndpoint}`;
2562
+ const tail = "Tracing continues, but the SDK drops the spans that it cannot send.";
2563
+ if (kind === "auth") {
2564
+ warn(
2565
+ `${where}: it answered HTTP ${status}. The endpoint refused the API key. Check the apiKey (or RISICARE_API_KEY) and the project it belongs to. ${tail}`
2566
+ );
2567
+ } else if (kind === "http") {
2568
+ warn(
2569
+ `${where}: it answered HTTP ${status}. The server did not take the batch. Check the endpoint and the server. ${tail} Set debug: true to see each attempt.`
2570
+ );
2571
+ } else if (kind === "none" && this._endpointHasCredentials) {
2572
+ warn(
2573
+ `${where}: no answer (${error}). The endpoint URL holds credentials (a user name or a password before the host), and fetch does not send a request to such a URL. Remove the credentials from the endpoint URL. ${tail}`
2574
+ );
2575
+ } else if (kind === "none") {
2576
+ warn(
2577
+ `${where}: no answer (${error}). The endpoint cannot be reached, or it did not answer in time. Check the endpoint and the network. ${tail} Set debug: true to see each attempt.`
2578
+ );
2579
+ } else {
2580
+ warn(
2581
+ `${where}: the export failed. Common causes: an invalid apiKey or an unreachable endpoint. ${tail} Set debug: true to see each attempt.`
2582
+ );
2583
+ }
2584
+ }
2585
+ /** Record a MISROUTE for the retry loop and the breaker. Always returns FAILURE. */
2586
+ _noteMisroute(call, answer) {
2587
+ call.misroute = this._scrub(answer, 300);
2588
+ debug(`Ingest misroute: ${call.misroute}`);
2589
+ return "failure" /* FAILURE */;
2590
+ }
1938
2591
  /**
1939
2592
  * Record a CAPACITY REFUSAL for the retry loop. Returns true if it was one.
1940
2593
  *
@@ -1942,7 +2595,7 @@ var HttpExporter = class {
1942
2595
  * HTTP-date); anything else falls back to our own backoff rather than guessing at a date
1943
2596
  * parse.
1944
2597
  */
1945
- _noteRefusal(status, retryAfterRaw) {
2598
+ _noteRefusal(call, status, retryAfterRaw) {
1946
2599
  if (!CAPACITY_REFUSAL_STATUSES.has(status)) return false;
1947
2600
  let delay = REFUSAL_NO_HINT;
1948
2601
  if (retryAfterRaw) {
@@ -1951,11 +2604,13 @@ var HttpExporter = class {
1951
2604
  delay = Math.min(secs * 1e3, RETRY_AFTER_CEILING_MS);
1952
2605
  }
1953
2606
  }
1954
- this._lastRefusalAfterMs = delay;
1955
- debug(`Ingest refused for capacity: HTTP ${status} (Retry-After=${retryAfterRaw})`);
2607
+ call.refusalAfterMs = delay;
2608
+ debug(`Ingest refused for capacity: HTTP ${status} (Retry-After=${this._scrub(retryAfterRaw)})`);
1956
2609
  return true;
1957
2610
  }
1958
- async _sendRequest(body) {
2611
+ async _sendRequest(body, spansSent, call, spans) {
2612
+ const cancelled = call.cancel.signal;
2613
+ const timeoutMs = this._timeoutMs;
1959
2614
  const url = `${this._endpoint}/v1/spans`;
1960
2615
  const headers = {
1961
2616
  "Content-Type": "application/json",
@@ -1970,83 +2625,156 @@ var HttpExporter = class {
1970
2625
  if (this._apiKey) {
1971
2626
  headers["Authorization"] = `Bearer ${this._apiKey}`;
1972
2627
  }
1973
- let payload = JSON.stringify(body);
2628
+ let payload = body;
1974
2629
  if (this._compress && payload.length > 1024) {
1975
2630
  try {
1976
2631
  const { gzipSync } = await import("zlib");
1977
2632
  payload = gzipSync(Buffer.from(payload));
1978
2633
  headers["Content-Encoding"] = "gzip";
1979
2634
  } catch (e) {
1980
- debug(`Gzip compression failed, sending uncompressed: ${e}`);
2635
+ debug(`Gzip compression failed, sending uncompressed: ${this._scrub(e)}`);
1981
2636
  }
1982
2637
  }
2638
+ const controller = new AbortController();
2639
+ const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
2640
+ const onCancel = () => controller.abort();
2641
+ cancelled.addEventListener("abort", onCancel, { once: true });
2642
+ if (cancelled.aborted) controller.abort();
1983
2643
  try {
1984
- const controller = new AbortController();
1985
- const timeoutId = setTimeout(() => controller.abort(), this._timeoutMs);
1986
2644
  const response = await fetch(url, {
1987
2645
  method: "POST",
1988
2646
  headers,
1989
2647
  body: payload,
1990
- signal: controller.signal
2648
+ signal: controller.signal,
2649
+ // Never follow: a redirect is a misroute (see MISROUTE_WARN_WINDOW_MS). Node returns
2650
+ // the 3xx itself; a browser-like runtime returns type 'opaqueredirect' with status 0.
2651
+ redirect: "manual"
1991
2652
  });
1992
- clearTimeout(timeoutId);
1993
- if (response.status < 300) {
1994
- return await checkAck(response);
2653
+ call.status = response.status;
2654
+ const redirected = response.type === "opaqueredirect";
2655
+ if (redirected || response.status >= 300 && response.status < 400) {
2656
+ const location = response.headers?.get?.("Location");
2657
+ const target = location ? this._scrub(location, 1e3) : "no Location header";
2658
+ return this._noteMisroute(call, `HTTP ${response.status || "3xx"}, a redirect to ${target}`);
2659
+ }
2660
+ if (response.status >= 200 && response.status < 300) {
2661
+ const ack = await checkAck(response, spansSent, (t) => this._scrub(t, 1e3));
2662
+ if (ack === null) {
2663
+ if (controller.signal.aborted) {
2664
+ call.status = null;
2665
+ call.error = `timeout after ${timeoutMs} ms`;
2666
+ debug(`HTTP export timeout: the ack body did not arrive within ${timeoutMs} ms`);
2667
+ return "timeout" /* TIMEOUT */;
2668
+ }
2669
+ return this._noteMisroute(
2670
+ call,
2671
+ `HTTP ${response.status} and a body that is not a Risicare ack (content-type: ${response.headers?.get?.("Content-Type") || "none"})`
2672
+ );
2673
+ }
2674
+ if (ack.result === "success" /* SUCCESS */) this._acks.set(spans, ack.counts);
2675
+ if (ack.final) call.noRetry = true;
2676
+ return ack.result;
1995
2677
  } else if (response.status === 408 || response.status === 504) {
1996
2678
  debug(`HTTP export timeout: ${response.status}`);
1997
2679
  return "timeout" /* TIMEOUT */;
1998
2680
  }
1999
- this._noteRefusal(response.status, response.headers.get("Retry-After"));
2681
+ this._noteRefusal(call, response.status, response.headers.get("Retry-After"));
2000
2682
  debug(`HTTP export failed: ${response.status}`);
2001
2683
  return "failure" /* FAILURE */;
2002
2684
  } catch (e) {
2003
- debug(`HTTP export error: ${e}`);
2685
+ const cause = e instanceof Error ? e.cause : void 0;
2686
+ call.error = controller.signal.aborted ? `timeout after ${timeoutMs} ms` : typeof cause?.code === "string" ? cause.code : e instanceof Error ? e.name : "Error";
2687
+ debug(`HTTP export error: ${this._scrub(e)}`);
2004
2688
  return "failure" /* FAILURE */;
2689
+ } finally {
2690
+ clearTimeout(timeoutId);
2691
+ cancelled.removeEventListener("abort", onCancel);
2005
2692
  }
2006
2693
  }
2007
2694
  shutdown() {
2008
2695
  }
2009
2696
  };
2010
- function sleep(ms) {
2011
- return new Promise((resolve) => setTimeout(resolve, ms));
2697
+ function sleep(ms, signal) {
2698
+ return new Promise((resolve) => {
2699
+ if (signal?.aborted) return resolve();
2700
+ const done = () => {
2701
+ clearTimeout(timer);
2702
+ signal?.removeEventListener("abort", done);
2703
+ resolve();
2704
+ };
2705
+ const timer = setTimeout(done, ms);
2706
+ signal?.addEventListener("abort", done, { once: true });
2707
+ });
2012
2708
  }
2013
2709
  function asCount(v) {
2014
2710
  return typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : void 0;
2015
2711
  }
2016
- async function checkAck(response) {
2712
+ var MAX_ACK_REASONS = 3;
2713
+ var MAX_ACK_REASON_CHARS = 200;
2714
+ function oneLine(text) {
2715
+ return text.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ");
2716
+ }
2717
+ function ackReasons(body) {
2718
+ const reasons = [];
2719
+ const errors = body.errors;
2720
+ if (Array.isArray(errors)) {
2721
+ for (const entry of errors) {
2722
+ const text = entry?.error;
2723
+ if (typeof text !== "string" || text.length === 0) continue;
2724
+ const cut = oneLine(text).slice(0, MAX_ACK_REASON_CHARS);
2725
+ if (!reasons.includes(cut)) reasons.push(cut);
2726
+ if (reasons.length === MAX_ACK_REASONS) break;
2727
+ }
2728
+ }
2729
+ if (reasons.length === 0) {
2730
+ const message = typeof body.errorMessage === "string" && body.errorMessage || typeof body.error_message === "string" && body.error_message || "";
2731
+ if (message) reasons.push(oneLine(message).slice(0, MAX_ACK_REASON_CHARS));
2732
+ }
2733
+ return reasons.length === 0 ? "No reason was returned." : `Reasons: ${reasons.join("; ")}`;
2734
+ }
2735
+ async function checkAck(response, spansSent, scrub) {
2017
2736
  let payload;
2018
2737
  try {
2019
2738
  payload = await response.json();
2020
2739
  } catch {
2021
- return "success" /* SUCCESS */;
2740
+ return null;
2022
2741
  }
2023
2742
  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
2024
- return "success" /* SUCCESS */;
2743
+ return null;
2025
2744
  }
2026
2745
  const body = payload;
2027
2746
  const accepted = asCount(body.accepted);
2028
2747
  const rejected = asCount(body.rejected);
2029
- if (accepted === void 0 || rejected === void 0 || rejected <= 0) {
2030
- return "success" /* SUCCESS */;
2748
+ if (accepted === void 0 || rejected === void 0) return null;
2749
+ const counts = { accepted, rejected };
2750
+ if (accepted === 0 && rejected === 0 && spansSent > 0) {
2751
+ warn(
2752
+ `Risicare: the backend acknowledged 0 of ${spansSent} span(s): its ack counts no span as accepted or rejected. This batch is counted as NOT delivered.`
2753
+ );
2754
+ return { result: "failure" /* FAILURE */, counts, final: true };
2031
2755
  }
2032
- const errors = body.errors;
2033
- const detail = typeof body.errorMessage === "string" && body.errorMessage || typeof body.error_message === "string" && body.error_message || (Array.isArray(errors) && errors.length > 0 ? JSON.stringify(errors[0]) : "") || "No reason was returned.";
2756
+ if (rejected === 0) return { result: "success" /* SUCCESS */, counts, final: false };
2034
2757
  const total = accepted + rejected;
2035
2758
  if (accepted === 0) {
2036
2759
  warn(
2037
- `Risicare: the backend accepted 0 of ${total} span(s) and rejected ${rejected} \u2014 this batch was NOT stored. ${detail}`
2760
+ `Risicare: the backend accepted 0 of ${total} span(s) and rejected ${rejected} \u2014 this batch was NOT stored. Rejected spans are permanently lost and are NOT retried. ${scrub(ackReasons(body))}`
2038
2761
  );
2039
- return "failure" /* FAILURE */;
2762
+ return { result: "success" /* SUCCESS */, counts, final: false };
2040
2763
  }
2041
2764
  warn(
2042
- `Risicare: the backend rejected ${rejected} of ${total} span(s); the remaining ${accepted} were stored. Those ${rejected} are permanently lost and are NOT retried. ${detail}`
2765
+ `Risicare: the backend rejected ${rejected} of ${total} span(s); the remaining ${accepted} were stored. Those ${rejected} are permanently lost and are NOT retried. ${scrub(ackReasons(body))}`
2043
2766
  );
2044
- return "success" /* SUCCESS */;
2767
+ return { result: "success" /* SUCCESS */, counts, final: false };
2045
2768
  }
2046
2769
 
2047
2770
  // src/exporters/console.ts
2048
2771
  var ConsoleExporter = class {
2049
2772
  name = "console";
2773
+ /**
2774
+ * It only shows spans locally, so its success is not a delivery. When another
2775
+ * exporter is present, the batch processor ignores this exporter's result.
2776
+ */
2777
+ countsAsDelivery = false;
2050
2778
  export(spans) {
2051
2779
  for (const span of spans) {
2052
2780
  const payload = span.toPayload();
@@ -2060,6 +2788,17 @@ var ConsoleExporter = class {
2060
2788
  }
2061
2789
  };
2062
2790
 
2791
+ // src/utils/stream-proxy.ts
2792
+ function endOpenProviderSpans() {
2793
+ let open;
2794
+ try {
2795
+ open = [...getProviderSpanState().open];
2796
+ } catch {
2797
+ return;
2798
+ }
2799
+ for (const o of open) o.end("shutdown");
2800
+ }
2801
+
2063
2802
  // src/runtime/cache.ts
2064
2803
  var FixCache = class {
2065
2804
  _ttlMs;
@@ -2235,6 +2974,94 @@ function emptyResult(fix, fixType) {
2235
2974
  modifications: {}
2236
2975
  };
2237
2976
  }
2977
+ var SAME_ESCAPES = "bBdDsSwWfnrtv";
2978
+ var SAME_ESCAPES_IN_CLASS = "bdDsSwWfnrtv";
2979
+ var LEADING_INLINE_FLAGS = /^\(\?([ims]+)\)/;
2980
+ var PY_NAMED_GROUP = /^\(\?P<([A-Za-z_][A-Za-z0-9_]*)>/;
2981
+ var PY_NAMED_BACKREF = /^\(\?P=([A-Za-z_][A-Za-z0-9_]*)\)/;
2982
+ var JS_NAMED_GROUP = /^\(\?<([A-Za-z_][A-Za-z0-9_]*)>/;
2983
+ function translatePythonPattern(pattern) {
2984
+ let flags = "i";
2985
+ let rest = pattern;
2986
+ const m = LEADING_INLINE_FLAGS.exec(rest);
2987
+ if (m) {
2988
+ for (const f of m[1]) if (!flags.includes(f)) flags += f;
2989
+ rest = rest.slice(m[0].length);
2990
+ }
2991
+ const names = /* @__PURE__ */ new Set();
2992
+ const addName = (name) => {
2993
+ if (names.has(name)) throw new Error("a group name occurs two times");
2994
+ names.add(name);
2995
+ };
2996
+ let source = "";
2997
+ let inClass = false;
2998
+ for (let i = 0; i < rest.length; i++) {
2999
+ const c = rest[i];
3000
+ if (c === "\\" && i + 1 < rest.length) {
3001
+ const next = rest[i + 1];
3002
+ if (/[A-Za-z]/.test(next)) {
3003
+ if (!inClass && next === "A") {
3004
+ source += "(?<![\\s\\S])";
3005
+ i++;
3006
+ continue;
3007
+ }
3008
+ if (!inClass && next === "Z") {
3009
+ source += "(?![\\s\\S])";
3010
+ i++;
3011
+ continue;
3012
+ }
3013
+ if (next === "x" || next === "u") {
3014
+ const n = next === "x" ? 2 : 4;
3015
+ const hex = rest.slice(i + 2, i + 2 + n);
3016
+ if (!new RegExp(`^[0-9A-Fa-f]{${n}}$`).test(hex)) throw new Error("short hex escape");
3017
+ source += c + next + hex;
3018
+ i += 1 + n;
3019
+ continue;
3020
+ }
3021
+ if (!(inClass ? SAME_ESCAPES_IN_CLASS : SAME_ESCAPES).includes(next)) {
3022
+ throw new Error("an escape that Python and JavaScript read differently");
3023
+ }
3024
+ }
3025
+ source += c + next;
3026
+ i++;
3027
+ continue;
3028
+ }
3029
+ if (inClass) {
3030
+ if (c === "]") inClass = false;
3031
+ source += c;
3032
+ continue;
3033
+ }
3034
+ if (c === "[") {
3035
+ inClass = true;
3036
+ source += c;
3037
+ continue;
3038
+ }
3039
+ const tail = rest.slice(i);
3040
+ let g;
3041
+ if ((g = PY_NAMED_GROUP.exec(tail)) || (g = JS_NAMED_GROUP.exec(tail))) {
3042
+ addName(g[1]);
3043
+ source += `(?<${g[1]}>`;
3044
+ i += g[0].length - 1;
3045
+ continue;
3046
+ }
3047
+ if (g = PY_NAMED_BACKREF.exec(tail)) {
3048
+ source += `\\k<${g[1]}>`;
3049
+ i += g[0].length - 1;
3050
+ continue;
3051
+ }
3052
+ source += c;
3053
+ }
3054
+ return { source, flags };
3055
+ }
3056
+ var warnedGuardPatterns = /* @__PURE__ */ new Set();
3057
+ function warnUnusablePattern(fixId, index) {
3058
+ const key = `${fixId ?? "unknown"}\0${index}`;
3059
+ if (warnedGuardPatterns.has(key)) return;
3060
+ warnedGuardPatterns.add(key);
3061
+ warn(
3062
+ index < 0 ? `Guard fix ${fixId ?? "unknown"}: blocked_patterns is not a list. The guard rejects every call.` : `Guard fix ${fixId ?? "unknown"}: blocked pattern ${index} is not usable (empty, not a string, longer than 500 characters, or it does not compile). The guard rejects every call.`
3063
+ );
3064
+ }
2238
3065
  var FixApplier = class {
2239
3066
  _config;
2240
3067
  _cache;
@@ -2492,6 +3319,26 @@ var FixApplier = class {
2492
3319
  * - content_filter: Regex-based blocked patterns
2493
3320
  * - format_check: JSON.parse() validity
2494
3321
  * - input_validation / output_validation: min/max length
3322
+ *
3323
+ * `content_filter` searches the content for each entry of `blocked_patterns`
3324
+ * (case-insensitive, after `translatePythonPattern`). It fails CLOSED: when
3325
+ * `blocked_patterns` is not a list, or an entry is empty, is not a string,
3326
+ * is longer than 500 characters or cannot be used, the guard does not pass.
3327
+ * One WARNING names the fix id and the pattern index, once for each pair in
3328
+ * the process. The reason names the pattern index, never the pattern or the
3329
+ * content.
3330
+ *
3331
+ * Limits:
3332
+ * - The interceptor runs only on the OpenAI chat patch (input guards) and on
3333
+ * `interceptCall` / `interceptResponse`. It does not run when a framework
3334
+ * integration suppresses provider instrumentation.
3335
+ * - Each SDK uses its own regular-expression engine. These constructs can
3336
+ * give a different result in JavaScript and Python: `$` before a final
3337
+ * newline, Unicode case folding, `\d` and `\w` on non-ASCII text,
3338
+ * `\N{...}` and `\U........` (JavaScript fails closed), and a `]` first
3339
+ * in a class.
3340
+ * - A pattern has no time bound. A pattern with nested repeats can take a
3341
+ * very long time on a long input.
2495
3342
  */
2496
3343
  applyGuardFix(fix, content, isInput = true) {
2497
3344
  try {
@@ -2512,13 +3359,25 @@ var FixApplier = class {
2512
3359
  let passed = true;
2513
3360
  let reason;
2514
3361
  if (guardType === "content_filter") {
2515
- const blockedPatterns = guardConfig.blocked_patterns ?? guardConfig.blockedPatterns ?? [];
2516
- for (const pattern of blockedPatterns) {
2517
- const regex = this._safeCompileRegex(pattern);
2518
- if (regex && regex.test(content)) {
2519
- passed = false;
2520
- reason = `blocked pattern matched: ${pattern.slice(0, 80)}`;
2521
- break;
3362
+ const blockedPatterns = "blocked_patterns" in guardConfig ? guardConfig.blocked_patterns : "blockedPatterns" in guardConfig ? guardConfig.blockedPatterns : [];
3363
+ if (!Array.isArray(blockedPatterns)) {
3364
+ warnUnusablePattern(fix.fixId, -1);
3365
+ passed = false;
3366
+ reason = "blocked_patterns is not a list";
3367
+ } else {
3368
+ for (let index = 0; index < blockedPatterns.length; index++) {
3369
+ const regex = this._safeCompileRegex(blockedPatterns[index]);
3370
+ if (!regex) {
3371
+ warnUnusablePattern(fix.fixId, index);
3372
+ passed = false;
3373
+ reason = `blocked pattern ${index} is not usable`;
3374
+ break;
3375
+ }
3376
+ if (regex.test(content)) {
3377
+ passed = false;
3378
+ reason = `blocked pattern matched (pattern ${index})`;
3379
+ break;
3380
+ }
2522
3381
  }
2523
3382
  }
2524
3383
  } else if (guardType === "format_check") {
@@ -2579,11 +3438,17 @@ var FixApplier = class {
2579
3438
  /**
2580
3439
  * Safely compile a regex pattern from untrusted input.
2581
3440
  * Returns null if invalid or too long.
3441
+ *
3442
+ * F-029: the fix patterns are written for Python `re`. Before it compiles
3443
+ * the pattern, this function translates the Python forms that have an exact
3444
+ * JavaScript equivalent (see `translatePythonPattern`). The `i` flag is
3445
+ * always on, as in the Python applier.
2582
3446
  */
2583
3447
  _safeCompileRegex(pattern, maxLength = 500) {
2584
- if (!pattern || pattern.length > maxLength) return null;
3448
+ if (typeof pattern !== "string" || !pattern || pattern.length > maxLength) return null;
2585
3449
  try {
2586
- return new RegExp(pattern, "i");
3450
+ const { source, flags } = translatePythonPattern(pattern);
3451
+ return new RegExp(source, flags);
2587
3452
  } catch {
2588
3453
  debug(`Invalid regex pattern (length=${pattern.length})`);
2589
3454
  return null;
@@ -2659,6 +3524,8 @@ var FixLoader = class _FixLoader {
2659
3524
  _consecutiveFailures = 0;
2660
3525
  _circuitOpenUntil = 0;
2661
3526
  _onLoadCallbacks = [];
3527
+ // The HTTP status of the last load that got a non-2xx answer; null otherwise.
3528
+ _lastStatus = null;
2662
3529
  // Circuit breaker settings
2663
3530
  static CIRCUIT_BREAKER_THRESHOLD = 3;
2664
3531
  static CIRCUIT_BREAKER_COOLDOWN_MS = 3e4;
@@ -2666,6 +3533,43 @@ var FixLoader = class _FixLoader {
2666
3533
  this._config = resolveFixRuntimeConfig(config);
2667
3534
  this._cache = cache;
2668
3535
  }
3536
+ /** Error text for a log line: one line, the api endpoint as `safeUrl` gives it, no key. */
3537
+ _scrub(error) {
3538
+ let out;
3539
+ try {
3540
+ out = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
3541
+ } catch {
3542
+ out = typeof error;
3543
+ }
3544
+ const endpoint = (this._config.apiEndpoint ?? "").replace(/\/+$/, "");
3545
+ if (endpoint && safeUrl(endpoint) !== endpoint) out = out.split(endpoint).join(safeUrl(endpoint));
3546
+ return scrubText(out, [this._config.apiKey]);
3547
+ }
3548
+ /**
3549
+ * The WARNING for a failed first load: the request URL with no userinfo, no
3550
+ * query and no key, the HTTP status or the error class, and that tracing is
3551
+ * not affected. Never the error text: it can echo the URL with its query.
3552
+ */
3553
+ _firstLoadWarning(error) {
3554
+ let cause;
3555
+ if (this._lastStatus !== null) {
3556
+ cause = `HTTP ${this._lastStatus}`;
3557
+ } else {
3558
+ cause = error instanceof Error ? error.name : typeof error;
3559
+ const code = error?.cause?.code;
3560
+ if (typeof code === "string" && /^[A-Z][A-Z0-9_]*$/.test(code)) cause += ` (${code})`;
3561
+ }
3562
+ const endpoint = (this._config.apiEndpoint ?? "").replace(/\/+$/, "");
3563
+ return scrubText(
3564
+ `The first load of the fixes from ${safeUrl(endpoint)}/v1/fixes/active failed (${cause}). No fix is applied until a later load succeeds. Tracing is not affected.`,
3565
+ [this._config.apiKey],
3566
+ 500
3567
+ );
3568
+ }
3569
+ /** Hide the key from `util.inspect` and `console.log` of the loader. */
3570
+ [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
3571
+ return "FixLoader {}";
3572
+ }
2669
3573
  /** Timestamp of last successful load. */
2670
3574
  get lastLoadTime() {
2671
3575
  return this._lastLoadTime;
@@ -2686,13 +3590,13 @@ var FixLoader = class _FixLoader {
2686
3590
  return;
2687
3591
  }
2688
3592
  this.loadSync().catch((e) => {
2689
- debug(`Initial fix load failed: ${e}`);
3593
+ warn(this._firstLoadWarning(e));
2690
3594
  });
2691
3595
  if (this._config.autoRefresh) {
2692
3596
  this._startRefreshInterval();
2693
3597
  }
2694
3598
  } catch (e) {
2695
- debug(`FixLoader.start error: ${e}`);
3599
+ debug(`FixLoader.start error: ${this._scrub(e)}`);
2696
3600
  }
2697
3601
  }
2698
3602
  /** Stop the loader: clear the refresh interval. */
@@ -2703,7 +3607,7 @@ var FixLoader = class _FixLoader {
2703
3607
  this._refreshTimer = null;
2704
3608
  }
2705
3609
  } catch (e) {
2706
- debug(`FixLoader.stop error: ${e}`);
3610
+ debug(`FixLoader.stop error: ${this._scrub(e)}`);
2707
3611
  }
2708
3612
  }
2709
3613
  /**
@@ -2727,9 +3631,10 @@ var FixLoader = class _FixLoader {
2727
3631
  debug("Fix loader circuit breaker open \u2014 skipping load");
2728
3632
  return this._cache.getAll();
2729
3633
  }
3634
+ this._lastStatus = null;
2730
3635
  try {
2731
3636
  const endpoint = this._config.apiEndpoint.replace(/\/+$/, "");
2732
- const url = `${endpoint}/api/v1/fixes/active`;
3637
+ const url = `${endpoint}/v1/fixes/active`;
2733
3638
  const controller = new AbortController();
2734
3639
  const timeoutId = setTimeout(
2735
3640
  () => controller.abort(),
@@ -2746,6 +3651,7 @@ var FixLoader = class _FixLoader {
2746
3651
  });
2747
3652
  clearTimeout(timeoutId);
2748
3653
  if (!response.ok) {
3654
+ this._lastStatus = response.status;
2749
3655
  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
2750
3656
  }
2751
3657
  const data = await response.json();
@@ -2772,7 +3678,7 @@ var FixLoader = class _FixLoader {
2772
3678
  fixes.push(activeFixFromApiResponse(item));
2773
3679
  }
2774
3680
  } catch (e) {
2775
- debug(`Failed to parse fix item: ${e}`);
3681
+ debug(`Failed to parse fix item: ${this._scrub(e)}`);
2776
3682
  }
2777
3683
  }
2778
3684
  return fixes;
@@ -2785,7 +3691,7 @@ var FixLoader = class _FixLoader {
2785
3691
  try {
2786
3692
  callback(fixes);
2787
3693
  } catch (e) {
2788
- debug(`Load callback error: ${e}`);
3694
+ debug(`Load callback error: ${this._scrub(e)}`);
2789
3695
  }
2790
3696
  }
2791
3697
  debug(`Loaded ${fixes.length} active fixes`);
@@ -2799,14 +3705,14 @@ var FixLoader = class _FixLoader {
2799
3705
  );
2800
3706
  } else {
2801
3707
  debug(
2802
- `Fix load failed (attempt ${this._consecutiveFailures}): ${error.message}`
3708
+ `Fix load failed (attempt ${this._consecutiveFailures}): ${this._scrub(error)}`
2803
3709
  );
2804
3710
  }
2805
3711
  }
2806
3712
  _startRefreshInterval() {
2807
3713
  const tick = () => {
2808
3714
  this.loadSync().catch((e) => {
2809
- debug(`Background fix refresh failed: ${e}`);
3715
+ debug(`Background fix refresh failed: ${this._scrub(e)}`);
2810
3716
  });
2811
3717
  };
2812
3718
  this._refreshTimer = setInterval(
@@ -3074,6 +3980,78 @@ var TERMINATING_SIGNALS = [
3074
3980
  ];
3075
3981
  var BACKSTOP_MARGIN_MS = 500;
3076
3982
  var _finalMetrics;
3983
+ var SCORE_TIMEOUT_MS = 2e3;
3984
+ var _pendingScores = /* @__PURE__ */ new Set();
3985
+ var _failedScores = 0;
3986
+ var _failedScoresFlushMark = 0;
3987
+ var SCORE_MAX_IN_FLIGHT = 50;
3988
+ var SCORE_MAX_WAITING = 1e3;
3989
+ var SCORE_CAP_REASON = `not sent: ${SCORE_MAX_WAITING} scores wait for a free slot`;
3990
+ var SCORE_DEADLINE_REASON = "not sent before the deadline";
3991
+ var _scoresInFlight = 0;
3992
+ var _scoreWaiters = [];
3993
+ function _startWaitingScores() {
3994
+ while (_scoresInFlight < SCORE_MAX_IN_FLIGHT && _scoreWaiters.length > 0) {
3995
+ _scoreWaiters.shift().start();
3996
+ }
3997
+ }
3998
+ function _failWaitingScores(reason) {
3999
+ for (const waiter of _scoreWaiters.splice(0)) waiter.fail(reason);
4000
+ }
4001
+ var _scoreWarnWindowMs = 1e4;
4002
+ var SCORE_NAME_MAX = 200;
4003
+ var _scoreWarnedAt;
4004
+ var _scoreHeld = 0;
4005
+ var _scoreHeldReason = "";
4006
+ function _resetScoreFailures() {
4007
+ _failedScores = 0;
4008
+ _failedScoresFlushMark = 0;
4009
+ _scoreWarnedAt = void 0;
4010
+ _scoreHeld = 0;
4011
+ _scoreHeldReason = "";
4012
+ }
4013
+ function _heldText() {
4014
+ return ` ${_scoreHeld} more scores failed after the last warning. The last reason: ${_scoreHeldReason}.`;
4015
+ }
4016
+ function _scoreFailed(name, reason) {
4017
+ _failedScores += 1;
4018
+ const now = Date.now();
4019
+ if (_scoreWarnedAt !== void 0 && now - _scoreWarnedAt < _scoreWarnWindowMs) {
4020
+ _scoreHeld += 1;
4021
+ _scoreHeldReason = reason;
4022
+ return;
4023
+ }
4024
+ let message = `score ${JSON.stringify(name.slice(0, SCORE_NAME_MAX))} failed: ${reason}.`;
4025
+ if (_scoreHeld > 0) message += _heldText();
4026
+ _scoreWarnedAt = now;
4027
+ _scoreHeld = 0;
4028
+ _scoreHeldReason = "";
4029
+ warn(message);
4030
+ }
4031
+ function _warnHeldScores() {
4032
+ if (_scoreHeld === 0) return;
4033
+ const message = _heldText().trimStart();
4034
+ _scoreWarnedAt = Date.now();
4035
+ _scoreHeld = 0;
4036
+ _scoreHeldReason = "";
4037
+ warn(message);
4038
+ }
4039
+ async function _waitForPendingScores(timeoutMs) {
4040
+ if (_pendingScores.size === 0) return true;
4041
+ let timer;
4042
+ const expired = new Promise((resolve) => {
4043
+ timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
4044
+ });
4045
+ const settled = (async () => {
4046
+ while (_pendingScores.size > 0) await Promise.all([..._pendingScores]);
4047
+ return true;
4048
+ })();
4049
+ try {
4050
+ return await Promise.race([settled, expired]);
4051
+ } finally {
4052
+ clearTimeout(timer);
4053
+ }
4054
+ }
3077
4055
  var RisicareClient = class {
3078
4056
  config;
3079
4057
  processor;
@@ -3086,8 +4064,17 @@ var RisicareClient = class {
3086
4064
  _shutdownHandlers = [];
3087
4065
  constructor(config) {
3088
4066
  this.config = resolveConfig(config);
3089
- if (this.config.apiKey && !this.config.apiKey.startsWith("rsk-")) {
3090
- debug('Warning: API key should start with "rsk-". Got: ' + this.config.apiKey.slice(0, 4) + "...");
4067
+ const hasKnownPrefix = this.config.apiKey?.startsWith("rsk-") || this.config.apiKey?.startsWith("rski_") || this.config.apiKey?.startsWith("rsks_");
4068
+ if (this.config.apiKey && !hasKnownPrefix) {
4069
+ warn(
4070
+ 'the API key does not look like a Risicare key: it should start with "rsk-", "rski_" or "rsks_". Tracing continues with this key.'
4071
+ );
4072
+ }
4073
+ const tracingSetExplicitly = config?.enabled !== void 0 || (process.env.RISICARE_TRACING ?? "").trim() !== "";
4074
+ if (!this.config.apiKey && !this.config.enabled && !tracingSetExplicitly) {
4075
+ warn(
4076
+ "Risicare found no API key. Tracing is off and the SDK sends no span. Pass apiKey to init() or set RISICARE_API_KEY."
4077
+ );
3091
4078
  }
3092
4079
  let exporter;
3093
4080
  if (this.config.debug && !this.config.apiKey) {
@@ -3141,31 +4128,38 @@ var RisicareClient = class {
3141
4128
  serviceVersion: this.config.serviceVersion
3142
4129
  });
3143
4130
  this.processor.start();
3144
- if (this.config.apiKey && this.config.enabled) {
4131
+ if (this.config.apiKey && this.config.enabled && this.config.fixRuntime) {
3145
4132
  try {
3146
4133
  initFixRuntime({
3147
- apiEndpoint: this.config.endpoint,
4134
+ apiEndpoint: this.config.apiEndpoint,
3148
4135
  apiKey: this.config.apiKey,
3149
4136
  enabled: true,
3150
4137
  debug: this.config.debug
3151
4138
  });
3152
4139
  } catch (e) {
3153
4140
  const errName = e instanceof Error ? e.name : "Error";
3154
- const errMsg = e instanceof Error ? e.message : String(e);
4141
+ const errMsg = scrubText(e instanceof Error ? e.message : String(e), [this.config.apiKey]);
3155
4142
  try {
3156
4143
  console.warn(
3157
- `[risicare] FixRuntime initialization failed \u2014 auto-fix is OFFLINE for this process. endpoint=${this.config.endpoint} error=${errName}: ${errMsg}. Tracing + reporting still work; only fix application is disabled. Pass debug:true in init() options for the full traceback.`
4144
+ `[risicare] FixRuntime initialization failed \u2014 auto-fix is OFFLINE for this process. apiEndpoint=${safeUrl(this.config.apiEndpoint)} error=${errName}: ${errMsg}. Tracing + reporting still work; only fix application is disabled. Pass debug:true in init() options for the full traceback.`
3158
4145
  );
3159
4146
  } catch {
3160
4147
  }
3161
4148
  if (this.config.debug) {
3162
- debug(`FixRuntime init traceback: ${e instanceof Error && e.stack ? e.stack : String(e)}`);
4149
+ debug(
4150
+ `FixRuntime init traceback: ${scrubText(e instanceof Error && e.stack ? e.stack : String(e), [this.config.apiKey], 2e3)}`
4151
+ );
3163
4152
  }
3164
4153
  }
3165
4154
  }
3166
4155
  this._registerShutdownHooks();
3167
4156
  setDebug(this.config.debug);
3168
- debug(`Initialized: enabled=${this.config.enabled}, endpoint=${this.config.endpoint}`);
4157
+ debug(`Initialized: enabled=${this.config.enabled}, endpoint=${safeUrl(this.config.endpoint)}`);
4158
+ if (!this.config.fixRuntime) {
4159
+ debug(
4160
+ "FixRuntime is off: nothing polls /fixes/active and no fix is applied. Opt in with fixRuntime: true or RISICARE_FIX_RUNTIME=true."
4161
+ );
4162
+ }
3169
4163
  }
3170
4164
  get enabled() {
3171
4165
  return this.tracer.enabled;
@@ -3174,18 +4168,20 @@ var RisicareClient = class {
3174
4168
  this.tracer.enabled = value;
3175
4169
  }
3176
4170
  // Audit #6: Promise-based shutdown dedup (fixes TOCTOU race condition)
3177
- async shutdown() {
4171
+ async shutdown(timeoutMs) {
3178
4172
  if (this._shutdownPromise) return this._shutdownPromise;
3179
- this._shutdownPromise = this._doShutdown();
4173
+ this._shutdownPromise = this._doShutdown(timeoutMs);
3180
4174
  return this._shutdownPromise;
3181
4175
  }
3182
- async _doShutdown() {
4176
+ async _doShutdown(timeoutMs) {
3183
4177
  debug("Shutting down...");
3184
4178
  for (const { signal, handler } of this._shutdownHandlers) {
3185
4179
  process.removeListener(signal, handler);
3186
4180
  }
3187
4181
  this._shutdownHandlers = [];
3188
- await this.processor.shutdown();
4182
+ endOpenProviderSpans();
4183
+ await this.processor.shutdown(timeoutMs);
4184
+ _failWaitingScores(SCORE_DEADLINE_REASON);
3189
4185
  this.isShutdown = true;
3190
4186
  _finalMetrics = this.processor.getMetrics();
3191
4187
  }
@@ -3200,8 +4196,8 @@ var RisicareClient = class {
3200
4196
  * false one — both leave the customer unable to tell *drained* from
3201
4197
  * *discarded*.
3202
4198
  */
3203
- async flush() {
3204
- return this.processor.flush();
4199
+ async flush(timeoutMs) {
4200
+ return this.processor.flush(timeoutMs);
3205
4201
  }
3206
4202
  /**
3207
4203
  * SDK-RELEASE-RULING.md §3 — who decides whether the process dies.
@@ -3299,25 +4295,39 @@ function init(config) {
3299
4295
  return;
3300
4296
  }
3301
4297
  _finalMetrics = void 0;
4298
+ _resetScoreFailures();
3302
4299
  const client = new RisicareClient(config);
3303
4300
  setClient(client);
3304
4301
  setTracer(client.tracer);
3305
4302
  }
3306
- async function shutdown() {
4303
+ async function shutdown(timeoutMs) {
3307
4304
  try {
3308
4305
  shutdownFixRuntime();
3309
4306
  } catch {
3310
4307
  }
3311
4308
  const client = getClient();
3312
4309
  if (!client) return;
3313
- await client.shutdown();
4310
+ await client.shutdown(timeoutMs);
3314
4311
  setClient(void 0);
3315
4312
  setTracer(void 0);
3316
4313
  }
3317
- async function flush() {
4314
+ async function flush(timeoutMs) {
4315
+ const budgetMs = normalizeTimeoutMs(timeoutMs);
4316
+ const deadline = Date.now() + budgetMs;
4317
+ const scoreMark = _failedScoresFlushMark;
3318
4318
  const client = getClient();
3319
- if (!client) return true;
3320
- return client.flush();
4319
+ let spansOk;
4320
+ if (!client) {
4321
+ spansOk = (_finalMetrics?.droppedSpansByReason.shutdown_residue ?? 0) === 0;
4322
+ } else {
4323
+ spansOk = await client.flush(timeoutMs);
4324
+ }
4325
+ const scoresDone = await _waitForPendingScores(deadline - Date.now());
4326
+ if (!scoresDone) _failWaitingScores(SCORE_DEADLINE_REASON);
4327
+ _warnHeldScores();
4328
+ const failedNow = _failedScores;
4329
+ if (failedNow > _failedScoresFlushMark) _failedScoresFlushMark = failedNow;
4330
+ return spansOk && scoresDone && failedNow <= scoreMark;
3321
4331
  }
3322
4332
  function enable() {
3323
4333
  const client = getClient();
@@ -3341,22 +4351,30 @@ function getTraceContent() {
3341
4351
  function getMetrics() {
3342
4352
  const client = getClient();
3343
4353
  if (client && !client.isShutdown) {
3344
- return { ...client.processor.getMetrics(), sdkState: "running" };
4354
+ return {
4355
+ ...client.processor.getMetrics(),
4356
+ failedScores: _failedScores,
4357
+ sdkState: "running"
4358
+ };
3345
4359
  }
3346
4360
  if (_finalMetrics) {
3347
4361
  return {
3348
4362
  ..._finalMetrics,
4363
+ failedScores: _failedScores,
3349
4364
  droppedSpansByReason: { ..._finalMetrics.droppedSpansByReason },
3350
4365
  sdkState: "shutdown"
3351
4366
  };
3352
4367
  }
3353
4368
  return {
3354
4369
  exportedSpans: 0,
4370
+ rejectedSpans: 0,
4371
+ failedScores: _failedScores,
3355
4372
  droppedSpans: 0,
3356
4373
  droppedSpansByReason: {
3357
4374
  queue_full: 0,
3358
4375
  transport_refused: 0,
3359
- shutdown_residue: 0
4376
+ shutdown_residue: 0,
4377
+ unacknowledged: 0
3360
4378
  },
3361
4379
  failedExports: 0,
3362
4380
  queueSize: 0,
@@ -3401,8 +4419,8 @@ function reportError(error, options) {
3401
4419
  span.setStatus("error" /* ERROR */, err.message);
3402
4420
  span.setAttribute("error", true);
3403
4421
  span.setAttribute("error.type", err.constructor.name);
3404
- span.setAttribute("error.message", err.message.slice(0, 2e3));
3405
- if (err.stack) span.setAttribute("error.stack", err.stack.slice(0, 4e3));
4422
+ span.setAttribute("error.message", cutCodePoints(err.message, 2e3));
4423
+ if (err.stack) span.setAttribute("error.stack", cutCodePoints(err.stack, 4e3));
3406
4424
  span.setAttribute("risicare.reported_error", true);
3407
4425
  attachErrorCode(span, err);
3408
4426
  if (options?.attributes) {
@@ -3417,18 +4435,28 @@ function reportError(error, options) {
3417
4435
  }
3418
4436
  function score(traceId, name, value, options) {
3419
4437
  try {
3420
- if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
3421
- debug(`score: value must be in [0.0, 1.0], got ${value}. Score not sent.`);
4438
+ const raw = value;
4439
+ if (typeof raw === "boolean") value = raw ? 1 : 0;
4440
+ if (typeof value !== "number") {
4441
+ warn(`score: the value must be a number, not ${typeof raw}. The SDK does not send this score.`);
3422
4442
  return;
3423
4443
  }
3424
- if (!traceId || !name) {
3425
- debug("score: traceId and name are required");
4444
+ if (!Number.isFinite(value) || value < 0 || value > 1) {
4445
+ warn(`score: the value must be in [0.0, 1.0], not ${value}. The SDK does not send this score.`);
4446
+ return;
4447
+ }
4448
+ if (typeof traceId !== "string" || given(traceId) === void 0) {
4449
+ warn("score: traceId must be a non-empty string. The SDK does not send this score.");
4450
+ return;
4451
+ }
4452
+ if (typeof name !== "string" || given(name) === void 0) {
4453
+ warn("score: name must be a non-empty string. The SDK does not send this score.");
3426
4454
  return;
3427
4455
  }
3428
4456
  const client = getClient();
3429
4457
  if (!client?.enabled || !client.config.apiKey) return;
3430
- const endpoint = client.config.endpoint.replace(/\/$/, "");
3431
- const url = `${endpoint}/api/v1/scores`;
4458
+ const endpoint = client.config.apiEndpoint.replace(/\/+$/, "");
4459
+ const url = `${endpoint}/v1/scores`;
3432
4460
  let comment = options?.comment;
3433
4461
  if (comment !== void 0 && client.config.mask) {
3434
4462
  comment = maskText(client.config.mask, SCORE_COMMENT_KEY, comment);
@@ -3441,21 +4469,71 @@ function score(traceId, name, value, options) {
3441
4469
  ...options?.spanId && { span_id: options.spanId },
3442
4470
  ...comment && { comment }
3443
4471
  });
3444
- fetch(url, {
3445
- method: "POST",
3446
- headers: {
3447
- "Content-Type": "application/json",
3448
- "Authorization": `Bearer ${client.config.apiKey}`,
3449
- // F-SDKVER-001 — see the Python twin. `score()` reaches the FastAPI
3450
- // server under /v1/, which `main.py::audit_logging_middleware` audits
3451
- // into `audit_logs.user_agent`; ingest reaches the Rust gateway, which
3452
- // discards it. This is the one client-identity visible with no gateway
3453
- // change.
3454
- "User-Agent": `risicare-js/${SDK_VERSION} node/${process.version}`,
3455
- "X-Risicare-SDK-Version": SDK_VERSION
3456
- },
3457
- body
3458
- }).catch((err) => debug(`score: send failed: ${err}`));
4472
+ if (_scoresInFlight >= SCORE_MAX_IN_FLIGHT && _scoreWaiters.length >= SCORE_MAX_WAITING) {
4473
+ _scoreFailed(name, SCORE_CAP_REASON);
4474
+ return;
4475
+ }
4476
+ let settle;
4477
+ const request = new Promise((resolve) => settle = resolve);
4478
+ const send = async () => {
4479
+ const controller = new AbortController();
4480
+ const timer = setTimeout(() => controller.abort(), SCORE_TIMEOUT_MS);
4481
+ try {
4482
+ const response = await fetch(url, {
4483
+ method: "POST",
4484
+ headers: {
4485
+ "Content-Type": "application/json",
4486
+ "Authorization": `Bearer ${client.config.apiKey}`,
4487
+ // F-SDKVER-001 — see the Python twin. `score()` reaches the FastAPI
4488
+ // server under /v1/, which `main.py::audit_logging_middleware` audits
4489
+ // into `audit_logs.user_agent`; ingest reaches the Rust gateway, which
4490
+ // discards it. This is the one client-identity visible with no gateway
4491
+ // change.
4492
+ "User-Agent": `risicare-js/${SDK_VERSION} node/${process.version}`,
4493
+ "X-Risicare-SDK-Version": SDK_VERSION
4494
+ },
4495
+ body,
4496
+ // Never follow: a redirect is a misroute, not a route. Through 0.7.1
4497
+ // fetch followed a 307 and re-POSTed the score to the login page.
4498
+ redirect: "manual",
4499
+ signal: controller.signal
4500
+ });
4501
+ if (response.type === "opaqueredirect" || response.status >= 300) {
4502
+ _scoreFailed(name, `HTTP ${response.status || "3xx"}`);
4503
+ }
4504
+ try {
4505
+ await response.body?.cancel();
4506
+ } catch {
4507
+ }
4508
+ } catch (err) {
4509
+ const cause = err instanceof Error ? err.cause : void 0;
4510
+ const code = typeof cause?.code === "string" ? cause.code : void 0;
4511
+ const reason = controller.signal.aborted ? `no answer within ${SCORE_TIMEOUT_MS} ms` : code ?? (err instanceof Error ? err.name : "Error");
4512
+ _scoreFailed(name, reason);
4513
+ } finally {
4514
+ clearTimeout(timer);
4515
+ _scoresInFlight--;
4516
+ settle();
4517
+ _startWaitingScores();
4518
+ }
4519
+ };
4520
+ const start = () => {
4521
+ _scoresInFlight++;
4522
+ void send();
4523
+ };
4524
+ if (_scoresInFlight < SCORE_MAX_IN_FLIGHT) {
4525
+ start();
4526
+ } else {
4527
+ _scoreWaiters.push({
4528
+ start,
4529
+ fail: (reason) => {
4530
+ _scoreFailed(name, reason);
4531
+ settle();
4532
+ }
4533
+ });
4534
+ }
4535
+ _pendingScores.add(request);
4536
+ void request.finally(() => _pendingScores.delete(request));
3459
4537
  } catch {
3460
4538
  debug("score failed");
3461
4539
  }
@@ -3484,9 +4562,9 @@ var LIFECYCLE_STATUS = "risicare.lifecycle.status";
3484
4562
  var STATUS_MESSAGE_MAX = 500;
3485
4563
  function excSummary(error) {
3486
4564
  if (error instanceof Error) {
3487
- return `${error.constructor.name}: ${error.message}`.slice(0, STATUS_MESSAGE_MAX);
4565
+ return cutCodePoints(`${error.constructor.name}: ${error.message}`, STATUS_MESSAGE_MAX);
3488
4566
  }
3489
- return String(error).slice(0, STATUS_MESSAGE_MAX);
4567
+ return cutCodePoints(String(error), STATUS_MESSAGE_MAX);
3490
4568
  }
3491
4569
  function stampEndMarker(span, entity, error) {
3492
4570
  try {
@@ -3573,9 +4651,10 @@ function withSessionEndMarker(body) {
3573
4651
 
3574
4652
  // src/decorators/agent.ts
3575
4653
  function _wrapAgent(options, fn) {
3576
- const spanName = `agent:${options.name ?? "agent"}`;
3577
- const agentId = options.agentId ?? generateAgentId(options.name ?? "agent");
3578
- const boundOptions = { ...options, agentId };
4654
+ const agentName = options.name ?? (fn.name.replace(/^(bound )+/, "") || "agent");
4655
+ const spanName = `agent:${agentName}`;
4656
+ const agentId = options.agentId ?? generateAgentId(agentName);
4657
+ const boundOptions = { ...options, name: agentName, agentId };
3579
4658
  return (...args) => {
3580
4659
  const tracer = getTracer2();
3581
4660
  if (!tracer) {
@@ -3628,6 +4707,10 @@ function withPhase(phase, fn) {
3628
4707
  }
3629
4708
 
3630
4709
  // src/decorators/phase.ts
4710
+ function bareName(phase, fn) {
4711
+ const fnName = typeof fn === "function" ? fn.name.replace(/^(bound )+/, "") : "";
4712
+ return fnName ? `${phase}:${fnName}` : `phase:${phase}`;
4713
+ }
3631
4714
  function phaseWrapper(phase, kind, name, fn) {
3632
4715
  return (...args) => {
3633
4716
  const tracer = getTracer2();
@@ -3643,22 +4726,22 @@ function phaseWrapper(phase, kind, name, fn) {
3643
4726
  };
3644
4727
  }
3645
4728
  function traceThink(fnOrName, maybeFn) {
3646
- const name = typeof fnOrName === "string" ? fnOrName : `phase:think`;
4729
+ const name = typeof fnOrName === "string" ? fnOrName : bareName("think", fnOrName);
3647
4730
  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
3648
4731
  return phaseWrapper("think" /* THINK */, "think" /* THINK */, name, fn);
3649
4732
  }
3650
4733
  function traceDecide(fnOrName, maybeFn) {
3651
- const name = typeof fnOrName === "string" ? fnOrName : `phase:decide`;
4734
+ const name = typeof fnOrName === "string" ? fnOrName : bareName("decide", fnOrName);
3652
4735
  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
3653
4736
  return phaseWrapper("decide" /* DECIDE */, "decide" /* DECIDE */, name, fn);
3654
4737
  }
3655
4738
  function traceAct(fnOrName, maybeFn) {
3656
- const name = typeof fnOrName === "string" ? fnOrName : `phase:act`;
4739
+ const name = typeof fnOrName === "string" ? fnOrName : bareName("act", fnOrName);
3657
4740
  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
3658
4741
  return phaseWrapper("act" /* ACT */, "tool_call" /* TOOL_CALL */, name, fn);
3659
4742
  }
3660
4743
  function traceObserve(fnOrName, maybeFn) {
3661
- const name = typeof fnOrName === "string" ? fnOrName : `phase:observe`;
4744
+ const name = typeof fnOrName === "string" ? fnOrName : bareName("observe", fnOrName);
3662
4745
  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
3663
4746
  return phaseWrapper("observe" /* OBSERVE */, "observe" /* OBSERVE */, name, fn);
3664
4747
  }
@@ -3747,7 +4830,7 @@ function getTraceContext() {
3747
4830
  traceId = ctx._rootTraceId;
3748
4831
  } else {
3749
4832
  traceId = generateTraceId();
3750
- if (ctx.session || ctx.agent) {
4833
+ if (hasContextScope()) {
3751
4834
  ctx._rootTraceId = traceId;
3752
4835
  }
3753
4836
  }
@@ -3784,7 +4867,8 @@ function extractTraceContext(headers) {
3784
4867
  const result = {};
3785
4868
  const normalizedHeaders = {};
3786
4869
  for (const [key, value] of Object.entries(headers)) {
3787
- normalizedHeaders[key.toLowerCase()] = value;
4870
+ const first = Array.isArray(value) ? value[0] : value;
4871
+ if (typeof first === "string") normalizedHeaders[key.toLowerCase()] = first;
3788
4872
  }
3789
4873
  const traceparent = normalizedHeaders[TRACEPARENT_HEADER] ?? "";
3790
4874
  if (traceparent) {