modeldispatcher-client 0.6.0 → 0.6.7

package/src/interceptors/retry.ts

@@ -1,92 +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;
-    },
-  };
-}
+/**
+ * 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

@@ -1,48 +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);
-      }
-    },
-  };
-}
+/**
+ * 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

@@ -1,67 +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 };
-}
+/**
+ * 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

@@ -1,112 +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;
-}
+/**
+ * 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;
+}