risicare 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/README.md +282 -63
  2. package/dist/frameworks/instructor.cjs +790 -5
  3. package/dist/frameworks/instructor.cjs.map +1 -1
  4. package/dist/frameworks/instructor.js +780 -5
  5. package/dist/frameworks/instructor.js.map +1 -1
  6. package/dist/frameworks/langchain.cjs +790 -5
  7. package/dist/frameworks/langchain.cjs.map +1 -1
  8. package/dist/frameworks/langchain.d.cts +3 -2
  9. package/dist/frameworks/langchain.d.ts +3 -2
  10. package/dist/frameworks/langchain.js +780 -5
  11. package/dist/frameworks/langchain.js.map +1 -1
  12. package/dist/frameworks/langgraph.cjs +790 -5
  13. package/dist/frameworks/langgraph.cjs.map +1 -1
  14. package/dist/frameworks/langgraph.js +780 -5
  15. package/dist/frameworks/langgraph.js.map +1 -1
  16. package/dist/frameworks/llamaindex.cjs +801 -5
  17. package/dist/frameworks/llamaindex.cjs.map +1 -1
  18. package/dist/frameworks/llamaindex.d.cts +3 -2
  19. package/dist/frameworks/llamaindex.d.ts +3 -2
  20. package/dist/frameworks/llamaindex.js +791 -5
  21. package/dist/frameworks/llamaindex.js.map +1 -1
  22. package/dist/index.cjs +1113 -176
  23. package/dist/index.cjs.map +1 -1
  24. package/dist/index.d.cts +234 -42
  25. package/dist/index.d.ts +234 -42
  26. package/dist/index.js +1113 -176
  27. package/dist/index.js.map +1 -1
  28. package/dist/providers/anthropic/index.cjs +1601 -36
  29. package/dist/providers/anthropic/index.cjs.map +1 -1
  30. package/dist/providers/anthropic/index.d.cts +3 -1
  31. package/dist/providers/anthropic/index.d.ts +3 -1
  32. package/dist/providers/anthropic/index.js +1591 -36
  33. package/dist/providers/anthropic/index.js.map +1 -1
  34. package/dist/providers/bedrock/index.cjs +850 -32
  35. package/dist/providers/bedrock/index.cjs.map +1 -1
  36. package/dist/providers/bedrock/index.js +840 -32
  37. package/dist/providers/bedrock/index.js.map +1 -1
  38. package/dist/providers/cerebras/index.cjs +1534 -30
  39. package/dist/providers/cerebras/index.cjs.map +1 -1
  40. package/dist/providers/cerebras/index.js +1524 -30
  41. package/dist/providers/cerebras/index.js.map +1 -1
  42. package/dist/providers/cohere/index.cjs +1557 -102
  43. package/dist/providers/cohere/index.cjs.map +1 -1
  44. package/dist/providers/cohere/index.js +1547 -102
  45. package/dist/providers/cohere/index.js.map +1 -1
  46. package/dist/providers/google/index.cjs +1562 -60
  47. package/dist/providers/google/index.cjs.map +1 -1
  48. package/dist/providers/google/index.js +1552 -60
  49. package/dist/providers/google/index.js.map +1 -1
  50. package/dist/providers/groq/index.cjs +1534 -30
  51. package/dist/providers/groq/index.cjs.map +1 -1
  52. package/dist/providers/groq/index.js +1524 -30
  53. package/dist/providers/groq/index.js.map +1 -1
  54. package/dist/providers/huggingface/index.cjs +1622 -25
  55. package/dist/providers/huggingface/index.cjs.map +1 -1
  56. package/dist/providers/huggingface/index.d.cts +0 -9
  57. package/dist/providers/huggingface/index.d.ts +0 -9
  58. package/dist/providers/huggingface/index.js +1612 -25
  59. package/dist/providers/huggingface/index.js.map +1 -1
  60. package/dist/providers/mistral/index.cjs +1535 -54
  61. package/dist/providers/mistral/index.cjs.map +1 -1
  62. package/dist/providers/mistral/index.js +1525 -54
  63. package/dist/providers/mistral/index.js.map +1 -1
  64. package/dist/providers/ollama/index.cjs +1559 -93
  65. package/dist/providers/ollama/index.cjs.map +1 -1
  66. package/dist/providers/ollama/index.js +1549 -93
  67. package/dist/providers/ollama/index.js.map +1 -1
  68. package/dist/providers/openai/index.cjs +1598 -61
  69. package/dist/providers/openai/index.cjs.map +1 -1
  70. package/dist/providers/openai/index.d.cts +6 -1
  71. package/dist/providers/openai/index.d.ts +6 -1
  72. package/dist/providers/openai/index.js +1588 -61
  73. package/dist/providers/openai/index.js.map +1 -1
  74. package/dist/providers/together/index.cjs +1534 -30
  75. package/dist/providers/together/index.cjs.map +1 -1
  76. package/dist/providers/together/index.js +1524 -30
  77. package/dist/providers/together/index.js.map +1 -1
  78. package/dist/providers/vercel-ai/index.cjs +1288 -17
  79. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  80. package/dist/providers/vercel-ai/index.d.cts +0 -6
  81. package/dist/providers/vercel-ai/index.d.ts +0 -6
  82. package/dist/providers/vercel-ai/index.js +1278 -17
  83. package/dist/providers/vercel-ai/index.js.map +1 -1
  84. package/package.json +1 -1
package/README.md CHANGED
@@ -7,7 +7,9 @@ AI agent observability and error diagnosis for Node.js and TypeScript.
7
7
  [![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue.svg)](https://www.npmjs.com/package/risicare)
8
8
  [![License: Proprietary](https://img.shields.io/badge/license-proprietary-red.svg)](LICENSE)
9
9
 
10
- Monitor your AI agents in production. Trace every LLM call, detect errors automatically, and get AI-generated fix suggestions — with 3 lines of setup.
10
+ Monitor your AI agents in production. Patch your LLM client, wrap your agent,
11
+ and the SDK sends a span for each traced call to Risicare. Risicare then
12
+ diagnoses the errors and suggests fixes.
11
13
 
12
14
  ## Quickstart
13
15
 
@@ -20,11 +22,8 @@ import { init, agent, shutdown } from 'risicare';
20
22
  import { patchOpenAI } from 'risicare/openai';
21
23
  import OpenAI from 'openai';
22
24
 
23
- // 1. Initialize
24
- init({
25
- apiKey: 'rsk-...',
26
- endpoint: 'https://ingest.risicare.ai',
27
- });
25
+ // 1. Initialize (for the hosted service, set no endpoint)
26
+ init({ apiKey: 'rsk-...' });
28
27
 
29
28
  // 2. Patch your LLM client
30
29
  const openai = patchOpenAI(new OpenAI());
@@ -38,18 +37,72 @@ const myAgent = agent({ name: 'research-agent' }, async (query: string) => {
38
37
  return response.choices[0].message.content;
39
38
  });
40
39
 
41
- // Run it — traces appear in your dashboard within seconds
40
+ // Run it
42
41
  const result = await myAgent('What is quantum computing?');
43
42
  await shutdown();
44
43
  ```
45
44
 
46
- **That's it.** Your agent's LLM calls, latency, token usage, and costs now appear in the [Risicare dashboard](https://app.risicare.ai).
45
+ The SDK sends one span for the agent function and one span for the LLM call,
46
+ in the same trace. The LLM span has the model, the latency, the token counts
47
+ and the cost. You see them in the [Risicare dashboard](https://app.risicare.ai).
48
+
49
+ ## Two hosts
50
+
51
+ The SDK sends data to two hosts:
52
+
53
+ - **Spans** go to `endpoint`. The default is `https://ingest.risicare.ai`.
54
+ - **Scores and fix reads** go to `apiEndpoint`. The default is `https://api.risicare.ai`.
55
+
56
+ For the hosted service, set neither. For your own deployment, set `endpoint`
57
+ (or `RISICARE_ENDPOINT`). Scores and fix reads go to the first of these that
58
+ is set:
59
+
60
+ 1. the `apiEndpoint` option;
61
+ 2. the `endpoint` option, unless it is the default ingest host;
62
+ 3. the `RISICARE_API_ENDPOINT` environment variable;
63
+ 4. the `RISICARE_ENDPOINT` environment variable, if you gave no `endpoint`
64
+ option and it is not the default ingest host;
65
+ 5. the default, `https://api.risicare.ai`.
66
+
67
+ The SDK ignores the default ingest host (`https://ingest.risicare.ai`) when it
68
+ selects the api host, and goes to the next step. So your key does not go to a
69
+ host that you did not name. Only that exact value is ignored (letter case, a
70
+ `:443` port and slashes at the end do not matter). A different form, for
71
+ example `http://ingest.risicare.ai` or `https://ingest.risicare.ai/v1`, is a
72
+ host that you named, and the SDK uses it. A value that is empty, or that has
73
+ ASCII whitespace only, is "not set". `RISICARE_ENDPOINT=https://my-host` alone sends spans, scores and fix
74
+ reads to `https://my-host`.
75
+
76
+ ## Configuration
77
+
78
+ `RISICARE_TRACING` is trimmed and compared without case:
79
+
80
+ | Value | Result |
81
+ |-------|--------|
82
+ | `true`, `1`, `yes`, `on` | tracing on |
83
+ | `false`, `0`, `no`, `off` | tracing off |
84
+ | unset, empty, or whitespace only | the default applies |
85
+ | any other value | tracing off, with one WARNING that names the value |
86
+
87
+ The `enabled` option has priority over the variable. With no API key and no
88
+ explicit setting, tracing is off (see "A note on running without an API key").
89
+
90
+ ## Imports
91
+
92
+ The package has no default export. Use named imports or a namespace import.
93
+ `Span` and `Tracer` are types only: import them with `import type`.
94
+
95
+ ```typescript
96
+ import { init, agent } from 'risicare';
97
+ import * as risicare from 'risicare';
98
+ import type { Span, Tracer } from 'risicare';
99
+ ```
47
100
 
48
101
  ## Prompt content is NOT captured by default
49
102
 
50
- **Since 0.5.1, `traceContent` defaults to `false`.** Your prompts and completions
103
+ **`traceContent` defaults to `false`** (since 0.5.2, the first published version with this default). Your prompts and completions
51
104
  stay in your process. Everything else — model, token counts, latency, cost,
52
- message roles, errors, and any attributes you set — is captured as normal, so the
105
+ errors, and any attributes you set — is captured as normal, so the
53
106
  dashboard, cost tracking and error diagnosis all work unchanged.
54
107
 
55
108
  To send prompt and completion text as well, opt in:
@@ -59,6 +112,25 @@ init({ apiKey: 'rsk-...', traceContent: true });
59
112
  // or set RISICARE_TRACE_CONTENT=true
60
113
  ```
61
114
 
115
+ **Which providers capture text.** With `traceContent: true`:
116
+
117
+ - `patchOpenAI` and `patchAnthropic` capture the prompt and the completion text.
118
+ They write the first 10 messages to `gen_ai.prompt.N.role` and
119
+ `gen_ai.prompt.N.content`. They write the completion to
120
+ `gen_ai.completion.content`. `patchAnthropic` also writes a string `system`
121
+ prompt to `gen_ai.system_prompt`. The SDK cuts each text at 10,000 characters
122
+ (Unicode code points). It cuts the system prompt at 5,000. `patchOpenAI` also
123
+ captures text for a client of an OpenAI-compatible host.
124
+ - For a streamed call, they capture the prompt only, not the completion.
125
+ - `patchGoogleAI`, `patchMistral`, `patchGroq`, `patchCohere`, `patchTogether`,
126
+ `patchOllama`, `patchHuggingFace`, `patchCerebras`, `patchBedrock` and
127
+ `patchVercelAI` capture no prompt or completion text.
128
+
129
+ **Error text is not covered by this switch.** The error message from a
130
+ provider can contain your prompt text. For example, a 400 error can repeat
131
+ part of the prompt. The SDK sends error messages also when `traceContent` is
132
+ off, because error diagnosis uses them.
133
+
62
134
  **Upgrading from 0.5.0 or earlier?** This is a behaviour change: content that
63
135
  used to be sent is no longer sent unless you opt in. In those versions the flag
64
136
  also did not work for content you set by hand — `traceContent: false` did not
@@ -73,9 +145,9 @@ Since 0.7.0, the gate also covers the OpenTelemetry GenAI, OpenInference and
73
145
  CrewAI content keys, for example `input.value`, `output.value`,
74
146
  `gen_ai.input.messages` and `gen_ai.output.messages`.
75
147
 
76
- If you want content captured but redacted first, use the `mask` hook — it is
77
- independent of this switch and runs on every content-bearing field before
78
- export:
148
+ If you want content captured but redacted first, use the `mask` hook. It runs
149
+ on every content-bearing field of every span before export, for every
150
+ exporter:
79
151
 
80
152
  ```typescript
81
153
  init({ apiKey: 'rsk-...', traceContent: true, mask: (key, value) => value });
@@ -87,31 +159,91 @@ init({ apiKey: 'rsk-...', traceContent: true, mask: (key, value) => value });
87
159
  - **12 LLM providers** — OpenAI, Anthropic, Google, Mistral, Groq, Cohere, Together, Ollama, HuggingFace, Cerebras, Bedrock, Vercel AI
88
160
  - **4 framework integrations** — LangChain, LangGraph, Instructor, LlamaIndex
89
161
  - **Error Diagnosis (beta)** — LLM-powered root cause analysis with fix suggestions; auto-apply not yet wired (see "Error Diagnosis" section below)
90
- - **Evaluation scores** — Rate agent quality with `score()` and 13 built-in scorers
91
- - **Streaming support** — `tracedStream()` for async iterator tracing
92
- - **Context propagation** — Automatic across `async/await`, `Promise`, `setTimeout`, `EventEmitter`
162
+ - **Evaluation scores** — Rate agent quality with `score()`
163
+ - **Streaming** — `tracedStream()` traces an async iterator (see "Streaming" below)
164
+ - **Context propagation** — Automatic across `async/await`, `Promise` and `setTimeout`. An `EventEmitter` listener runs in the context of the `emit()` call
93
165
  - **Zero runtime dependencies** — No bloat in your node_modules
94
166
  - **Dual CJS/ESM** — Works with `require()` and `import`
95
167
  - **Full TypeScript** — Strict types and IntelliSense out of the box
96
- - **Non-blocking** — Async batch export with circuit breaker and retry
97
- - **Zero overhead when disabled** — Frozen NOOP_SPAN singleton, no allocations
168
+ - **Background export** — Async batch export with circuit breaker and retry
169
+ - **Low cost when disabled** — a frozen no-op span
98
170
 
99
171
  ## LLM Providers
100
172
 
101
173
  ```typescript
174
+ import OpenAI from 'openai';
102
175
  import { patchOpenAI } from 'risicare/openai';
103
176
  import { patchAnthropic } from 'risicare/anthropic';
104
- import { patchGoogle } from 'risicare/google';
177
+ import { patchGoogleAI } from 'risicare/google';
105
178
  // ... and 9 more
106
179
 
107
180
  const openai = patchOpenAI(new OpenAI());
108
- // Every call is now traced — model, tokens, latency, cost
181
+ // chat.completions.create and embeddings.create are now traced
109
182
  ```
110
183
 
111
184
  All 12 providers:
112
185
 
113
186
  `openai` · `anthropic` · `google` · `mistral` · `groq` · `cohere` · `together` · `ollama` · `huggingface` · `cerebras` · `bedrock` · `vercel-ai`
114
187
 
188
+ `patchOpenAI` also traces an OpenAI-compatible host (`baseURL`). It sets the
189
+ provider name (`gen_ai.system`) from the host for DeepSeek, Together, Groq, xAI,
190
+ Fireworks, Baseten, Novita and BytePlus (`api.byteplus.com` and
191
+ `ark.cn-beijing.byteplus.com`). Any other host is named `openai`.
192
+
193
+ ### Streaming
194
+
195
+ The caller gets the provider's own promise and stream objects. The SDK counts
196
+ only the chunks that the caller reads. It does not read ahead. The span of a
197
+ stream ends once, when the stream ends, with `stream.end_reason`:
198
+
199
+ | `stream.end_reason` | When | Status |
200
+ |---|---|---|
201
+ | `done` | The caller read the stream to its end. | ok |
202
+ | `return` | The caller stopped early (`break`, `return()`). | ok |
203
+ | `abort` | An abort stopped the stream: `controller.abort()` or the request `signal` (OpenAI, Anthropic, Groq, Together, Cerebras), the request `abortSignal` (Cohere), Ollama `abort()`, `cancel()`, or an `AbortError` that reached the caller. See the Google and Mistral limits. The span also gets `risicare.cancelled` = `true` and `risicare.cancel_type` = `AbortError`. | error |
204
+ | `error` | An error reached the caller. The span records it. | error |
205
+ | `handoff` | The caller took the data another way: `tee()`, `getReader()`, `toReadableStream()`, `pipeTo()`, `pipeThrough()` or `asResponse()`. | ok |
206
+ | `garbage` | Nothing holds the promise, the stream or an iterator, and no `next()` waits. The JavaScript engine decides when this is seen; it can be never. | ok |
207
+ | `shutdown` | `shutdown()` ends every stream span that is still open, and exports it. | ok |
208
+
209
+ The span has `stream.chunk_count`: the number of chunks that the caller read.
210
+ It has the token counts that the chunks gave: the usage chunk (OpenAI needs
211
+ `stream_options: { include_usage: true }`; also Groq, Together, Cerebras,
212
+ Hugging Face), `message_start` and `message_delta` (Anthropic), the last
213
+ `usageMetadata` (Google), the chunk `usage` (Mistral), the last chunk with
214
+ `done` (Ollama), `message-end` (Cohere). A count that the stream did not give
215
+ stays empty. The span does not capture the streamed completion text.
216
+
217
+ Call `shutdown()` before the process stops. A span that is still open is lost
218
+ if the process stops without it.
219
+
220
+ Limits:
221
+
222
+ - Cohere: `stream.controller.abort()` does not stop a Cohere stream, so it is
223
+ not an abort. The request option `abortSignal` stops it, and is an abort.
224
+ - Google, the request `signal`: the Google SDK changes the abort into a
225
+ `GoogleGenerativeAIError`. A read after the abort ends the span as `error`,
226
+ not `abort`. An abort with no read after it ends as `garbage` or
227
+ `shutdown`, status ok.
228
+ - Mistral, the request `signal` (`fetchOptions.signal`): a read after the
229
+ abort gets an `AbortError`, and the span ends as `abort`. The SDK cannot see
230
+ this signal, so an abort with no read after it ends as `garbage` or
231
+ `shutdown`, status ok.
232
+ - Google `result.response`: the Google SDK gives the aggregated response also
233
+ when nobody reads `result.stream`. If the caller never takes `result.stream`,
234
+ the span ends as `done` when `result.response` settles, with the tokens of
235
+ the aggregated response and `stream.chunk_count` = 0 (`error` if it
236
+ rejects). If the caller takes `result.stream`, the stream decides the end.
237
+ A stream that the caller takes after the span ended is not counted.
238
+ - `handoff`: the SDK does not see the chunks after the handoff, so the chunk
239
+ and token counts cover only the chunks read before it.
240
+ - Bedrock (`ConverseStreamCommand`): the SDK does not read the stream. The
241
+ span ends when `send()` returns. It has no token counts.
242
+ - Vercel AI (`tracedStreamText`): the span ends through the `streamText`
243
+ callbacks: `onFinish` (`done`, with the usage), `onAbort` (`abort`) or an
244
+ error chunk (`error`). With no callback, it ends as `garbage` or at
245
+ `shutdown()`.
246
+
115
247
  ## Framework Integrations
116
248
 
117
249
  ```typescript
@@ -130,13 +262,24 @@ const client = patchInstructor(instructor);
130
262
 
131
263
  // LlamaIndex
132
264
  import { RisicareLlamaIndexHandler } from 'risicare/llamaindex';
265
+ const liHandler = new RisicareLlamaIndexHandler();
266
+ for (const name of RisicareLlamaIndexHandler.EVENT_NAMES) {
267
+ Settings.callbackManager.on(name, (e) => liHandler.onEvent(e)); // Settings from 'llamaindex'
268
+ }
133
269
  ```
134
270
 
271
+ The LangChain and LlamaIndex handlers give one LLM span for each model call.
272
+ Use one handler: two handler instances on one call (for example one in the model
273
+ constructor and one in `invoke`) give two LLM spans. LangChain's `ChatOpenAI` and LlamaIndex's `OpenAI` make their own OpenAI client.
274
+ `patchOpenAI` changes only the client that you give to it, so it does not add a
275
+ second span to these calls. You need `withSuppression()` only when the same call
276
+ also goes through a client that you patched.
277
+
135
278
  ## Core API
136
279
 
137
280
  ```typescript
138
281
  import {
139
- init, shutdown, // Lifecycle
282
+ init, flush, shutdown, // Lifecycle
140
283
  agent, session, // Identity & grouping
141
284
  traceThink, traceDecide, traceAct, // Decision phases
142
285
  reportError, score, // Diagnosis & evaluation
@@ -144,48 +287,100 @@ import {
144
287
  } from 'risicare';
145
288
 
146
289
  init({ apiKey, endpoint }) // Initialize SDK
147
- agent({ name }, fn) // Wrap function with agent identity
148
- session({ sessionId, userId }, fn) // Group traces into user sessions
149
- // These are WRAPPER FACTORIES: they return a function you then call.
150
- await traceThink('analyze', async () => {...})() // note the trailing ()
151
- await traceDecide('choose', async () => {...})()
152
- await traceAct('execute', async () => {...})()
290
+ // agent(), session() and the trace* functions are WRAPPER FACTORIES:
291
+ // they return a function that you then call. Note the trailing ().
292
+ await agent({ name }, fn)() // Run fn with agent identity
293
+ await session({ sessionId, userId }, fn)() // Run fn in a user session
294
+ await traceThink('analyze', fn)()
295
+ await traceDecide('choose', fn)()
296
+ await traceAct('execute', fn)()
153
297
  reportError(error) // Report caught errors for diagnosis
154
298
  score(traceId, 'quality', 0.92) // Record evaluation score [0.0-1.0]
155
299
  tracedStream(asyncIterable, 'stream') // Trace async iterators
156
- await shutdown() // Flush pending spans and close
300
+ await flush(5000) // Wait for delivery; false when a span or a score was lost
301
+ await shutdown(5000) // Deliver what it can in the time, then stop
157
302
  ```
158
303
 
304
+ ## Delivery: flush, shutdown and metrics
305
+
306
+ - `await flush(timeoutMs?)` waits for the queued spans and the pending scores
307
+ (default 5000 ms). It returns `true` only when nothing is queued, no batch is
308
+ in flight, and no span was dropped or rejected and no score failed since the
309
+ previous `flush()` returned (or since `init()`, for the first call). A loss
310
+ makes the next `flush()` return `false` one time, also when it occurred while
311
+ no flush ran. It returns `false` at its deadline. `flush()` only waits. It
312
+ does not stop a request that is already sent. With more than one exporter,
313
+ a batch counts as delivered when the first exporter that succeeds takes it:
314
+ `flush()` can then return `true` while another exporter refused the batch.
315
+ - `await shutdown(timeoutMs?)` is the call that ends a process in a fixed time
316
+ (default 5000 ms). At the deadline it stops the export in flight. It counts
317
+ the spans that it did not deliver as `shutdown_residue`, with one WARNING.
318
+ - A timeout that is not a finite number means 5000 ms.
319
+ - `getMetrics()` gives `exportedSpans` (spans that the backend accepted),
320
+ `rejectedSpans`, `droppedSpans`, `droppedSpansByReason` (`queue_full`,
321
+ `transport_refused`, `shutdown_residue`, `unacknowledged`), `failedExports`,
322
+ `failedScores`, the queue numbers and `sdkState`. `unacknowledged` counts
323
+ spans that were sent, or that could not be serialized, and that the
324
+ backend's answer did not account for.
325
+ - `score()` stops its request after 2000 ms and does not follow a redirect. A
326
+ status of 300 or more, an error or a timeout adds 1 to `failedScores`. The
327
+ first failure writes one WARNING at once. Failures in the next 10 seconds
328
+ are counted, and the next WARNING gives their number.
329
+ At most 50 score requests run at one time. Up to 1,000 scores wait for a free
330
+ slot, with no timer: the 2000 ms bound starts when the request starts. A score
331
+ that comes when 1,000 already wait fails at once and is counted. When the bound
332
+ of `flush()` or `shutdown()` ends, the scores that still wait fail and are not
333
+ sent.
334
+
159
335
  ## Error Diagnosis
160
336
 
161
- > **Beta status (2026-05):** detect → diagnose → suggest is shipped and runs against
162
- > Together.AI Llama-3.3-70B with a circuit-breaker / template-only fallback. Suggested
163
- > fixes land in your dashboard as `status=draft` for human review. Automatic
164
- > deployment, A/B rollout, and learning-from-outcomes (stages 4–6 in our docs) are
165
- > in development and not yet wired in production. Treat this as **AI-assisted
166
- > error diagnosis** today; auto-apply will follow.
337
+ > **Beta.** The Risicare service detects an error, diagnoses it and suggests a
338
+ > fix. The diagnosis runs on the service, with Together.AI Llama-3.3-70B.
339
+ > Suggested fixes land in your dashboard as `status=draft` for human review.
340
+ > Automatic deployment, A/B rollout and learning from outcomes are not
341
+ > available. Treat this as **AI-assisted error diagnosis**.
167
342
 
168
- When your agent fails, Risicare:
343
+ When your agent fails:
169
344
 
170
- 1. **Classifies** the error (154 codes across TOOL, MEMORY, REASONING, OUTPUT, etc.)
171
- 2. **Diagnoses** the root cause using AI analysis
172
- 3. **Generates** a fix suggestion you can review in the dashboard and apply manually
345
+ 1. The SDK records the error on the span and gives it an error code
346
+ (`error.code`). The taxonomy has 154 codes in 10 modules (TOOL, MEMORY,
347
+ REASONING, OUTPUT and others). The SDK's own rules give 18 of them. An
348
+ error that no rule matches gets a 19th, `TOOL.EXECUTION.CRASHED`.
349
+ 2. The Risicare service diagnoses the root cause.
350
+ 3. The service writes a fix suggestion that you can review in the dashboard
351
+ and apply manually.
173
352
 
174
353
  ```typescript
175
354
  try {
176
355
  await myAgent(input);
177
356
  } catch (error) {
178
- reportError(error); // Triggers diagnosis pipeline; fix lands as draft for review
357
+ reportError(error); // Records the error for diagnosis; the fix lands as a draft for review
179
358
  }
180
359
  ```
181
360
 
182
361
  ## Fix application is off by default
183
362
 
184
- **Since 0.7.0, FixRuntime starts only when you opt in.** FixRuntime reads the
185
- active fixes for your project from Risicare and applies them to your LLM calls.
186
- A fix can change a prompt, a parameter, a tool, the retry or fallback behaviour,
187
- a guard, or the model routing. Through 0.6.0, FixRuntime started automatically
188
- when you set an API key.
363
+ **Since 0.7.0, FixRuntime starts only when you opt in.** During the beta, the
364
+ Risicare service does not give fixes to customer projects, so FixRuntime has no
365
+ effect for them. Through 0.6.0, FixRuntime started automatically when you set an
366
+ API key.
367
+
368
+ When FixRuntime is on, it reads the active fixes for your project from Risicare.
369
+ The fix interceptor enforces guard fixes on these paths only: `interceptCall` and
370
+ `interceptResponse` on the runtime, and the input guards of the patched OpenAI
371
+ chat call. The guards do not run when a framework integration suppresses provider
372
+ instrumentation. A failed input guard throws `GuardRejectedError` before the LLM
373
+ call. The input guards check messages that have text content: a string, or the
374
+ `text` parts of a list. A guard pattern that is not usable (not a string, empty,
375
+ longer than 500 characters, or JavaScript cannot use it) rejects the call. The
376
+ provider path does not apply prompt, parameter or fallback fixes.
377
+
378
+ Each SDK uses its own regular-expression engine. These constructs can give a
379
+ different result in JavaScript and Python: `$` before a final newline, Unicode
380
+ case folding, `\d` and `\w` on non-ASCII text, and a `]` first in a class.
381
+ JavaScript rejects a pattern that contains `\N{...}` or `\U........`. A pattern
382
+ has no time bound: a pattern with nested repeats can take a very long time on a
383
+ long input.
189
384
 
190
385
  When FixRuntime is off, the SDK does not request `/fixes/active`, and it does
191
386
  not change your LLM calls. Tracing, error reporting and scores are not affected.
@@ -226,39 +421,63 @@ const myAgent = agent({ name: 'planner', role: 'coordinator' }, async (input) =>
226
421
 
227
422
  ## Sessions
228
423
 
229
- Group traces from the same user conversation:
424
+ Group traces from the same user conversation. `withSession` runs the callback
425
+ now and returns its result:
230
426
 
231
427
  ```typescript
232
- const result = await session(
428
+ import { withSession } from 'risicare';
429
+
430
+ const result = await withSession(
233
431
  { sessionId: 'sess-abc123', userId: 'user-456' },
234
432
  () => myAgent(userMessage)
235
433
  );
236
434
  ```
237
435
 
436
+ `session()` does not run the callback. It returns a wrapped function, which you
437
+ call later, for example once for each request.
438
+
238
439
  ## Known limitation — span loss during a backend outage
239
440
 
240
- The SDK does **not** currently survive a sustained outage of the Risicare
241
- backend, and the loss is silent to your application (it is warned about, but
242
- nothing throws and `flush()` will not fail your request path).
441
+ The SDK does **not** keep spans through a long outage of the Risicare backend.
442
+ Nothing throws in your application. The SDK writes a WARNING, `flush()`
443
+ returns `false`, and `getMetrics()` counts the lost spans in
444
+ `droppedSpansByReason.transport_refused`.
243
445
 
244
446
  The HTTP exporter opens a circuit breaker after **5 consecutive failed export
245
- calls** and holds it open for **60 seconds**, returning failure immediately
246
- without touching the network. Queued spans get 3 re-queue attempts, which against
247
- an open breaker resolve in microseconds — so they are dropped — and for the
248
- remainder of the cooldown the SDK will not retry even after your backend is
249
- healthy again.
250
-
251
- Measured, for a 1,000-span cohort emitted during the outage: **4 s → all
252
- delivered; 5 s → half; 6 s and beyond → none.** The thresholds are counted in
253
- **failed calls, not seconds** — where the 5th consecutive failure falls in
254
- wall-clock time depends on your span rate and on how fast your endpoint fails.
255
-
256
- Nothing is lost on a clean `shutdown()`, and short blips that stay under the
257
- 5-failure threshold are fully survivable. Tracked as `F-SDKBLIP-001`.
447
+ calls** and holds it open for **60 seconds**. While it is open, an export
448
+ returns failure at once and does not use the network. A batch that fails is
449
+ put back in the queue at most 3 times. Against an open breaker these 3
450
+ attempts fail at once, so the spans are dropped. For the rest of the cooldown
451
+ the SDK does not send, also when your backend is healthy again.
452
+
453
+ The thresholds count **failed calls, not seconds**. When the 5th consecutive
454
+ failure occurs depends on your span rate and on how fast your endpoint fails.
455
+ A short failure that stays under 5 consecutive failed calls does not open the
456
+ breaker. Tracked as `F-SDKBLIP-001`.
457
+
458
+ One export call sends a batch at most 3 times. A 401 or 403 answer is sent
459
+ once in each export call: the endpoint refused the API key, and the same key
460
+ gets the same answer. At the first failed export of an outage (at most once in
461
+ 5 minutes), the SDK writes the WARNING "spans are NOT reaching ...". It gives
462
+ the HTTP status of the last answer, or the error code when there was no answer.
463
+ For a 401 or 403 it tells you to check the API key. When the kind of failure
464
+ changes in one outage (for example a 401, then no answer), the SDK writes one more
465
+ WARNING. An endpoint URL with credentials (a user name or a password before the
466
+ host) is not supported: `fetch` does not send a request to it.
467
+
468
+ The SDK removes its API key from each text that it logs: in any case of letters,
469
+ and also when the key is percent-encoded. An endpoint is logged without its user
470
+ name, password and query. A secret that you put in another place of a URL (for
471
+ example in its path) is logged as you gave it.
258
472
 
259
473
  ## A note on running without an API key
260
474
 
261
- If tracing is enabled but no API key is configured, the SDK emits a one-time
475
+ If you give no API key, or an empty one, tracing is off. This applies when
476
+ you do not set tracing explicitly. The SDK then writes one WARNING to stderr.
477
+ The SDK sends no span.
478
+
479
+ If tracing is enabled explicitly (`enabled: true` or `RISICARE_TRACING=true`)
480
+ but no API key is configured, the SDK emits a one-time
262
481
  `console.warn` and **drops** the spans. It deliberately does **not** print span
263
482
  payloads to your console: the SDK performs no redaction of its own, so printing
264
483
  would put prompts, completions and anything else in your attributes onto your