@dexcost/sdk 0.2.0

package/dist/core/compute-runtime.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Active compute-runtime resolver.
+ *
+ * Cascade priority (capture spec §5.5):
+ *
+ *   1. Serverless env vars — Lambda, Fargate, Cloud Run, Cloud Functions Gen2,
+ *      Azure Functions, Vercel
+ *   2. KUBERNETES_SERVICE_HOST → k8s_pod (wins over the underlying VM so a
+ *      pod-on-EC2 is billed once as k8s_pod, not twice as k8s_pod + ec2)
+ *   3. cloud_detect IaaS fallback — EC2 / GCE / Azure VM via the existing
+ *      CloudEnv.provider resolved by cloud-detect.
+ *   4. UNKNOWN
+ *
+ * The discriminator value emitted on compute_cost events
+ * (details.billing_model) is derived from this enum in
+ * compute-accountant._billingModelFor.
+ *
+ * **String values match Python** — cross-SDK event portability. Do not change.
+ *
+ * Mirrors python/src/dexcost/compute_runtime.py.
+ */
+/**
+ * Runtime kind discriminator. String values are pinned to Python so events
+ * serialized in one SDK can be consumed by another.
+ */
+export declare const RuntimeKind: {
+    readonly Lambda: "lambda";
+    readonly Fargate: "fargate";
+    readonly Ec2: "ec2";
+    readonly CloudRun: "cloud_run";
+    readonly CloudFunctions: "cloud_functions";
+    readonly Gce: "gce";
+    readonly AzureFunctions: "azure_functions";
+    readonly AzureVm: "azure_vm";
+    readonly Vercel: "vercel_fluid";
+    readonly K8sPod: "k8s_pod";
+    readonly Unknown: "unknown";
+};
+export type RuntimeKind = (typeof RuntimeKind)[keyof typeof RuntimeKind];
+/** Return the active compute runtime for the current process. */
+export declare function resolveRuntime(): RuntimeKind;
+//# sourceMappingURL=compute-runtime.d.ts.map

package/dist/core/compute-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-runtime.d.ts","sourceRoot":"","sources":["../../src/core/compute-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;CAYd,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAMzE,iEAAiE;AACjE,wBAAgB,cAAc,IAAI,WAAW,CA+B5C"}

package/dist/core/compute-runtime.js

@@ -0,0 +1,80 @@
+/**
+ * Active compute-runtime resolver.
+ *
+ * Cascade priority (capture spec §5.5):
+ *
+ *   1. Serverless env vars — Lambda, Fargate, Cloud Run, Cloud Functions Gen2,
+ *      Azure Functions, Vercel
+ *   2. KUBERNETES_SERVICE_HOST → k8s_pod (wins over the underlying VM so a
+ *      pod-on-EC2 is billed once as k8s_pod, not twice as k8s_pod + ec2)
+ *   3. cloud_detect IaaS fallback — EC2 / GCE / Azure VM via the existing
+ *      CloudEnv.provider resolved by cloud-detect.
+ *   4. UNKNOWN
+ *
+ * The discriminator value emitted on compute_cost events
+ * (details.billing_model) is derived from this enum in
+ * compute-accountant._billingModelFor.
+ *
+ * **String values match Python** — cross-SDK event portability. Do not change.
+ *
+ * Mirrors python/src/dexcost/compute_runtime.py.
+ */
+import { getCloudEnv } from "../cloud-detect.js";
+/**
+ * Runtime kind discriminator. String values are pinned to Python so events
+ * serialized in one SDK can be consumed by another.
+ */
+export const RuntimeKind = {
+    Lambda: "lambda",
+    Fargate: "fargate",
+    Ec2: "ec2",
+    CloudRun: "cloud_run",
+    CloudFunctions: "cloud_functions",
+    Gce: "gce",
+    AzureFunctions: "azure_functions",
+    AzureVm: "azure_vm",
+    Vercel: "vercel_fluid",
+    K8sPod: "k8s_pod",
+    Unknown: "unknown",
+};
+function _isNode() {
+    return typeof process !== "undefined" && !!process.versions?.node;
+}
+/** Return the active compute runtime for the current process. */
+export function resolveRuntime() {
+    // In browser bundles process.env doesn't expose the serverless env vars
+    // — collapse straight to Unknown.
+    if (!_isNode())
+        return RuntimeKind.Unknown;
+    const env = process.env;
+    // 1. Serverless env vars — highest priority.
+    if (env.AWS_LAMBDA_FUNCTION_NAME)
+        return RuntimeKind.Lambda;
+    if (env.ECS_CONTAINER_METADATA_URI_V4 || env.ECS_CONTAINER_METADATA_URI) {
+        return RuntimeKind.Fargate;
+    }
+    if (env.K_SERVICE) {
+        // Cloud Functions Gen2 sets BOTH K_SERVICE and FUNCTION_TARGET; plain
+        // Cloud Run sets only K_SERVICE.
+        if (env.FUNCTION_TARGET)
+            return RuntimeKind.CloudFunctions;
+        return RuntimeKind.CloudRun;
+    }
+    if (env.FUNCTIONS_WORKER_RUNTIME)
+        return RuntimeKind.AzureFunctions;
+    if (env.VERCEL)
+        return RuntimeKind.Vercel;
+    // 2. Kubernetes wins over the underlying VM.
+    if (env.KUBERNETES_SERVICE_HOST)
+        return RuntimeKind.K8sPod;
+    // 3. Fall through to cloud-detect IaaS classification.
+    const cloud = getCloudEnv();
+    if (cloud.provider === "aws")
+        return RuntimeKind.Ec2;
+    if (cloud.provider === "gcp")
+        return RuntimeKind.Gce;
+    if (cloud.provider === "azure")
+        return RuntimeKind.AzureVm;
+    return RuntimeKind.Unknown;
+}
+//# sourceMappingURL=compute-runtime.js.map

package/dist/core/compute-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-runtime.js","sourceRoot":"","sources":["../../src/core/compute-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;IAClB,GAAG,EAAE,KAAK;IACV,QAAQ,EAAE,WAAW;IACrB,cAAc,EAAE,iBAAiB;IACjC,GAAG,EAAE,KAAK;IACV,cAAc,EAAE,iBAAiB;IACjC,OAAO,EAAE,UAAU;IACnB,MAAM,EAAE,cAAc;IACtB,MAAM,EAAE,SAAS;IACjB,OAAO,EAAE,SAAS;CACV,CAAC;AAIX,SAAS,OAAO;IACd,OAAO,OAAO,OAAO,KAAK,WAAW,IAAI,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC;AACpE,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,cAAc;IAC5B,wEAAwE;IACxE,kCAAkC;IAClC,IAAI,CAAC,OAAO,EAAE;QAAE,OAAO,WAAW,CAAC,OAAO,CAAC;IAE3C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAExB,6CAA6C;IAC7C,IAAI,GAAG,CAAC,wBAAwB;QAAE,OAAO,WAAW,CAAC,MAAM,CAAC;IAC5D,IAAI,GAAG,CAAC,6BAA6B,IAAI,GAAG,CAAC,0BAA0B,EAAE,CAAC;QACxE,OAAO,WAAW,CAAC,OAAO,CAAC;IAC7B,CAAC;IACD,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QAClB,sEAAsE;QACtE,iCAAiC;QACjC,IAAI,GAAG,CAAC,eAAe;YAAE,OAAO,WAAW,CAAC,cAAc,CAAC;QAC3D,OAAO,WAAW,CAAC,QAAQ,CAAC;IAC9B,CAAC;IACD,IAAI,GAAG,CAAC,wBAAwB;QAAE,OAAO,WAAW,CAAC,cAAc,CAAC;IACpE,IAAI,GAAG,CAAC,MAAM;QAAE,OAAO,WAAW,CAAC,MAAM,CAAC;IAE1C,6CAA6C;IAC7C,IAAI,GAAG,CAAC,uBAAuB;QAAE,OAAO,WAAW,CAAC,MAAM,CAAC;IAE3D,uDAAuD;IACvD,MAAM,KAAK,GAAG,WAAW,EAAE,CAAC;IAC5B,IAAI,KAAK,CAAC,QAAQ,KAAK,KAAK;QAAE,OAAO,WAAW,CAAC,GAAG,CAAC;IACrD,IAAI,KAAK,CAAC,QAAQ,KAAK,KAAK;QAAE,OAAO,WAAW,CAAC,GAAG,CAAC;IACrD,IAAI,KAAK,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,WAAW,CAAC,OAAO,CAAC;IAE3D,OAAO,WAAW,CAAC,OAAO,CAAC;AAC7B,CAAC"}

package/dist/core/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SDK configuration and API-key infrastructure.
+ *
+ * Mirrors the Python SDK's `config.py`: API keys must start with
+ * `dx_live_` or `dx_test_`, the key is resolved from the
+ * `DEXCOST_API_KEY` environment variable when not passed explicitly,
+ * and an explicit `storage: "local"` forces local-only mode.
+ */
+/** Raised when an API key has an invalid format. */
+export declare class InvalidAPIKeyError extends Error {
+    constructor(message: string);
+}
+/** Detected key type — `"live"`, `"test"`, or `undefined` when no key. */
+export type KeyType = "live" | "test";
+/**
+ * Validate an API key's format.
+ *
+ * Returns `"live"`, `"test"`, or `undefined` when `key` is undefined/null.
+ * Throws `InvalidAPIKeyError` for any other (non-empty) value.
+ */
+export declare function validateApiKey(key: string | undefined | null): KeyType | undefined;
+/** Storage mode — `"cloud"` syncs to the Control Layer, `"local"` does not. */
+export type StorageMode = "cloud" | "local";
+/** Resolved SDK configuration. */
+export interface ResolvedConfig {
+    /** The effective API key (explicit arg or `DEXCOST_API_KEY` env var). */
+    apiKey?: string;
+    /** Detected key type. */
+    keyType?: KeyType;
+    /** True when the key is a test/sandbox key. */
+    isSandbox: boolean;
+    /** Resolved storage mode. */
+    storageMode: StorageMode;
+}
+/**
+ * Resolve the effective API key and storage mode.
+ *
+ * @param apiKey - Explicit API key (takes precedence over the env var).
+ * @param storage - Explicit storage mode. `"local"` forces local-only and
+ *   skips env-var resolution; otherwise the mode is inferred from whether
+ *   a key is present.
+ */
+export declare function resolveConfig(apiKey?: string, storage?: StorageMode): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oDAAoD;AACpD,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,0EAA0E;AAC1E,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtC;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,CAclF;AAED,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,CAAC;AAE5C,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+CAA+C;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,6BAA6B;IAC7B,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,WAAW,GACpB,cAAc,CAuBhB"}

package/dist/core/config.js

@@ -0,0 +1,66 @@
+/**
+ * SDK configuration and API-key infrastructure.
+ *
+ * Mirrors the Python SDK's `config.py`: API keys must start with
+ * `dx_live_` or `dx_test_`, the key is resolved from the
+ * `DEXCOST_API_KEY` environment variable when not passed explicitly,
+ * and an explicit `storage: "local"` forces local-only mode.
+ */
+/** Raised when an API key has an invalid format. */
+export class InvalidAPIKeyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidAPIKeyError";
+    }
+}
+/**
+ * Validate an API key's format.
+ *
+ * Returns `"live"`, `"test"`, or `undefined` when `key` is undefined/null.
+ * Throws `InvalidAPIKeyError` for any other (non-empty) value.
+ */
+export function validateApiKey(key) {
+    if (key === undefined || key === null) {
+        return undefined;
+    }
+    if (key.startsWith("dx_live_")) {
+        return "live";
+    }
+    if (key.startsWith("dx_test_")) {
+        return "test";
+    }
+    throw new InvalidAPIKeyError(`Invalid API key format: key must start with 'dx_live_' or 'dx_test_', ` +
+        `got '${key.slice(0, 10)}...'`);
+}
+/**
+ * Resolve the effective API key and storage mode.
+ *
+ * @param apiKey - Explicit API key (takes precedence over the env var).
+ * @param storage - Explicit storage mode. `"local"` forces local-only and
+ *   skips env-var resolution; otherwise the mode is inferred from whether
+ *   a key is present.
+ */
+export function resolveConfig(apiKey, storage) {
+    let effectiveKey = apiKey;
+    if (effectiveKey === undefined && storage !== "local") {
+        effectiveKey = process.env.DEXCOST_API_KEY ?? undefined;
+    }
+    const keyType = validateApiKey(effectiveKey);
+    let storageMode;
+    if (storage === "local") {
+        storageMode = "local";
+    }
+    else if (effectiveKey !== undefined) {
+        storageMode = "cloud";
+    }
+    else {
+        storageMode = "local";
+    }
+    return {
+        apiKey: effectiveKey,
+        keyType,
+        isSandbox: keyType === "test",
+        storageMode,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oDAAoD;AACpD,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAKD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAA8B;IAC3D,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACtC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,IAAI,kBAAkB,CAC1B,wEAAwE;QACtE,QAAQ,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CACjC,CAAC;AACJ,CAAC;AAiBD;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAe,EACf,OAAqB;IAErB,IAAI,YAAY,GAAG,MAAM,CAAC;IAC1B,IAAI,YAAY,KAAK,SAAS,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACtD,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,SAAS,CAAC;IAC1D,CAAC;IAED,MAAM,OAAO,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IAE7C,IAAI,WAAwB,CAAC;IAC7B,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACxB,WAAW,GAAG,OAAO,CAAC;IACxB,CAAC;SAAM,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QACtC,WAAW,GAAG,OAAO,CAAC;IACxB,CAAC;SAAM,CAAC;QACN,WAAW,GAAG,OAAO,CAAC;IACxB,CAAC;IAED,OAAO;QACL,MAAM,EAAE,YAAY;QACpB,OAAO;QACP,SAAS,EAAE,OAAO,KAAK,MAAM;QAC7B,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/core/context.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Task context propagation using AsyncLocalStorage.
+ *
+ * Allows automatic association of cost events with the currently-active
+ * task without explicit parameter passing.
+ */
+import type { Task } from "./models.js";
+/**
+ * Return the currently-active Task, or undefined if no task context is set.
+ */
+export declare function getCurrentTask(): Task | undefined;
+/**
+ * Execute `fn` with `task` as the current task context.
+ *
+ * Any code running inside `fn` (including async continuations) can call
+ * `getCurrentTask()` to retrieve the task.
+ */
+export declare function runWithTask<T>(task: Task, fn: () => T): T;
+/**
+ * Set the current task for the remaining async execution context.
+ *
+ * Uses `AsyncLocalStorage.enterWith()` (Node 18+) so the task is visible
+ * to all subsequent code in the current async chain without wrapping in
+ * a callback.
+ */
+export declare function setCurrentTask(task: Task): void;
+/**
+ * Ambient context for automatic cost attribution.
+ *
+ * Set once at request/job start (e.g., in Express middleware) and any
+ * auto-instrumented LLM call without an explicit task will inherit
+ * customerId, projectId, and metadata from this context.
+ */
+export interface DexcostContext {
+    customerId?: string;
+    projectId?: string;
+    metadata?: Record<string, unknown>;
+    agent?: string;
+}
+/**
+ * Set the ambient DexcostContext for the current async execution context.
+ *
+ * Uses `AsyncLocalStorage.enterWith()` (Node 18+) so the context is visible
+ * to all code in the remaining async chain without wrapping in a callback.
+ *
+ * For concurrent request isolation (web servers), call this inside a
+ * per-request middleware or use `runWithTask()` which isolates its own
+ * async context.
+ */
+export declare function setContext(ctx: {
+    customerId?: string;
+    projectId?: string;
+    metadata?: Record<string, unknown>;
+    agent?: string;
+}): void;
+/**
+ * Return the current DexcostContext, or undefined if none is set.
+ */
+export declare function getContext(): DexcostContext | undefined;
+/**
+ * Clear the ambient DexcostContext for the current async execution context.
+ */
+export declare function clearContext(): void;
+/**
+ * Returns `true` when the current async scope has suppressed `network`
+ * event emission. Bytes are still counted into the accountant; only the
+ * standalone event is withheld.
+ */
+export declare function isNetworkEventSuppressed(): boolean;
+/**
+ * Run `fn` (sync or async) inside a scope where `network`-event emission
+ * is suppressed. Used by LLM instruments around their fetch call so the
+ * call doesn't double-emit (llm_call + network).
+ */
+export declare function suppressNetworkEvent<T>(fn: () => T): T;
+//# sourceMappingURL=context.d.ts.map

package/dist/core/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAIxC;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,GAAG,SAAS,CAEjD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEzD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAE/C;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,IAAI,CAOP;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,cAAc,GAAG,SAAS,CAEvD;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAcD;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtD"}

package/dist/core/context.js

@@ -0,0 +1,91 @@
+/**
+ * Task context propagation using AsyncLocalStorage.
+ *
+ * Allows automatic association of cost events with the currently-active
+ * task without explicit parameter passing.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const taskStore = new AsyncLocalStorage();
+/**
+ * Return the currently-active Task, or undefined if no task context is set.
+ */
+export function getCurrentTask() {
+    return taskStore.getStore();
+}
+/**
+ * Execute `fn` with `task` as the current task context.
+ *
+ * Any code running inside `fn` (including async continuations) can call
+ * `getCurrentTask()` to retrieve the task.
+ */
+export function runWithTask(task, fn) {
+    return taskStore.run(task, fn);
+}
+/**
+ * Set the current task for the remaining async execution context.
+ *
+ * Uses `AsyncLocalStorage.enterWith()` (Node 18+) so the task is visible
+ * to all subsequent code in the current async chain without wrapping in
+ * a callback.
+ */
+export function setCurrentTask(task) {
+    taskStore.enterWith(task);
+}
+const contextStore = new AsyncLocalStorage();
+/**
+ * Set the ambient DexcostContext for the current async execution context.
+ *
+ * Uses `AsyncLocalStorage.enterWith()` (Node 18+) so the context is visible
+ * to all code in the remaining async chain without wrapping in a callback.
+ *
+ * For concurrent request isolation (web servers), call this inside a
+ * per-request middleware or use `runWithTask()` which isolates its own
+ * async context.
+ */
+export function setContext(ctx) {
+    contextStore.enterWith({
+        customerId: ctx.customerId,
+        projectId: ctx.projectId,
+        metadata: ctx.metadata ?? {},
+        agent: ctx.agent,
+    });
+}
+/**
+ * Return the current DexcostContext, or undefined if none is set.
+ */
+export function getContext() {
+    return contextStore.getStore();
+}
+/**
+ * Clear the ambient DexcostContext for the current async execution context.
+ */
+export function clearContext() {
+    contextStore.enterWith({});
+}
+// ---------------------------------------------------------------------------
+// Per-call network-event suppression flag (v1 §5.3 invariant)
+// ---------------------------------------------------------------------------
+//
+// When set, the HTTP adapter still records bytes into the NetworkAccountant
+// but does NOT emit a standalone `network` event. LLM instruments wrap
+// their outbound fetch call inside suppressNetworkEvent(...) so each call
+// produces at most one of {llm_call, external_cost, network} — the v1
+// §5.3 "≤ 1 event per HTTP call" invariant.
+const suppressStore = new AsyncLocalStorage();
+/**
+ * Returns `true` when the current async scope has suppressed `network`
+ * event emission. Bytes are still counted into the accountant; only the
+ * standalone event is withheld.
+ */
+export function isNetworkEventSuppressed() {
+    return suppressStore.getStore() === true;
+}
+/**
+ * Run `fn` (sync or async) inside a scope where `network`-event emission
+ * is suppressed. Used by LLM instruments around their fetch call so the
+ * call doesn't double-emit (llm_call + network).
+ */
+export function suppressNetworkEvent(fn) {
+    return suppressStore.run(true, fn);
+}
+//# sourceMappingURL=context.js.map

package/dist/core/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,MAAM,SAAS,GAAG,IAAI,iBAAiB,EAAQ,CAAC;AAEhD;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,SAAS,CAAC,QAAQ,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAI,IAAU,EAAE,EAAW;IACpD,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAU;IACvC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAoBD,MAAM,YAAY,GAAG,IAAI,iBAAiB,EAAkB,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,GAK1B;IACC,YAAY,CAAC,SAAS,CAAC;QACrB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,QAAQ,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE;QAC5B,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,YAAY,CAAC,QAAQ,EAAE,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,YAAY,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED,8EAA8E;AAC9E,8DAA8D;AAC9D,8EAA8E;AAC9E,EAAE;AACF,4EAA4E;AAC5E,uEAAuE;AACvE,0EAA0E;AAC1E,sEAAsE;AACtE,4CAA4C;AAE5C,MAAM,aAAa,GAAG,IAAI,iBAAiB,EAAW,CAAC;AAEvD;;;;GAIG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,aAAa,CAAC,QAAQ,EAAE,KAAK,IAAI,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAI,EAAW;IACjD,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AACrC,CAAC"}

package/dist/core/fargate-metadata.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Fargate ECS task metadata reader (node-only, browser-safe).
+ *
+ * Hits `${ECS_CONTAINER_METADATA_URI_V4}/task` (or v3) once per process and
+ * caches the parsed result. Exposes vcpuCount (number) and
+ * memoryBytesLimit (number — converted from MiB per Decision #7).
+ *
+ * Fail-silent contract (convention §9): unreachable endpoint, malformed JSON,
+ * missing fields all return `null` and log once via convention §11.
+ *
+ * Mirrors python/src/dexcost/fargate_metadata.py.
+ */
+export interface FargateTaskMetadata {
+    vcpuCount: number;
+    memoryBytesLimit: number;
+}
+/** Test-only — clear cached state. */
+export declare function _resetForTests(): void;
+export declare function _setFetchForTests(impl: typeof fetch | null): void;
+/**
+ * Read + cache the ECS task metadata. Idempotent.
+ *
+ * Returns `null` when not on Fargate, when the endpoint is unreachable,
+ * or when the Limits block is missing / malformed.
+ */
+export declare function fetchFargateMetadata(): Promise<FargateTaskMetadata | null>;
+//# sourceMappingURL=fargate-metadata.d.ts.map

package/dist/core/fargate-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fargate-metadata.d.ts","sourceRoot":"","sources":["../../src/core/fargate-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAMD,sCAAsC;AACtC,wBAAgB,cAAc,IAAI,IAAI,CAIrC;AAID,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,KAAK,GAAG,IAAI,GAAG,IAAI,CAEjE;AAeD;;;;;GAKG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CA+DhF"}

package/dist/core/fargate-metadata.js

@@ -0,0 +1,102 @@
+/**
+ * Fargate ECS task metadata reader (node-only, browser-safe).
+ *
+ * Hits `${ECS_CONTAINER_METADATA_URI_V4}/task` (or v3) once per process and
+ * caches the parsed result. Exposes vcpuCount (number) and
+ * memoryBytesLimit (number — converted from MiB per Decision #7).
+ *
+ * Fail-silent contract (convention §9): unreachable endpoint, malformed JSON,
+ * missing fields all return `null` and log once via convention §11.
+ *
+ * Mirrors python/src/dexcost/fargate_metadata.py.
+ */
+const PROBE_TIMEOUT_MS = 250;
+let _cached = null;
+let _resolved = false;
+let _warned = false;
+/** Test-only — clear cached state. */
+export function _resetForTests() {
+    _cached = null;
+    _resolved = false;
+    _warned = false;
+}
+/** Hookable fetch — tests replace this to avoid real network calls. */
+let _fetchImpl = (...args) => fetch(...args);
+export function _setFetchForTests(impl) {
+    _fetchImpl = impl ?? ((...args) => fetch(...args));
+}
+function _isNode() {
+    return typeof process !== "undefined" && !!process.versions?.node;
+}
+function _endpoint() {
+    if (!_isNode())
+        return null;
+    const base = process.env.ECS_CONTAINER_METADATA_URI_V4 ||
+        process.env.ECS_CONTAINER_METADATA_URI;
+    if (!base)
+        return null;
+    return base.replace(/\/+$/, "") + "/task";
+}
+/**
+ * Read + cache the ECS task metadata. Idempotent.
+ *
+ * Returns `null` when not on Fargate, when the endpoint is unreachable,
+ * or when the Limits block is missing / malformed.
+ */
+export async function fetchFargateMetadata() {
+    if (_resolved)
+        return _cached;
+    const url = _endpoint();
+    if (url === null) {
+        _resolved = true;
+        return null;
+    }
+    let payload;
+    try {
+        const resp = await _fetchImpl(url, {
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        });
+        if (!resp.ok)
+            throw new Error(`HTTP ${resp.status}`);
+        payload = await resp.json();
+    }
+    catch (exc) {
+        _resolved = true;
+        if (!_warned) {
+            _warned = true;
+            // eslint-disable-next-line no-console
+            console.warn(`fargate metadata unreachable (${exc?.message ?? exc}); ` +
+                "compute cost will fall through to default rates");
+        }
+        return null;
+    }
+    const limits = typeof payload === "object" && payload !== null
+        ? payload.Limits
+        : undefined;
+    if (!limits) {
+        _resolved = true;
+        return null;
+    }
+    const cpuRaw = limits.CPU;
+    const memRaw = limits.Memory;
+    const vcpu = typeof cpuRaw === "number" ? cpuRaw : Number(cpuRaw);
+    const memMib = typeof memRaw === "number" ? memRaw : Number(memRaw);
+    if (!Number.isFinite(vcpu) ||
+        Number.isNaN(vcpu) ||
+        !Number.isFinite(memMib) ||
+        Number.isNaN(memMib)) {
+        _resolved = true;
+        return null;
+    }
+    // Decision #7 — Fargate memory is in MiB (binary), NOT MB. Convert to
+    // bytes via the binary divisor.
+    const memoryBytesLimit = Math.trunc(memMib) * 1024 * 1024;
+    const result = {
+        vcpuCount: vcpu,
+        memoryBytesLimit,
+    };
+    _cached = result;
+    _resolved = true;
+    return result;
+}
+//# sourceMappingURL=fargate-metadata.js.map

package/dist/core/fargate-metadata.js.map

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