@frugalco/frugal-sdk-node 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!) The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,227 @@
+# Frugal SDK for Node
+
+Instrument your AI API calls with one line of code. Get per-call-site metrics — token usage, latency, call counts — exported via OpenTelemetry to any collector.
+
+## Install
+
+```bash
+npm install @frugalco/frugal-sdk-node
+
+# Plus whichever provider SDKs you use (peer dependencies):
+npm install openai @anthropic-ai/sdk
+```
+
+Requires Node.js 18+.
+
+## Quick start
+
+```ts
+import { wrapOpenAI, wrapAnthropic, wrapBedrock } from "@frugalco/frugal-sdk-node";
+import OpenAI from "openai";
+import Anthropic from "@anthropic-ai/sdk";
+import { BedrockRuntimeClient } from "@aws-sdk/client-bedrock-runtime";
+
+const openai = wrapOpenAI(new OpenAI());
+const anthropic = wrapAnthropic(new Anthropic());
+const bedrock = wrapBedrock(new BedrockRuntimeClient({ region: "us-west-2" }));
+
+// Every call now emits metrics — no other code changes needed
+const response = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [...],
+});
+```
+
+## Configuration
+
+All configuration is via environment variables. No `init()` call, no config objects.
+
+### Required
+
+Set both or the wrapper silently returns the client unmodified:
+
+| Variable            | Purpose                                                    |
+| ------------------- | ---------------------------------------------------------- |
+| `FRUGAL_API_KEY`    | Per-customer bearer token issued by Frugal. Builds the export `Authorization` header. (Or supply the bearer yourself via `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`.) |
+| `FRUGAL_PROJECT_ID` | The Frugal project this deployment belongs to. Stats are attributed per project, so the same repo across microservices no longer collides. |
+
+### Optional
+
+| Variable                                 | Purpose                                                                                 |
+| ---------------------------------------- | --------------------------------------------------------------------------------------- |
+| `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_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_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_DISABLED`                        | Set to `1` to disable all instrumentation without uninstalling.                          |
+
+## What gets captured
+
+Every wrapped call emits OTel metrics tagged with the caller's source file and function, the provider, and the model:
+
+| Metric                                  | Kind      | Description                                                  | Additional attributes                  |
+| --------------------------------------- | --------- | ------------------------------------------------------------ | -------------------------------------- |
+| `gen_ai.client.operation.duration`      | histogram | Call latency in seconds                                      | —                                      |
+| `gen_ai.client.token.usage`             | histogram | Input and output token counts                                | `gen_ai.token.type`                    |
+| `frugal.gen_ai.calls`                   | counter   | Number of calls per site                                     | —                                      |
+| `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.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.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` (analyzer-sampled)                         | —                                      |
+| `frugal.gen_ai.few_shot_count`          | histogram | Few-shot exemplar pairs before final user (analyzer-sampled) | —                                      |
+| `frugal.gen_ai.noise_ratio`             | histogram | HTML/base64/whitespace fraction of input (analyzer-sampled)  | —                                      |
+| `frugal.gen_ai.cache_prefix_stable`     | counter   | Per-block prompt-cache stability (analyzer-sampled)          | `frugal.block`, `frugal.stable`        |
+| `frugal.gen_ai.structured_output_hint`  | counter   | "Return JSON" prompts missing `response_format`/`tools`      | —                                      |
+
+The bottom block of analyzer-sampled metrics fires on a fraction of calls
+(`FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`, default 10%); the token-side metrics are
+100% — never sampled.
+
+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` — `openai`, `anthropic`, `aws.bedrock`, `vertex_ai`, or `custom` (the default for hand-instrumented call sites; override via the `provider` field)
+- `gen_ai.request.model`, `gen_ai.response.model` — the model used
+- `gen_ai.operation.name` — `chat`, `text_completion`, or `embeddings`
+- `frugal.batched` — `true` for batch-API submissions, `false` otherwise
+
+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.
+
+Metrics are aggregated per export interval (not sent per call), so network overhead is minimal regardless of call volume.
+
+## Supported providers
+
+| Provider                                       | Usage                                                          |
+| ---------------------------------------------- | -------------------------------------------------------------- |
+| OpenAI                                         | `wrapOpenAI(new OpenAI())`                                     |
+| Anthropic                                      | `wrapAnthropic(new Anthropic())`                               |
+| Claude on AWS Bedrock (via Anthropic SDK)      | `wrapAnthropic(new AnthropicBedrock())`                        |
+| AWS Bedrock — any model, AWS SDKs directly     | `wrapBedrock(new BedrockRuntimeClient({ region: "..." }))`     |
+| Claude on Google Vertex                        | `wrapAnthropic(new AnthropicVertex())`                         |
+
+`wrapBedrock` covers all four `bedrock-runtime` commands (`InvokeModelCommand`,
+`InvokeModelWithResponseStreamCommand`, `ConverseCommand`,
+`ConverseStreamCommand`) across every model on Bedrock — Anthropic, OpenAI
+gpt-oss, Amazon Nova, Meta Llama, Mistral, Cohere, AI21, DeepSeek, Qwen,
+Kimi, etc. Cross-region inference profile prefixes (`us.`, `eu.`, `jp.`,
+`apac.`, `au.`, `global.`) are preserved in `gen_ai.request.model`. See
+[`docs/quickstart.md`](docs/quickstart.md#native-aws-bedrock-wrapbedrock) for the full Bedrock walkthrough.
+
+## Custom call sites
+
+For AI calls that don't go through a wrapped client — a `fetch()` to a model gateway, a CLI shell-out, or an internal helper that returns raw usage — mark the call site yourself and feed in the usage you have. You get the same metrics and the same caller attribution as the auto-wrappers.
+
+```ts
+import { trackAICall } from "@frugalco/frugal-sdk-node";
+
+const answer = await trackAICall(
+  { provider: "anthropic", model: "claude-sonnet-4-20250514" },
+  async (report) => {
+    const res = await myCustomLlmCall(prompt);
+    report({
+      inputTokens: res.usage.input_tokens,
+      outputTokens: res.usage.output_tokens,
+      responseModel: res.model,
+    });
+    return res.text;
+  },
+);
+```
+
+`trackAICall(info, fn)` runs `fn`, times it, and emits metrics when it finishes — or an error metric if `fn` throws (the original return value and any error always pass through untouched). Works with sync or `async` callbacks. Call `report(usage)` with whatever token counts you have once the response is back; if you never call it, you still get a call-count and latency point.
+
+For calls that span function boundaries — where a single callback won't fit — use the manual handle:
+
+```ts
+import { startAICall } from "@frugalco/frugal-sdk-node";
+
+const call = startAICall({ provider: "anthropic", model: "claude-sonnet-4-20250514" });
+try {
+  const res = await myCustomLlmCall(prompt);
+  call.end({
+    inputTokens: res.usage.input_tokens,
+    outputTokens: res.usage.output_tokens,
+    responseModel: res.model,
+  });
+} catch (err) {
+  call.fail(err);
+  throw err;
+}
+```
+
+`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>"`). 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`.
+
+The same env-var configuration, safety guarantees, and exported metrics apply.
+
+## Streaming
+
+Streaming works with no extra setup. The wrapper returns a drop-in async iterable that passes events through and emits metrics when the stream finishes.
+
+```ts
+// OpenAI — opt in to include_usage for token counts in streams
+const stream = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [...],
+  stream: true,
+  stream_options: { include_usage: true },
+});
+for await (const chunk of stream) {
+  // ...
+}
+
+// Anthropic — token counts available natively, no opt-in needed
+const stream = await anthropic.messages.create({
+  model: "claude-sonnet-4-20250514",
+  max_tokens: 1024,
+  messages: [...],
+  stream: true,
+});
+for await (const event of stream) {
+  // ...
+}
+```
+
+## Internal library attribution
+
+If your code calls an internal helper library that wraps the AI SDK (e.g. `acme-ai-helpers`), add it to the block list so attribution lands on your business code:
+
+```bash
+FRUGAL_PATH_BLOCK_LIST="src/acme-ai-helpers,libs/llm-utils"
+```
+
+## Safety guarantees
+
+- If any required env var is unset, `wrapOpenAI` / `wrapAnthropic` return the client completely unmodified with zero overhead.
+- If any part of our instrumentation fails at runtime (OTel init, stack walking, metric emission), the original SDK call executes normally. We never throw our own exceptions into your code.
+- Wrapping is idempotent — calling `wrapOpenAI(client)` twice on the same client is safe.
+
+## Verifying the setup
+
+Set the OTLP endpoint to empty to print metrics to the console instead of exporting them:
+
+```bash
+export FRUGAL_API_KEY=local
+export FRUGAL_PROJECT_ID=my-project
+export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=   # empty → ConsoleMetricExporter
+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.
+
+## License
+
+This project is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). A copy of the license is also included in the root of the installed package.

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

@@ -0,0 +1,18 @@
+export interface BlockHashes {
+    systemHash: string | null;
+    userHash: string | null;
+    toolsHash: string | null;
+    schemaHash: string | null;
+}
+export declare class BlockHashLRU {
+    private readonly capacity;
+    private readonly map;
+    constructor(capacity?: number);
+    get(callSiteId: string): BlockHashes | undefined;
+    set(callSiteId: string, hashes: BlockHashes): void;
+    size(): number;
+    clear(): void;
+}
+export declare function getSharedBlockHashLRU(capacity?: number): BlockHashLRU;
+export declare function resetSharedBlockHashLRUForTests(): void;
+//# sourceMappingURL=block-hash-lru.d.ts.map

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

@@ -0,0 +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"}

package/dist/block-hash-lru.js

@@ -0,0 +1,48 @@
+// Per-call-site LRU storing the previous call's block hashes. Used by the
+// prompt analyzer to derive cache_prefix_stable signals without leaving raw
+// hashes anywhere outside the process.
+//
+// Default capacity matches the existing call-site cardinality cap so a busy
+// process can't blow memory by tracking thousands of distinct sites.
+export class BlockHashLRU {
+    capacity;
+    map = new Map();
+    constructor(capacity = 500) {
+        this.capacity = capacity;
+    }
+    get(callSiteId) {
+        const entry = this.map.get(callSiteId);
+        if (entry === undefined)
+            return undefined;
+        this.map.delete(callSiteId);
+        this.map.set(callSiteId, entry);
+        return entry;
+    }
+    set(callSiteId, hashes) {
+        if (this.map.has(callSiteId)) {
+            this.map.delete(callSiteId);
+        }
+        else if (this.capacity > 0 && this.map.size >= this.capacity) {
+            const oldest = this.map.keys().next().value;
+            if (oldest !== undefined)
+                this.map.delete(oldest);
+        }
+        this.map.set(callSiteId, hashes);
+    }
+    size() {
+        return this.map.size;
+    }
+    clear() {
+        this.map.clear();
+    }
+}
+let shared = null;
+export function getSharedBlockHashLRU(capacity) {
+    if (shared === null)
+        shared = new BlockHashLRU(capacity);
+    return shared;
+}
+export function resetSharedBlockHashLRUForTests() {
+    shared = null;
+}
+//# sourceMappingURL=block-hash-lru.js.map

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

@@ -0,0 +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"}

package/dist/caller.d.ts

@@ -0,0 +1,23 @@
+export interface CallerInfo {
+    file: string;
+    function: string;
+}
+export interface ResolveCallerArgs {
+    skipPackageDirs: readonly string[];
+    blockList: readonly string[];
+    repoRoot: string;
+    /** Max distinct (file, function) pairs to attribute before overflow. 0 = unlimited. */
+    maxCallSites: number;
+    skipFrames?: number;
+}
+export declare function resolveCaller(args: ResolveCallerArgs): CallerInfo;
+/**
+ * Returns true iff a cardinality cap was crossed since the last call.
+ * Designed to be called once per `startCall` so the instrument layer can
+ * emit a single `frugal.gen_ai.internal_errors{stage=cardinality_cap_hit}`.
+ */
+export declare function consumeCapHitEvent(): boolean;
+export declare function packageDirFor(anyPathInPackage: string): string;
+/** Test-only hook — clear all caches. */
+export declare function resetCachesForTests(): void;
+//# sourceMappingURL=caller.d.ts.map

package/dist/caller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller.d.ts","sourceRoot":"","sources":["../src/caller.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAQD,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAkBD,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,UAAU,CAqCjE;AA8BD;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAM5C;AA6ED,wBAAgB,aAAa,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAiB9D;AAED,yCAAyC;AACzC,wBAAgB,mBAAmB,IAAI,IAAI,CAO1C"}