modeldispatcher-client 0.6.0

package/src/interceptors/appcheck.ts

@@ -0,0 +1,33 @@
+/**
+ * Firebase App Check interceptor (request side).
+ *
+ * Mints/attaches the attestation token the Vercel Python wrapper verifies before
+ * it will invoke the gateway. The token *provider* is injected rather than
+ * importing the Firebase SDK directly, so this package carries no hard Firebase
+ * dependency and stays trivially testable — the app wires
+ * `() => getToken(appCheck).then(r => r.token)` at construction time.
+ */
+
+import type { AppCheckTokenProvider } from "../types.js";
+import type { GatewayRequestConfig, Interceptor, Send } from "./interceptor.js";
+
+/** HTTP header the wrapper reads (matches `firebase_admin.app_check`). */
+export const APP_CHECK_HEADER = "X-Firebase-AppCheck";
+
+/**
+ * Build the interceptor that stamps every request with an App Check token.
+ *
+ * A `null` token (provider opted out, or dev bypass) is simply not attached;
+ * the wrapper then decides whether to reject based on its own environment.
+ */
+export function appCheckInterceptor(provider: AppCheckTokenProvider): Interceptor {
+  return {
+    async intercept(config: GatewayRequestConfig, next: Send): Promise<Response> {
+      const token = await provider();
+      if (token) {
+        config.headers[APP_CHECK_HEADER] = token;
+      }
+      return next(config);
+    },
+  };
+}

package/src/interceptors/auth.ts

@@ -0,0 +1,34 @@
+/**
+ * Firebase Auth interceptor (request side).
+ *
+ * Mints/attaches the ID token the Vercel Python wrapper verifies to derive an
+ * *authoritative* tenant id (see `_lib/auth.py`). Mirrors
+ * {@link appCheckInterceptor} exactly: the token provider is injected rather
+ * than importing the Firebase SDK directly, so this package carries no hard
+ * Firebase dependency. Without this header, the wrapper's `MD_AUTH_MODE=enforce`
+ * default rejects the request with `401` before the gateway ever runs.
+ */
+
+import type { AuthTokenProvider } from "../types.js";
+import type { GatewayRequestConfig, Interceptor, Send } from "./interceptor.js";
+
+/** HTTP header the wrapper reads the bearer token from. */
+export const AUTHORIZATION_HEADER = "Authorization";
+
+/**
+ * Build the interceptor that stamps every request with a Firebase Auth ID token.
+ *
+ * A `null` token (provider opted out, or dev bypass) is simply not attached;
+ * the wrapper then decides whether to reject based on its own `MD_AUTH_MODE`.
+ */
+export function authInterceptor(provider: AuthTokenProvider): Interceptor {
+  return {
+    async intercept(config: GatewayRequestConfig, next: Send): Promise<Response> {
+      const token = await provider();
+      if (token) {
+        config.headers[AUTHORIZATION_HEADER] = `Bearer ${token}`;
+      }
+      return next(config);
+    },
+  };
+}

package/src/interceptors/handoff.ts

@@ -0,0 +1,91 @@
+/**
+ * Response decoder: HTTP {@link Response} → {@link DispatchOutcome}.
+ *
+ * This is where the gateway's `to_payload()` contract is interpreted. A `2xx`
+ * body becomes `{ kind: "ok" }`; a non-OK body whose `action` names a known
+ * handoff becomes `{ kind: "handoff" }` *and* is published on the event bus so a
+ * decoupled wizard host can react; anything else becomes `{ kind: "error" }`.
+ * Runs after the retry interceptor, so only *final* responses reach it.
+ */
+
+import type { GatewayEventBus } from "../events.js";
+import type {
+  DispatchOutcome,
+  GatewayError,
+  Handoff,
+  HandoffAction,
+} from "../types.js";
+
+/** The actions this client knows how to surface. */
+export const HANDOFF_ACTIONS: readonly HandoffAction[] = [
+  "trigger_key_wizard",
+  "upgrade_plan",
+  "retry_later",
+];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** Type guard: does an arbitrary parsed body match the {@link Handoff} shape? */
+export function isHandoffPayload(body: unknown): body is Handoff {
+  if (!isRecord(body)) return false;
+  return (
+    typeof body["error"] === "string" &&
+    typeof body["provider"] === "string" &&
+    typeof body["action"] === "string" &&
+    (HANDOFF_ACTIONS as readonly string[]).includes(body["action"])
+  );
+}
+
+/** Parse a JSON body without throwing; returns `undefined` on empty/invalid. */
+async function readJson(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function toGatewayError(body: unknown, status: number): GatewayError {
+  if (isRecord(body) && typeof body["error"] === "string") {
+    const detail = body["detail"];
+    return {
+      error: body["error"],
+      ...(typeof detail === "string" ? { detail } : {}),
+    };
+  }
+  return { error: "unexpected_response", detail: `HTTP ${status}` };
+}
+
+/**
+ * Decode a final response into a typed outcome.
+ *
+ * @param response - The response emerging from the interceptor chain.
+ * @param bus - Event bus a handoff is published on before returning.
+ */
+export async function decodeOutcome<T>(
+  response: Response,
+  bus: GatewayEventBus,
+): Promise<DispatchOutcome<T>> {
+  const body = await readJson(response);
+
+  if (response.ok) {
+    return { kind: "ok", result: body as T };
+  }
+
+  if (isHandoffPayload(body)) {
+    const handoff: Handoff = {
+      error: body.error,
+      provider: body.provider,
+      action: body.action,
+      ...(body.detail !== undefined ? { detail: body.detail } : {}),
+    };
+    bus.emit("handoff", { status: response.status, handoff });
+    return { kind: "handoff", status: response.status, handoff };
+  }
+
+  return { kind: "error", status: response.status, error: toGatewayError(body, response.status) };
+}

package/src/interceptors/interceptor.ts

@@ -0,0 +1,53 @@
+/**
+ * Interceptor pipeline contracts (Chain of Responsibility).
+ *
+ * Each {@link Interceptor} receives the outgoing request config and a `next`
+ * continuation. It may mutate the config, short-circuit, wrap `next` with
+ * cross-cutting behaviour (timeout, retry), and inspect the resulting response
+ * before returning it. Interceptors are composed as an onion: the first in the
+ * list is the outermost layer.
+ */
+
+/** The in-flight request description handed down the interceptor chain. */
+export interface GatewayRequestConfig {
+  /** Absolute or app-relative endpoint, e.g. `"/api/gateway"`. */
+  url: string;
+  /** HTTP method; the gateway endpoint is `POST`. */
+  method: string;
+  /** Mutable header bag; interceptors add to it (App Check, content-type). */
+  headers: Record<string, string>;
+  /** JSON-serialisable request body. */
+  body: unknown;
+  /** Per-attempt timeout in milliseconds. */
+  timeoutMs: number;
+  /** Optional caller-supplied cancellation signal, merged with the timeout. */
+  signal?: AbortSignal;
+}
+
+/** Terminal continuation: performs exactly one transport attempt. */
+export type Send = (config: GatewayRequestConfig) => Promise<Response>;
+
+/** A single layer of the request/response pipeline. */
+export interface Interceptor {
+  /**
+   * Process the request and return a response.
+   *
+   * @param config - The (mutable) request configuration.
+   * @param next - Continuation invoking the remaining inner layers.
+   */
+  intercept(config: GatewayRequestConfig, next: Send): Promise<Response>;
+}
+
+/**
+ * Fold a list of interceptors around a terminal {@link Send} into one `Send`.
+ *
+ * The first interceptor becomes the outermost layer, so a list of
+ * `[appcheck, retry, timeout]` yields `appcheck(retry(timeout(fetch)))` — retry
+ * re-drives the timeout+transport on each attempt.
+ */
+export function compose(interceptors: readonly Interceptor[], terminal: Send): Send {
+  return interceptors.reduceRight<Send>(
+    (next, interceptor) => (config) => interceptor.intercept(config, next),
+    terminal,
+  );
+}

package/src/interceptors/retry.ts

@@ -0,0 +1,92 @@
+/**
+ * Retry interceptor with exponential backoff (Policy object pattern).
+ *
+ * Re-issues the request when the response status is in
+ * {@link RetryPolicy.retryableStatuses} — the 5xx family — sleeping
+ * `min(maxDelayMs, baseDelayMs * 2 ** attempt)` between tries, optionally with
+ * full jitter to avoid a thundering herd. It deliberately does **not** retry
+ * `402`/`429`: those are structured quota handoffs that must reach the UI intact,
+ * not transient faults to paper over. Transport errors thrown by inner layers
+ * (e.g. a timeout) propagate unchanged so the client can classify them.
+ */
+
+import type { Scheduler } from "../types.js";
+import type { GatewayRequestConfig, Interceptor, Send } from "./interceptor.js";
+
+/** Tunable backoff parameters. */
+export interface RetryPolicy {
+  /** Maximum *additional* attempts after the first (e.g. `3`). */
+  readonly maxRetries: number;
+  /** Base delay in milliseconds (e.g. `250`). */
+  readonly baseDelayMs: number;
+  /** Upper bound on any single backoff sleep. */
+  readonly maxDelayMs: number;
+  /** Apply full jitter (`random(0, delay)`) when `true`. */
+  readonly jitter: boolean;
+  /** Statuses worth retrying. Never include `402`/`429`. */
+  readonly retryableStatuses: readonly number[];
+}
+
+/** Sensible defaults for a Vercel ↔ serverless-Python round trip. */
+export const DEFAULT_RETRY_POLICY: RetryPolicy = {
+  maxRetries: 3,
+  baseDelayMs: 250,
+  maxDelayMs: 4_000,
+  jitter: true,
+  retryableStatuses: [500, 502, 503, 504],
+};
+
+/** Real-time scheduler backing the default client. */
+export const REAL_SCHEDULER: Scheduler = {
+  sleep: (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now: () => Date.now(),
+};
+
+/**
+ * Compute the backoff for a given zero-based attempt index.
+ *
+ * @param policy - The active {@link RetryPolicy}.
+ * @param attempt - Number of retries already performed (0 for the first retry).
+ * @param random - Source of `[0, 1)` randomness (injected for deterministic tests).
+ */
+export function backoffDelayMs(
+  policy: RetryPolicy,
+  attempt: number,
+  random: () => number = Math.random,
+): number {
+  const uncapped = policy.baseDelayMs * 2 ** attempt;
+  const capped = Math.min(policy.maxDelayMs, uncapped);
+  return policy.jitter ? Math.floor(random() * capped) : capped;
+}
+
+/** Options for {@link retryInterceptor}. */
+export interface RetryOptions {
+  readonly policy?: RetryPolicy;
+  readonly scheduler?: Scheduler;
+  readonly random?: () => number;
+}
+
+/** Build the backoff/retry {@link Interceptor}. */
+export function retryInterceptor(options: RetryOptions = {}): Interceptor {
+  const policy = options.policy ?? DEFAULT_RETRY_POLICY;
+  const scheduler = options.scheduler ?? REAL_SCHEDULER;
+  const random = options.random ?? Math.random;
+
+  return {
+    async intercept(config: GatewayRequestConfig, next: Send): Promise<Response> {
+      let response = await next(config);
+      let attempt = 0;
+
+      while (
+        policy.retryableStatuses.includes(response.status) &&
+        attempt < policy.maxRetries
+      ) {
+        await scheduler.sleep(backoffDelayMs(policy, attempt, random));
+        attempt += 1;
+        response = await next(config);
+      }
+
+      return response;
+    },
+  };
+}

package/src/interceptors/timeout.ts

@@ -0,0 +1,48 @@
+/**
+ * Timeout interceptor.
+ *
+ * Arms an {@link AbortController} that fires after `config.timeoutMs`, and also
+ * forwards any caller-supplied `config.signal`, so a slow serverless cold-start
+ * cannot hang the UI. When the deadline trips it re-labels the resulting
+ * `AbortError` as a {@link TimeoutError} (an external cancellation keeps its
+ * original error), which the client maps to a `{ kind: "network" }` outcome.
+ */
+
+import type { GatewayRequestConfig, Interceptor, Send } from "./interceptor.js";
+
+/** Thrown when a single transport attempt exceeds its deadline. */
+export class TimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`request exceeded ${timeoutMs}ms timeout`);
+    this.name = "TimeoutError";
+  }
+}
+
+/** Build the {@link Interceptor} that enforces a per-attempt deadline. */
+export function timeoutInterceptor(): Interceptor {
+  return {
+    async intercept(config: GatewayRequestConfig, next: Send): Promise<Response> {
+      const controller = new AbortController();
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+      }, config.timeoutMs);
+
+      const external = config.signal;
+      if (external) {
+        if (external.aborted) controller.abort();
+        else external.addEventListener("abort", () => controller.abort(), { once: true });
+      }
+
+      try {
+        return await next({ ...config, signal: controller.signal });
+      } catch (error) {
+        if (timedOut) throw new TimeoutError(config.timeoutMs);
+        throw error;
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  };
+}

package/src/react/useGateway.ts

@@ -0,0 +1,67 @@
+/**
+ * React binding for {@link GatewayClient}.
+ *
+ * Subscribes to the client's event bus and lifts any `trigger_key_wizard`
+ * handoff into local state, so a component can render the API-key wizard
+ * declaratively without threading the dispatch outcome down through props. The
+ * `dispatch` it returns still yields the typed {@link DispatchOutcome} for
+ * call-site handling — both paths, one decode.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+
+import type { GatewayClient, DispatchOptions } from "../client.js";
+import type { DispatchOutcome, GatewayResult, HandoffAction } from "../types.js";
+
+/** UI-facing snapshot of an active key-wizard handoff. */
+export interface WizardState {
+  readonly provider: string;
+  readonly status: number;
+  readonly action: HandoffAction;
+  readonly detail?: string;
+}
+
+/** Return value of {@link useGateway}. */
+export interface UseGatewayResult<T> {
+  /** Dispatch a request; resolves to a typed outcome (never rejects). */
+  dispatch: (body: unknown, options?: DispatchOptions) => Promise<DispatchOutcome<T>>;
+  /** Non-null when the gateway asked the UI to open the key wizard. */
+  wizard: WizardState | null;
+  /** Dismiss the wizard (e.g. after the user saves a key). */
+  dismissWizard: () => void;
+}
+
+/**
+ * Bind a {@link GatewayClient} to React state.
+ *
+ * @param client - A stable client instance (create it once, e.g. in a module or
+ *   a context provider, not inside render).
+ */
+export function useGateway<T = GatewayResult>(
+  client: GatewayClient,
+): UseGatewayResult<T> {
+  const [wizard, setWizard] = useState<WizardState | null>(null);
+
+  useEffect(() => {
+    const unsubscribe = client.bus.on("handoff", ({ status, handoff }) => {
+      if (handoff.action === "trigger_key_wizard") {
+        setWizard({
+          provider: handoff.provider,
+          status,
+          action: handoff.action,
+          ...(handoff.detail !== undefined ? { detail: handoff.detail } : {}),
+        });
+      }
+    });
+    return unsubscribe;
+  }, [client]);
+
+  const dispatch = useCallback(
+    (body: unknown, options?: DispatchOptions) => client.dispatch<T>(body, options),
+    [client],
+  );
+
+  const dismissWizard = useCallback(() => setWizard(null), []);
+
+  return { dispatch, wizard, dismissWizard };
+}

package/src/types.ts

@@ -0,0 +1,112 @@
+/**
+ * Public type surface for the ModelDispatcher client.
+ *
+ * These interfaces are the strict, versioned contract between a Vercel frontend
+ * and the packaged Python gateway. The response-side types intentionally mirror
+ * the gateway's `to_payload()` output (see `src/model_dispatcher/exceptions.py`
+ * and `onboarding/handoff.py`): the discriminated {@link DispatchOutcome} is the
+ * TypeScript view of "either a run result, a structured onboarding handoff, a
+ * mapped HTTP error, or a transport failure".
+ */
+
+/** A handoff action the gateway can instruct the UI to take. */
+export type HandoffAction = "trigger_key_wizard" | "upgrade_plan" | "retry_later";
+
+/**
+ * The structured Stage-2 onboarding instruction returned by the gateway.
+ *
+ * Serialised form (from the Python `HandoffResponse.to_payload`):
+ * `{"error": "quota_exceeded", "provider": "openai", "action": "trigger_key_wizard"}`.
+ */
+export interface Handoff {
+  /** Machine-readable error code, e.g. `"quota_exceeded"`. */
+  readonly error: string;
+  /** Provider whose limit was hit, so the wizard can pre-select it. */
+  readonly provider: string;
+  /** What the client UI should do next. */
+  readonly action: HandoffAction;
+  /** Optional human-readable explanation for display/logging. */
+  readonly detail?: string;
+}
+
+/** A non-handoff error body mapped from a `ModelDispatcherError`. */
+export interface GatewayError {
+  /** Stable machine-readable slug, e.g. `"perimeter_violation"`. */
+  readonly error: string;
+  /** Human-readable description, when the backend supplies one. */
+  readonly detail?: string;
+}
+
+/** Kinds of transport failure that never reached a well-formed HTTP response. */
+export type NetworkErrorKind = "timeout" | "offline" | "retries_exhausted" | "unknown";
+
+/** A failure to obtain any HTTP response (before status interpretation). */
+export interface NetworkError {
+  readonly kind: NetworkErrorKind;
+  /** Human-readable summary for logging/telemetry. */
+  readonly message: string;
+  /** The underlying thrown value, when one is available. */
+  readonly cause?: unknown;
+}
+
+/**
+ * The result of a dispatch, as a discriminated union.
+ *
+ * `T` is the shape of a successful gateway run (default {@link GatewayResult}).
+ * Callers narrow on `kind`; there is no other legal way to read the payload.
+ */
+export type DispatchOutcome<T = GatewayResult> =
+  | { readonly kind: "ok"; readonly result: T }
+  | { readonly kind: "handoff"; readonly status: number; readonly handoff: Handoff }
+  | { readonly kind: "error"; readonly status: number; readonly error: GatewayError }
+  | { readonly kind: "network"; readonly error: NetworkError };
+
+/** Token usage reported by a completed run. */
+export interface Usage {
+  readonly prompt: number;
+  readonly completion: number;
+  readonly total: number;
+}
+
+/** One provider attempt within a run step (mirrors the demo trace shape). */
+export interface Attempt {
+  readonly provider: string;
+  readonly error: string | null;
+}
+
+/** One turn of the agent loop. */
+export interface Step {
+  readonly message: string | null;
+  readonly usage: number;
+  readonly attempts: readonly Attempt[];
+}
+
+/** Default success shape returned by the reference `/api/gateway` wrapper. */
+export interface GatewayResult {
+  readonly final: string | null;
+  readonly stop_reason: string;
+  readonly complexity: string;
+  readonly usage: Usage;
+  readonly steps: readonly Step[];
+}
+
+/** Zero-argument async supplier of a Firebase App Check token. */
+export type AppCheckTokenProvider = () => Promise<string | null>;
+
+/**
+ * Zero-argument async supplier of a Firebase Auth ID token.
+ *
+ * Distinct from {@link AppCheckTokenProvider}: App Check attests the *app*,
+ * this attests the *end user* — the wrapper derives the authoritative tenant
+ * id (and thus quota isolation) from this token's verified `uid`, not from
+ * anything in the request body. See `_lib/auth.py`.
+ */
+export type AuthTokenProvider = () => Promise<string | null>;
+
+/** Injectable clock/timer seam so retry backoff is deterministic under test. */
+export interface Scheduler {
+  /** Resolve after `ms` milliseconds. */
+  sleep(ms: number): Promise<void>;
+  /** Current epoch milliseconds. */
+  now(): number;
+}