metergraph 0.6.10 → 0.6.14

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
@@ -1,8 +1,19 @@
1
1
  # metergraph (TypeScript)
2
2
 
3
- Zero-runtime-dependency capture for OpenAI, Anthropic, and Gemini clients plus
4
- provider-independent Vercel AI SDK language models on Node 18+, including AWS
5
- Lambda. Worker-style `waitUntil` hooks are present but are not part of the v1
3
+ See where your agentic AI application's LLM spend comes from. Attribute usage
4
+ to functions, agents, and workflows without changing provider call sites, then
5
+ send it to Metergraph Cloud or your self-hosted Metergraph server.
6
+
7
+ [Metergraph](https://www.metergraph.dev/) helps teams understand and optimize
8
+ agentic AI applications. This open-source, zero-runtime-dependency package
9
+ provides function-level LLM cost attribution for OpenAI, Anthropic, and Gemini
10
+ clients plus provider-independent Vercel AI SDK language models. Paid
11
+ Metergraph builds on that attribution with experimentation and optimization
12
+ across models, prompts, tools, retrieval, context, batching, and caching. This
13
+ package captures and attributes usage; it does not run experiments or optimize
14
+ your application.
15
+
16
+ The package runs on Node 18+, including AWS Lambda. Worker-style `waitUntil` hooks are present but are not part of the v1
6
17
  public-package qualification contract.
7
18
 
8
19
  Metergraph supports OpenAI JavaScript SDK majors 4 through 7. The current
@@ -176,6 +187,21 @@ inference while iterating a wrapped `client.messages.batches.results()` result.
176
187
  Consume results inside `route()` so the asynchronous batch retains its product
177
188
  route. Job-management polls are deliberately not counted as model calls.
178
189
 
190
+ OpenAI Responses created with `background: true` are recorded once, when a
191
+ wrapped `client.responses.retrieve()` or `cancel()` first returns a terminal
192
+ status (`completed`, `failed`, `cancelled` or `incomplete`), with that
193
+ response's usage and output. A `retrieve(id, { stream: true })` or
194
+ `responses.stream({ response_id })` resume is observed through its terminal
195
+ `response.*` event when the stream is iterated directly; `tee()` and
196
+ `toReadableStream()` copies are not observed. Polls that still report
197
+ `queued` or `in_progress` add no rows, and latency runs from `create` to the
198
+ observed terminal response. A background response whose terminal status the
199
+ process never observes is recorded at `shutdown()` with status `abandoned`
200
+ and unknown usage, never as a completed call with zero tokens. Only retrieves
201
+ made through the same wrapped client in the same process are observed; a
202
+ client derived with `withOptions()` or polling from a different process leaves
203
+ the call to be recorded as `abandoned`.
204
+
179
205
  ## Batch-first execution (opt-in)
180
206
 
181
207
  `batchFirst()` is a separate, explicitly opt-in code path from `wrap()`/capture: submit one request through a provider's Batch API, wait up to a caller-chosen deadline, and fall back to exactly one direct call if the batch hasn't finished in time.
@@ -220,7 +246,7 @@ codebase you want instrumented:
220
246
 
221
247
  ```text
222
248
  Instrument this codebase's LLM API costs with the `metergraph` npm package
223
- (https://github.com/PioneerSquareLabs/metergraphsdk): npm install metergraph,
249
+ (https://github.com/metergraph/metergraphsdk): npm install metergraph,
224
250
  then wrap every new OpenAI(), new Anthropic(), and new GoogleGenAI()
225
251
  construction in place, e.g. const client = mg.wrap(new OpenAI()) after
226
252
  import * as mg from "metergraph". wrap() returns the same client and
@@ -247,3 +273,7 @@ mg.vercelAISDKMiddleware() }); do not also wrap its internal provider transport.
247
273
  When done, list every client and AI SDK model you instrumented, and flag LLM
248
274
  calls made outside these supported paths.
249
275
  ```
276
+
277
+ ### Service tier evidence
278
+
279
+ Calls record `service_tier` separately from `requested_service_tier`: requesting Flex does not prove it was served. Capture reads OpenAI's response tier, Anthropic's usage tier, and Google's usage tier or traffic type, retaining evidence across trailing stream events. Successful Batch API results record `batch` from the transport, without inventing a requested tier. Missing response evidence stays unknown.
package/dist/capture.d.ts CHANGED
@@ -44,6 +44,7 @@ export declare class CaptureRuntime {
44
44
  ttftMs?: number;
45
45
  responseText?: string;
46
46
  responseChunks?: unknown[];
47
+ evidenceChunks?: unknown[];
47
48
  }): void;
48
49
  }
49
50
  export {};
package/dist/capture.js CHANGED
@@ -2,6 +2,7 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.CaptureRuntime = exports.DEFAULT_TEXT_MAX_BYTES = void 0;
4
4
  exports.chunkText = chunkText;
5
+ const model_evidence_js_1 = require("./model-evidence.js");
5
6
  const node_crypto_1 = require("node:crypto");
6
7
  const context_js_1 = require("./context.js");
7
8
  const gateway_js_1 = require("./gateway.js");
@@ -12,6 +13,54 @@ exports.DEFAULT_TEXT_MAX_BYTES = 1024 * 1024;
12
13
  function get(value, key) {
13
14
  return value && typeof value === "object" ? value[key] : undefined;
14
15
  }
16
+ function tierString(value) {
17
+ return typeof value === "string" && value.trim() ? value.trim() : undefined;
18
+ }
19
+ function serviceTier(value) {
20
+ return tierString(get(value, "service_tier") ?? get(value, "serviceTier"));
21
+ }
22
+ function responseTier(value) {
23
+ const direct = serviceTier(value) ?? serviceTier(get(value, "usage"));
24
+ if (direct !== undefined)
25
+ return direct;
26
+ const usage = get(value, "usageMetadata") ?? get(value, "usage_metadata");
27
+ const nativeTier = serviceTier(usage);
28
+ if (nativeTier !== undefined)
29
+ return nativeTier;
30
+ const traffic = tierString(get(usage, "trafficType") ?? get(usage, "traffic_type"));
31
+ if (traffic === "ON_DEMAND_FLEX")
32
+ return "flex";
33
+ if (traffic === "ON_DEMAND")
34
+ return "standard";
35
+ if (traffic === "ON_DEMAND_PRIORITY")
36
+ return "priority";
37
+ return traffic;
38
+ }
39
+ function servedServiceTier(response, chunks = []) {
40
+ const read = (value) => responseTier(value)
41
+ ?? responseTier(get(value, "response")) ?? responseTier(get(value, "message"));
42
+ const direct = read(response);
43
+ if (direct !== undefined)
44
+ return direct;
45
+ // A trailing event need not repeat the provider's tier.
46
+ for (let i = chunks.length - 1; i >= 0; i--) {
47
+ const tier = read(chunks[i]);
48
+ if (tier !== undefined)
49
+ return tier;
50
+ }
51
+ return undefined;
52
+ }
53
+ function requestedServiceTier(request) {
54
+ const config = get(request, "config");
55
+ const explicit = serviceTier(request) ?? serviceTier(config);
56
+ if (explicit !== undefined)
57
+ return explicit;
58
+ const http = get(config, "httpOptions") ?? get(config, "http_options");
59
+ const headers = get(http, "headers");
60
+ if (!headers || typeof headers !== "object")
61
+ return undefined;
62
+ return tierString(Object.entries(headers).find(([key]) => key.toLowerCase() === "x-vertex-ai-llm-shared-request-type")?.[1]);
63
+ }
15
64
  function first(value) {
16
65
  return Array.isArray(value) ? value[0] : undefined;
17
66
  }
@@ -767,12 +816,19 @@ class CaptureRuntime {
767
816
  provider: state.provider,
768
817
  model: state.request.model,
769
818
  ...usage(response),
819
+ // The Batch API confirms billing even when its body reports a default tier.
820
+ service_tier: state.endpoint.startsWith("batch.") && response != null
821
+ && !extra.error && extra.status !== "error"
822
+ ? "batch" : servedServiceTier(response, extra.responseChunks),
823
+ requested_service_tier: requestedServiceTier(state.request),
770
824
  ...(0, gateway_js_1.gatewayEvidence)(state.gateway, state.endpoint, response),
771
825
  latency_ms: Math.round(performance.now() - state.started),
772
826
  status,
773
827
  status_code: statusCode,
774
828
  finish_reason: finishReason,
775
829
  finish_reason_raw: finishReasonRaw,
830
+ ...(0, model_evidence_js_1.modelEvidence)({ response, error: extra.error, refusalSignal: state.context.refusalSignal,
831
+ stream_chunks: extra.evidenceChunks ?? extra.responseChunks, stream_complete: extra.stream === true && extra.error === undefined && extra.status !== "error" && extra.status !== "abandoned" }),
776
832
  session_id: state.context.sessionId,
777
833
  conversation_id: state.context.sessionId,
778
834
  trace_id: state.traceId,
package/dist/context.d.ts CHANGED
@@ -7,6 +7,7 @@ export interface CaptureContext {
7
7
  unitName?: string;
8
8
  unitCount?: number;
9
9
  captureText?: boolean;
10
+ refusalSignal?: boolean;
10
11
  funcName?: string;
11
12
  traceId?: string;
12
13
  traceName?: string;
@@ -24,6 +25,8 @@ export interface TraceOptions {
24
25
  captureText?: boolean;
25
26
  }
26
27
  export interface ContextOptions {
28
+ /** Scoped observation; an explicit native refusal takes precedence. */
29
+ refusalSignal?: boolean;
27
30
  sessionId?: string;
28
31
  tags?: Record<string, unknown>;
29
32
  }
package/dist/context.js CHANGED
@@ -31,6 +31,7 @@ function withContext(options, fn) {
31
31
  const child = {
32
32
  ...parent,
33
33
  sessionId: options.sessionId ?? parent.sessionId,
34
+ refusalSignal: options.refusalSignal ?? parent.refusalSignal,
34
35
  tags: { ...parent.tags, ...normalizeTags(options.tags ?? {}) },
35
36
  };
36
37
  return storage.run(child, fn);
package/dist/index.js CHANGED
@@ -93,7 +93,7 @@ function init(options = {}) {
93
93
  initialized = true;
94
94
  if (!repoConfig && !warnedNoRepository) {
95
95
  warnedNoRepository = true;
96
- console.warn("Metergraph repository identity is not configured; set init({ repository: \"owner/repository\" }), METERGRAPH_REPOSITORY, or provide .metergraph/config.json. Continuing with legacy ingestion.");
96
+ console.warn("Metergraph is capturing calls normally. Repository identity is optional and not set, so traces are not linked to a source repository. To link them, commit .metergraph/config.json containing {\"repository\": \"owner/name\"}, set METERGRAPH_REPOSITORY=owner/name, pass init({ repository: \"owner/name\" }), or run `metergraph setup` in the project.");
97
97
  }
98
98
  sessionManager = repoConfig
99
99
  ? new session_js_1.SessionManager(token, ingestUrl, repoConfig.repository, version_js_1.SDK_VERSION)
@@ -179,6 +179,14 @@ async function flush(timeoutMs = 3_000) {
179
179
  return transport?.flush(timeoutMs) ?? true;
180
180
  }
181
181
  async function shutdown() {
182
+ // Background responses whose final result was never retrieved are recorded
183
+ // as abandoned before the transport drains, never as zero usage.
184
+ try {
185
+ (0, wrap_js_1.finishBackgroundCalls)();
186
+ }
187
+ catch {
188
+ // fail-open
189
+ }
182
190
  config?.stop();
183
191
  config = undefined;
184
192
  await transport?.shutdown();
@@ -0,0 +1,15 @@
1
+ export declare function modelEvidence(input: {
2
+ response?: unknown;
3
+ error?: unknown;
4
+ stream_chunks?: unknown[];
5
+ stream_complete?: boolean;
6
+ refusalSignal?: boolean;
7
+ }): {
8
+ otel?: {
9
+ finish_reasons: string[];
10
+ } | undefined;
11
+ http_status_code: number | null;
12
+ error_code: string | null;
13
+ refusal_signal: boolean | null;
14
+ response_received: boolean | null;
15
+ };
@@ -0,0 +1,105 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.modelEvidence = modelEvidence;
4
+ /** Content-free native facts; receivers own outcome classification. */
5
+ function get(value, key) {
6
+ return value && typeof value === "object" ? value[key] : undefined;
7
+ }
8
+ function items(value) { return Array.isArray(value) ? value : []; }
9
+ function text(value) { return typeof value === "string" && value.trim().length > 0 && value.length <= 256; }
10
+ function inspect(value) {
11
+ const reasons = [], coverage = [];
12
+ let positive = false, received = false;
13
+ const reason = (raw) => { if (text(raw))
14
+ reasons.push(raw); };
15
+ reason(get(value, "finish_reason"));
16
+ reason(get(value, "stop_reason"));
17
+ const camelFinish = get(value, "finishReason");
18
+ reason(get(camelFinish, "raw") ?? get(camelFinish, "unified") ?? camelFinish);
19
+ if (["refusal", "response.refusal.delta", "response.refusal.done"].includes(String(get(value, "type"))))
20
+ positive = true;
21
+ for (const part of [get(value, "part"), get(value, "content_block")])
22
+ positive ||= get(part, "type") === "refusal";
23
+ const delta = get(value, "delta");
24
+ reason(get(delta, "stop_reason"));
25
+ positive ||= Boolean(get(delta, "refusal"));
26
+ const choices = get(value, "choices");
27
+ if (Array.isArray(choices)) {
28
+ received = true;
29
+ for (const choice of choices) {
30
+ const finish = get(choice, "finish_reason"), message = get(choice, "message");
31
+ reason(finish);
32
+ positive ||= Boolean(get(message, "refusal")) || Boolean(get(get(choice, "delta"), "refusal")) || items(get(message, "content")).some(part => get(part, "type") === "refusal");
33
+ coverage.push(message != null && text(finish) && (get(message, "content") != null || get(message, "tool_calls") != null || typeof message === "object" && "refusal" in message));
34
+ }
35
+ }
36
+ const content = get(value, "content");
37
+ if (Array.isArray(content)) {
38
+ positive ||= content.some(part => get(part, "type") === "refusal");
39
+ if (text(get(value, "stop_reason"))) {
40
+ received = true;
41
+ coverage.push(content.length > 0 && content.every(part => ["text", "thinking", "redacted_thinking", "tool_use", "refusal"].includes(String(get(part, "type")))));
42
+ }
43
+ }
44
+ const output = get(value, "output");
45
+ if (Array.isArray(output)) {
46
+ received = true;
47
+ for (const item of output) {
48
+ const parts = items(get(item, "content"));
49
+ positive ||= get(item, "type") === "refusal" || parts.some(part => get(part, "type") === "refusal");
50
+ coverage.push(["completed", "incomplete"].includes(String(get(value, "status"))) && (get(item, "type") === "message" && parts.length > 0 && parts.every(part => ["output_text", "refusal"].includes(String(get(part, "type")))) ||
51
+ ["function_call", "reasoning"].includes(String(get(item, "type")))));
52
+ }
53
+ }
54
+ reason(get(get(value, "incomplete_details"), "reason"));
55
+ const feedback = get(value, "promptFeedback") ?? get(value, "prompt_feedback");
56
+ if (feedback != null) {
57
+ received = true;
58
+ reason(get(feedback, "blockReason") ?? get(feedback, "block_reason"));
59
+ }
60
+ const candidates = get(value, "candidates");
61
+ if (Array.isArray(candidates)) {
62
+ received = true;
63
+ for (const candidate of candidates) {
64
+ const finish = get(candidate, "finishReason") ?? get(candidate, "finish_reason");
65
+ reason(finish);
66
+ const parts = items(get(get(candidate, "content"), "parts"));
67
+ positive ||= parts.some(part => get(part, "type") === "refusal");
68
+ coverage.push(text(finish) && parts.length > 0);
69
+ }
70
+ }
71
+ return { positive, complete: coverage.length > 0 && coverage.every(Boolean), received, reasons };
72
+ }
73
+ function modelEvidence(input) {
74
+ const { response, error } = input;
75
+ const raw = get(error, "status_code") ?? get(error, "status") ?? get(error, "statusCode")
76
+ ?? get(get(error, "response"), "status_code") ?? get(response, "status_code");
77
+ const status = typeof raw === "number" && Number.isInteger(raw) && raw >= 100 && raw <= 599 ? raw : null;
78
+ let payload = get(error, "error") ?? get(error, "body") ?? error;
79
+ payload = get(payload, "error") ?? payload;
80
+ const code = get(payload, "code") ?? get(error, "code");
81
+ const safeInspect = (value) => {
82
+ try {
83
+ return inspect(value);
84
+ }
85
+ catch {
86
+ return { positive: false, complete: false, received: false, reasons: [] };
87
+ }
88
+ };
89
+ const native = safeInspect(response);
90
+ for (const chunk of input.stream_chunks ?? []) {
91
+ for (const value of [chunk, get(chunk, "response")]) {
92
+ const inspected = safeInspect(value);
93
+ native.positive ||= inspected.positive;
94
+ native.received ||= inspected.received;
95
+ native.reasons.push(...inspected.reasons);
96
+ }
97
+ }
98
+ const signal = native.positive ? true : typeof input.refusalSignal === "boolean" ? input.refusalSignal :
99
+ native.complete && (input.stream_chunks === undefined || input.stream_complete) ? false : null;
100
+ return {
101
+ http_status_code: status, error_code: text(code) ? code : null,
102
+ refusal_signal: signal, response_received: native.received || native.positive ? true : null,
103
+ ...(native.reasons.length ? { otel: { finish_reasons: native.reasons } } : {}),
104
+ };
105
+ }
package/dist/template.js CHANGED
@@ -82,10 +82,21 @@ function normalized(value) {
82
82
  }
83
83
  if (typeof value !== "string")
84
84
  return value;
85
+ // Every pattern here must run in time linear in the text: a request can
86
+ // carry megabytes in one string (an inline image) and this runs inside the
87
+ // wrapped call. The email local part is capped at 64 characters, the most
88
+ // RFC 5321 allows, and the domain commits to its first dot instead of
89
+ // retrying from every dot. It matches the same strings as the former
90
+ // `[^\s@]+@[^\s@]+\.[^\s@]+\b`, which rescanned a run with no whitespace
91
+ // or "@" from every word boundary and was quadratic on a base64 image.
92
+ // Inline images differ on every call, so for fingerprinting they are a URL.
93
+ // The data URL's media type is bounded and may not hold ":", which a media
94
+ // type never does, so a "data:" that is not a data URL fails within a few
95
+ // characters instead of scanning the rest of the string from every "data:".
85
96
  return value
86
97
  .replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/gi, "<uuid>")
87
- .replace(/\b[^\s@]+@[^\s@]+\.[^\s@]+\b/g, "<email>")
88
- .replace(/\bhttps?:\/\/\S+/g, "<url>")
98
+ .replace(/\b[^\s@]{1,64}@[^\s@][^\s@.]*\.[^\s@]+\b/g, "<email>")
99
+ .replace(/\b(?:https?:\/\/|data:[^\s,:]{0,255};base64,)\S+/g, "<url>")
89
100
  .replace(/\b[A-Za-z0-9_-]{24,}\b/g, "<token>")
90
101
  .replace(/(^|[^A-Za-z])[-+]?\d+(?:\.\d+)?(?=$|[^A-Za-z])/g, "$1<n>")
91
102
  .replace(/\s+/g, " ")
package/dist/vercel-ai.js CHANGED
@@ -81,10 +81,12 @@ function wrapStreamResult(result, capture, state, started) {
81
81
  let finishPart;
82
82
  let streamError;
83
83
  const content = [];
84
+ const evidenceChunks = [];
84
85
  const responseMetadata = {};
85
86
  // Telemetry inspection of one part. Reads part fields, so callers run it
86
87
  // fail-open; a fault must not block delivery or become a stream error.
87
88
  const observe = (part) => {
89
+ evidenceChunks.push(part);
88
90
  if (firstOutputAt === undefined && outputChunk(part))
89
91
  firstOutputAt = performance.now();
90
92
  const delta = (0, capture_js_1.chunkText)(part);
@@ -137,6 +139,7 @@ function wrapStreamResult(result, capture, state, started) {
137
139
  status,
138
140
  stream: true,
139
141
  responseText: text,
142
+ evidenceChunks,
140
143
  ttftMs: firstOutputAt === undefined ? undefined : Math.round(firstOutputAt - started),
141
144
  });
142
145
  };
package/dist/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const SDK_VERSION = "0.6.10";
1
+ export declare const SDK_VERSION = "0.6.14";
package/dist/version.js CHANGED
@@ -1,4 +1,4 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.SDK_VERSION = void 0;
4
- exports.SDK_VERSION = "0.6.10";
4
+ exports.SDK_VERSION = "0.6.14";
package/dist/wrap.d.ts CHANGED
@@ -3,6 +3,8 @@ type AnyRecord = Record<PropertyKey, any>;
3
3
  export declare function setCaptureRuntime(value?: CaptureRuntime): void;
4
4
  /** @internal Used by optional framework adapters without adding runtime dependencies. */
5
5
  export declare function getCaptureRuntime(): CaptureRuntime | undefined;
6
+ /** Record every held background call whose final result was never observed. */
7
+ export declare function finishBackgroundCalls(status?: string): number;
6
8
  export interface Seam {
7
9
  path: string;
8
10
  method: string;
package/dist/wrap.js CHANGED
@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.wrapClient = exports.SEAM_TABLES = exports.GOOGLE_SEAMS = exports.ANTHROPIC_SEAMS = exports.OPENAI_SEAMS = void 0;
4
4
  exports.setCaptureRuntime = setCaptureRuntime;
5
5
  exports.getCaptureRuntime = getCaptureRuntime;
6
+ exports.finishBackgroundCalls = finishBackgroundCalls;
6
7
  exports.wrap = wrap;
7
8
  const capture_js_1 = require("./capture.js");
8
9
  const context_js_1 = require("./context.js");
@@ -77,7 +78,6 @@ function captureOpenAIBatchItem(capture, item, sourceId, context, stack) {
77
78
  const request = {
78
79
  model: get(body, "model"),
79
80
  batch: true,
80
- service_tier: "batch",
81
81
  batch_custom_id: customId || undefined,
82
82
  batch_item_id: itemId || undefined,
83
83
  };
@@ -150,7 +150,6 @@ function captureAnthropicBatchItem(capture, item, batchId, context, stack) {
150
150
  const state = capture.start("anthropic", "batch.messages", {
151
151
  model: get(message, "model"),
152
152
  batch: true,
153
- service_tier: "batch",
154
153
  batch_custom_id: customId || undefined,
155
154
  batch_id: batchId || undefined,
156
155
  }, stack, context);
@@ -278,7 +277,7 @@ function streamProxy(stream, state, capture, suppressUsageOnly) {
278
277
  stream.on("error", (error) => finish(last, error));
279
278
  }
280
279
  return new Proxy(stream, {
281
- get(target, property, receiver) {
280
+ get(target, property) {
282
281
  if (property === Symbol.asyncIterator && typeof target[Symbol.asyncIterator] === "function") {
283
282
  return async function* () {
284
283
  try {
@@ -337,7 +336,7 @@ function streamProxy(stream, state, capture, suppressUsageOnly) {
337
336
  };
338
337
  }
339
338
  if (property === "close" || property === "abort") {
340
- const original = Reflect.get(target, property, receiver);
339
+ const original = Reflect.get(target, property);
341
340
  if (typeof original !== "function")
342
341
  return original;
343
342
  return (...args) => {
@@ -357,7 +356,7 @@ function streamProxy(stream, state, capture, suppressUsageOnly) {
357
356
  return returned;
358
357
  };
359
358
  }
360
- const value = Reflect.get(target, property, receiver);
359
+ const value = Reflect.get(target, property);
361
360
  return typeof value === "function" ? value.bind(target) : value;
362
361
  },
363
362
  });
@@ -405,6 +404,153 @@ function preserveProviderPromise(target, complete, fail) {
405
404
  },
406
405
  });
407
406
  }
407
+ // Background Responses ({ background: true }) return a queued or in-progress
408
+ // response from create(); output and usage arrive on a later retrieve() or
409
+ // cancel(). The capture is held until the client observes a terminal status,
410
+ // then recorded once from that response. A held call the client never sees
411
+ // finish is recorded as "abandoned" at shutdown (or when the bound is
412
+ // exceeded), so it is never stored as a completed call with zero usage.
413
+ const BACKGROUND_PENDING = new Set(["queued", "in_progress"]);
414
+ const BACKGROUND_TERMINAL = new Set(["completed", "failed", "cancelled", "incomplete"]);
415
+ const BACKGROUND_MAX_PENDING = 1024;
416
+ const backgroundCalls = new Map();
417
+ function shouldHoldBackground(endpoint, request, response) {
418
+ try {
419
+ return (endpoint === "responses" || endpoint === "responses.parse")
420
+ && BACKGROUND_PENDING.has(get(response, "status"))
421
+ && (request.background === true || get(response, "background") === true)
422
+ && typeof get(response, "id") === "string"
423
+ && get(response, "id") !== "";
424
+ }
425
+ catch {
426
+ return false;
427
+ }
428
+ }
429
+ function holdBackground(capture, state, response) {
430
+ const id = get(response, "id");
431
+ backgroundCalls.delete(id);
432
+ backgroundCalls.set(id, { capture, state, last: response });
433
+ while (backgroundCalls.size > BACKGROUND_MAX_PENDING) {
434
+ const [oldest, held] = backgroundCalls.entries().next().value;
435
+ backgroundCalls.delete(oldest);
436
+ finishCapture(held.capture, held.state, held.last, { status: "abandoned" });
437
+ }
438
+ }
439
+ function observeBackground(response) {
440
+ try {
441
+ const id = get(response, "id");
442
+ if (typeof id !== "string")
443
+ return;
444
+ const held = backgroundCalls.get(id);
445
+ if (!held)
446
+ return;
447
+ const status = get(response, "status");
448
+ if (BACKGROUND_PENDING.has(status)) {
449
+ held.last = response;
450
+ return;
451
+ }
452
+ if (!BACKGROUND_TERMINAL.has(status))
453
+ return;
454
+ backgroundCalls.delete(id);
455
+ finishCapture(held.capture, held.state, response);
456
+ }
457
+ catch {
458
+ // Observation is telemetry-only and fail-open.
459
+ }
460
+ }
461
+ function observeBackgroundEvent(event) {
462
+ try {
463
+ const type = get(event, "type");
464
+ if (typeof type === "string" && type.startsWith("response.")) {
465
+ const response = get(event, "response");
466
+ if (response)
467
+ observeBackground(response);
468
+ }
469
+ }
470
+ catch {
471
+ // fail-open
472
+ }
473
+ }
474
+ // Pass a resumed background stream through unchanged, observing its response
475
+ // events so the terminal one finishes the held call.
476
+ function observedBackgroundStream(stream) {
477
+ return new Proxy(stream, {
478
+ get(target, property, receiver) {
479
+ if (property === Symbol.asyncIterator) {
480
+ return async function* () {
481
+ for await (const event of target) {
482
+ observeBackgroundEvent(event);
483
+ yield event;
484
+ }
485
+ };
486
+ }
487
+ const value = Reflect.get(target, property, receiver);
488
+ return typeof value === "function" ? value.bind(target) : value;
489
+ },
490
+ });
491
+ }
492
+ /** Record every held background call whose final result was never observed. */
493
+ function finishBackgroundCalls(status = "abandoned") {
494
+ const held = [...backgroundCalls.values()];
495
+ backgroundCalls.clear();
496
+ for (const call of held)
497
+ finishCapture(call.capture, call.state, call.last, { status });
498
+ return held.length;
499
+ }
500
+ function patchBackgroundObserver(owner, method) {
501
+ if (!owner || typeof owner[method] !== "function")
502
+ return false;
503
+ if (owner[method].__metergraph__)
504
+ return true;
505
+ const original = owner[method];
506
+ const wrapped = function (...args) {
507
+ const result = original.apply(owner, args);
508
+ // retrieve(id, { stream: true }) resumes a background response as a stream.
509
+ let streamed = false;
510
+ try {
511
+ streamed = get(args[1], "stream") === true;
512
+ }
513
+ catch {
514
+ // fail-open
515
+ }
516
+ const observe = (value) => {
517
+ if (streamed) {
518
+ try {
519
+ return value && value[Symbol.asyncIterator] ? observedBackgroundStream(value) : value;
520
+ }
521
+ catch {
522
+ return value;
523
+ }
524
+ }
525
+ observeBackground(value);
526
+ return value;
527
+ };
528
+ if (result && typeof result.then === "function") {
529
+ return preserveProviderPromise(result, observe, (error) => {
530
+ throw error;
531
+ });
532
+ }
533
+ return observe(result);
534
+ };
535
+ wrapped.__metergraph__ = true;
536
+ owner[method] = wrapped;
537
+ return true;
538
+ }
539
+ function applyBackgroundObservers(client) {
540
+ let patched = 0;
541
+ for (const path of ["responses", "beta.responses"]) {
542
+ let owner;
543
+ try {
544
+ owner = resolveSeam(client, path);
545
+ }
546
+ catch {
547
+ continue;
548
+ }
549
+ for (const method of ["retrieve", "cancel"])
550
+ patched += Number(patchBackgroundObserver(owner, method));
551
+ }
552
+ return patched;
553
+ }
408
554
  function patch(owner, method, provider, endpoint, gatewayName) {
409
555
  if (!owner || typeof owner[method] !== "function")
410
556
  return false;
@@ -433,6 +579,12 @@ function patch(owner, method, provider, endpoint, gatewayName) {
433
579
  return original.apply(owner, args);
434
580
  }
435
581
  const incoming = requestFrom(args);
582
+ if (endpoint === "responses.stream" && incoming.response_id != null) {
583
+ // Resuming an existing (background) response is not a new model call:
584
+ // it retrieves with stream: true, and the retrieve observer records the
585
+ // held create once from its terminal event.
586
+ return original.apply(owner, args);
587
+ }
436
588
  const patchUsage = typeof process === "undefined"
437
589
  || process.env.METERGRAPH_PATCH_STREAM_USAGE !== "0";
438
590
  let injectedUsage = false;
@@ -482,7 +634,12 @@ function patch(owner, method, provider, endpoint, gatewayName) {
482
634
  }
483
635
  if (!settled) {
484
636
  settled = true;
485
- finishCapture(capture, state, response);
637
+ if (shouldHoldBackground(endpoint, request, response)) {
638
+ holdBackground(capture, state, response);
639
+ }
640
+ else {
641
+ finishCapture(capture, state, response);
642
+ }
486
643
  }
487
644
  return response;
488
645
  };
@@ -613,7 +770,8 @@ function wrap(client, providerOrOptions) {
613
770
  const name = provider ?? detectProvider(client);
614
771
  const gatewayName = overrideGateway ?? (name === "openai" ? (0, gateway_js_1.detectGateway)(client) : undefined);
615
772
  const patched = applySeams(client, name, gatewayName);
616
- const patchedCount = patched.length + applyBatchExtras(client, name);
773
+ const patchedCount = patched.length + applyBatchExtras(client, name)
774
+ + (name === "openai" ? applyBackgroundObservers(client) : 0);
617
775
  const label = gatewayName ? `${gatewayName} gateway via ${name}` : name;
618
776
  if (!patchedCount) {
619
777
  console.warn(`Metergraph found no supported methods on ${label} client`);
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "metergraph",
3
- "version": "0.6.10",
4
- "description": "Fire-and-forget LLM spend capture for Metergraph",
3
+ "version": "0.6.14",
4
+ "description": "Zero-dependency TypeScript SDK for function-level LLM cost attribution across major LLM providers and frameworks, including OpenAI, Anthropic, Gemini, and Vercel AI SDK.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
7
7
  "module": "./dist/index.mjs",
@@ -29,17 +29,29 @@
29
29
  "node": ">=18"
30
30
  },
31
31
  "license": "Apache-2.0",
32
- "author": "Pioneer Square Labs",
32
+ "author": "Metergraph",
33
33
  "homepage": "https://www.metergraph.dev/",
34
34
  "repository": {
35
35
  "type": "git",
36
- "url": "git+https://github.com/PioneerSquareLabs/metergraphsdk.git",
36
+ "url": "git+https://github.com/metergraph/metergraphsdk.git",
37
37
  "directory": "typescript"
38
38
  },
39
39
  "bugs": {
40
- "url": "https://github.com/PioneerSquareLabs/metergraphsdk/issues"
40
+ "url": "https://github.com/metergraph/metergraphsdk/issues"
41
41
  },
42
- "keywords": ["llm", "observability", "openai", "anthropic", "gemini", "vercel-ai-sdk", "cost-tracking"],
42
+ "keywords": [
43
+ "llm",
44
+ "llm-cost",
45
+ "llm-observability",
46
+ "cost-attribution",
47
+ "ai-agents",
48
+ "openai",
49
+ "anthropic",
50
+ "gemini",
51
+ "vercel-ai-sdk",
52
+ "opentelemetry",
53
+ "self-hosted"
54
+ ],
43
55
  "dependencies": {},
44
56
  "devDependencies": {
45
57
  "@ai-sdk/anthropic": "^4.0.39",