@dvai-bridge/core 4.0.0

package/dist/index.d.cts

@@ -0,0 +1,1030 @@
+export { InitProgressReport } from '@mlc-ai/web-llm';
+
+/**
+ * Phase 3 — peer discovery types.
+ *
+ * A "peer" is another device running dvai-bridge that this device can
+ * (potentially) offload inference requests to. Peers are surfaced by
+ * one or more `IDiscovery` impls — LAN mDNS, app-supplied static list,
+ * rendezvous-paired (internet), or a host-app-provided custom source.
+ */
+interface Peer {
+    /** Stable per-install device ID of the peer. */
+    deviceId: string;
+    /** Human-readable hint (iOS device name, hostname, etc.). */
+    deviceName: string;
+    /** Library SemVer the peer is running. */
+    dvaiVersion: string;
+    /** OpenAI-compatible base URL the peer's local server exposes. */
+    baseUrl: string;
+    /**
+     * v3.1 wire-protocol extension. Identifies which application on the
+     * peer device is making the request — used by multi-tenant targets
+     * (the Hub) to isolate per-app state. Optional for backwards compat
+     * with v3.0 SDKs that don't send this field.
+     */
+    appId?: string;
+    /**
+     * Models the peer claims to have loaded right now. Used to filter
+     * peer eligibility — we only offload model X to a peer that already
+     * has model X loaded (loading from scratch on the peer is fine but
+     * defeats the latency win).
+     */
+    loadedModels: string[];
+    /**
+     * Peer-reported capability map: { modelId → tok/s }. Treat as
+     * advisory only; the offload decider re-probes a peer with a small
+     * reachability+decode test before its first real offload request.
+     */
+    capability: Record<string, number>;
+    /** Discovery source — useful for diagnostics and the structured-error response. */
+    via: "mdns" | "static" | "rendezvous" | "custom";
+    /** Whether the peer's URL uses TLS. */
+    secure: boolean;
+    /** Last-seen unix ms — discovery sources update this. */
+    lastSeenAt: number;
+}
+
+/**
+ * Phase 3 (v3.0) — capability assessment types.
+ *
+ * A "capability score" is an estimate of decode tok/s for a given
+ * (model, device) pair on this device. Used by the offload decider
+ * to pick local vs. peer execution per request.
+ */
+interface CapabilityScore {
+    /** Model identifier this score applies to. */
+    modelId: string;
+    /** Stable per-install device identifier. */
+    deviceId: string;
+    /** Library SemVer at the time the score was measured. */
+    libraryVersion: string;
+    /** Estimated decode rate, tokens-per-second. */
+    tokPerSec: number;
+    /** Source of the estimate. */
+    source: "probe" | "heuristic";
+    /** Unix milliseconds the score was measured / computed. */
+    measuredAt: number;
+}
+/**
+ * Coarse device-class buckets used by the heuristic fallback when no
+ * cold-run probe has run yet. Numbers are intentionally conservative
+ * — the probe will refine on first real use.
+ */
+interface DeviceCapabilityHints {
+    /** Has a dedicated NPU (Apple Neural Engine, Hexagon, Intel NPU, etc.) */
+    hasNpu: boolean;
+    /** Approximate system RAM in GB. */
+    ramGb: number;
+    /** GPU class — best-guess based on platform clues. */
+    gpuClass: "none" | "integrated" | "discrete" | "apple-silicon";
+    /** Coarse CPU bucket. */
+    cpuClass: "low" | "mid" | "high";
+}
+
+/**
+ * LAN-pairing handshake. The first time Device A wants to offload to
+ * Device B over the LAN, A POSTs /v1/dvai/handshake to B with its
+ * identity + a nonce. B surfaces a UI prompt to the user; on approve,
+ * B generates a 256-bit pairing key and returns it. From then on, A
+ * includes `X-DVAI-Pairing: HMAC-SHA256(pairingKey, body)` on every
+ * offload request to B.
+ */
+
+/** Generate a fresh 256-bit pairing key (base64-url encoded). */
+declare function generatePairingKey(): string;
+/** Generate a fresh nonce for a handshake request. */
+declare function generateNonce(): string;
+/**
+ * HMAC-SHA256(key, message). Used to sign offload requests so the
+ * peer can verify they came from a paired device.
+ */
+declare function signHmac(pairingKey: string, message: string): Promise<string>;
+/** Verify an HMAC. Returns true on match, false otherwise (constant-time-ish). */
+declare function verifyHmac(pairingKey: string, message: string, signature: string): Promise<boolean>;
+/**
+ * Compose the canonical message that gets HMAC-signed for a peer-to-peer
+ * offload request. The peer recomputes the same string and verifies.
+ *
+ * Format: `${nonce}\n${method}\n${path}\n${bodyHash}` — bodyHash is the
+ * hex-encoded SHA-256 of the request body bytes.
+ */
+declare function composeSignedMessage(nonce: string, method: string, path: string, body: string | undefined): Promise<string>;
+
+/**
+ * Phase 3 — `/v1/dvai/*` handlers.
+ *
+ * Hosted by the same in-process HTTP server (or MSW intercept in
+ * browser) that already serves the OpenAI surface. Routes:
+ *
+ *   GET  /v1/dvai/health      — liveness, capacity, version
+ *   GET  /v1/dvai/capability  — this device's capability map
+ *   GET  /v1/dvai/peers       — discovered peer list
+ *   POST /v1/dvai/probe       — manually trigger a capability probe
+ *   POST /v1/dvai/handshake   — LAN-pairing handshake
+ *   POST /v1/dvai/pair-qr     — start a rendezvous session, return QR payload
+ *   POST /v1/dvai/pair-scan   — submit a scanned QR payload, complete the join
+ *
+ * These handlers are pure-ish — they take a context object with the
+ * relevant collaborators (capability cache, discovery, pairing policy,
+ * rendezvous client, etc.) and return JSON responses. Wired into the
+ * core's existing handler pipeline by src/index.ts.
+ */
+
+/** Generic handler shape: takes parsed request body, returns JSON-stringifiable. */
+type DvaiHandler = (req: {
+    body: unknown;
+}) => Promise<{
+    status: number;
+    body: unknown;
+}>;
+
+/**
+ * Duck-typed backend contract consumed by the transport-agnostic handlers.
+ * Both existing backends (WebLLMBackend, TransformersBackend) satisfy this
+ * structurally without any backend changes.
+ */
+interface BackendInterface {
+    chatCompletion(body: any): Promise<any>;
+    createStreamingResponse(body: any): ReadableStream<Uint8Array>;
+    embedding?(inputs: string | string[]): Promise<number[][]>;
+    /** WebLLM sets this on fatal errors; triggers recovery path. */
+    lastFatalError?: unknown;
+    clearFatalError?(): void;
+}
+/**
+ * Per-request context passed to every handler. Built once by DVAI.initialize()
+ * and reused for the lifetime of the transport; handler reads the fields on
+ * each request so state updates on DVAI (e.g. backendInstance replaced during
+ * recovery) are visible through the same reference.
+ */
+interface HandlerContext {
+    /** Active backend; null means "not initialized" → 503. */
+    backend: BackendInterface | null;
+    /**
+     * Resolved backend kind. Used only for error messages and the model
+     * echo in responses. Union widens as new backends are added in later
+     * phases — handlers must NOT dispatch on this value; always duck-type
+     * on backend methods instead.
+     */
+    resolvedBackend: "webllm" | "transformers" | "native";
+    /** Model identifier echoed back in responses. */
+    modelId: string;
+    /**
+     * Optional recovery hook. Handler awaits this before a retry when
+     * backend.lastFatalError is set. DVAI owns the retry counter and
+     * throws when exhausted; handler only awaits. Undefined → no recovery.
+     */
+    onRecovery?: () => Promise<void>;
+    /**
+     * Phase 3 — `/v1/dvai/*` route map populated when `offload.enabled`.
+     * Late-bound (getter) so transports can read it per request even
+     * though the routes are built after the transport starts. Undefined
+     * when offload isn't enabled — transports return 404 in that case.
+     */
+    dvaiRoutes?: Record<string, DvaiHandler>;
+    /**
+     * Phase 4 — first-chance hook for /v1/chat/completions. The Hub
+     * uses this to inject substitution-policy + engine-bridge routing
+     * before the default handler dispatches to the local backend.
+     *
+     * Return a Response → that's what the client gets.
+     * Return null → fall through to the default backend path.
+     *
+     * Receives request headers (lower-cased keys) so the interceptor can
+     * read v3.1 identity fields (X-DVAI-Peer-Device-Id, X-DVAI-App-Id,
+     * X-DVAI-Nonce, X-DVAI-Signature) for HMAC verification + tenant
+     * routing.
+     *
+     * Errors raised in the interceptor propagate to the standard error
+     * response path in handleChatCompletion.
+     */
+    chatCompletionInterceptor?: (body: any, ctx: HandlerContext, headers?: Record<string, string>) => Promise<Response | null>;
+}
+
+/**
+ * Phase 3 — offload module types.
+ */
+
+interface OffloadConfig {
+    /** Master switch. Default false; offload is opt-in at v3.0. */
+    enabled: boolean;
+    /** Run mDNS to discover LAN peers. */
+    discoverLAN: boolean;
+    /**
+     * v3.2.1 — advertise this DVAI instance on `_dvai-bridge._tcp` so
+     * other LAN peers can discover it. Default false to preserve v3.1
+     * behaviour where mobile SDKs owned the advertise side and the
+     * desktop Hub didn't advertise. Set this to `true` on the Hub so
+     * mobile peers can auto-discover it without manual URL entry.
+     */
+    advertiseLAN?: boolean;
+    /**
+     * Optional override of the port we advertise. Default: pulled from
+     * the running DVAI server's bound port.
+     */
+    advertisePort?: number;
+    /** Below this tok/s, look for a peer. Default 10. */
+    minLocalCapability: number;
+    /**
+     * v3.2 — hard floor for any local inference, in tok/s. Below this
+     * the device is "too weak"; the SDK aborts initialize() and
+     * (optionally) shows a system popup via [onHardwareTooWeak].
+     *
+     * Default: 3. Apps targeting long-prompt batch use cases where
+     * latency is acceptable can lower this; apps targeting interactive
+     * chat should leave it.
+     */
+    hardwareMinimum?: number;
+    /** Optional rendezvous-server URL — enables internet path if set. */
+    rendezvousUrl?: string;
+    /** Optional pre-known peers (skip discovery). */
+    knownPeers?: Peer[];
+    /**
+     * Hook to surface pairing-request UI to the host app. Default: deny.
+     *
+     * Return:
+     *   - `true` / `false` — boolean approve/deny. PairingPolicy generates
+     *     a fresh pairingKey on approval.
+     *   - `{ approved: true, pairingKey }` — host has its own pairing
+     *     state (the v3.1 Hub's MultiTenantPairing) and wants the
+     *     library to use the host-supplied key. Avoids the library
+     *     generating a key that diverges from the host's store.
+     *   - `{ approved: false }` — denied.
+     */
+    onPairingRequest?: (peer: Peer) => Promise<boolean | {
+        approved: true;
+        pairingKey: string;
+    } | {
+        approved: false;
+    }>;
+    /** Diagnostic callback when a request is offloaded. */
+    onOffload?: (peer: Peer) => void;
+    /** Hook to plug a custom discovery source. */
+    customDiscovery?: () => Promise<Peer[]>;
+}
+
+/**
+ * Supported pipeline tasks from Transformers.js.
+ * Common tasks include:
+ * - "text-generation" (default) — LLM chat/text generation
+ * - "text2text-generation" — encoder-decoder text models
+ * - "text-to-image" — image generation from text prompts
+ * - "image-to-text" — image captioning
+ * - "automatic-speech-recognition" — audio/speech to text
+ * - "text-to-speech" — text to audio
+ * - "zero-shot-classification" — classify without training
+ * - "feature-extraction" — embeddings
+ * - "translation" — language translation
+ * - "summarization" — text summarization
+ * - And many more: see https://huggingface.co/docs/transformers.js
+ */
+type PipelineTask = string;
+/**
+ * A pipeline-compatible callable function.
+ * Accepts messages (chat format) and generation options,
+ * returns results in the same shape as a Transformers.js pipeline:
+ *   [{ generated_text: string }]
+ */
+type PipelineCallable = (messages: any, options?: any) => Promise<any>;
+/**
+ * Factory function that the client can supply to customize model loading.
+ * Receives the dynamically-imported @huggingface/transformers module and
+ * config details; must return a PipelineCallable.
+ *
+ * This lets the client control *how* the model is loaded and how inference
+ * is run, while DVAI handles everything else (MSW, OpenAI endpoint, etc.).
+ */
+type CreatePipelineFn = (transformers: any, ctx: {
+    modelId: string;
+    device: "webgpu" | "wasm" | "cpu";
+    dtype?: string;
+    onProgress?: (info: any) => void;
+}) => Promise<PipelineCallable>;
+interface TransformersProgressInfo {
+    status: string;
+    name?: string;
+    file?: string;
+    progress?: number;
+    loaded?: number;
+    total?: number;
+}
+/**
+ * Detects whether WebGPU is available in the current environment.
+ */
+declare function detectWebGPU(): Promise<boolean>;
+
+/**
+ * Public-key registry for DVAI-Bridge license JWT verification.
+ *
+ * Each entry is keyed by `kid` (key id, written by the license generator
+ * into the JWT header). The SDK looks up the matching entry by kid when
+ * verifying a license token. Multiple entries can coexist so that key
+ * rotation is non-disruptive: ship the new key in a release alongside
+ * the old, leave the old in place for ~12 months while previously-
+ * issued licenses naturally expire or get re-issued, then prune.
+ *
+ * THE PRIVATE KEY DOES NOT LIVE HERE. It belongs in your secrets
+ * manager (1Password / AWS Secrets Manager / Vault), accessible only
+ * to the license-generator service that produces signed JWTs. The
+ * mathematics of ECDSA P-256 guarantee that a holder of the public
+ * key alone cannot forge a signature.
+ *
+ * To populate this registry:
+ *   1. Run `node scripts/license/generate-keypair.mjs` (see that
+ *      script's comment for full instructions)
+ *   2. Paste the printed PUBLIC key JWK as an entry below
+ *   3. Move the printed PRIVATE key into your secrets store
+ *   4. Wire your license-generator backend to use the private key
+ */
+/** ES256 (P-256 ECDSA) public key in JWK form. */
+interface DvaiPublicKeyJwk {
+    kty: "EC";
+    crv: "P-256";
+    x: string;
+    y: string;
+    alg?: "ES256";
+    use?: "sig";
+    kid?: string;
+}
+/**
+ * Registry mapping `kid` → public key JWK.
+ *
+ * ⚠️ The entry below is a **placeholder** — it is a published, well-known
+ * test keypair and DOES NOT verify any real production license. Before
+ * shipping licenses to customers, replace it with the output of
+ * `scripts/license/generate-keypair.mjs`. The SDK refuses to validate
+ * licenses against the placeholder kid `"placeholder-do-not-ship"`
+ * unless DVAI_LICENSE_ALLOW_PLACEHOLDER=1 is set (test-only escape hatch).
+ *
+ * Adding a new key for rotation:
+ *
+ *   export const DVAI_PUBLIC_KEYS: Record<string, DvaiPublicKeyJwk> = {
+ *     "2026-05": { kty: "EC", crv: "P-256", x: "...", y: "...", alg: "ES256", use: "sig", kid: "2026-05" },
+ *     "2027-01": { kty: "EC", crv: "P-256", x: "...", y: "...", alg: "ES256", use: "sig", kid: "2027-01" },
+ *   };
+ */
+declare const DVAI_PUBLIC_KEYS: Record<string, DvaiPublicKeyJwk>;
+/**
+ * `kid` reserved for the placeholder key above. The validator refuses to
+ * accept tokens signed with this kid unless the caller explicitly opts
+ * in (DVAI_LICENSE_ALLOW_PLACEHOLDER=1 or `allowPlaceholderKey: true`
+ * passed to the validator constructor). Used by tests and by the
+ * sample license printed by `generate-keypair.mjs`.
+ */
+declare const PLACEHOLDER_KID = "placeholder-do-not-ship";
+
+/**
+ * License-file discovery for the JS/TS SDK.
+ *
+ * The SDK reads the license JWT from (in priority order):
+ *
+ *   1. An explicit string literal passed as `licenseToken` in DVAIConfig
+ *      — useful for CI / serverless / contexts where reading a file isn't
+ *      practical and the operator wants to inject via env var instead.
+ *
+ *   2. A path passed as `licenseKeyPath` in DVAIConfig — the developer
+ *      points the SDK at a file they've placed somewhere non-default.
+ *
+ *   3. The `DVAI_LICENSE_PATH` env var — same as (2) but driven by
+ *      process environment, helpful for containerised deployments.
+ *
+ *   4. Auto-discovery from platform-default locations (see below) —
+ *      the dev-friendly happy path. Drop the file at the convention
+ *      location and forget about it.
+ *
+ * Default discovery paths per JS-side platform:
+ *
+ *   - **Node.js**: looks for `dvai-license.jwt` in `process.cwd()` and
+ *     in `<package-root>/dvai-license.jwt` (one level up). Mirrors how
+ *     `.env` files are discovered.
+ *
+ *   - **Browser**: fetches `/dvai-license.jwt` from the same origin. The
+ *     file must be served alongside `mockServiceWorker.js` — typically
+ *     in `public/` for Vite/Webpack apps. The HTTP fetch is cached by
+ *     the browser so this is one round-trip on startup, not per request.
+ *
+ *   - **Capacitor**: fetches `/dvai-license.jwt` from the bundled web
+ *     assets (Capacitor.convertFileSrc on the public/ folder). The
+ *     native-side validator (in DVAIBridge.iOS / .Android) is the
+ *     authoritative binding for native bundle ids; this JS-side check
+ *     is a soft signal only.
+ *
+ * Returning `null` means "no license file found"; the validator treats
+ * that as the free-tier case (after dev-mode bypass).
+ */
+/**
+ * Default filename the SDK looks for. Chosen to be self-documenting and
+ * to encourage commit-to-vcs (so the license travels with the code,
+ * audited and reviewable by the team).
+ */
+declare const DEFAULT_LICENSE_FILENAME = "dvai-license.jwt";
+interface LicenseDiscoveryOptions {
+    /** Pre-loaded JWT string (skips all filesystem / fetch lookups). */
+    token?: string;
+    /** Explicit path or URL to load from. Overrides auto-discovery. */
+    path?: string;
+}
+
+/**
+ * Type surface for the DVAI-Bridge offline JWT license system.
+ *
+ * The whole license flow is deliberately small:
+ *   1. A signed JWT (produced server-side by your license generator) is
+ *      either dropped at a platform-default path, pointed at via the
+ *      `licenseKeyPath` config option, or pasted directly into the
+ *      `licenseToken` config option.
+ *   2. The SDK reads it, verifies the ECDSA P-256 signature against the
+ *      key registry in `publicKeys.ts`, and checks four runtime claims:
+ *      - signature must verify against a known kid
+ *      - `exp` must be in the future
+ *      - `aud` must include the current audience (hostname / bundleId)
+ *      - `platforms` must include the current SDK platform
+ *   3. The outcome is summarised in a `LicenseStatus` value that the
+ *      rest of the SDK can dispatch on (commercial/trial → premium
+ *      behaviour; everything else → free-tier behaviour with the
+ *      "Powered by DVAI Bridge" attribution badge).
+ *
+ * Nothing in this file makes network calls. The entire flow is offline.
+ */
+/** Recognised license tiers. Free-tier values are produced internally by
+ * the validator; commercial / trial come from the signed token's `tier`
+ * claim. Anything unknown collapses to "free-prod" defensively. */
+type LicenseTier = "commercial" | "trial" | "free-dev" | "free-prod" | "free-expired";
+/** Payload shape we issue (subset; extra claims tolerated). */
+interface DvaiLicensePayload {
+    /** Standard JWT issuer claim. Must be `"DVAI-Bridge"`. */
+    iss: string;
+    /** Standard subject — our internal license id. Surfaced in audit logs. */
+    sub: string;
+    /** Audience binding — array of domains and/or bundle ids permitted to
+     * activate this license. Each entry is either an exact string match
+     * (e.g. `"com.acme.app"`) or a wildcard subdomain pattern
+     * (e.g. `"*.acme.com"` matches both `acme.com` and `app.acme.com`). */
+    aud: string[];
+    /** Tier the license grants. `commercial` and `trial` are the live tiers;
+     * the validator never produces `free-*` here (those are computed). */
+    tier: "commercial" | "trial";
+    /** Which DVAI-Bridge SDK platforms this license activates. The current
+     * runtime platform must appear here for the license to apply. */
+    platforms: DvaiPlatform[];
+    /** Display name of the licensee, for audit logs + user-facing messaging. */
+    licensee: string;
+    /** Standard JWT issued-at (seconds since Unix epoch). */
+    iat: number;
+    /** Standard JWT expiry (seconds since Unix epoch). */
+    exp: number;
+}
+/** Platform identifiers the SDK recognises in license `platforms` claims. */
+type DvaiPlatform = "web" | "node" | "ios" | "android" | "dotnet" | "flutter" | "react-native" | "capacitor";
+/**
+ * Result of license validation. Discriminated union so the consumer's
+ * decision tree is exhaustive ("commercial" or "trial" → premium;
+ * everything else → free).
+ */
+type LicenseStatus = {
+    kind: "commercial";
+    licensee: string;
+    expiresAt: number;
+    platform: DvaiPlatform;
+    audienceMatched: string;
+} | {
+    kind: "trial";
+    licensee: string;
+    expiresAt: number;
+    platform: DvaiPlatform;
+    audienceMatched: string;
+} | {
+    kind: "free-dev";
+    /** Why dev mode was detected (for logging / dashboard surfacing). */
+    reason: string;
+} | {
+    kind: "free-prod";
+    /** Why a license could not be loaded or validated. Surfaced via a
+     * console warning so the developer can debug. Does NOT throw — the
+     * SDK falls back to free tier rather than refusing to start. */
+    reason: string;
+} | {
+    kind: "free-expired";
+    licensee: string;
+    expiredAt: number;
+};
+/** Returns true iff `tier` represents a paid / unwatermarked status. */
+declare function isPaidTier(status: LicenseStatus): boolean;
+/**
+ * Thrown by `LicenseValidator.validateAndAssert()` (and propagated from
+ * `DVAI.initialize()`) when an SDK consumer attempts to run the library
+ * in a production / release context without a valid commercial or trial
+ * license.
+ *
+ * The error message is intentionally verbose: it tells the developer
+ * exactly which check failed (missing file, expired, audience mismatch,
+ * etc.), how to resolve it, and where to put the license file once
+ * they have one. This is the front line of the BSL 1.1 commercial
+ * enforcement story — surface it clearly enough that a developer can
+ * unblock themselves without a support ticket.
+ *
+ * The `status` field carries the underlying `LicenseStatus` so
+ * programmatic callers can dispatch on `err.status.kind` if they
+ * want to handle "expired" differently from "missing".
+ */
+declare class LicenseRequiredError extends Error {
+    /** The underlying validator status that triggered the throw. */
+    readonly status: LicenseStatus;
+    /** Stable name set so `err.name === "LicenseRequiredError"` works
+     *  across module-boundary serialisation (e.g. Vite SSR). */
+    readonly name = "LicenseRequiredError";
+    constructor(message: string, 
+    /** The underlying validator status that triggered the throw. */
+    status: LicenseStatus);
+}
+
+interface LicenseValidatorOptions extends LicenseDiscoveryOptions {
+    /**
+     * Override the public-key registry. Defaults to `DVAI_PUBLIC_KEYS`
+     * from `./publicKeys.ts`. Tests inject their own keypair via this
+     * option so they can sign + verify against a deterministic key
+     * without polluting the production registry.
+     */
+    publicKeys?: Record<string, DvaiPublicKeyJwk>;
+    /**
+     * If true, accept tokens signed under `PLACEHOLDER_KID` (i.e. the
+     * built-in placeholder public key). Off by default — a real
+     * production build must replace the placeholder with a generated
+     * key. Tests set this to true.
+     */
+    allowPlaceholderKey?: boolean;
+}
+/**
+ * Validate a DVAI-Bridge license once at SDK startup. The returned
+ * `LicenseStatus` is the discriminated value the rest of the SDK
+ * dispatches on. Never throws on validation failure — it logs a
+ * console.warn and returns a `free-prod` / `free-expired` status.
+ */
+declare class LicenseValidator {
+    private readonly opts;
+    constructor(opts?: LicenseValidatorOptions);
+    /**
+     * Validate WITHOUT throwing. Returns a `LicenseStatus` describing what
+     * the validator determined; never throws on missing / invalid /
+     * expired licenses. Useful for host-app dashboards that want to
+     * display the licensee / expiry / fallback reason without halting
+     * SDK startup, and for tests.
+     *
+     * The SDK's `initialize()` calls `validateAndAssert()` instead — that
+     * throws `LicenseRequiredError` for `free-prod` / `free-expired`,
+     * which is how the BSL 1.1 commercial-only-in-production policy is
+     * actually enforced at runtime.
+     *
+     * Idempotent; safe to call multiple times.
+     */
+    validate(): Promise<LicenseStatus>;
+    /**
+     * Strict validation entry point used by the SDK at startup. Returns
+     * `LicenseStatus` on success (`commercial`, `trial`, `free-dev`) and
+     * THROWS `LicenseRequiredError` on `free-prod` / `free-expired`.
+     *
+     * This is the BSL 1.1 enforcement point: in production / release
+     * builds (any non-dev-mode environment), the SDK refuses to operate
+     * without a valid commercial or trial license. Developers running on
+     * localhost / debug builds / explicit DVAI_FORCE_DEV are unaffected
+     * — those return a `free-dev` status and the SDK proceeds normally.
+     *
+     * Use `validate()` instead when you want to inspect the status
+     * without halting startup (host-app dashboards, test fixtures).
+     */
+    validateAndAssert(): Promise<LicenseStatus>;
+    private verifyToken;
+}
+
+/**
+ * Convert an OpenAI chat.completion response body into the legacy
+ * text_completion shape used by POST /v1/completions.
+ */
+declare function chatToLegacyCompletion(chatResp: any): any;
+/**
+ * Wraps an SSE stream of chat.completion.chunk events and rewrites each
+ * event as a legacy text_completion chunk. Preserves event boundaries.
+ */
+declare function legacyCompletionStreamAdapter(chatStream: ReadableStream<Uint8Array>, model: string): ReadableStream<Uint8Array>;
+
+type BackendType = "webllm" | "transformers" | "native" | "auto";
+type DeviceType = "webgpu" | "cpu" | "auto";
+
+interface DVAIConfig {
+    /** The model ID for web-llm backend. Default: "gemma-2-2b-it-q4f16_1-MLC" */
+    modelId?: string;
+    /**
+     * The backend engine to use. Default: "webllm". Set to "auto" to auto-detect.
+     * - "webllm"       → @mlc-ai/web-llm (browser, WebGPU)
+     * - "transformers" → @huggingface/transformers (browser or Node)
+     * - "native"       → node-llama-cpp (Node only; loads a GGUF file)
+     * - "auto"         → resolved at runtime
+     */
+    backend?: BackendType;
+    /** HuggingFace model ID for Transformers.js backend. Default: "onnx-community/gemma-3n-E2B-it-ONNX" */
+    transformersModelId?: string;
+    /** Pipeline task for Transformers.js (e.g. "text-generation", "text-to-image", "automatic-speech-recognition"). Default: "text-generation" */
+    pipelineTask?: string;
+    /** Device for Transformers.js - "webgpu", "cpu", or "auto" (detect). Default: "auto" */
+    device?: DeviceType;
+    /** Quantization for Transformers.js (e.g. "q4", "q8", "f16"). Default: undefined */
+    dtype?: string;
+    /** Generation timeout in ms. Default: 60000 (60s) */
+    generationTimeout?: number;
+    /** Maximum consecutive blank chunks before aborting stream (WebLLM). Default: 20 */
+    maxBlankChunks?: number;
+    /** Maximum auto-recovery retries on fatal WebLLM errors (blank output/timeout). Default: 2 */
+    maxRetries?: number;
+    /** Mock URL for MSW interception. Default: "https://api.openai.local/v1/chat/completions" */
+    mockUrl?: string;
+    /** Path to the MSW service worker script. Default: "/mockServiceWorker.js" */
+    serviceWorkerUrl?: string;
+    /** URL to the WebLLM worker script (for offloading inference). Default: "/dvai-webllm.worker.js" */
+    webllmWorkerUrl?: string;
+    /** URL to the Transformers.js worker script (for offloading inference). Default: "/dvai-transformers.worker.js" */
+    transformersWorkerUrl?: string;
+    /**
+     * Custom pipeline factory for Transformers.js backend.
+     * MAIN-THREAD ONLY — function closures don't cross the Worker boundary.
+     * When provided, replaces the default pipeline() call with your own
+     * model loading and inference logic. Must return a callable that accepts
+     * (messages, options) and returns [{ generated_text: string }].
+     *
+     * For multimodal models that should run in the worker (recommended),
+     * use the declarative `transformersModelClass` / `transformersProcessorClass`
+     * / `transformersDisableEncoders` config instead.
+     */
+    createPipeline?: CreatePipelineFn;
+    /**
+     * Name of a transformers.js export to use as the model class (loaded via
+     * `ClassName.from_pretrained(modelId)`). Enables the declarative
+     * multimodal loader — works in the worker AND on main thread so the
+     * same config ships correctly regardless of path.
+     *
+     * Examples: "Gemma4ForConditionalGeneration", "LlavaForConditionalGeneration",
+     * "AutoModelForCausalLM". Leave unset to use the generic `pipeline()` factory.
+     */
+    transformersModelClass?: string;
+    /**
+     * Processor class name for the declarative loader. Default: "AutoProcessor".
+     * Only used when `transformersModelClass` is set.
+     */
+    transformersProcessorClass?: string;
+    /**
+     * Model submodule fields to null out after load, e.g. `["vision_encoder"]`
+     * for a voice-only host app using a multimodal checkpoint. Purely
+     * declarative — dvai-bridge walks the list and nulls each named field
+     * if present; unknown/absent names are silently ignored. Host apps
+     * control this based on their own criteria.
+     */
+    transformersDisableEncoders?: string[];
+    /** Path to the GGUF model file for the Capacitor llama backend. */
+    nativeModelPath?: string;
+    /** Number of GPU layers for the Capacitor llama backend (iOS Metal). Default: 99 (max) */
+    nativeGpuLayers?: number;
+    /** Number of CPU threads for the Capacitor llama backend. Default: 4 */
+    nativeThreads?: number;
+    /** Context window size for the Capacitor llama backend. Default: 2048 */
+    nativeContextSize?: number;
+    /**
+     * Initialize the Capacitor llama context in embedding mode. Required for
+     * `/v1/embeddings` to work natively. When true, the context should be a
+     * dedicated embedding model and will typically not be usable for
+     * chat/completion. Default: false.
+     */
+    nativeEmbeddingMode?: boolean;
+    /**
+     * Path (or fetchable URL) to your DVAI-Bridge license JWT file.
+     *
+     * Default behaviour when this is unset: the SDK looks for
+     * `dvai-license.jwt` at platform-conventional locations:
+     *   - Node: `process.cwd()/dvai-license.jwt` (and one level up for
+     *     monorepos)
+     *   - Browser / Capacitor: same-origin `/dvai-license.jwt`
+     *
+     * Override mechanisms in priority order:
+     *   1. `licenseToken` (below) — inline JWT string, highest priority
+     *   2. `licenseKeyPath` (this field) — explicit path or URL
+     *   3. `DVAI_LICENSE_PATH` env var
+     *   4. `DVAI_LICENSE_TOKEN` env var — inline JWT
+     *   5. Auto-discovery
+     *
+     * If no license is found OR validation fails, the SDK falls back to
+     * the free tier (with the "Powered by DVAI Bridge" attribution
+     * badge in browser/Capacitor contexts). The SDK never refuses to
+     * start because of a license problem — license issues surface as a
+     * `licenseStatus` value with `kind: "free-prod"` and a
+     * human-readable `reason`.
+     */
+    licenseKeyPath?: string;
+    /**
+     * Inline DVAI-Bridge license JWT (the full token string). Use this
+     * when you'd rather inject the license via env var / config than
+     * ship a file — typical in serverless / containerised deployments
+     * where filesystem state is awkward.
+     *
+     * If both `licenseToken` and `licenseKeyPath` are set, `licenseToken`
+     * wins.
+     */
+    licenseToken?: string;
+    /** Auto-initialize on creation (React/Vanilla). Default: true */
+    autoInit?: boolean;
+    /**
+     * Phase 3 (v3.0+) — distributed inference / device offload.
+     *
+     * If unset OR `enabled: false`, the library behaves exactly like
+     * v2.x: every request runs locally. When enabled, the library
+     * discovers peer devices on the LAN (via mDNS) and / or via a
+     * self-hosted rendezvous server (if `rendezvousUrl` is set), and
+     * routes inference requests to the most-capable peer when local
+     * tok/s falls below `minLocalCapability`.
+     *
+     * See `docs/guide/distributed-inference.md` for the full design,
+     * `docs/guide/self-hosting-rendezvous.md` for the rendezvous
+     * server self-hosting flow, and `src/offload/types.ts` for the
+     * full `OffloadConfig` shape.
+     */
+    offload?: OffloadConfig;
+    /**
+     * Which transport to use for the OpenAI-compatible surface.
+     * - "auto"      (default) → capacitor on Capacitor, msw in browser,
+     *                            http in Node, none in workers
+     * - "msw"       → force MSW (browser only; errors elsewhere)
+     * - "http"      → force HTTP server (Node only; errors elsewhere)
+     * - "capacitor" → force native Capacitor HTTP server (requires
+     *                  @dvai-bridge/capacitor + a Capacitor backend plugin)
+     * - "none"      → no transport; use dvai.chatCompletion() directly
+     */
+    transport?: "auto" | "msw" | "http" | "none" | "capacitor";
+    /** HTTP-only. Base port. Default: 38883. */
+    httpBasePort?: number;
+    /** HTTP-only. Max port-fallback attempts. Default: 16. */
+    httpMaxPortAttempts?: number;
+    /**
+     * HTTP-only. Network interface to bind. Default `127.0.0.1`
+     * (loopback only). Set to `0.0.0.0` for LAN-target deployments
+     * (the v3.1 Hub, native SDKs running in target mode) so peers on
+     * the same Wi-Fi can reach the embedded server. Phone-as-source /
+     * single-device deployments should leave this default — a
+     * 0.0.0.0 bind on a developer laptop without pairing protection
+     * exposes the OpenAI surface.
+     */
+    httpBindHost?: string;
+    /**
+     * Phase 4 — first-chance interceptor for /v1/chat/completions. The
+     * v3.1 Hub uses this to apply substitution-policy + engine-bridge
+     * routing before falling through to the default local-backend
+     * handler. Return a Response → that's what the client gets;
+     * return null → fall through to the local backend.
+     *
+     * Receives request headers (lower-cased keys) so the interceptor
+     * can read the v3.1 identity fields (X-DVAI-Peer-Device-Id,
+     * X-DVAI-App-Id, X-DVAI-Nonce, X-DVAI-Signature) for HMAC verify.
+     */
+    chatCompletionInterceptor?: (body: any, ctx: HandlerContext, headers?: Record<string, string>) => Promise<Response | null>;
+    /**
+     * HTTP-only. Controls the Access-Control-Allow-Origin response header.
+     * - "*"               → echo "*" (default; dev-friendly)
+     * - "https://x.com"   → echo that exact origin
+     * - ["a.com","b.com"] → match the request's Origin header against the
+     *                        list; echo the matched value. Requests from
+     *                        unlisted origins get ACAO omitted.
+     */
+    corsOrigin?: string | string[];
+    /**
+     * Capacitor-backend selection (when transport resolves to "capacitor").
+     * Default: "llama".
+     */
+    capacitorBackend?: "llama" | "foundation" | "mediapipe";
+    /**
+     * Path to the mmproj (vision projector) file when using a multimodal
+     * llama.cpp model. Optional; only required for vision-capable models.
+     */
+    nativeMmprojPath?: string;
+}
+/**
+ * DVAI: Local AI Orchestration
+ * Orchestrates WebLLM or Transformers.js for local inference and selects
+ * an MSW, HTTP, or Capacitor transport (auto-detected from environment)
+ * to expose the OpenAI-compatible endpoint. On Capacitor, the native
+ * runtime runs in a first-party plugin behind the "capacitor" transport.
+ * Read `dvai.baseUrl` after initialize() to get the URL to point any
+ * OpenAI SDK at.
+ */
+declare class DVAI {
+    modelId: string;
+    mockUrl: string;
+    serviceWorkerUrl: string;
+    licenseKeyPath?: string;
+    licenseToken?: string;
+    /**
+     * Result of the most recent license validation. Populated by
+     * `initialize()`; consult before promoting paid-tier UI affordances
+     * (e.g. hiding the attribution badge). Null before initialization.
+     */
+    licenseStatus: LicenseStatus | null;
+    backend: BackendType;
+    transformersModelId: string;
+    pipelineTask: string;
+    device: DeviceType;
+    generationTimeout: number;
+    maxBlankChunks: number;
+    maxRetries: number;
+    webllmWorkerUrl: string;
+    transformersWorkerUrl: string;
+    dtype?: string;
+    createPipeline?: CreatePipelineFn;
+    transformersModelClass?: string;
+    transformersProcessorClass?: string;
+    transformersDisableEncoders?: string[];
+    nativeModelPath: string;
+    nativeGpuLayers: number;
+    nativeThreads: number;
+    nativeContextSize: number;
+    nativeEmbeddingMode: boolean;
+    capacitorBackend: "llama" | "foundation" | "mediapipe";
+    nativeMmprojPath?: string;
+    /** Raw transport config (e.g., "auto"). */
+    transport: "auto" | "msw" | "http" | "none" | "capacitor";
+    httpBasePort: number;
+    httpMaxPortAttempts: number;
+    corsOrigin: string | string[];
+    httpBindHost: string | undefined;
+    chatCompletionInterceptor: ((body: any, ctx: HandlerContext, headers?: Record<string, string>) => Promise<Response | null>) | undefined;
+    /** Resolved transport kind after selectTransport() runs. */
+    private resolvedTransport;
+    /** Populated after transport.start(). Undefined on "none". */
+    baseUrl?: string;
+    port?: number;
+    /** Active transport instance; null before initialize() / after unload(). */
+    private activeTransport;
+    private validator;
+    private backendInstance;
+    isReady: boolean;
+    /** Tracks how many consecutive recovery attempts have been made. */
+    private recoveryAttempts;
+    /** The resolved backend type (after "auto" resolution). */
+    private resolvedBackend;
+    /** OffloadConfig as supplied by the consumer (or undefined). */
+    offload?: OffloadConfig;
+    /**
+     * v3.2 — set true when the pre-init capability gate decides this
+     * device is below `OffloadConfig.minLocalCapability`. In this mode
+     * `initialize()` skips backend init entirely (no model download /
+     * load) and only brings up discovery + pairing. Every request is
+     * expected to be forwarded to a paired peer; without one, requests
+     * 503.
+     */
+    offloadOnlyMode: boolean;
+    /** Capability cache (persistent storage of probe scores). */
+    private capabilityCache?;
+    /** Phase 3 — built when offload.enabled; mounted on the HTTP transport via the handler context. */
+    private dvaiRoutes?;
+    /** Used by the dvai/health endpoint to report uptime. */
+    private startedAt;
+    /** Discovery layer — composite of LAN mDNS + static + custom. */
+    private discovery?;
+    /** Pairing policy (LAN-handshake auth + persistent store). */
+    private pairingPolicy?;
+    /** Stable per-install device ID (cached after first call). */
+    private deviceId?;
+    constructor(config?: DVAIConfig);
+    /**
+     * Returns the active backend type (resolved from "auto" if applicable).
+     */
+    getActiveBackend(): "webllm" | "transformers" | "native";
+    /** Returns the resolved transport kind (after "auto" resolution). */
+    getActiveTransport(): "msw" | "http" | "none" | "capacitor";
+    /** Returns the base URL a host app hands to an OpenAI SDK. */
+    getBaseUrl(): string | undefined;
+    /** Returns the HTTP port bound (http transport only). */
+    getPort(): number | undefined;
+    /**
+     * Resolves the "auto" backend to a concrete type based on environment.
+     *
+     * On Capacitor, the native runtime is selected via `transport: "capacitor"`
+     * (which delegates to a native HTTP server in the Capacitor plugin), not
+     * via the backend. The backend stays in the webview as a thin client.
+     */
+    private resolveBackend;
+    /**
+     * Initializes the selected backend engine and starts the resolved
+     * transport (MSW in browsers, HTTP server in Node, or none).
+     * @param onProgress - Callback for model download progress
+     */
+    initialize(onProgress?: (info: any) => void): Promise<boolean>;
+    /**
+     * Phase 3 — bring up the capability cache, discovery layer, and
+     * pairing policy on top of an already-running DVAI instance.
+     * Called from initialize() when `offload.enabled` is true.
+     */
+    private initializeOffload;
+    /** Phase 3 — release offload state (LAN advertiser, discovery sockets, etc). */
+    private shutdownOffload;
+    /**
+     * Builds a HandlerContext consumed by the transport-agnostic handlers.
+     * `backend` is exposed via a getter so that when recovery replaces
+     * `this.backendInstance` mid-request, the handler's subsequent reads of
+     * `ctx.backend` see the new instance (critical for the reactive-recovery
+     * retry path in handleChatCompletion).
+     */
+    private getHandlerContext;
+    /**
+     * Attempts to recover from a fatal WebLLM error by unloading and reloading the backend.
+     */
+    private attemptRecovery;
+    /**
+     * Lazy-imports and initializes the selected backend.
+     */
+    private initializeBackend;
+    /**
+     * Gets the underlying engine instance directly.
+     * - For WebLLM: returns the MLCEngine
+     * - For Transformers.js: returns the pipeline
+     */
+    getEngine(): any;
+    /**
+     * Perform a direct chat completion (bypasses MSW, calls backend directly).
+     * Useful for programmatic usage without going through the fetch mock.
+     */
+    chatCompletion(requestBody: any): Promise<any>;
+    /**
+     * Generate embeddings for one or more text inputs.
+     *
+     * Supported when backend is "transformers" with
+     * pipelineTask: "feature-extraction".
+     *
+     * Throws when called on the WebLLM backend.
+     *
+     * @param inputs - A single string or array of strings to embed
+     * @returns An array of embedding vectors (one per input)
+     */
+    embedding(inputs: string | string[]): Promise<number[][]>;
+    /**
+     * Run the pipeline directly (Transformers.js only).
+     * Use this for non-text tasks like text-to-image, ASR, text-to-speech, etc.
+     * @param inputs - Input data appropriate for the pipeline task
+     * @param options - Pipeline-specific options
+     */
+    runPipeline(inputs: any, options?: Record<string, any>): Promise<any>;
+    /**
+     * Unloads the AI engine and stops the active transport to free up resources.
+     */
+    unload(): Promise<void>;
+    /**
+     * v3.2 — pre-init hardware assessment.
+     *
+     * Returns a JSON-serializable description of how this device
+     * would handle local inference, BEFORE any model download/load.
+     *
+     * Consumers should call this before `initialize()` if they want
+     * to refuse to start on too-weak devices. The SDK itself never
+     * shows UI — it's the consumer app's job to decide what (if
+     * anything) to surface based on the result.
+     *
+     * Result `mode` values:
+     *   - `ok`           → device can comfortably run the model
+     *                      locally; initialize() will proceed normally.
+     *   - `offload-only` → device can run but slowly (below
+     *                      `minLocalCapability`); initialize() will
+     *                      skip the model load and route every
+     *                      request to a paired peer.
+     *   - `too-weak`     → device is below the hardware floor (3
+     *                      tok/s by default); initialize() will
+     *                      ALSO skip the model load — the consumer
+     *                      should typically bail rather than even
+     *                      calling initialize().
+     *
+     * Pass `hardwareMinimum` / `minLocalCapability` to override the
+     * defaults (matches `OffloadConfig`).
+     *
+     * @returns a serializable assessment (safe to JSON.stringify and
+     *   ship over a Pigeon / Capacitor channel).
+     */
+    assessHardware(opts?: {
+        hardwareMinimum?: number;
+        minLocalCapability?: number;
+    }): Promise<{
+        mode: "ok" | "offload-only" | "too-weak";
+        tokPerSec: number;
+        reason: string;
+        hints: DeviceCapabilityHints;
+    }>;
+    /**
+     * Run a cold-run capability probe against the active backend +
+     * model. Persists the result for future getCapability() calls.
+     * Requires offload.enabled.
+     */
+    probeCapability(): Promise<CapabilityScore | undefined>;
+    /**
+     * Get the cached capability score for a model on this device, or
+     * compute a heuristic estimate if no probe has run yet.
+     */
+    getCapability(modelId?: string): Promise<CapabilityScore | undefined>;
+    /** Snapshot of currently-known peers via the discovery layer. */
+    getPeers(): Peer[];
+}
+declare const dvai: DVAI;
+
+export { type BackendType, type CreatePipelineFn, DEFAULT_LICENSE_FILENAME, DVAI, type DVAIConfig, DVAI_PUBLIC_KEYS, type DeviceType, type DvaiLicensePayload, type DvaiPlatform, type DvaiPublicKeyJwk, type LicenseDiscoveryOptions, LicenseRequiredError, type LicenseStatus, type LicenseTier, LicenseValidator, type LicenseValidatorOptions, PLACEHOLDER_KID, type PipelineCallable, type PipelineTask, type TransformersProgressInfo, chatToLegacyCompletion, composeSignedMessage, detectWebGPU, dvai, generateNonce, generatePairingKey, isPaidTier, legacyCompletionStreamAdapter, signHmac, verifyHmac };