@frugalco/frugal-sdk-node 0.4.0 → 0.6.0

package/README.md

@@ -38,7 +38,7 @@ All configuration is via environment variables. No `init()` call, no config obje
 
 ### Required
 
-Set both or the wrapper silently returns the client unmodified:
+Set both (or, with `FRUGAL_METRICS_EXPORTER=console`, only `FRUGAL_PROJECT_ID`) or the wrapper silently returns the client unmodified:
 
 | Variable            | Purpose                                                    |
 | ------------------- | ---------------------------------------------------------- |
@@ -49,24 +49,38 @@ Set both or the wrapper silently returns the client unmodified:
 
 | Variable                                 | Purpose                                                                                 |
 | ---------------------------------------- | --------------------------------------------------------------------------------------- |
+| `FRUGAL_METRICS_PROJECT_ID` / `FRUGAL_METRICS_API_KEY` | Namespaced overrides read before `FRUGAL_PROJECT_ID` / `FRUGAL_API_KEY`; an empty value falls through. Use them when the host app already owns the bare names. |
 | `FRUGAL_CUSTOMER_ID`                     | Customer ID issued by Frugal. When unset, the tenant label (auto-injected server-side by VMAuth from the bearer token) identifies the customer and `frugal.customer_id` is omitted. |
 | `FRUGAL_REPO_ROOT`                       | Absolute path to the source root; the strip prefix for `caller_file`. Defaults to the process working directory. |
-| `FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT`     | OTLP collector URL for Frugal metrics. Defaults to `https://metrics.frugal.co/opentelemetry/v1/metrics`. Falls back to `OTEL_EXPORTER_OTLP_ENDPOINT`. |
-| `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`      | Export auth headers (e.g. `Authorization=Bearer ...`). Overrides the header built from `FRUGAL_API_KEY`. Falls back to `OTEL_EXPORTER_OTLP_HEADERS`. |
-| `FRUGAL_COMPONENTS`                      | Comma-separated logical components (e.g. `ai-handler,reco`). When set, each metric is ALSO emitted once per component (tagged `frugal.component`) on top of the base project series, so usage can be viewed for the whole project or split by component. |
+| `FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT`     | OTLP collector URL for Frugal metrics. Defaults to `https://metrics.frugal.co/opentelemetry/v1/metrics`; an empty value falls through to the default. |
+| `FRUGAL_METRICS_EXPORTER` | `otlp` (default) or `console`. `console` prints metrics to stdout through the console exporter for local verification; console mode needs only `FRUGAL_PROJECT_ID`; the API key, endpoint and header variables are ignored. Value is trimmed and case-insensitive; anything else warns once and uses `otlp`. |
+| `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`      | Export auth headers (e.g. `Authorization=Bearer ...`). Overrides the header built from `FRUGAL_METRICS_API_KEY` / `FRUGAL_API_KEY`; an empty or blank (whitespace-only) value is treated as unset and falls through to it. A non-blank value with no `key=value` pairs (e.g. `Authorization: Bearer x`) counts as missing auth, even when an API key is set — it never falls back to the key. Values are percent-decoded (`Bearer%20tok` → `Bearer tok`); a value that fails to decode is kept as-is. |
+| `FRUGAL_COMPONENTS`                      | Comma-separated logical components (e.g. `ai-handler,reco`). When set, each metric is ALSO emitted once per component (tagged `frugal.component`) on top of the base project series, so usage can be viewed for the whole project or split by component. Only the **first 10** distinct entries are honored (a fixed cap, not configurable — each component multiplies every instrument's series count); the rest are dropped with one warning. |
 | `FRUGAL_CUSTOM_PROVIDERS`                | Comma-separated allowlist of provider names beyond the built-in registry (e.g. `together_ai,fireworks`) that should pass through verbatim on `gen_ai.system` / `gen_ai.provider.name` instead of being coerced to `custom`. Capped at 10 (extras are coerced) to keep label cardinality bounded. |
-| `FRUGAL_CUSTOM_LABEL`                   | Comma-separated allowlist for the `frugal.custom_label` label on manual track calls (e.g. `billing,search,recs`). A `customLabel` passed to `trackAICall`/`startAICall` outside the first 20 entries (a hard, non-configurable cap) is coerced to `other` with a warn-once diagnostic. `other` is reserved and ignored as an entry. See [Custom call sites](#custom-call-sites). |
+| `FRUGAL_CUSTOM_LABEL`                   | Comma-separated allowlist for the `frugal.custom_label` label on manual track calls (e.g. `billing,search,recs`). A `customLabel` passed to `trackAICall`/`startAICall` outside the first 20 entries (a hard, non-configurable cap) is coerced to `other` with a warn-once diagnostic. A warning fires only when non-empty entries past the 20th are dropped (a trailing comma does not warn). `other` is reserved and ignored as an entry. See [Custom call sites](#custom-call-sites). |
 | `FRUGAL_PATH_BLOCK_LIST`                 | Comma-separated repo-relative paths to skip for caller attribution (see below).          |
-| `FRUGAL_METRIC_EXPORT_INTERVAL_MS`       | Export cadence in milliseconds. Default `60000`.                                         |
+| `FRUGAL_METRIC_EXPORT_INTERVAL_MS`       | Export cadence in milliseconds, `1`-`2147483647`. Default `60000`; a larger value warns once and uses the default.                                      |
 | `FRUGAL_MAX_CALL_SITES`                  | Cardinality cap — max distinct `(caller_file, caller_function)` pairs to attribute. Default `500`. Set to `0` to disable. |
-| `FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`     | Fraction of calls (0..1) that run the lightweight prompt analyzer. Default `0.1`. Set to `0` to disable, `1` for every call. |
+| `FRUGAL_MAX_MODELS`                      | Cardinality cap — max distinct model strings (`gen_ai.request.model` and `gen_ai.response.model` share one registry) before further models collapse to `<overflow>`. Default `100`, which is ~50 logical models: a request alias (`gpt-4o`) and the dated snapshot the response reports (`gpt-4o-2024-08-06`) are two strings in the one shared registry. Set to `0` to disable. |
+| `FRUGAL_MAX_SERIES_PER_INSTRUMENT`       | OpenTelemetry's per-instrument limit on distinct label **combinations**. Default `50000` (OTel's own default is 2000, far too low for this SDK's label set); `0` means effectively unlimited (a 1,000,000 ceiling). |
+| `FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`     | Fraction of calls (0..1) that run the lightweight prompt analyzer. Default `0.1`. Set to `0` to disable, `1` for every call. A decimal in [0, 1], plain or scientific notation (e.g. `0.25`, `1e-1`); anything else warns once and uses `0.1`. |
 | `FRUGAL_DUPLICATE_REQUEST_DETECTION`     | Duplicate-request detection (default **on**): every chat request is canonicalized and hashed in-process to classify `first_seen`/`repeat_seen` — only the 2-value state is exported, never content. Set to `0`/`false`/`no`/`off` to disable the hashing and the `frugal.gen_ai.duplicate_requests` metric entirely. |
 | `FRUGAL_DUPLICATE_WINDOW_SECONDS`        | How long a request signature is remembered. Default `3600`, max `86400` (retention is 30–60 min at defaults — see [docs/metrics-reference.md](docs/metrics-reference.md)). |
 | `FRUGAL_DUPLICATE_CAPACITY`              | Expected distinct requests per window (Bloom filter sizing). Default `10000`, max `1000000`. Raise if the saturation warning fires. |
-| `FRUGAL_DUPLICATE_FP_RATE`               | Target false-positive rate for the duplicate filter. Default `0.01`, max `0.5`.          |
+| `FRUGAL_DUPLICATE_FP_RATE`               | Target false-positive rate for the duplicate filter. Default `0.01`; clamped to `[1e-6, 0.5]` with a warning. |
 | `FRUGAL_DUPLICATE_GENERATIONS`           | Rotating-Bloom generation count. Default `2`, max `16`.                                  |
 | `FRUGAL_DISABLED`                        | Set to `1` to disable all instrumentation without uninstalling.                          |
 
+The export endpoint and headers come only from `FRUGAL_`-prefixed variables.
+The SDK never reads `OTEL_EXPORTER_OTLP_ENDPOINT` or
+`OTEL_EXPORTER_OTLP_HEADERS`, and it hides `OTEL_EXPORTER_OTLP_HEADERS` and
+`OTEL_EXPORTER_OTLP_METRICS_HEADERS` from the OTel exporter library while
+constructing its exporter (the library would otherwise merge them into every
+request), so the host's own OpenTelemetry headers never reach Frugal and the
+Frugal bearer never reaches the host's collector. The exporter library still
+reads its other standard variables (TLS, compression, timeout, temporality) on
+its own.
+
 ## What gets captured
 
 Every wrapped call emits OTel metrics tagged with the caller's source file and function, the provider, and the model:
@@ -79,8 +93,9 @@ Every wrapped call emits OTel metrics tagged with the caller's source file and f
 | `frugal.gen_ai.cache_read_tokens`       | histogram | Prompt cache hits                                            | —                                      |
 | `frugal.gen_ai.cache_write_tokens`      | histogram | Prompt cache writes                                          | —                                      |
 | `frugal.gen_ai.reasoning_tokens`        | histogram | OpenAI reasoning tokens (o-series), Anthropic thinking tokens| —                                      |
+| `frugal.gen_ai.agent.turns`             | histogram | Model-response turns in a successful agent invocation        | —                                      |
 | `frugal.gen_ai.errors`                  | counter   | Errors by exception type                                     | `frugal.error.type`                    |
-| `frugal.gen_ai.internal_errors`         | counter   | frugal-metrics internal failures (cardinality cap, bugs)     | `frugal.internal_error.stage`          |
+| `frugal.gen_ai.internal_errors`         | counter   | frugal-metrics internal failures (cardinality caps, bugs)    | `frugal.internal_error.stage`, `frugal.internal_error.type`, `frugal.instrument` (on `otel_cardinality_overflow` only) |
 | `frugal.gen_ai.output_cap_utilization`  | histogram | `output_tokens / max_tokens` ratio when `max_tokens` is set  | `frugal.structured_output_mode`        |
 | `frugal.gen_ai.history_depth`           | histogram | `messages.length` — every chat call, success or error (100%, not sampled) | —                         |
 | `frugal.gen_ai.duplicate_requests`      | counter   | Request-duplication state from a windowed signature filter — every chat call (100%, not sampled; see `FRUGAL_DUPLICATE_*` vars) | `frugal.dup_state` (`first_seen` \| `repeat_seen`) |
@@ -101,9 +116,9 @@ Every metric carries this base attribute set:
 - `frugal.project_id` — from your env vars (`frugal.customer_id` too when set); `frugal.component` is added on the per-component series when `FRUGAL_COMPONENTS` is set
 - `frugal.caller_file`, `frugal.caller_function` — auto-detected from the call stack
 - `gen_ai.system` + `gen_ai.provider.name` — the provider, dual-emitted under both the legacy and current OTel attribute (`openai`, `anthropic`, `aws.bedrock`, `vertex_ai`/`gcp.vertex_ai`, …, or `custom`). Override via the `provider` field; an unrecognized value is coerced to `custom` with a one-time warning. See [`docs/metrics-reference.md`](docs/metrics-reference.md#attributes).
-- `gen_ai.request.model`, `gen_ai.response.model` — the model used
+- `gen_ai.request.model`, `gen_ai.response.model` — the model used. Both draw on one shared registry capped by `FRUGAL_MAX_MODELS`; past the cap the value reads `<overflow>` (the same sentinel the caller labels use). `<unknown>` when the wrapper could not read a model off the request
 - `gen_ai.operation.name` — `chat`, `text_completion`, `embeddings`, `generate_content`, `execute_tool`, `create_agent`, `invoke_agent`, or `other` (the sentinel an unrecognized operation coerces to)
-- `frugal.batched` — `true` for batch-API paths (OpenAI Batch API submissions; Anthropic Message Batches submissions and results), `false` otherwise
+- `frugal.batched` — `true` for batch-API paths (OpenAI Batch API submissions; Anthropic Message Batches submissions and results), `false` otherwise; on every metric of the call except the `frugal.gen_ai.internal_errors` points
 
 The "Additional attributes" column above lists what each metric carries on top of the base set. See [`docs/metrics-reference.md`](docs/metrics-reference.md) for the values each attribute takes, sentinel values for caller fields, and the full internal-error-stage list.
 
@@ -171,9 +186,57 @@ try {
 
 `end()` and `fail()` finalize the call exactly once and are idempotent — extra calls are ignored, so a `try/finally` that always calls `end()` won't double-count.
 
-**Metadata** — `info` (all optional): `provider` (→ `gen_ai.system`, default `"custom"`), `operation` (default `"chat"`), `model` (→ `gen_ai.request.model`, default `"<unknown>"`), `customLabel` (→ `frugal.custom_label` on **every** metric of the call; the value must be one of the first 20 comma-separated entries of `FRUGAL_CUSTOM_LABEL` or it is coerced to `"other"` — the label is exclusive to this manual API, wrapper calls never carry it). To also run the sampled prompt analyzer, pass any of `messages` / `system` / `tools` / `responseFormat` / `maxTokens`.
+For an agent invocation, set `operation: "invoke_agent"` and report the number
+of model-response steps completed by the whole run:
+
+```ts
+const result = await trackAICall(
+  { operation: "invoke_agent", model: "agent-model" },
+  async (report) => {
+    const run = await agent.invoke(task);
+    report({ agentTurns: run.turnCount });
+    return run.output;
+  },
+);
+```
+
+The manual-handle form uses the same contract:
+
+```ts
+const handle = startAICall({ operation: "invoke_agent", model: "agent-model" });
+try {
+  const run = await agent.invoke(task);
+  handle.end({ agentTurns: run.turnCount });
+} catch (err) {
+  handle.fail(err);
+  throw err;
+}
+```
 
-**Usage** — `report(...)` / `end(...)` fields (all optional): `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `reasoningTokens`, `responseModel`.
+Provider wrappers continue to measure individual model calls. Agent frameworks
+use `trackAICall` or `startAICall` to measure the enclosing invocation; dedicated
+framework adapters are not available yet. A turn sample is emitted only for a
+successful `invoke_agent` call with a positive-integer `agentTurns` value.
+
+**Avoid double-counting tokens.** The examples above report `agentTurns` only,
+which is correct when the agent's inner model-client calls are already wrapped
+by a supported provider wrapper: those wrappers emit token usage per inner
+call, so also reporting aggregate tokens on the `invoke_agent` call would
+double-count them. Only when the inner calls are **not** wrapped, add the
+aggregate `inputTokens` / `outputTokens` (and the other usage fields):
+
+```ts
+// Inner model calls are NOT wrapped by a provider wrapper.
+report({
+  agentTurns: run.turnCount,
+  inputTokens: run.usage.inputTokens,
+  outputTokens: run.usage.outputTokens,
+});
+```
+
+**Metadata** — `info` (all optional): `provider` (→ `gen_ai.system`, default `"custom"`), `operation` (default `"chat"`), `model` (→ `gen_ai.request.model`, default `"<unknown>"`), `customLabel` (→ `frugal.custom_label` on every metric of the call except the `frugal.gen_ai.internal_errors` `setup_failed` / `emission` points; the value must be one of the first 20 comma-separated entries of `FRUGAL_CUSTOM_LABEL` or it is coerced to `"other"` — the label is exclusive to this manual API, wrapper calls never carry it). To also run the sampled prompt analyzer, pass any of `messages` / `system` / `tools` / `responseFormat` / `maxTokens`.
+
+**Usage** — `report(...)` / `end(...)` fields (all optional): `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `reasoningTokens`, `responseModel`, `agentTurns`.
 
 The same env-var configuration, safety guarantees, and exported metrics apply.
 
@@ -269,17 +332,28 @@ It is **opt-in** because installing signal handlers is intrusive. If you run you
 
 ## Verifying the setup
 
-Set the OTLP endpoint to empty to print metrics to the console instead of exporting them:
+Set `FRUGAL_METRICS_EXPORTER=console` to print the metrics to stdout instead
+of exporting them (console mode needs only `FRUGAL_PROJECT_ID`; the API key, endpoint and header variables are ignored):
+
+```bash
+export FRUGAL_PROJECT_ID=my-project
+export FRUGAL_METRICS_EXPORTER=console
+export FRUGAL_METRIC_EXPORT_INTERVAL_MS=5000
+node my_script.js
+```
+
+Or point the library at a local OTLP/HTTP collector. An empty endpoint is not a
+console switch: it falls through to the default Frugal endpoint.
 
 ```bash
-export FRUGAL_API_KEY=local
+export FRUGAL_API_KEY=my-key
 export FRUGAL_PROJECT_ID=my-project
-export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=   # empty → ConsoleMetricExporter
+export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/metrics
 export FRUGAL_METRIC_EXPORT_INTERVAL_MS=5000
 node my_script.js
 ```
 
-You should see JSON metric records with `gen_ai.*` and `frugal.*` attributes every 5 seconds.
+The collector should receive metric records with `gen_ai.*` and `frugal.*` attributes every 5 seconds.
 
 ## License
 

package/dist/block-hash-lru.d.ts

@@ -5,8 +5,15 @@ export interface BlockHashes {
     schemaHash: string | null;
 }
 export declare class BlockHashLRU {
-    private readonly capacity;
     private readonly map;
+    private readonly capacity;
+    /**
+     * A capacity of 0 or less means "use the default", never "never evict". The
+     * capacity is threaded from FRUGAL_MAX_CALL_SITES, where 0 legitimately means
+     * "don't cap the call-site LABEL" — but this map is process memory, not label
+     * cardinality, and an unbounded one grows with every distinct call site for
+     * the life of the process.
+     */
     constructor(capacity?: number);
     get(callSiteId: string): BlockHashes | undefined;
     set(callSiteId: string, hashes: BlockHashes): void;

package/dist/block-hash-lru.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"block-hash-lru.d.ts","sourceRoot":"","sources":["../src/block-hash-lru.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,qBAAa,YAAY;IAGX,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkC;gBAEzB,QAAQ,GAAE,MAAY;IAEnD,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAQhD,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IAUlD,IAAI,IAAI,MAAM;IAId,KAAK,IAAI,IAAI;CAGd;AAID,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CAGrE;AAED,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD"}
+{"version":3,"file":"block-hash-lru.d.ts","sourceRoot":"","sources":["../src/block-hash-lru.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAKD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkC;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC;;;;;;OAMG;gBACS,QAAQ,GAAE,MAAyB;IAI/C,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAQhD,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IAUlD,IAAI,IAAI,MAAM;IAId,KAAK,IAAI,IAAI;CAGd;AAID,wBAAgB,qBAAqB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CAGrE;AAED,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD"}

package/dist/block-hash-lru.js

@@ -4,11 +4,20 @@
 //
 // Default capacity matches the existing call-site cardinality cap so a busy
 // process can't blow memory by tracking thousands of distinct sites.
+/** Capacity used whenever the caller supplies nothing usable. */
+const DEFAULT_CAPACITY = 500;
 export class BlockHashLRU {
-    capacity;
     map = new Map();
-    constructor(capacity = 500) {
-        this.capacity = capacity;
+    capacity;
+    /**
+     * A capacity of 0 or less means "use the default", never "never evict". The
+     * capacity is threaded from FRUGAL_MAX_CALL_SITES, where 0 legitimately means
+     * "don't cap the call-site LABEL" — but this map is process memory, not label
+     * cardinality, and an unbounded one grows with every distinct call site for
+     * the life of the process.
+     */
+    constructor(capacity = DEFAULT_CAPACITY) {
+        this.capacity = capacity > 0 ? capacity : DEFAULT_CAPACITY;
     }
     get(callSiteId) {
         const entry = this.map.get(callSiteId);
@@ -22,7 +31,7 @@ export class BlockHashLRU {
         if (this.map.has(callSiteId)) {
             this.map.delete(callSiteId);
         }
-        else if (this.capacity > 0 && this.map.size >= this.capacity) {
+        else if (this.map.size >= this.capacity) {
             const oldest = this.map.keys().next().value;
             if (oldest !== undefined)
                 this.map.delete(oldest);

package/dist/block-hash-lru.js.map

@@ -1 +1 @@
-{"version":3,"file":"block-hash-lru.js","sourceRoot":"","sources":["../src/block-hash-lru.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,4EAA4E;AAC5E,uCAAuC;AACvC,EAAE;AACF,4EAA4E;AAC5E,qEAAqE;AASrE,MAAM,OAAO,YAAY;IAGM;IAFZ,GAAG,GAAG,IAAI,GAAG,EAAuB,CAAC;IAEtD,YAA6B,WAAmB,GAAG;QAAtB,aAAQ,GAAR,QAAQ,CAAc;IAAG,CAAC;IAEvD,GAAG,CAAC,UAAkB;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC1C,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,GAAG,CAAC,UAAkB,EAAE,MAAmB;QACzC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC9B,CAAC;aAAM,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAC5C,IAAI,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;IACvB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;CACF;AAED,IAAI,MAAM,GAAwB,IAAI,CAAC;AAEvC,MAAM,UAAU,qBAAqB,CAAC,QAAiB;IACrD,IAAI,MAAM,KAAK,IAAI;QAAE,MAAM,GAAG,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC;IACzD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,+BAA+B;IAC7C,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC"}
+{"version":3,"file":"block-hash-lru.js","sourceRoot":"","sources":["../src/block-hash-lru.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,4EAA4E;AAC5E,uCAAuC;AACvC,EAAE;AACF,4EAA4E;AAC5E,qEAAqE;AASrE,iEAAiE;AACjE,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B,MAAM,OAAO,YAAY;IACN,GAAG,GAAG,IAAI,GAAG,EAAuB,CAAC;IACrC,QAAQ,CAAS;IAElC;;;;;;OAMG;IACH,YAAY,WAAmB,gBAAgB;QAC7C,IAAI,CAAC,QAAQ,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC;IAC7D,CAAC;IAED,GAAG,CAAC,UAAkB;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC1C,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,GAAG,CAAC,UAAkB,EAAE,MAAmB;QACzC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC9B,CAAC;aAAM,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAC5C,IAAI,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;IACvB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;CACF;AAED,IAAI,MAAM,GAAwB,IAAI,CAAC;AAEvC,MAAM,UAAU,qBAAqB,CAAC,QAAiB;IACrD,IAAI,MAAM,KAAK,IAAI;QAAE,MAAM,GAAG,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC;IACzD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,+BAA+B;IAC7C,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC"}

package/dist/config.d.ts

@@ -19,11 +19,32 @@ export interface Config {
     customLabels: readonly string[];
     repoRoot: string;
     pathBlockList: readonly string[];
+    /** Metric exporter: `otlp` (default) or `console` (prints to stdout; endpoint/headers ignored). */
+    exporter: "otlp" | "console";
     otlpEndpoint: string;
+    /** Resolved header string (display/compat). Only an explicit FRUGAL_OTEL_EXPORTER_OTLP_HEADERS value is parsed and percent-decoded for export. */
     otlpHeaders: string;
+    /**
+     * The raw API key when the export header comes from it (no explicit
+     * FRUGAL_OTEL_EXPORTER_OTLP_HEADERS), else null. The exporter builds
+     * `Authorization: Bearer <key>` from it directly, so a key containing `%` or
+     * `,` is never decoded or split.
+     */
+    otlpApiKey: string | null;
     exportIntervalMs: number;
     /** Max distinct (file, function) combinations to attribute before overflow. 0 = unlimited. */
     maxCallSites: number;
+    /**
+     * OTel's per-instrument limit on distinct attribute SETS. Beyond it the SDK
+     * merges everything into one `{otel.metric.overflow: true}` series with every
+     * other attribute dropped. 0 = disabled (effectively unlimited).
+     */
+    maxSeriesPerInstrument: number;
+    /**
+     * Max distinct model strings (request + response share one registry) to
+     * attribute before they collapse to the `<overflow>` sentinel. 0 = unlimited.
+     */
+    maxModels: number;
     /** Fraction of analyzed calls to emit prompt-analysis metrics for, 0..1. */
     promptAnalysisSampleRate: number;
     duplicateDetection: boolean;
@@ -32,7 +53,27 @@ export interface Config {
     duplicateFpRate: number;
     duplicateGenerations: number;
 }
+/**
+ * Load the configuration, or null when the SDK should stay a no-op.
+ *
+ * Every wrapX() calls this at the customer's module scope, so a throw here
+ * crashes the host app before it has run a line of its own code. Nothing in
+ * the body is supposed to throw — but it reads the environment and touches the
+ * filesystem (process.cwd() raises ENOENT when the working directory has been
+ * removed, realpathSync can raise on a broken mount), so the whole thing is
+ * contained: any failure disables the SDK with one diagnostic instead of
+ * taking the process with it.
+ */
 export declare function loadConfig(): Config | null;
+/**
+ * Parse an OTLP `key=value,key=value` header string. Values are
+ * percent-decoded like OTel's own env parser (`Bearer%20tok` → `Bearer tok`);
+ * keys are kept literal, and a value that fails to decode is kept raw. Parts
+ * without `=` or with an empty key are dropped; a string with no pairs at all
+ * returns undefined.
+ * Same rule in the Python and Go SDKs.
+ */
+export declare function parseHeaders(raw: string | null): Record<string, string> | undefined;
 /** Test-only hook to re-arm the one-shot warning. */
 export declare function resetWarningStateForTests(): void;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,MAAM;IACrB,mGAAmG;IACnG,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B;;;;OAIG;IACH,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;OAIG;IACH,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,8FAA8F;IAC9F,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,wBAAwB,EAAE,MAAM,CAAC;IACjC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAqHD,wBAAgB,UAAU,IAAI,MAAM,GAAG,IAAI,CA+O1C;AAED,qDAAqD;AACrD,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAwCA,MAAM,WAAW,MAAM;IACrB,mGAAmG;IACnG,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B;;;;OAIG;IACH,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;OAIG;IACH,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mGAAmG;IACnG,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,kJAAkJ;IAClJ,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,8FAA8F;IAC9F,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,sBAAsB,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,wBAAwB,EAAE,MAAM,CAAC;IACjC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAmMD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,IAAI,MAAM,GAAG,IAAI,CAW1C;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAoBnF;AAwUD,qDAAqD;AACrD,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}