metergraph 0.2.0 → 0.3.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.
package/README.md CHANGED
@@ -9,7 +9,7 @@ client; call `init(...)` before the first `wrap()` only to pass options in
9
9
  code.
10
10
 
11
11
  ```ts
12
- import { wrap, route, modelFor, recordOutcome, setSession } from "metergraph";
12
+ import { wrap, route, trace, modelFor, recordOutcome, setSession } from "metergraph";
13
13
  import OpenAI from "openai";
14
14
 
15
15
  // new Anthropic() and new GoogleGenAI({}) wrap the same way.
@@ -17,10 +17,12 @@ const client = wrap(new OpenAI());
17
17
  setSession("ticket-123");
18
18
 
19
19
  let model = "gpt-4.1-mini";
20
- await route("ticket-classifier", async () => {
21
- model = modelFor("ticket-classifier", { default: model });
22
- await client.chat.completions.create({ model, messages: [] });
23
- }, { unit: "answer", captureText: true });
20
+ await trace("ticket-workflow", () =>
21
+ route("ticket-classifier", async () => {
22
+ model = modelFor("ticket-classifier", { default: model });
23
+ await client.chat.completions.create({ model, messages: [] });
24
+ }, { unit: "answer" })
25
+ );
24
26
 
25
27
  recordOutcome("ticket-classifier", {
26
28
  model,
@@ -38,9 +40,23 @@ required and throws if missing so a caller error surfaces immediately
38
40
  instead of an `undefined` model reaching a provider call.
39
41
 
40
42
  Set `METERGRAPH_APP_TOKEN`; `METERGRAPH_INGEST_URL` is only needed to override
41
- the hosted HTTPS endpoint. Content is metadata-only by default; set
42
- `METERGRAPH_CAPTURE_TEXT=1` globally or `captureText: true` on an individual
43
- route to opt in. Actual wire batches never exceed 512 KiB after optional gzip.
43
+ the hosted HTTPS endpoint. SDK 0.3 captures the scrubbed provider request and a
44
+ normalized response envelope, including assistant content and tool calls, by
45
+ default. Provider credentials and transport headers are removed. Request and
46
+ response are each limited to 100 KiB of UTF-8 with an explicit truncation
47
+ marker. Set `METERGRAPH_CAPTURE_TEXT=0`, initialize with
48
+ `captureText: false`, or set `captureText: false` on an individual `route()` or
49
+ `trace()` to opt out for sensitive operations. The public open-source server
50
+ still discards content; hosted workspaces retain it under their metadata
51
+ retention period.
52
+
53
+ `trace(name, fn, { traceId, parentSpanId, captureText })` groups calls into a
54
+ logical trace using `AsyncLocalStorage`. Nested traces reuse the active trace
55
+ unless given a different trace ID. Calls outside a trace become one-span
56
+ traces. Manual IDs can join work across process boundaries; automatic W3C HTTP
57
+ propagation is not included.
58
+
59
+ Actual wire batches never exceed 512 KiB after optional gzip.
44
60
  Long-running Node processes use an unref'd
45
61
  background timer. On Workers or Vercel, call
46
62
  `bindWaitUntil(ctx)` once per request. On Lambda, use `wrapHandler(handler)`
@@ -72,9 +88,13 @@ import * as mg from "metergraph". wrap() returns the same client and
72
88
  initializes itself from the environment: METERGRAPH_APP_TOKEN is required
73
89
  (capture is silently off without it) and METERGRAPH_INGEST_URL is only for
74
90
  self-hosted servers. Add both to .env.example, and never commit a real token.
75
- Capture is metadata-only (tokens, latency, model, no prompt/completion
76
- content) and fail-open, so do not change call sites, arguments, or error
77
- handling; async and streaming work unchanged. Wrap each function that calls a
91
+ SDK 0.3 captures scrubbed provider requests and normalized responses by
92
+ default for the hosted dashboard; use METERGRAPH_CAPTURE_TEXT=0 or
93
+ captureText: false around sensitive operations. Provider credentials and
94
+ transport headers must never be captured. Capture is fail-open, so do not
95
+ change call sites, arguments, or error handling; async and streaming work
96
+ unchanged. Use mg.trace("stable-name", fn) to group multi-call workflows. Wrap
97
+ each function that calls a
78
98
  wrapped client with mg.track("stable.name", fn), because stack-based
79
99
  attribution is unreliable under bundlers. On serverless (Lambda / Workers /
80
100
  Vercel), ensure delivery before the runtime freezes: mg.wrapHandler(handler),
package/dist/capture.d.ts CHANGED
@@ -21,6 +21,10 @@ interface CallState {
21
21
  started: number;
22
22
  ts: string;
23
23
  frames: Frame[];
24
+ traceId: string;
25
+ spanId: string;
26
+ parentSpanId?: string;
27
+ traceName: string;
24
28
  done: boolean;
25
29
  }
26
30
  export declare function chunkText(chunk: unknown): string | undefined;
@@ -35,6 +39,7 @@ export declare class CaptureRuntime {
35
39
  stream?: boolean;
36
40
  ttftMs?: number;
37
41
  responseText?: string;
42
+ responseChunks?: unknown[];
38
43
  }): void;
39
44
  }
40
45
  export {};
package/dist/capture.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { randomBytes } from "node:crypto";
1
2
  import { contextSnapshot } from "./context.js";
2
3
  import { scrub, templateHash } from "./template.js";
3
4
  import { SDK_VERSION } from "./version.js";
@@ -77,6 +78,242 @@ function toolNames(request) {
77
78
  });
78
79
  return names.length ? names : undefined;
79
80
  }
81
+ function toolArgument(value) {
82
+ if (typeof value === "string") {
83
+ try {
84
+ return JSON.parse(value);
85
+ }
86
+ catch {
87
+ return value;
88
+ }
89
+ }
90
+ return scrub(value);
91
+ }
92
+ function toolEvents(request, response, streamChunks = []) {
93
+ const calls = new Map();
94
+ const pending = new Map();
95
+ const policies = new Map();
96
+ if (Array.isArray(request.tools)) {
97
+ for (const tool of request.tools) {
98
+ const fn = get(tool, "function");
99
+ const name = get(fn, "name") ?? get(tool, "name");
100
+ const policy = get(fn, "x-metergraph-idempotency")
101
+ ?? get(tool, "x-metergraph-idempotency")
102
+ ?? get(fn, "metergraph_idempotency")
103
+ ?? get(tool, "metergraph_idempotency");
104
+ if (name)
105
+ policies.set(String(name), policy === "idempotent" ? "idempotent" : "non_idempotent");
106
+ }
107
+ }
108
+ const complete = (id, result, error = false) => {
109
+ const key = String(id ?? "");
110
+ const item = calls.get(key);
111
+ if (!item) {
112
+ pending.set(key, { result, error });
113
+ return;
114
+ }
115
+ item.result = toolArgument(result);
116
+ item.status = error ? "error" : "completed";
117
+ };
118
+ const add = (id, name, args) => {
119
+ if (!name)
120
+ return;
121
+ const key = String(id ?? `${String(name)}:${calls.size}`);
122
+ const item = {
123
+ call_id: key,
124
+ name: String(name),
125
+ arguments: toolArgument(args),
126
+ status: "requested",
127
+ idempotency: policies.get(String(name)) ?? "non_idempotent",
128
+ };
129
+ calls.set(key, item);
130
+ const waiting = pending.get(key);
131
+ if (waiting) {
132
+ pending.delete(key);
133
+ complete(key, waiting.result, waiting.error);
134
+ }
135
+ };
136
+ const blocks = (value) => {
137
+ if (!Array.isArray(value))
138
+ return;
139
+ for (const block of value) {
140
+ const kind = get(block, "type");
141
+ if (kind === "tool_use") {
142
+ add(get(block, "id"), get(block, "name"), get(block, "input"));
143
+ }
144
+ else if (kind === "tool_result") {
145
+ complete(get(block, "tool_use_id"), get(block, "content"), Boolean(get(block, "is_error")));
146
+ }
147
+ }
148
+ };
149
+ const geminiParts = (value) => {
150
+ const parts = get(value, "parts");
151
+ if (!Array.isArray(parts))
152
+ return;
153
+ for (const part of parts) {
154
+ const call = get(part, "function_call") ?? get(part, "functionCall");
155
+ if (call)
156
+ add(get(call, "id"), get(call, "name"), get(call, "args") ?? get(call, "arguments"));
157
+ const result = get(part, "function_response") ?? get(part, "functionResponse");
158
+ if (result)
159
+ complete(get(result, "id") ?? get(result, "name"), get(result, "response"));
160
+ }
161
+ };
162
+ const history = Array.isArray(request.messages)
163
+ ? request.messages
164
+ : Array.isArray(request.input)
165
+ ? request.input
166
+ : Array.isArray(request.contents)
167
+ ? request.contents
168
+ : [];
169
+ for (const message of history) {
170
+ const messageCalls = get(message, "tool_calls");
171
+ if (Array.isArray(messageCalls)) {
172
+ for (const tool of messageCalls) {
173
+ const fn = get(tool, "function");
174
+ add(get(tool, "id") ?? get(tool, "call_id"), get(fn, "name") ?? get(tool, "name"), get(fn, "arguments") ?? get(tool, "arguments"));
175
+ }
176
+ }
177
+ if (get(message, "role") === "tool") {
178
+ complete(get(message, "tool_call_id") ?? get(message, "call_id"), get(message, "content"), Boolean(get(message, "is_error")));
179
+ }
180
+ const kind = get(message, "type");
181
+ if (kind === "function_call" || kind === "tool_call") {
182
+ add(get(message, "call_id") ?? get(message, "id"), get(message, "name"), get(message, "arguments"));
183
+ }
184
+ else if (kind === "function_call_output" || kind === "tool_result") {
185
+ complete(get(message, "call_id") ?? get(message, "tool_use_id"), get(message, "output") ?? get(message, "content"), Boolean(get(message, "is_error")));
186
+ }
187
+ blocks(get(message, "content"));
188
+ geminiParts(message);
189
+ }
190
+ const message = get(first(get(response, "choices")), "message");
191
+ const responseCalls = get(message, "tool_calls");
192
+ if (Array.isArray(responseCalls)) {
193
+ for (const tool of responseCalls) {
194
+ const fn = get(tool, "function");
195
+ add(get(tool, "id") ?? get(tool, "call_id"), get(fn, "name") ?? get(tool, "name"), get(fn, "arguments") ?? get(tool, "arguments"));
196
+ }
197
+ }
198
+ blocks(get(response, "content"));
199
+ const outputs = get(response, "output");
200
+ if (Array.isArray(outputs)) {
201
+ for (const output of outputs) {
202
+ const kind = get(output, "type");
203
+ if (kind === "function_call" || kind === "tool_call") {
204
+ add(get(output, "call_id") ?? get(output, "id"), get(output, "name"), get(output, "arguments"));
205
+ }
206
+ }
207
+ }
208
+ const candidates = get(response, "candidates");
209
+ if (Array.isArray(candidates)) {
210
+ for (const candidate of candidates)
211
+ geminiParts(get(candidate, "content"));
212
+ }
213
+ const openAIDeltas = new Map();
214
+ const anthropicDeltas = new Map();
215
+ for (const chunk of streamChunks) {
216
+ const choices = get(chunk, "choices");
217
+ if (Array.isArray(choices)) {
218
+ for (const choice of choices) {
219
+ const tools = get(get(choice, "delta"), "tool_calls");
220
+ if (!Array.isArray(tools))
221
+ continue;
222
+ tools.forEach((tool, position) => {
223
+ const key = String(get(tool, "index") ?? position);
224
+ const item = openAIDeltas.get(key) ?? { id: key, name: "", arguments: "" };
225
+ item.id = String(get(tool, "id") ?? item.id);
226
+ const fn = get(tool, "function");
227
+ if (get(fn, "name"))
228
+ item.name += String(get(fn, "name"));
229
+ if (get(fn, "arguments"))
230
+ item.arguments += String(get(fn, "arguments"));
231
+ openAIDeltas.set(key, item);
232
+ });
233
+ }
234
+ }
235
+ const kind = get(chunk, "type");
236
+ if (kind === "content_block_start") {
237
+ const block = get(chunk, "content_block");
238
+ if (get(block, "type") === "tool_use") {
239
+ const key = String(get(chunk, "index") ?? anthropicDeltas.size);
240
+ const input = get(block, "input");
241
+ anthropicDeltas.set(key, {
242
+ id: String(get(block, "id") ?? key),
243
+ name: String(get(block, "name") ?? ""),
244
+ arguments: input && typeof input === "object"
245
+ && Object.keys(input).length === 0
246
+ ? ""
247
+ : JSON.stringify(scrub(input ?? {})),
248
+ });
249
+ }
250
+ }
251
+ else if (kind === "content_block_delta") {
252
+ const delta = get(chunk, "delta");
253
+ if (get(delta, "type") === "input_json_delta") {
254
+ const key = String(get(chunk, "index") ?? "0");
255
+ const item = anthropicDeltas.get(key) ?? { id: key, name: "", arguments: "" };
256
+ item.arguments += String(get(delta, "partial_json") ?? "");
257
+ anthropicDeltas.set(key, item);
258
+ }
259
+ }
260
+ const chunkCandidates = get(chunk, "candidates");
261
+ if (Array.isArray(chunkCandidates)) {
262
+ for (const candidate of chunkCandidates)
263
+ geminiParts(get(candidate, "content"));
264
+ }
265
+ }
266
+ for (const item of [...openAIDeltas.values(), ...anthropicDeltas.values()]) {
267
+ if (item.name)
268
+ add(item.id, item.name, item.arguments);
269
+ }
270
+ return calls.size ? [...calls.values()] : undefined;
271
+ }
272
+ function responseContent(response, aggregate) {
273
+ if (aggregate !== undefined)
274
+ return aggregate;
275
+ const direct = get(response, "output_text") ?? get(response, "text");
276
+ if (direct !== undefined)
277
+ return scrub(direct);
278
+ const message = get(first(get(response, "choices")), "message");
279
+ const content = get(message, "content");
280
+ if (content !== undefined)
281
+ return scrub(content);
282
+ const parsed = get(message, "parsed");
283
+ if (parsed !== undefined)
284
+ return scrub(parsed);
285
+ const normalizedText = responseText(response);
286
+ if (normalizedText !== undefined)
287
+ return normalizedText;
288
+ const blocks = get(response, "content");
289
+ if (blocks !== undefined)
290
+ return scrub(blocks);
291
+ const output = get(response, "output");
292
+ if (output !== undefined)
293
+ return scrub(output);
294
+ const candidates = get(response, "candidates");
295
+ return candidates === undefined ? undefined : scrub(candidates);
296
+ }
297
+ function responseEnvelope(response, aggregate, tools, error, status) {
298
+ const envelope = {
299
+ role: "assistant",
300
+ content: responseContent(response, aggregate),
301
+ tool_calls: tools ?? [],
302
+ finish_reason: stopReason(response),
303
+ request_id: get(response, "_request_id") ?? get(response, "response_id")
304
+ ?? get(response, "responseId") ?? get(response, "id"),
305
+ model: get(response, "model") ?? get(response, "model_version")
306
+ ?? get(response, "modelVersion"),
307
+ status,
308
+ };
309
+ if (error !== undefined) {
310
+ envelope.error = {
311
+ type: error instanceof Error ? error.name : "Error",
312
+ message: error instanceof Error ? error.message : String(error),
313
+ };
314
+ }
315
+ return Object.fromEntries(Object.entries(envelope).filter(([, value]) => value !== undefined));
316
+ }
80
317
  const SDK_DIR = (() => {
81
318
  try {
82
319
  return new URL(".", import.meta.url).pathname;
@@ -124,6 +361,11 @@ export class CaptureRuntime {
124
361
  started: performance.now(),
125
362
  ts: new Date().toISOString(),
126
363
  frames: frames(stack, this.options.appRoot, this.options.skipFrames),
364
+ traceId: context.traceId ?? randomBytes(16).toString("hex"),
365
+ spanId: randomBytes(8).toString("hex"),
366
+ parentSpanId: context.parentSpanId,
367
+ traceName: context.traceName ?? context.route ?? context.funcName
368
+ ?? endpoint,
127
369
  done: false,
128
370
  };
129
371
  }
@@ -144,11 +386,45 @@ export class CaptureRuntime {
144
386
  const bytes = new TextEncoder().encode(value);
145
387
  if (bytes.byteLength <= this.options.textMaxBytes)
146
388
  return { value, truncated: false };
147
- const clipped = new TextDecoder().decode(bytes.slice(0, this.options.textMaxBytes - 24));
148
- return { value: `${clipped}\n<metergraph:truncated>`, truncated: true };
389
+ const marker = "\n<metergraph:truncated>";
390
+ const markerBytes = new TextEncoder().encode(marker).byteLength;
391
+ let clipped = new TextDecoder().decode(bytes.slice(0, Math.max(0, this.options.textMaxBytes - markerBytes)));
392
+ while (clipped
393
+ && new TextEncoder().encode(`${clipped}${marker}`).byteLength
394
+ > this.options.textMaxBytes) {
395
+ clipped = clipped.slice(0, -1);
396
+ }
397
+ return { value: `${clipped}${marker}`, truncated: true };
149
398
  };
150
399
  const request = text(JSON.stringify(scrub(state.request)), "request");
151
- const output = text(extra.responseText ?? responseText(response), "response");
400
+ const fullTools = toolEvents(scrub(state.request), response, extra.responseChunks);
401
+ const status = extra.status ?? (extra.error ? "error" : stopReason(response) ?? "success");
402
+ const output = text(JSON.stringify(responseEnvelope(response, extra.responseText, fullTools, extra.error, status)), "response");
403
+ let toolTruncated = false;
404
+ let persistedTools;
405
+ if (fullTools && captureText) {
406
+ const encodedTools = text(JSON.stringify(fullTools), "response");
407
+ toolTruncated = encodedTools.truncated;
408
+ try {
409
+ persistedTools = encodedTools.value
410
+ ? JSON.parse(encodedTools.value)
411
+ : undefined;
412
+ }
413
+ catch {
414
+ // A truncated JSON payload is intentionally omitted. The bounded,
415
+ // redacted response envelope still describes the call and the row's
416
+ // text_truncated flag tells ingestion why this field is unavailable.
417
+ persistedTools = undefined;
418
+ }
419
+ }
420
+ else if (fullTools) {
421
+ persistedTools = fullTools.map((item) => ({
422
+ call_id: item.call_id,
423
+ name: item.name,
424
+ status: item.status,
425
+ idempotency: item.idempotency,
426
+ }));
427
+ }
152
428
  const firstFrame = state.frames[0];
153
429
  this.transport.enqueue({
154
430
  ts: state.ts,
@@ -157,22 +433,28 @@ export class CaptureRuntime {
157
433
  model: state.request.model,
158
434
  ...usage(response),
159
435
  latency_ms: Math.round(performance.now() - state.started),
160
- status: extra.status ?? (extra.error ? "error" : stopReason(response) ?? "success"),
436
+ status,
161
437
  session_id: state.context.sessionId,
438
+ conversation_id: state.context.sessionId,
439
+ trace_id: state.traceId,
440
+ span_id: state.spanId,
441
+ parent_span_id: state.parentSpanId,
442
+ trace_name: state.traceName,
162
443
  template_hash: templateHash(state.request),
163
444
  unit_name: state.context.unitName,
164
445
  unit_count: state.context.unitCount,
165
- tool_calls: toolNames(state.request),
446
+ tool_calls: fullTools ? persistedTools : toolNames(state.request),
166
447
  endpoint: state.endpoint,
167
- request_id: get(response, "_request_id") ?? get(response, "response_id") ?? get(response, "id"),
448
+ request_id: get(response, "_request_id") ?? get(response, "response_id")
449
+ ?? get(response, "responseId") ?? get(response, "id"),
168
450
  batch: state.request.batch === true,
169
451
  batch_custom_id: state.request.batch_custom_id,
170
- // Explicit positive consent stamp; the worker never infers opt-in from
171
- // content fields that happen to be present.
452
+ // Explicit false is the sensitive-operation opt-out; hosted ingestion
453
+ // otherwise preserves content that is present.
172
454
  content_opted_in: captureText,
173
455
  request_json: request.value,
174
456
  response_text: output.value,
175
- text_truncated: request.truncated || output.truncated,
457
+ text_truncated: request.truncated || output.truncated || toolTruncated,
176
458
  stream: extra.stream ?? false,
177
459
  ttft_ms: extra.ttftMs,
178
460
  func: state.context.funcName
package/dist/config.d.ts CHANGED
@@ -19,6 +19,10 @@ export declare class ConfigPoller {
19
19
  private routes;
20
20
  private lastSuccess;
21
21
  private timer?;
22
+ private stopped;
23
+ private readonly failureLog;
24
+ /** Resolves once the constructor's initial poll attempt has completed (success or failure). Exposed primarily so tests can synchronize deterministically instead of guessing a delay; not required for normal use. */
25
+ readonly ready: Promise<boolean>;
22
26
  constructor(token: string, baseUrl: string, pollMs?: number, hardTtlMs?: number);
23
27
  poll(): Promise<boolean>;
24
28
  modelFor(route: string, fallback: string, sessionKey?: string): string;
package/dist/config.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { FailureLogger } from "./failure-log.js";
1
2
  function bucket(value) {
2
3
  let hash = 0xcbf29ce484222325n;
3
4
  for (const byte of new TextEncoder().encode(value)) {
@@ -26,16 +27,25 @@ export class ConfigPoller {
26
27
  routes = {};
27
28
  lastSuccess = 0;
28
29
  timer;
30
+ stopped = false;
31
+ failureLog = new FailureLogger();
32
+ /** Resolves once the constructor's initial poll attempt has completed (success or failure). Exposed primarily so tests can synchronize deterministically instead of guessing a delay; not required for normal use. */
33
+ ready;
29
34
  constructor(token, baseUrl, pollMs = 30_000, hardTtlMs = 120_000) {
30
35
  this.token = token;
31
36
  this.baseUrl = baseUrl;
32
37
  this.pollMs = pollMs;
33
38
  this.hardTtlMs = hardTtlMs;
34
- void this.poll();
35
- this.timer = setInterval(() => void this.poll(), Math.max(1_000, pollMs));
39
+ this.ready = this.poll();
40
+ this.timer = setInterval(() => {
41
+ if (!this.stopped)
42
+ void this.poll();
43
+ }, Math.max(1_000, pollMs));
36
44
  this.timer.unref?.();
37
45
  }
38
46
  async poll() {
47
+ if (this.stopped)
48
+ return false;
39
49
  try {
40
50
  const headers = { Authorization: `Bearer ${this.token}` };
41
51
  if (this.etag)
@@ -45,15 +55,23 @@ export class ConfigPoller {
45
55
  this.lastSuccess = Date.now();
46
56
  return true;
47
57
  }
48
- if (!response.ok)
58
+ if (response.status === 401 || response.status === 403) {
59
+ console.warn("Metergraph config authentication failed; using default models");
60
+ this.stop();
61
+ return false;
62
+ }
63
+ if (!response.ok) {
64
+ this.failureLog.report("config_poll_error", `config poll to ${this.baseUrl} failed with HTTP ${response.status}`);
49
65
  return false;
66
+ }
50
67
  const body = await response.json();
51
68
  this.routes = body.routes ?? {};
52
69
  this.etag = response.headers.get("etag") ?? undefined;
53
70
  this.lastSuccess = Date.now();
54
71
  return true;
55
72
  }
56
- catch {
73
+ catch (error) {
74
+ this.failureLog.report("config_poll_error", `config poll to ${this.baseUrl} failed: ${error instanceof Error ? error.message : String(error)}`);
57
75
  return false;
58
76
  }
59
77
  }
@@ -63,6 +81,7 @@ export class ConfigPoller {
63
81
  return chooseModel(route, fallback, sessionKey, this.routes[route]);
64
82
  }
65
83
  stop() {
84
+ this.stopped = true;
66
85
  if (this.timer)
67
86
  clearInterval(this.timer);
68
87
  }
package/dist/context.d.ts CHANGED
@@ -6,6 +6,9 @@ export interface CaptureContext {
6
6
  unitCount?: number;
7
7
  captureText?: boolean;
8
8
  funcName?: string;
9
+ traceId?: string;
10
+ traceName?: string;
11
+ parentSpanId?: string;
9
12
  }
10
13
  export interface RouteOptions {
11
14
  unit?: string;
@@ -13,8 +16,14 @@ export interface RouteOptions {
13
16
  tags?: Record<string, unknown>;
14
17
  captureText?: boolean;
15
18
  }
19
+ export interface TraceOptions {
20
+ traceId?: string;
21
+ parentSpanId?: string;
22
+ captureText?: boolean;
23
+ }
16
24
  export declare function contextSnapshot(): CaptureContext;
17
25
  export declare function runWithContext<T>(context: CaptureContext, fn: () => T): T;
18
26
  export declare function route<T>(name: string, fn: () => T | Promise<T>, options?: RouteOptions): Promise<T>;
27
+ export declare function trace<T>(name: string, fn: () => T | Promise<T>, options?: TraceOptions): T | Promise<T>;
19
28
  export declare function setSession(sessionId?: string): void;
20
29
  export declare function setTags(tags: Record<string, unknown>): void;
package/dist/context.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { AsyncLocalStorage } from "node:async_hooks";
2
+ import { randomBytes } from "node:crypto";
2
3
  const storage = new AsyncLocalStorage();
3
4
  let ambient = { tags: {} };
4
5
  export function contextSnapshot() {
@@ -23,6 +24,20 @@ export async function route(name, fn, options = {}) {
23
24
  };
24
25
  return storage.run(child, fn);
25
26
  }
27
+ export function trace(name, fn, options = {}) {
28
+ const parent = contextSnapshot();
29
+ const requested = options.traceId?.trim();
30
+ const reuse = parent.traceId !== undefined
31
+ && (requested === undefined || requested === parent.traceId);
32
+ const child = {
33
+ ...parent,
34
+ traceId: reuse ? parent.traceId : requested || randomBytes(16).toString("hex"),
35
+ traceName: reuse ? parent.traceName : String(name),
36
+ parentSpanId: options.parentSpanId ?? (reuse ? parent.parentSpanId : undefined),
37
+ captureText: options.captureText ?? parent.captureText,
38
+ };
39
+ return storage.run(child, fn);
40
+ }
26
41
  export function setSession(sessionId) {
27
42
  const store = storage.getStore();
28
43
  if (store)
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Rate-limited failure logging. Logs the first occurrence of a failure kind
3
+ * immediately, then suppresses repeats within a quiet window and reports how
4
+ * many were suppressed on the next log line for that kind.
5
+ */
6
+ export declare class FailureLogger {
7
+ private readonly quietMs;
8
+ private readonly clock;
9
+ private readonly sink;
10
+ private readonly lastLogged;
11
+ private readonly suppressed;
12
+ constructor(quietMs?: number, clock?: () => number, sink?: (message: string) => void);
13
+ report(kind: string, message: string): void;
14
+ }
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Rate-limited failure logging. Logs the first occurrence of a failure kind
3
+ * immediately, then suppresses repeats within a quiet window and reports how
4
+ * many were suppressed on the next log line for that kind.
5
+ */
6
+ export class FailureLogger {
7
+ quietMs;
8
+ clock;
9
+ sink;
10
+ lastLogged = new Map();
11
+ suppressed = new Map();
12
+ constructor(quietMs = 60_000, clock = Date.now, sink = (m) => console.warn(m)) {
13
+ this.quietMs = quietMs;
14
+ this.clock = clock;
15
+ this.sink = sink;
16
+ }
17
+ report(kind, message) {
18
+ const now = this.clock();
19
+ const last = this.lastLogged.get(kind);
20
+ if (last !== undefined && now - last < this.quietMs) {
21
+ this.suppressed.set(kind, (this.suppressed.get(kind) ?? 0) + 1);
22
+ return;
23
+ }
24
+ const suppressedCount = this.suppressed.get(kind) ?? 0;
25
+ this.suppressed.delete(kind);
26
+ const suffix = suppressedCount
27
+ ? ` (${suppressedCount} more suppressed in the last ${Math.round(this.quietMs / 1000)}s)`
28
+ : "";
29
+ this.sink(`metergraph: ${message}${suffix}`);
30
+ this.lastLogged.set(kind, now);
31
+ }
32
+ }
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { route, setSession, setTags, type RouteOptions } from "./context.js";
1
+ import { route, setSession, setTags, trace, type RouteOptions, type TraceOptions } from "./context.js";
2
2
  import { track } from "./track.js";
3
3
  import { type TransportMode, type WaitUntil } from "./transport.js";
4
4
  export interface MetergraphOptions {
@@ -51,5 +51,5 @@ export declare function wrapHandler<TArgs extends unknown[], TResult>(handler: (
51
51
  */
52
52
  export declare function wrap<T extends Record<PropertyKey, any>>(client: T, provider?: "openai" | "anthropic" | "google"): T;
53
53
  export declare const wrapClient: typeof wrap;
54
- export { route, setSession, setTags, track };
55
- export type { RouteOptions, TransportMode };
54
+ export { route, setSession, setTags, trace, track };
55
+ export type { RouteOptions, TraceOptions, TransportMode };
package/dist/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { CaptureRuntime } from "./capture.js";
2
2
  import { ConfigPoller } from "./config.js";
3
- import { contextSnapshot, route, setSession, setTags, } from "./context.js";
3
+ import { contextSnapshot, route, setSession, setTags, trace, } from "./context.js";
4
4
  import { track } from "./track.js";
5
5
  import { Transport } from "./transport.js";
6
6
  import { setCaptureRuntime, wrap as wrapProvider } from "./wrap.js";
@@ -44,12 +44,12 @@ export function init(options = {}) {
44
44
  mode: options.transport ?? "auto",
45
45
  });
46
46
  setCaptureRuntime(new CaptureRuntime(transport, {
47
- captureText: options.captureText ?? envBool("METERGRAPH_CAPTURE_TEXT", false),
47
+ captureText: options.captureText ?? envBool("METERGRAPH_CAPTURE_TEXT", true),
48
48
  redact: options.redact,
49
49
  appRoot: options.appRoot ?? (typeof process === "undefined" ? "" : process.cwd()),
50
50
  skipFrames: options.skipFrames ?? [],
51
51
  environment: options.environment ?? env("METERGRAPH_ENV"),
52
- textMaxBytes: Number(env("METERGRAPH_TEXT_MAX_BYTES") ?? 100_000),
52
+ textMaxBytes: Math.min(100 * 1024, Math.max(1, Number(env("METERGRAPH_TEXT_MAX_BYTES") ?? 100 * 1024))),
53
53
  }));
54
54
  config = new ConfigPoller(token, ingestUrl, options.configPollMs, options.configHardTtlMs);
55
55
  }
@@ -138,4 +138,4 @@ export function wrap(client, provider) {
138
138
  return wrapProvider(client, provider);
139
139
  }
140
140
  export const wrapClient = wrap;
141
- export { route, setSession, setTags, track };
141
+ export { route, setSession, setTags, trace, track };
package/dist/template.js CHANGED
@@ -1,10 +1,26 @@
1
- const sensitive = new Set(["api_key", "apikey", "authorization", "headers", "token", "secret"]);
1
+ const sensitive = new Set([
2
+ "api-key",
3
+ "api_key",
4
+ "apikey",
5
+ "authorization",
6
+ "client_secret",
7
+ "cookie",
8
+ "headers",
9
+ "id_token",
10
+ "password",
11
+ "proxy-authorization",
12
+ "refresh_token",
13
+ "secret",
14
+ "set-cookie",
15
+ "token",
16
+ "x-api-key",
17
+ ]);
2
18
  export function scrub(value) {
3
19
  if (Array.isArray(value))
4
20
  return value.map(scrub);
5
21
  if (value && typeof value === "object") {
6
22
  return Object.fromEntries(Object.entries(value)
7
- .filter(([key]) => !sensitive.has(key.toLowerCase()))
23
+ .filter(([key]) => !sensitive.has(key.trim().toLowerCase()))
8
24
  .map(([key, item]) => [key, scrub(item)]));
9
25
  }
10
26
  return value;
@@ -23,6 +23,7 @@ export declare class Transport {
23
23
  private errors;
24
24
  private retryAt;
25
25
  private backoffMs;
26
+ private readonly failureLog;
26
27
  constructor(token: string, baseUrl: string, options?: TransportOptions);
27
28
  bindWaitUntil(value: {
28
29
  waitUntil(promise: Promise<unknown>): void;
@@ -30,6 +31,7 @@ export declare class Transport {
30
31
  enqueue(row: Record<string, unknown>): boolean;
31
32
  private schedule;
32
33
  flush(timeoutMs?: number): Promise<boolean>;
34
+ private markTransientFailure;
33
35
  private deliver;
34
36
  shutdown(): Promise<void>;
35
37
  }
package/dist/transport.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { FailureLogger } from "./failure-log.js";
1
2
  export const MAX_BATCH_BYTES = 512 * 1024;
2
3
  function detectedMode() {
3
4
  const env = typeof process === "undefined" ? {} : process.env;
@@ -28,6 +29,7 @@ export class Transport {
28
29
  errors = 0;
29
30
  retryAt = 0;
30
31
  backoffMs = 1_000;
32
+ failureLog = new FailureLogger();
31
33
  constructor(token, baseUrl, options = {}) {
32
34
  this.token = token;
33
35
  this.baseUrl = baseUrl;
@@ -86,6 +88,12 @@ export class Transport {
86
88
  });
87
89
  return this.queue.length === 0;
88
90
  }
91
+ markTransientFailure(rowCount) {
92
+ this.errors += 1;
93
+ this.dropped += rowCount;
94
+ this.retryAt = Date.now() + this.backoffMs;
95
+ this.backoffMs = Math.min(this.backoffMs * 2, 60_000);
96
+ }
89
97
  async deliver(rows) {
90
98
  if (this.fatal || Date.now() < this.retryAt) {
91
99
  this.dropped += rows.length;
@@ -125,16 +133,28 @@ export class Transport {
125
133
  console.warn("Metergraph authentication failed; capture disabled for this process");
126
134
  return;
127
135
  }
128
- if (response.status !== 202)
129
- throw new Error(`ingest returned ${response.status}`);
136
+ if (response.status === 413 && rows.length > 1) {
137
+ const midpoint = Math.floor(rows.length / 2);
138
+ await this.deliver(rows.slice(0, midpoint));
139
+ await this.deliver(rows.slice(midpoint));
140
+ return;
141
+ }
142
+ if ([400, 404, 413, 422].includes(response.status)) {
143
+ this.dropped += rows.length;
144
+ this.failureLog.report("client_error", `ingest rejected batch with HTTP ${response.status} against ${this.baseUrl}; dropping this batch (payload-specific, not a process-wide failure)`);
145
+ return;
146
+ }
147
+ if (response.status !== 202) {
148
+ this.markTransientFailure(rows.length);
149
+ this.failureLog.report("server_error", `ingest request failed with HTTP ${response.status} against ${this.baseUrl}`);
150
+ return;
151
+ }
130
152
  this.backoffMs = 1_000;
131
153
  this.retryAt = 0;
132
154
  }
133
- catch {
134
- this.errors += 1;
135
- this.dropped += rows.length;
136
- this.retryAt = Date.now() + this.backoffMs;
137
- this.backoffMs = Math.min(this.backoffMs * 2, 60_000);
155
+ catch (error) {
156
+ this.markTransientFailure(rows.length);
157
+ this.failureLog.report("transport_error", `ingest request to ${this.baseUrl} failed: ${error instanceof Error ? error.message : String(error)}`);
138
158
  }
139
159
  }
140
160
  async shutdown() {
package/dist/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const SDK_VERSION = "0.2.0";
1
+ export declare const SDK_VERSION = "0.3.0";
package/dist/version.js CHANGED
@@ -1 +1 @@
1
- export const SDK_VERSION = "0.2.0";
1
+ export const SDK_VERSION = "0.3.0";
package/dist/wrap.d.ts CHANGED
@@ -1,6 +1,15 @@
1
1
  import { type CaptureRuntime } from "./capture.js";
2
2
  type AnyRecord = Record<PropertyKey, any>;
3
3
  export declare function setCaptureRuntime(value?: CaptureRuntime): void;
4
+ export interface Seam {
5
+ path: string;
6
+ method: string;
7
+ endpoint: string;
8
+ }
9
+ export declare const OPENAI_SEAMS: Seam[];
10
+ export declare const ANTHROPIC_SEAMS: Seam[];
11
+ export declare const GOOGLE_SEAMS: Seam[];
12
+ export declare const SEAM_TABLES: Record<string, Seam[]>;
4
13
  export declare function wrap<T extends AnyRecord>(client: T, provider?: "openai" | "anthropic" | "google"): T;
5
14
  export declare const wrapClient: typeof wrap;
6
15
  export {};
package/dist/wrap.js CHANGED
@@ -2,6 +2,15 @@ import { chunkText } from "./capture.js";
2
2
  import { contextSnapshot } from "./context.js";
3
3
  let runtime;
4
4
  const seenBatchItems = new Set();
5
+ // Tracks which resource *owners* (e.g. a specific chat.completions instance)
6
+ // currently have a wrapped call in flight synchronously, so a delegating
7
+ // method (like openai's .parse() calling .create() on the same owner
8
+ // before any await) can be told apart from an unrelated wrapped call that
9
+ // merely happens to be nested inside another's synchronous execution.
10
+ // Scoped per-owner, not global, so two independent clients invoked in the
11
+ // same synchronous window are never mistaken for one delegating into the
12
+ // other.
13
+ const reentrantOwners = new WeakSet();
5
14
  export function setCaptureRuntime(value) {
6
15
  runtime = value;
7
16
  }
@@ -189,8 +198,10 @@ function streamProxy(stream, state, capture) {
189
198
  let last;
190
199
  let ttftMs;
191
200
  const parts = [];
201
+ const chunks = [];
192
202
  const observe = (chunk) => {
193
203
  last = chunk;
204
+ chunks.push(chunk);
194
205
  const text = chunkText(chunk);
195
206
  if (text) {
196
207
  ttftMs ??= Math.round(performance.now() - state.started);
@@ -205,6 +216,7 @@ function streamProxy(stream, state, capture) {
205
216
  stream: true,
206
217
  ttftMs,
207
218
  responseText: parts.join("") || undefined,
219
+ responseChunks: chunks,
208
220
  });
209
221
  };
210
222
  if (typeof stream.on === "function") {
@@ -281,6 +293,23 @@ function patch(owner, method, provider, endpoint) {
281
293
  const capture = runtime;
282
294
  if (!capture)
283
295
  return original.apply(owner, args);
296
+ if (reentrantOwners.has(owner)) {
297
+ // Some SDK methods delegate to another already-wrapped method on the
298
+ // *same owner* synchronously as part of building their return value
299
+ // (e.g. openai's chat.completions.parse calls .create(...) — on the
300
+ // same chat.completions instance — internally, then immediately
301
+ // chains its proprietary ._thenUnwrap() onto the result). Capturing
302
+ // this nested call too would both double-count a single underlying
303
+ // request and, worse, replace .create()'s return value with a plain
304
+ // Promise that lacks ._thenUnwrap, breaking the outer method
305
+ // entirely. Pass straight through untouched.
306
+ //
307
+ // Scoped to this specific owner (not a global flag): an unrelated
308
+ // wrapped call — a different resource, or a different client's
309
+ // instance entirely — invoked synchronously inside this one's
310
+ // execution must still be captured independently.
311
+ return original.apply(owner, args);
312
+ }
284
313
  const incoming = requestFrom(args);
285
314
  const patchUsage = typeof process === "undefined"
286
315
  || process.env.METERGRAPH_PATCH_STREAM_USAGE !== "0";
@@ -293,6 +322,7 @@ function patch(owner, method, provider, endpoint) {
293
322
  }
294
323
  const state = capture.start(provider, endpoint, requestFrom(args), new Error().stack);
295
324
  let result;
325
+ reentrantOwners.add(owner);
296
326
  try {
297
327
  result = original.apply(owner, args);
298
328
  }
@@ -300,6 +330,9 @@ function patch(owner, method, provider, endpoint) {
300
330
  capture.finish(state, undefined, { error });
301
331
  throw error;
302
332
  }
333
+ finally {
334
+ reentrantOwners.delete(owner);
335
+ }
303
336
  const complete = (response) => {
304
337
  const request = requestFrom(args);
305
338
  const streaming = endpoint.endsWith(".stream") || request.stream === true;
@@ -321,32 +354,102 @@ function patch(owner, method, provider, endpoint) {
321
354
  owner[method] = wrapped;
322
355
  return true;
323
356
  }
324
- export function wrap(client, provider) {
325
- const name = provider ?? (client.models?.generateContent
326
- ? "google"
327
- : client.chat || client.responses ? "openai" : "anthropic");
328
- let patched = 0;
329
- if (name === "google") {
330
- patched += Number(patch(client.models, "generateContent", name, "models.generate_content"));
331
- patched += Number(patch(client.models, "generateContentStream", name, "models.generate_content.stream"));
357
+ export const OPENAI_SEAMS = [
358
+ { path: "chat.completions", method: "create", endpoint: "chat.completions" },
359
+ { path: "chat.completions", method: "parse", endpoint: "chat.completions.parse" },
360
+ // beta.chat.completions.parse is v4.x-only — removed at the v4->v5
361
+ // boundary when .parse() moved to the stable chat.completions/responses
362
+ // namespaces (see metergraph-internal#9). Kept here anyway: a seam that
363
+ // doesn't exist on the installed client resolves to undefined and is
364
+ // silently skipped (see resolveSeam/applySeams below), so keeping this
365
+ // entry costs nothing on openai>=5 and restores real instrumentation for
366
+ // any consumer still on openai v4.
367
+ { path: "beta.chat.completions", method: "parse", endpoint: "chat.completions.parse" },
368
+ { path: "responses", method: "create", endpoint: "responses" },
369
+ { path: "responses", method: "stream", endpoint: "responses.stream" },
370
+ { path: "responses", method: "parse", endpoint: "responses.parse" },
371
+ { path: "beta.responses", method: "create", endpoint: "responses" },
372
+ // Note: as of openai (npm) v7.x, client.beta.responses has no .parse
373
+ // method. This table's reality-check test is pinned to latest openai, so
374
+ // beta.chat.completions.parse above is exempted from that check since it
375
+ // will correctly show as absent there — see the test for details.
376
+ ];
377
+ export const ANTHROPIC_SEAMS = [
378
+ { path: "messages", method: "create", endpoint: "messages" },
379
+ { path: "messages", method: "stream", endpoint: "messages.stream" },
380
+ ];
381
+ export const GOOGLE_SEAMS = [
382
+ { path: "models", method: "generateContent", endpoint: "models.generate_content" },
383
+ { path: "models", method: "generateContentStream", endpoint: "models.generate_content.stream" },
384
+ // Note: unlike the Python google-genai client, the JS/TS @google/genai
385
+ // client has no .aio namespace at all (verified directly against the
386
+ // installed package — client.aio is undefined; JS methods are already
387
+ // Promise-based) — do not add aio.models entries here.
388
+ ];
389
+ export const SEAM_TABLES = {
390
+ openai: OPENAI_SEAMS,
391
+ anthropic: ANTHROPIC_SEAMS,
392
+ google: GOOGLE_SEAMS,
393
+ };
394
+ function detectProvider(client) {
395
+ if (client.models?.generateContent)
396
+ return "google";
397
+ if (client.chat || client.responses)
398
+ return "openai";
399
+ return "anthropic";
400
+ }
401
+ function resolveSeam(client, path) {
402
+ let obj = client;
403
+ for (const part of path.split(".")) {
404
+ obj = obj?.[part];
405
+ if (obj === undefined || obj === null)
406
+ return undefined;
332
407
  }
333
- patched += Number(patch(client.chat?.completions, "create", name, "chat.completions"));
334
- patched += Number(patch(client.chat?.completions, "parse", name, "chat.completions.parse"));
335
- patched += Number(patch(client.beta?.chat?.completions, "parse", name, "chat.completions.parse"));
336
- patched += Number(patch(client.responses, "create", name, "responses"));
337
- patched += Number(patch(client.responses, "stream", name, "responses.stream"));
338
- patched += Number(patch(client.messages, "create", name, "messages"));
339
- patched += Number(patch(client.messages, "stream", name, "messages.stream"));
340
- if (name === "openai") {
408
+ return obj;
409
+ }
410
+ function applySeams(client, provider) {
411
+ const patched = [];
412
+ for (const seam of SEAM_TABLES[provider] ?? []) {
413
+ let owner;
414
+ try {
415
+ owner = resolveSeam(client, seam.path);
416
+ }
417
+ catch {
418
+ continue; // a pathological client property must never break wrap()
419
+ }
420
+ if (owner !== undefined && patch(owner, seam.method, provider, seam.endpoint)) {
421
+ patched.push(`${seam.path}.${seam.method}`);
422
+ }
423
+ }
424
+ return patched;
425
+ }
426
+ function applyBatchExtras(client, provider) {
427
+ let patched = 0;
428
+ if (provider === "openai") {
341
429
  patched += Number(patchOpenAIBatchContent(client.files, "content"));
342
430
  patched += Number(patchOpenAIBatchContent(client.files, "retrieveContent"));
343
431
  }
344
- else if (name === "anthropic") {
432
+ else if (provider === "anthropic") {
345
433
  patched += Number(patchAnthropicBatchResults(client.messages?.batches));
346
434
  patched += Number(patchAnthropicBatchResults(client.beta?.messages?.batches));
347
435
  }
348
- if (!patched)
349
- console.warn(`Metergraph found no supported methods on ${name} client`);
436
+ return patched;
437
+ }
438
+ export function wrap(client, provider) {
439
+ try {
440
+ const name = provider ?? detectProvider(client);
441
+ const patched = applySeams(client, name);
442
+ const patchedCount = patched.length + applyBatchExtras(client, name);
443
+ if (!patchedCount) {
444
+ console.warn(`Metergraph found no supported methods on ${name} client`);
445
+ }
446
+ else {
447
+ console.info(`Metergraph patched ${patchedCount} seam(s) on ${name} client: ${patched.join(", ") || "(batch-only)"}`);
448
+ }
449
+ }
450
+ catch (error) {
451
+ console.warn("Metergraph wrap() failed; client is unmodified and uninstrumented", error);
452
+ }
350
453
  return client;
351
454
  }
352
455
  export const wrapClient = wrap;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "metergraph",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Fire-and-forget LLM spend capture for Metergraph",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -14,6 +14,7 @@
14
14
  "files": ["dist", "README.md"],
15
15
  "scripts": {
16
16
  "build": "tsc -p tsconfig.json",
17
+ "prepack": "npm run build",
17
18
  "test": "npm run build && node --test test/*.test.mjs"
18
19
  },
19
20
  "engines": {
@@ -34,7 +35,10 @@
34
35
  "dependencies": {},
35
36
  "devDependencies": {
36
37
  "@types/node": "^24.0.0",
37
- "typescript": "^5.8.0"
38
+ "typescript": "^5.8.0",
39
+ "openai": "^7",
40
+ "@anthropic-ai/sdk": "^0.30",
41
+ "@google/genai": "^1"
38
42
  },
39
43
  "peerDependencies": {
40
44
  "@anthropic-ai/sdk": ">=0.30",