metergraph 0.4.0 → 0.6.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
@@ -5,14 +5,18 @@ 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, setSession } 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
22
  setSession("ticket-123");
@@ -47,7 +51,7 @@ import * as mg from "metergraph";
47
51
 
48
52
  const model = wrapLanguageModel({
49
53
  model: openai("gpt-5.6-luna"),
50
- middleware: mg.vercelAISDKMiddleware(),
54
+ middleware: mg.vercelAISDKMiddleware({ repository: "owner/repository" }),
51
55
  });
52
56
 
53
57
  const result = await mg.trace("support-answer", () =>
@@ -65,6 +69,19 @@ for server-side pricing. Provider options, abort signals, and transport headers
65
69
  are never serialized. Calls outside `trace()` remain valid one-span traces;
66
70
  wrap a multi-call workflow in `trace()` to group its spans.
67
71
 
72
+ `vercelAISDKMiddleware()` initializes Metergraph itself, so the standard
73
+ integration needs only the middleware call. Pass any `init()` options there,
74
+ as shown above, or omit them when configuration comes from environment
75
+ variables. Applications that initialize Metergraph centrally may continue to
76
+ call `init()` first and then create the middleware without initialization
77
+ options.
78
+
79
+ Applications with several providers should use the [examples
80
+ chooser](../examples/README.md): apply MeterGraph once through the AI SDK
81
+ provider registry, or wrap the controlled exit of a custom factory the
82
+ application already has. The separate examples mark original application code
83
+ and every MeterGraph addition.
84
+
68
85
  | Vercel AI SDK | Metergraph middleware | Node.js |
69
86
  |---|---|---|
70
87
  | 5 | `vercelAISDKMiddleware({ aiSdkVersion: 5 })` | 18+ |
@@ -86,12 +103,22 @@ required and throws if missing so a caller error surfaces immediately
86
103
  instead of an `undefined` model reaching a provider call.
87
104
 
88
105
  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
106
+ the hosted HTTPS endpoint. Repository identity enables repository-level
107
+ attribution and [MeterGraph Bot](https://github.com/apps/metergraph). Choose any
108
+ one of these options; each is sufficient on its own:
109
+
110
+ - Pass `{ repository: "owner/repository" }` to `mg.init()`.
111
+ - Set `METERGRAPH_REPOSITORY=owner/repository` in the environment.
112
+ - Store the identity with the source code in `.metergraph/config.json`:
113
+
114
+ ```json
115
+ {"repository":"owner/repository"}
116
+ ```
117
+
118
+ Resolution order is the explicit option, environment variable, then
119
+ configuration file. The SDK treats the file as read-only. Without repository
120
+ identity, it warns once and continues capture without repository attribution.
121
+ Metergraph captures the scrubbed provider request and a
95
122
  normalized response envelope, including assistant content and tool calls, by
96
123
  default. Provider credentials and transport headers are removed. Request and
97
124
  response are each limited to 100 KiB of UTF-8 with an explicit truncation
@@ -125,6 +152,43 @@ inference while iterating a wrapped `client.messages.batches.results()` result.
125
152
  Consume results inside `route()` so the asynchronous batch retains its product
126
153
  route. Job-management polls are deliberately not counted as model calls.
127
154
 
155
+ ## Batch-first execution (opt-in)
156
+
157
+ `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.
158
+
159
+ ```ts
160
+ import { batchFirst } from "metergraph";
161
+ import OpenAI from "openai";
162
+
163
+ const client = new OpenAI(); // unwrapped — batchFirst() drives it directly, not through wrap()
164
+
165
+ const outcome = await batchFirst(
166
+ client,
167
+ "openai",
168
+ { model: "gpt-5-mini", input: "Summarize this document." },
169
+ {
170
+ deadlineMs: 60_000,
171
+ acceptDuplicateProviderExecution: true, // required: a missed deadline can execute the request twice
172
+ onLateBatchSettled: (info) => {
173
+ // Fires later, asynchronously, only if a losing batch eventually
174
+ // settles. Never blocks batchFirst()'s own return, and never exposes
175
+ // the late result's content — only whether it contained a
176
+ // tool-call plan.
177
+ },
178
+ },
179
+ );
180
+
181
+ outcome.source; // "batch" | "direct"
182
+ outcome.result; // the provider response
183
+ outcome.metadata.batch_outcome; // "completed" | "failed" | "expired" | "pending_at_deadline"
184
+ ```
185
+
186
+ `provider` is `"openai" | "anthropic" | "google"`, matching `wrap()`'s own explicit-provider option — never inferred from the client instance. A request with `stream: true` is rejected before any provider call. A request carrying `tools` is rejected unless `allowDuplicateToolCallPlans: true` is also set, acknowledging that the batch result and the direct fallback are independent provider executions that may each choose a different tool-call plan. `acceptDuplicateProviderExecution` must be exactly `true` — there is no default and no environment-variable override, and a missed deadline can execute (and bill) the same request twice. Neither the batch nor the direct path executes a tool call automatically; the caller receives the tool-call plan in `outcome.result` and is responsible for executing it, exactly as with a normal (non-batch-first) provider response.
187
+
188
+ `batchFirst()` is not integrated with `wrap()`'s capture/telemetry pipeline; its result and metadata are returned directly to the caller, never enqueued for delivery. The background poll that watches a losing batch for late telemetry uses an ordinary `setTimeout`, not an unref'd one — after a deadline-triggered direct fallback it keeps the Node process alive until the batch reaches a terminal state, which can take up to 24 hours; this is currently unmitigated, so a short-lived script or CLI process should not assume it exits promptly after a fallback.
189
+
190
+ OpenAI, Anthropic, and Google Gemini all have adapters (`createOpenAIBatchAdapter`, `createAnthropicBatchAdapter`, `createGoogleBatchAdapter`), built against each provider's documented Batch API shape and covered by fake-client contract tests, but **none has been exercised against a live provider Batch API from this SDK** — treat this as a beta-quality, code-reviewed-but-not-live-verified surface.
191
+
128
192
  ## Set up with an AI coding agent
129
193
 
130
194
  Paste this into Claude Code, Codex, Cursor, or any coding agent inside the
@@ -136,11 +200,14 @@ Instrument this codebase's LLM API costs with the `metergraph` npm package
136
200
  then wrap every new OpenAI(), new Anthropic(), and new GoogleGenAI()
137
201
  construction in place, e.g. const client = mg.wrap(new OpenAI()) after
138
202
  import * as mg from "metergraph". wrap() returns the same client and
139
- initializes itself from the environment: METERGRAPH_APP_TOKEN is required
140
- (capture is silently off without it) and METERGRAPH_INGEST_URL is only for
141
- self-hosted servers. Add both to .env.example, and never commit a real token.
142
- SDK 0.4 captures scrubbed provider requests and normalized responses by
143
- default for the hosted dashboard; use METERGRAPH_CAPTURE_TEXT=0 or
203
+ initializes itself from the environment. Before wrapping, call
204
+ mg.init({ repository: "owner/repository" }) using the actual GitHub owner and
205
+ repository name. METERGRAPH_APP_TOKEN is required; the SDK warns and disables
206
+ capture when it is missing. METERGRAPH_INGEST_URL is only for self-hosted
207
+ servers. Document variable names with placeholders in .env.example, and put
208
+ real values only in deployment configuration. Metergraph captures scrubbed
209
+ provider requests and normalized responses by default for the hosted dashboard;
210
+ use METERGRAPH_CAPTURE_TEXT=0 or
144
211
  captureText: false around sensitive operations. Provider credentials and
145
212
  transport headers must never be captured. Capture is fail-open, so do not
146
213
  change call sites, arguments, or error handling; async and streaming work
@@ -0,0 +1,112 @@
1
+ /**
2
+ * Explicit, opt-in batch-first execution: submit one request through a
3
+ * provider's Batch API, wait a caller-selected deadline, and fall back to
4
+ * a single direct call if the batch hasn't finished in time. Never enabled
5
+ * by wrap()/capture defaults or by an environment variable — a caller
6
+ * reaches this only by importing and calling batchFirst() directly, and
7
+ * only after explicitly acknowledging the duplicate-execution semantic
8
+ * below.
9
+ *
10
+ * On a missed deadline, the request may execute twice against the
11
+ * provider (once via batch, once via direct) — an accepted, deliberate
12
+ * semantic, never silently avoided. What this module guarantees instead:
13
+ * exactly one direct fallback is ever issued, and a batch result that
14
+ * arrives after the fallback already won is never returned, never
15
+ * executed, and never mutates an already-resolved result.
16
+ */
17
+ import { type BatchFirstRequest, type ProviderBatchAdapter } from "./provider-batch.js";
18
+ export type { BatchFirstRequest } from "./provider-batch.js";
19
+ /** An injectable time source. Real timers by default; tests can supply a
20
+ * fake to drive the deadline deterministically, with no real waiting. */
21
+ export interface BatchFirstClock {
22
+ setTimeout(handler: () => void, ms: number): unknown;
23
+ clearTimeout(handle: unknown): void;
24
+ }
25
+ /** Reported asynchronously, after batchFirst() has already returned via the
26
+ * direct fallback, if the losing batch eventually reaches a terminal
27
+ * state. Its actual result content is never included here and never
28
+ * returned from batchFirst() — only whether it happened to contain a
29
+ * tool-call plan, which may differ from the one the direct fallback
30
+ * produced (see allowDuplicateToolCallPlans on BatchFirstPolicy). */
31
+ export interface LateBatchInfo {
32
+ outcome: "completed" | "failed" | "expired";
33
+ containedToolCallPlan: boolean;
34
+ }
35
+ export interface BatchFirstPolicy {
36
+ /** How long to wait for the batch before issuing the one direct
37
+ * fallback. Required — there is no default deadline. */
38
+ deadlineMs: number;
39
+ /**
40
+ * Required, explicit acknowledgement that a missed deadline can result
41
+ * in the same request executing twice against the provider. Must be
42
+ * exactly `true`; never read from an environment variable, and never
43
+ * defaulted.
44
+ */
45
+ acceptDuplicateProviderExecution: true;
46
+ /**
47
+ * Required, explicit acknowledgement for a request that includes
48
+ * `tools`: the batch result and the direct fallback are two independent
49
+ * provider executions of the same prompt, and may each choose a
50
+ * DIFFERENT tool-call plan (different tool, different arguments). A
51
+ * caller whose tools have side effects must not assume the two plans
52
+ * agree. Without this flag, a request carrying `tools` is rejected
53
+ * before any provider call is made.
54
+ */
55
+ allowDuplicateToolCallPlans?: boolean;
56
+ /** Fired once, later, only when the losing batch eventually settles.
57
+ * Never blocks batchFirst()'s own return. */
58
+ onLateBatchSettled?: (info: LateBatchInfo) => void;
59
+ }
60
+ /** Non-public knobs for driving runBatchFirst()'s poll interval and time
61
+ * source from tests — deliberately kept off BatchFirstPolicy so a real
62
+ * caller of batchFirst() has no way to set them. */
63
+ interface RunBatchFirstTestControls {
64
+ /** How often to re-check batch status while waiting. Default 2000ms. */
65
+ pollIntervalMs?: number;
66
+ /** Injectable time source — see BatchFirstClock. */
67
+ clock?: BatchFirstClock;
68
+ }
69
+ export type BatchFirstSource = "batch" | "direct";
70
+ export interface BatchFirstMetadata {
71
+ execution_mode: "batch_first";
72
+ deadline_ms: number;
73
+ /** Wall-clock time from submission to the canonical result settling. */
74
+ batch_wait_ms: number;
75
+ /** The batch's own status as of when batchFirst() returned — not its
76
+ * eventual status if that differs (see onLateBatchSettled). */
77
+ batch_outcome: "completed" | "failed" | "expired" | "pending_at_deadline";
78
+ canonical_result: BatchFirstSource;
79
+ duplicate_provider_execution: boolean;
80
+ /** Always false when canonical_result is "batch" (no lateness is
81
+ * possible — the batch IS the canonical result). When
82
+ * canonical_result is "direct", this reflects what was known AT THE
83
+ * MOMENT batchFirst() returned, which is always false: a completion
84
+ * confirmed later only reaches the caller through
85
+ * onLateBatchSettled, never by mutating this object. */
86
+ late_batch_completed: boolean;
87
+ late_batch_contained_tool_call_plan: boolean;
88
+ }
89
+ export interface BatchFirstResult<TResult = unknown> {
90
+ source: BatchFirstSource;
91
+ result: TResult;
92
+ metadata: BatchFirstMetadata;
93
+ }
94
+ /** Thrown before any provider call when a request/policy combination is
95
+ * not eligible for batch-first execution — streaming, tools without
96
+ * acknowledgement, a missing/false acceptDuplicateProviderExecution, or
97
+ * an adapter-specific ineligibility. */
98
+ export declare class BatchFirstIneligibleError extends Error {
99
+ }
100
+ /**
101
+ * The adapter-injected core state machine — exported so fake-adapter,
102
+ * fake-clock tests can drive it directly, and used internally by the
103
+ * public, provider-explicit batchFirst() below.
104
+ */
105
+ export declare function runBatchFirst<TResult>(adapter: ProviderBatchAdapter<TResult>, request: BatchFirstRequest, policy: BatchFirstPolicy, testControls?: RunBatchFirstTestControls): Promise<BatchFirstResult<TResult>>;
106
+ export type BatchFirstProvider = "openai" | "anthropic" | "google";
107
+ /**
108
+ * Explicit, provider-specific batch-first execution. Never inferred from
109
+ * the client instance — the caller states the provider, matching wrap()'s
110
+ * own explicit-provider option.
111
+ */
112
+ export declare function batchFirst<TResult = unknown>(client: unknown, provider: BatchFirstProvider, request: BatchFirstRequest, policy: BatchFirstPolicy): Promise<BatchFirstResult<TResult>>;
@@ -0,0 +1,213 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.BatchFirstIneligibleError = void 0;
4
+ exports.runBatchFirst = runBatchFirst;
5
+ exports.batchFirst = batchFirst;
6
+ /**
7
+ * Explicit, opt-in batch-first execution: submit one request through a
8
+ * provider's Batch API, wait a caller-selected deadline, and fall back to
9
+ * a single direct call if the batch hasn't finished in time. Never enabled
10
+ * by wrap()/capture defaults or by an environment variable — a caller
11
+ * reaches this only by importing and calling batchFirst() directly, and
12
+ * only after explicitly acknowledging the duplicate-execution semantic
13
+ * below.
14
+ *
15
+ * On a missed deadline, the request may execute twice against the
16
+ * provider (once via batch, once via direct) — an accepted, deliberate
17
+ * semantic, never silently avoided. What this module guarantees instead:
18
+ * exactly one direct fallback is ever issued, and a batch result that
19
+ * arrives after the fallback already won is never returned, never
20
+ * executed, and never mutates an already-resolved result.
21
+ */
22
+ const provider_batch_js_1 = require("./provider-batch.js");
23
+ function realClock() {
24
+ return {
25
+ setTimeout: (handler, ms) => setTimeout(handler, ms),
26
+ clearTimeout: (handle) => clearTimeout(handle),
27
+ };
28
+ }
29
+ /** Thrown before any provider call when a request/policy combination is
30
+ * not eligible for batch-first execution — streaming, tools without
31
+ * acknowledgement, a missing/false acceptDuplicateProviderExecution, or
32
+ * an adapter-specific ineligibility. */
33
+ class BatchFirstIneligibleError extends Error {
34
+ }
35
+ exports.BatchFirstIneligibleError = BatchFirstIneligibleError;
36
+ function hasTools(request) {
37
+ return Array.isArray(request.tools) && request.tools.length > 0;
38
+ }
39
+ function validate(request, policy) {
40
+ if (policy.acceptDuplicateProviderExecution !== true) {
41
+ throw new BatchFirstIneligibleError("batchFirst() requires policy.acceptDuplicateProviderExecution: true — "
42
+ + "a missed deadline can execute the request twice against the provider");
43
+ }
44
+ if (!Number.isFinite(policy.deadlineMs) || policy.deadlineMs <= 0) {
45
+ throw new BatchFirstIneligibleError("batchFirst() requires a positive policy.deadlineMs");
46
+ }
47
+ if (request.stream === true) {
48
+ throw new BatchFirstIneligibleError("batchFirst() does not support streaming requests — streaming is direct-only");
49
+ }
50
+ if (hasTools(request) && policy.allowDuplicateToolCallPlans !== true) {
51
+ throw new BatchFirstIneligibleError("batchFirst() requires policy.allowDuplicateToolCallPlans: true for requests with "
52
+ + "tools — the batch result and the direct fallback are independent provider "
53
+ + "executions and may each choose a different tool call plan");
54
+ }
55
+ }
56
+ const DEFAULT_POLL_INTERVAL_MS = 2_000;
57
+ /**
58
+ * The adapter-injected core state machine — exported so fake-adapter,
59
+ * fake-clock tests can drive it directly, and used internally by the
60
+ * public, provider-explicit batchFirst() below.
61
+ */
62
+ async function runBatchFirst(adapter, request, policy, testControls) {
63
+ validate(request, policy);
64
+ const eligibility = adapter.eligibility(request);
65
+ if (!eligibility.eligible) {
66
+ throw new BatchFirstIneligibleError(`request is not eligible for batch-first execution: ${eligibility.reason ?? "unsupported by this adapter"}`);
67
+ }
68
+ const clock = testControls?.clock ?? realClock();
69
+ const pollIntervalMs = testControls?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
70
+ const startedAt = Date.now();
71
+ const handle = await adapter.submitOne(request);
72
+ let settleDeadline;
73
+ const deadlineSettled = new Promise((resolve) => {
74
+ settleDeadline = resolve;
75
+ });
76
+ const deadlineTimer = clock.setTimeout(() => settleDeadline?.(), policy.deadlineMs);
77
+ // Resolves at most once, and only from inside the poll loop below, the
78
+ // moment a real terminal status is observed — never resolves at all if
79
+ // the deadline wins first. Racing this directly (rather than racing the
80
+ // loop's own completion promise) means there is no "loop stopped without
81
+ // a terminal status" case to fake a result for: that case simply never
82
+ // resolves this promise, which is exactly the semantics Promise.race
83
+ // needs.
84
+ let resolveBatchTerminal;
85
+ const batchTerminalSettled = new Promise((resolve) => {
86
+ resolveBatchTerminal = resolve;
87
+ });
88
+ let stopPolling = false;
89
+ const pollUntilTerminal = (async () => {
90
+ while (!stopPolling) {
91
+ const outcome = await adapter.poll(handle);
92
+ if (outcome.status !== "pending") {
93
+ resolveBatchTerminal?.(outcome.status);
94
+ return outcome.status;
95
+ }
96
+ if (stopPolling)
97
+ return undefined;
98
+ await new Promise((resolve) => clock.setTimeout(resolve, pollIntervalMs));
99
+ }
100
+ return undefined;
101
+ })();
102
+ const winner = await Promise.race([
103
+ batchTerminalSettled.then((status) => ({ kind: "batch", status })),
104
+ deadlineSettled.then(() => ({ kind: "deadline" })),
105
+ ]);
106
+ clock.clearTimeout(deadlineTimer);
107
+ // A batch reported "completed" but whose result cannot be read (a
108
+ // missing output file, an item-level provider error, a malformed or
109
+ // missing matching line, a transient read failure) is neither a valid
110
+ // canonical batch result nor grounds to throw out of batchFirst()
111
+ // instead of the promised fallback — it is treated exactly like a batch
112
+ // that reported "failed": exactly one direct fallback, never a second
113
+ // read attempt, never surfaced as a rejection.
114
+ let unreadableCompletedBatch = false;
115
+ if (winner.kind === "batch" && winner.status === "completed") {
116
+ stopPolling = true;
117
+ try {
118
+ const { result } = await adapter.readResult(handle);
119
+ return {
120
+ source: "batch",
121
+ result,
122
+ metadata: {
123
+ execution_mode: "batch_first",
124
+ deadline_ms: policy.deadlineMs,
125
+ batch_wait_ms: Date.now() - startedAt,
126
+ batch_outcome: "completed",
127
+ canonical_result: "batch",
128
+ duplicate_provider_execution: false,
129
+ late_batch_completed: false,
130
+ late_batch_contained_tool_call_plan: false,
131
+ },
132
+ };
133
+ }
134
+ catch {
135
+ unreadableCompletedBatch = true;
136
+ }
137
+ }
138
+ // Either the deadline fired first, the batch reached a non-completed
139
+ // terminal status before the deadline, or the batch completed but its
140
+ // result could not be read — either way, issue exactly one direct
141
+ // fallback now, and never wait further (or retry a read) on the batch
142
+ // for the canonical result. Only stop the poll loop when the batch
143
+ // itself already produced a terminal status (it has nothing left to do,
144
+ // so this is a no-op) — when the DEADLINE won, deliberately leave
145
+ // polling running in the background: "keep polling only to write
146
+ // terminal telemetry" requires the loop to keep going, not stop here.
147
+ const batchOutcomeAtFallback = unreadableCompletedBatch
148
+ ? "failed"
149
+ : winner.kind === "batch"
150
+ ? winner.status
151
+ : "pending_at_deadline";
152
+ if (winner.kind === "batch")
153
+ stopPolling = true;
154
+ const directResultPromise = adapter.direct(request);
155
+ if (winner.kind === "deadline") {
156
+ // Observe the batch purely for telemetry — never read for its content
157
+ // to be returned, executed, or used to mutate the already-in-flight
158
+ // direct result.
159
+ pollUntilTerminal
160
+ .then(async (status) => {
161
+ if (status !== "completed" && status !== "failed" && status !== "expired")
162
+ return;
163
+ let containedToolCallPlan = false;
164
+ if (status === "completed") {
165
+ try {
166
+ const late = await adapter.readResult(handle);
167
+ containedToolCallPlan = late.containedToolCallPlan;
168
+ }
169
+ catch {
170
+ /* telemetry only — never thrown, never surfaced */
171
+ }
172
+ }
173
+ policy.onLateBatchSettled?.({ outcome: status, containedToolCallPlan });
174
+ })
175
+ .catch(() => { });
176
+ }
177
+ const { result } = await directResultPromise;
178
+ return {
179
+ source: "direct",
180
+ result,
181
+ metadata: {
182
+ execution_mode: "batch_first",
183
+ deadline_ms: policy.deadlineMs,
184
+ batch_wait_ms: Date.now() - startedAt,
185
+ batch_outcome: batchOutcomeAtFallback,
186
+ canonical_result: "direct",
187
+ duplicate_provider_execution: true,
188
+ late_batch_completed: false,
189
+ late_batch_contained_tool_call_plan: false,
190
+ },
191
+ };
192
+ }
193
+ function resolveAdapter(client, provider) {
194
+ if (provider === "openai") {
195
+ return (0, provider_batch_js_1.createOpenAIBatchAdapter)(client);
196
+ }
197
+ if (provider === "anthropic") {
198
+ return (0, provider_batch_js_1.createAnthropicBatchAdapter)(client);
199
+ }
200
+ if (provider === "google") {
201
+ return (0, provider_batch_js_1.createGoogleBatchAdapter)(client);
202
+ }
203
+ throw new BatchFirstIneligibleError(`batchFirst() has no adapter for provider "${provider}" yet`);
204
+ }
205
+ /**
206
+ * Explicit, provider-specific batch-first execution. Never inferred from
207
+ * the client instance — the caller states the provider, matching wrap()'s
208
+ * own explicit-provider option.
209
+ */
210
+ async function batchFirst(client, provider, request, policy) {
211
+ const adapter = resolveAdapter(client, provider);
212
+ return runBatchFirst(adapter, request, policy);
213
+ }
package/dist/capture.js CHANGED
@@ -1,7 +1,11 @@
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 = 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");
5
9
  function get(value, key) {
6
10
  return value && typeof value === "object" ? value[key] : undefined;
7
11
  }
@@ -94,7 +98,7 @@ function responseText(response) {
94
98
  }
95
99
  return undefined;
96
100
  }
97
- export function chunkText(chunk) {
101
+ function chunkText(chunk) {
98
102
  const delta = get(first(get(chunk, "choices")), "delta") ?? get(chunk, "delta");
99
103
  if (typeof delta === "string" && get(chunk, "type") === "text-delta")
100
104
  return delta;
@@ -126,7 +130,7 @@ function toolArgument(value) {
126
130
  return value;
127
131
  }
128
132
  }
129
- return scrub(value);
133
+ return (0, template_js_1.scrub)(value);
130
134
  }
131
135
  function toolEvents(request, response, streamChunks = []) {
132
136
  const calls = new Map();
@@ -297,7 +301,7 @@ function toolEvents(request, response, streamChunks = []) {
297
301
  arguments: input && typeof input === "object"
298
302
  && Object.keys(input).length === 0
299
303
  ? ""
300
- : JSON.stringify(scrub(input ?? {})),
304
+ : JSON.stringify((0, template_js_1.scrub)(input ?? {})),
301
305
  });
302
306
  }
303
307
  }
@@ -327,25 +331,25 @@ function responseContent(response, aggregate) {
327
331
  return aggregate;
328
332
  const direct = get(response, "output_text") ?? get(response, "text");
329
333
  if (direct !== undefined)
330
- return scrub(direct);
334
+ return (0, template_js_1.scrub)(direct);
331
335
  const message = get(first(get(response, "choices")), "message");
332
336
  const content = get(message, "content");
333
337
  if (content !== undefined)
334
- return scrub(content);
338
+ return (0, template_js_1.scrub)(content);
335
339
  const parsed = get(message, "parsed");
336
340
  if (parsed !== undefined)
337
- return scrub(parsed);
341
+ return (0, template_js_1.scrub)(parsed);
338
342
  const normalizedText = responseText(response);
339
343
  if (normalizedText !== undefined)
340
344
  return normalizedText;
341
345
  const blocks = get(response, "content");
342
346
  if (blocks !== undefined)
343
- return scrub(blocks);
347
+ return (0, template_js_1.scrub)(blocks);
344
348
  const output = get(response, "output");
345
349
  if (output !== undefined)
346
- return scrub(output);
350
+ return (0, template_js_1.scrub)(output);
347
351
  const candidates = get(response, "candidates");
348
- return candidates === undefined ? undefined : scrub(candidates);
352
+ return candidates === undefined ? undefined : (0, template_js_1.scrub)(candidates);
349
353
  }
350
354
  function responseEnvelope(response, aggregate, tools, error, status) {
351
355
  const responseMetadata = get(response, "response");
@@ -369,12 +373,9 @@ function responseEnvelope(response, aggregate, tools, error, status) {
369
373
  return Object.fromEntries(Object.entries(envelope).filter(([, value]) => value !== undefined));
370
374
  }
371
375
  const SDK_DIR = (() => {
372
- try {
373
- return new URL(".", import.meta.url).pathname;
374
- }
375
- catch {
376
- return "metergraph-sdk-dir-unavailable";
377
- }
376
+ const frame = new Error().stack?.split("\n")[1] ?? "";
377
+ const match = frame.match(/^\s*at\s+(?:.*?\s+\()?(.+?)[/\\][^/\\:]+:\d+:\d+\)?$/);
378
+ return match?.[1]?.replace(/^file:\/\//, "") ?? "metergraph-sdk-dir-unavailable";
378
379
  })();
379
380
  function frames(stack, appRoot, skip, repoRoot) {
380
381
  if (!stack)
@@ -405,14 +406,14 @@ function frames(stack, appRoot, skip, repoRoot) {
405
406
  }
406
407
  return result;
407
408
  }
408
- export class CaptureRuntime {
409
+ class CaptureRuntime {
409
410
  transport;
410
411
  options;
411
412
  constructor(transport, options) {
412
413
  this.transport = transport;
413
414
  this.options = options;
414
415
  }
415
- start(provider, endpoint, request, stack, context = contextSnapshot()) {
416
+ start(provider, endpoint, request, stack, context = (0, context_js_1.contextSnapshot)()) {
416
417
  return {
417
418
  provider,
418
419
  endpoint,
@@ -421,8 +422,8 @@ export class CaptureRuntime {
421
422
  started: performance.now(),
422
423
  ts: new Date().toISOString(),
423
424
  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"),
425
+ traceId: context.traceId ?? (0, node_crypto_1.randomBytes)(16).toString("hex"),
426
+ spanId: (0, node_crypto_1.randomBytes)(8).toString("hex"),
426
427
  parentSpanId: context.parentSpanId,
427
428
  traceName: context.traceName ?? context.route ?? context.funcName
428
429
  ?? endpoint,
@@ -456,8 +457,8 @@ export class CaptureRuntime {
456
457
  }
457
458
  return { value: `${clipped}${marker}`, truncated: true };
458
459
  };
459
- const request = text(JSON.stringify(scrub(state.request)), "request");
460
- const fullTools = toolEvents(scrub(state.request), response, extra.responseChunks);
460
+ const request = text(JSON.stringify((0, template_js_1.scrub)(state.request)), "request");
461
+ const fullTools = toolEvents((0, template_js_1.scrub)(state.request), response, extra.responseChunks);
461
462
  const status = extra.status ?? (extra.error ? "error" : stopReason(response) ?? "success");
462
463
  const output = text(JSON.stringify(responseEnvelope(response, extra.responseText, fullTools, extra.error, status)), "response");
463
464
  let toolTruncated = false;
@@ -503,7 +504,7 @@ export class CaptureRuntime {
503
504
  span_id: state.spanId,
504
505
  parent_span_id: state.parentSpanId,
505
506
  trace_name: state.traceName,
506
- template_hash: templateHash(state.request),
507
+ template_hash: (0, template_js_1.templateHash)(state.request),
507
508
  unit_name: state.context.unitName,
508
509
  unit_count: state.context.unitCount,
509
510
  tool_calls: fullTools ? persistedTools : toolNames(state.request),
@@ -531,8 +532,9 @@ export class CaptureRuntime {
531
532
  error: Boolean(extra.error),
532
533
  error_type: extra.error instanceof Error ? extra.error.name : undefined,
533
534
  sdk: "js",
534
- sdk_version: SDK_VERSION,
535
+ sdk_version: version_js_1.SDK_VERSION,
535
536
  runtime: typeof process === "undefined" ? "edge" : `node-${process.versions.node}`,
536
537
  });
537
538
  }
538
539
  }
540
+ 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;