risicare 0.4.0 → 0.5.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 (80) hide show
  1. package/README.md +30 -0
  2. package/dist/frameworks/instructor.cjs +93 -73
  3. package/dist/frameworks/instructor.cjs.map +1 -1
  4. package/dist/frameworks/instructor.d.cts +19 -7
  5. package/dist/frameworks/instructor.d.ts +19 -7
  6. package/dist/frameworks/instructor.js +85 -67
  7. package/dist/frameworks/instructor.js.map +1 -1
  8. package/dist/frameworks/langchain.cjs +192 -94
  9. package/dist/frameworks/langchain.cjs.map +1 -1
  10. package/dist/frameworks/langchain.d.cts +97 -3
  11. package/dist/frameworks/langchain.d.ts +97 -3
  12. package/dist/frameworks/langchain.js +190 -88
  13. package/dist/frameworks/langchain.js.map +1 -1
  14. package/dist/frameworks/langgraph.cjs +192 -94
  15. package/dist/frameworks/langgraph.cjs.map +1 -1
  16. package/dist/frameworks/langgraph.js +190 -88
  17. package/dist/frameworks/langgraph.js.map +1 -1
  18. package/dist/frameworks/llamaindex.cjs +94 -69
  19. package/dist/frameworks/llamaindex.cjs.map +1 -1
  20. package/dist/frameworks/llamaindex.d.cts +33 -17
  21. package/dist/frameworks/llamaindex.d.ts +33 -17
  22. package/dist/frameworks/llamaindex.js +85 -62
  23. package/dist/frameworks/llamaindex.js.map +1 -1
  24. package/dist/index.cjs +2684 -1934
  25. package/dist/index.cjs.map +1 -1
  26. package/dist/index.d.cts +234 -46
  27. package/dist/index.d.ts +234 -46
  28. package/dist/index.js +2492 -1762
  29. package/dist/index.js.map +1 -1
  30. package/dist/providers/anthropic/index.cjs +33 -34
  31. package/dist/providers/anthropic/index.cjs.map +1 -1
  32. package/dist/providers/anthropic/index.js +25 -28
  33. package/dist/providers/anthropic/index.js.map +1 -1
  34. package/dist/providers/bedrock/index.cjs +56 -44
  35. package/dist/providers/bedrock/index.cjs.map +1 -1
  36. package/dist/providers/bedrock/index.d.cts +13 -1
  37. package/dist/providers/bedrock/index.d.ts +13 -1
  38. package/dist/providers/bedrock/index.js +47 -38
  39. package/dist/providers/bedrock/index.js.map +1 -1
  40. package/dist/providers/cerebras/index.cjs +33 -34
  41. package/dist/providers/cerebras/index.cjs.map +1 -1
  42. package/dist/providers/cerebras/index.js +25 -28
  43. package/dist/providers/cerebras/index.js.map +1 -1
  44. package/dist/providers/cohere/index.cjs +35 -36
  45. package/dist/providers/cohere/index.cjs.map +1 -1
  46. package/dist/providers/cohere/index.js +27 -30
  47. package/dist/providers/cohere/index.js.map +1 -1
  48. package/dist/providers/google/index.cjs +33 -34
  49. package/dist/providers/google/index.cjs.map +1 -1
  50. package/dist/providers/google/index.js +25 -28
  51. package/dist/providers/google/index.js.map +1 -1
  52. package/dist/providers/groq/index.cjs +33 -34
  53. package/dist/providers/groq/index.cjs.map +1 -1
  54. package/dist/providers/groq/index.js +25 -28
  55. package/dist/providers/groq/index.js.map +1 -1
  56. package/dist/providers/huggingface/index.cjs +33 -34
  57. package/dist/providers/huggingface/index.cjs.map +1 -1
  58. package/dist/providers/huggingface/index.js +25 -28
  59. package/dist/providers/huggingface/index.js.map +1 -1
  60. package/dist/providers/mistral/index.cjs +37 -38
  61. package/dist/providers/mistral/index.cjs.map +1 -1
  62. package/dist/providers/mistral/index.js +29 -32
  63. package/dist/providers/mistral/index.js.map +1 -1
  64. package/dist/providers/ollama/index.cjs +41 -34
  65. package/dist/providers/ollama/index.cjs.map +1 -1
  66. package/dist/providers/ollama/index.js +33 -28
  67. package/dist/providers/ollama/index.js.map +1 -1
  68. package/dist/providers/openai/index.cjs +36 -35
  69. package/dist/providers/openai/index.cjs.map +1 -1
  70. package/dist/providers/openai/index.js +28 -29
  71. package/dist/providers/openai/index.js.map +1 -1
  72. package/dist/providers/together/index.cjs +33 -34
  73. package/dist/providers/together/index.cjs.map +1 -1
  74. package/dist/providers/together/index.js +25 -28
  75. package/dist/providers/together/index.js.map +1 -1
  76. package/dist/providers/vercel-ai/index.cjs +27 -35
  77. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  78. package/dist/providers/vercel-ai/index.js +19 -29
  79. package/dist/providers/vercel-ai/index.js.map +1 -1
  80. package/package.json +94 -33
@@ -2,8 +2,21 @@
2
2
  * LangChain.js integration via callback handler.
3
3
  *
4
4
  * LangChain.js uses BaseCallbackHandler from @langchain/core/callbacks/base.
5
- * This handler receives lifecycle events (handleChainStart, handleLLMEnd, etc.)
6
- * with a runId (UUID string) for parent-child correlation.
5
+ * F-628/F-729: prior versions of this handler did NOT extend BaseCallbackHandler
6
+ * — LangChain v0.2+ tightened its callback registration to do `instanceof
7
+ * BaseCallbackHandler` checks, silently dropping any handler that does not
8
+ * inherit. Zero spans fired from any LCEL chain.
9
+ *
10
+ * PR-4+5 review B1 (2026-05-25): even with `extends BaseCallbackHandler`,
11
+ * `instanceof` would fail for ESM consumers because we resolve via
12
+ * `createRequire()` (CJS) — the two module instances are DIFFERENT class
13
+ * identities. LangChain v0.3 ships `isBaseCallbackHandler(x)` which checks
14
+ * duck-type markers (`x.copy` function, `x.name` string, `x.awaitHandlers`
15
+ * boolean). We now set those markers explicitly so we pass the duck-typed
16
+ * check regardless of which class identity ends up resolving in the customer
17
+ * environment. We ALSO still extend the resolved BaseCallbackHandler when
18
+ * available — that satisfies any remaining v0.2 `instanceof` callsite in
19
+ * the customer's bundle AND inherits the real `copy()` method.
7
20
  *
8
21
  * Usage:
9
22
  * import { RisicareCallbackHandler } from 'risicare/langchain';
@@ -15,9 +28,41 @@
15
28
  * SUPPRESSES provider instrumentation — LangChain handler creates LLM spans,
16
29
  * so provider-level spans (patchOpenAI, etc.) would duplicate without suppression.
17
30
  */
18
- declare class RisicareCallbackHandler {
31
+ declare const _BaseCallbackHandler: new (...args: unknown[]) => object;
32
+ /**
33
+ * RisicareCallbackHandler — emits Risicare spans for every LangChain callback.
34
+ *
35
+ * Extends BaseCallbackHandler at runtime when @langchain/core is installed,
36
+ * which is required for LangChain v0.2+ to accept it.
37
+ *
38
+ * F-882/F-883: chat-model and agent events are NEW in v0.2; older handlers
39
+ * that only implement handleLLMStart get zero spans from `ChatModel`s (every
40
+ * modern LangChain LLM is a ChatModel). The full chat / agent / custom-event
41
+ * surface is now covered.
42
+ */
43
+ declare class RisicareCallbackHandler extends _BaseCallbackHandler {
19
44
  name: string;
45
+ awaitHandlers: boolean;
46
+ ignoreLLM: boolean;
47
+ ignoreChain: boolean;
48
+ ignoreAgent: boolean;
49
+ ignoreRetriever: boolean;
50
+ ignoreCustomEvent: boolean;
51
+ raiseError: boolean;
52
+ lc_serializable: boolean;
53
+ lc_kwargs: Record<string, unknown>;
20
54
  private _spans;
55
+ constructor();
56
+ /**
57
+ * Required by LangChain's `isBaseCallbackHandler(x)` duck-type check
58
+ * (`typeof x.copy === 'function'`). When @langchain/core is installed
59
+ * BaseCallbackHandler's prototype provides its own `copy()`; this
60
+ * declaration overrides with a Risicare-aware copy that re-instantiates
61
+ * — sufficient for the handler-cloning paths LangChain uses internally
62
+ * (e.g., per-run isolation in concurrent chains). Spans map starts empty
63
+ * because a fresh handler should not share span state with its parent.
64
+ */
65
+ copy(): RisicareCallbackHandler;
21
66
  /**
22
67
  * Run a function with provider instrumentation suppressed.
23
68
  *
@@ -32,6 +77,9 @@ declare class RisicareCallbackHandler {
32
77
  * );
33
78
  */
34
79
  withSuppression<T>(fn: () => T): T;
80
+ private _startSpan;
81
+ private _endSpan;
82
+ private _errorSpan;
35
83
  handleChainStart(chain: {
36
84
  name?: string;
37
85
  _type?: string;
@@ -42,11 +90,29 @@ declare class RisicareCallbackHandler {
42
90
  name?: string;
43
91
  _type?: string;
44
92
  }, _prompts: string[], runId: string, parentRunId?: string): void;
93
+ /**
94
+ * F-882: chat-model lifecycle — LangChain v0.2+ emits this for any
95
+ * ChatModel (which is EVERY production LLM today). Without this method,
96
+ * not a single `langchain` LLM span fires when used via LCEL.
97
+ *
98
+ * The messages payload is an array-of-arrays (one inner array per prompt);
99
+ * we just count rather than materialize content (PII boundary).
100
+ */
101
+ handleChatModelStart(llm: {
102
+ name?: string;
103
+ _type?: string;
104
+ }, messages: unknown[][], runId: string, parentRunId?: string): void;
45
105
  handleLLMEnd(output: {
46
106
  generations?: unknown[][];
47
107
  llmOutput?: Record<string, unknown>;
48
108
  }, runId: string): void;
49
109
  handleLLMError(error: Error, runId: string): void;
110
+ /**
111
+ * F-883: streaming-token event. We do NOT create a new span (the LLM span
112
+ * already exists from handleLLMStart/handleChatModelStart) — just count tokens
113
+ * on the existing span. This is a HIGH-FREQUENCY event; do the cheap work only.
114
+ */
115
+ handleLLMNewToken(_token: string, _idx: unknown, runId: string): void;
50
116
  handleToolStart(tool: {
51
117
  name?: string;
52
118
  }, input: string, runId: string, parentRunId?: string): void;
@@ -56,6 +122,34 @@ declare class RisicareCallbackHandler {
56
122
  name?: string;
57
123
  }, _query: string, runId: string, parentRunId?: string): void;
58
124
  handleRetrieverEnd(documents: unknown[], runId: string): void;
125
+ handleRetrieverError(error: Error, runId: string): void;
126
+ /**
127
+ * Agent decided to take an action (call a tool). LangChain v0.2 agents emit
128
+ * this between LLM calls. Cheap span, no parent change.
129
+ */
130
+ handleAgentAction(action: {
131
+ tool?: string;
132
+ toolInput?: unknown;
133
+ log?: string;
134
+ }, runId: string, parentRunId?: string): void;
135
+ /**
136
+ * Agent finished (final answer produced). Mirror of handleAgentAction.
137
+ */
138
+ handleAgentEnd(action: {
139
+ returnValues?: Record<string, unknown>;
140
+ log?: string;
141
+ }, runId: string, parentRunId?: string): void;
142
+ /**
143
+ * Free-text emission (logging-style). Used by ConversationalRetrievalChain
144
+ * and verbose prints. Adds an event to the current chain span if one exists.
145
+ */
146
+ handleText(text: string, runId: string, _parentRunId?: string): void;
147
+ /**
148
+ * Custom event hook (introduced in @langchain/core 0.2.14). Customer code can
149
+ * `dispatchCustomEvent(name, payload)` from inside a runnable. We surface as
150
+ * a span event on the closest enclosing run so it shows up in the trace.
151
+ */
152
+ handleCustomEvent(eventName: string, _payload: unknown, runId: string, _tags?: string[], _metadata?: Record<string, unknown>): void;
59
153
  }
60
154
 
61
155
  export { RisicareCallbackHandler };
@@ -1,10 +1,17 @@
1
- var __getOwnPropNames = Object.getOwnPropertyNames;
2
- var __esm = (fn, res) => function __init() {
3
- return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
4
- };
1
+ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
2
+ get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
3
+ }) : x)(function(x) {
4
+ if (typeof require !== "undefined") return require.apply(this, arguments);
5
+ throw Error('Dynamic require of "' + x + '" is not supported');
6
+ });
7
+
8
+ // src/client.ts
9
+ import { createHash as createHash2 } from "crypto";
5
10
 
6
11
  // src/globals.ts
7
12
  import { AsyncLocalStorage } from "async_hooks";
13
+ var G = globalThis;
14
+ var PREFIX = "__risicare_";
8
15
  function getTracer() {
9
16
  return G[PREFIX + "tracer"];
10
17
  }
@@ -14,22 +21,21 @@ function getContextStorage() {
14
21
  }
15
22
  return G[PREFIX + "ctx"];
16
23
  }
17
- var G, PREFIX;
18
- var init_globals = __esm({
19
- "src/globals.ts"() {
20
- "use strict";
21
- G = globalThis;
22
- PREFIX = "__risicare_";
23
- }
24
- });
24
+ function getDebug() {
25
+ return G[PREFIX + "debug"] ?? false;
26
+ }
25
27
 
26
28
  // src/utils/log.ts
27
- var init_log = __esm({
28
- "src/utils/log.ts"() {
29
- "use strict";
30
- init_globals();
29
+ function debug(msg) {
30
+ if (getDebug()) {
31
+ process.stderr.write(`[risicare] ${msg}
32
+ `);
31
33
  }
32
- });
34
+ }
35
+
36
+ // src/exporters/batch.ts
37
+ var MAX_BATCH_BYTES = 8 * 1024 * 1024;
38
+ var utf8ByteLength = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function" ? (s) => Buffer.byteLength(s, "utf8") : (s) => s.length * 3;
33
39
 
34
40
  // src/ids.ts
35
41
  import { randomBytes } from "crypto";
@@ -105,7 +111,6 @@ var NOOP_SPAN = Object.freeze({
105
111
  });
106
112
 
107
113
  // src/context/storage.ts
108
- init_globals();
109
114
  function storage() {
110
115
  return getContextStorage();
111
116
  }
@@ -118,15 +123,10 @@ function runWithContext(overrides, fn) {
118
123
  return storage().run(merged, fn);
119
124
  }
120
125
 
121
- // src/exporters/batch.ts
122
- init_log();
123
-
124
- // src/exporters/http.ts
125
- init_log();
126
+ // src/runtime/applier.ts
127
+ import { createHash } from "crypto";
126
128
 
127
129
  // src/client.ts
128
- init_log();
129
- init_globals();
130
130
  function getTracer2() {
131
131
  return getTracer();
132
132
  }
@@ -138,9 +138,61 @@ function suppressProviderInstrumentation(fn) {
138
138
  }
139
139
 
140
140
  // src/frameworks/langchain.ts
141
- var RisicareCallbackHandler = class {
141
+ function resolveBaseCallbackHandler() {
142
+ try {
143
+ const { createRequire } = __require("module");
144
+ const req = createRequire(import.meta.url);
145
+ const mod = req("@langchain/core/callbacks/base");
146
+ if (mod?.BaseCallbackHandler) {
147
+ return mod.BaseCallbackHandler;
148
+ }
149
+ } catch {
150
+ }
151
+ try {
152
+ const mod = __require("@langchain/core/callbacks/base");
153
+ if (mod?.BaseCallbackHandler) {
154
+ return mod.BaseCallbackHandler;
155
+ }
156
+ } catch {
157
+ debug("RisicareCallbackHandler: @langchain/core not installed; handler will not satisfy LangChain v0.2+ instanceof check");
158
+ }
159
+ return Object;
160
+ }
161
+ var _BaseCallbackHandler = resolveBaseCallbackHandler();
162
+ var RisicareCallbackHandler = class _RisicareCallbackHandler extends _BaseCallbackHandler {
163
+ // PR-4+5 review B1: duck-type markers that LangChain v0.3's
164
+ // `isBaseCallbackHandler(x)` checks. This is the ONLY reliable way to be
165
+ // recognised across the CJS↔ESM identity split — `instanceof` cannot work
166
+ // when our `createRequire`-loaded BaseCallbackHandler is a different
167
+ // class object from the customer's ESM-imported BaseCallbackHandler.
168
+ // Keep these as instance properties (not prototype) so they survive any
169
+ // Object-fallback path when @langchain/core is absent.
142
170
  name = "RisicareCallbackHandler";
171
+ awaitHandlers = true;
172
+ ignoreLLM = false;
173
+ ignoreChain = false;
174
+ ignoreAgent = false;
175
+ ignoreRetriever = false;
176
+ ignoreCustomEvent = false;
177
+ raiseError = false;
178
+ lc_serializable = false;
179
+ lc_kwargs = {};
143
180
  _spans = /* @__PURE__ */ new Map();
181
+ constructor() {
182
+ super();
183
+ }
184
+ /**
185
+ * Required by LangChain's `isBaseCallbackHandler(x)` duck-type check
186
+ * (`typeof x.copy === 'function'`). When @langchain/core is installed
187
+ * BaseCallbackHandler's prototype provides its own `copy()`; this
188
+ * declaration overrides with a Risicare-aware copy that re-instantiates
189
+ * — sufficient for the handler-cloning paths LangChain uses internally
190
+ * (e.g., per-run isolation in concurrent chains). Spans map starts empty
191
+ * because a fresh handler should not share span state with its parent.
192
+ */
193
+ copy() {
194
+ return new _RisicareCallbackHandler();
195
+ }
144
196
  /**
145
197
  * Run a function with provider instrumentation suppressed.
146
198
  *
@@ -157,57 +209,75 @@ var RisicareCallbackHandler = class {
157
209
  withSuppression(fn) {
158
210
  return suppressProviderInstrumentation(fn);
159
211
  }
160
- // ── Chain lifecycle ────────────────────────────────────────────────────────
161
- handleChainStart(chain, _inputs, runId, parentRunId) {
212
+ // ── Internal helpers ──────────────────────────────────────────────────────
213
+ _startSpan(runId, parentRunId, name, kind, extraAttrs = {}) {
162
214
  const tracer = getTracer2();
163
215
  if (!tracer?.enabled) return;
164
216
  const parentEntry = parentRunId ? this._spans.get(parentRunId) : void 0;
165
217
  const span = tracer.createSpan({
166
- name: chain.name || chain._type || "chain",
167
- kind: "internal" /* INTERNAL */,
218
+ name,
219
+ kind,
168
220
  parentSpanId: parentEntry?.span.spanId,
169
221
  traceId: parentEntry?.span.traceId,
170
222
  attributes: {
171
- "framework": "langchain",
223
+ framework: "langchain",
172
224
  "langchain.run_id": runId,
173
225
  ...parentRunId ? { "langchain.parent_run_id": parentRunId } : {},
174
- ...chain._type ? { "langchain.chain_type": chain._type } : {}
226
+ ...extraAttrs
175
227
  }
176
228
  });
177
229
  this._spans.set(runId, { span, startTime: Date.now() });
178
230
  }
179
- handleChainEnd(_outputs, runId) {
231
+ _endSpan(runId, extraAttrs = {}) {
180
232
  const entry = this._spans.get(runId);
181
233
  if (!entry) return;
234
+ for (const [k, v] of Object.entries(extraAttrs)) {
235
+ entry.span.setAttribute(k, v);
236
+ }
182
237
  entry.span.setAttribute("gen_ai.latency_ms", Date.now() - entry.startTime);
183
238
  entry.span.end();
184
239
  this._spans.delete(runId);
185
240
  }
186
- handleChainError(error, runId) {
241
+ _errorSpan(runId, error) {
187
242
  const entry = this._spans.get(runId);
188
243
  if (!entry) return;
189
244
  entry.span.recordException(error);
190
245
  entry.span.end();
191
246
  this._spans.delete(runId);
192
247
  }
248
+ // ── Chain lifecycle ────────────────────────────────────────────────────────
249
+ handleChainStart(chain, _inputs, runId, parentRunId) {
250
+ this._startSpan(runId, parentRunId, chain.name || chain._type || "chain", "internal" /* INTERNAL */, {
251
+ ...chain._type ? { "langchain.chain_type": chain._type } : {}
252
+ });
253
+ }
254
+ handleChainEnd(_outputs, runId) {
255
+ this._endSpan(runId);
256
+ }
257
+ handleChainError(error, runId) {
258
+ this._errorSpan(runId, error);
259
+ }
193
260
  // ── LLM lifecycle ─────────────────────────────────────────────────────────
194
261
  handleLLMStart(llm, _prompts, runId, parentRunId) {
195
- const tracer = getTracer2();
196
- if (!tracer?.enabled) return;
197
- const parentEntry = parentRunId ? this._spans.get(parentRunId) : void 0;
198
- const span = tracer.createSpan({
199
- name: llm.name || llm._type || "llm",
200
- kind: "llm_call" /* LLM_CALL */,
201
- parentSpanId: parentEntry?.span.spanId,
202
- traceId: parentEntry?.span.traceId,
203
- attributes: {
204
- "framework": "langchain",
205
- "langchain.run_id": runId,
206
- "gen_ai.system": "langchain",
207
- "gen_ai.prompt.count": _prompts.length
208
- }
262
+ this._startSpan(runId, parentRunId, llm.name || llm._type || "llm", "llm_call" /* LLM_CALL */, {
263
+ "gen_ai.system": "langchain",
264
+ "gen_ai.prompt.count": _prompts.length
265
+ });
266
+ }
267
+ /**
268
+ * F-882: chat-model lifecycle — LangChain v0.2+ emits this for any
269
+ * ChatModel (which is EVERY production LLM today). Without this method,
270
+ * not a single `langchain` LLM span fires when used via LCEL.
271
+ *
272
+ * The messages payload is an array-of-arrays (one inner array per prompt);
273
+ * we just count rather than materialize content (PII boundary).
274
+ */
275
+ handleChatModelStart(llm, messages, runId, parentRunId) {
276
+ const messageCount = Array.isArray(messages) ? messages.reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0) : 0;
277
+ this._startSpan(runId, parentRunId, llm.name || llm._type || "chat_model", "llm_call" /* LLM_CALL */, {
278
+ "gen_ai.system": "langchain",
279
+ "gen_ai.message.count": messageCount
209
280
  });
210
- this._spans.set(runId, { span, startTime: Date.now() });
211
281
  }
212
282
  handleLLMEnd(output, runId) {
213
283
  const entry = this._spans.get(runId);
@@ -229,73 +299,105 @@ var RisicareCallbackHandler = class {
229
299
  this._spans.delete(runId);
230
300
  }
231
301
  handleLLMError(error, runId) {
302
+ this._errorSpan(runId, error);
303
+ }
304
+ /**
305
+ * F-883: streaming-token event. We do NOT create a new span (the LLM span
306
+ * already exists from handleLLMStart/handleChatModelStart) — just count tokens
307
+ * on the existing span. This is a HIGH-FREQUENCY event; do the cheap work only.
308
+ */
309
+ handleLLMNewToken(_token, _idx, runId) {
232
310
  const entry = this._spans.get(runId);
233
311
  if (!entry) return;
234
- entry.span.recordException(error);
235
- entry.span.end();
236
- this._spans.delete(runId);
312
+ const prior = entry.span.attributes?.["gen_ai.stream.token_count"] ?? 0;
313
+ entry.span.setAttribute("gen_ai.stream.token_count", prior + 1);
237
314
  }
238
315
  // ── Tool lifecycle ────────────────────────────────────────────────────────
239
316
  handleToolStart(tool, input, runId, parentRunId) {
317
+ this._startSpan(runId, parentRunId, tool.name || "tool", "tool_call" /* TOOL_CALL */, {
318
+ "tool.name": tool.name || "unknown",
319
+ "tool.input_length": input?.length ?? 0
320
+ });
321
+ }
322
+ handleToolEnd(output, runId) {
323
+ this._endSpan(runId, { "tool.output_length": output?.length ?? 0 });
324
+ }
325
+ handleToolError(error, runId) {
326
+ this._errorSpan(runId, error);
327
+ }
328
+ // ── Retriever lifecycle ───────────────────────────────────────────────────
329
+ handleRetrieverStart(retriever, _query, runId, parentRunId) {
330
+ this._startSpan(runId, parentRunId, retriever.name || "retriever", "retrieval" /* RETRIEVAL */);
331
+ }
332
+ handleRetrieverEnd(documents, runId) {
333
+ this._endSpan(runId, { "retriever.document_count": documents?.length ?? 0 });
334
+ }
335
+ handleRetrieverError(error, runId) {
336
+ this._errorSpan(runId, error);
337
+ }
338
+ // ── Agent lifecycle (F-882) ───────────────────────────────────────────────
339
+ /**
340
+ * Agent decided to take an action (call a tool). LangChain v0.2 agents emit
341
+ * this between LLM calls. Cheap span, no parent change.
342
+ */
343
+ handleAgentAction(action, runId, parentRunId) {
240
344
  const tracer = getTracer2();
241
345
  if (!tracer?.enabled) return;
242
346
  const parentEntry = parentRunId ? this._spans.get(parentRunId) : void 0;
243
347
  const span = tracer.createSpan({
244
- name: tool.name || "tool",
245
- kind: "tool_call" /* TOOL_CALL */,
348
+ name: `agent.action:${action.tool ?? "unknown"}`,
349
+ kind: "internal" /* INTERNAL */,
246
350
  parentSpanId: parentEntry?.span.spanId,
247
351
  traceId: parentEntry?.span.traceId,
248
352
  attributes: {
249
- "framework": "langchain",
353
+ framework: "langchain",
250
354
  "langchain.run_id": runId,
251
- "tool.name": tool.name || "unknown",
252
- "tool.input_length": input?.length ?? 0
355
+ "agent.action.tool": action.tool ?? ""
253
356
  }
254
357
  });
255
- this._spans.set(runId, { span, startTime: Date.now() });
256
- }
257
- handleToolEnd(output, runId) {
258
- const entry = this._spans.get(runId);
259
- if (!entry) return;
260
- entry.span.setAttribute("tool.output_length", output?.length ?? 0);
261
- entry.span.setAttribute("gen_ai.latency_ms", Date.now() - entry.startTime);
262
- entry.span.end();
263
- this._spans.delete(runId);
358
+ span.end();
264
359
  }
265
- handleToolError(error, runId) {
266
- const entry = this._spans.get(runId);
267
- if (!entry) return;
268
- entry.span.recordException(error);
269
- entry.span.end();
270
- this._spans.delete(runId);
271
- }
272
- // ── Retriever lifecycle ───────────────────────────────────────────────────
273
- handleRetrieverStart(retriever, _query, runId, parentRunId) {
360
+ /**
361
+ * Agent finished (final answer produced). Mirror of handleAgentAction.
362
+ */
363
+ handleAgentEnd(action, runId, parentRunId) {
274
364
  const tracer = getTracer2();
275
365
  if (!tracer?.enabled) return;
276
366
  const parentEntry = parentRunId ? this._spans.get(parentRunId) : void 0;
277
367
  const span = tracer.createSpan({
278
- name: retriever.name || "retriever",
279
- kind: "retrieval" /* RETRIEVAL */,
368
+ name: "agent.end",
369
+ kind: "internal" /* INTERNAL */,
280
370
  parentSpanId: parentEntry?.span.spanId,
281
371
  traceId: parentEntry?.span.traceId,
282
372
  attributes: {
283
- "framework": "langchain",
284
- "langchain.run_id": runId
373
+ framework: "langchain",
374
+ "langchain.run_id": runId,
375
+ "agent.return_keys": action.returnValues ? Object.keys(action.returnValues).length : 0
285
376
  }
286
377
  });
287
- this._spans.set(runId, { span, startTime: Date.now() });
378
+ span.end();
288
379
  }
289
- handleRetrieverEnd(documents, runId) {
380
+ // ── Misc (F-882) ──────────────────────────────────────────────────────────
381
+ /**
382
+ * Free-text emission (logging-style). Used by ConversationalRetrievalChain
383
+ * and verbose prints. Adds an event to the current chain span if one exists.
384
+ */
385
+ handleText(text, runId, _parentRunId) {
290
386
  const entry = this._spans.get(runId);
291
387
  if (!entry) return;
292
- entry.span.setAttribute(
293
- "retriever.document_count",
294
- documents?.length ?? 0
295
- );
296
- entry.span.setAttribute("gen_ai.latency_ms", Date.now() - entry.startTime);
297
- entry.span.end();
298
- this._spans.delete(runId);
388
+ entry.span.addEvent("langchain.text", {
389
+ "text.length": text?.length ?? 0
390
+ });
391
+ }
392
+ /**
393
+ * Custom event hook (introduced in @langchain/core 0.2.14). Customer code can
394
+ * `dispatchCustomEvent(name, payload)` from inside a runnable. We surface as
395
+ * a span event on the closest enclosing run so it shows up in the trace.
396
+ */
397
+ handleCustomEvent(eventName, _payload, runId, _tags, _metadata) {
398
+ const entry = this._spans.get(runId);
399
+ if (!entry) return;
400
+ entry.span.addEvent("langchain.custom_event", { name: eventName });
299
401
  }
300
402
  };
301
403
  export {