@frugalco/frugal-sdk-node 0.1.0

package/dist/prompt-analyzer.js

@@ -0,0 +1,210 @@
+// Lightweight per-request analyzer. Inspects messages, tools, and
+// response_format kwargs to derive low-cardinality signals for the
+// AI cost-trap detection catalogue. Never emits raw request content; emits
+// stats and (in-process-only) hashes that the instrument layer turns into
+// metrics.
+import { createHash } from "node:crypto";
+import { STRUCTURED_OUTPUT_JSON_OBJECT, STRUCTURED_OUTPUT_JSON_SCHEMA, STRUCTURED_OUTPUT_NONE, STRUCTURED_OUTPUT_TOOLS, } from "./semconv.js";
+export function analyzeRequest(payload) {
+    return {
+        systemHash: safe(() => hashSystemBlock(payload), null),
+        userHash: safe(() => hashUserBlock(payload), null),
+        toolsHash: safe(() => hashJSON(payload.tools), null),
+        schemaHash: safe(() => hashJSON(payload.responseFormat), null),
+        historyDepth: safe(() => historyDepth(payload), null),
+        fewShotCount: safe(() => fewShotCount(payload), null),
+        noiseRatio: safe(() => noiseRatio(payload), null),
+        structuredOutputHint: safe(() => structuredOutputHint(payload), false),
+    };
+}
+export function structuredOutputMode(payload) {
+    if (Array.isArray(payload.tools) && payload.tools.length > 0) {
+        return STRUCTURED_OUTPUT_TOOLS;
+    }
+    const rf = payload.responseFormat;
+    if (rf && typeof rf === "object") {
+        const type = rf.type;
+        if (type === "json_object")
+            return STRUCTURED_OUTPUT_JSON_OBJECT;
+        if (type === "json_schema")
+            return STRUCTURED_OUTPUT_JSON_SCHEMA;
+    }
+    return STRUCTURED_OUTPUT_NONE;
+}
+function safe(fn, fallback) {
+    try {
+        return fn();
+    }
+    catch {
+        return fallback;
+    }
+}
+// --- hashing ---------------------------------------------------------------
+function sha256(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+function hashJSON(value) {
+    if (value === undefined || value === null)
+        return null;
+    return sha256(canonicalize(value));
+}
+function canonicalize(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map((v) => canonicalize(v)).join(",") + "]";
+    }
+    const keys = Object.keys(value).sort();
+    const parts = keys.map((k) => JSON.stringify(k) + ":" + canonicalize(value[k]));
+    return "{" + parts.join(",") + "}";
+}
+function hashSystemBlock(payload) {
+    const blocks = [];
+    if (payload.system !== undefined && payload.system !== null) {
+        blocks.push(payload.system);
+    }
+    if (Array.isArray(payload.messages)) {
+        for (const m of payload.messages) {
+            if (m && typeof m === "object" && m.role === "system") {
+                blocks.push(m.content ?? null);
+            }
+        }
+    }
+    if (blocks.length === 0)
+        return null;
+    return hashJSON(blocks);
+}
+function hashUserBlock(payload) {
+    if (!Array.isArray(payload.messages))
+        return null;
+    const blocks = [];
+    for (const m of payload.messages) {
+        if (m && typeof m === "object" && m.role === "user") {
+            blocks.push(m.content ?? null);
+        }
+    }
+    if (blocks.length === 0)
+        return null;
+    return hashJSON(blocks);
+}
+// --- structural counts -----------------------------------------------------
+function historyDepth(payload) {
+    if (!Array.isArray(payload.messages))
+        return null;
+    return payload.messages.length;
+}
+function fewShotCount(payload) {
+    if (!Array.isArray(payload.messages))
+        return null;
+    const msgs = payload.messages.filter((m) => m !== null && typeof m === "object");
+    // Skip leading system messages.
+    let i = 0;
+    while (i < msgs.length && msgs[i].role === "system")
+        i++;
+    // The conversation must end with a user turn for "few-shot before final
+    // user" to make sense; otherwise the shape is mid-conversation.
+    if (msgs.length === 0 || msgs[msgs.length - 1].role !== "user")
+        return null;
+    // If any tool-call turns exist, treat this as a real conversation, not a
+    // few-shot prompt.
+    for (const m of msgs) {
+        if (m.role === "tool")
+            return null;
+        if (Array.isArray(m.tool_calls) && m.tool_calls.length > 0)
+            return null;
+    }
+    // Count consecutive (user, assistant) pairs preceding the final user.
+    let pairs = 0;
+    let j = i;
+    const lastIdx = msgs.length - 1; // final user
+    while (j + 1 < lastIdx) {
+        if (msgs[j].role === "user" && msgs[j + 1].role === "assistant") {
+            pairs++;
+            j += 2;
+        }
+        else {
+            break;
+        }
+    }
+    return pairs;
+}
+// --- noise ratio -----------------------------------------------------------
+const HTML_TAG_REGEX = /<[^>]+>/g;
+const BASE64_REGEX = /[A-Za-z0-9+/]{40,}={0,2}/g;
+const WHITESPACE_RUN_REGEX = /\s{4,}/g;
+function noiseRatio(payload) {
+    const text = collectText(payload);
+    if (text.length === 0)
+        return null;
+    let noise = 0;
+    for (const match of text.matchAll(HTML_TAG_REGEX))
+        noise += match[0].length;
+    for (const match of text.matchAll(BASE64_REGEX))
+        noise += match[0].length;
+    for (const match of text.matchAll(WHITESPACE_RUN_REGEX))
+        noise += match[0].length;
+    // Cap at 1.0 — the regex classes can overlap in degenerate inputs.
+    return Math.min(1, noise / text.length);
+}
+function collectText(payload) {
+    const parts = [];
+    if (typeof payload.system === "string")
+        parts.push(payload.system);
+    if (Array.isArray(payload.messages)) {
+        for (const m of payload.messages) {
+            if (!m || typeof m !== "object")
+                continue;
+            const content = m.content;
+            if (typeof content === "string")
+                parts.push(content);
+            else if (Array.isArray(content)) {
+                for (const c of content) {
+                    if (!c || typeof c !== "object")
+                        continue;
+                    const text = c.text;
+                    if (typeof text === "string")
+                        parts.push(text);
+                }
+            }
+        }
+    }
+    return parts.join("\n");
+}
+// --- structured output hint ------------------------------------------------
+const STRUCTURED_HINT_REGEXES = [
+    /format\s+as\s+JSON/i,
+    /return\s+a\s+(JSON\s+)?(list|array|object)/i,
+    /respond\s+with\s+a\s+JSON/i,
+    /output\s+(must\s+be|should\s+be|in)\s+JSON/i,
+];
+function structuredOutputHint(payload) {
+    if (Array.isArray(payload.tools) && payload.tools.length > 0)
+        return false;
+    if (payload.responseFormat &&
+        typeof payload.responseFormat === "object" &&
+        payload.responseFormat.type !== undefined) {
+        return false;
+    }
+    const text = collectText(payload);
+    if (text.length === 0)
+        return false;
+    return STRUCTURED_HINT_REGEXES.some((r) => r.test(text));
+}
+// --- sampling --------------------------------------------------------------
+const BUCKET_MS = 60_000;
+export function shouldSample(callSiteId, sampleRate, nowMs = Date.now()) {
+    if (sampleRate >= 1)
+        return true;
+    if (sampleRate <= 0)
+        return false;
+    const bucket = Math.floor(nowMs / BUCKET_MS);
+    const key = `${callSiteId}:${bucket}`;
+    // FNV-1a 32-bit, fast and good enough for sampling.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < key.length; i++) {
+        hash ^= key.charCodeAt(i);
+        hash = (hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24))) >>> 0;
+    }
+    return hash / 0xffffffff < sampleRate;
+}
+//# sourceMappingURL=prompt-analyzer.js.map

package/dist/prompt-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-analyzer.js","sourceRoot":"","sources":["../src/prompt-analyzer.ts"],"names":[],"mappings":"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"}

package/dist/semconv.d.ts

@@ -0,0 +1,52 @@
+export declare const GEN_AI_SYSTEM = "gen_ai.system";
+export declare const GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
+export declare const GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
+export declare const GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
+export declare const GEN_AI_TOKEN_TYPE = "gen_ai.token.type";
+export declare const SYSTEM_OPENAI = "openai";
+export declare const SYSTEM_ANTHROPIC = "anthropic";
+export declare const SYSTEM_AZURE_OPENAI = "az.ai.openai";
+export declare const SYSTEM_AWS_BEDROCK = "aws.bedrock";
+export declare const SYSTEM_VERTEX_AI = "vertex_ai";
+export declare const SYSTEM_CUSTOM = "custom";
+export declare const OP_CHAT = "chat";
+export declare const OP_TEXT_COMPLETION = "text_completion";
+export declare const OP_EMBEDDINGS = "embeddings";
+export declare const TOKEN_INPUT = "input";
+export declare const TOKEN_OUTPUT = "output";
+export declare const METRIC_OPERATION_DURATION = "gen_ai.client.operation.duration";
+export declare const METRIC_TOKEN_USAGE = "gen_ai.client.token.usage";
+export declare const METRIC_CALLS = "frugal.gen_ai.calls";
+export declare const METRIC_CACHE_READ_TOKENS = "frugal.gen_ai.cache_read_tokens";
+export declare const METRIC_CACHE_WRITE_TOKENS = "frugal.gen_ai.cache_write_tokens";
+export declare const METRIC_REASONING_TOKENS = "frugal.gen_ai.reasoning_tokens";
+export declare const METRIC_ERRORS = "frugal.gen_ai.errors";
+export declare const METRIC_INTERNAL_ERRORS = "frugal.gen_ai.internal_errors";
+export declare const METRIC_OUTPUT_CAP_UTILIZATION = "frugal.gen_ai.output_cap_utilization";
+export declare const METRIC_CACHE_PREFIX_STABLE = "frugal.gen_ai.cache_prefix_stable";
+export declare const METRIC_HISTORY_DEPTH = "frugal.gen_ai.history_depth";
+export declare const METRIC_FEW_SHOT_COUNT = "frugal.gen_ai.few_shot_count";
+export declare const METRIC_NOISE_RATIO = "frugal.gen_ai.noise_ratio";
+export declare const METRIC_STRUCTURED_OUTPUT_HINT = "frugal.gen_ai.structured_output_hint";
+export declare const FRUGAL_CUSTOMER_ID = "frugal.customer_id";
+export declare const FRUGAL_PROJECT_ID = "frugal.project_id";
+export declare const FRUGAL_COMPONENT = "frugal.component";
+export declare const FRUGAL_CALLER_FILE = "frugal.caller_file";
+export declare const FRUGAL_CALLER_FUNCTION = "frugal.caller_function";
+export declare const FRUGAL_ERROR_TYPE = "frugal.error.type";
+export declare const FRUGAL_BATCHED = "frugal.batched";
+export declare const FRUGAL_STRUCTURED_OUTPUT_MODE = "frugal.structured_output_mode";
+export declare const FRUGAL_BLOCK = "frugal.block";
+export declare const FRUGAL_STABLE = "frugal.stable";
+export declare const STRUCTURED_OUTPUT_NONE = "none";
+export declare const STRUCTURED_OUTPUT_JSON_OBJECT = "json_object";
+export declare const STRUCTURED_OUTPUT_JSON_SCHEMA = "json_schema";
+export declare const STRUCTURED_OUTPUT_TOOLS = "tools";
+export declare const BLOCK_SYSTEM = "system";
+export declare const BLOCK_USER = "user";
+export declare const BLOCK_TOOLS = "tools";
+export declare const BLOCK_SCHEMA = "schema";
+export declare const CALLER_FILE_EXTERNAL = "<external>";
+export declare const CALLER_FILE_UNKNOWN = "<unknown>";
+export declare const CALLER_OVERFLOW = "<overflow>";
+//# sourceMappingURL=semconv.d.ts.map

package/dist/semconv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semconv.d.ts","sourceRoot":"","sources":["../src/semconv.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAC7C,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAC7D,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAC7D,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAC5C,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAChD,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAC5C,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC,eAAO,MAAM,OAAO,SAAS,CAAC;AAC9B,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AACpD,eAAO,MAAM,aAAa,eAAe,CAAC;AAE1C,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,YAAY,WAAW,CAAC;AAErC,eAAO,MAAM,yBAAyB,qCAAqC,CAAC;AAC5E,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,eAAO,MAAM,YAAY,wBAAwB,CAAC;AAClD,eAAO,MAAM,wBAAwB,oCAAoC,CAAC;AAC1E,eAAO,MAAM,yBAAyB,qCAAqC,CAAC;AAC5E,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AACxE,eAAO,MAAM,aAAa,yBAAyB,CAAC;AACpD,eAAO,MAAM,sBAAsB,kCAAkC,CAAC;AACtE,eAAO,MAAM,6BAA6B,yCAAyC,CAAC;AACpF,eAAO,MAAM,0BAA0B,sCAAsC,CAAC;AAC9E,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAClE,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AACpE,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAC9D,eAAO,MAAM,6BAA6B,yCAAyC,CAAC;AAEpF,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AACrD,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AACnD,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAC/D,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AACrD,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,6BAA6B,kCAAkC,CAAC;AAC7E,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAC3C,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C,eAAO,MAAM,sBAAsB,SAAS,CAAC;AAC7C,eAAO,MAAM,6BAA6B,gBAAgB,CAAC;AAC3D,eAAO,MAAM,6BAA6B,gBAAgB,CAAC;AAC3D,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAE/C,eAAO,MAAM,YAAY,WAAW,CAAC;AACrC,eAAO,MAAM,UAAU,SAAS,CAAC;AACjC,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,YAAY,WAAW,CAAC;AAErC,eAAO,MAAM,oBAAoB,eAAe,CAAC;AACjD,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAC/C,eAAO,MAAM,eAAe,eAAe,CAAC"}

package/dist/semconv.js

@@ -0,0 +1,53 @@
+// OpenTelemetry GenAI semantic convention constants + Frugal extensions.
+export const GEN_AI_SYSTEM = "gen_ai.system";
+export const GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
+export const GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
+export const GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
+export const GEN_AI_TOKEN_TYPE = "gen_ai.token.type";
+export const SYSTEM_OPENAI = "openai";
+export const SYSTEM_ANTHROPIC = "anthropic";
+export const SYSTEM_AZURE_OPENAI = "az.ai.openai";
+export const SYSTEM_AWS_BEDROCK = "aws.bedrock";
+export const SYSTEM_VERTEX_AI = "vertex_ai";
+export const SYSTEM_CUSTOM = "custom";
+export const OP_CHAT = "chat";
+export const OP_TEXT_COMPLETION = "text_completion";
+export const OP_EMBEDDINGS = "embeddings";
+export const TOKEN_INPUT = "input";
+export const TOKEN_OUTPUT = "output";
+export const METRIC_OPERATION_DURATION = "gen_ai.client.operation.duration";
+export const METRIC_TOKEN_USAGE = "gen_ai.client.token.usage";
+export const METRIC_CALLS = "frugal.gen_ai.calls";
+export const METRIC_CACHE_READ_TOKENS = "frugal.gen_ai.cache_read_tokens";
+export const METRIC_CACHE_WRITE_TOKENS = "frugal.gen_ai.cache_write_tokens";
+export const METRIC_REASONING_TOKENS = "frugal.gen_ai.reasoning_tokens";
+export const METRIC_ERRORS = "frugal.gen_ai.errors";
+export const METRIC_INTERNAL_ERRORS = "frugal.gen_ai.internal_errors";
+export const METRIC_OUTPUT_CAP_UTILIZATION = "frugal.gen_ai.output_cap_utilization";
+export const METRIC_CACHE_PREFIX_STABLE = "frugal.gen_ai.cache_prefix_stable";
+export const METRIC_HISTORY_DEPTH = "frugal.gen_ai.history_depth";
+export const METRIC_FEW_SHOT_COUNT = "frugal.gen_ai.few_shot_count";
+export const METRIC_NOISE_RATIO = "frugal.gen_ai.noise_ratio";
+export const METRIC_STRUCTURED_OUTPUT_HINT = "frugal.gen_ai.structured_output_hint";
+export const FRUGAL_CUSTOMER_ID = "frugal.customer_id";
+export const FRUGAL_PROJECT_ID = "frugal.project_id";
+export const FRUGAL_COMPONENT = "frugal.component";
+export const FRUGAL_CALLER_FILE = "frugal.caller_file";
+export const FRUGAL_CALLER_FUNCTION = "frugal.caller_function";
+export const FRUGAL_ERROR_TYPE = "frugal.error.type";
+export const FRUGAL_BATCHED = "frugal.batched";
+export const FRUGAL_STRUCTURED_OUTPUT_MODE = "frugal.structured_output_mode";
+export const FRUGAL_BLOCK = "frugal.block";
+export const FRUGAL_STABLE = "frugal.stable";
+export const STRUCTURED_OUTPUT_NONE = "none";
+export const STRUCTURED_OUTPUT_JSON_OBJECT = "json_object";
+export const STRUCTURED_OUTPUT_JSON_SCHEMA = "json_schema";
+export const STRUCTURED_OUTPUT_TOOLS = "tools";
+export const BLOCK_SYSTEM = "system";
+export const BLOCK_USER = "user";
+export const BLOCK_TOOLS = "tools";
+export const BLOCK_SCHEMA = "schema";
+export const CALLER_FILE_EXTERNAL = "<external>";
+export const CALLER_FILE_UNKNOWN = "<unknown>";
+export const CALLER_OVERFLOW = "<overflow>";
+//# sourceMappingURL=semconv.js.map

package/dist/semconv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semconv.js","sourceRoot":"","sources":["../src/semconv.ts"],"names":[],"mappings":"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"}

package/dist/streams.d.ts

@@ -0,0 +1,21 @@
+import type { CallEmitter, UsageReport } from "./instrument.js";
+export type StreamEventHandler<E = unknown> = (event: E, usage: UsageReport) => void;
+export declare class AsyncStreamProxy<E = unknown> implements AsyncIterable<E> {
+    private readonly wrapped;
+    private readonly emit;
+    private readonly handler;
+    private usage;
+    private finalized;
+    constructor(wrapped: AsyncIterable<E>, emit: CallEmitter, handler: StreamEventHandler<E>);
+    [Symbol.asyncIterator](): AsyncIterator<E>;
+    private finalizeSuccess;
+    private finalizeError;
+}
+/**
+ * Attach a tee-style proxy onto an object that is iterable AND has its own
+ * helper methods/properties (as OpenAI and Anthropic stream wrappers do).
+ * Returns a proxy that looks and behaves like the original but teases off
+ * `Symbol.asyncIterator` to our accumulator.
+ */
+export declare function wrapStreamObject<T extends object>(wrapped: T & AsyncIterable<unknown>, emit: CallEmitter, handler: StreamEventHandler): T & AsyncIterable<unknown>;
+//# sourceMappingURL=streams.d.ts.map

package/dist/streams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.d.ts","sourceRoot":"","sources":["../src/streams.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEhE,MAAM,MAAM,kBAAkB,CAAC,CAAC,GAAG,OAAO,IAAI,CAC5C,KAAK,EAAE,CAAC,EACR,KAAK,EAAE,WAAW,KACf,IAAI,CAAC;AAEV,qBAAa,gBAAgB,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAKlE,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,SAAS,CAAS;gBAGP,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAGjD,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;IAuC1C,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,aAAa;CAKtB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAC/C,OAAO,EAAE,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,EACnC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,kBAAkB,GAC1B,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAU5B"}

package/dist/streams.js

@@ -0,0 +1,85 @@
+// Stream proxy that wraps an async iterable (OpenAI and Anthropic streaming
+// responses), passes events through, accumulates per-event usage, and emits
+// metrics once on drain / close / early termination.
+export class AsyncStreamProxy {
+    wrapped;
+    emit;
+    handler;
+    usage = {};
+    finalized = false;
+    constructor(wrapped, emit, handler) {
+        this.wrapped = wrapped;
+        this.emit = emit;
+        this.handler = handler;
+    }
+    [Symbol.asyncIterator]() {
+        const inner = this.wrapped[Symbol.asyncIterator]();
+        return {
+            next: async () => {
+                let result;
+                try {
+                    result = await inner.next();
+                }
+                catch (err) {
+                    this.finalizeError(err);
+                    throw err;
+                }
+                if (result.done) {
+                    this.finalizeSuccess();
+                    return result;
+                }
+                try {
+                    this.handler(result.value, this.usage);
+                }
+                catch {
+                    // swallow handler errors — we never want to break user code
+                }
+                return result;
+            },
+            return: async (value) => {
+                this.finalizeSuccess();
+                if (typeof inner.return === "function") {
+                    return inner.return(value);
+                }
+                return { value: value, done: true };
+            },
+            throw: async (err) => {
+                this.finalizeError(err);
+                if (typeof inner.throw === "function") {
+                    return inner.throw(err);
+                }
+                throw err;
+            },
+        };
+    }
+    finalizeSuccess() {
+        if (this.finalized)
+            return;
+        this.finalized = true;
+        this.emit.success(this.usage);
+    }
+    finalizeError(err) {
+        if (this.finalized)
+            return;
+        this.finalized = true;
+        this.emit.error(err);
+    }
+}
+/**
+ * Attach a tee-style proxy onto an object that is iterable AND has its own
+ * helper methods/properties (as OpenAI and Anthropic stream wrappers do).
+ * Returns a proxy that looks and behaves like the original but teases off
+ * `Symbol.asyncIterator` to our accumulator.
+ */
+export function wrapStreamObject(wrapped, emit, handler) {
+    const proxy = new AsyncStreamProxy(wrapped, emit, handler);
+    return new Proxy(wrapped, {
+        get(target, prop, receiver) {
+            if (prop === Symbol.asyncIterator) {
+                return () => proxy[Symbol.asyncIterator]();
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+//# sourceMappingURL=streams.js.map

package/dist/streams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.js","sourceRoot":"","sources":["../src/streams.ts"],"names":[],"mappings":"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"}

package/dist/track.d.ts

@@ -0,0 +1,44 @@
+import { type UsageReport } from "./instrument.js";
+/** Metadata describing a hand-instrumented AI call. All fields optional. */
+export interface AICallInfo {
+    /** gen_ai.system — free-form (e.g. "anthropic"). Default "custom". */
+    provider?: string;
+    /** gen_ai.operation.name. Default OP_CHAT ("chat"). */
+    operation?: string;
+    /** gen_ai.request.model. Default "<unknown>". */
+    model?: string;
+    messages?: unknown;
+    system?: unknown;
+    tools?: unknown;
+    responseFormat?: unknown;
+    maxTokens?: number | null;
+}
+/**
+ * Usage data fed back to the SDK. Mirrors the core UsageReport exactly so it can
+ * be passed straight through — no parallel shape, no mapping.
+ */
+export type AIUsage = UsageReport;
+/** Manual handle for an in-flight AI call that crosses function boundaries. */
+export interface AICallHandle {
+    /** Merge usage into the call; last-write-wins per field. */
+    setUsage(usage: AIUsage): void;
+    /** Finalize as success; idempotent. */
+    end(usage?: AIUsage): void;
+    /** Finalize as error; idempotent; first finalize wins. */
+    fail(error: unknown): void;
+}
+/**
+ * Manual/try-finally form. Returns a handle whose methods are guarded no-ops
+ * when the SDK is disabled, and which never throws internal errors to the
+ * caller. Use `skipFrames: 2` and rely on `skipPackageDirs` to absorb the
+ * variable number of internal track.ts frames.
+ */
+export declare function startAICall(info?: AICallInfo): AICallHandle;
+/**
+ * Foolproof callback form, built on startAICall. Runs `fn`, passing a `report`
+ * setter to feed usage; finalizes success on return / error on throw. Supports
+ * sync and async (thenable) callbacks. The resolved value and any error always
+ * pass through untouched.
+ */
+export declare function trackAICall<T>(info: AICallInfo, fn: (report: (usage: AIUsage) => void) => T): T;
+//# sourceMappingURL=track.d.ts.map

package/dist/track.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track.d.ts","sourceRoot":"","sources":["../src/track.ts"],"names":[],"mappings":"AAeA,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAIzB,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,WAAW,CAAC;AAElC,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,uCAAuC;IACvC,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3B,0DAA0D;IAC1D,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5B;AAmCD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,UAAe,GAAG,YAAY,CAqD/D;AAkBD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,IAAI,EAAE,UAAU,EAChB,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,KAAK,CAAC,GAC1C,CAAC,CA2BH"}