@halo-sdk/gateway 1.0.0

package/README.md

@@ -0,0 +1,31 @@
+# @halo-sdk/gateway
+
+Cache-aware AI gateway for Halo SDK. A `ModelAdapter` that fronts a pool of providers with:
+
+- **Sticky routing** — requests stay on the last provider that succeeded, so that provider's prefix cache stays warm. The gateway only moves off it on failure (not round-robin, which would cold-start a different cache every call).
+- **Fallback chains** — on error it tries the remaining providers in order.
+
+Every routing decision emits a `route` event onto the S5 observability spine.
+
+## Usage
+
+```ts
+import { GatewayAdapter } from "@halo-sdk/gateway";
+import { AnthropicAdapter, OpenAIAdapter } from "@halo-sdk/adapters";
+
+const gateway = new GatewayAdapter({
+  routes: [
+    { name: "anthropic", adapter: new AnthropicAdapter({ apiKey: A }) },
+    { name: "openai", adapter: new OpenAIAdapter({ apiKey: O }) }, // fallback
+  ],
+  onEvent: (e) => console.log(e), // wire to an agent's event bus
+});
+
+const agent = halo.agent({ adapter: gateway /* ... */ });
+```
+
+It composes with the `@halo-sdk/otel` decorators — wrap each route's adapter with `withRetry` / `withTelemetry` as needed.
+
+## Reserved extension point
+
+The `middleware` option (`GatewayMiddleware`) is the designated integration seam for a forthcoming maintainer-defined capability. Implementations must emit their activity onto the S5 event stream. This interface will change when that capability lands.

package/dist/index.cjs

@@ -0,0 +1,115 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  GatewayAdapter: () => GatewayAdapter
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@halo-sdk/core");
+var GatewayAdapter = class {
+  _routes;
+  _onEvent;
+  _middleware;
+  _preferred = 0;
+  constructor(opts) {
+    if (!opts.routes.length) throw new Error("GatewayAdapter requires at least one route.");
+    this._routes = opts.routes;
+    this._onEvent = opts.onEvent;
+    this._middleware = opts.middleware;
+  }
+  // Surface the currently-preferred provider's capabilities/pricing/identity.
+  get _primary() {
+    return this._routes[this._preferred].adapter;
+  }
+  get modelId() {
+    return this._primary.modelId;
+  }
+  get contextWindow() {
+    return this._primary.contextWindow;
+  }
+  get capabilities() {
+    return this._primary.capabilities;
+  }
+  get pricing() {
+    return this._primary.pricing;
+  }
+  /** Provider order the gateway will try this call: preferred first, then the rest. */
+  _order() {
+    const order = [this._preferred];
+    for (let i = 0; i < this._routes.length; i++) if (i !== this._preferred) order.push(i);
+    return order;
+  }
+  _emitRoute(route, reason) {
+    this._onEvent?.({
+      type: "route",
+      ts: (0, import_core.eventNow)(),
+      provider: route.name,
+      model: route.adapter.modelId,
+      reason
+    });
+  }
+  async chat(params) {
+    let lastErr = new Error("no routes");
+    const order = this._order();
+    for (let oi = 0; oi < order.length; oi++) {
+      const idx = order[oi];
+      const route = this._routes[idx];
+      try {
+        await this._middleware?.beforeRequest?.({ route, params });
+        this._emitRoute(route, oi === 0 ? "sticky" : `fallback:${lastErr.message}`);
+        const result = await route.adapter.chat(params);
+        await this._middleware?.afterResponse?.({ route, usage: result.usage });
+        this._preferred = idx;
+        return result;
+      } catch (err) {
+        lastErr = err instanceof Error ? err : new Error(String(err));
+      }
+    }
+    throw lastErr;
+  }
+  async *stream(params) {
+    const order = this._order();
+    let lastErr = new Error("no routes");
+    for (let oi = 0; oi < order.length; oi++) {
+      const idx = order[oi];
+      const route = this._routes[idx];
+      try {
+        await this._middleware?.beforeRequest?.({ route, params });
+        const gen = route.adapter.stream(params);
+        const first = await gen.next();
+        this._emitRoute(route, oi === 0 ? "sticky" : `fallback:${lastErr.message}`);
+        this._preferred = idx;
+        if (!first.done) yield first.value;
+        yield* gen;
+        await this._middleware?.afterResponse?.({ route });
+        return;
+      } catch (err) {
+        lastErr = err instanceof Error ? err : new Error(String(err));
+      }
+    }
+    throw lastErr;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GatewayAdapter
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  eventNow,\n  type ChatParams,\n  type HaloEvent,\n  type ModelAdapter,\n  type ModelCapabilities,\n  type PricingInfo,\n  type ToolCall,\n  type TurnChunk,\n  type Usage,\n} from \"@halo-sdk/core\";\n\n/** A named provider in the gateway's routing pool. */\nexport interface GatewayRoute {\n  /** Human-readable provider name (for route events + diagnostics). */\n  name: string;\n  adapter: ModelAdapter;\n}\n\n/**\n * Reserved extension seam.\n *\n * The gateway is the designated integration point for a forthcoming\n * maintainer-defined capability (TBD). Implementations receive every request\n * and response and **must** emit their activity onto the S5 event stream via\n * the gateway's route/observer callback rather than logging out of band. This\n * interface and its call sites will change when that capability lands.\n */\nexport interface GatewayMiddleware {\n  beforeRequest?(ctx: { route: GatewayRoute; params: ChatParams }): void | Promise<void>;\n  afterResponse?(ctx: { route: GatewayRoute; usage?: Usage }): void | Promise<void>;\n}\n\nexport interface GatewayOptions {\n  /** Providers in priority order; the first is the default route. */\n  routes: GatewayRoute[];\n  /**\n   * Sink for `route` {@link HaloEvent}s. Wire it to an agent's observer, e.g.\n   * `new GatewayAdapter({ routes, onEvent: (e) => bus.emit(e) })`.\n   */\n  onEvent?: (event: Extract<HaloEvent, { type: \"route\" }>) => void;\n  /** Reserved extension seam (see {@link GatewayMiddleware}). */\n  middleware?: GatewayMiddleware;\n}\n\n/**\n * A cache-aware {@link ModelAdapter} that fronts a pool of providers.\n *\n * - **Sticky routing** — requests stay on the last provider that succeeded, so\n *   that provider's prefix cache stays warm; the gateway only moves on failure.\n * - **Fallback chains** — on error it tries the remaining providers in order;\n *   a fallback never silently discards a warm cache because routing is sticky,\n *   not round-robin.\n *\n * Composes with the `@halo-sdk/otel` decorators (wrap each route's adapter) and\n * emits a `route` event (onto the S5 spine via `onEvent`) for every decision.\n */\nexport class GatewayAdapter implements ModelAdapter {\n  private readonly _routes: GatewayRoute[];\n  private readonly _onEvent: ((event: Extract<HaloEvent, { type: \"route\" }>) => void) | undefined;\n  private readonly _middleware: GatewayMiddleware | undefined;\n  private _preferred = 0;\n\n  constructor(opts: GatewayOptions) {\n    if (!opts.routes.length) throw new Error(\"GatewayAdapter requires at least one route.\");\n    this._routes = opts.routes;\n    this._onEvent = opts.onEvent;\n    this._middleware = opts.middleware;\n  }\n\n  // Surface the currently-preferred provider's capabilities/pricing/identity.\n  private get _primary(): ModelAdapter {\n    return this._routes[this._preferred]!.adapter;\n  }\n  get modelId(): string {\n    return this._primary.modelId;\n  }\n  get contextWindow(): number {\n    return this._primary.contextWindow;\n  }\n  get capabilities(): ModelCapabilities {\n    return this._primary.capabilities;\n  }\n  get pricing(): PricingInfo | undefined {\n    return this._primary.pricing;\n  }\n\n  /** Provider order the gateway will try this call: preferred first, then the rest. */\n  private _order(): number[] {\n    const order = [this._preferred];\n    for (let i = 0; i < this._routes.length; i++) if (i !== this._preferred) order.push(i);\n    return order;\n  }\n\n  private _emitRoute(route: GatewayRoute, reason: string): void {\n    this._onEvent?.({\n      type: \"route\",\n      ts: eventNow(),\n      provider: route.name,\n      model: route.adapter.modelId,\n      reason,\n    });\n  }\n\n  async chat(params: ChatParams): Promise<{\n    content: string;\n    toolCalls: ToolCall[];\n    usage: Usage;\n    reasoning?: { text: string; signature?: string };\n  }> {\n    let lastErr: Error = new Error(\"no routes\");\n    const order = this._order();\n    for (let oi = 0; oi < order.length; oi++) {\n      const idx = order[oi]!;\n      const route = this._routes[idx]!;\n      try {\n        await this._middleware?.beforeRequest?.({ route, params });\n        this._emitRoute(route, oi === 0 ? \"sticky\" : `fallback:${lastErr.message}`);\n        const result = await route.adapter.chat(params);\n        await this._middleware?.afterResponse?.({ route, usage: result.usage });\n        this._preferred = idx; // stay sticky on the provider that worked\n        return result;\n      } catch (err: unknown) {\n        lastErr = err instanceof Error ? err : new Error(String(err));\n      }\n    }\n    throw lastErr;\n  }\n\n  async *stream(params: ChatParams): AsyncGenerator<TurnChunk> {\n    const order = this._order();\n    let lastErr: Error = new Error(\"no routes\");\n    for (let oi = 0; oi < order.length; oi++) {\n      const idx = order[oi]!;\n      const route = this._routes[idx]!;\n      try {\n        await this._middleware?.beforeRequest?.({ route, params });\n        // Open the stream eagerly so connection errors are caught here for fallback.\n        const gen = route.adapter.stream(params);\n        const first = await gen.next();\n        this._emitRoute(route, oi === 0 ? \"sticky\" : `fallback:${lastErr.message}`);\n        this._preferred = idx;\n        if (!first.done) yield first.value;\n        yield* gen;\n        await this._middleware?.afterResponse?.({ route });\n        return;\n      } catch (err: unknown) {\n        lastErr = err instanceof Error ? err : new Error(String(err));\n      }\n    }\n    throw lastErr;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import { type ChatParams, type HaloEvent, type ModelAdapter, type ModelCapabilities, type PricingInfo, type ToolCall, type TurnChunk, type Usage } from "@halo-sdk/core";
+/** A named provider in the gateway's routing pool. */
+export interface GatewayRoute {
+    /** Human-readable provider name (for route events + diagnostics). */
+    name: string;
+    adapter: ModelAdapter;
+}
+/**
+ * Reserved extension seam.
+ *
+ * The gateway is the designated integration point for a forthcoming
+ * maintainer-defined capability (TBD). Implementations receive every request
+ * and response and **must** emit their activity onto the S5 event stream via
+ * the gateway's route/observer callback rather than logging out of band. This
+ * interface and its call sites will change when that capability lands.
+ */
+export interface GatewayMiddleware {
+    beforeRequest?(ctx: {
+        route: GatewayRoute;
+        params: ChatParams;
+    }): void | Promise<void>;
+    afterResponse?(ctx: {
+        route: GatewayRoute;
+        usage?: Usage;
+    }): void | Promise<void>;
+}
+export interface GatewayOptions {
+    /** Providers in priority order; the first is the default route. */
+    routes: GatewayRoute[];
+    /**
+     * Sink for `route` {@link HaloEvent}s. Wire it to an agent's observer, e.g.
+     * `new GatewayAdapter({ routes, onEvent: (e) => bus.emit(e) })`.
+     */
+    onEvent?: (event: Extract<HaloEvent, {
+        type: "route";
+    }>) => void;
+    /** Reserved extension seam (see {@link GatewayMiddleware}). */
+    middleware?: GatewayMiddleware;
+}
+/**
+ * A cache-aware {@link ModelAdapter} that fronts a pool of providers.
+ *
+ * - **Sticky routing** — requests stay on the last provider that succeeded, so
+ *   that provider's prefix cache stays warm; the gateway only moves on failure.
+ * - **Fallback chains** — on error it tries the remaining providers in order;
+ *   a fallback never silently discards a warm cache because routing is sticky,
+ *   not round-robin.
+ *
+ * Composes with the `@halo-sdk/otel` decorators (wrap each route's adapter) and
+ * emits a `route` event (onto the S5 spine via `onEvent`) for every decision.
+ */
+export declare class GatewayAdapter implements ModelAdapter {
+    private readonly _routes;
+    private readonly _onEvent;
+    private readonly _middleware;
+    private _preferred;
+    constructor(opts: GatewayOptions);
+    private get _primary();
+    get modelId(): string;
+    get contextWindow(): number;
+    get capabilities(): ModelCapabilities;
+    get pricing(): PricingInfo | undefined;
+    /** Provider order the gateway will try this call: preferred first, then the rest. */
+    private _order;
+    private _emitRoute;
+    chat(params: ChatParams): Promise<{
+        content: string;
+        toolCalls: ToolCall[];
+        usage: Usage;
+        reasoning?: {
+            text: string;
+            signature?: string;
+        };
+    }>;
+    stream(params: ChatParams): AsyncGenerator<TurnChunk>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,KAAK,EACX,MAAM,gBAAgB,CAAC;AAExB,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,CAAC,GAAG,EAAE;QAAE,KAAK,EAAE,YAAY,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,aAAa,CAAC,CAAC,GAAG,EAAE;QAAE,KAAK,EAAE,YAAY,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF;AAED,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IACjE,+DAA+D;IAC/D,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,cAAe,YAAW,YAAY;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuE;IAChG,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAC5D,OAAO,CAAC,UAAU,CAAK;gBAEX,IAAI,EAAE,cAAc;IAQhC,OAAO,KAAK,QAAQ,GAEnB;IACD,IAAI,OAAO,IAAI,MAAM,CAEpB;IACD,IAAI,aAAa,IAAI,MAAM,CAE1B;IACD,IAAI,YAAY,IAAI,iBAAiB,CAEpC;IACD,IAAI,OAAO,IAAI,WAAW,GAAG,SAAS,CAErC;IAED,qFAAqF;IACrF,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,UAAU;IAUZ,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC;QACtC,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,QAAQ,EAAE,CAAC;QACtB,KAAK,EAAE,KAAK,CAAC;QACb,SAAS,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAClD,CAAC;IAoBK,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAAC,SAAS,CAAC;CAuB7D"}

package/dist/index.js

@@ -0,0 +1,92 @@
+// src/index.ts
+import {
+  eventNow
+} from "@halo-sdk/core";
+var GatewayAdapter = class {
+  _routes;
+  _onEvent;
+  _middleware;
+  _preferred = 0;
+  constructor(opts) {
+    if (!opts.routes.length) throw new Error("GatewayAdapter requires at least one route.");
+    this._routes = opts.routes;
+    this._onEvent = opts.onEvent;
+    this._middleware = opts.middleware;
+  }
+  // Surface the currently-preferred provider's capabilities/pricing/identity.
+  get _primary() {
+    return this._routes[this._preferred].adapter;
+  }
+  get modelId() {
+    return this._primary.modelId;
+  }
+  get contextWindow() {
+    return this._primary.contextWindow;
+  }
+  get capabilities() {
+    return this._primary.capabilities;
+  }
+  get pricing() {
+    return this._primary.pricing;
+  }
+  /** Provider order the gateway will try this call: preferred first, then the rest. */
+  _order() {
+    const order = [this._preferred];
+    for (let i = 0; i < this._routes.length; i++) if (i !== this._preferred) order.push(i);
+    return order;
+  }
+  _emitRoute(route, reason) {
+    this._onEvent?.({
+      type: "route",
+      ts: eventNow(),
+      provider: route.name,
+      model: route.adapter.modelId,
+      reason
+    });
+  }
+  async chat(params) {
+    let lastErr = new Error("no routes");
+    const order = this._order();
+    for (let oi = 0; oi < order.length; oi++) {
+      const idx = order[oi];
+      const route = this._routes[idx];
+      try {
+        await this._middleware?.beforeRequest?.({ route, params });
+        this._emitRoute(route, oi === 0 ? "sticky" : `fallback:${lastErr.message}`);
+        const result = await route.adapter.chat(params);
+        await this._middleware?.afterResponse?.({ route, usage: result.usage });
+        this._preferred = idx;
+        return result;
+      } catch (err) {
+        lastErr = err instanceof Error ? err : new Error(String(err));
+      }
+    }
+    throw lastErr;
+  }
+  async *stream(params) {
+    const order = this._order();
+    let lastErr = new Error("no routes");
+    for (let oi = 0; oi < order.length; oi++) {
+      const idx = order[oi];
+      const route = this._routes[idx];
+      try {
+        await this._middleware?.beforeRequest?.({ route, params });
+        const gen = route.adapter.stream(params);
+        const first = await gen.next();
+        this._emitRoute(route, oi === 0 ? "sticky" : `fallback:${lastErr.message}`);
+        this._preferred = idx;
+        if (!first.done) yield first.value;
+        yield* gen;
+        await this._middleware?.afterResponse?.({ route });
+        return;
+      } catch (err) {
+        lastErr = err instanceof Error ? err : new Error(String(err));
+      }
+    }
+    throw lastErr;
+  }
+};
+export {
+  GatewayAdapter
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  eventNow,\n  type ChatParams,\n  type HaloEvent,\n  type ModelAdapter,\n  type ModelCapabilities,\n  type PricingInfo,\n  type ToolCall,\n  type TurnChunk,\n  type Usage,\n} from \"@halo-sdk/core\";\n\n/** A named provider in the gateway's routing pool. */\nexport interface GatewayRoute {\n  /** Human-readable provider name (for route events + diagnostics). */\n  name: string;\n  adapter: ModelAdapter;\n}\n\n/**\n * Reserved extension seam.\n *\n * The gateway is the designated integration point for a forthcoming\n * maintainer-defined capability (TBD). Implementations receive every request\n * and response and **must** emit their activity onto the S5 event stream via\n * the gateway's route/observer callback rather than logging out of band. This\n * interface and its call sites will change when that capability lands.\n */\nexport interface GatewayMiddleware {\n  beforeRequest?(ctx: { route: GatewayRoute; params: ChatParams }): void | Promise<void>;\n  afterResponse?(ctx: { route: GatewayRoute; usage?: Usage }): void | Promise<void>;\n}\n\nexport interface GatewayOptions {\n  /** Providers in priority order; the first is the default route. */\n  routes: GatewayRoute[];\n  /**\n   * Sink for `route` {@link HaloEvent}s. Wire it to an agent's observer, e.g.\n   * `new GatewayAdapter({ routes, onEvent: (e) => bus.emit(e) })`.\n   */\n  onEvent?: (event: Extract<HaloEvent, { type: \"route\" }>) => void;\n  /** Reserved extension seam (see {@link GatewayMiddleware}). */\n  middleware?: GatewayMiddleware;\n}\n\n/**\n * A cache-aware {@link ModelAdapter} that fronts a pool of providers.\n *\n * - **Sticky routing** — requests stay on the last provider that succeeded, so\n *   that provider's prefix cache stays warm; the gateway only moves on failure.\n * - **Fallback chains** — on error it tries the remaining providers in order;\n *   a fallback never silently discards a warm cache because routing is sticky,\n *   not round-robin.\n *\n * Composes with the `@halo-sdk/otel` decorators (wrap each route's adapter) and\n * emits a `route` event (onto the S5 spine via `onEvent`) for every decision.\n */\nexport class GatewayAdapter implements ModelAdapter {\n  private readonly _routes: GatewayRoute[];\n  private readonly _onEvent: ((event: Extract<HaloEvent, { type: \"route\" }>) => void) | undefined;\n  private readonly _middleware: GatewayMiddleware | undefined;\n  private _preferred = 0;\n\n  constructor(opts: GatewayOptions) {\n    if (!opts.routes.length) throw new Error(\"GatewayAdapter requires at least one route.\");\n    this._routes = opts.routes;\n    this._onEvent = opts.onEvent;\n    this._middleware = opts.middleware;\n  }\n\n  // Surface the currently-preferred provider's capabilities/pricing/identity.\n  private get _primary(): ModelAdapter {\n    return this._routes[this._preferred]!.adapter;\n  }\n  get modelId(): string {\n    return this._primary.modelId;\n  }\n  get contextWindow(): number {\n    return this._primary.contextWindow;\n  }\n  get capabilities(): ModelCapabilities {\n    return this._primary.capabilities;\n  }\n  get pricing(): PricingInfo | undefined {\n    return this._primary.pricing;\n  }\n\n  /** Provider order the gateway will try this call: preferred first, then the rest. */\n  private _order(): number[] {\n    const order = [this._preferred];\n    for (let i = 0; i < this._routes.length; i++) if (i !== this._preferred) order.push(i);\n    return order;\n  }\n\n  private _emitRoute(route: GatewayRoute, reason: string): void {\n    this._onEvent?.({\n      type: \"route\",\n      ts: eventNow(),\n      provider: route.name,\n      model: route.adapter.modelId,\n      reason,\n    });\n  }\n\n  async chat(params: ChatParams): Promise<{\n    content: string;\n    toolCalls: ToolCall[];\n    usage: Usage;\n    reasoning?: { text: string; signature?: string };\n  }> {\n    let lastErr: Error = new Error(\"no routes\");\n    const order = this._order();\n    for (let oi = 0; oi < order.length; oi++) {\n      const idx = order[oi]!;\n      const route = this._routes[idx]!;\n      try {\n        await this._middleware?.beforeRequest?.({ route, params });\n        this._emitRoute(route, oi === 0 ? \"sticky\" : `fallback:${lastErr.message}`);\n        const result = await route.adapter.chat(params);\n        await this._middleware?.afterResponse?.({ route, usage: result.usage });\n        this._preferred = idx; // stay sticky on the provider that worked\n        return result;\n      } catch (err: unknown) {\n        lastErr = err instanceof Error ? err : new Error(String(err));\n      }\n    }\n    throw lastErr;\n  }\n\n  async *stream(params: ChatParams): AsyncGenerator<TurnChunk> {\n    const order = this._order();\n    let lastErr: Error = new Error(\"no routes\");\n    for (let oi = 0; oi < order.length; oi++) {\n      const idx = order[oi]!;\n      const route = this._routes[idx]!;\n      try {\n        await this._middleware?.beforeRequest?.({ route, params });\n        // Open the stream eagerly so connection errors are caught here for fallback.\n        const gen = route.adapter.stream(params);\n        const first = await gen.next();\n        this._emitRoute(route, oi === 0 ? \"sticky\" : `fallback:${lastErr.message}`);\n        this._preferred = idx;\n        if (!first.done) yield first.value;\n        yield* gen;\n        await this._middleware?.afterResponse?.({ route });\n        return;\n      } catch (err: unknown) {\n        lastErr = err instanceof Error ? err : new Error(String(err));\n      }\n    }\n    throw lastErr;\n  }\n}\n"],"mappings":";AAAA;AAAA,EACE;AAAA,OASK;AA+CA,IAAM,iBAAN,MAA6C;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACT,aAAa;AAAA,EAErB,YAAY,MAAsB;AAChC,QAAI,CAAC,KAAK,OAAO,OAAQ,OAAM,IAAI,MAAM,6CAA6C;AACtF,SAAK,UAAU,KAAK;AACpB,SAAK,WAAW,KAAK;AACrB,SAAK,cAAc,KAAK;AAAA,EAC1B;AAAA;AAAA,EAGA,IAAY,WAAyB;AACnC,WAAO,KAAK,QAAQ,KAAK,UAAU,EAAG;AAAA,EACxC;AAAA,EACA,IAAI,UAAkB;AACpB,WAAO,KAAK,SAAS;AAAA,EACvB;AAAA,EACA,IAAI,gBAAwB;AAC1B,WAAO,KAAK,SAAS;AAAA,EACvB;AAAA,EACA,IAAI,eAAkC;AACpC,WAAO,KAAK,SAAS;AAAA,EACvB;AAAA,EACA,IAAI,UAAmC;AACrC,WAAO,KAAK,SAAS;AAAA,EACvB;AAAA;AAAA,EAGQ,SAAmB;AACzB,UAAM,QAAQ,CAAC,KAAK,UAAU;AAC9B,aAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,QAAQ,IAAK,KAAI,MAAM,KAAK,WAAY,OAAM,KAAK,CAAC;AACrF,WAAO;AAAA,EACT;AAAA,EAEQ,WAAW,OAAqB,QAAsB;AAC5D,SAAK,WAAW;AAAA,MACd,MAAM;AAAA,MACN,IAAI,SAAS;AAAA,MACb,UAAU,MAAM;AAAA,MAChB,OAAO,MAAM,QAAQ;AAAA,MACrB;AAAA,IACF,CAAC;AAAA,EACH;AAAA,EAEA,MAAM,KAAK,QAKR;AACD,QAAI,UAAiB,IAAI,MAAM,WAAW;AAC1C,UAAM,QAAQ,KAAK,OAAO;AAC1B,aAAS,KAAK,GAAG,KAAK,MAAM,QAAQ,MAAM;AACxC,YAAM,MAAM,MAAM,EAAE;AACpB,YAAM,QAAQ,KAAK,QAAQ,GAAG;AAC9B,UAAI;AACF,cAAM,KAAK,aAAa,gBAAgB,EAAE,OAAO,OAAO,CAAC;AACzD,aAAK,WAAW,OAAO,OAAO,IAAI,WAAW,YAAY,QAAQ,OAAO,EAAE;AAC1E,cAAM,SAAS,MAAM,MAAM,QAAQ,KAAK,MAAM;AAC9C,cAAM,KAAK,aAAa,gBAAgB,EAAE,OAAO,OAAO,OAAO,MAAM,CAAC;AACtE,aAAK,aAAa;AAClB,eAAO;AAAA,MACT,SAAS,KAAc;AACrB,kBAAU,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAAA,MAC9D;AAAA,IACF;AACA,UAAM;AAAA,EACR;AAAA,EAEA,OAAO,OAAO,QAA+C;AAC3D,UAAM,QAAQ,KAAK,OAAO;AAC1B,QAAI,UAAiB,IAAI,MAAM,WAAW;AAC1C,aAAS,KAAK,GAAG,KAAK,MAAM,QAAQ,MAAM;AACxC,YAAM,MAAM,MAAM,EAAE;AACpB,YAAM,QAAQ,KAAK,QAAQ,GAAG;AAC9B,UAAI;AACF,cAAM,KAAK,aAAa,gBAAgB,EAAE,OAAO,OAAO,CAAC;AAEzD,cAAM,MAAM,MAAM,QAAQ,OAAO,MAAM;AACvC,cAAM,QAAQ,MAAM,IAAI,KAAK;AAC7B,aAAK,WAAW,OAAO,OAAO,IAAI,WAAW,YAAY,QAAQ,OAAO,EAAE;AAC1E,aAAK,aAAa;AAClB,YAAI,CAAC,MAAM,KAAM,OAAM,MAAM;AAC7B,eAAO;AACP,cAAM,KAAK,aAAa,gBAAgB,EAAE,MAAM,CAAC;AACjD;AAAA,MACF,SAAS,KAAc;AACrB,kBAAU,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAAA,MAC9D;AAAA,IACF;AACA,UAAM;AAAA,EACR;AACF;","names":[]}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@halo-sdk/gateway",
+  "version": "1.0.0",
+  "description": "Cache-aware AI gateway for Halo SDK — sticky routing + fallback chains that don't throw away a warm prefix cache",
+  "keywords": [
+    "ai",
+    "fallback",
+    "gateway",
+    "llm",
+    "prefix-cache",
+    "routing"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halo-sdk/halo-ai",
+    "directory": "packages/gateway"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0",
+    "@halo-sdk/core": "1.1.0"
+  },
+  "peerDependencies": {
+    "@halo-sdk/core": ">=1.1.0"
+  },
+  "scripts": {
+    "build": "tsc --build --emitDeclarationOnly && tsup",
+    "dev": "tsup --watch",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "publint": "publint",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}