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.js CHANGED
@@ -48,6 +48,29 @@ function getDebug() {
48
48
  function setDebugFlag(enabled) {
49
49
  G[PREFIX + "debug"] = enabled;
50
50
  }
51
+ var PROVIDER_SPANS = /* @__PURE__ */ Symbol.for("risicare.providerSpans");
52
+ function usableProviderSpanState(s) {
53
+ if (!s || typeof s !== "object") return false;
54
+ const { version, open, registry } = s;
55
+ const o = open;
56
+ return version === 1 && !!o && typeof o.add === "function" && typeof o.delete === "function" && typeof o[Symbol.iterator] === "function" && (registry === void 0 || typeof registry.register === "function");
57
+ }
58
+ function getProviderSpanState() {
59
+ const found = G[PROVIDER_SPANS];
60
+ if (found === void 0) {
61
+ const s = {
62
+ version: 1,
63
+ open: /* @__PURE__ */ new Set(),
64
+ registry: typeof FinalizationRegistry === "function" ? new FinalizationRegistry((o) => o.release()) : void 0
65
+ };
66
+ G[PROVIDER_SPANS] = s;
67
+ return s;
68
+ }
69
+ if (!usableProviderSpanState(found)) {
70
+ throw new TypeError("the shared provider span state is not version 1");
71
+ }
72
+ return found;
73
+ }
51
74
 
52
75
  // src/utils/log.ts
53
76
  function setDebug(enabled) {
@@ -64,6 +87,73 @@ function warn(msg) {
64
87
  `);
65
88
  }
66
89
 
90
+ // src/utils/text.ts
91
+ function cutCodePoints(text, max) {
92
+ if (text.length <= max) return text;
93
+ let units = 0;
94
+ for (let points = 0; points < max && units < text.length; points++) {
95
+ units += text.codePointAt(units) > 65535 ? 2 : 1;
96
+ }
97
+ return text.slice(0, units);
98
+ }
99
+
100
+ // src/utils/scrub.ts
101
+ var KEY_MARKER = "[REDACTED-KEY]";
102
+ var CONTROL = new RegExp("[\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]", "g");
103
+ function escapeRegExp(text) {
104
+ return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
105
+ }
106
+ function percentDecode(text) {
107
+ try {
108
+ return decodeURIComponent(text);
109
+ } catch {
110
+ return text.replace(/%([0-9A-Fa-f]{2})/g, (_m, hex) => String.fromCharCode(parseInt(hex, 16)));
111
+ }
112
+ }
113
+ function keyPattern(keys) {
114
+ const values = /* @__PURE__ */ new Set();
115
+ for (const k of [...keys, process.env.RISICARE_API_KEY]) if (k) values.add(k);
116
+ if (values.size === 0) return null;
117
+ const ordered = [...values].sort((a, b) => b.length - a.length);
118
+ return new RegExp(ordered.map(escapeRegExp).join("|"), "gi");
119
+ }
120
+ function scrubText(text, keys, limit = 200) {
121
+ let out;
122
+ try {
123
+ out = text instanceof Error ? `${text.name}: ${text.message}` : String(text);
124
+ } catch {
125
+ out = typeof text;
126
+ }
127
+ const pattern = keyPattern(keys);
128
+ if (pattern !== null) {
129
+ if (out.includes("%")) {
130
+ const decoded = percentDecode(out);
131
+ pattern.lastIndex = 0;
132
+ if (decoded !== out && pattern.test(decoded)) out = decoded;
133
+ }
134
+ pattern.lastIndex = 0;
135
+ out = out.replace(pattern, KEY_MARKER);
136
+ }
137
+ return cutCodePoints(out.replace(CONTROL, " "), limit);
138
+ }
139
+ function safeUrl(url) {
140
+ try {
141
+ const u = new URL(url);
142
+ const path = u.pathname === "/" && !/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*\//i.test(url) ? "" : u.pathname;
143
+ return `${u.protocol}//${u.host}${path}`;
144
+ } catch {
145
+ return url.split("?")[0].split("#")[0].replace(/\/\/[^/@]*@/, "//");
146
+ }
147
+ }
148
+ function hasCredentials(url) {
149
+ try {
150
+ const u = new URL(url);
151
+ return u.username !== "" || u.password !== "";
152
+ } catch {
153
+ return false;
154
+ }
155
+ }
156
+
67
157
  // src/masking.ts
68
158
  var MASK_ERROR_MARKER = "<risicare:mask-error>";
69
159
  var MASK_BUDGET_MS_PER_SPAN = 1;
@@ -130,15 +220,124 @@ function applyMask(span, mask, onError) {
130
220
  markMasked(span);
131
221
  }
132
222
  var CONTENT_KEYS_EXACT = /* @__PURE__ */ new Set([
223
+ // spec v1
133
224
  "gen_ai.system_prompt",
134
- "gen_ai.prompt.message"
225
+ // anthropic, bedrock
226
+ "gen_ai.prompt.message",
227
+ // cohere
228
+ "gen_ai.prompt",
229
+ // OTel GenAI (deprecated form)
230
+ "gen_ai.completion",
231
+ "gen_ai.input.messages",
232
+ // OTel GenAI
233
+ "gen_ai.output.messages",
234
+ "gen_ai.system_instructions",
235
+ "gen_ai.tool.call.arguments",
236
+ // Corpus v2: the list of tool definitions of a request. The names,
237
+ // descriptions and schemas in it are text that the customer wrote.
238
+ "gen_ai.tool.definitions",
239
+ "gen_ai.tool.call.result",
240
+ "input.value",
241
+ // OpenInference
242
+ "output.value",
243
+ "llm.prompts",
244
+ "llm.prompt_template.template",
245
+ "llm.prompt_template.variables",
246
+ "task_description",
247
+ // CrewAI
248
+ // ⚠ EXTENSION to spec v1: content keys that the Python SDK's integrations emit
249
+ // and that no v1 rule strips. Kept here too, so the two SDKs agree on the rule.
250
+ "framework.crewai.task_description",
251
+ "framework.crewai.agent_goal",
252
+ "framework.crewai.agent_output",
253
+ "framework.crewai.result",
254
+ "framework.autogen.last_message",
255
+ "framework.autogen.reply",
256
+ "framework.autogen.response",
257
+ "framework.openai_agents.input",
258
+ "framework.openai_agents.output",
259
+ "framework.dspy.signature",
260
+ "gen_ai.request.messages",
261
+ "agent.action.input",
262
+ "agent.action.log",
263
+ "agent.finish.output",
264
+ "tool.input",
265
+ "tool.output",
266
+ "retriever.query",
267
+ "retriever.first_doc",
268
+ // ⚠ FAIL CLOSED: third-party content keys that no other rule strips.
269
+ "gen_ai.retrieval.query.text",
270
+ // OTel GenAI
271
+ "gen_ai.retrieval.documents",
272
+ "gen_ai.evaluation.explanation",
273
+ "llm.function_call",
274
+ // OpenInference
275
+ "llm.choices",
276
+ "reranker.query",
277
+ "audio.transcript",
278
+ "traceloop.entity.input",
279
+ // OpenLLMetry
280
+ "traceloop.entity.output"
281
+ ]);
282
+ var CONTENT_LAST_SEGMENT_IN_CONTEXT = /* @__PURE__ */ new Map([
283
+ ["function_call_arguments_json", /* @__PURE__ */ new Set()],
284
+ // OpenInference `message.*`
285
+ ["data", /* @__PURE__ */ new Set(["message_content"])],
286
+ ["url", /* @__PURE__ */ new Set(["image"])],
287
+ // `image.url` can hold base64 data
288
+ ["metadata", /* @__PURE__ */ new Set(["document", "documents"])]
135
289
  ]);
290
+ var CONTENT_CONTAINER_SEGMENTS = /* @__PURE__ */ new Set([
291
+ "message",
292
+ "messages",
293
+ "message_content",
294
+ "contents",
295
+ "embedding",
296
+ "embeddings",
297
+ "document",
298
+ "documents",
299
+ "tool_call",
300
+ "tool_calls",
301
+ "function"
302
+ ]);
303
+ var CONTENT_KEYS_KEEP_EXACT = /* @__PURE__ */ new Set([
304
+ "gen_ai.response.content_type",
305
+ "gen_ai.response.content_blocks",
306
+ "gen_ai.prompt.parts",
307
+ "gen_ai.prompt.count",
308
+ "gen_ai.response.choices",
309
+ "gen_ai.completion.tool_calls"
310
+ ]);
311
+ var KEEP_LAST_SEGMENTS = /* @__PURE__ */ new Set([
312
+ "role",
313
+ "name",
314
+ "id",
315
+ "type",
316
+ "count",
317
+ "index",
318
+ "model",
319
+ "finish_reason",
320
+ "mime_type"
321
+ ]);
322
+ var KEEP_LAST_SUFFIXES = ["_length", "_tokens", "_count"];
136
323
  var CONTENT_OMITTED_MARKER = "<risicare:content-omitted>";
137
324
  function isContentKey(key) {
138
- if (CONTENT_KEYS_EXACT.has(key)) return true;
139
- const lastSegment = key.slice(key.lastIndexOf(".") + 1);
140
- if (lastSegment === "content") return true;
141
- return key.endsWith("_content");
325
+ if (CONTENT_KEYS_KEEP_EXACT.has(key)) return false;
326
+ if (CONTENT_KEYS_EXACT.has(key) || key.endsWith("_content")) return true;
327
+ const segments = key.split(".");
328
+ const last = segments[segments.length - 1];
329
+ const context = CONTENT_LAST_SEGMENT_IN_CONTEXT.get(last);
330
+ if (context && (context.size === 0 || segments.slice(0, -1).some((s) => context.has(s)))) {
331
+ return true;
332
+ }
333
+ if (KEEP_LAST_SEGMENTS.has(last) || KEEP_LAST_SUFFIXES.some((x) => last.endsWith(x))) {
334
+ return false;
335
+ }
336
+ if (last === "content") return true;
337
+ if (last === "text" || last === "arguments") {
338
+ return segments.slice(0, -1).some((s) => CONTENT_CONTAINER_SEGMENTS.has(s));
339
+ }
340
+ return false;
142
341
  }
143
342
  function stripAttributes(attrs) {
144
343
  let n = 0;
@@ -200,7 +399,13 @@ function applyMaskBatch(spans, mask, onError) {
200
399
  }
201
400
  const elapsedMs = Date.now() - started;
202
401
  if (errors > 0 && firstKey !== void 0) {
203
- debug(`mask threw on ${errors} field(s); first: key=${firstKey} ${String(firstError)}`);
402
+ let detail;
403
+ try {
404
+ detail = String(firstError);
405
+ } catch {
406
+ detail = typeof firstError;
407
+ }
408
+ debug(`mask threw on ${errors} field(s); first: key=${firstKey} ${detail}`);
204
409
  }
205
410
  return { errors, elapsedMs };
206
411
  }
@@ -216,8 +421,37 @@ function warnMaskSlow(spanCount, elapsedMs) {
216
421
  }
217
422
 
218
423
  // src/exporters/batch.ts
424
+ var DEADLINE = /* @__PURE__ */ Symbol("deadline");
425
+ async function raceDeadline(p, ms) {
426
+ let timer;
427
+ const deadline = new Promise((resolve) => {
428
+ timer = setTimeout(() => resolve(DEADLINE), Math.max(0, ms));
429
+ });
430
+ try {
431
+ return await Promise.race([p, deadline]);
432
+ } finally {
433
+ clearTimeout(timer);
434
+ }
435
+ }
436
+ function describeThrown(e) {
437
+ return scrubText(e, []);
438
+ }
439
+ async function shutdownExporter(exporter, ms) {
440
+ try {
441
+ const outcome = await raceDeadline(Promise.resolve().then(() => exporter.shutdown()), ms);
442
+ if (outcome === DEADLINE) debug(`${exporter.name}.shutdown() did not finish within ${ms} ms`);
443
+ } catch (e) {
444
+ debug(`Error shutting down ${exporter.name}: ${describeThrown(e)}`);
445
+ }
446
+ }
219
447
  var SHUTDOWN_RESERVE_MS = 100;
220
448
  var SHUTDOWN_BUDGET_MS = 5e3;
449
+ var MAX_TIMEOUT_MS = 2 ** 31 - 1;
450
+ function normalizeTimeoutMs(value) {
451
+ if (typeof value !== "number" || !Number.isFinite(value)) return SHUTDOWN_BUDGET_MS;
452
+ if (value < 0) return 0;
453
+ return Math.min(value, MAX_TIMEOUT_MS);
454
+ }
221
455
  var REFUSAL_WARN_WINDOW_MS = 3e5;
222
456
  var DEFAULT_BATCH_SIZE = 500;
223
457
  var MAX_ATTRIBUTE_PAIRS_PER_BATCH = 24e3;
@@ -306,11 +540,18 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
306
540
  _timer = null;
307
541
  _started = false;
308
542
  _flushing = false;
543
+ _inFlight = null;
309
544
  _beforeExitHandler = null;
310
545
  // Retry tracking for failed batches (Audit #5)
311
546
  _retryCounts = /* @__PURE__ */ new Map();
312
547
  static MAX_RETRIES = 3;
313
548
  _lastRefusalWarnAt = Number.NEGATIVE_INFINITY;
549
+ _lastUnackWarnAt = Number.NEGATIVE_INFINITY;
550
+ /**
551
+ * The loss total (dropped + rejected) that the last finished `flush()` saw.
552
+ * A flush reports a loss that is new since then, one time.
553
+ */
554
+ _lossMark = 0;
314
555
  // ── Masking (see `../masking.ts`) ──────────────────────────────────────────
315
556
  _mask;
316
557
  // ── Content capture gate (see `../masking.ts`) ─────────────────────────────
@@ -332,9 +573,15 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
332
573
  droppedSpansByReason = {
333
574
  queue_full: 0,
334
575
  transport_refused: 0,
335
- shutdown_residue: 0
576
+ shutdown_residue: 0,
577
+ unacknowledged: 0
336
578
  };
337
579
  exportedSpans = 0;
580
+ /**
581
+ * Spans that the backend acknowledged as REJECTED (the ack's `rejected`). They
582
+ * are not stored and are not retried. An exporter without an ack adds nothing.
583
+ */
584
+ rejectedSpans = 0;
338
585
  /** Export ATTEMPTS, not a span count. */
339
586
  failedExports = 0;
340
587
  /**
@@ -419,13 +666,32 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
419
666
  * NO progress and abandons the queue exactly as before — measured at 900 of
420
667
  * 1,000. We await a tick instead, the shape `flush()` already models.
421
668
  *
422
- * Anything still queued when the loop stops is COUNTED as `shutdown_residue`
423
- * and announced with a WARNING. The warning is the primary signal, not the
424
- * counter: a counter incremented inside `shutdown()` is written to memory
425
- * about to be freed and has no reader (RULING §2 / §8.2).
669
+ * The deadline is a hard wall-clock bound. Each round is raced against the
670
+ * budget that remains. At the deadline, `shutdown()` stops the round in flight
671
+ * through the exporter's optional `abort()`. That stopped round changes no
672
+ * counter, does not move the circuit breaker and re-queues nothing. Through
673
+ * 0.7.1 the deadline was checked only between rounds, so one round against a
674
+ * silent server (3 attempts x 5 s) held a 5,000 ms shutdown for 15 s.
675
+ *
676
+ * Anything still queued when the loop stops, AND a batch whose export was
677
+ * stopped, is COUNTED as `shutdown_residue` and announced with ONE WARNING
678
+ * that gives both numbers. The server may have received the spans of the
679
+ * stopped export. The warning is the primary signal, not the counter: a
680
+ * counter incremented inside `shutdown()` is written to memory about to be
681
+ * freed and has no reader (RULING §2 / §8.2).
682
+ *
683
+ * Each exporter's own `shutdown()` gets the time that is left of the budget.
684
+ * An exporter that does not finish in that time is not awaited.
685
+ *
686
+ * Limit: the abort does not stop a TLS handshake that stalls. Measured, such a
687
+ * handshake kept the process alive about 10 s after `shutdown()` returned.
688
+ *
689
+ * @param timeoutMs - The budget (default 5000). See `normalizeTimeoutMs` for
690
+ * the values that are not a finite number.
426
691
  */
427
692
  async shutdown(timeoutMs = SHUTDOWN_BUDGET_MS) {
428
693
  if (!this._started) return;
694
+ timeoutMs = normalizeTimeoutMs(timeoutMs);
429
695
  this._started = false;
430
696
  if (this._timer) {
431
697
  clearInterval(this._timer);
@@ -436,10 +702,13 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
436
702
  this._beforeExitHandler = null;
437
703
  }
438
704
  const reserveMs = Math.min(SHUTDOWN_RESERVE_MS, timeoutMs / 2);
439
- const drainDeadline = Date.now() + Math.max(0, timeoutMs - reserveMs);
705
+ const shutdownDeadline = Date.now() + timeoutMs;
706
+ const drainDeadline = shutdownDeadline - reserveMs;
440
707
  while (this._queue.length > 0 || this._flushing) {
441
- if (Date.now() >= drainDeadline) break;
442
- const outcome = await this._exportBatch();
708
+ const remaining = drainDeadline - Date.now();
709
+ if (remaining <= 0) break;
710
+ const outcome = await raceDeadline(this._exportBatch(), remaining);
711
+ if (outcome === DEADLINE) break;
443
712
  if (outcome === 3 /* Busy */) {
444
713
  await new Promise((r) => setTimeout(r, 1));
445
714
  continue;
@@ -448,20 +717,29 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
448
717
  break;
449
718
  }
450
719
  }
451
- const residue = this._queue.length;
720
+ const queued = this._queue.length;
721
+ const flight = this._inFlight;
722
+ const inFlight = flight !== null && !flight.abandoned ? flight.size : 0;
723
+ if (flight !== null && !flight.abandoned) {
724
+ flight.abandoned = true;
725
+ for (const exporter of this._exporters) {
726
+ try {
727
+ exporter.abort?.(flight.spans);
728
+ } catch (e) {
729
+ debug(`Error aborting ${exporter.name}: ${describeThrown(e)}`);
730
+ }
731
+ }
732
+ }
733
+ const residue = queued + inFlight;
452
734
  if (residue > 0) {
453
735
  this._queue.length = 0;
454
736
  this._recordDropped("shutdown_residue", residue);
455
737
  warn(
456
- `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.`
738
+ `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.`
457
739
  );
458
740
  }
459
741
  for (const exporter of this._exporters) {
460
- try {
461
- await exporter.shutdown();
462
- } catch (e) {
463
- debug(`Error shutting down ${exporter.name}: ${e}`);
464
- }
742
+ await shutdownExporter(exporter, Math.max(0, shutdownDeadline - Date.now()));
465
743
  }
466
744
  this._retryCounts.clear();
467
745
  debug(
@@ -485,7 +763,8 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
485
763
  /**
486
764
  * Flush pending spans.
487
765
  *
488
- * @returns `true` only if everything queued at entry was DELIVERED.
766
+ * @returns `true` only if everything queued at entry was DELIVERED and no
767
+ * span was lost since the previous flush returned.
489
768
  *
490
769
  * RULING §6. This used to answer a different question — "is the queue
491
770
  * empty?" — and those two diverge in exactly one case: when spans left the
@@ -494,35 +773,76 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
494
773
  * everything right; silence lets them discover the problem, a false
495
774
  * affirmative forecloses it.
496
775
  *
497
- * Returns `false` when (a) the deadline expires with spans still queued,
498
- * (b) any span was discarded during the window — breaker refusal or retry
499
- * exhaustion — or (c) it is called after `shutdown()` and the shutdown
500
- * residue was non-zero.
776
+ * A LOSS IS REPORTED BY THE NEXT `flush()`, ONE TIME (design section 0,
777
+ * third revision). Returns `true` only when, at the moment it returns, the
778
+ * queue is empty, no batch is in flight, and no span was discarded or
779
+ * rejected since the previous `flush()` returned (or since start, for the
780
+ * first call). Through 0.7.1 only a loss during the call counted: a script
781
+ * whose spans the batch timer had discarded against a 401 sink got `true`
782
+ * with nothing delivered. A failure that a retry repairs does not make it
783
+ * `false`.
784
+ *
785
+ * Mechanics: the processor keeps a loss mark, the loss total (dropped +
786
+ * rejected) that the last finished flush saw. A flush compares the total
787
+ * with the mark it read at its start, then raises the mark to the total
788
+ * (never lowers it). Two flushes that overlap both answer `false` for one
789
+ * loss. The flush after that answers `true` when nothing new was lost.
790
+ *
791
+ * Returns `false` in these cases:
792
+ * (a) the deadline expires with spans still queued or in flight;
793
+ * (b) a span was discarded since the previous flush returned: queue full,
794
+ * breaker refusal, retry exhaustion, or an ack that did not account
795
+ * for it or a span that could not be serialized (`unacknowledged`);
796
+ * (c) the backend rejected a span since the previous flush returned;
797
+ * (d) it is called after `shutdown()`, and the shutdown residue was not 0.
798
+ *
799
+ * The deadline is a hard wall-clock bound on the WAIT. At the deadline
800
+ * `flush()` returns `false`. Through 0.7.1 the deadline was checked only
801
+ * between rounds.
802
+ *
803
+ * ⚠ `flush()` never stops a request that is already sent. The export round in
804
+ * flight continues and ends by its own rules: its request timeout, its
805
+ * retries, the circuit breaker. A short flush budget therefore costs no retry,
806
+ * moves no breaker and sends nothing twice. Its result still counts.
807
+ *
808
+ * Limit: that round can keep the process alive after `flush()` returns
809
+ * `false`, until its own timeouts end. Measured on a silent server: 22 s. To
810
+ * end a process within a bound, call `await shutdown(timeoutMs)`: it stops
811
+ * the round in flight.
501
812
  *
502
813
  * ⚠ (b) reads the flat total, so a concurrent `queue_full` drop of a span
503
- * that arrived DURING the window also answers `false`. That is the
814
+ * that arrived during the call also answers `false`. That is the
504
815
  * conservative direction on purpose: a false negative costs a caller one
505
816
  * more flush, a false positive is the defect being fixed.
506
817
  */
507
818
  async flush(timeoutMs = SHUTDOWN_BUDGET_MS) {
819
+ timeoutMs = normalizeTimeoutMs(timeoutMs);
508
820
  if (!this._started) {
509
821
  return this._queue.length === 0 && this.droppedSpansByReason.shutdown_residue === 0;
510
822
  }
511
- const start = Date.now();
512
- const discardedAtEntry = this.droppedSpans;
823
+ const deadline = Date.now() + timeoutMs;
824
+ const mark = this._lossMark;
825
+ const finish = (settled) => {
826
+ const lost = this.droppedSpans + this.rejectedSpans;
827
+ this._lossMark = Math.max(this._lossMark, lost);
828
+ return settled && lost === mark;
829
+ };
513
830
  while (this._queue.length > 0 || this._flushing) {
831
+ const remaining = deadline - Date.now();
832
+ if (remaining <= 0) return finish(false);
514
833
  if (!this._flushing && this._queue.length > 0) {
515
- await this._exportBatch();
834
+ const outcome = await raceDeadline(this._exportBatch(), remaining);
835
+ if (outcome === DEADLINE) return finish(false);
516
836
  } else {
517
837
  await new Promise((r) => setTimeout(r, 1));
518
838
  }
519
- if (Date.now() - start > timeoutMs) return false;
520
839
  }
521
- return this.droppedSpans === discardedAtEntry;
840
+ return finish(true);
522
841
  }
523
842
  getMetrics() {
524
843
  return {
525
844
  exportedSpans: this.exportedSpans,
845
+ rejectedSpans: this.rejectedSpans,
526
846
  droppedSpans: this.droppedSpans,
527
847
  droppedSpansByReason: { ...this.droppedSpansByReason },
528
848
  failedExports: this.failedExports,
@@ -532,10 +852,56 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
532
852
  queueUtilization: this._queue.length / this._maxQueueSize
533
853
  };
534
854
  }
855
+ /**
856
+ * Count a delivered batch of `n` spans from the exporter's ack.
857
+ *
858
+ * The ack is not trusted. With r = min(rejected, n), a = min(accepted, n - r)
859
+ * and u = n - a - r: `exportedSpans` rises by a, `rejectedSpans` by r, and the
860
+ * u spans that no ack accounts for are dropped as `unacknowledged`, with one
861
+ * rate-limited WARNING. Without an ack (console, custom exporter), the whole
862
+ * batch counts as exported, as before. Python twin: the same clamp.
863
+ */
864
+ _countDelivered(n, ack) {
865
+ if (ack === null) {
866
+ this.exportedSpans += n;
867
+ return;
868
+ }
869
+ const rejected = Math.min(ack.rejected, n);
870
+ const accepted = Math.min(ack.accepted, n - rejected);
871
+ const unacknowledged = n - accepted - rejected;
872
+ this.exportedSpans += accepted;
873
+ this.rejectedSpans += rejected;
874
+ if (unacknowledged > 0) {
875
+ this._recordDropped("unacknowledged", unacknowledged);
876
+ const now = Date.now();
877
+ if (now - this._lastUnackWarnAt > REFUSAL_WARN_WINDOW_MS) {
878
+ this._lastUnackWarnAt = now;
879
+ warn(
880
+ `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.`
881
+ );
882
+ }
883
+ }
884
+ }
885
+ /** The requests in one export round, when every exporter that delivers states it. */
886
+ _requestsPerRound() {
887
+ const delivering = this._exporters.filter((e) => e.countsAsDelivery !== false);
888
+ if (delivering.length !== 1) return void 0;
889
+ const n = delivering[0].attemptsPerExport;
890
+ return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : void 0;
891
+ }
892
+ /**
893
+ * One export round.
894
+ *
895
+ * Which results decide delivery: an exporter that only shows spans locally
896
+ * (`countsAsDelivery === false`, the console exporter) decides only when no
897
+ * other kind of exporter is present. Among the exporters that deliver, ANY
898
+ * success counts the batch as delivered, once.
899
+ */
535
900
  async _exportBatch() {
536
901
  if (this._flushing) return 3 /* Busy */;
537
902
  if (this._queue.length === 0) return 0 /* Empty */;
538
903
  this._flushing = true;
904
+ let flight = null;
539
905
  try {
540
906
  let take = 0;
541
907
  let pairs = 0;
@@ -554,6 +920,8 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
554
920
  }
555
921
  const batch = this._queue.splice(0, take);
556
922
  if (batch.length === 0) return 0 /* Empty */;
923
+ flight = { spans: batch, size: batch.length, abandoned: false };
924
+ this._inFlight = flight;
557
925
  if (!this._traceContent) {
558
926
  const stripped = stripContentBatch(batch);
559
927
  if (stripped > 0) {
@@ -567,12 +935,19 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
567
935
  }
568
936
  debug(`Exporting batch of ${batch.length} spans`);
569
937
  let batchExported = false;
938
+ const anyDelivers = this._exporters.some((e) => e.countsAsDelivery !== false);
939
+ const unserializable = /* @__PURE__ */ new Set();
570
940
  for (const exporter of this._exporters) {
941
+ const decides = !anyDelivers || exporter.countsAsDelivery !== false;
571
942
  try {
572
943
  const result = await exporter.export(batch);
944
+ if (flight.abandoned) return 2 /* Failed */;
945
+ if (!decides) continue;
946
+ for (const span of exporter.takeUnserializable?.(batch) ?? []) unserializable.add(span);
573
947
  if (result === "success" /* SUCCESS */) {
948
+ const ack = exporter.takeAck?.(batch) ?? null;
574
949
  if (!batchExported) {
575
- this.exportedSpans += batch.length;
950
+ this._countDelivered(batch.length - unserializable.size, ack);
576
951
  batchExported = true;
577
952
  for (const span of batch) {
578
953
  this._retryCounts.delete(span.spanId);
@@ -582,13 +957,17 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
582
957
  this.failedExports++;
583
958
  }
584
959
  } catch (e) {
960
+ if (flight.abandoned) return 2 /* Failed */;
961
+ if (!decides) continue;
585
962
  this.failedExports++;
586
- debug(`Export to ${exporter.name} failed: ${e}`);
963
+ debug(`Export to ${exporter.name} failed: ${describeThrown(e)}`);
587
964
  }
588
965
  }
966
+ if (unserializable.size > 0) this._recordDropped("unacknowledged", unserializable.size);
589
967
  if (!batchExported) {
590
968
  let dropped = 0;
591
969
  const retryable = batch.filter((span) => {
970
+ if (unserializable.has(span)) return false;
592
971
  const count = (this._retryCounts.get(span.spanId) ?? 0) + 1;
593
972
  if (count > _BatchSpanProcessor.MAX_RETRIES) {
594
973
  this._retryCounts.delete(span.spanId);
@@ -607,38 +986,72 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
607
986
  const now = Date.now();
608
987
  if (now - this._lastRefusalWarnAt > REFUSAL_WARN_WINDOW_MS) {
609
988
  this._lastRefusalWarnAt = now;
989
+ const rounds = _BatchSpanProcessor.MAX_RETRIES + 1;
990
+ const perRound = this._requestsPerRound();
610
991
  warn(
611
- `${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.`
992
+ `${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.`
612
993
  );
613
994
  }
614
995
  }
615
996
  }
616
997
  return batchExported ? 1 /* Delivered */ : 2 /* Failed */;
617
998
  } finally {
999
+ if (this._inFlight === flight) this._inFlight = null;
618
1000
  this._flushing = false;
619
1001
  }
620
1002
  }
621
1003
  };
622
1004
 
623
1005
  // src/config.ts
624
- var DEFAULT_ENDPOINT = "https://app.risicare.ai";
1006
+ var DEFAULT_ENDPOINT = "https://ingest.risicare.ai";
1007
+ var DEFAULT_API_ENDPOINT = "https://api.risicare.ai";
1008
+ var ASCII_WS_EDGES = /^[ \t\n\r\f\v]+|[ \t\n\r\f\v]+$/g;
1009
+ function given(value) {
1010
+ if (typeof value !== "string") return void 0;
1011
+ const trimmed = value.replace(ASCII_WS_EDGES, "");
1012
+ return trimmed === "" ? void 0 : trimmed;
1013
+ }
1014
+ var DEFAULT_INGEST_PATTERN = /^https:\/\/ingest\.risicare\.ai(?::443)?\/*$/i;
1015
+ function isDefaultIngest(value) {
1016
+ return DEFAULT_INGEST_PATTERN.test(value);
1017
+ }
1018
+ function resolveEndpoints(endpointOption, apiEndpointOption, envEndpoint, envApiEndpoint) {
1019
+ const e = given(endpointOption);
1020
+ const a = given(apiEndpointOption);
1021
+ const ee = given(envEndpoint);
1022
+ const ea = given(envApiEndpoint);
1023
+ const endpoint = e ?? ee ?? DEFAULT_ENDPOINT;
1024
+ let apiEndpoint;
1025
+ if (a !== void 0) apiEndpoint = a;
1026
+ else if (e !== void 0 && !isDefaultIngest(e)) apiEndpoint = e;
1027
+ else if (ea !== void 0) apiEndpoint = ea;
1028
+ else if (e === void 0 && ee !== void 0 && !isDefaultIngest(ee)) apiEndpoint = ee;
1029
+ else apiEndpoint = DEFAULT_API_ENDPOINT;
1030
+ return { endpoint, apiEndpoint };
1031
+ }
625
1032
  function resolveConfig(config) {
626
1033
  const env = process.env;
627
1034
  const apiKey = config?.apiKey ?? env.RISICARE_API_KEY;
628
- const endpoint = config?.endpoint ?? env.RISICARE_ENDPOINT ?? DEFAULT_ENDPOINT;
1035
+ const { endpoint, apiEndpoint } = resolveEndpoints(
1036
+ config?.endpoint,
1037
+ config?.apiEndpoint,
1038
+ env.RISICARE_ENDPOINT,
1039
+ env.RISICARE_API_ENDPOINT
1040
+ );
629
1041
  const projectId = config?.projectId ?? env.RISICARE_PROJECT_ID;
630
1042
  if (config?.projectId || env.RISICARE_PROJECT_ID) {
631
1043
  console.warn(
632
1044
  "[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."
633
1045
  );
634
1046
  }
635
- const environment = config?.environment ?? env.RISICARE_ENVIRONMENT ?? "development";
1047
+ const environment = config?.environment || env.RISICARE_ENVIRONMENT || "development";
636
1048
  const serviceName = config?.serviceName ?? env.RISICARE_SERVICE_NAME;
637
1049
  const serviceVersion = config?.serviceVersion ?? env.RISICARE_SERVICE_VERSION;
638
1050
  const traceContent = config?.traceContent ?? parseBool(env.RISICARE_TRACE_CONTENT, false);
639
1051
  const sampleRateRaw = config?.sampleRate ?? parseFloat(env.RISICARE_SAMPLE_RATE ?? "1.0");
640
1052
  const debug2 = config?.debug ?? parseBool(env.RISICARE_DEBUG, false);
641
1053
  const compress = config?.compress ?? parseBool(env.RISICARE_COMPRESS, false);
1054
+ const fixRuntime = config?.fixRuntime ?? parseBool(env.RISICARE_FIX_RUNTIME, false);
642
1055
  const batchSizeRaw = config?.batchSize ?? parseNumericEnv(env.RISICARE_BATCH_SIZE, DEFAULT_BATCH_SIZE);
643
1056
  const batchTimeoutMsRaw = config?.batchTimeoutMs ?? parseNumericEnv(env.RISICARE_BATCH_TIMEOUT_MS, 1e3);
644
1057
  const maxQueueSizeRaw = config?.maxQueueSize ?? parseNumericEnv(env.RISICARE_MAX_QUEUE_SIZE, 1e4);
@@ -652,16 +1065,18 @@ function resolveConfig(config) {
652
1065
  const batchTimeoutMs = validatePositiveInt("batchTimeoutMs", batchTimeoutMsRaw, 1e3, 1, 6e5);
653
1066
  const maxQueueSize = validatePositiveInt("maxQueueSize", maxQueueSizeRaw, 1e4, 1, 1e6);
654
1067
  let enabled;
1068
+ const tracingEnv = config?.enabled === void 0 ? tracingFromEnv(env.RISICARE_TRACING) : void 0;
655
1069
  if (config?.enabled !== void 0) {
656
1070
  enabled = config.enabled;
657
- } else if (env.RISICARE_TRACING !== void 0) {
658
- enabled = parseBool(env.RISICARE_TRACING, false);
1071
+ } else if (tracingEnv !== void 0) {
1072
+ enabled = tracingEnv;
659
1073
  } else {
660
1074
  enabled = !!apiKey;
661
1075
  }
662
- return {
1076
+ return hideKeyFromInspect({
663
1077
  apiKey: apiKey ?? "",
664
1078
  endpoint,
1079
+ apiEndpoint,
665
1080
  projectId: projectId ?? "",
666
1081
  environment,
667
1082
  serviceName: serviceName ?? "",
@@ -674,16 +1089,40 @@ function resolveConfig(config) {
674
1089
  maxQueueSize,
675
1090
  debug: debug2,
676
1091
  compress,
1092
+ fixRuntime,
677
1093
  metadata: config?.metadata ?? {},
678
1094
  // No env fallback — see the field's note on RisicareConfig.
679
1095
  mask: config?.mask
680
- };
1096
+ });
1097
+ }
1098
+ function hideKeyFromInspect(config) {
1099
+ Object.defineProperty(config, /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom"), {
1100
+ enumerable: false,
1101
+ value(_depth, options, inspect) {
1102
+ const { apiKey, ...rest } = this;
1103
+ return `RisicareConfig ${inspect({ ...rest, apiKey: apiKey ? "<redacted>" : "" }, options)}`;
1104
+ }
1105
+ });
1106
+ return config;
681
1107
  }
682
1108
  function parseBool(value, defaultValue) {
683
1109
  if (value === void 0) return defaultValue;
684
1110
  const lower = value.toLowerCase();
685
1111
  return lower === "true" || lower === "1" || lower === "yes";
686
1112
  }
1113
+ var TRACING_ON = /* @__PURE__ */ new Set(["true", "1", "yes", "on"]);
1114
+ var TRACING_OFF = /* @__PURE__ */ new Set(["false", "0", "no", "off"]);
1115
+ function tracingFromEnv(value) {
1116
+ if (value === void 0) return void 0;
1117
+ const v = value.trim().toLowerCase();
1118
+ if (v === "") return void 0;
1119
+ if (TRACING_ON.has(v)) return true;
1120
+ if (TRACING_OFF.has(v)) return false;
1121
+ warn(
1122
+ `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.`
1123
+ );
1124
+ return false;
1125
+ }
687
1126
  function parseNumericEnv(value, defaultValue) {
688
1127
  if (value === void 0) return defaultValue;
689
1128
  const n = Number(value);
@@ -1289,12 +1728,31 @@ var CANONICAL_ERROR_CODES = /* @__PURE__ */ new Set([
1289
1728
  "TOOL.RESULT.UNEXPECTED_FORMAT",
1290
1729
  "TOOL.RESULT.UNPARSEABLE"
1291
1730
  ]);
1731
+ var CORE_RULES = [
1732
+ { re: new RegExp("json", "u"), code: "PERCEPTION.PARSING.JSON_INVALID" },
1733
+ { re: new RegExp("encoding", "u"), code: "PERCEPTION.INPUT.ENCODING" },
1734
+ { re: new RegExp("injection", "u"), code: "PERCEPTION.INPUT.INJECTION" },
1735
+ { re: new RegExp("malformed", "u"), code: "PERCEPTION.INPUT.MALFORMED" },
1736
+ { re: new RegExp("hallucin", "u"), code: "REASONING.HALLUCINATION.FACTUAL" },
1737
+ { re: new RegExp("contradict", "u"), code: "REASONING.LOGIC.CONTRADICTION" },
1738
+ { re: new RegExp("timeout", "u"), code: "TOOL.EXECUTION.TIMEOUT" },
1739
+ { re: new RegExp("rate[^\\n]?limit", "u"), code: "TOOL.EXECUTION.RATE_LIMITED" },
1740
+ { re: new RegExp("permission", "u"), code: "TOOL.INVOCATION.PERMISSION_DENIED" },
1741
+ { re: new RegExp("context[^\\n]+overflow", "u"), code: "MEMORY.CONTEXT_WINDOW.EXCEEDED" },
1742
+ { re: new RegExp("state[^\\n]+corrupt", "u"), code: "MEMORY.STATE.CORRUPTED" },
1743
+ { re: new RegExp("pii", "u"), code: "OUTPUT.SAFETY.PII_LEAK" },
1744
+ { re: new RegExp("deadlock", "u"), code: "COORDINATION.WORKFLOW.DEADLOCK" },
1745
+ { re: new RegExp("undeliverable", "u"), code: "COMMUNICATION.DELIVERY.UNDELIVERABLE" },
1746
+ { re: new RegExp("crash", "u"), code: "ORCHESTRATION.LIFECYCLE.CRASHED" },
1747
+ { re: new RegExp("quorum", "u"), code: "CONSENSUS.AGREEMENT.QUORUM_FAILED" },
1748
+ { re: new RegExp("quota[^\\n]+exceed", "u"), code: "RESOURCES.QUOTA.EXCEEDED" }
1749
+ ];
1292
1750
  var SUPPLEMENTAL_RULES = [
1293
- { re: new RegExp("timeout|timedout|aborted", "i"), code: "TOOL.EXECUTION.TIMEOUT" },
1294
- { re: new RegExp("rate.?limit|\\b429\\b|too many requests", "i"), code: "TOOL.EXECUTION.RATE_LIMITED" },
1295
- { re: new RegExp("connection|econnrefused|econnreset|enotfound|fetch failed|unreachable|broken pipe", "i"), code: "TOOL.EXECUTION.DEPENDENCY_FAILED" },
1296
- { re: new RegExp("\\bauth|unauthorized|forbidden|permission|\\b401\\b|\\b403\\b", "i"), code: "TOOL.INVOCATION.PERMISSION_DENIED" },
1297
- { re: new RegExp("json|syntaxerror|unexpected token|decodeerror", "i"), code: "PERCEPTION.PARSING.JSON_INVALID" }
1751
+ { re: new RegExp("timeout|timedout|aborted", "u"), code: "TOOL.EXECUTION.TIMEOUT" },
1752
+ { re: new RegExp("rate[^\\n]?limit|(?<![\\p{L}\\p{N}_])429(?![\\p{L}\\p{N}_])|too many requests", "u"), code: "TOOL.EXECUTION.RATE_LIMITED" },
1753
+ { re: new RegExp("connection|econnrefused|econnreset|enotfound|fetch failed|unreachable|broken pipe", "u"), code: "TOOL.EXECUTION.DEPENDENCY_FAILED" },
1754
+ { 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" },
1755
+ { re: new RegExp("json|syntaxerror|unexpected token|decodeerror", "u"), code: "PERCEPTION.PARSING.JSON_INVALID" }
1298
1756
  ];
1299
1757
  var GENERIC_FALLBACK = "TOOL.EXECUTION.CRASHED";
1300
1758
 
@@ -1311,6 +1769,16 @@ var GuardRejectedError = class extends Error {
1311
1769
  this.phase = phase;
1312
1770
  }
1313
1771
  };
1772
+ function guardText(message) {
1773
+ if (!message || typeof message !== "object") return null;
1774
+ const content = message.content;
1775
+ if (typeof content === "string") return content === "" ? null : content;
1776
+ if (Array.isArray(content)) {
1777
+ const texts = content.filter((p) => !!p && typeof p === "object" && p.type === "text" && typeof p.text === "string").map((p) => p.text);
1778
+ if (texts.length > 0) return texts.join("\n");
1779
+ }
1780
+ return null;
1781
+ }
1314
1782
  function createInterceptContext(operationType, operationName, options) {
1315
1783
  return {
1316
1784
  operationType,
@@ -1370,8 +1838,8 @@ var DefaultFixInterceptor = class {
1370
1838
  }
1371
1839
  if (modifiedMessages && this._config.enabled) {
1372
1840
  for (const msg of modifiedMessages) {
1373
- const content = msg.content;
1374
- if (typeof content === "string") {
1841
+ const content = guardText(msg);
1842
+ if (content !== null) {
1375
1843
  for (const fix of this._cache.getAll()) {
1376
1844
  if (fix.fixType === "guard") {
1377
1845
  const { passed, result } = this._applier.applyGuardFix(
@@ -1516,7 +1984,13 @@ var DefaultFixInterceptor = class {
1516
1984
  }
1517
1985
  };
1518
1986
  function classifyError(error) {
1519
- const haystack = `${error?.constructor?.name ?? "Error"} ${error?.message ?? ""}`;
1987
+ const message = String(error?.message ?? "").toLowerCase();
1988
+ for (const rule of CORE_RULES) {
1989
+ if (rule.re.test(message)) {
1990
+ return CANONICAL_ERROR_CODES.has(rule.code) ? rule.code : GENERIC_FALLBACK;
1991
+ }
1992
+ }
1993
+ const haystack = `${error?.constructor?.name ?? "Error"} ${String(error?.message ?? "")}`.toLowerCase();
1520
1994
  for (const rule of SUPPLEMENTAL_RULES) {
1521
1995
  if (rule.re.test(haystack)) {
1522
1996
  return CANONICAL_ERROR_CODES.has(rule.code) ? rule.code : GENERIC_FALLBACK;
@@ -1532,6 +2006,9 @@ function storage() {
1532
2006
  function getContext() {
1533
2007
  return storage().getStore() ?? {};
1534
2008
  }
2009
+ function hasContextScope() {
2010
+ return storage().getStore() !== void 0;
2011
+ }
1535
2012
  function runWithContext(overrides, fn) {
1536
2013
  const parent = getContext();
1537
2014
  const merged = { ...parent, ...overrides };
@@ -1588,7 +2065,8 @@ function getCurrentContext() {
1588
2065
  // src/tracer.ts
1589
2066
  function attachErrorCode(span, error) {
1590
2067
  try {
1591
- const err = error instanceof Error ? error : new Error(String(error));
2068
+ const ownMessage = error !== null && typeof error === "object" ? error.message : void 0;
2069
+ const err = error instanceof Error ? error : new Error(typeof ownMessage === "string" ? ownMessage : String(error));
1592
2070
  const code = classifyError(err);
1593
2071
  if (code) {
1594
2072
  span.setAttribute("error.code", code);
@@ -1690,6 +2168,7 @@ var Tracer = class {
1690
2168
  (error) => {
1691
2169
  span.recordException(error instanceof Error ? error : String(error));
1692
2170
  attachErrorCode(span, error);
2171
+ markCancel(span, error);
1693
2172
  span.end();
1694
2173
  throw error;
1695
2174
  }
@@ -1700,6 +2179,7 @@ var Tracer = class {
1700
2179
  } catch (error) {
1701
2180
  span.recordException(error instanceof Error ? error : String(error));
1702
2181
  attachErrorCode(span, error);
2182
+ markCancel(span, error);
1703
2183
  span.end();
1704
2184
  throw error;
1705
2185
  }
@@ -1719,7 +2199,7 @@ var Tracer = class {
1719
2199
  const session2 = getCurrentSession();
1720
2200
  const agent2 = getCurrentAgent();
1721
2201
  const phase = getCurrentPhase();
1722
- const traceId = opts.traceId ?? parentSpan?.traceId ?? generateTraceId();
2202
+ const traceId = opts.traceId ?? parentSpan?.traceId ?? getContext()._rootTraceId ?? generateTraceId();
1723
2203
  if (!parentSpan) {
1724
2204
  if (getContext()._traceSampled === false) {
1725
2205
  return NOOP_SPAN;
@@ -1755,15 +2235,24 @@ var Tracer = class {
1755
2235
  );
1756
2236
  }
1757
2237
  };
2238
+ function markCancel(span, error) {
2239
+ if (error instanceof Error && error.name === "AbortError") {
2240
+ span.setAttribute("risicare.cancelled", true);
2241
+ span.setAttribute("risicare.cancel_type", "AbortError");
2242
+ }
2243
+ }
1758
2244
 
1759
2245
  // src/version.ts
1760
- var SDK_VERSION = "0.6.0";
2246
+ var SDK_VERSION = "0.8.0";
1761
2247
 
1762
2248
  // src/exporters/http.ts
1763
2249
  var CAPACITY_REFUSAL_STATUSES = /* @__PURE__ */ new Set([429, 503]);
1764
2250
  var RETRY_AFTER_CEILING_MS = 1e4;
1765
2251
  var REFUSAL_BACKOFF_BASE_MS = 1e3;
1766
2252
  var REFUSAL_NO_HINT = -1;
2253
+ var MISROUTE_WARN_WINDOW_MS = 3e5;
2254
+ var AUTH_REFUSAL_STATUSES = /* @__PURE__ */ new Set([401, 403]);
2255
+ var FAILURE_WARN_WINDOW_MS = 3e5;
1767
2256
  var HttpExporter = class {
1768
2257
  name = "http";
1769
2258
  _endpoint;
@@ -1779,18 +2268,24 @@ var HttpExporter = class {
1779
2268
  // cooldown gives the gateway time to come back before the half-open
1780
2269
  // probe fires. Lower numbers (was 3@30s) tripped on transient blips.
1781
2270
  _consecutiveFailures = 0;
2271
+ _lastMisrouteWarnAt = -Infinity;
2272
+ _lastFailureWarnAt = -Infinity;
1782
2273
  /**
1783
- * F-SDK503-001. Set by `_sendRequest` when a response is a CAPACITY REFUSAL, read by the
1784
- * retry loop and the breaker. `null` = not a refusal; `REFUSAL_NO_HINT` = refused with no
1785
- * `Retry-After`; otherwise the honoured delay in ms.
1786
- *
1787
- * ⚠ Node has ONE thread and `export()` is `async`, so two concurrent exports interleave on
1788
- * this field at every `await`. It is written immediately after the awaited `fetch` resolves
1789
- * and read on the very next statement, with no `await` between — so the value cannot be
1790
- * clobbered mid-decision. The Python twin carries the same per-call state on `self` for the
1791
- * same reason (its `_send_request` signature is pin-locked).
2274
+ * The kind of failure that the last outage WARNING named ('auth', 'http', 'none',
2275
+ * 'unknown'). `null` after a success. A new kind in the same outage writes one more
2276
+ * WARNING, also inside the window.
1792
2277
  */
1793
- _lastRefusalAfterMs = null;
2278
+ _failureKind = null;
2279
+ /** The endpoint as a log line may show it: no userinfo, no query (see `safeUrl`). */
2280
+ _safeEndpoint;
2281
+ /** The endpoint holds userinfo. `fetch` refuses such a URL. */
2282
+ _endpointHasCredentials;
2283
+ /** The calls in progress, by their batch, so that `abort(spans)` stops the right one. */
2284
+ _calls = /* @__PURE__ */ new Map();
2285
+ /** The ack of each finished call, by its batch. Read once by `takeAck(spans)`. */
2286
+ _acks = /* @__PURE__ */ new WeakMap();
2287
+ /** The spans of each finished call that could not be serialized, by its batch. */
2288
+ _unserializable = /* @__PURE__ */ new WeakMap();
1794
2289
  _circuitOpenUntil = 0;
1795
2290
  _circuitBreakerThreshold = 5;
1796
2291
  _circuitBreakerCooldownMs = 6e4;
@@ -1802,9 +2297,105 @@ var HttpExporter = class {
1802
2297
  this._timeoutMs = options.timeoutMs ?? 5e3;
1803
2298
  this._maxRetries = options.maxRetries ?? 3;
1804
2299
  this._compress = options.compress ?? false;
2300
+ this._safeEndpoint = safeUrl(this._endpoint);
2301
+ this._endpointHasCredentials = hasCredentials(this._endpoint);
1805
2302
  }
2303
+ /**
2304
+ * Network or error text for a log line: the endpoint as `safeUrl` gives it, and no
2305
+ * form of the API key (`utils/scrub.ts`).
2306
+ */
2307
+ _scrub(text, limit = 200) {
2308
+ let out;
2309
+ try {
2310
+ out = text instanceof Error ? `${text.name}: ${text.message}` : String(text);
2311
+ } catch {
2312
+ out = typeof text;
2313
+ }
2314
+ if (this._safeEndpoint !== this._endpoint) out = out.split(this._endpoint).join(this._safeEndpoint);
2315
+ return scrubText(out, [this._apiKey], limit);
2316
+ }
2317
+ /** Hide the key from `util.inspect` and `console.log` of the exporter. */
2318
+ [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
2319
+ return `HttpExporter { endpoint: '${this._safeEndpoint}' }`;
2320
+ }
2321
+ /** The most requests that one `export()` call sends (`maxRetries`). */
2322
+ get attemptsPerExport() {
2323
+ return this._maxRetries;
2324
+ }
2325
+ /**
2326
+ * Returns the counts of the ack that the `export()` call for `spans` received, and clears
2327
+ * them. The answer is kept per batch, not on the instance: two processors that share this
2328
+ * exporter cannot read each other's ack across an `await`.
2329
+ */
2330
+ takeAck(spans) {
2331
+ const ack = this._acks.get(spans) ?? null;
2332
+ this._acks.delete(spans);
2333
+ return ack;
2334
+ }
2335
+ /** Returns the spans of `spans` that could not be serialized and were not sent, and clears them. */
2336
+ takeUnserializable(spans) {
2337
+ const bad = this._unserializable.get(spans) ?? [];
2338
+ this._unserializable.delete(spans);
2339
+ return bad;
2340
+ }
2341
+ /**
2342
+ * Cancel the `export()` call for `spans` (all calls when `spans` is not given): its
2343
+ * request, its retries and its backoff sleep. The batch processor calls it when
2344
+ * `shutdown()` abandons the batch, so that the call does not keep the process alive. The
2345
+ * cancelled call returns FAILURE, changes no counter (the circuit breaker included) and
2346
+ * logs no WARNING.
2347
+ */
2348
+ abort(spans) {
2349
+ if (spans !== void 0) this._calls.get(spans)?.cancel.abort();
2350
+ else for (const call of this._calls.values()) call.cancel.abort();
2351
+ }
2352
+ /**
2353
+ * Send one batch. The limits are the request timeout and `maxRetries`.
2354
+ *
2355
+ * ⚠ NO CALLER BUDGET. `flush(timeoutMs)` only stops WAITING at its deadline; it never
2356
+ * cuts a request that is already sent. A short flush budget that cut the request made a
2357
+ * healthy, slow server look like a failure: the span used a retry, the breaker moved, and
2358
+ * the server stored the same spans again. Only `abort()` stops the call, and only
2359
+ * `shutdown()` calls it.
2360
+ */
1806
2361
  async export(spans) {
1807
2362
  if (spans.length === 0) return "success" /* SUCCESS */;
2363
+ const call = {
2364
+ cancel: new AbortController(),
2365
+ refusalAfterMs: null,
2366
+ misroute: null,
2367
+ noRetry: false,
2368
+ status: null,
2369
+ error: null
2370
+ };
2371
+ this._calls.set(spans, call);
2372
+ try {
2373
+ return await this._export(spans, call);
2374
+ } finally {
2375
+ this._calls.delete(spans);
2376
+ }
2377
+ }
2378
+ async _export(spans, call) {
2379
+ const cancelled = call.cancel.signal;
2380
+ const parts = [];
2381
+ const bad = [];
2382
+ let errorClass = "";
2383
+ for (const span of spans) {
2384
+ try {
2385
+ parts.push(JSON.stringify(span.toPayload()));
2386
+ } catch (e) {
2387
+ bad.push(span);
2388
+ errorClass ||= e instanceof Error ? e.name : typeof e;
2389
+ }
2390
+ }
2391
+ if (bad.length > 0) {
2392
+ this._unserializable.set(spans, bad);
2393
+ warn(
2394
+ `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).`
2395
+ );
2396
+ }
2397
+ if (parts.length === 0) return "success" /* SUCCESS */;
2398
+ const payload = `{"spans":[${parts.join(",")}]` + (this._projectId ? `,"projectId":${JSON.stringify(this._projectId)}` : "") + (this._environment ? `,"environment":${JSON.stringify(this._environment)}` : "") + "}";
1808
2399
  const now = Date.now();
1809
2400
  let isHalfOpen = false;
1810
2401
  if (this._consecutiveFailures >= this._circuitBreakerThreshold) {
@@ -1813,34 +2404,64 @@ var HttpExporter = class {
1813
2404
  }
1814
2405
  isHalfOpen = true;
1815
2406
  }
1816
- const body = {
1817
- spans: spans.map((s) => s.toPayload())
1818
- };
1819
- if (this._projectId) body.projectId = this._projectId;
1820
- if (this._environment) body.environment = this._environment;
1821
2407
  const maxAttempts = isHalfOpen ? 1 : this._maxRetries;
2408
+ let attempts = 0;
1822
2409
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
1823
- this._lastRefusalAfterMs = null;
1824
- const result = await this._sendRequest(body);
2410
+ call.refusalAfterMs = null;
2411
+ call.misroute = null;
2412
+ call.noRetry = false;
2413
+ call.status = null;
2414
+ call.error = null;
2415
+ attempts++;
2416
+ const result = await this._sendRequest(payload, parts.length, call, spans);
2417
+ if (cancelled.aborted) {
2418
+ this._acks.delete(spans);
2419
+ return "failure" /* FAILURE */;
2420
+ }
1825
2421
  if (result === "success" /* SUCCESS */) {
1826
2422
  this._consecutiveFailures = 0;
2423
+ this._failureKind = null;
1827
2424
  return result;
1828
2425
  }
2426
+ if (call.misroute !== null || call.noRetry) break;
2427
+ if (call.status !== null && AUTH_REFUSAL_STATUSES.has(call.status)) break;
1829
2428
  if (attempt < maxAttempts - 1) {
1830
- const refusal = this._lastRefusalAfterMs;
2429
+ const refusal = call.refusalAfterMs;
1831
2430
  const delay = refusal === null ? 100 * Math.pow(2, attempt) : refusal === REFUSAL_NO_HINT ? REFUSAL_BACKOFF_BASE_MS * Math.pow(2, attempt) : refusal;
1832
- await sleep(delay);
2431
+ await sleep(delay, cancelled);
2432
+ if (cancelled.aborted) return "failure" /* FAILURE */;
1833
2433
  }
1834
2434
  }
1835
- const refusedForCapacity = this._lastRefusalAfterMs !== null;
1836
- this._lastRefusalAfterMs = null;
1837
- if (refusedForCapacity) {
2435
+ if (call.refusalAfterMs !== null) {
1838
2436
  warn(
1839
- `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.`
2437
+ `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.`
1840
2438
  );
1841
2439
  return "failure" /* FAILURE */;
1842
2440
  }
2441
+ const misroute = call.misroute;
2442
+ if (misroute !== null && Date.now() - this._lastMisrouteWarnAt > MISROUTE_WARN_WINDOW_MS) {
2443
+ this._lastMisrouteWarnAt = Date.now();
2444
+ warn(
2445
+ `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.`
2446
+ );
2447
+ }
1843
2448
  this._consecutiveFailures++;
2449
+ if (misroute === null && !call.noRetry) {
2450
+ const status = call.status;
2451
+ const kind = status !== null && AUTH_REFUSAL_STATUSES.has(status) ? "auth" : status !== null ? "http" : call.error !== null ? "none" : "unknown";
2452
+ let write = false;
2453
+ if (this._consecutiveFailures === 1 || this._failureKind === null) {
2454
+ if (Date.now() - this._lastFailureWarnAt > FAILURE_WARN_WINDOW_MS) {
2455
+ this._lastFailureWarnAt = Date.now();
2456
+ write = true;
2457
+ }
2458
+ this._failureKind = kind;
2459
+ } else if (kind !== this._failureKind) {
2460
+ this._failureKind = kind;
2461
+ write = true;
2462
+ }
2463
+ if (write) this._warnOutage(kind, status, call.error);
2464
+ }
1844
2465
  if (this._consecutiveFailures >= this._circuitBreakerThreshold) {
1845
2466
  this._circuitOpenUntil = Date.now() + this._circuitBreakerCooldownMs;
1846
2467
  warn(
@@ -1849,6 +2470,38 @@ var HttpExporter = class {
1849
2470
  }
1850
2471
  return "failure" /* FAILURE */;
1851
2472
  }
2473
+ /** The outage WARNING for one kind of failure. */
2474
+ _warnOutage(kind, status, error) {
2475
+ const where = `Risicare: spans are NOT reaching ${this._safeEndpoint}`;
2476
+ const tail = "Tracing continues, but the SDK drops the spans that it cannot send.";
2477
+ if (kind === "auth") {
2478
+ warn(
2479
+ `${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}`
2480
+ );
2481
+ } else if (kind === "http") {
2482
+ warn(
2483
+ `${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.`
2484
+ );
2485
+ } else if (kind === "none" && this._endpointHasCredentials) {
2486
+ warn(
2487
+ `${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}`
2488
+ );
2489
+ } else if (kind === "none") {
2490
+ warn(
2491
+ `${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.`
2492
+ );
2493
+ } else {
2494
+ warn(
2495
+ `${where}: the export failed. Common causes: an invalid apiKey or an unreachable endpoint. ${tail} Set debug: true to see each attempt.`
2496
+ );
2497
+ }
2498
+ }
2499
+ /** Record a MISROUTE for the retry loop and the breaker. Always returns FAILURE. */
2500
+ _noteMisroute(call, answer) {
2501
+ call.misroute = this._scrub(answer, 300);
2502
+ debug(`Ingest misroute: ${call.misroute}`);
2503
+ return "failure" /* FAILURE */;
2504
+ }
1852
2505
  /**
1853
2506
  * Record a CAPACITY REFUSAL for the retry loop. Returns true if it was one.
1854
2507
  *
@@ -1856,7 +2509,7 @@ var HttpExporter = class {
1856
2509
  * HTTP-date); anything else falls back to our own backoff rather than guessing at a date
1857
2510
  * parse.
1858
2511
  */
1859
- _noteRefusal(status, retryAfterRaw) {
2512
+ _noteRefusal(call, status, retryAfterRaw) {
1860
2513
  if (!CAPACITY_REFUSAL_STATUSES.has(status)) return false;
1861
2514
  let delay = REFUSAL_NO_HINT;
1862
2515
  if (retryAfterRaw) {
@@ -1865,11 +2518,13 @@ var HttpExporter = class {
1865
2518
  delay = Math.min(secs * 1e3, RETRY_AFTER_CEILING_MS);
1866
2519
  }
1867
2520
  }
1868
- this._lastRefusalAfterMs = delay;
1869
- debug(`Ingest refused for capacity: HTTP ${status} (Retry-After=${retryAfterRaw})`);
2521
+ call.refusalAfterMs = delay;
2522
+ debug(`Ingest refused for capacity: HTTP ${status} (Retry-After=${this._scrub(retryAfterRaw)})`);
1870
2523
  return true;
1871
2524
  }
1872
- async _sendRequest(body) {
2525
+ async _sendRequest(body, spansSent, call, spans) {
2526
+ const cancelled = call.cancel.signal;
2527
+ const timeoutMs = this._timeoutMs;
1873
2528
  const url = `${this._endpoint}/v1/spans`;
1874
2529
  const headers = {
1875
2530
  "Content-Type": "application/json",
@@ -1884,83 +2539,156 @@ var HttpExporter = class {
1884
2539
  if (this._apiKey) {
1885
2540
  headers["Authorization"] = `Bearer ${this._apiKey}`;
1886
2541
  }
1887
- let payload = JSON.stringify(body);
2542
+ let payload = body;
1888
2543
  if (this._compress && payload.length > 1024) {
1889
2544
  try {
1890
2545
  const { gzipSync } = await import("zlib");
1891
2546
  payload = gzipSync(Buffer.from(payload));
1892
2547
  headers["Content-Encoding"] = "gzip";
1893
2548
  } catch (e) {
1894
- debug(`Gzip compression failed, sending uncompressed: ${e}`);
2549
+ debug(`Gzip compression failed, sending uncompressed: ${this._scrub(e)}`);
1895
2550
  }
1896
2551
  }
2552
+ const controller = new AbortController();
2553
+ const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
2554
+ const onCancel = () => controller.abort();
2555
+ cancelled.addEventListener("abort", onCancel, { once: true });
2556
+ if (cancelled.aborted) controller.abort();
1897
2557
  try {
1898
- const controller = new AbortController();
1899
- const timeoutId = setTimeout(() => controller.abort(), this._timeoutMs);
1900
2558
  const response = await fetch(url, {
1901
2559
  method: "POST",
1902
2560
  headers,
1903
2561
  body: payload,
1904
- signal: controller.signal
2562
+ signal: controller.signal,
2563
+ // Never follow: a redirect is a misroute (see MISROUTE_WARN_WINDOW_MS). Node returns
2564
+ // the 3xx itself; a browser-like runtime returns type 'opaqueredirect' with status 0.
2565
+ redirect: "manual"
1905
2566
  });
1906
- clearTimeout(timeoutId);
1907
- if (response.status < 300) {
1908
- return await checkAck(response);
2567
+ call.status = response.status;
2568
+ const redirected = response.type === "opaqueredirect";
2569
+ if (redirected || response.status >= 300 && response.status < 400) {
2570
+ const location = response.headers?.get?.("Location");
2571
+ const target = location ? this._scrub(location, 1e3) : "no Location header";
2572
+ return this._noteMisroute(call, `HTTP ${response.status || "3xx"}, a redirect to ${target}`);
2573
+ }
2574
+ if (response.status >= 200 && response.status < 300) {
2575
+ const ack = await checkAck(response, spansSent, (t) => this._scrub(t, 1e3));
2576
+ if (ack === null) {
2577
+ if (controller.signal.aborted) {
2578
+ call.status = null;
2579
+ call.error = `timeout after ${timeoutMs} ms`;
2580
+ debug(`HTTP export timeout: the ack body did not arrive within ${timeoutMs} ms`);
2581
+ return "timeout" /* TIMEOUT */;
2582
+ }
2583
+ return this._noteMisroute(
2584
+ call,
2585
+ `HTTP ${response.status} and a body that is not a Risicare ack (content-type: ${response.headers?.get?.("Content-Type") || "none"})`
2586
+ );
2587
+ }
2588
+ if (ack.result === "success" /* SUCCESS */) this._acks.set(spans, ack.counts);
2589
+ if (ack.final) call.noRetry = true;
2590
+ return ack.result;
1909
2591
  } else if (response.status === 408 || response.status === 504) {
1910
2592
  debug(`HTTP export timeout: ${response.status}`);
1911
2593
  return "timeout" /* TIMEOUT */;
1912
2594
  }
1913
- this._noteRefusal(response.status, response.headers.get("Retry-After"));
2595
+ this._noteRefusal(call, response.status, response.headers.get("Retry-After"));
1914
2596
  debug(`HTTP export failed: ${response.status}`);
1915
2597
  return "failure" /* FAILURE */;
1916
2598
  } catch (e) {
1917
- debug(`HTTP export error: ${e}`);
2599
+ const cause = e instanceof Error ? e.cause : void 0;
2600
+ call.error = controller.signal.aborted ? `timeout after ${timeoutMs} ms` : typeof cause?.code === "string" ? cause.code : e instanceof Error ? e.name : "Error";
2601
+ debug(`HTTP export error: ${this._scrub(e)}`);
1918
2602
  return "failure" /* FAILURE */;
2603
+ } finally {
2604
+ clearTimeout(timeoutId);
2605
+ cancelled.removeEventListener("abort", onCancel);
1919
2606
  }
1920
2607
  }
1921
2608
  shutdown() {
1922
2609
  }
1923
2610
  };
1924
- function sleep(ms) {
1925
- return new Promise((resolve) => setTimeout(resolve, ms));
2611
+ function sleep(ms, signal) {
2612
+ return new Promise((resolve) => {
2613
+ if (signal?.aborted) return resolve();
2614
+ const done = () => {
2615
+ clearTimeout(timer);
2616
+ signal?.removeEventListener("abort", done);
2617
+ resolve();
2618
+ };
2619
+ const timer = setTimeout(done, ms);
2620
+ signal?.addEventListener("abort", done, { once: true });
2621
+ });
1926
2622
  }
1927
2623
  function asCount(v) {
1928
2624
  return typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : void 0;
1929
2625
  }
1930
- async function checkAck(response) {
2626
+ var MAX_ACK_REASONS = 3;
2627
+ var MAX_ACK_REASON_CHARS = 200;
2628
+ function oneLine(text) {
2629
+ return text.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ");
2630
+ }
2631
+ function ackReasons(body) {
2632
+ const reasons = [];
2633
+ const errors = body.errors;
2634
+ if (Array.isArray(errors)) {
2635
+ for (const entry of errors) {
2636
+ const text = entry?.error;
2637
+ if (typeof text !== "string" || text.length === 0) continue;
2638
+ const cut = oneLine(text).slice(0, MAX_ACK_REASON_CHARS);
2639
+ if (!reasons.includes(cut)) reasons.push(cut);
2640
+ if (reasons.length === MAX_ACK_REASONS) break;
2641
+ }
2642
+ }
2643
+ if (reasons.length === 0) {
2644
+ const message = typeof body.errorMessage === "string" && body.errorMessage || typeof body.error_message === "string" && body.error_message || "";
2645
+ if (message) reasons.push(oneLine(message).slice(0, MAX_ACK_REASON_CHARS));
2646
+ }
2647
+ return reasons.length === 0 ? "No reason was returned." : `Reasons: ${reasons.join("; ")}`;
2648
+ }
2649
+ async function checkAck(response, spansSent, scrub) {
1931
2650
  let payload;
1932
2651
  try {
1933
2652
  payload = await response.json();
1934
2653
  } catch {
1935
- return "success" /* SUCCESS */;
2654
+ return null;
1936
2655
  }
1937
2656
  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
1938
- return "success" /* SUCCESS */;
2657
+ return null;
1939
2658
  }
1940
2659
  const body = payload;
1941
2660
  const accepted = asCount(body.accepted);
1942
2661
  const rejected = asCount(body.rejected);
1943
- if (accepted === void 0 || rejected === void 0 || rejected <= 0) {
1944
- return "success" /* SUCCESS */;
2662
+ if (accepted === void 0 || rejected === void 0) return null;
2663
+ const counts = { accepted, rejected };
2664
+ if (accepted === 0 && rejected === 0 && spansSent > 0) {
2665
+ warn(
2666
+ `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.`
2667
+ );
2668
+ return { result: "failure" /* FAILURE */, counts, final: true };
1945
2669
  }
1946
- const errors = body.errors;
1947
- 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.";
2670
+ if (rejected === 0) return { result: "success" /* SUCCESS */, counts, final: false };
1948
2671
  const total = accepted + rejected;
1949
2672
  if (accepted === 0) {
1950
2673
  warn(
1951
- `Risicare: the backend accepted 0 of ${total} span(s) and rejected ${rejected} \u2014 this batch was NOT stored. ${detail}`
2674
+ `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))}`
1952
2675
  );
1953
- return "failure" /* FAILURE */;
2676
+ return { result: "success" /* SUCCESS */, counts, final: false };
1954
2677
  }
1955
2678
  warn(
1956
- `Risicare: the backend rejected ${rejected} of ${total} span(s); the remaining ${accepted} were stored. Those ${rejected} are permanently lost and are NOT retried. ${detail}`
2679
+ `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))}`
1957
2680
  );
1958
- return "success" /* SUCCESS */;
2681
+ return { result: "success" /* SUCCESS */, counts, final: false };
1959
2682
  }
1960
2683
 
1961
2684
  // src/exporters/console.ts
1962
2685
  var ConsoleExporter = class {
1963
2686
  name = "console";
2687
+ /**
2688
+ * It only shows spans locally, so its success is not a delivery. When another
2689
+ * exporter is present, the batch processor ignores this exporter's result.
2690
+ */
2691
+ countsAsDelivery = false;
1964
2692
  export(spans) {
1965
2693
  for (const span of spans) {
1966
2694
  const payload = span.toPayload();
@@ -1974,6 +2702,17 @@ var ConsoleExporter = class {
1974
2702
  }
1975
2703
  };
1976
2704
 
2705
+ // src/utils/stream-proxy.ts
2706
+ function endOpenProviderSpans() {
2707
+ let open;
2708
+ try {
2709
+ open = [...getProviderSpanState().open];
2710
+ } catch {
2711
+ return;
2712
+ }
2713
+ for (const o of open) o.end("shutdown");
2714
+ }
2715
+
1977
2716
  // src/runtime/cache.ts
1978
2717
  var FixCache = class {
1979
2718
  _ttlMs;
@@ -2149,6 +2888,94 @@ function emptyResult(fix, fixType) {
2149
2888
  modifications: {}
2150
2889
  };
2151
2890
  }
2891
+ var SAME_ESCAPES = "bBdDsSwWfnrtv";
2892
+ var SAME_ESCAPES_IN_CLASS = "bdDsSwWfnrtv";
2893
+ var LEADING_INLINE_FLAGS = /^\(\?([ims]+)\)/;
2894
+ var PY_NAMED_GROUP = /^\(\?P<([A-Za-z_][A-Za-z0-9_]*)>/;
2895
+ var PY_NAMED_BACKREF = /^\(\?P=([A-Za-z_][A-Za-z0-9_]*)\)/;
2896
+ var JS_NAMED_GROUP = /^\(\?<([A-Za-z_][A-Za-z0-9_]*)>/;
2897
+ function translatePythonPattern(pattern) {
2898
+ let flags = "i";
2899
+ let rest = pattern;
2900
+ const m = LEADING_INLINE_FLAGS.exec(rest);
2901
+ if (m) {
2902
+ for (const f of m[1]) if (!flags.includes(f)) flags += f;
2903
+ rest = rest.slice(m[0].length);
2904
+ }
2905
+ const names = /* @__PURE__ */ new Set();
2906
+ const addName = (name) => {
2907
+ if (names.has(name)) throw new Error("a group name occurs two times");
2908
+ names.add(name);
2909
+ };
2910
+ let source = "";
2911
+ let inClass = false;
2912
+ for (let i = 0; i < rest.length; i++) {
2913
+ const c = rest[i];
2914
+ if (c === "\\" && i + 1 < rest.length) {
2915
+ const next = rest[i + 1];
2916
+ if (/[A-Za-z]/.test(next)) {
2917
+ if (!inClass && next === "A") {
2918
+ source += "(?<![\\s\\S])";
2919
+ i++;
2920
+ continue;
2921
+ }
2922
+ if (!inClass && next === "Z") {
2923
+ source += "(?![\\s\\S])";
2924
+ i++;
2925
+ continue;
2926
+ }
2927
+ if (next === "x" || next === "u") {
2928
+ const n = next === "x" ? 2 : 4;
2929
+ const hex = rest.slice(i + 2, i + 2 + n);
2930
+ if (!new RegExp(`^[0-9A-Fa-f]{${n}}$`).test(hex)) throw new Error("short hex escape");
2931
+ source += c + next + hex;
2932
+ i += 1 + n;
2933
+ continue;
2934
+ }
2935
+ if (!(inClass ? SAME_ESCAPES_IN_CLASS : SAME_ESCAPES).includes(next)) {
2936
+ throw new Error("an escape that Python and JavaScript read differently");
2937
+ }
2938
+ }
2939
+ source += c + next;
2940
+ i++;
2941
+ continue;
2942
+ }
2943
+ if (inClass) {
2944
+ if (c === "]") inClass = false;
2945
+ source += c;
2946
+ continue;
2947
+ }
2948
+ if (c === "[") {
2949
+ inClass = true;
2950
+ source += c;
2951
+ continue;
2952
+ }
2953
+ const tail = rest.slice(i);
2954
+ let g;
2955
+ if ((g = PY_NAMED_GROUP.exec(tail)) || (g = JS_NAMED_GROUP.exec(tail))) {
2956
+ addName(g[1]);
2957
+ source += `(?<${g[1]}>`;
2958
+ i += g[0].length - 1;
2959
+ continue;
2960
+ }
2961
+ if (g = PY_NAMED_BACKREF.exec(tail)) {
2962
+ source += `\\k<${g[1]}>`;
2963
+ i += g[0].length - 1;
2964
+ continue;
2965
+ }
2966
+ source += c;
2967
+ }
2968
+ return { source, flags };
2969
+ }
2970
+ var warnedGuardPatterns = /* @__PURE__ */ new Set();
2971
+ function warnUnusablePattern(fixId, index) {
2972
+ const key = `${fixId ?? "unknown"}\0${index}`;
2973
+ if (warnedGuardPatterns.has(key)) return;
2974
+ warnedGuardPatterns.add(key);
2975
+ warn(
2976
+ 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.`
2977
+ );
2978
+ }
2152
2979
  var FixApplier = class {
2153
2980
  _config;
2154
2981
  _cache;
@@ -2406,6 +3233,26 @@ var FixApplier = class {
2406
3233
  * - content_filter: Regex-based blocked patterns
2407
3234
  * - format_check: JSON.parse() validity
2408
3235
  * - input_validation / output_validation: min/max length
3236
+ *
3237
+ * `content_filter` searches the content for each entry of `blocked_patterns`
3238
+ * (case-insensitive, after `translatePythonPattern`). It fails CLOSED: when
3239
+ * `blocked_patterns` is not a list, or an entry is empty, is not a string,
3240
+ * is longer than 500 characters or cannot be used, the guard does not pass.
3241
+ * One WARNING names the fix id and the pattern index, once for each pair in
3242
+ * the process. The reason names the pattern index, never the pattern or the
3243
+ * content.
3244
+ *
3245
+ * Limits:
3246
+ * - The interceptor runs only on the OpenAI chat patch (input guards) and on
3247
+ * `interceptCall` / `interceptResponse`. It does not run when a framework
3248
+ * integration suppresses provider instrumentation.
3249
+ * - Each SDK uses its own regular-expression engine. These constructs can
3250
+ * give a different result in JavaScript and Python: `$` before a final
3251
+ * newline, Unicode case folding, `\d` and `\w` on non-ASCII text,
3252
+ * `\N{...}` and `\U........` (JavaScript fails closed), and a `]` first
3253
+ * in a class.
3254
+ * - A pattern has no time bound. A pattern with nested repeats can take a
3255
+ * very long time on a long input.
2409
3256
  */
2410
3257
  applyGuardFix(fix, content, isInput = true) {
2411
3258
  try {
@@ -2426,13 +3273,25 @@ var FixApplier = class {
2426
3273
  let passed = true;
2427
3274
  let reason;
2428
3275
  if (guardType === "content_filter") {
2429
- const blockedPatterns = guardConfig.blocked_patterns ?? guardConfig.blockedPatterns ?? [];
2430
- for (const pattern of blockedPatterns) {
2431
- const regex = this._safeCompileRegex(pattern);
2432
- if (regex && regex.test(content)) {
2433
- passed = false;
2434
- reason = `blocked pattern matched: ${pattern.slice(0, 80)}`;
2435
- break;
3276
+ const blockedPatterns = "blocked_patterns" in guardConfig ? guardConfig.blocked_patterns : "blockedPatterns" in guardConfig ? guardConfig.blockedPatterns : [];
3277
+ if (!Array.isArray(blockedPatterns)) {
3278
+ warnUnusablePattern(fix.fixId, -1);
3279
+ passed = false;
3280
+ reason = "blocked_patterns is not a list";
3281
+ } else {
3282
+ for (let index = 0; index < blockedPatterns.length; index++) {
3283
+ const regex = this._safeCompileRegex(blockedPatterns[index]);
3284
+ if (!regex) {
3285
+ warnUnusablePattern(fix.fixId, index);
3286
+ passed = false;
3287
+ reason = `blocked pattern ${index} is not usable`;
3288
+ break;
3289
+ }
3290
+ if (regex.test(content)) {
3291
+ passed = false;
3292
+ reason = `blocked pattern matched (pattern ${index})`;
3293
+ break;
3294
+ }
2436
3295
  }
2437
3296
  }
2438
3297
  } else if (guardType === "format_check") {
@@ -2493,11 +3352,17 @@ var FixApplier = class {
2493
3352
  /**
2494
3353
  * Safely compile a regex pattern from untrusted input.
2495
3354
  * Returns null if invalid or too long.
3355
+ *
3356
+ * F-029: the fix patterns are written for Python `re`. Before it compiles
3357
+ * the pattern, this function translates the Python forms that have an exact
3358
+ * JavaScript equivalent (see `translatePythonPattern`). The `i` flag is
3359
+ * always on, as in the Python applier.
2496
3360
  */
2497
3361
  _safeCompileRegex(pattern, maxLength = 500) {
2498
- if (!pattern || pattern.length > maxLength) return null;
3362
+ if (typeof pattern !== "string" || !pattern || pattern.length > maxLength) return null;
2499
3363
  try {
2500
- return new RegExp(pattern, "i");
3364
+ const { source, flags } = translatePythonPattern(pattern);
3365
+ return new RegExp(source, flags);
2501
3366
  } catch {
2502
3367
  debug(`Invalid regex pattern (length=${pattern.length})`);
2503
3368
  return null;
@@ -2573,6 +3438,8 @@ var FixLoader = class _FixLoader {
2573
3438
  _consecutiveFailures = 0;
2574
3439
  _circuitOpenUntil = 0;
2575
3440
  _onLoadCallbacks = [];
3441
+ // The HTTP status of the last load that got a non-2xx answer; null otherwise.
3442
+ _lastStatus = null;
2576
3443
  // Circuit breaker settings
2577
3444
  static CIRCUIT_BREAKER_THRESHOLD = 3;
2578
3445
  static CIRCUIT_BREAKER_COOLDOWN_MS = 3e4;
@@ -2580,6 +3447,43 @@ var FixLoader = class _FixLoader {
2580
3447
  this._config = resolveFixRuntimeConfig(config);
2581
3448
  this._cache = cache;
2582
3449
  }
3450
+ /** Error text for a log line: one line, the api endpoint as `safeUrl` gives it, no key. */
3451
+ _scrub(error) {
3452
+ let out;
3453
+ try {
3454
+ out = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
3455
+ } catch {
3456
+ out = typeof error;
3457
+ }
3458
+ const endpoint = (this._config.apiEndpoint ?? "").replace(/\/+$/, "");
3459
+ if (endpoint && safeUrl(endpoint) !== endpoint) out = out.split(endpoint).join(safeUrl(endpoint));
3460
+ return scrubText(out, [this._config.apiKey]);
3461
+ }
3462
+ /**
3463
+ * The WARNING for a failed first load: the request URL with no userinfo, no
3464
+ * query and no key, the HTTP status or the error class, and that tracing is
3465
+ * not affected. Never the error text: it can echo the URL with its query.
3466
+ */
3467
+ _firstLoadWarning(error) {
3468
+ let cause;
3469
+ if (this._lastStatus !== null) {
3470
+ cause = `HTTP ${this._lastStatus}`;
3471
+ } else {
3472
+ cause = error instanceof Error ? error.name : typeof error;
3473
+ const code = error?.cause?.code;
3474
+ if (typeof code === "string" && /^[A-Z][A-Z0-9_]*$/.test(code)) cause += ` (${code})`;
3475
+ }
3476
+ const endpoint = (this._config.apiEndpoint ?? "").replace(/\/+$/, "");
3477
+ return scrubText(
3478
+ `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.`,
3479
+ [this._config.apiKey],
3480
+ 500
3481
+ );
3482
+ }
3483
+ /** Hide the key from `util.inspect` and `console.log` of the loader. */
3484
+ [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
3485
+ return "FixLoader {}";
3486
+ }
2583
3487
  /** Timestamp of last successful load. */
2584
3488
  get lastLoadTime() {
2585
3489
  return this._lastLoadTime;
@@ -2600,13 +3504,13 @@ var FixLoader = class _FixLoader {
2600
3504
  return;
2601
3505
  }
2602
3506
  this.loadSync().catch((e) => {
2603
- debug(`Initial fix load failed: ${e}`);
3507
+ warn(this._firstLoadWarning(e));
2604
3508
  });
2605
3509
  if (this._config.autoRefresh) {
2606
3510
  this._startRefreshInterval();
2607
3511
  }
2608
3512
  } catch (e) {
2609
- debug(`FixLoader.start error: ${e}`);
3513
+ debug(`FixLoader.start error: ${this._scrub(e)}`);
2610
3514
  }
2611
3515
  }
2612
3516
  /** Stop the loader: clear the refresh interval. */
@@ -2617,7 +3521,7 @@ var FixLoader = class _FixLoader {
2617
3521
  this._refreshTimer = null;
2618
3522
  }
2619
3523
  } catch (e) {
2620
- debug(`FixLoader.stop error: ${e}`);
3524
+ debug(`FixLoader.stop error: ${this._scrub(e)}`);
2621
3525
  }
2622
3526
  }
2623
3527
  /**
@@ -2641,9 +3545,10 @@ var FixLoader = class _FixLoader {
2641
3545
  debug("Fix loader circuit breaker open \u2014 skipping load");
2642
3546
  return this._cache.getAll();
2643
3547
  }
3548
+ this._lastStatus = null;
2644
3549
  try {
2645
3550
  const endpoint = this._config.apiEndpoint.replace(/\/+$/, "");
2646
- const url = `${endpoint}/api/v1/fixes/active`;
3551
+ const url = `${endpoint}/v1/fixes/active`;
2647
3552
  const controller = new AbortController();
2648
3553
  const timeoutId = setTimeout(
2649
3554
  () => controller.abort(),
@@ -2660,6 +3565,7 @@ var FixLoader = class _FixLoader {
2660
3565
  });
2661
3566
  clearTimeout(timeoutId);
2662
3567
  if (!response.ok) {
3568
+ this._lastStatus = response.status;
2663
3569
  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
2664
3570
  }
2665
3571
  const data = await response.json();
@@ -2686,7 +3592,7 @@ var FixLoader = class _FixLoader {
2686
3592
  fixes.push(activeFixFromApiResponse(item));
2687
3593
  }
2688
3594
  } catch (e) {
2689
- debug(`Failed to parse fix item: ${e}`);
3595
+ debug(`Failed to parse fix item: ${this._scrub(e)}`);
2690
3596
  }
2691
3597
  }
2692
3598
  return fixes;
@@ -2699,7 +3605,7 @@ var FixLoader = class _FixLoader {
2699
3605
  try {
2700
3606
  callback(fixes);
2701
3607
  } catch (e) {
2702
- debug(`Load callback error: ${e}`);
3608
+ debug(`Load callback error: ${this._scrub(e)}`);
2703
3609
  }
2704
3610
  }
2705
3611
  debug(`Loaded ${fixes.length} active fixes`);
@@ -2713,14 +3619,14 @@ var FixLoader = class _FixLoader {
2713
3619
  );
2714
3620
  } else {
2715
3621
  debug(
2716
- `Fix load failed (attempt ${this._consecutiveFailures}): ${error.message}`
3622
+ `Fix load failed (attempt ${this._consecutiveFailures}): ${this._scrub(error)}`
2717
3623
  );
2718
3624
  }
2719
3625
  }
2720
3626
  _startRefreshInterval() {
2721
3627
  const tick = () => {
2722
3628
  this.loadSync().catch((e) => {
2723
- debug(`Background fix refresh failed: ${e}`);
3629
+ debug(`Background fix refresh failed: ${this._scrub(e)}`);
2724
3630
  });
2725
3631
  };
2726
3632
  this._refreshTimer = setInterval(
@@ -2988,6 +3894,78 @@ var TERMINATING_SIGNALS = [
2988
3894
  ];
2989
3895
  var BACKSTOP_MARGIN_MS = 500;
2990
3896
  var _finalMetrics;
3897
+ var SCORE_TIMEOUT_MS = 2e3;
3898
+ var _pendingScores = /* @__PURE__ */ new Set();
3899
+ var _failedScores = 0;
3900
+ var _failedScoresFlushMark = 0;
3901
+ var SCORE_MAX_IN_FLIGHT = 50;
3902
+ var SCORE_MAX_WAITING = 1e3;
3903
+ var SCORE_CAP_REASON = `not sent: ${SCORE_MAX_WAITING} scores wait for a free slot`;
3904
+ var SCORE_DEADLINE_REASON = "not sent before the deadline";
3905
+ var _scoresInFlight = 0;
3906
+ var _scoreWaiters = [];
3907
+ function _startWaitingScores() {
3908
+ while (_scoresInFlight < SCORE_MAX_IN_FLIGHT && _scoreWaiters.length > 0) {
3909
+ _scoreWaiters.shift().start();
3910
+ }
3911
+ }
3912
+ function _failWaitingScores(reason) {
3913
+ for (const waiter of _scoreWaiters.splice(0)) waiter.fail(reason);
3914
+ }
3915
+ var _scoreWarnWindowMs = 1e4;
3916
+ var SCORE_NAME_MAX = 200;
3917
+ var _scoreWarnedAt;
3918
+ var _scoreHeld = 0;
3919
+ var _scoreHeldReason = "";
3920
+ function _resetScoreFailures() {
3921
+ _failedScores = 0;
3922
+ _failedScoresFlushMark = 0;
3923
+ _scoreWarnedAt = void 0;
3924
+ _scoreHeld = 0;
3925
+ _scoreHeldReason = "";
3926
+ }
3927
+ function _heldText() {
3928
+ return ` ${_scoreHeld} more scores failed after the last warning. The last reason: ${_scoreHeldReason}.`;
3929
+ }
3930
+ function _scoreFailed(name, reason) {
3931
+ _failedScores += 1;
3932
+ const now = Date.now();
3933
+ if (_scoreWarnedAt !== void 0 && now - _scoreWarnedAt < _scoreWarnWindowMs) {
3934
+ _scoreHeld += 1;
3935
+ _scoreHeldReason = reason;
3936
+ return;
3937
+ }
3938
+ let message = `score ${JSON.stringify(name.slice(0, SCORE_NAME_MAX))} failed: ${reason}.`;
3939
+ if (_scoreHeld > 0) message += _heldText();
3940
+ _scoreWarnedAt = now;
3941
+ _scoreHeld = 0;
3942
+ _scoreHeldReason = "";
3943
+ warn(message);
3944
+ }
3945
+ function _warnHeldScores() {
3946
+ if (_scoreHeld === 0) return;
3947
+ const message = _heldText().trimStart();
3948
+ _scoreWarnedAt = Date.now();
3949
+ _scoreHeld = 0;
3950
+ _scoreHeldReason = "";
3951
+ warn(message);
3952
+ }
3953
+ async function _waitForPendingScores(timeoutMs) {
3954
+ if (_pendingScores.size === 0) return true;
3955
+ let timer;
3956
+ const expired = new Promise((resolve) => {
3957
+ timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
3958
+ });
3959
+ const settled = (async () => {
3960
+ while (_pendingScores.size > 0) await Promise.all([..._pendingScores]);
3961
+ return true;
3962
+ })();
3963
+ try {
3964
+ return await Promise.race([settled, expired]);
3965
+ } finally {
3966
+ clearTimeout(timer);
3967
+ }
3968
+ }
2991
3969
  var RisicareClient = class {
2992
3970
  config;
2993
3971
  processor;
@@ -3000,8 +3978,17 @@ var RisicareClient = class {
3000
3978
  _shutdownHandlers = [];
3001
3979
  constructor(config) {
3002
3980
  this.config = resolveConfig(config);
3003
- if (this.config.apiKey && !this.config.apiKey.startsWith("rsk-")) {
3004
- debug('Warning: API key should start with "rsk-". Got: ' + this.config.apiKey.slice(0, 4) + "...");
3981
+ const hasKnownPrefix = this.config.apiKey?.startsWith("rsk-") || this.config.apiKey?.startsWith("rski_") || this.config.apiKey?.startsWith("rsks_");
3982
+ if (this.config.apiKey && !hasKnownPrefix) {
3983
+ warn(
3984
+ 'the API key does not look like a Risicare key: it should start with "rsk-", "rski_" or "rsks_". Tracing continues with this key.'
3985
+ );
3986
+ }
3987
+ const tracingSetExplicitly = config?.enabled !== void 0 || (process.env.RISICARE_TRACING ?? "").trim() !== "";
3988
+ if (!this.config.apiKey && !this.config.enabled && !tracingSetExplicitly) {
3989
+ warn(
3990
+ "Risicare found no API key. Tracing is off and the SDK sends no span. Pass apiKey to init() or set RISICARE_API_KEY."
3991
+ );
3005
3992
  }
3006
3993
  let exporter;
3007
3994
  if (this.config.debug && !this.config.apiKey) {
@@ -3055,31 +4042,38 @@ var RisicareClient = class {
3055
4042
  serviceVersion: this.config.serviceVersion
3056
4043
  });
3057
4044
  this.processor.start();
3058
- if (this.config.apiKey && this.config.enabled) {
4045
+ if (this.config.apiKey && this.config.enabled && this.config.fixRuntime) {
3059
4046
  try {
3060
4047
  initFixRuntime({
3061
- apiEndpoint: this.config.endpoint,
4048
+ apiEndpoint: this.config.apiEndpoint,
3062
4049
  apiKey: this.config.apiKey,
3063
4050
  enabled: true,
3064
4051
  debug: this.config.debug
3065
4052
  });
3066
4053
  } catch (e) {
3067
4054
  const errName = e instanceof Error ? e.name : "Error";
3068
- const errMsg = e instanceof Error ? e.message : String(e);
4055
+ const errMsg = scrubText(e instanceof Error ? e.message : String(e), [this.config.apiKey]);
3069
4056
  try {
3070
4057
  console.warn(
3071
- `[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.`
4058
+ `[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.`
3072
4059
  );
3073
4060
  } catch {
3074
4061
  }
3075
4062
  if (this.config.debug) {
3076
- debug(`FixRuntime init traceback: ${e instanceof Error && e.stack ? e.stack : String(e)}`);
4063
+ debug(
4064
+ `FixRuntime init traceback: ${scrubText(e instanceof Error && e.stack ? e.stack : String(e), [this.config.apiKey], 2e3)}`
4065
+ );
3077
4066
  }
3078
4067
  }
3079
4068
  }
3080
4069
  this._registerShutdownHooks();
3081
4070
  setDebug(this.config.debug);
3082
- debug(`Initialized: enabled=${this.config.enabled}, endpoint=${this.config.endpoint}`);
4071
+ debug(`Initialized: enabled=${this.config.enabled}, endpoint=${safeUrl(this.config.endpoint)}`);
4072
+ if (!this.config.fixRuntime) {
4073
+ debug(
4074
+ "FixRuntime is off: nothing polls /fixes/active and no fix is applied. Opt in with fixRuntime: true or RISICARE_FIX_RUNTIME=true."
4075
+ );
4076
+ }
3083
4077
  }
3084
4078
  get enabled() {
3085
4079
  return this.tracer.enabled;
@@ -3088,18 +4082,20 @@ var RisicareClient = class {
3088
4082
  this.tracer.enabled = value;
3089
4083
  }
3090
4084
  // Audit #6: Promise-based shutdown dedup (fixes TOCTOU race condition)
3091
- async shutdown() {
4085
+ async shutdown(timeoutMs) {
3092
4086
  if (this._shutdownPromise) return this._shutdownPromise;
3093
- this._shutdownPromise = this._doShutdown();
4087
+ this._shutdownPromise = this._doShutdown(timeoutMs);
3094
4088
  return this._shutdownPromise;
3095
4089
  }
3096
- async _doShutdown() {
4090
+ async _doShutdown(timeoutMs) {
3097
4091
  debug("Shutting down...");
3098
4092
  for (const { signal, handler } of this._shutdownHandlers) {
3099
4093
  process.removeListener(signal, handler);
3100
4094
  }
3101
4095
  this._shutdownHandlers = [];
3102
- await this.processor.shutdown();
4096
+ endOpenProviderSpans();
4097
+ await this.processor.shutdown(timeoutMs);
4098
+ _failWaitingScores(SCORE_DEADLINE_REASON);
3103
4099
  this.isShutdown = true;
3104
4100
  _finalMetrics = this.processor.getMetrics();
3105
4101
  }
@@ -3114,8 +4110,8 @@ var RisicareClient = class {
3114
4110
  * false one — both leave the customer unable to tell *drained* from
3115
4111
  * *discarded*.
3116
4112
  */
3117
- async flush() {
3118
- return this.processor.flush();
4113
+ async flush(timeoutMs) {
4114
+ return this.processor.flush(timeoutMs);
3119
4115
  }
3120
4116
  /**
3121
4117
  * SDK-RELEASE-RULING.md §3 — who decides whether the process dies.
@@ -3213,25 +4209,39 @@ function init(config) {
3213
4209
  return;
3214
4210
  }
3215
4211
  _finalMetrics = void 0;
4212
+ _resetScoreFailures();
3216
4213
  const client = new RisicareClient(config);
3217
4214
  setClient(client);
3218
4215
  setTracer(client.tracer);
3219
4216
  }
3220
- async function shutdown() {
4217
+ async function shutdown(timeoutMs) {
3221
4218
  try {
3222
4219
  shutdownFixRuntime();
3223
4220
  } catch {
3224
4221
  }
3225
4222
  const client = getClient();
3226
4223
  if (!client) return;
3227
- await client.shutdown();
4224
+ await client.shutdown(timeoutMs);
3228
4225
  setClient(void 0);
3229
4226
  setTracer(void 0);
3230
4227
  }
3231
- async function flush() {
4228
+ async function flush(timeoutMs) {
4229
+ const budgetMs = normalizeTimeoutMs(timeoutMs);
4230
+ const deadline = Date.now() + budgetMs;
4231
+ const scoreMark = _failedScoresFlushMark;
3232
4232
  const client = getClient();
3233
- if (!client) return true;
3234
- return client.flush();
4233
+ let spansOk;
4234
+ if (!client) {
4235
+ spansOk = (_finalMetrics?.droppedSpansByReason.shutdown_residue ?? 0) === 0;
4236
+ } else {
4237
+ spansOk = await client.flush(timeoutMs);
4238
+ }
4239
+ const scoresDone = await _waitForPendingScores(deadline - Date.now());
4240
+ if (!scoresDone) _failWaitingScores(SCORE_DEADLINE_REASON);
4241
+ _warnHeldScores();
4242
+ const failedNow = _failedScores;
4243
+ if (failedNow > _failedScoresFlushMark) _failedScoresFlushMark = failedNow;
4244
+ return spansOk && scoresDone && failedNow <= scoreMark;
3235
4245
  }
3236
4246
  function enable() {
3237
4247
  const client = getClient();
@@ -3255,22 +4265,30 @@ function getTraceContent() {
3255
4265
  function getMetrics() {
3256
4266
  const client = getClient();
3257
4267
  if (client && !client.isShutdown) {
3258
- return { ...client.processor.getMetrics(), sdkState: "running" };
4268
+ return {
4269
+ ...client.processor.getMetrics(),
4270
+ failedScores: _failedScores,
4271
+ sdkState: "running"
4272
+ };
3259
4273
  }
3260
4274
  if (_finalMetrics) {
3261
4275
  return {
3262
4276
  ..._finalMetrics,
4277
+ failedScores: _failedScores,
3263
4278
  droppedSpansByReason: { ..._finalMetrics.droppedSpansByReason },
3264
4279
  sdkState: "shutdown"
3265
4280
  };
3266
4281
  }
3267
4282
  return {
3268
4283
  exportedSpans: 0,
4284
+ rejectedSpans: 0,
4285
+ failedScores: _failedScores,
3269
4286
  droppedSpans: 0,
3270
4287
  droppedSpansByReason: {
3271
4288
  queue_full: 0,
3272
4289
  transport_refused: 0,
3273
- shutdown_residue: 0
4290
+ shutdown_residue: 0,
4291
+ unacknowledged: 0
3274
4292
  },
3275
4293
  failedExports: 0,
3276
4294
  queueSize: 0,
@@ -3315,8 +4333,8 @@ function reportError(error, options) {
3315
4333
  span.setStatus("error" /* ERROR */, err.message);
3316
4334
  span.setAttribute("error", true);
3317
4335
  span.setAttribute("error.type", err.constructor.name);
3318
- span.setAttribute("error.message", err.message.slice(0, 2e3));
3319
- if (err.stack) span.setAttribute("error.stack", err.stack.slice(0, 4e3));
4336
+ span.setAttribute("error.message", cutCodePoints(err.message, 2e3));
4337
+ if (err.stack) span.setAttribute("error.stack", cutCodePoints(err.stack, 4e3));
3320
4338
  span.setAttribute("risicare.reported_error", true);
3321
4339
  attachErrorCode(span, err);
3322
4340
  if (options?.attributes) {
@@ -3331,18 +4349,28 @@ function reportError(error, options) {
3331
4349
  }
3332
4350
  function score(traceId, name, value, options) {
3333
4351
  try {
3334
- if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
3335
- debug(`score: value must be in [0.0, 1.0], got ${value}. Score not sent.`);
4352
+ const raw = value;
4353
+ if (typeof raw === "boolean") value = raw ? 1 : 0;
4354
+ if (typeof value !== "number") {
4355
+ warn(`score: the value must be a number, not ${typeof raw}. The SDK does not send this score.`);
3336
4356
  return;
3337
4357
  }
3338
- if (!traceId || !name) {
3339
- debug("score: traceId and name are required");
4358
+ if (!Number.isFinite(value) || value < 0 || value > 1) {
4359
+ warn(`score: the value must be in [0.0, 1.0], not ${value}. The SDK does not send this score.`);
4360
+ return;
4361
+ }
4362
+ if (typeof traceId !== "string" || given(traceId) === void 0) {
4363
+ warn("score: traceId must be a non-empty string. The SDK does not send this score.");
4364
+ return;
4365
+ }
4366
+ if (typeof name !== "string" || given(name) === void 0) {
4367
+ warn("score: name must be a non-empty string. The SDK does not send this score.");
3340
4368
  return;
3341
4369
  }
3342
4370
  const client = getClient();
3343
4371
  if (!client?.enabled || !client.config.apiKey) return;
3344
- const endpoint = client.config.endpoint.replace(/\/$/, "");
3345
- const url = `${endpoint}/api/v1/scores`;
4372
+ const endpoint = client.config.apiEndpoint.replace(/\/+$/, "");
4373
+ const url = `${endpoint}/v1/scores`;
3346
4374
  let comment = options?.comment;
3347
4375
  if (comment !== void 0 && client.config.mask) {
3348
4376
  comment = maskText(client.config.mask, SCORE_COMMENT_KEY, comment);
@@ -3355,21 +4383,71 @@ function score(traceId, name, value, options) {
3355
4383
  ...options?.spanId && { span_id: options.spanId },
3356
4384
  ...comment && { comment }
3357
4385
  });
3358
- fetch(url, {
3359
- method: "POST",
3360
- headers: {
3361
- "Content-Type": "application/json",
3362
- "Authorization": `Bearer ${client.config.apiKey}`,
3363
- // F-SDKVER-001 — see the Python twin. `score()` reaches the FastAPI
3364
- // server under /v1/, which `main.py::audit_logging_middleware` audits
3365
- // into `audit_logs.user_agent`; ingest reaches the Rust gateway, which
3366
- // discards it. This is the one client-identity visible with no gateway
3367
- // change.
3368
- "User-Agent": `risicare-js/${SDK_VERSION} node/${process.version}`,
3369
- "X-Risicare-SDK-Version": SDK_VERSION
3370
- },
3371
- body
3372
- }).catch((err) => debug(`score: send failed: ${err}`));
4386
+ if (_scoresInFlight >= SCORE_MAX_IN_FLIGHT && _scoreWaiters.length >= SCORE_MAX_WAITING) {
4387
+ _scoreFailed(name, SCORE_CAP_REASON);
4388
+ return;
4389
+ }
4390
+ let settle;
4391
+ const request = new Promise((resolve) => settle = resolve);
4392
+ const send = async () => {
4393
+ const controller = new AbortController();
4394
+ const timer = setTimeout(() => controller.abort(), SCORE_TIMEOUT_MS);
4395
+ try {
4396
+ const response = await fetch(url, {
4397
+ method: "POST",
4398
+ headers: {
4399
+ "Content-Type": "application/json",
4400
+ "Authorization": `Bearer ${client.config.apiKey}`,
4401
+ // F-SDKVER-001 — see the Python twin. `score()` reaches the FastAPI
4402
+ // server under /v1/, which `main.py::audit_logging_middleware` audits
4403
+ // into `audit_logs.user_agent`; ingest reaches the Rust gateway, which
4404
+ // discards it. This is the one client-identity visible with no gateway
4405
+ // change.
4406
+ "User-Agent": `risicare-js/${SDK_VERSION} node/${process.version}`,
4407
+ "X-Risicare-SDK-Version": SDK_VERSION
4408
+ },
4409
+ body,
4410
+ // Never follow: a redirect is a misroute, not a route. Through 0.7.1
4411
+ // fetch followed a 307 and re-POSTed the score to the login page.
4412
+ redirect: "manual",
4413
+ signal: controller.signal
4414
+ });
4415
+ if (response.type === "opaqueredirect" || response.status >= 300) {
4416
+ _scoreFailed(name, `HTTP ${response.status || "3xx"}`);
4417
+ }
4418
+ try {
4419
+ await response.body?.cancel();
4420
+ } catch {
4421
+ }
4422
+ } catch (err) {
4423
+ const cause = err instanceof Error ? err.cause : void 0;
4424
+ const code = typeof cause?.code === "string" ? cause.code : void 0;
4425
+ const reason = controller.signal.aborted ? `no answer within ${SCORE_TIMEOUT_MS} ms` : code ?? (err instanceof Error ? err.name : "Error");
4426
+ _scoreFailed(name, reason);
4427
+ } finally {
4428
+ clearTimeout(timer);
4429
+ _scoresInFlight--;
4430
+ settle();
4431
+ _startWaitingScores();
4432
+ }
4433
+ };
4434
+ const start = () => {
4435
+ _scoresInFlight++;
4436
+ void send();
4437
+ };
4438
+ if (_scoresInFlight < SCORE_MAX_IN_FLIGHT) {
4439
+ start();
4440
+ } else {
4441
+ _scoreWaiters.push({
4442
+ start,
4443
+ fail: (reason) => {
4444
+ _scoreFailed(name, reason);
4445
+ settle();
4446
+ }
4447
+ });
4448
+ }
4449
+ _pendingScores.add(request);
4450
+ void request.finally(() => _pendingScores.delete(request));
3373
4451
  } catch {
3374
4452
  debug("score failed");
3375
4453
  }
@@ -3398,9 +4476,9 @@ var LIFECYCLE_STATUS = "risicare.lifecycle.status";
3398
4476
  var STATUS_MESSAGE_MAX = 500;
3399
4477
  function excSummary(error) {
3400
4478
  if (error instanceof Error) {
3401
- return `${error.constructor.name}: ${error.message}`.slice(0, STATUS_MESSAGE_MAX);
4479
+ return cutCodePoints(`${error.constructor.name}: ${error.message}`, STATUS_MESSAGE_MAX);
3402
4480
  }
3403
- return String(error).slice(0, STATUS_MESSAGE_MAX);
4481
+ return cutCodePoints(String(error), STATUS_MESSAGE_MAX);
3404
4482
  }
3405
4483
  function stampEndMarker(span, entity, error) {
3406
4484
  try {
@@ -3487,9 +4565,10 @@ function withSessionEndMarker(body) {
3487
4565
 
3488
4566
  // src/decorators/agent.ts
3489
4567
  function _wrapAgent(options, fn) {
3490
- const spanName = `agent:${options.name ?? "agent"}`;
3491
- const agentId = options.agentId ?? generateAgentId(options.name ?? "agent");
3492
- const boundOptions = { ...options, agentId };
4568
+ const agentName = options.name ?? (fn.name.replace(/^(bound )+/, "") || "agent");
4569
+ const spanName = `agent:${agentName}`;
4570
+ const agentId = options.agentId ?? generateAgentId(agentName);
4571
+ const boundOptions = { ...options, name: agentName, agentId };
3493
4572
  return (...args) => {
3494
4573
  const tracer = getTracer2();
3495
4574
  if (!tracer) {
@@ -3542,6 +4621,10 @@ function withPhase(phase, fn) {
3542
4621
  }
3543
4622
 
3544
4623
  // src/decorators/phase.ts
4624
+ function bareName(phase, fn) {
4625
+ const fnName = typeof fn === "function" ? fn.name.replace(/^(bound )+/, "") : "";
4626
+ return fnName ? `${phase}:${fnName}` : `phase:${phase}`;
4627
+ }
3545
4628
  function phaseWrapper(phase, kind, name, fn) {
3546
4629
  return (...args) => {
3547
4630
  const tracer = getTracer2();
@@ -3557,22 +4640,22 @@ function phaseWrapper(phase, kind, name, fn) {
3557
4640
  };
3558
4641
  }
3559
4642
  function traceThink(fnOrName, maybeFn) {
3560
- const name = typeof fnOrName === "string" ? fnOrName : `phase:think`;
4643
+ const name = typeof fnOrName === "string" ? fnOrName : bareName("think", fnOrName);
3561
4644
  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
3562
4645
  return phaseWrapper("think" /* THINK */, "think" /* THINK */, name, fn);
3563
4646
  }
3564
4647
  function traceDecide(fnOrName, maybeFn) {
3565
- const name = typeof fnOrName === "string" ? fnOrName : `phase:decide`;
4648
+ const name = typeof fnOrName === "string" ? fnOrName : bareName("decide", fnOrName);
3566
4649
  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
3567
4650
  return phaseWrapper("decide" /* DECIDE */, "decide" /* DECIDE */, name, fn);
3568
4651
  }
3569
4652
  function traceAct(fnOrName, maybeFn) {
3570
- const name = typeof fnOrName === "string" ? fnOrName : `phase:act`;
4653
+ const name = typeof fnOrName === "string" ? fnOrName : bareName("act", fnOrName);
3571
4654
  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
3572
4655
  return phaseWrapper("act" /* ACT */, "tool_call" /* TOOL_CALL */, name, fn);
3573
4656
  }
3574
4657
  function traceObserve(fnOrName, maybeFn) {
3575
- const name = typeof fnOrName === "string" ? fnOrName : `phase:observe`;
4658
+ const name = typeof fnOrName === "string" ? fnOrName : bareName("observe", fnOrName);
3576
4659
  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
3577
4660
  return phaseWrapper("observe" /* OBSERVE */, "observe" /* OBSERVE */, name, fn);
3578
4661
  }
@@ -3661,7 +4744,7 @@ function getTraceContext() {
3661
4744
  traceId = ctx._rootTraceId;
3662
4745
  } else {
3663
4746
  traceId = generateTraceId();
3664
- if (ctx.session || ctx.agent) {
4747
+ if (hasContextScope()) {
3665
4748
  ctx._rootTraceId = traceId;
3666
4749
  }
3667
4750
  }
@@ -3698,7 +4781,8 @@ function extractTraceContext(headers) {
3698
4781
  const result = {};
3699
4782
  const normalizedHeaders = {};
3700
4783
  for (const [key, value] of Object.entries(headers)) {
3701
- normalizedHeaders[key.toLowerCase()] = value;
4784
+ const first = Array.isArray(value) ? value[0] : value;
4785
+ if (typeof first === "string") normalizedHeaders[key.toLowerCase()] = first;
3702
4786
  }
3703
4787
  const traceparent = normalizedHeaders[TRACEPARENT_HEADER] ?? "";
3704
4788
  if (traceparent) {