@dexcost/sdk 0.2.0

package/dist/core/tracker.js

@@ -0,0 +1,1073 @@
+/**
+ * CostTracker — the main entry point for recording AI agent costs.
+ *
+ * Wraps business logic in tracked tasks, records cost events, and
+ * manages background flushing to a remote endpoint.
+ */
+import { randomUUID } from "node:crypto";
+import { Decimal } from "decimal.js";
+/**
+ * Decimal-based addition to defeat floating-point drift in cost
+ * accumulation. Sprint 2 Theme E / §3.3.1 (B3).
+ *
+ * Native `a + b` on `number` accumulates ~2e-16 of error per add;
+ * over 10 000 events that adds up to a visible drift in the per-
+ * task total. decimal.js does exact decimal arithmetic; we convert
+ * back to `number` at the boundary so the customer-facing field
+ * type stays `number` (full `number → string` wire-format change
+ * is deferred to a major version per plan §0.7).
+ */
+function decAdd(a, b) {
+    return new Decimal(a).plus(b).toNumber();
+}
+import { createTask, createCostEvent } from "./models.js";
+import { getCurrentTask, runWithTask } from "./context.js";
+import { EventBuffer } from "../transport/buffer.js";
+import { NetworkAccountant, registerAccountant, unregisterAccountant, } from "../adapters/network-accountant.js";
+import { EgressPricingEngine } from "../pricing/egress-pricing.js";
+import { ComputePricingEngine } from "../pricing/compute-pricing.js";
+import { RuntimeKind } from "./compute-runtime.js";
+import { GpuPricingEngine } from "../pricing/gpu-pricing.js";
+import { GpuRuntimeKind } from "./gpu-runtime.js";
+import { getCloudEnv } from "../cloud-detect.js";
+import { EventPusher } from "../transport/pusher.js";
+import { PricingEngine } from "../pricing/engine.js";
+import { RateRegistry } from "../pricing/rates.js";
+import { RetryHeuristicEngine } from "./heuristics.js";
+import { resolveConfig } from "./config.js";
+import { ALL_SUPPORTED_INSTRUMENTS, instrumentProvider, uninstrumentProvider, } from "../instruments/index.js";
+export const DEFAULT_ENDPOINT = "https://api.dexcost.io";
+/**
+ * Resolves the Control Layer endpoint from the DEXCOST_ENDPOINT env
+ * var. Sprint 1 Theme A / §2.1 (A2): only https:// URLs are accepted.
+ * An attacker who controls the env (misconfigured CI runner, hostile
+ * container) could otherwise silently exfiltrate cost telemetry to an
+ * HTTP collector — we refuse and fall back to the production default
+ * with a console.warn.
+ *
+ * Exported for testability; the CostTracker constructor is the only
+ * production caller.
+ */
+export function resolveEndpoint() {
+    const env = process.env.DEXCOST_ENDPOINT;
+    if (env === undefined || env === "") {
+        return DEFAULT_ENDPOINT;
+    }
+    if (!env.startsWith("https://")) {
+        console.warn(`dexcost: DEXCOST_ENDPOINT=${JSON.stringify(env)} rejected — only ` +
+            `https:// URLs are accepted. Falling back to ${DEFAULT_ENDPOINT}.`);
+        return DEFAULT_ENDPOINT;
+    }
+    return env;
+}
+/** Event types accepted by `recordCost` (non-LLM cost events). */
+const NON_LLM_EVENT_TYPES = new Set(["external_cost", "compute_cost"]);
+import { isDevMode, enableDevMode, logEvent, logTaskComplete } from "../dev-console.js";
+// Side-effect imports to register instruments
+import "../instruments/openai.js";
+import "../instruments/anthropic.js";
+import "../instruments/vercel-ai.js";
+import "../instruments/gemini.js";
+import "../instruments/bedrock.js";
+import "../instruments/cohere.js";
+import "../instruments/mcp.js";
+// ---------------------------------------------------------------------------
+// Singleton / init() factory
+// ---------------------------------------------------------------------------
+let _instance = null;
+/**
+ * Sprint 2 Theme E / §3.3.2 (B9) — exit-time flush handlers.
+ *
+ * Pre-fix events recorded just before `process.exit(0)` were lost:
+ * the buffered in-memory queue and the not-yet-flushed pusher batch
+ * both died with the process. These handlers run on process tear-
+ * down (graceful exit, SIGTERM, SIGINT) and synchronously close the
+ * tracker. closeAsync() flushes the pending push first.
+ *
+ * The handlers are stored so `close()` can unregister them — avoids
+ * cross-test listener-leak when init/close cycles repeatedly.
+ */
+let _exitHandlers = null;
+function _registerExitHandlers() {
+    if (_exitHandlers !== null)
+        return;
+    const beforeExit = (_code) => {
+        // Synchronous best-effort flush on graceful exit. Node will wait
+        // for any returned promise from `beforeExit` (unlike `exit`), so
+        // closeAsync's in-flight push has a chance to land.
+        void globalCloseAsync();
+    };
+    const sigterm = () => {
+        // SIGTERM: containerized environments (k8s, docker stop) deliver
+        // this 30s before SIGKILL. Run closeAsync to flush, then let the
+        // default handler take over (re-emit so other listeners run).
+        void globalCloseAsync();
+    };
+    const sigint = () => {
+        // SIGINT (Ctrl+C in dev): same flush guarantee.
+        void globalCloseAsync();
+    };
+    process.on("beforeExit", beforeExit);
+    process.on("SIGTERM", sigterm);
+    process.on("SIGINT", sigint);
+    _exitHandlers = { beforeExit, sigterm, sigint };
+}
+function _unregisterExitHandlers() {
+    if (_exitHandlers === null)
+        return;
+    if (_exitHandlers.beforeExit)
+        process.off("beforeExit", _exitHandlers.beforeExit);
+    if (_exitHandlers.sigterm)
+        process.off("SIGTERM", _exitHandlers.sigterm);
+    if (_exitHandlers.sigint)
+        process.off("SIGINT", _exitHandlers.sigint);
+    _exitHandlers = null;
+}
+export function init(options = {}) {
+    if (_instance !== null) {
+        throw new Error("dexcost already initialized — call close() first to reset");
+    }
+    _instance = new CostTracker(options);
+    _registerExitHandlers();
+    return _instance;
+}
+export function getTracker() {
+    if (_instance === null) {
+        throw new Error("dexcost not initialized — call init() first");
+    }
+    return _instance;
+}
+/**
+ * Update the SDK's API key and resume sync after auth failure.
+ *
+ * Sprint 2 Theme D / §3.2.3 (B14). When the Control Layer returns
+ * 401/403 the pusher sets `_authFailed=true` and stops; without this
+ * function the only recovery is restarting the customer's process.
+ *
+ * Returns `true` on success, `false` if `init()` has not been called
+ * (logs a console warning).
+ */
+export function setApiKey(newKey) {
+    if (_instance === null) {
+        console.warn("dexcost: setApiKey called before init(); ignoring. " +
+            "Call dexcost.init({apiKey:...}) first.");
+        return false;
+    }
+    _instance.setApiKey(newKey);
+    return true;
+}
+export async function globalTrack(opts, fn) {
+    return getTracker().track(opts, fn);
+}
+export async function globalFlush() {
+    return getTracker().flush();
+}
+export function globalClose() {
+    if (_instance !== null) {
+        _instance.close();
+        _instance = null;
+    }
+    _unregisterExitHandlers();
+}
+export async function globalCloseAsync() {
+    if (_instance !== null) {
+        await _instance.closeAsync();
+        _instance = null;
+    }
+    _unregisterExitHandlers();
+}
+/**
+ * A task that is currently being tracked.
+ *
+ * Provides methods to record cost events (LLM calls, external costs,
+ * retries) against the task.
+ */
+export class TrackedTask {
+    _task;
+    _buffer;
+    _tracker;
+    _events = [];
+    _ended = false;
+    constructor(task, buffer, tracker) {
+        this._task = task;
+        this._buffer = buffer;
+        this._tracker = tracker;
+        // Register a NetworkAccountant for this task so the patched
+        // globalThis.fetch (which sees only the task_id via AsyncLocalStorage)
+        // can record byte usage via core.getAccountant(taskId).
+        // Unregistered in end().
+        registerAccountant(task.taskId, new NetworkAccountant());
+    }
+    /** The underlying Task data. */
+    get task() {
+        return this._task;
+    }
+    /** All events recorded against this task. */
+    get events() {
+        return this._events;
+    }
+    /**
+     * Record an LLM call event.
+     *
+     * When `cost` is omitted, the cost is auto-computed via the pricing
+     * engine (mirrors Python `tracker.record_llm_call`). Accepts an
+     * options object for `error_type`, `details`, `pricingSource`, and
+     * `costConfidence`. `error_type` is stored in `details.error_type`.
+     */
+    recordLlmCall(provider, model, inputTokens, outputTokens, cost, cachedTokens, latencyMs, options = {}) {
+        let costUsd;
+        let costConfidence;
+        let pricingSource;
+        let pricingVersion = options.pricingVersion;
+        if (cost === undefined) {
+            // Auto-compute via the pricing engine (mirrors Python US-010).
+            const result = this._tracker.pricing.getCost(model, inputTokens, outputTokens, cachedTokens ?? 0);
+            costUsd = result.costUsd;
+            costConfidence = options.costConfidence ?? result.costConfidence;
+            pricingSource = options.pricingSource ?? result.pricingSource;
+            pricingVersion = pricingVersion ?? result.pricingVersion;
+        }
+        else {
+            costUsd = cost;
+            costConfidence = options.costConfidence ?? "exact";
+            pricingSource = options.pricingSource ?? "manual";
+        }
+        const details = { ...(options.details ?? {}) };
+        if (options.errorType !== undefined) {
+            details.error_type = options.errorType;
+        }
+        const event = createCostEvent({
+            eventId: randomUUID(),
+            taskId: this._task.taskId,
+            eventType: "llm_call",
+            costUsd,
+            costConfidence,
+            pricingSource,
+            pricingVersion,
+            provider,
+            model,
+            inputTokens,
+            outputTokens,
+            cachedTokens,
+            latencyMs,
+            isRetry: false,
+            details,
+        });
+        // Heuristic retry detection — must run BEFORE the event is persisted so
+        // the SQLite row reflects the detected retry. Mirrors the Python SDK,
+        // which runs the heuristic engine before `insert_event` (sync.py /
+        // tracker.py). Running it after `addEvent` would persist is_retry=0 and
+        // any later update would be a separate, easy-to-drop write.
+        const engine = this._tracker.heuristicEngine;
+        if (engine && !event.isRetry) {
+            const match = engine.check(event);
+            if (match.isRetry) {
+                event.isRetry = true;
+                event.retryReason = match.reason || "heuristic";
+                event.retryOf = match.matchedEventId;
+                event.details = { ...event.details, retry_confidence: match.confidence };
+                this._task.retryCount += 1;
+                this._task.retryCostUsd = decAdd(this._task.retryCostUsd, costUsd);
+            }
+        }
+        // Persist only after the retry fields have been finalised on `event`.
+        this._events.push(event);
+        this._buffer.addEvent(event);
+        logEvent(event, this._task.taskType);
+        // Feed the persisted event into the engine's sliding window.
+        if (engine) {
+            engine.record(event);
+        }
+        // Aggregate into task
+        this._task.llmCostUsd = decAdd(this._task.llmCostUsd, costUsd);
+        this._task.totalCostUsd = decAdd(this._task.totalCostUsd, costUsd);
+        this._task.totalInputTokens += inputTokens;
+        this._task.totalOutputTokens += outputTokens;
+        if (cachedTokens !== undefined) {
+            this._task.totalCachedTokens += cachedTokens;
+        }
+        this._buffer.upsertTask(this._task);
+        return event;
+    }
+    /**
+     * Record a non-LLM cost event (external API call, compute, etc.).
+     *
+     * `eventType` must be `"external_cost"` or `"compute_cost"`; any other
+     * value throws an Error (mirrors Python `tracker.record_cost`).
+     */
+    recordCost(service, costUsd, details, eventType = "external_cost", costConfidence = "exact", pricingSource = "manual", pricingVersion) {
+        if (!NON_LLM_EVENT_TYPES.has(eventType)) {
+            throw new Error(`event_type must be one of ${[...NON_LLM_EVENT_TYPES].sort().join(", ")}, ` +
+                `got "${eventType}"`);
+        }
+        const event = createCostEvent({
+            eventId: randomUUID(),
+            taskId: this._task.taskId,
+            eventType,
+            costUsd,
+            costConfidence,
+            pricingSource,
+            pricingVersion,
+            serviceName: service,
+            isRetry: false,
+            details: details ?? {},
+        });
+        this._events.push(event);
+        this._buffer.addEvent(event);
+        logEvent(event, this._task.taskType);
+        // Aggregate into task
+        if (eventType === "external_cost") {
+            this._task.externalCostUsd = decAdd(this._task.externalCostUsd, costUsd);
+        }
+        else if (eventType === "compute_cost") {
+            this._task.computeCostUsd = decAdd(this._task.computeCostUsd, costUsd);
+        }
+        this._task.totalCostUsd = decAdd(this._task.totalCostUsd, costUsd);
+        this._buffer.upsertTask(this._task);
+        return event;
+    }
+    /**
+     * Record a retry event.
+     */
+    markRetry(reason, cost, retryOf) {
+        const costUsd = cost ?? 0;
+        const event = createCostEvent({
+            eventId: randomUUID(),
+            taskId: this._task.taskId,
+            eventType: "retry_marker",
+            costUsd,
+            costConfidence: costUsd > 0 ? "exact" : "unknown",
+            isRetry: true,
+            retryReason: reason,
+            retryOf,
+        });
+        this._events.push(event);
+        this._buffer.addEvent(event);
+        logEvent(event, this._task.taskType);
+        // Aggregate into task
+        this._task.retryCount += 1;
+        this._task.retryCostUsd = decAdd(this._task.retryCostUsd, costUsd);
+        this._task.totalCostUsd = decAdd(this._task.totalCostUsd, costUsd);
+        this._buffer.upsertTask(this._task);
+        return event;
+    }
+    /**
+     * Link an external trace (e.g., Langfuse, LangSmith, Datadog) to this task.
+     *
+     * Stored under `metadata._trace_links` with `{ provider, trace_id }`
+     * entries — the same shape the Python SDK uses, so cross-SDK buffers
+     * interoperate.
+     */
+    linkTrace(provider, traceId) {
+        if (!this._task.metadata["_trace_links"]) {
+            this._task.metadata["_trace_links"] = [];
+        }
+        this._task.metadata["_trace_links"].push({
+            provider,
+            trace_id: traceId,
+        });
+        this._buffer.upsertTask(this._task);
+    }
+    /**
+     * Return all linked traces for this task.
+     *
+     * Each entry is a `{ provider, trace_id }` object (mirrors Python
+     * `TrackedTask.get_trace_links`).
+     */
+    getTraceLinks() {
+        const links = this._task.metadata["_trace_links"];
+        if (Array.isArray(links)) {
+            return links;
+        }
+        return [];
+    }
+    /**
+     * End the task, setting its status and ended_at timestamp.
+     */
+    end(status = "success") {
+        if (this._ended) {
+            throw new Error(`Task ${this._task.taskId} has already been ended.`);
+        }
+        this._ended = true;
+        this._task.status = status;
+        this._task.endedAt = new Date();
+        if (status === "failed") {
+            this._task.failureCount += 1;
+        }
+        // ── Network finalize — v1 byte aggregates + v2 egress pricing ────
+        // Mirrors python tracker.py:_aggregate_costs + rust TrackedTask::
+        // finalize_network + go finalizeNetwork. Tier-5 fail-silent: any
+        // throw in the egress block is logged and swallowed so a pricing
+        // bug never breaks task finalization (the task still ships with
+        // v1 + LLM/external/compute costs intact).
+        try {
+            this._finalizeNetwork();
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[dexcost] egress cost computation failed for task ${this._task.taskId}:`, err);
+            this._task.networkCostUsd = 0;
+        }
+        // ── Compute capture (v1 + v2 cost) ───────────────────────────────────
+        // Long-running runtimes emit their compute_cost event at task finalize
+        // from the cgroup diff; serverless runtimes have already emitted from
+        // the handler wrap with cost_pending=true. Either way, the v2 pricing
+        // engine back-fills cost_usd here via the deferred-cost pattern.
+        // Wrapped in Tier-5 fail-silent so a pricing throw never breaks
+        // finalize (mirrors python tracker.py:_aggregate_costs +
+        // _finalize_compute).
+        try {
+            this._finalizeCompute();
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[dexcost] compute cost computation failed for task ${this._task.taskId}:`, err);
+        }
+        // ── GPU capture (Phase 2 v1 + v2) ─────────────────────────────────────
+        // Long-running GPU runtimes (AWS_EC2_GPU / GCP_GCE_BUNDLED / etc.) emit
+        // 1 gpu_cost + N gpu_utilization_signal at task finalize from the cgroup
+        // walk + NVML snapshot diff. Serverless runtimes (Modal / RunPod /
+        // Replicate) have already emitted via the handler wrap. Either way the
+        // GpuPricingEngine back-fills gpu_cost.costUsd here via the deferred-
+        // cost pattern. gpu_utilization_signal events are NEVER priced
+        // (Decision #3 observability carve-out). Tier-5 fail-silent.
+        try {
+            this._finalizeGpu();
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[dexcost] gpu cost computation failed for task ${this._task.taskId}:`, err);
+        }
+        this._buffer.upsertTask(this._task);
+        logTaskComplete(this._task);
+    }
+    /**
+     * Compute auto-emission + back-fill at task finalize.
+     *
+     * Mirrors python tracker.py:_finalize_compute.
+     *
+     * Step 1: long-running runtime → call snapshotEndAndBuild and insert a
+     *         compute_cost event with details.cost_pending=true.
+     * Step 2: walk all compute_cost events with cost_pending=true, resolve
+     *         their cost via the pricing engine, then updateEvent to strip
+     *         the marker + stamp pricing source/confidence/version.
+     * Step 3: apply DELTA-based total adjustment — never recompute total_
+     *         cost_usd from scratch, which would blow away retry_marker
+     *         and other costs accumulated by the main loop.
+     */
+    _finalizeCompute() {
+        const task = this._task;
+        const accountant = task._compute;
+        const cloudEnv = getCloudEnv();
+        const overrides = this._tracker.computeBillingOverrides;
+        let durationMs = 0;
+        let windowS = new Decimal(0);
+        if (task.endedAt && task.startedAt) {
+            const ms = task.endedAt.getTime() - task.startedAt.getTime();
+            durationMs = Math.trunc(ms);
+            windowS = new Decimal(ms).dividedBy(1000);
+        }
+        // 1. Long-running runtimes: build + persist the cgroup-diff event.
+        const longRunning = new Set([
+            RuntimeKind.Fargate,
+            RuntimeKind.Ec2,
+            RuntimeKind.Gce,
+            RuntimeKind.AzureVm,
+            RuntimeKind.K8sPod,
+        ]);
+        const newEventIds = new Set();
+        if (accountant && longRunning.has(accountant.runtime)) {
+            const details = accountant.snapshotEndAndBuild(durationMs);
+            if (details !== null) {
+                const ev = createCostEvent({
+                    eventId: randomUUID(),
+                    taskId: task.taskId,
+                    eventType: "compute_cost",
+                    costUsd: 0,
+                    costConfidence: "unknown",
+                    isRetry: false,
+                    details,
+                });
+                this._buffer.addEvent(ev);
+                this._events.push(ev);
+                newEventIds.add(ev.eventId);
+            }
+        }
+        // 2. Back-fill cost on every compute_cost event with cost_pending=true.
+        //    Track per-event delta so we adjust totals without blowing away the
+        //    running totals already accumulated by the main loop.
+        const engine = this._tracker.computePricing;
+        const events = this._buffer.queryEvents(task.taskId);
+        let costDelta = new Decimal(0);
+        for (const ev of events) {
+            if (ev.eventType !== "compute_cost")
+                continue;
+            const details = ev.details || {};
+            if (details.cost_pending !== true)
+                continue;
+            const oldCost = new Decimal(ev.costUsd);
+            const priced = engine.resolveComputeCost(details, cloudEnv, overrides, windowS);
+            ev.costUsd = priced.costUsd.toNumber();
+            ev.pricingSource = priced.pricingSource;
+            ev.costConfidence = priced.costConfidence;
+            ev.pricingVersion = `compute:${engine.catalogVersion}`;
+            const newDetails = {};
+            for (const [k, v] of Object.entries(details)) {
+                if (k !== "cost_pending")
+                    newDetails[k] = v;
+            }
+            ev.details = newDetails;
+            this._buffer.updateEvent(ev);
+            // Delta = new - old. For newly-inserted long-running events the
+            // main loop never saw them at all, so we add the original $0 too
+            // (always 0 here, but explicit per python parity).
+            const delta = priced.costUsd.minus(oldCost);
+            costDelta = costDelta.plus(delta);
+            if (newEventIds.has(ev.eventId)) {
+                costDelta = costDelta.plus(oldCost);
+            }
+        }
+        const deltaNum = costDelta.toNumber();
+        task.computeCostUsd = decAdd(task.computeCostUsd, deltaNum);
+        task.totalCostUsd = decAdd(task.totalCostUsd, deltaNum);
+    }
+    /**
+     * GPU auto-emission + back-fill at task finalize.
+     *
+     * Mirrors python tracker.py:_finalize_gpu. Three steps:
+     *
+     *  1. Long-running GPU runtimes (AwsEc2Gpu / GcpGceBundled /
+     *     GcpGceN1Attached / AzureVmGpu / AzureVmVgpu / LambdaLabs /
+     *     CoreWeave) call accountant.snapshotEndAndBuild(durationMs) and
+     *     persist a gpu_cost event (cost_pending=true) plus N
+     *     gpu_utilization_signal events. Serverless GPU runtimes (Modal /
+     *     RunPod / Replicate) have already emitted via the handler wrap;
+     *     this step is a no-op for them.
+     *  2. Back-fills cost_usd on every gpu_cost event with cost_pending=true:
+     *     resolves rate via GpuPricingEngine.resolveGpuCost, sets cost_usd,
+     *     pricing_source, cost_confidence, pricing_version ("gpu:<version>"
+     *     — distinct from compute / egress prefixes), and strips the
+     *     internal cost_pending / _cgroup_scope_fallback /
+     *     _nvml_product_name_lower hints from details before re-persisting.
+     *  3. gpu_utilization_signal events are NEVER touched by the back-fill
+     *     walker — they stay at cost_usd=0 (Decision #3 observability
+     *     carve-out). Load-bearing convention §1 carve-out — see test
+     *     gpu-auto-emission.test.ts.
+     *
+     * Delta-based total adjustment preserves any retry_marker costs already
+     * accumulated by the main aggregation loop.
+     */
+    _finalizeGpu() {
+        const task = this._task;
+        const accountant = task._gpu;
+        const cloudEnv = getCloudEnv();
+        let durationMs = 0;
+        let windowS = new Decimal(0);
+        if (task.endedAt && task.startedAt) {
+            const ms = task.endedAt.getTime() - task.startedAt.getTime();
+            durationMs = Math.trunc(ms);
+            windowS = new Decimal(ms).dividedBy(1000);
+        }
+        // 1. Long-running GPU runtimes: snapshot + persist dual events.
+        const longRunningGpu = new Set([
+            GpuRuntimeKind.AwsEc2Gpu,
+            GpuRuntimeKind.GcpGceBundled,
+            GpuRuntimeKind.GcpGceN1Attached,
+            GpuRuntimeKind.AzureVmGpu,
+            GpuRuntimeKind.AzureVmVgpu,
+            GpuRuntimeKind.LambdaLabs,
+            GpuRuntimeKind.CoreWeave,
+        ]);
+        const newEventIds = new Set();
+        if (accountant && longRunningGpu.has(accountant.runtime)) {
+            const { costDetails, signalEvents } = accountant.snapshotEndAndBuild(durationMs);
+            if (costDetails !== null) {
+                const ev = createCostEvent({
+                    eventId: randomUUID(),
+                    taskId: task.taskId,
+                    eventType: "gpu_cost",
+                    costUsd: 0,
+                    costConfidence: "unknown",
+                    isRetry: false,
+                    details: costDetails,
+                });
+                this._buffer.addEvent(ev);
+                this._events.push(ev);
+                newEventIds.add(ev.eventId);
+            }
+            if (signalEvents) {
+                for (const sig of signalEvents) {
+                    const sev = createCostEvent({
+                        eventId: randomUUID(),
+                        taskId: task.taskId,
+                        eventType: "gpu_utilization_signal",
+                        costUsd: 0, // Decision #3 — observability only
+                        costConfidence: "unknown",
+                        isRetry: false,
+                        details: sig,
+                    });
+                    this._buffer.addEvent(sev);
+                    this._events.push(sev);
+                }
+            }
+        }
+        // 2. Back-fill cost on every gpu_cost event with cost_pending=true.
+        //    Per Decision #3, gpu_utilization_signal events are NEVER priced.
+        const engine = this._tracker.gpuPricing;
+        const events = this._buffer.queryEvents(task.taskId);
+        let costDelta = new Decimal(0);
+        for (const ev of events) {
+            if (ev.eventType !== "gpu_cost")
+                continue;
+            const details = (ev.details || {});
+            if (details.cost_pending !== true)
+                continue;
+            const oldCost = new Decimal(ev.costUsd);
+            const priced = engine.resolveGpuCost(details, cloudEnv, windowS);
+            ev.costUsd = priced.costUsd.toNumber();
+            ev.pricingSource = priced.pricingSource;
+            ev.costConfidence = priced.costConfidence;
+            ev.pricingVersion = `gpu:${engine.catalogVersion}`;
+            const newDetails = {};
+            for (const [k, v] of Object.entries(details)) {
+                if (k !== "cost_pending" &&
+                    k !== "_cgroup_scope_fallback" &&
+                    k !== "_nvml_product_name_lower") {
+                    newDetails[k] = v;
+                }
+            }
+            ev.details = newDetails;
+            this._buffer.updateEvent(ev);
+            const delta = priced.costUsd.minus(oldCost);
+            costDelta = costDelta.plus(delta);
+            if (newEventIds.has(ev.eventId)) {
+                costDelta = costDelta.plus(oldCost); // always 0; explicit
+            }
+        }
+        const deltaNum = costDelta.toNumber();
+        task.gpuCostUsd = decAdd(task.gpuCostUsd, deltaNum);
+        task.totalCostUsd = decAdd(task.totalCostUsd, deltaNum);
+    }
+    /**
+     * Snapshot the NetworkAccountant onto the task's v1 fields and (if
+     * a CloudEnv has been resolved) compute v2 egress dollars + back-fill
+     * the cost_pending network events for this task.
+     *
+     * Caller (end) wraps this in a Tier-5 fail-silent shell.
+     */
+    _finalizeNetwork() {
+        // v1 — drain the accountant into task fields. Lookup-then-unregister:
+        // late HTTP calls attributed to this task_id won't find an accountant
+        // (no orphan rows; matches Python frozen-then-snapshot).
+        const accountant = unregisterAccountant(this._task.taskId);
+        if (!accountant) {
+            // No accountant was registered (ad-hoc task creation outside
+            // CostTracker); v1 fields stay at zero.
+            return;
+        }
+        const snapshot = accountant.finalize();
+        this._task.networkBytesIn = snapshot.bytesIn;
+        this._task.networkBytesOut = snapshot.bytesOut;
+        this._task.networkCallCount = snapshot.callCount;
+        this._task.networkByHost = snapshot.byHost;
+        // v2 — egress pricing.
+        const env = getCloudEnv();
+        const engine = new EgressPricingEngine();
+        const rate = engine.resolveRate(env.provider, env.region);
+        const pricingVersion = `egress:${engine.catalogVersion}`;
+        // Convert external_bytes_out (number) to GB. Per spec §6.3 — 1 GB
+        // = 10^9 bytes, NOT 2^30. We use plain `number` here because the TS
+        // SDK uses number throughout for cost fields (a pre-existing design
+        // choice); the catalog stores rates as strings (preserved exactness
+        // at rest) and we parseFloat only at the boundary.
+        const ratePerGb = parseFloat(rate.ratePerGb);
+        const networkCostUsd = (snapshot.externalBytesOut / 1_000_000_000) * ratePerGb;
+        this._task.networkCostUsd = networkCostUsd;
+        // Stamp per-host egress_cost_usd into network_by_host[].hosts. The
+        // per-host external_bytes_out survives the LIVE_CAP overflow + top-N
+        // cap; sum(per-host egress_cost_usd) == network_cost_usd by
+        // construction (v2 §10.3 property invariant 2).
+        const byHost = this._task.networkByHost;
+        if (Array.isArray(byHost.hosts)) {
+            for (const host of byHost.hosts) {
+                const hostExternal = host["external_bytes_out"] ?? 0;
+                const hostCost = (hostExternal / 1_000_000_000) * ratePerGb;
+                host["egress_cost_usd"] = String(hostCost);
+            }
+        }
+        // v2 §6.4 — back-fill each network event for this task. Walk the
+        // buffer's stored events, find any with details.cost_pending ===
+        // true, compute their cost, strip the marker, and updateEvent to
+        // re-sync.
+        const stored = this._buffer.queryEvents(this._task.taskId);
+        for (const ev of stored) {
+            if (ev.eventType !== "network")
+                continue;
+            if (ev.details?.cost_pending !== true)
+                continue;
+            const respBytes = ev.details?.response_bytes ?? 0;
+            const reqBytes = ev.details?.request_bytes ?? 0;
+            const isInternal = ev.details?.is_internal_traffic === true;
+            const billable = isInternal ? 0 : respBytes + reqBytes;
+            const evCost = (billable / 1_000_000_000) * ratePerGb;
+            ev.costUsd = evCost;
+            ev.costConfidence = isInternal
+                ? "exact"
+                : rate.costConfidence;
+            ev.pricingVersion = pricingVersion;
+            // Strip cost_pending marker so the back-filled event is no longer
+            // "deferred-cost".
+            delete ev.details.cost_pending;
+            // Stamp egress_pricing_source so the wire payload carries the v2
+            // source detail (egress_catalog:aws:us-east-1).
+            ev.details.egress_pricing_source =
+                isInternal ? "egress_catalog:internal" : rate.pricingSource;
+            this._buffer.updateEvent(ev);
+            // First-pass total_cost_usd summed this event at 0 (cost_pending);
+            // add the back-filled cost.
+            this._task.totalCostUsd = decAdd(this._task.totalCostUsd, evCost);
+        }
+        // Add network_cost_usd to total — captures every external byte
+        // (cataloged + below-threshold un-cataloged calls included via the
+        // accountant scalar even when they emitted no per-event row).
+        this._task.totalCostUsd = decAdd(this._task.totalCostUsd, this._task.networkCostUsd);
+    }
+    /**
+     * Record a usage event priced via the rate registry.
+     */
+    recordUsage(service, units = 1, details) {
+        const rate = this._tracker.getRate(service);
+        if (rate === undefined) {
+            throw new Error(`No rate registered for service "${service}". Use tracker.registerRate("${service}", per, costUsd) first.`);
+        }
+        const costUsd = rate * units;
+        const event = createCostEvent({
+            eventId: randomUUID(),
+            taskId: this._task.taskId,
+            eventType: "external_cost",
+            costUsd,
+            costConfidence: "computed",
+            pricingSource: "rate_registry",
+            pricingVersion: this._tracker.rateRegistry.pricingVersion,
+            serviceName: service,
+            isRetry: false,
+            details: details ?? {},
+        });
+        this._events.push(event);
+        this._buffer.addEvent(event);
+        logEvent(event, this._task.taskType);
+        this._task.externalCostUsd = decAdd(this._task.externalCostUsd, costUsd);
+        this._task.totalCostUsd = decAdd(this._task.totalCostUsd, costUsd);
+        this._buffer.upsertTask(this._task);
+        return event;
+    }
+    /**
+     * Un-flag a retry event as non-retry, reversing the retry accounting.
+     * If eventId is provided, targets that specific event; otherwise targets
+     * the most recent retry event.
+     */
+    markNotRetry(eventId) {
+        let target;
+        if (eventId) {
+            target = this._events.find((e) => e.eventId === eventId && e.isRetry);
+        }
+        else {
+            for (let i = this._events.length - 1; i >= 0; i--) {
+                if (this._events[i].isRetry) {
+                    target = this._events[i];
+                    break;
+                }
+            }
+        }
+        if (!target)
+            return undefined;
+        target.isRetry = false;
+        target.retryReason = undefined;
+        target.retryOf = undefined;
+        this._task.retryCount = Math.max(0, this._task.retryCount - 1);
+        this._task.retryCostUsd = Math.max(0, this._task.retryCostUsd - target.costUsd);
+        this._buffer.upsertTask(this._task);
+        return target;
+    }
+}
+/**
+ * Main cost tracker for recording AI agent unit economics.
+ *
+ * Manages task lifecycle, event recording, and background push to
+ * a remote endpoint.
+ */
+export class CostTracker {
+    _buffer;
+    _pusher = null;
+    _options;
+    _pricing;
+    _computePricing;
+    _gpuPricing;
+    _computeBillingOverrides;
+    _k8sNodeAware;
+    _rateRegistry;
+    _heuristicEngine;
+    _instrumented = new Set();
+    _config;
+    _httpTracked = false;
+    constructor(options = {}) {
+        this._options = {
+            batchSize: 100,
+            // Sprint 3 Theme F / §4.1.3 P5: default flush 5 s, matching
+            // Python's `flush_interval=5.0`. Pre-fix the TS default was
+            // 30 s, leaving up to 6× more time for events to be lost on
+            // process exit (and inconsistent with Python's UX).
+            flushIntervalMs: 5000,
+            ...options,
+        };
+        // Resolve API key (explicit arg → DEXCOST_API_KEY env var) and storage
+        // mode. Throws InvalidAPIKeyError for a malformed key.
+        this._config = resolveConfig(this._options.apiKey, this._options.storage);
+        // Use the resolved key everywhere downstream (env-var fallback included).
+        this._options.apiKey = this._config.apiKey;
+        this._buffer = new EventBuffer(this._options.dbPath);
+        // Dev mode detection
+        const env = options?.environment ?? process.env.DEXCOST_ENV;
+        if (env === "development") {
+            enableDevMode();
+        }
+        const endpoint = resolveEndpoint();
+        const cloudMode = this._config.storageMode === "cloud" && !isDevMode();
+        if (cloudMode) {
+            this._pusher = new EventPusher(this._buffer, this._options);
+            this._pusher.start();
+        }
+        this._pricing = new PricingEngine();
+        this._computePricing = new ComputePricingEngine();
+        // GPU pricing engine (Phase 2 — bundled gpu_prices.json). No init knob
+        // needed: GPU billing models are unambiguous per provider (Modal is
+        // always per_gpu_second_active, etc.). Mirrors python tracker.py.
+        this._gpuPricing = new GpuPricingEngine();
+        this._computeBillingOverrides = { ...(options.computeBillingOverrides ?? {}) };
+        this._k8sNodeAware = options.k8sNodeAware ?? false;
+        // Start background pricing refresh in cloud mode
+        if (cloudMode && this._config.apiKey) {
+            this._pricing.setApiKey(this._config.apiKey);
+            this._pricing.startBackgroundRefresh(endpoint);
+        }
+        this._rateRegistry = new RateRegistry();
+        this._heuristicEngine = options.enableRetryHeuristics
+            ? new RetryHeuristicEngine(options.retryHeuristicWindow, options.retryHeuristicThreshold)
+            : null;
+        const instruments = options.autoInstrument ?? [...ALL_SUPPORTED_INSTRUMENTS];
+        for (const name of instruments) {
+            void this.instrument(name);
+        }
+        // Auto-track outgoing HTTP calls (default on, matches Python).
+        if (this._options.trackHttp !== false) {
+            void this._enableHttpTracking(this._options.serviceCatalogUrl);
+        }
+        // Wire the browser adapter to durable storage so trackBrowser() cost
+        // events are persisted and shipped by the pusher. Browser tracking is
+        // opt-in via the trackBrowser() wrapper (no init flag), so the buffer is
+        // wired unconditionally and used only if trackBrowser actually runs.
+        void import("../adapters/browser.js").then(({ setBrowserBuffer }) => setBrowserBuffer(this._buffer));
+    }
+    /** The resolved API-key / storage configuration. */
+    get config() {
+        return this._config;
+    }
+    /**
+     * Patch outgoing HTTP transports to auto-record external costs and,
+     * when a catalog URL is provided, refresh the service catalog.
+     */
+    async _enableHttpTracking(serviceCatalogUrl) {
+        try {
+            const { trackHttp, getServiceCatalog } = await import("../adapters/http.js");
+            trackHttp(this._buffer);
+            this._httpTracked = true;
+            if (serviceCatalogUrl) {
+                const catalog = getServiceCatalog();
+                if (catalog) {
+                    await catalog.refreshFromUrl(serviceCatalogUrl);
+                }
+            }
+        }
+        catch {
+            // HTTP tracking is best-effort — never crash init.
+        }
+    }
+    /** The underlying event buffer. */
+    get buffer() {
+        return this._buffer;
+    }
+    /** The pricing engine used for cost calculations. */
+    get pricing() {
+        return this._pricing;
+    }
+    /** The compute pricing engine — wires through to TrackedTask.end finalize. */
+    get computePricing() {
+        return this._computePricing;
+    }
+    /** The GPU pricing engine — wires through to TrackedTask.end finalize. */
+    get gpuPricing() {
+        return this._gpuPricing;
+    }
+    /** Compute billing-model dispatch overrides (e.g. cloud_run=instance). */
+    get computeBillingOverrides() {
+        return this._computeBillingOverrides;
+    }
+    /** Whether K8s node-aware pricing is enabled (reserved for follow-up). */
+    get k8sNodeAware() {
+        return this._k8sNodeAware;
+    }
+    /** The rate registry for service-based cost calculations. */
+    get rateRegistry() {
+        return this._rateRegistry;
+    }
+    /** The heuristic retry engine, or null if heuristics are disabled. */
+    get heuristicEngine() {
+        return this._heuristicEngine;
+    }
+    /** Register a per-unit rate for a named service. */
+    registerRate(service, per, costUsd) {
+        this._rateRegistry.register(service, per, costUsd);
+    }
+    /** Get the per-unit cost (in USD) for a named service, or undefined if not registered. */
+    getRate(service) {
+        return this._rateRegistry.get(service)?.costUsd;
+    }
+    /**
+     * Activate the named instrument, monkey-patching the provider library.
+     */
+    async instrument(name) {
+        if (this._instrumented.has(name))
+            return;
+        const success = await instrumentProvider(name, this._pricing, this._buffer);
+        if (success)
+            this._instrumented.add(name);
+    }
+    /**
+     * Deactivate the named instrument, restoring the original library methods.
+     */
+    uninstrument(name) {
+        uninstrumentProvider(name);
+        this._instrumented.delete(name);
+    }
+    /**
+     * Execute `fn` inside a tracked task context.
+     *
+     * Creates a new task, runs the function within an AsyncLocalStorage
+     * context, and ends the task on completion (or failure).
+     */
+    /**
+     * Manually start a task and return a `TrackedTask` handle.
+     *
+     * Use this when callbacks/context managers don't fit your architecture
+     * (e.g. Celery-style workers, multi-process pipelines). The caller
+     * **must** call `TrackedTask.end()` when the task is complete.
+     * Mirrors the Python SDK's `CostTracker.start_task`.
+     */
+    startTask(opts = {}) {
+        const parentTask = getCurrentTask();
+        const task = createTask({
+            taskId: randomUUID(),
+            taskType: opts.taskType ?? "",
+            customerId: opts.customerId,
+            projectId: opts.projectId,
+            metadata: opts.metadata ? { ...opts.metadata } : {},
+            parentTaskId: parentTask?.taskId,
+            experimentId: opts.experimentId,
+            variant: opts.variant,
+        });
+        this._buffer.upsertTask(task);
+        return new TrackedTask(task, this._buffer, this);
+    }
+    async track(opts, fn) {
+        const parentTask = getCurrentTask();
+        const task = createTask({
+            taskId: randomUUID(),
+            taskType: opts.taskType,
+            customerId: opts.customerId,
+            projectId: opts.projectId,
+            metadata: opts.metadata ? { ...opts.metadata } : {},
+            parentTaskId: parentTask?.taskId,
+            experimentId: opts.experimentId,
+            variant: opts.variant,
+        });
+        this._buffer.upsertTask(task);
+        const trackedTask = new TrackedTask(task, this._buffer, this);
+        try {
+            const result = await runWithTask(task, () => fn(trackedTask));
+            if (task.status === "pending") {
+                trackedTask.end("success");
+            }
+            return result;
+        }
+        catch (error) {
+            trackedTask.end("failed");
+            throw error;
+        }
+    }
+    /**
+     * Force an immediate flush of all buffered events to the remote endpoint.
+     */
+    async flush() {
+        if (this._pusher) {
+            await this._pusher.flush();
+        }
+    }
+    /**
+     * Update the API key on both pricing engine and pusher. Sprint 2
+     * Theme D / §3.2.3 (B14) — entry point for `dexcost.setApiKey`.
+     */
+    setApiKey(newKey) {
+        this._config = { ...this._config, apiKey: newKey };
+        this._pricing.setApiKey(newKey);
+        if (this._pusher) {
+            this._pusher.setApiKey(newKey);
+        }
+    }
+    /**
+     * Stop the background pusher and release resources.
+     */
+    close() {
+        for (const name of this._instrumented) {
+            uninstrumentProvider(name);
+        }
+        this._instrumented.clear();
+        this._disableHttpTracking();
+        if (this._pusher) {
+            // Note: flush() is async but close() is sync by contract.
+            // We call stop() which clears the interval; any in-flight push
+            // completes naturally. Use flush() before close() for guaranteed delivery.
+            this._pusher.stop();
+        }
+        this._pricing.stopBackgroundRefresh();
+        this._buffer.close();
+    }
+    /** Restore patched HTTP transports if HTTP tracking was enabled. */
+    _disableHttpTracking() {
+        if (!this._httpTracked)
+            return;
+        this._httpTracked = false;
+        void import("../adapters/http.js")
+            .then(({ untrackHttp }) => untrackHttp())
+            .catch(() => {
+            // best-effort
+        });
+    }
+    /**
+     * Flush pending events and then stop the background pusher and release resources.
+     * Prefer this over close() when you need to guarantee all events are delivered.
+     */
+    async closeAsync() {
+        for (const name of this._instrumented) {
+            uninstrumentProvider(name);
+        }
+        this._instrumented.clear();
+        this._disableHttpTracking();
+        if (this._pusher) {
+            await this._pusher.flush();
+            this._pusher.stop();
+        }
+        this._pricing.stopBackgroundRefresh();
+        this._buffer.close();
+    }
+}
+//# sourceMappingURL=tracker.js.map