@zhivex-ai/gateway 0.9.2 → 1.0.0

package/README.md

@@ -33,14 +33,20 @@ const gateway = createGateway({
     openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
     ollama: createOllama()
   },
-  maxRetries: 1
+  maxRetries: 1,
+  attemptTimeoutMs: 15_000,
+  unknownCostPolicy: "reject"
 });
 
+const abortController = new AbortController();
+
 const result = await gateway.generate({
   primary: { provider: "openai", modelId: "gpt-4o-mini" },
   fallbacks: [{ provider: "ollama", modelId: "llama3.2" }],
   messages: [{ role: "user", content: "Summarize the benefits of fallback routing." }],
-  routingMode: "balanced"
+  routingMode: "balanced",
+  maxCostPer1kTokens: 0.01,
+  abortSignal: abortController.signal
 });
 
 console.log(result.text);
@@ -48,7 +54,17 @@ console.log(result.providerUsed);
 console.log(result.attempts);
 ```
 
-The gateway also supports `streamText()`, `generateObject()`, and `streamObject()` while preserving the selected target for the full request lifecycle, including tool loops. Object routes skip incompatible targets before making a provider call: native mode requires `structuredOutput`, prompted mode requires `jsonMode`, and auto mode accepts either capability.
+The gateway also supports `streamText()`, `generateObject()`, and `streamObject()` through one Core generation loop. A provider is fixed once its stream emits, while a later model step in the same tool loop can still fail over before emitting provider output. Object routes skip incompatible targets before making a provider call: native mode requires `structuredOutput`, prompted mode requires `jsonMode`, and auto mode accepts either capability.
+
+## Routing guarantees
+
+- Text, object, and agent operations retry eligible failures on the current target and then continue through the ordered fallback targets. Agent routing happens inside one `runAgent()` or `streamAgent()` execution, so a fallback does not restart the agent, duplicate its run, or replay completed tools.
+- Text and object streaming fallback is resolved before the first event is exposed. Agent streams may expose lifecycle events such as `agent-run-start` first, but provider fallback is resolved before the first provider event. Once a provider stream emits an event, an error from that stream is propagated without mixing in another provider's transcript.
+- `attemptTimeoutMs` and the per-provider `attemptTimeoutsMs` do more than reject the gateway promise: they abort a non-streaming provider call or a streaming call that has not produced its first event. A request-level `abortSignal` remains active for the full operation and stops pending retries, backoff, fallback routing, and active streams.
+- `ProviderHTTPError` is classified by its typed HTTP status. Status `408`, `429`, and `5xx` errors are retryable on the same target. Other `4xx` errors are not retried on that target, but an eligible fallback can still handle a provider- or model-specific rejection.
+- When `maxCostPer1kTokens` is set, a target without configured or catalog pricing is rejected by default. Set `unknownCostPolicy: "allow"` on `createGateway()` only when routing to models with unknown cost is acceptable.
+- Requests containing image attachments only route to models that declare `capabilities.vision: true`. The gateway never removes images to make a target appear compatible; if one target cannot accept the original request, it is skipped in favor of a compatible fallback.
+- `scoreTarget(context)` can replace the built-in name-based heuristic with application metrics. It must return a finite number; higher scores route first.
 
 For agent workloads, use `runAgent()` or `streamAgent()` to route by both regular model capabilities and agent-specific capabilities such as `supportTier`, `approvalRequests`, or `remoteMcp`.
 
@@ -69,6 +85,12 @@ console.log(agentResult.attempts);
 console.log(agentResult.routeDecision);
 ```
 
+Agent requests also forward the durable Core controls `runId`, `scope`, `idempotencyKey`, `parentRunId`, `policy`, and `toolApprovalPolicy`. Use a durable store plus `idempotencyKey` for effectful production runs.
+
+## Migration note
+
+`GatewayConfig.groundedAdapters` has been removed because it was not used by any gateway operation. Register provider adapters through `adapters`; `@zhivex-ai/gateway` does not currently expose a grounded-generation route.
+
 This package is the SDK-local routing layer. It is not the Zhivex-hosted Gateway API and it is not re-exported from `@zhivex-ai/sdk`.
 
 Repository and full documentation:

package/dist/compat.d.ts

@@ -1,7 +1,5 @@
 import type { ModelMessage } from "@zhivex-ai/core";
-import type { GatewayMessage, GatewayModelTarget, GatewayProviderId, GatewayResponse } from "./types.js";
-export declare const supportsVisionInput: (provider: GatewayProviderId, modelId: string) => boolean;
-export declare const stripImagesForUnsupportedModel: (messages: GatewayMessage[], provider: GatewayProviderId, modelId: string) => GatewayMessage[];
+import type { GatewayMessage, GatewayModelTarget, GatewayResponse } from "./types.js";
 export declare const gatewayMessagesToModelMessages: (messages: GatewayMessage[], systemPrompt?: string) => ModelMessage[];
 export declare const createRouteDecision: (mode: GatewayResponse["routeDecision"]["mode"], intent: GatewayResponse["routeDecision"]["intent"], orderedTargets: GatewayModelTarget[]) => GatewayResponse["routeDecision"];
 //# sourceMappingURL=compat.d.ts.map

package/dist/compat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compat.d.ts","sourceRoot":"","sources":["../src/compat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,mBAAmB,GAAI,UAAU,iBAAiB,EAAE,SAAS,MAAM,KAAG,OAYlF,CAAC;AAEF,eAAO,MAAM,8BAA8B,GACzC,UAAU,cAAc,EAAE,EAC1B,UAAU,iBAAiB,EAC3B,SAAS,MAAM,KACd,cAAc,EAMhB,CAAC;AAEF,eAAO,MAAM,8BAA8B,GACzC,UAAU,cAAc,EAAE,EAC1B,eAAe,MAAM,KACpB,YAAY,EAyBd,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,MAAM,eAAe,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,EAC9C,QAAQ,eAAe,CAAC,eAAe,CAAC,CAAC,QAAQ,CAAC,EAClD,gBAAgB,kBAAkB,EAAE,KACnC,eAAe,CAAC,eAAe,CAMhC,CAAC"}
+{"version":3,"file":"compat.d.ts","sourceRoot":"","sources":["../src/compat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,8BAA8B,GACzC,UAAU,cAAc,EAAE,EAC1B,eAAe,MAAM,KACpB,YAAY,EAyBd,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,MAAM,eAAe,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,EAC9C,QAAQ,eAAe,CAAC,eAAe,CAAC,CAAC,QAAQ,CAAC,EAClD,gBAAgB,kBAAkB,EAAE,KACnC,eAAe,CAAC,eAAe,CAMhC,CAAC"}

package/dist/compat.js

@@ -1,19 +1,3 @@
-export const supportsVisionInput = (provider, modelId) => {
-    const model = modelId.toLowerCase();
-    if (provider === "gemini") {
-        return !model.includes("embedding");
-    }
-    if (provider === "bedrock") {
-        return model.includes("nova") || model.includes("claude-3") || model.includes("claude-4");
-    }
-    return true;
-};
-export const stripImagesForUnsupportedModel = (messages, provider, modelId) => {
-    if (supportsVisionInput(provider, modelId)) {
-        return messages;
-    }
-    return messages.map((message) => (message.images?.length ? { ...message, images: [] } : message));
-};
 export const gatewayMessagesToModelMessages = (messages, systemPrompt) => {
     const mappedMessages = [];
     if (systemPrompt) {

package/dist/compat.js.map

@@ -1 +1 @@
-{"version":3,"file":"compat.js","sourceRoot":"","sources":["../src/compat.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAA2B,EAAE,OAAe,EAAW,EAAE;IAC3F,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAEpC,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC5F,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAC5C,QAA0B,EAC1B,QAA2B,EAC3B,OAAe,EACG,EAAE;IACpB,IAAI,mBAAmB,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;QAC3C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AACpG,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAC5C,QAA0B,EAC1B,YAAqB,EACL,EAAE;IAClB,MAAM,cAAc,GAAmB,EAAE,CAAC;IAE1C,IAAI,YAAY,EAAE,CAAC;QACjB,cAAc,CAAC,IAAI,CAAC;YAClB,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;SAC9C,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,cAAc,CAAC,IAAI,CAAC;YAClB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE;gBACL,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE;gBACvC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBACzC,IAAI,EAAE,OAAgB;oBACtB,KAAK,EAAE,KAAK,CAAC,OAAO;oBACpB,SAAS,EAAE,KAAK,CAAC,QAAQ;iBAC1B,CAAC,CAAC,IAAI,EAAE,CAAC;aACX;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,cAAc,CAAC;AACxB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,IAA8C,EAC9C,MAAkD,EAClD,cAAoC,EACF,EAAE,CAAC,CAAC;IACtC,IAAI;IACJ,MAAM;IACN,cAAc;IACd,UAAU,EAAE,WAAW,IAAI,EAAE;IAC7B,MAAM,EAAE,cAAc,IAAI,cAAc,MAAM,UAAU;CACzD,CAAC,CAAC"}
+{"version":3,"file":"compat.js","sourceRoot":"","sources":["../src/compat.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAC5C,QAA0B,EAC1B,YAAqB,EACL,EAAE;IAClB,MAAM,cAAc,GAAmB,EAAE,CAAC;IAE1C,IAAI,YAAY,EAAE,CAAC;QACjB,cAAc,CAAC,IAAI,CAAC;YAClB,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;SAC9C,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,cAAc,CAAC,IAAI,CAAC;YAClB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE;gBACL,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE;gBACvC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBACzC,IAAI,EAAE,OAAgB;oBACtB,KAAK,EAAE,KAAK,CAAC,OAAO;oBACpB,SAAS,EAAE,KAAK,CAAC,QAAQ;iBAC1B,CAAC,CAAC,IAAI,EAAE,CAAC;aACX;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,cAAc,CAAC;AACxB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,IAA8C,EAC9C,MAAkD,EAClD,cAAoC,EACF,EAAE,CAAC,CAAC;IACtC,IAAI;IACJ,MAAM;IACN,cAAc;IACd,UAAU,EAAE,WAAW,IAAI,EAAE;IAC7B,MAAM,EAAE,cAAc,IAAI,cAAc,MAAM,UAAU;CACzD,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import type { ZodTypeAny } from "zod";
 import { type GatewayAgentRequest, type GatewayAgentResponse, type GatewayAgentStreamResult, type GatewayConfig, type GatewayGenerateObjectRequest, type GatewayObjectResponse, type GatewayRequest, type GatewayResponse, type GatewayStreamObjectResult, type GatewayStreamTextResult } from "./types.js";
 export { GatewayError } from "./types.js";
-export type { GatewayAgentRequest, GatewayAgentResponse, GatewayAgentStreamResult, GatewayAttempt, GatewayAttemptReasonCode, GatewayConfig, GatewayGenerateObjectRequest, GatewayImageAttachment, GatewayMessage, GatewayModelTarget, GatewayObjectResponse, GatewayProviderId, GatewayRequest, GatewayResponse, GatewayRouteDecisionReasonCode, GatewayRoutingMode, GatewayStreamObjectResult, GatewayStreamTextResult, GatewayTaskIntent } from "./types.js";
+export type { GatewayAgentRequest, GatewayAgentResponse, GatewayAgentStreamResult, GatewayAttempt, GatewayAttemptReasonCode, GatewayConfig, GatewayGenerateObjectRequest, GatewayImageAttachment, GatewayMessage, GatewayModelTarget, GatewayObjectResponse, GatewayProviderId, GatewayRequest, GatewayResponse, GatewayRouteDecisionReasonCode, GatewayRoutingMode, GatewayRoutingScoreContext, GatewayStreamObjectResult, GatewayStreamTextResult, GatewayTaskIntent, GatewayUnknownCostPolicy } from "./types.js";
 export declare const createGateway: (config: GatewayConfig) => {
     generate(request: GatewayRequest): Promise<GatewayResponse>;
     streamText(request: GatewayRequest): GatewayStreamTextResult;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAGtC,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,KAAK,4BAA4B,EAEjC,KAAK,qBAAqB,EAE1B,KAAK,cAAc,EACnB,KAAK,eAAe,EAEpB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAE7B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,cAAc,EACd,wBAAwB,EACxB,aAAa,EACb,4BAA4B,EAC5B,sBAAsB,EACtB,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,8BAA8B,EAC9B,kBAAkB,EAClB,yBAAyB,EACzB,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAoVpB,eAAO,MAAM,aAAa,GAAI,QAAQ,aAAa;sBAsTvB,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;wBAK7C,cAAc,GAAG,uBAAuB;mBAyCvC,OAAO,SAAS,UAAU,WACpC,4BAA4B,CAAC,OAAO,CAAC,GAC7C,OAAO,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC;iBAyB7B,OAAO,SAAS,UAAU,WAAW,4BAA4B,CAAC,OAAO,CAAC,GAAG,yBAAyB,CAAC,OAAO,CAAC;sBA6DpG,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;yBAwCtD,mBAAmB,GAAG,wBAAwB;CA2EtE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAGtC,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAG7B,KAAK,aAAa,EAClB,KAAK,4BAA4B,EAEjC,KAAK,qBAAqB,EAE1B,KAAK,cAAc,EACnB,KAAK,eAAe,EAEpB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAE7B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,cAAc,EACd,wBAAwB,EACxB,aAAa,EACb,4BAA4B,EAC5B,sBAAsB,EACtB,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,8BAA8B,EAC9B,kBAAkB,EAClB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,iBAAiB,EACjB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAslBpB,eAAO,MAAM,aAAa,GAAI,QAAQ,aAAa;sBAuXvB,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;wBAa7C,cAAc,GAAG,uBAAuB;mBAuBvC,OAAO,SAAS,UAAU,WACpC,4BAA4B,CAAC,OAAO,CAAC,GAC7C,OAAO,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC;iBAyB7B,OAAO,SAAS,UAAU,WAC5B,4BAA4B,CAAC,OAAO,CAAC,GAC7C,yBAAyB,CAAC,OAAO,CAAC;sBAkCb,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;yBAkDtD,mBAAmB,GAAG,wBAAwB;CA0DtE,CAAC"}