@tokenrein/sdk 0.0.0-stage → 0.1.1

package/dist/direct.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Direct mode: the wrapped client calls its provider itself; Tokenrein gets usage only.
+ *
+ * Before each call the SDK asks Tokenrein whether the run may continue (`POST /v1/check`);
+ * after each response it reads the token usage (also from streams) and reports it in the
+ * background (`POST /v1/usage`). Prompts and responses never leave the process. Problems
+ * reaching Tokenrein never break a call: checks fail open and reports are dropped after retries.
+ */
+import { TokenreinError } from './errors.js';
+/** Name the provider from the client's base URL (OpenAI-compatible clients reach many). */
+export declare function providerFor(baseURL: string, fallback: string): string;
+export interface TokenUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+}
+/** Token counts from an OpenAI- or Anthropic-shaped object with a `usage` field. */
+export declare function usageFrom(obj: unknown): TokenUsage | undefined;
+/** Accumulates usage from server-sent events. */
+export declare class StreamUsage {
+    #private;
+    model: string | undefined;
+    usage: TokenUsage | undefined;
+    feed(text: string): void;
+}
+export interface Verdict {
+    allowed: boolean;
+    reason?: string;
+    scope?: string;
+    run_state?: string | null;
+    run_id?: string;
+}
+/** Talks to Tokenrein: budget checks and batched usage reports. */
+export declare class Reporter {
+    #private;
+    readonly baseURL: string;
+    readonly apiKey: string;
+    readonly checkTimeoutMs: number;
+    /** Enforced limits that recent reports said are used up: label -> time noted. */
+    readonly over: Map<string, number>;
+    constructor(baseURL: string, apiKey: string, checkTimeoutMs?: number);
+    /** Fails open when Tokenrein can't be reached. */
+    check(body: Record<string, unknown>): Promise<Verdict | undefined>;
+    report(event: Record<string, unknown>): void;
+    /** Send queued reports now. */
+    flush(): Promise<void>;
+}
+export declare function reporterFor(baseURL: string, apiKey: string): Reporter;
+/** Send every queued usage report now (call before a short-lived process exits). */
+export declare function flush(): Promise<void>;
+export declare function verdictError(v: Verdict, runId: string | undefined): TokenreinError;

package/dist/direct.js

@@ -0,0 +1,229 @@
+/**
+ * Direct mode: the wrapped client calls its provider itself; Tokenrein gets usage only.
+ *
+ * Before each call the SDK asks Tokenrein whether the run may continue (`POST /v1/check`);
+ * after each response it reads the token usage (also from streams) and reports it in the
+ * background (`POST /v1/usage`). Prompts and responses never leave the process. Problems
+ * reaching Tokenrein never break a call: checks fail open and reports are dropped after retries.
+ */
+import { BUDGET_EXCEEDED, BudgetExceeded, RUN_KILLED, RUN_PAUSED, RunKilled, RunPaused, TokenreinError } from './errors.js';
+const HOST_PROVIDERS = {
+    'api.openai.com': 'openai',
+    'api.anthropic.com': 'anthropic',
+    'generativelanguage.googleapis.com': 'google',
+    'api.groq.com': 'groq',
+    'api.mistral.ai': 'mistral',
+    'api.deepseek.com': 'deepseek',
+    'api.x.ai': 'xai',
+    'openrouter.ai': 'openrouter',
+    'api.together.xyz': 'together',
+    'api.fireworks.ai': 'fireworks',
+    'api.cohere.ai': 'cohere',
+    'api.cohere.com': 'cohere',
+};
+/** Name the provider from the client's base URL (OpenAI-compatible clients reach many). */
+export function providerFor(baseURL, fallback) {
+    let url;
+    try {
+        url = new URL(baseURL);
+    }
+    catch {
+        return fallback;
+    }
+    const host = url.hostname.toLowerCase();
+    if (HOST_PROVIDERS[host])
+        return HOST_PROVIDERS[host];
+    if (host.endsWith('.openai.azure.com'))
+        return 'openai';
+    if (['localhost', '127.0.0.1', '[::1]', '::1'].includes(host)) {
+        // Well-known local model servers are free; any other local address may be a gateway to
+        // paid models, so it is priced by model name.
+        return { '11434': 'ollama', '1234': 'lmstudio', '8000': 'vllm' }[url.port] ?? fallback;
+    }
+    return fallback;
+}
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+/** Token counts from an OpenAI- or Anthropic-shaped object with a `usage` field. */
+export function usageFrom(obj) {
+    const u = obj?.usage;
+    if (!u || typeof u !== 'object')
+        return undefined;
+    const nested = (a, b) => num(u[a]?.[b]);
+    if ('prompt_tokens' in u) {
+        const cached = nested('prompt_tokens_details', 'cached_tokens');
+        return { input_tokens: Math.max(0, num(u.prompt_tokens) - cached), output_tokens: num(u.completion_tokens), cache_read_tokens: cached, cache_write_tokens: 0 };
+    }
+    if ('input_tokens_details' in u || 'output_tokens_details' in u) {
+        const cached = nested('input_tokens_details', 'cached_tokens');
+        return { input_tokens: Math.max(0, num(u.input_tokens) - cached), output_tokens: num(u.output_tokens), cache_read_tokens: cached, cache_write_tokens: 0 };
+    }
+    if ('input_tokens' in u || 'output_tokens' in u) {
+        return {
+            input_tokens: num(u.input_tokens),
+            output_tokens: num(u.output_tokens),
+            cache_read_tokens: num(u.cache_read_input_tokens),
+            cache_write_tokens: num(u.cache_creation_input_tokens),
+        };
+    }
+    return undefined;
+}
+/** Accumulates usage from server-sent events. */
+export class StreamUsage {
+    model;
+    usage;
+    #buf = '';
+    feed(text) {
+        this.#buf += text;
+        let i;
+        while ((i = this.#buf.indexOf('\n')) >= 0) {
+            const line = this.#buf.slice(0, i).trim();
+            this.#buf = this.#buf.slice(i + 1);
+            this.#line(line);
+        }
+    }
+    #line(line) {
+        if (!line.startsWith('data:'))
+            return;
+        const data = line.slice(5).trim();
+        if (!data || data === '[DONE]')
+            return;
+        let ev;
+        try {
+            ev = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (!ev || typeof ev !== 'object')
+            return;
+        if (ev.type === 'message_start') {
+            this.model = ev.message?.model ?? this.model;
+            this.usage = usageFrom(ev.message) ?? this.usage;
+        }
+        else if (ev.type === 'message_delta') {
+            if (typeof ev.usage?.output_tokens === 'number') {
+                this.usage = { input_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, ...this.usage, output_tokens: ev.usage.output_tokens };
+            }
+        }
+        else if (ev.type === 'response.completed') {
+            this.model = ev.response?.model ?? this.model;
+            this.usage = usageFrom(ev.response) ?? this.usage;
+        }
+        else {
+            this.model = ev.model ?? this.model;
+            this.usage = usageFrom(ev) ?? this.usage;
+        }
+    }
+}
+/** Talks to Tokenrein: budget checks and batched usage reports. */
+export class Reporter {
+    baseURL;
+    apiKey;
+    checkTimeoutMs;
+    /** Enforced limits that recent reports said are used up: label -> time noted. */
+    over = new Map();
+    #queue = [];
+    #timer;
+    #inflight = Promise.resolve();
+    constructor(baseURL, apiKey, checkTimeoutMs = 2000) {
+        this.baseURL = baseURL;
+        this.apiKey = apiKey;
+        this.checkTimeoutMs = checkTimeoutMs;
+    }
+    async #post(path, body, timeoutMs) {
+        return globalThis.fetch(this.baseURL + path, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${this.apiKey}`, 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    /** Fails open when Tokenrein can't be reached. */
+    async check(body) {
+        let res;
+        try {
+            res = await this.#post('/v1/check', body, this.checkTimeoutMs);
+        }
+        catch {
+            return undefined;
+        }
+        if (res.status === 401) {
+            throw new TokenreinError('Tokenrein rejected the API key (TOKENREIN_API_KEY)', { errorType: 'tokenrein_unauthorized', status: 401 });
+        }
+        if (!res.ok)
+            return undefined;
+        try {
+            return (await res.json());
+        }
+        catch {
+            return undefined;
+        }
+    }
+    report(event) {
+        if (this.#queue.length >= 10_000)
+            return;
+        this.#queue.push(event);
+        if (!this.#timer) {
+            this.#timer = setTimeout(() => {
+                this.#timer = undefined;
+                this.#inflight = this.#inflight.then(() => this.#send());
+            }, 200);
+            this.#timer.unref?.();
+        }
+    }
+    /** Send queued reports now. */
+    async flush() {
+        if (this.#timer) {
+            clearTimeout(this.#timer);
+            this.#timer = undefined;
+            this.#inflight = this.#inflight.then(() => this.#send());
+        }
+        await this.#inflight;
+    }
+    async #send() {
+        while (this.#queue.length) {
+            const batch = this.#queue.splice(0, 100);
+            for (let attempt = 0; attempt < 3; attempt++) {
+                try {
+                    const res = await this.#post('/v1/usage', { events: batch }, 10_000);
+                    if (res.ok) {
+                        const out = (await res.json());
+                        const now = Date.now();
+                        for (const label of out.over ?? [])
+                            this.over.set(label, now);
+                        break;
+                    }
+                    if (res.status < 500)
+                        break;
+                }
+                catch {
+                    // retry below
+                }
+                await new Promise((r) => setTimeout(r, 300 * (attempt + 1)));
+            }
+        }
+    }
+}
+const reporters = new Map();
+export function reporterFor(baseURL, apiKey) {
+    const key = `${baseURL}\u0000${apiKey}`;
+    let r = reporters.get(key);
+    if (!r) {
+        r = new Reporter(baseURL, apiKey);
+        reporters.set(key, r);
+    }
+    return r;
+}
+/** Send every queued usage report now (call before a short-lived process exits). */
+export async function flush() {
+    await Promise.all([...reporters.values()].map((r) => r.flush()));
+}
+export function verdictError(v, runId) {
+    const message = v.reason ?? 'Tokenrein refused the call';
+    const id = v.run_id ?? runId;
+    if (v.run_state === 'killed')
+        return new RunKilled(message, { runId: id, errorType: RUN_KILLED });
+    if (v.run_state === 'paused')
+        return new RunPaused(message, { runId: id, errorType: RUN_PAUSED });
+    return new BudgetExceeded(message, { runId: id, errorType: BUDGET_EXCEEDED });
+}

package/dist/env.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `TOKENREIN_<name>` from the environment, or the name used before the product was renamed
+ * (read with a deprecation warning until v1.1).
+ */
+export declare function envVar(name: string): string | undefined;

package/dist/env.js

@@ -0,0 +1,17 @@
+const warned = new Set();
+/**
+ * `TOKENREIN_<name>` from the environment, or the name used before the product was renamed
+ * (read with a deprecation warning until v1.1).
+ */
+export function envVar(name) {
+    const value = process.env[`TOKENREIN_${name}`];
+    if (value)
+        return value;
+    const old = `TOKENLENS_${name}`; // pre-rename name
+    const legacy = process.env[old];
+    if (legacy && !warned.has(old)) {
+        warned.add(old);
+        process.emitWarning(`${old} is deprecated; set TOKENREIN_${name}`, 'DeprecationWarning');
+    }
+    return legacy || undefined;
+}

package/dist/errors.d.ts

@@ -0,0 +1,51 @@
+/** Errors raised when the Tokenrein proxy (or the local fallback cap) stops a call. */
+export declare const BUDGET_EXCEEDED = "tokenrein_budget_exceeded";
+export declare const RUN_PAUSED = "tokenrein_run_paused";
+export declare const RUN_KILLED = "tokenrein_run_killed";
+export declare const LOCAL_CAP_EXCEEDED = "tokenrein_local_cap_exceeded";
+/**
+ * Base class for every Tokenrein error.
+ *
+ * Errors from the proxy are the provider SDK's own error objects (e.g. `OpenAI.APIError`,
+ * `Anthropic.PermissionDeniedError`) re-labelled as Tokenrein errors, so both
+ * `err instanceof BudgetExceeded` and existing `err instanceof OpenAI.APIError` checks work.
+ */
+export declare class TokenreinError extends Error {
+    /** The run the proxy evaluated (response header `x-tr-run-id`), if known. */
+    runId: string | undefined;
+    /** The proxy's error type, e.g. `tokenrein_budget_exceeded`. */
+    errorType: string;
+    /** HTTP status from the proxy; `undefined` for local errors. */
+    status: number | undefined;
+    constructor(message: string, opts: {
+        runId?: string;
+        errorType: string;
+        status?: number;
+    });
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/** HTTP 402: the call would put the run (or an ancestor, agent, project or org) over budget. */
+export declare class BudgetExceeded extends TokenreinError {
+}
+/** HTTP 403: the run or one of its ancestors was paused or killed. */
+export declare class RunStopped extends TokenreinError {
+}
+/** HTTP 403 `tokenrein_run_paused`: resume the run from the dashboard or admin API. */
+export declare class RunPaused extends RunStopped {
+}
+/** HTTP 403 `tokenrein_run_killed`: the run is blocked permanently. */
+export declare class RunKilled extends RunStopped {
+}
+/** The in-process `maxCalls` cap of a run was reached; the request was not sent. */
+export declare class LocalCapExceeded extends BudgetExceeded {
+}
+/**
+ * `[type, message]` from an OpenAI-shaped `{"error": {...}}` or Anthropic-shaped
+ * `{"type": "error", "error": {...}}` body.
+ */
+export declare function parseError(body: unknown): [string | undefined, string | undefined];
+/**
+ * Re-label the SDK's error for a proxy response as a Tokenrein error, in place.
+ * Returns `sdkError` unchanged when the response is not a Tokenrein 402/403.
+ */
+export declare function relabel<E extends Error>(sdkError: E, status: number, body: unknown, runId: string | undefined): E;

package/dist/errors.js

@@ -0,0 +1,90 @@
+/** Errors raised when the Tokenrein proxy (or the local fallback cap) stops a call. */
+export const BUDGET_EXCEEDED = 'tokenrein_budget_exceeded';
+export const RUN_PAUSED = 'tokenrein_run_paused';
+export const RUN_KILLED = 'tokenrein_run_killed';
+export const LOCAL_CAP_EXCEEDED = 'tokenrein_local_cap_exceeded';
+/** Set on SDK errors that Tokenrein re-labels; points at the Tokenrein class they belong to. */
+const KIND = Symbol.for('tokenrein.errorKind');
+/**
+ * Base class for every Tokenrein error.
+ *
+ * Errors from the proxy are the provider SDK's own error objects (e.g. `OpenAI.APIError`,
+ * `Anthropic.PermissionDeniedError`) re-labelled as Tokenrein errors, so both
+ * `err instanceof BudgetExceeded` and existing `err instanceof OpenAI.APIError` checks work.
+ */
+export class TokenreinError extends Error {
+    /** The run the proxy evaluated (response header `x-tr-run-id`), if known. */
+    runId;
+    /** The proxy's error type, e.g. `tokenrein_budget_exceeded`. */
+    errorType;
+    /** HTTP status from the proxy; `undefined` for local errors. */
+    status;
+    constructor(message, opts) {
+        super(message);
+        this.name = new.target.name;
+        this.runId = opts.runId;
+        this.errorType = opts.errorType;
+        this.status = opts.status;
+    }
+    static [Symbol.hasInstance](value) {
+        if (Function.prototype[Symbol.hasInstance].call(this, value))
+            return true;
+        const kind = value?.[KIND];
+        return typeof kind === 'function' && (kind === this || kind.prototype instanceof this);
+    }
+}
+/** HTTP 402: the call would put the run (or an ancestor, agent, project or org) over budget. */
+export class BudgetExceeded extends TokenreinError {
+}
+/** HTTP 403: the run or one of its ancestors was paused or killed. */
+export class RunStopped extends TokenreinError {
+}
+/** HTTP 403 `tokenrein_run_paused`: resume the run from the dashboard or admin API. */
+export class RunPaused extends RunStopped {
+}
+/** HTTP 403 `tokenrein_run_killed`: the run is blocked permanently. */
+export class RunKilled extends RunStopped {
+}
+/** The in-process `maxCalls` cap of a run was reached; the request was not sent. */
+export class LocalCapExceeded extends BudgetExceeded {
+}
+const BY_STATUS_AND_TYPE = {
+    [`402 ${BUDGET_EXCEEDED}`]: BudgetExceeded,
+    [`403 ${RUN_PAUSED}`]: RunPaused,
+    [`403 ${RUN_KILLED}`]: RunKilled,
+};
+/**
+ * `[type, message]` from an OpenAI-shaped `{"error": {...}}` or Anthropic-shaped
+ * `{"type": "error", "error": {...}}` body.
+ */
+export function parseError(body) {
+    const err = body?.error;
+    if (!err || typeof err !== 'object')
+        return [undefined, undefined];
+    const { type, message } = err;
+    return [typeof type === 'string' ? type : undefined, typeof message === 'string' ? message : undefined];
+}
+/**
+ * Re-label the SDK's error for a proxy response as a Tokenrein error, in place.
+ * Returns `sdkError` unchanged when the response is not a Tokenrein 402/403.
+ */
+export function relabel(sdkError, status, body, runId) {
+    const [type, message] = parseError(body);
+    const cls = type && BY_STATUS_AND_TYPE[`${status} ${type}`];
+    if (!cls || !type)
+        return sdkError;
+    const firstLine = `${sdkError.name}: ${sdkError.message}`;
+    Object.defineProperty(sdkError, KIND, { value: cls });
+    const fields = {
+        name: cls.name,
+        message: message ?? sdkError.message,
+        runId,
+        errorType: type,
+        status,
+    };
+    Object.assign(sdkError, fields);
+    if (typeof sdkError.stack === 'string' && sdkError.stack.startsWith(firstLine)) {
+        sdkError.stack = `${sdkError.name}: ${sdkError.message}` + sdkError.stack.slice(firstLine.length);
+    }
+    return sdkError;
+}

package/dist/guard.d.ts

@@ -0,0 +1,16 @@
+import { type GuardOptions } from './clients.js';
+export { flush } from './direct.js';
+export { run, currentRun, Run, type RunOptions } from './run.js';
+export type { GuardOptions } from './clients.js';
+/**
+ * Return a copy of an `OpenAI` client guarded by Tokenrein. Works with any provider the
+ * `openai` SDK reaches through `baseURL` (OpenAI, Azure, Gemini, Groq, Mistral, DeepSeek, xAI,
+ * OpenRouter, Together, Ollama, vLLM, ...).
+ *
+ * ```ts
+ * const client = guard.openai(new OpenAI(), { agent: 'support-bot' });
+ * ```
+ */
+export declare function openai<T>(client: T, options?: GuardOptions): T;
+/** Return a copy of an `Anthropic` client guarded by Tokenrein. Options as {@link openai}. */
+export declare function anthropic<T>(client: T, options?: GuardOptions): T;

package/dist/guard.js

@@ -0,0 +1,38 @@
+import { envVar } from './env.js';
+import { resolveApiKey, resolveBaseURL, wrap, wrapDirect } from './clients.js';
+export { flush } from './direct.js';
+function direct(options) {
+    const mode = options.mode ?? envVar('MODE') ?? 'direct';
+    if (mode !== 'direct' && mode !== 'proxy')
+        throw new TypeError("mode must be 'direct' or 'proxy'");
+    return mode === 'direct';
+}
+function directOptions(options, defaultProvider) {
+    return {
+        tokenreinURL: resolveBaseURL(options.baseURL),
+        apiKey: resolveApiKey(options.apiKey),
+        agent: options.agent,
+        user: options.user,
+        defaultProvider,
+        check: options.check ?? true,
+    };
+}
+export { run, currentRun, Run } from './run.js';
+/**
+ * Return a copy of an `OpenAI` client guarded by Tokenrein. Works with any provider the
+ * `openai` SDK reaches through `baseURL` (OpenAI, Azure, Gemini, Groq, Mistral, DeepSeek, xAI,
+ * OpenRouter, Together, Ollama, vLLM, ...).
+ *
+ * ```ts
+ * const client = guard.openai(new OpenAI(), { agent: 'support-bot' });
+ * ```
+ */
+export function openai(client, options = {}) {
+    return direct(options) ? wrapDirect(client, directOptions(options, 'openai'), 'openai') : wrap(client, options, 'openai');
+}
+/** Return a copy of an `Anthropic` client guarded by Tokenrein. Options as {@link openai}. */
+export function anthropic(client, options = {}) {
+    return direct(options)
+        ? wrapDirect(client, directOptions(options, 'anthropic'), 'anthropic')
+        : wrap(client, options, 'anthropic');
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * as guard from './guard.js';
+export { flush } from './direct.js';
+export { Run, currentRun, type RunOptions } from './run.js';
+export type { GuardOptions } from './clients.js';
+export { TokenreinError, BudgetExceeded, LocalCapExceeded, RunStopped, RunPaused, RunKilled, BUDGET_EXCEEDED, RUN_PAUSED, RUN_KILLED, LOCAL_CAP_EXCEEDED, } from './errors.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * as guard from './guard.js';
+export { flush } from './direct.js';
+export { Run, currentRun } from './run.js';
+export { TokenreinError, BudgetExceeded, LocalCapExceeded, RunStopped, RunPaused, RunKilled, BUDGET_EXCEEDED, RUN_PAUSED, RUN_KILLED, LOCAL_CAP_EXCEEDED, } from './errors.js';

package/dist/run.d.ts

@@ -0,0 +1,52 @@
+/** Run scopes: which run (and parent run) the current async context is executing in. */
+export declare function validateId(value: string, what: string): string;
+/** Users may be emails. */
+export declare function validateUser(value: string): string;
+export declare function newRunId(): string;
+export interface RunOptions {
+    /** Run id (1-128 of `A-Z a-z 0-9 . _ -`). Generated when omitted. */
+    runId?: string;
+    /** Budget for this run (`x-tr-run-budget-usd`), fixed by the proxy on first use. */
+    budgetUsd?: number;
+    /** Agent name for clients wrapped without `agent`. Not inherited by child runs. */
+    agent?: string;
+    /**
+     * Person or service the run works for (`x-tr-user`), for spend reports by user. Inherited by
+     * child runs; a client's own `user` takes precedence.
+     */
+    user?: string;
+    /**
+     * Local fallback cap: at most this many requests in this run (including its child runs),
+     * counted in this process and enforced even if the proxy is unreachable. Exceeding it
+     * throws {@link LocalCapExceeded} before the request is sent. SDK retries are not counted.
+     */
+    maxCalls?: number;
+}
+/** One agent run. Created by `guard.run`; read it with `currentRun()`. */
+export declare class Run {
+    #private;
+    readonly runId: string;
+    readonly budgetUsd: number | undefined;
+    readonly agent: string | undefined;
+    readonly user: string | undefined;
+    readonly maxCalls: number | undefined;
+    readonly parent: Run | undefined;
+    constructor(options?: RunOptions, parent?: Run);
+    get parentRunId(): string | undefined;
+    /** Requests made in this run and its child runs (SDK retries are not counted). */
+    get calls(): number;
+    /** Count one call against this run and every ancestor, or throw if a cap is hit. */
+    recordCall(): void;
+    headers(): Record<string, string>;
+}
+/** The innermost active run in this async context, or `undefined`. */
+export declare function currentRun(): Run | undefined;
+/**
+ * Run `fn` inside a new run. Every request made by a guarded client inside `fn` (including
+ * in awaited promises, timers and child tasks it starts) carries the run's headers. Runs
+ * nest: a run started inside another sends `x-tr-parent-run-id`.
+ *
+ * Returns whatever `fn` returns (a promise if `fn` is async).
+ */
+export declare function run<T>(fn: (run: Run) => T): T;
+export declare function run<T>(options: RunOptions | string | undefined, fn: (run: Run) => T): T;

package/dist/run.js

@@ -0,0 +1,93 @@
+/** Run scopes: which run (and parent run) the current async context is executing in. */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { LOCAL_CAP_EXCEEDED, LocalCapExceeded } from './errors.js';
+// Same rule the proxy applies to run ids and agent names.
+const ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+const storage = new AsyncLocalStorage();
+export function validateId(value, what) {
+    if (typeof value !== 'string' || !ID_RE.test(value)) {
+        throw new TypeError(`${what} must be 1-128 letters, digits, '.', '_' or '-' (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+const USER_RE = /^[A-Za-z0-9._@+-]{1,128}$/;
+/** Users may be emails. */
+export function validateUser(value) {
+    if (typeof value !== 'string' || !USER_RE.test(value)) {
+        throw new TypeError(`user must be 1-128 letters, digits, '.', '_', '-', '@' or '+' (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+export function newRunId() {
+    return `run_${randomUUID().replaceAll('-', '')}`;
+}
+/** One agent run. Created by `guard.run`; read it with `currentRun()`. */
+export class Run {
+    runId;
+    budgetUsd;
+    agent;
+    user;
+    maxCalls;
+    parent;
+    #calls = 0;
+    constructor(options = {}, parent) {
+        this.runId = options.runId !== undefined ? validateId(options.runId, 'runId') : newRunId();
+        const { budgetUsd, maxCalls } = options;
+        if (budgetUsd !== undefined && (typeof budgetUsd !== 'number' || !Number.isFinite(budgetUsd) || budgetUsd <= 0)) {
+            throw new RangeError('budgetUsd must be a positive number of US dollars');
+        }
+        if (maxCalls !== undefined && (!Number.isInteger(maxCalls) || maxCalls < 1)) {
+            throw new RangeError('maxCalls must be a positive integer');
+        }
+        this.budgetUsd = budgetUsd;
+        this.agent = options.agent !== undefined ? validateId(options.agent, 'agent') : undefined;
+        this.user = options.user !== undefined ? validateUser(options.user) : parent?.user;
+        this.maxCalls = maxCalls;
+        this.parent = parent;
+        if (parent && parent.runId === this.runId) {
+            throw new RangeError('a run cannot be its own parent');
+        }
+    }
+    get parentRunId() {
+        return this.parent?.runId;
+    }
+    /** Requests made in this run and its child runs (SDK retries are not counted). */
+    get calls() {
+        return this.#calls;
+    }
+    /** Count one call against this run and every ancestor, or throw if a cap is hit. */
+    recordCall() {
+        const chain = [];
+        for (let r = this; r; r = r.parent)
+            chain.push(r);
+        // Check every cap first so a refused call is not counted anywhere.
+        for (const r of chain) {
+            if (r.maxCalls !== undefined && r.#calls >= r.maxCalls) {
+                throw new LocalCapExceeded(`Tokenrein local cap: run ${r.runId} reached maxCalls=${r.maxCalls}; request not sent`, { runId: r.runId, errorType: LOCAL_CAP_EXCEEDED });
+            }
+        }
+        for (const r of chain)
+            r.#calls += 1;
+    }
+    headers() {
+        const h = { 'x-tr-run-id': this.runId };
+        if (this.budgetUsd !== undefined)
+            h['x-tr-run-budget-usd'] = String(this.budgetUsd);
+        if (this.parent)
+            h['x-tr-parent-run-id'] = this.parent.runId;
+        return h;
+    }
+}
+/** The innermost active run in this async context, or `undefined`. */
+export function currentRun() {
+    return storage.getStore();
+}
+export function run(a, b) {
+    const fn = typeof a === 'function' ? a : b;
+    if (typeof fn !== 'function')
+        throw new TypeError('guard.run needs a callback');
+    const options = typeof a === 'string' ? { runId: a } : typeof a === 'function' ? {} : (a ?? {});
+    const r = new Run(options, storage.getStore());
+    return storage.run(r, fn, r);
+}