metergraph 0.5.0 → 0.6.2

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
@@ -5,35 +5,47 @@ provider-independent Vercel AI SDK language models on Node 18+, including AWS
5
5
  Lambda. Worker-style `waitUntil` hooks are present but are not part of the v1
6
6
  public-package qualification contract.
7
7
 
8
- `wrap()` initializes capture from the environment, so setup is one line per
9
- client; call `init(...)` before the first `wrap()` only to pass options in
10
- code.
8
+ Initialize Metergraph once, then wrap each provider client. `init()` reads the
9
+ token and other omitted options from the environment.
10
+
11
+ Initialization is process-wide. The first `init()` configuration remains
12
+ active; later explicit calls are ignored and produce one generic warning
13
+ without option names, token values, or other secrets.
11
14
 
12
15
  ```ts
13
- import { wrap, route, trace, modelFor, recordOutcome, setSession } from "metergraph";
16
+ import { init, wrap, route, trace, modelFor, recordOutcome, withSession } from "metergraph";
14
17
  import OpenAI from "openai";
15
18
 
19
+ init({ repository: "owner/repository" });
16
20
  // new Anthropic() and new GoogleGenAI({}) wrap the same way.
17
21
  const client = wrap(new OpenAI());
18
- setSession("ticket-123");
19
22
 
20
23
  let model = "gpt-4.1-mini";
21
- await trace("ticket-workflow", () =>
22
- route("ticket-classifier", async () => {
23
- model = modelFor("ticket-classifier", { default: model });
24
- await client.chat.completions.create({ model, messages: [] });
25
- }, { unit: "answer" })
26
- );
27
-
28
- recordOutcome("ticket-classifier", {
29
- model,
30
- taskCompleted: true,
31
- feedbackScore: 1,
32
- turnsToResolution: 2,
33
- escalated: false,
24
+ await withSession("ticket-123", async () => {
25
+ await trace("ticket-workflow", () =>
26
+ route("ticket-classifier", async () => {
27
+ model = modelFor("ticket-classifier", { default: model });
28
+ await client.chat.completions.create({ model, messages: [] });
29
+ }, { unit: "answer" })
30
+ );
31
+
32
+ recordOutcome("ticket-classifier", {
33
+ model,
34
+ taskCompleted: true,
35
+ feedbackScore: 1,
36
+ turnsToResolution: 2,
37
+ escalated: false,
38
+ });
34
39
  });
35
40
  ```
36
41
 
42
+ Use `withContext({ sessionId, tags }, fn)`, `withSession(sessionId, fn)`, or
43
+ `withTags(tags, fn)` for request and job identity. These callback scopes follow
44
+ Node's asynchronous execution and isolate concurrent jobs. Legacy
45
+ `setSession()` and `setTags()` remain available inside an active Metergraph
46
+ scope, but warn and do nothing when called outside one. Use `setDefaultTags()`
47
+ only for deliberate process-wide tags; sessions are always execution-scoped.
48
+
37
49
  ## Vercel AI SDK
38
50
 
39
51
  Use Metergraph as language-model middleware. It records each actual provider
@@ -47,7 +59,7 @@ import * as mg from "metergraph";
47
59
 
48
60
  const model = wrapLanguageModel({
49
61
  model: openai("gpt-5.6-luna"),
50
- middleware: mg.vercelAISDKMiddleware(),
62
+ middleware: mg.vercelAISDKMiddleware({ repository: "owner/repository" }),
51
63
  });
52
64
 
53
65
  const result = await mg.trace("support-answer", () =>
@@ -65,6 +77,19 @@ for server-side pricing. Provider options, abort signals, and transport headers
65
77
  are never serialized. Calls outside `trace()` remain valid one-span traces;
66
78
  wrap a multi-call workflow in `trace()` to group its spans.
67
79
 
80
+ `vercelAISDKMiddleware()` initializes Metergraph itself, so the standard
81
+ integration needs only the middleware call. Pass any `init()` options there,
82
+ as shown above, or omit them when configuration comes from environment
83
+ variables. Applications that initialize Metergraph centrally may continue to
84
+ call `init()` first and then create the middleware without initialization
85
+ options.
86
+
87
+ Applications with several providers should use the [examples
88
+ chooser](../examples/README.md): apply MeterGraph once through the AI SDK
89
+ provider registry, or wrap the controlled exit of a custom factory the
90
+ application already has. The separate examples mark original application code
91
+ and every MeterGraph addition.
92
+
68
93
  | Vercel AI SDK | Metergraph middleware | Node.js |
69
94
  |---|---|---|
70
95
  | 5 | `vercelAISDKMiddleware({ aiSdkVersion: 5 })` | 18+ |
@@ -86,20 +111,31 @@ required and throws if missing so a caller error surfaces immediately
86
111
  instead of an `undefined` model reaching a provider call.
87
112
 
88
113
  Set `METERGRAPH_APP_TOKEN`; `METERGRAPH_INGEST_URL` is only needed to override
89
- the hosted HTTPS endpoint. SDK 0.4 automatically reads the GitHub `origin` on
90
- first initialization and creates `.metergraph/config.json` at the repository
91
- root if absent. Commit this non-secret file so production can use
92
- repository-aware ingest without Git metadata. Existing config is authoritative
93
- and never overwritten; when discovery or creation is unavailable, the SDK
94
- continues with protocol v1. SDK 0.4 captures the scrubbed provider request and a
114
+ the hosted HTTPS endpoint. Repository identity enables repository-level
115
+ attribution and [MeterGraph Bot](https://github.com/apps/metergraph). Choose any
116
+ one of these options; each is sufficient on its own:
117
+
118
+ - Pass `{ repository: "owner/repository" }` to `mg.init()`.
119
+ - Set `METERGRAPH_REPOSITORY=owner/repository` in the environment.
120
+ - Store the identity with the source code in `.metergraph/config.json`:
121
+
122
+ ```json
123
+ {"repository":"owner/repository"}
124
+ ```
125
+
126
+ Resolution order is the explicit option, environment variable, then
127
+ configuration file. The SDK treats the file as read-only. Without repository
128
+ identity, it warns once and continues capture without repository attribution.
129
+ Metergraph captures the scrubbed provider request and a
95
130
  normalized response envelope, including assistant content and tool calls, by
96
131
  default. Provider credentials and transport headers are removed. Request and
97
- response are each limited to 100 KiB of UTF-8 with an explicit truncation
98
- marker. Set `METERGRAPH_CAPTURE_TEXT=0`, initialize with
99
- `captureText: false`, or set `captureText: false` on an individual `route()` or
100
- `trace()` to opt out for sensitive operations. The public open-source server
101
- still discards content; hosted workspaces retain it under their metadata
102
- retention period.
132
+ response are each limited to 1 MiB of UTF-8 by default with an explicit
133
+ truncation marker. Set `METERGRAPH_TEXT_MAX_BYTES` or initialize with
134
+ `textMaxBytes` to raise the per-field limit. Set `METERGRAPH_CAPTURE_TEXT=0`,
135
+ initialize with `captureText: false`, or set `captureText: false` on an
136
+ individual `route()` or `trace()` to opt out for sensitive operations. The
137
+ public open-source server still discards content; hosted workspaces retain it
138
+ under their metadata retention period.
103
139
 
104
140
  `trace(name, fn, { traceId, parentSpanId, captureText })` groups calls into a
105
141
  logical trace using `AsyncLocalStorage`. Nested traces reuse the active trace
@@ -107,7 +143,7 @@ unless given a different trace ID. Calls outside a trace become one-span
107
143
  traces. Manual IDs can join work across process boundaries; automatic W3C HTTP
108
144
  propagation is not included.
109
145
 
110
- Actual wire batches never exceed 512 KiB after optional gzip.
146
+ Actual wire batches never exceed 4 MiB after optional gzip.
111
147
  Long-running Node processes use an unref'd
112
148
  background timer. On Workers or Vercel, call
113
149
  `bindWaitUntil(ctx)` once per request. On Lambda, use `wrapHandler(handler)`
@@ -173,11 +209,14 @@ Instrument this codebase's LLM API costs with the `metergraph` npm package
173
209
  then wrap every new OpenAI(), new Anthropic(), and new GoogleGenAI()
174
210
  construction in place, e.g. const client = mg.wrap(new OpenAI()) after
175
211
  import * as mg from "metergraph". wrap() returns the same client and
176
- initializes itself from the environment: METERGRAPH_APP_TOKEN is required
177
- (capture is silently off without it) and METERGRAPH_INGEST_URL is only for
178
- self-hosted servers. Add both to .env.example, and never commit a real token.
179
- SDK 0.4 captures scrubbed provider requests and normalized responses by
180
- default for the hosted dashboard; use METERGRAPH_CAPTURE_TEXT=0 or
212
+ initializes itself from the environment. Before wrapping, call
213
+ mg.init({ repository: "owner/repository" }) using the actual GitHub owner and
214
+ repository name. METERGRAPH_APP_TOKEN is required; the SDK warns and disables
215
+ capture when it is missing. METERGRAPH_INGEST_URL is only for self-hosted
216
+ servers. Document variable names with placeholders in .env.example, and put
217
+ real values only in deployment configuration. Metergraph captures scrubbed
218
+ provider requests and normalized responses by default for the hosted dashboard;
219
+ use METERGRAPH_CAPTURE_TEXT=0 or
181
220
  captureText: false around sensitive operations. Provider credentials and
182
221
  transport headers must never be captured. Capture is fail-open, so do not
183
222
  change call sites, arguments, or error handling; async and streaming work
@@ -1,3 +1,8 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.BatchFirstIneligibleError = void 0;
4
+ exports.runBatchFirst = runBatchFirst;
5
+ exports.batchFirst = batchFirst;
1
6
  /**
2
7
  * Explicit, opt-in batch-first execution: submit one request through a
3
8
  * provider's Batch API, wait a caller-selected deadline, and fall back to
@@ -14,7 +19,7 @@
14
19
  * arrives after the fallback already won is never returned, never
15
20
  * executed, and never mutates an already-resolved result.
16
21
  */
17
- import { createAnthropicBatchAdapter, createGoogleBatchAdapter, createOpenAIBatchAdapter, } from "./provider-batch.js";
22
+ const provider_batch_js_1 = require("./provider-batch.js");
18
23
  function realClock() {
19
24
  return {
20
25
  setTimeout: (handler, ms) => setTimeout(handler, ms),
@@ -25,8 +30,9 @@ function realClock() {
25
30
  * not eligible for batch-first execution — streaming, tools without
26
31
  * acknowledgement, a missing/false acceptDuplicateProviderExecution, or
27
32
  * an adapter-specific ineligibility. */
28
- export class BatchFirstIneligibleError extends Error {
33
+ class BatchFirstIneligibleError extends Error {
29
34
  }
35
+ exports.BatchFirstIneligibleError = BatchFirstIneligibleError;
30
36
  function hasTools(request) {
31
37
  return Array.isArray(request.tools) && request.tools.length > 0;
32
38
  }
@@ -53,7 +59,7 @@ const DEFAULT_POLL_INTERVAL_MS = 2_000;
53
59
  * fake-clock tests can drive it directly, and used internally by the
54
60
  * public, provider-explicit batchFirst() below.
55
61
  */
56
- export async function runBatchFirst(adapter, request, policy, testControls) {
62
+ async function runBatchFirst(adapter, request, policy, testControls) {
57
63
  validate(request, policy);
58
64
  const eligibility = adapter.eligibility(request);
59
65
  if (!eligibility.eligible) {
@@ -186,13 +192,13 @@ export async function runBatchFirst(adapter, request, policy, testControls) {
186
192
  }
187
193
  function resolveAdapter(client, provider) {
188
194
  if (provider === "openai") {
189
- return createOpenAIBatchAdapter(client);
195
+ return (0, provider_batch_js_1.createOpenAIBatchAdapter)(client);
190
196
  }
191
197
  if (provider === "anthropic") {
192
- return createAnthropicBatchAdapter(client);
198
+ return (0, provider_batch_js_1.createAnthropicBatchAdapter)(client);
193
199
  }
194
200
  if (provider === "google") {
195
- return createGoogleBatchAdapter(client);
201
+ return (0, provider_batch_js_1.createGoogleBatchAdapter)(client);
196
202
  }
197
203
  throw new BatchFirstIneligibleError(`batchFirst() has no adapter for provider "${provider}" yet`);
198
204
  }
@@ -201,7 +207,7 @@ function resolveAdapter(client, provider) {
201
207
  * the client instance — the caller states the provider, matching wrap()'s
202
208
  * own explicit-provider option.
203
209
  */
204
- export async function batchFirst(client, provider, request, policy) {
210
+ async function batchFirst(client, provider, request, policy) {
205
211
  const adapter = resolveAdapter(client, provider);
206
212
  return runBatchFirst(adapter, request, policy);
207
213
  }
package/dist/capture.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { type CaptureContext } from "./context.js";
2
2
  import type { Transport } from "./transport.js";
3
+ export declare const DEFAULT_TEXT_MAX_BYTES: number;
3
4
  export interface RuntimeOptions {
4
5
  captureText: boolean;
5
6
  redact?: (text: string, kind: "request" | "response") => string;
package/dist/capture.js CHANGED
@@ -1,7 +1,12 @@
1
- import { randomBytes } from "node:crypto";
2
- import { contextSnapshot } from "./context.js";
3
- import { scrub, templateHash } from "./template.js";
4
- import { SDK_VERSION } from "./version.js";
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.CaptureRuntime = exports.DEFAULT_TEXT_MAX_BYTES = void 0;
4
+ exports.chunkText = chunkText;
5
+ const node_crypto_1 = require("node:crypto");
6
+ const context_js_1 = require("./context.js");
7
+ const template_js_1 = require("./template.js");
8
+ const version_js_1 = require("./version.js");
9
+ exports.DEFAULT_TEXT_MAX_BYTES = 1024 * 1024;
5
10
  function get(value, key) {
6
11
  return value && typeof value === "object" ? value[key] : undefined;
7
12
  }
@@ -94,7 +99,7 @@ function responseText(response) {
94
99
  }
95
100
  return undefined;
96
101
  }
97
- export function chunkText(chunk) {
102
+ function chunkText(chunk) {
98
103
  const delta = get(first(get(chunk, "choices")), "delta") ?? get(chunk, "delta");
99
104
  if (typeof delta === "string" && get(chunk, "type") === "text-delta")
100
105
  return delta;
@@ -108,6 +113,43 @@ function stopReason(response) {
108
113
  const normalized = get(value, "unified") ?? get(value, "raw") ?? value;
109
114
  return normalized == null ? undefined : String(normalized);
110
115
  }
116
+ function normalizeFinishReason(value) {
117
+ const normalized = value.trim().toLowerCase().replace(/[\s_]+/g, "-");
118
+ if (["stop", "end-turn", "stop-sequence", "completed", "succeeded"].includes(normalized)) {
119
+ return "stop";
120
+ }
121
+ if (["length", "max-tokens", "max-output-tokens"].includes(normalized))
122
+ return "length";
123
+ if (["content-filter", "safety", "blocked"].includes(normalized))
124
+ return "content-filter";
125
+ if (["tool-calls", "tool-use", "function-call"].includes(normalized))
126
+ return "tool-calls";
127
+ if (["error", "failed"].includes(normalized))
128
+ return "error";
129
+ if (["other", "unknown"].includes(normalized))
130
+ return "other";
131
+ return normalized;
132
+ }
133
+ function finishReasonDetails(response) {
134
+ const responseStatus = get(response, "status");
135
+ const incompleteReason = responseStatus === "incomplete"
136
+ ? get(get(response, "incomplete_details"), "reason")
137
+ : undefined;
138
+ const value = get(response, "stop_reason") ?? incompleteReason ?? responseStatus
139
+ ?? get(response, "finishReason") ?? get(response, "finish_reason")
140
+ ?? get(first(get(response, "choices")), "finish_reason");
141
+ const unified = get(value, "unified");
142
+ const rawValue = get(value, "raw") ?? (unified === undefined ? value : undefined);
143
+ const source = unified ?? rawValue;
144
+ if (source == null)
145
+ return {};
146
+ const finishReason = normalizeFinishReason(String(source));
147
+ const raw = rawValue == null ? undefined : String(rawValue);
148
+ return {
149
+ finishReason,
150
+ finishReasonRaw: raw !== undefined && raw !== finishReason ? raw : undefined,
151
+ };
152
+ }
111
153
  function toolNames(request) {
112
154
  if (!Array.isArray(request.tools))
113
155
  return undefined;
@@ -126,7 +168,7 @@ function toolArgument(value) {
126
168
  return value;
127
169
  }
128
170
  }
129
- return scrub(value);
171
+ return (0, template_js_1.scrub)(value);
130
172
  }
131
173
  function toolEvents(request, response, streamChunks = []) {
132
174
  const calls = new Map();
@@ -297,7 +339,7 @@ function toolEvents(request, response, streamChunks = []) {
297
339
  arguments: input && typeof input === "object"
298
340
  && Object.keys(input).length === 0
299
341
  ? ""
300
- : JSON.stringify(scrub(input ?? {})),
342
+ : JSON.stringify((0, template_js_1.scrub)(input ?? {})),
301
343
  });
302
344
  }
303
345
  }
@@ -327,25 +369,25 @@ function responseContent(response, aggregate) {
327
369
  return aggregate;
328
370
  const direct = get(response, "output_text") ?? get(response, "text");
329
371
  if (direct !== undefined)
330
- return scrub(direct);
372
+ return (0, template_js_1.scrub)(direct);
331
373
  const message = get(first(get(response, "choices")), "message");
332
374
  const content = get(message, "content");
333
375
  if (content !== undefined)
334
- return scrub(content);
376
+ return (0, template_js_1.scrub)(content);
335
377
  const parsed = get(message, "parsed");
336
378
  if (parsed !== undefined)
337
- return scrub(parsed);
379
+ return (0, template_js_1.scrub)(parsed);
338
380
  const normalizedText = responseText(response);
339
381
  if (normalizedText !== undefined)
340
382
  return normalizedText;
341
383
  const blocks = get(response, "content");
342
384
  if (blocks !== undefined)
343
- return scrub(blocks);
385
+ return (0, template_js_1.scrub)(blocks);
344
386
  const output = get(response, "output");
345
387
  if (output !== undefined)
346
- return scrub(output);
388
+ return (0, template_js_1.scrub)(output);
347
389
  const candidates = get(response, "candidates");
348
- return candidates === undefined ? undefined : scrub(candidates);
390
+ return candidates === undefined ? undefined : (0, template_js_1.scrub)(candidates);
349
391
  }
350
392
  function responseEnvelope(response, aggregate, tools, error, status) {
351
393
  const responseMetadata = get(response, "response");
@@ -369,12 +411,9 @@ function responseEnvelope(response, aggregate, tools, error, status) {
369
411
  return Object.fromEntries(Object.entries(envelope).filter(([, value]) => value !== undefined));
370
412
  }
371
413
  const SDK_DIR = (() => {
372
- try {
373
- return new URL(".", import.meta.url).pathname;
374
- }
375
- catch {
376
- return "metergraph-sdk-dir-unavailable";
377
- }
414
+ const frame = new Error().stack?.split("\n")[1] ?? "";
415
+ const match = frame.match(/^\s*at\s+(?:.*?\s+\()?(.+?)[/\\][^/\\:]+:\d+:\d+\)?$/);
416
+ return match?.[1]?.replace(/^file:\/\//, "") ?? "metergraph-sdk-dir-unavailable";
378
417
  })();
379
418
  function frames(stack, appRoot, skip, repoRoot) {
380
419
  if (!stack)
@@ -405,14 +444,14 @@ function frames(stack, appRoot, skip, repoRoot) {
405
444
  }
406
445
  return result;
407
446
  }
408
- export class CaptureRuntime {
447
+ class CaptureRuntime {
409
448
  transport;
410
449
  options;
411
450
  constructor(transport, options) {
412
451
  this.transport = transport;
413
452
  this.options = options;
414
453
  }
415
- start(provider, endpoint, request, stack, context = contextSnapshot()) {
454
+ start(provider, endpoint, request, stack, context = (0, context_js_1.contextSnapshot)()) {
416
455
  return {
417
456
  provider,
418
457
  endpoint,
@@ -421,8 +460,8 @@ export class CaptureRuntime {
421
460
  started: performance.now(),
422
461
  ts: new Date().toISOString(),
423
462
  frames: frames(stack, this.options.appRoot, this.options.skipFrames, this.options.repoRoot),
424
- traceId: context.traceId ?? randomBytes(16).toString("hex"),
425
- spanId: randomBytes(8).toString("hex"),
463
+ traceId: context.traceId ?? (0, node_crypto_1.randomBytes)(16).toString("hex"),
464
+ spanId: (0, node_crypto_1.randomBytes)(8).toString("hex"),
426
465
  parentSpanId: context.parentSpanId,
427
466
  traceName: context.traceName ?? context.route ?? context.funcName
428
467
  ?? endpoint,
@@ -456,9 +495,13 @@ export class CaptureRuntime {
456
495
  }
457
496
  return { value: `${clipped}${marker}`, truncated: true };
458
497
  };
459
- const request = text(JSON.stringify(scrub(state.request)), "request");
460
- const fullTools = toolEvents(scrub(state.request), response, extra.responseChunks);
498
+ const request = text(JSON.stringify((0, template_js_1.scrub)(state.request)), "request");
499
+ const fullTools = toolEvents((0, template_js_1.scrub)(state.request), response, extra.responseChunks);
461
500
  const status = extra.status ?? (extra.error ? "error" : stopReason(response) ?? "success");
501
+ const { finishReason, finishReasonRaw } = finishReasonDetails(response);
502
+ const statusCode = extra.error || extra.status === "error" || finishReason === "error"
503
+ ? "error"
504
+ : "unset";
462
505
  const output = text(JSON.stringify(responseEnvelope(response, extra.responseText, fullTools, extra.error, status)), "response");
463
506
  let toolTruncated = false;
464
507
  let persistedTools;
@@ -497,13 +540,16 @@ export class CaptureRuntime {
497
540
  ...usage(response),
498
541
  latency_ms: Math.round(performance.now() - state.started),
499
542
  status,
543
+ status_code: statusCode,
544
+ finish_reason: finishReason,
545
+ finish_reason_raw: finishReasonRaw,
500
546
  session_id: state.context.sessionId,
501
547
  conversation_id: state.context.sessionId,
502
548
  trace_id: state.traceId,
503
549
  span_id: state.spanId,
504
550
  parent_span_id: state.parentSpanId,
505
551
  trace_name: state.traceName,
506
- template_hash: templateHash(state.request),
552
+ template_hash: (0, template_js_1.templateHash)(state.request),
507
553
  unit_name: state.context.unitName,
508
554
  unit_count: state.context.unitCount,
509
555
  tool_calls: fullTools ? persistedTools : toolNames(state.request),
@@ -528,11 +574,12 @@ export class CaptureRuntime {
528
574
  frames_json: state.frames,
529
575
  tags: state.context.tags,
530
576
  environment: this.options.environment,
531
- error: Boolean(extra.error),
577
+ error: statusCode === "error",
532
578
  error_type: extra.error instanceof Error ? extra.error.name : undefined,
533
579
  sdk: "js",
534
- sdk_version: SDK_VERSION,
580
+ sdk_version: version_js_1.SDK_VERSION,
535
581
  runtime: typeof process === "undefined" ? "edge" : `node-${process.versions.node}`,
536
582
  });
537
583
  }
538
584
  }
585
+ exports.CaptureRuntime = CaptureRuntime;
package/dist/config.js CHANGED
@@ -1,4 +1,8 @@
1
- import { FailureLogger } from "./failure-log.js";
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.ConfigPoller = void 0;
4
+ exports.chooseModel = chooseModel;
5
+ const failure_log_js_1 = require("./failure-log.js");
2
6
  function bucket(value) {
3
7
  let hash = 0xcbf29ce484222325n;
4
8
  for (const byte of new TextEncoder().encode(value)) {
@@ -7,7 +11,7 @@ function bucket(value) {
7
11
  }
8
12
  return Number(hash) / 2 ** 64 * 100;
9
13
  }
10
- export function chooseModel(route, fallback, sessionKey, config) {
14
+ function chooseModel(route, fallback, sessionKey, config) {
11
15
  if (!config || config.enabled === false)
12
16
  return fallback;
13
17
  const incumbent = config.incumbent_model ?? fallback;
@@ -18,7 +22,7 @@ export function chooseModel(route, fallback, sessionKey, config) {
18
22
  const seed = `${route}:${config.version ?? ""}:${config.salt ?? ""}:${sessionKey}`;
19
23
  return bucket(seed) < percentage ? challenger : incumbent;
20
24
  }
21
- export class ConfigPoller {
25
+ class ConfigPoller {
22
26
  token;
23
27
  baseUrl;
24
28
  pollMs;
@@ -28,7 +32,7 @@ export class ConfigPoller {
28
32
  lastSuccess = 0;
29
33
  timer;
30
34
  stopped = false;
31
- failureLog = new FailureLogger();
35
+ failureLog = new failure_log_js_1.FailureLogger();
32
36
  /** 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
37
  ready;
34
38
  constructor(token, baseUrl, pollMs = 30_000, hardTtlMs = 120_000) {
@@ -86,3 +90,4 @@ export class ConfigPoller {
86
90
  clearInterval(this.timer);
87
91
  }
88
92
  }
93
+ exports.ConfigPoller = ConfigPoller;
package/dist/context.d.ts CHANGED
@@ -21,8 +21,16 @@ export interface TraceOptions {
21
21
  parentSpanId?: string;
22
22
  captureText?: boolean;
23
23
  }
24
+ export interface ContextOptions {
25
+ sessionId?: string;
26
+ tags?: Record<string, unknown>;
27
+ }
24
28
  export declare function contextSnapshot(): CaptureContext;
25
29
  export declare function runWithContext<T>(context: CaptureContext, fn: () => T): T;
30
+ export declare function withContext<T>(options: ContextOptions, fn: () => T): T;
31
+ export declare function withSession<T>(sessionId: string, fn: () => T): T;
32
+ export declare function withTags<T>(tags: Record<string, unknown>, fn: () => T): T;
33
+ export declare function setDefaultTags(tags: Record<string, unknown>): void;
26
34
  export declare function route<T>(name: string, fn: () => T | Promise<T>, options?: RouteOptions): Promise<T>;
27
35
  export declare function trace<T>(name: string, fn: () => T | Promise<T>, options?: TraceOptions): T | Promise<T>;
28
36
  export declare function setSession(sessionId?: string): void;
package/dist/context.js CHANGED
@@ -1,15 +1,50 @@
1
- import { AsyncLocalStorage } from "node:async_hooks";
2
- import { randomBytes } from "node:crypto";
3
- const storage = new AsyncLocalStorage();
4
- let ambient = { tags: {} };
5
- export function contextSnapshot() {
6
- const value = storage.getStore() ?? ambient;
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.contextSnapshot = contextSnapshot;
4
+ exports.runWithContext = runWithContext;
5
+ exports.withContext = withContext;
6
+ exports.withSession = withSession;
7
+ exports.withTags = withTags;
8
+ exports.setDefaultTags = setDefaultTags;
9
+ exports.route = route;
10
+ exports.trace = trace;
11
+ exports.setSession = setSession;
12
+ exports.setTags = setTags;
13
+ const node_async_hooks_1 = require("node:async_hooks");
14
+ const node_crypto_1 = require("node:crypto");
15
+ const storage = new node_async_hooks_1.AsyncLocalStorage();
16
+ let defaultTags = {};
17
+ let warnedSessionOutsideScope = false;
18
+ let warnedTagsOutsideScope = false;
19
+ function normalizeTags(tags) {
20
+ return Object.fromEntries(Object.entries(tags).map(([key, value]) => [key, String(value)]));
21
+ }
22
+ function contextSnapshot() {
23
+ const value = storage.getStore() ?? { tags: defaultTags };
7
24
  return { ...value, tags: { ...value.tags } };
8
25
  }
9
- export function runWithContext(context, fn) {
26
+ function runWithContext(context, fn) {
10
27
  return storage.run(context, fn);
11
28
  }
12
- export async function route(name, fn, options = {}) {
29
+ function withContext(options, fn) {
30
+ const parent = contextSnapshot();
31
+ const child = {
32
+ ...parent,
33
+ sessionId: options.sessionId ?? parent.sessionId,
34
+ tags: { ...parent.tags, ...normalizeTags(options.tags ?? {}) },
35
+ };
36
+ return storage.run(child, fn);
37
+ }
38
+ function withSession(sessionId, fn) {
39
+ return withContext({ sessionId }, fn);
40
+ }
41
+ function withTags(tags, fn) {
42
+ return withContext({ tags }, fn);
43
+ }
44
+ function setDefaultTags(tags) {
45
+ defaultTags = normalizeTags(tags);
46
+ }
47
+ async function route(name, fn, options = {}) {
13
48
  const parent = contextSnapshot();
14
49
  const child = {
15
50
  ...parent,
@@ -24,32 +59,39 @@ export async function route(name, fn, options = {}) {
24
59
  };
25
60
  return storage.run(child, fn);
26
61
  }
27
- export function trace(name, fn, options = {}) {
62
+ function trace(name, fn, options = {}) {
28
63
  const parent = contextSnapshot();
29
64
  const requested = options.traceId?.trim();
30
65
  const reuse = parent.traceId !== undefined
31
66
  && (requested === undefined || requested === parent.traceId);
32
67
  const child = {
33
68
  ...parent,
34
- traceId: reuse ? parent.traceId : requested || randomBytes(16).toString("hex"),
69
+ traceId: reuse ? parent.traceId : requested || (0, node_crypto_1.randomBytes)(16).toString("hex"),
35
70
  traceName: reuse ? parent.traceName : String(name),
36
71
  parentSpanId: options.parentSpanId ?? (reuse ? parent.parentSpanId : undefined),
37
72
  captureText: options.captureText ?? parent.captureText,
38
73
  };
39
74
  return storage.run(child, fn);
40
75
  }
41
- export function setSession(sessionId) {
76
+ function setSession(sessionId) {
42
77
  const store = storage.getStore();
43
- if (store)
44
- store.sessionId = sessionId;
45
- else
46
- ambient = { ...ambient, sessionId };
78
+ if (!store) {
79
+ if (!warnedSessionOutsideScope) {
80
+ warnedSessionOutsideScope = true;
81
+ console.warn("Metergraph setSession() requires an active Metergraph context; use withSession() or withContext().");
82
+ }
83
+ return;
84
+ }
85
+ storage.enterWith({ ...store, sessionId, tags: { ...store.tags } });
47
86
  }
48
- export function setTags(tags) {
49
- const normalized = Object.fromEntries(Object.entries(tags).map(([key, value]) => [key, String(value)]));
87
+ function setTags(tags) {
50
88
  const store = storage.getStore();
51
- if (store)
52
- store.tags = { ...store.tags, ...normalized };
53
- else
54
- ambient = { ...ambient, tags: { ...ambient.tags, ...normalized } };
89
+ if (!store) {
90
+ if (!warnedTagsOutsideScope) {
91
+ warnedTagsOutsideScope = true;
92
+ console.warn("Metergraph setTags() requires an active Metergraph context; use withTags() or withContext().");
93
+ }
94
+ return;
95
+ }
96
+ storage.enterWith({ ...store, tags: { ...store.tags, ...normalizeTags(tags) } });
55
97
  }
@@ -1,9 +1,12 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.FailureLogger = void 0;
1
4
  /**
2
5
  * Rate-limited failure logging. Logs the first occurrence of a failure kind
3
6
  * immediately, then suppresses repeats within a quiet window and reports how
4
7
  * many were suppressed on the next log line for that kind.
5
8
  */
6
- export class FailureLogger {
9
+ class FailureLogger {
7
10
  quietMs;
8
11
  clock;
9
12
  sink;
@@ -30,3 +33,4 @@ export class FailureLogger {
30
33
  this.lastLogged.set(kind, now);
31
34
  }
32
35
  }
36
+ exports.FailureLogger = FailureLogger;