theokit 0.11.7 → 0.12.0

package/dist/server/auth/index.d.ts

@@ -1,419 +0,0 @@
-import { IncomingMessage, ServerResponse } from 'node:http';
-import { R as RateLimitStore } from '../../rate-limit-store-BEJnhWdw.js';
-
-/**
- * T4.1 — Per-request CSP nonce generation.
- *
- * Returns a 22–24 character base64-encoded string carrying 16 bytes of
- * cryptographic entropy. Used by the SSR pipeline to nonce the inline
- * hydration data script so the default CSP can drop `'unsafe-inline'`
- * from `script-src` in 0.3.0.
- *
- * Runtime portability: prefers Web Crypto (`globalThis.crypto`) because
- * it is available on every target runtime (Node 19+, Bun, Deno, Vercel
- * Edge, Cloudflare Workers). Falls back to `node:crypto` for older Node
- * builds where `globalThis.crypto` is absent.
- *
- * NOT a security primitive in the cryptographic sense — the nonce is a
- * one-shot, single-request value that defeats trivial XSS injection by
- * making the attacker guess a 128-bit string per request. It is NOT
- * suitable for signing or session tokens.
- */
-declare function generateNonce(): string;
-
-declare class AuthRequiredError extends Error {
-    code: "AUTH_REQUIRED";
-    status: number;
-    constructor(message?: string);
-}
-declare function requireAuth<T>(session: T | null | undefined): asserts session is T;
-
-interface SessionConfig {
-    /**
-     * Session secret. Either a single string (legacy) or an array of strings
-     * where index 0 is the newest. The array form enables dual-key rotation
-     * (T3.1 / ADR D5): encrypt always uses `secrets[0]`, decrypt walks the
-     * array, transparent re-encrypt on legacy hits (T3.2).
-     *
-     * EC-1: array length capped at 5 — enforced via throw at construction.
-     */
-    secret: string | string[];
-    cookieName?: string;
-    maxAge?: number;
-}
-interface SessionMeta {
-    /** Index of the secret that decrypted the session. 0 = newest; > 0 = legacy. */
-    secretIndex: number;
-    /** True when the decrypt used a legacy secret and the cookie should be re-encrypted. */
-    needsReencrypt: boolean;
-}
-interface SessionManager<TSession> {
-    getSession(req: IncomingMessage): Promise<TSession | null>;
-    /**
-     * T3.2 — Variant of `getSession` that surfaces decrypt metadata.
-     * Used by `api-middleware.ts` to wire transparent re-encrypt BEFORE
-     * the handler runs (so streaming SSR routes don't miss the Set-Cookie
-     * window — EC-4).
-     */
-    getSessionWithMeta(req: IncomingMessage): Promise<{
-        data: TSession | null;
-        meta: SessionMeta;
-    }>;
-    createSession(res: ServerResponse, data: TSession): Promise<void>;
-    destroySession(res: ServerResponse): void;
-    /**
-     * T3.3 — OWASP A07:2021 session fixation mitigation. Re-encrypts the
-     * current session with a fresh IV and refreshed expiry. No-op when no
-     * session is present.
-     */
-    rotateSession(req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
-}
-declare function createSessionManager<TSession>(config: SessionConfig): SessionManager<TSession>;
-/**
- * T5a.2 Phase D slice 3/3 — Web-Standards session manager.
- *
- * Mirror of `SessionManager<TSession>` for the Web `Request` + `Headers`
- * shape. Same `SessionConfig`, same encryption (`encrypt`/`decrypt` from
- * `./crypto.js`), same dual-key rotation logic (CR-002 constant-time
- * decrypt fallback walk + transparent re-encrypt), same OWASP A07
- * `rotateSession` invariant.
- *
- * **Signature differences vs `SessionManager`:**
- *   - Read methods take `Request` (instead of `IncomingMessage`).
- *   - Write methods take a `Headers` instance to mutate (instead of
- *     `ServerResponse`) — caller passes the headers they're building
- *     for their `Response` constructor.
- *
- * Uses `getCookieFromRequest` / `appendCookieToHeaders` /
- * `appendDeleteCookieToHeaders` from Phase B slice 6/6.
- */
-interface SessionManagerWeb<TSession> {
-    getSession(request: Request): Promise<TSession | null>;
-    getSessionWithMeta(request: Request): Promise<{
-        data: TSession | null;
-        meta: SessionMeta;
-    }>;
-    createSession(target: Headers, data: TSession): Promise<void>;
-    destroySession(target: Headers): void;
-    rotateSession(request: Request, target: Headers): Promise<TSession | null>;
-}
-declare function createSessionManagerWeb<TSession>(config: SessionConfig): SessionManagerWeb<TSession>;
-/**
- * T5a.2 Phase D slice 3/3 — Web-Standards transparent re-encrypt helper.
- *
- * Mirror of `rotateIfNeeded(sm, req, res)` for the Web Request + Headers
- * shape. Reads session via `getSessionWithMeta`; if the cookie was
- * decrypted with a legacy secret (index > 0), re-issues the cookie with
- * the newest secret via `createSession(target, data)`.
- *
- * **EC-4 honest framing:** unlike the IncomingMessage path where the
- * timing constraint is "before `res.writeHead` fires", the Web Request
- * path's constraint is "before the `Response` object is constructed and
- * returned to the runtime". Caller MUST invoke `rotateIfNeededWeb`
- * BEFORE building the final `Response(body, { headers: target })` so the
- * re-encrypted Set-Cookie lands on the wire.
- */
-declare function rotateIfNeededWeb<TSession>(sm: SessionManagerWeb<TSession>, request: Request, target: Headers): Promise<TSession | null>;
-/**
- * T3.2 — Transparent re-encrypt helper (EC-4 timing-safe wrapper).
- *
- * Call this in your `createContext` (before any rendering / streaming
- * starts). It:
- *   1. Reads the session via `getSessionWithMeta`.
- *   2. If the cookie was decrypted with a legacy secret (index > 0), it
- *      immediately re-issues the cookie with `secrets[0]` so the next
- *      request lands on the newest key.
- *   3. Returns the session data (or null) for use downstream.
- *
- * EC-4: this MUST run before `renderToPipeableStream` / `res.writeHead`
- * fires. Calling it inside an SSR component or handler body that has
- * already streamed bytes makes the re-encrypt a silent no-op (Set-Cookie
- * is locked once headers commit), trapping users on the legacy secret
- * forever once it's removed from the array.
- */
-declare function rotateIfNeeded<TSession>(sm: SessionManager<TSession>, req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
-declare function assertProductionSecret(secret: string | string[]): void;
-
-declare function encrypt<T>(data: T, secret: string): Promise<string>;
-declare function decrypt<T>(token: string, secret: string): Promise<T | null>;
-/**
- * Reset the derived-key cache. Test helper — never call from production code.
- * Used by Vitest to guarantee isolation between tests that use distinct
- * secrets and want to confirm the derivation path runs.
- */
-declare function _resetKeyCacheForTests(): void;
-
-/**
- * T6.2 — RFC 6238 TOTP primitive.
- *
- * Reference: https://datatracker.ietf.org/doc/html/rfc6238
- * HMAC-based one-time password (HOTP) base: https://datatracker.ietf.org/doc/html/rfc4226
- *
- * Pure-function, dependency-free implementation via Web Crypto. Secrets
- * may be passed as Uint8Array (preferred) or base32 string.
- *
- * SECURITY NOTES (documented per EC-13):
- *   - TOTP secrets are equivalent to passwords. Encrypt at rest using a
- *     separate KMS key from the session secret. If your DB leaks, ALL
- *     2FA codes are compromised — rotate by forcing all users to re-enroll.
- *   - Use `verifyTotp` constant-time (we use crypto.timingSafeEqual internally).
- */
-/** Supported HMAC algorithms per RFC 6238 §1.2. Default SHA-1. */
-type TotpAlgorithm = 'SHA-1' | 'SHA-256' | 'SHA-512';
-interface TotpOptions {
-    /** Shared secret — bytes (preferred) OR base32 string. */
-    secret: Uint8Array | string;
-    /** Time step in seconds. Default 30 (RFC 6238 §5.2 recommended). */
-    step?: number;
-    /** Code length: 6, 7, or 8 digits. Default 6. */
-    digits?: 6 | 7 | 8;
-    /** HMAC algorithm. Default SHA-1 (RFC default). */
-    algorithm?: TotpAlgorithm;
-    /** Time in ms since epoch. Default Date.now(). */
-    time?: number;
-}
-interface VerifyTotpOptions extends TotpOptions {
-    /**
-     * Drift tolerance in number of steps on each side. Default 1
-     * (RFC 6238 §5.2 recommends ±1 step = 90s total window).
-     */
-    window?: number;
-}
-/** Generate a TOTP code for a given time. */
-declare function generateTotp(opts: TotpOptions): Promise<string>;
-/**
- * Verify a TOTP code against the current window ± `window` steps.
- *
- * Returns `false` for malformed tokens (non-digit, wrong length) without
- * throwing — defensive against accidental user-input passthrough.
- */
-declare function verifyTotp(token: string, opts: VerifyTotpOptions): Promise<boolean>;
-/** Generate a cryptographically random TOTP secret. Default 20 bytes (RFC minimum). */
-declare function generateTotpSecret(bytes?: number): Uint8Array;
-/**
- * Build an `otpauth://` URI for QR code enrollment. Format follows the
- * de facto Google Authenticator spec adopted by every major TOTP app.
- *   otpauth://totp/<issuer>:<account>?secret=<base32>&issuer=<issuer>&algorithm=<alg>&digits=<n>&period=<sec>
- */
-interface TotpUriOptions {
-    secret: Uint8Array;
-    issuer: string;
-    account: string;
-    algorithm?: TotpAlgorithm;
-    digits?: 6 | 7 | 8;
-    step?: number;
-}
-declare function totpUri(opts: TotpUriOptions): string;
-
-/**
- * T6.3 — Backup codes for 2FA recovery.
- *
- * generateBackupCodes returns N plaintexts (display once to user) + hashes
- * (store in DB). verifyBackupCode constant-time-walks all hashes and
- * returns the matchedHash so caller can delete the used code from storage
- * — replay protection lives at the caller (we can't see their database).
- *
- * SECURITY NOTES:
- *   - Codes have ~40 bits entropy (8 chars × 5 bits per char from a
- *     32-char alphabet excluding I/L/O/0/1). Single-use → argon2id
- *     overhead is unnecessary; SHA-256 of the normalized code suffices.
- *   - The caller MUST atomically delete the matched hash on successful
- *     verify. Without that, the code is replayable. We surface
- *     matchedHash explicitly so this step is conspicuous.
- *   - Pair this with throttleLoginAttempts (T6.1) on the verify endpoint
- *     to prevent online brute-force against the 40-bit space.
- */
-interface BackupCodeOptions {
-    /** How many codes to generate. Default 10. */
-    count?: number;
-    /** Length in chars (excluding separator). Default 8. */
-    length?: number;
-    /** Separator inserted at the midpoint. Default '-'; pass null to omit. */
-    separator?: '-' | null;
-    /** Custom alphabet. Default excludes ambiguous chars (I, L, O, 0, 1). */
-    alphabet?: string;
-}
-interface BackupCode {
-    plaintext: string;
-    hash: string;
-}
-/**
- * Generate cryptographically random backup codes + their SHA-256 hashes.
- *
- * Plaintext is uppercase alphanumeric (default alphabet excludes ambiguous
- * chars). Separator inserted at the midpoint (default `-`).
- */
-declare function generateBackupCodes(opts?: BackupCodeOptions): Promise<BackupCode[]>;
-/**
- * Verify a code against a list of stored hashes. Walks all hashes
- * constant-time (no early exit). Returns `valid:true` + matchedHash on
- * hit; `valid:false` otherwise.
- *
- * `matchedHash` is the EXACT string the caller stored, ready to be passed
- * to a `DELETE FROM backup_codes WHERE hash = ?` query.
- */
-declare function verifyBackupCode(code: string, hashes: readonly string[]): Promise<{
-    valid: boolean;
-    matchedHash?: string;
-}>;
-
-/**
- * T6.1 — Login throttling primitive.
- *
- * Per-credential failure counter backed by any `RateLimitStore`. After
- * `maxAttempts` failures within `windowMs`, the identifier is locked
- * for `lockoutMs`. Successful login resets the counter.
- *
- * Usage in a login handler:
- *
- *   const state = await checkThrottle({ store, identifier: hash(email) })
- *   if (!state.allowed) return 429
- *   const valid = await verifyPassword(creds)
- *   await recordAttempt({ store, identifier: hash(email) }, valid)
- *   if (!valid) return 401
- *
- * SECURITY:
- *   - NEVER pass raw email/username as `identifier`. Hash or normalize
- *     first (e.g. SHA-256 of the lowercased email). This prevents PII
- *     from landing in the rate-limit store or audit logs.
- *   - Combine with the per-route IP rate limit (T2.2) for layered defense:
- *     IP-level limits stop scripted floods; credential-level limits stop
- *     distributed brute force.
- */
-interface ThrottleOptions {
-    store: RateLimitStore;
-    /**
-     * Stable identifier per credential. Hash raw emails/usernames before
-     * passing in — never leak PII to the rate-limit key space.
-     */
-    identifier: string;
-    /** Failures before lockout. Default 5. */
-    maxAttempts?: number;
-    /** Sliding window for counting failures. Default 15 minutes. */
-    windowMs?: number;
-    /** Lockout duration after maxAttempts hit. Default 1 hour. */
-    lockoutMs?: number;
-}
-interface ThrottleState {
-    allowed: boolean;
-    remainingAttempts: number;
-    /** Set when `allowed === false`. Absolute timestamp when the lockout expires. */
-    lockedUntil?: Date;
-}
-/**
- * Read the current throttle state for an identifier WITHOUT modifying
- * the counter. Call before validating credentials so locked attempts
- * are rejected fast.
- */
-declare function checkThrottle(opts: ThrottleOptions): Promise<ThrottleState>;
-/**
- * Record an attempt outcome. On success → reset the counter. On failure
- * → increment within the sliding window. Returns the new throttle state.
- *
- * Storage model: the store entry's TTL is `lockoutMs` (which doubles as
- * the failure-accumulation window). When `lockoutMs` is short — common
- * in tests or for soft lockouts — the entry auto-expires and the next
- * attempt starts fresh.
- */
-declare function recordAttempt(opts: ThrottleOptions, success: boolean): Promise<ThrottleState>;
-
-/**
- * T7.3 — RFC 7636 PKCE primitive.
- *
- * Reference: https://datatracker.ietf.org/doc/html/rfc7636
- *
- * Pure-function, dependency-free implementation using Web Crypto.
- *
- * Usage in an OAuth authorization-code flow:
- *
- *   const { codeVerifier, codeChallenge, codeChallengeMethod } = await generatePkceChallenge()
- *   // Store codeVerifier in the user's session
- *   // Send codeChallenge + codeChallengeMethod in the /authorize redirect
- *   // ... user authenticates with provider ...
- *   // On /callback, send codeVerifier with the code → token exchange
- */
-interface PkceChallenge {
-    codeVerifier: string;
-    codeChallenge: string;
-    codeChallengeMethod: 'S256';
-}
-/**
- * Compute the code_challenge from a code_verifier per RFC 7636 §4.2.
- * Exported separately to enable RFC 7636 Appendix B vector testing.
- */
-declare function pkceChallengeFromVerifier(verifier: string): Promise<string>;
-/**
- * Generate a fresh PKCE challenge pair.
- *
- * Verifier: 32 cryptographically random bytes → 43-char base64url string.
- * RFC 7636 §4.1 allows 43–128 chars; we ship the minimum-safe default.
- *
- * Method: 'S256' only — no 'plain' fallback. RFC 7636 §7.2 strongly
- * discourages plain and modern providers reject it.
- */
-declare function generatePkceChallenge(): Promise<PkceChallenge>;
-
-/**
- * T7.4 — OAuth `state` parameter helpers (RFC 6749 §10.12).
- *
- * `state` is a cryptographically random anti-CSRF token. The client
- * stores it (in session/cookie/db) before redirecting to the
- * authorization endpoint and verifies it on the callback. Without it,
- * an attacker can authorize on the user's account using a captured code.
- */
-/**
- * Generate a cryptographically random state token. Default 32 bytes
- * (~43 base64url chars). Increase for higher entropy if your provider
- * supports it.
- */
-declare function generateOAuthState(opts?: {
-    bytes?: number;
-}): string;
-/**
- * Verify a state token. Constant-time compare. Empty inputs always fail
- * (defensive — never accept empty as "they match").
- *
- * CR-012 fix: `constantTimeEquals` does not early-exit on length mismatch,
- * so the comparison time is independent of how the input was forged.
- */
-declare function verifyOAuthState(provided: string, stored: string): boolean;
-
-/**
- * T7.4 — OpenID Connect Discovery 1.0 metadata fetcher.
- *
- * Reference: https://openid.net/specs/openid-connect-discovery-1_0.html
- *
- * Caches metadata in module scope. Cache key is the exact issuer string
- * (trailing-slash sensitive per RFC 8414 §3). Failures are NOT cached —
- * subsequent calls retry the fetch.
- *
- * EC-7 — HTTPS enforced. RFC 8414 §3 requires HTTPS for OIDC issuers.
- * Localhost (loopback) is allowed for development.
- */
-interface OidcMetadata {
-    issuer: string;
-    authorization_endpoint: string;
-    token_endpoint: string;
-    jwks_uri?: string;
-    userinfo_endpoint?: string;
-    end_session_endpoint?: string;
-    scopes_supported?: string[];
-    response_types_supported?: string[];
-    grant_types_supported?: string[];
-    id_token_signing_alg_values_supported?: string[];
-    [key: string]: unknown;
-}
-/** Clear the discovery cache. Used by tests. */
-declare function clearOidcCache(): void;
-/**
- * Fetch (or return cached) OIDC provider metadata.
- *
- * Throws when:
- *   - Issuer URL is malformed
- *   - Issuer is HTTP and not a loopback host (EC-7)
- *   - HTTP response is non-OK
- *   - Metadata lacks `authorization_endpoint` (sanity check)
- */
-declare function discoverOidcProvider(issuer: string | URL): Promise<OidcMetadata>;
-
-export { AuthRequiredError, type BackupCode, type BackupCodeOptions, type OidcMetadata, type PkceChallenge, type SessionConfig, type SessionManager, type SessionManagerWeb, type SessionMeta, type ThrottleOptions, type ThrottleState, type TotpAlgorithm, type TotpOptions, type TotpUriOptions, type VerifyTotpOptions, _resetKeyCacheForTests, assertProductionSecret, checkThrottle, clearOidcCache, createSessionManager, createSessionManagerWeb, decrypt, discoverOidcProvider, encrypt, generateBackupCodes, generateNonce, generateOAuthState, generatePkceChallenge, generateTotp, generateTotpSecret, pkceChallengeFromVerifier, recordAttempt, requireAuth, rotateIfNeeded, rotateIfNeededWeb, totpUri, verifyBackupCode, verifyOAuthState, verifyTotp };

package/dist/server/cost/index.d.ts

@@ -1,177 +0,0 @@
-import { d as StorageAdapter } from '../../storage-types-DsDTCPbp.js';
-
-/**
- * Cost tracking types (R0.5.11).
- *
- * @see docs/adr/0002-job-backend-interface-neutral-contract.md (mirror pattern)
- *
- * Phase 5 — Production-Readiness #4: adds `ToolUsageRecord` for per-tool
- * latency / error tracking via SDK's onToolStart/onToolEnd/onToolError hooks.
- * Same UsageStorageAdapter handles both via discriminated union.
- *
- * EC-9 (SHOULD TEST): backward compat — record() input without `kind` is
- * normalized to 'llm' by the framework so external adapters from older
- * versions keep working.
- */
-/**
- * Per-LLM-call cost record (existing — gains optional `kind` discriminator).
- */
-interface UsageRecord {
-    /** Discriminator. Optional for backward-compat; defaults to 'llm'. */
-    kind?: 'llm';
-    /** User identifier (e.g., session userId, tenantId, apiKey hash). */
-    userId: string;
-    /** Model id (e.g., 'claude-sonnet-4-5-20250929'). */
-    model: string;
-    /** Token counts per direction. */
-    tokens: {
-        input: number;
-        output: number;
-    };
-    /** USD cost in fractional dollars. */
-    costUsd: number;
-    /** When the run happened. */
-    timestamp: Date;
-}
-/**
- * Per-tool-invocation record (Phase 5 — Production-Readiness #4).
- *
- * Emitted by `trackAgentTools` on every `onToolEnd` / `onToolError`. The same
- * `UsageStorageAdapter.record` accepts both record kinds via union.
- */
-interface ToolUsageRecord {
-    kind: 'tool';
-    userId: string;
-    conversationId: string;
-    toolName: string;
-    /**
-     * Unique per invocation; correlates onToolStart with onToolEnd / onToolError.
-     * EC-16 (DOCUMENT): callId uniqueness is SDK contract — if SDK ever reuses
-     * a callId, `trackAgentTools`'s Map uses last-write-wins (defensive).
-     */
-    callId: string;
-    /** True when the tool handler returned; false when it threw. */
-    success: boolean;
-    /** Milliseconds from onToolStart to onToolEnd / onToolError. */
-    durationMs: number;
-    /** Populated only when success === false. */
-    errorMessage?: string;
-    timestamp: Date;
-}
-interface UsageQuery {
-    userId: string;
-    period: {
-        from: Date;
-        to: Date;
-    };
-}
-interface UsageResult {
-    totalTokens: number;
-    totalCostUsd: number;
-    runs: number;
-}
-interface UsageStorageAdapter {
-    readonly name: string;
-    /**
-     * Record a usage event. Accepts both kinds; framework normalizes input
-     * without `kind` to 'llm' before calling adapter (EC-9 backward compat).
-     */
-    record(input: UsageRecord | ToolUsageRecord): Promise<void>;
-    getUsage(query: UsageQuery): Promise<UsageResult>;
-}
-
-interface TrackAgentRunInput {
-    userId: string;
-    model: string;
-    tokens: {
-        input: number;
-        output: number;
-    };
-    costUsd: number;
-    /** Defaults to `new Date()`. */
-    timestamp?: Date;
-    /** Optional execution status surfaced to devtools (default 'finished'). */
-    status?: 'finished' | 'error' | 'aborted';
-}
-interface TrackAgentRunOptions {
-    /** Adapter resolved from `theo.config.ts > cost.storage`. */
-    storage: UsageStorageAdapter | undefined;
-}
-/**
- * Record a single agent run's usage + cost. Companion to the client-side
- * `<CostMeter>` from `@theokit/ui`.
- *
- * EC-14: this function NEVER bubbles errors back to the caller. Adapter
- * failures (network outage, DB down, etc.) are logged via `console.warn`
- * and swallowed. The agent response MUST NOT fail because cost tracking
- * is degraded.
- *
- * No-op when `storage` is undefined (cost tracking unconfigured).
- *
- * In dev mode (Vite OR tsup-built with NODE_ENV != 'production'), fires a
- * `theokit-evolution-ci-and-dx` Phase 3 dispatcher event so the devtools
- * Agents tab can render the run. Prod tree-shakes the entire dispatcher
- * import via the `__IS_DEV` IIFE guard.
- *
- * @see docs/concepts/cost-tracking.md (when implemented in T6.3)
- */
-declare function trackAgentRun(input: TrackAgentRunInput, opts: TrackAgentRunOptions): Promise<void>;
-
-/**
- * In-memory usage storage for dev/tests. Unbounded — production
- * deployments MUST plug in a durable adapter (Postgres/Redis recipes
- * land with R0.6.7; documented in EC-114).
- *
- * Phase 5 — Production-Readiness #4: accepts both `UsageRecord` (LLM call,
- * kind='llm' or omitted) AND `ToolUsageRecord` (tool call, kind='tool').
- * `getUsage` only sums LLM records (tools have no token/cost dimension).
- *
- * EC-9 (backward compat): input without `kind` is normalized to `kind:'llm'`
- * — adapters from older versions stay working.
- *
- * Concurrency: Node's single-threaded event loop guarantees that
- * `Array.push` is atomic, so concurrent record() calls cannot lose data.
- */
-declare class InMemoryUsageStorage implements UsageStorageAdapter, StorageAdapter {
-    #private;
-    readonly name = "memory";
-    /**
-     * T2.3 — `StorageAdapter` lifecycle hook (ADR-0007 D6). In-memory storage
-     * has no real cleanup to perform — this is intentionally a noop so the
-     * adapter can be registered with `StorageManager.register()` and
-     * participate in graceful shutdown without changing behavior.
-     *
-     * Does NOT clear stored records (dispose ≠ reset). For test reset use
-     * a fresh instance.
-     */
-    dispose(): Promise<void>;
-    record(input: UsageRecord | ToolUsageRecord): Promise<void>;
-    getUsage(query: UsageQuery): Promise<UsageResult>;
-}
-
-interface TrackAgentToolsOptions {
-    storage: UsageStorageAdapter;
-    /** Defaults to () => new Date() — overridable for deterministic testing. */
-    now?: () => Date;
-    /** Identifier for the user — passed through to ToolUsageRecord.userId. */
-    userId?: string;
-    /** Identifier for the conversation — passed through to ToolUsageRecord.conversationId. */
-    conversationId?: string;
-}
-interface ToolHookEvent {
-    callId: string;
-    name: string;
-    [key: string]: unknown;
-}
-interface TrackAgentToolsHooks {
-    onToolStart: (event: ToolHookEvent) => void;
-    onToolEnd: (event: ToolHookEvent) => void;
-    onToolError: (event: ToolHookEvent) => void;
-}
-/**
- * Create the three tool-lifecycle callbacks. Hand the returned object's
- * methods to `Agent.create({ tools, onToolStart, onToolEnd, onToolError })`.
- */
-declare function trackAgentTools(opts: TrackAgentToolsOptions): TrackAgentToolsHooks;
-
-export { InMemoryUsageStorage, type ToolHookEvent, type ToolUsageRecord, type TrackAgentRunInput, type TrackAgentRunOptions, type TrackAgentToolsHooks, type TrackAgentToolsOptions, type UsageQuery, type UsageRecord, type UsageResult, type UsageStorageAdapter, trackAgentRun, trackAgentTools };