@antseed/router-core 0.1.49 → 0.1.50

package/dist/cache-observations.d.ts

@@ -0,0 +1,11 @@
+import type { RouteCandidate, RoutingUsageObservation } from '@antseed/node';
+/** Per-conversation prompt-cache reuse observed from completed inference responses. */
+export declare class CacheObservations {
+    private readonly now;
+    private readonly conversations;
+    constructor(now?: () => number);
+    record(observation: RoutingUsageObservation): void;
+    /** Expected cached input tokens for one exact peer/provider/model in this conversation. */
+    expectedCachedInputTokens(conversationKey: string | null, candidate: Pick<RouteCandidate, 'peerId' | 'provider' | 'serviceId'>, promptTokens: number): number;
+}
+//# sourceMappingURL=cache-observations.d.ts.map

package/dist/cache-observations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-observations.d.ts","sourceRoot":"","sources":["../src/cache-observations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAK7E,uFAAuF;AACvF,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;gBAEpC,GAAG,GAAE,MAAM,MAAiB;IAEzD,MAAM,CAAC,WAAW,EAAE,uBAAuB,GAAG,IAAI;IAoBlD,2FAA2F;IAC3F,yBAAyB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;CAM9J"}

package/dist/cache-observations.js

@@ -0,0 +1,41 @@
+/** Per-conversation prompt-cache reuse observed from completed inference responses. */
+export class CacheObservations {
+    now;
+    conversations = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    record(observation) {
+        const { conversationKey, requestId, peerId, provider, serviceId, inputTokens, cachedInputTokens } = observation;
+        if (!conversationKey || !requestId || !Number.isSafeInteger(inputTokens) || inputTokens <= 0
+            || !Number.isSafeInteger(cachedInputTokens) || cachedInputTokens < 0 || cachedInputTokens > inputTokens)
+            return;
+        const conversation = this.conversations.get(conversationKey) ?? { offers: new Map(), requests: new Set() };
+        const requestKey = JSON.stringify([requestId, peerId, provider, serviceId]);
+        if (conversation.requests.has(requestKey))
+            return;
+        conversation.requests.add(requestKey);
+        if (conversation.requests.size > 512)
+            conversation.requests.delete(conversation.requests.values().next().value);
+        const key = JSON.stringify([peerId, provider, serviceId]);
+        const previous = conversation.offers.get(key);
+        const ratio = cachedInputTokens / inputTokens;
+        conversation.offers.delete(key);
+        conversation.offers.set(key, { ratio: previous ? previous.ratio * 0.5 + ratio * 0.5 : ratio, inputTokens, at: this.now() });
+        if (conversation.offers.size > 64)
+            conversation.offers.delete(conversation.offers.keys().next().value);
+        this.conversations.delete(conversationKey);
+        this.conversations.set(conversationKey, conversation);
+        if (this.conversations.size > 500)
+            this.conversations.delete(this.conversations.keys().next().value);
+    }
+    /** Expected cached input tokens for one exact peer/provider/model in this conversation. */
+    expectedCachedInputTokens(conversationKey, candidate, promptTokens) {
+        const conversation = conversationKey ? this.conversations.get(conversationKey) : undefined;
+        const observation = conversation?.offers.get(JSON.stringify([candidate.peerId, candidate.provider, candidate.serviceId]));
+        if (!observation || this.now() - observation.at > 3 * 60_000)
+            return 0;
+        return Math.max(0, Math.round(Math.min(observation.inputTokens * observation.ratio, promptTokens)));
+    }
+}
+//# sourceMappingURL=cache-observations.js.map

package/dist/cache-observations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-observations.js","sourceRoot":"","sources":["../src/cache-observations.ts"],"names":[],"mappings":"AAKA,uFAAuF;AACvF,MAAM,OAAO,iBAAiB;IAGC;IAFZ,aAAa,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEjE,YAA6B,MAAoB,IAAI,CAAC,GAAG;QAA5B,QAAG,GAAH,GAAG,CAAyB;IAAG,CAAC;IAE7D,MAAM,CAAC,WAAoC;QACzC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,GAAG,WAAW,CAAC;QAChH,IAAI,CAAC,eAAe,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC;eACvF,CAAC,MAAM,CAAC,aAAa,CAAC,iBAAiB,CAAC,IAAI,iBAAiB,GAAG,CAAC,IAAI,iBAAiB,GAAG,WAAW;YAAE,OAAO;QAClH,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;QAC3G,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;QAC5E,IAAI,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC;YAAE,OAAO;QAClD,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACtC,IAAI,YAAY,CAAC,QAAQ,CAAC,IAAI,GAAG,GAAG;YAAE,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,CAAC,CAAC;QACjH,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;QAC1D,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9C,MAAM,KAAK,GAAG,iBAAiB,GAAG,WAAW,CAAC;QAC9C,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChC,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,GAAG,GAAG,GAAG,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC5H,IAAI,YAAY,CAAC,MAAM,CAAC,IAAI,GAAG,EAAE;YAAE,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,CAAC,CAAC;QACxG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QAC3C,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,eAAe,EAAE,YAAY,CAAC,CAAC;QACtD,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,GAAG,GAAG;YAAE,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,CAAC,CAAC;IACxG,CAAC;IAED,2FAA2F;IAC3F,yBAAyB,CAAC,eAA8B,EAAE,SAAoE,EAAE,YAAoB;QAClJ,MAAM,YAAY,GAAG,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3F,MAAM,WAAW,GAAG,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC1H,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,CAAC,EAAE,GAAG,CAAC,GAAG,MAAM;YAAE,OAAO,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,WAAW,GAAG,WAAW,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IACtG,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { scoreCandidates, DEFAULT_WEIGHTS, type ScoringWeights, type ScoredCandidate, type TokenPricingUsdPerMillion, type PeerMetrics, } from './peer-scorer.js';
 export { PeerMetricsTracker, computeFailureCooldownMs, DEFAULT_MAX_FAILURES, DEFAULT_FAILURE_COOLDOWN_MS, MAX_COOLDOWN_DOUBLINGS, type PeerMetricsTrackerConfig, type FailureCooldownOptions, } from './peer-metrics.js';
 export { WELL_KNOWN_TOOL_HINTS, formatToolHints, type ToolHint, } from './tool-hints.js';
+export { ModelRoutingClient, routingProtocolOfTarget, type ModelRoutingClientApi } from './model-routing-client.js';
+export { candidatePricing, findRoutingClientAdapter, InvalidRouterOptionsError, irpCandidateId, irpSuggestAdapter, RouterCannotRankError, routingClientAdapter, validateRouterOptions, type RankCandidate, type RouterOptionSpec, type RoutingClientAdapter, } from './routing-adapters/index.js';
+export { CacheObservations } from './cache-observations.js';
+export { routerModelResolver } from './router-model-names.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,2BAA2B,EAC3B,sBAAsB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,KAAK,QAAQ,GACd,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,2BAA2B,EAC3B,sBAAsB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,KAAK,QAAQ,GACd,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,KAAK,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACnH,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -1,4 +1,8 @@
 export { scoreCandidates, DEFAULT_WEIGHTS, } from './peer-scorer.js';
 export { PeerMetricsTracker, computeFailureCooldownMs, DEFAULT_MAX_FAILURES, DEFAULT_FAILURE_COOLDOWN_MS, MAX_COOLDOWN_DOUBLINGS, } from './peer-metrics.js';
 export { WELL_KNOWN_TOOL_HINTS, formatToolHints, } from './tool-hints.js';
+export { ModelRoutingClient, routingProtocolOfTarget } from './model-routing-client.js';
+export { candidatePricing, findRoutingClientAdapter, InvalidRouterOptionsError, irpCandidateId, irpSuggestAdapter, RouterCannotRankError, routingClientAdapter, validateRouterOptions, } from './routing-adapters/index.js';
+export { CacheObservations } from './cache-observations.js';
+export { routerModelResolver } from './router-model-names.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,eAAe,GAKhB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,2BAA2B,EAC3B,sBAAsB,GAGvB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EACrB,eAAe,GAEhB,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,eAAe,GAKhB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,2BAA2B,EAC3B,sBAAsB,GAGvB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EACrB,eAAe,GAEhB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAA8B,MAAM,2BAA2B,CAAA;AACnH,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,GAItB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/model-routing-client.d.ts

@@ -0,0 +1,27 @@
+import { type PeerInfo, type RouteRecommendation, type RouterModelEntry, type RouterOptions, type RouteSelectionContext, type RoutingModelsContext, type RoutingProtocol, type RoutingServiceTarget, type RoutingUsageObservation, type SerializedHttpRequest } from '@antseed/node';
+import { CacheObservations } from './cache-observations.js';
+import { type RoutingClientAdapter } from './routing-adapters/types.js';
+/** The routing protocol a target service advertises on its peer. */
+export declare function routingProtocolOfTarget(peers: PeerInfo[], target: RoutingServiceTarget): RoutingProtocol | null;
+/**
+ * Buyer side of routing services, independent of any routing protocol:
+ * - `listModels`: the models the router can rank (free).
+ * - `selectRoute`: one paid ranking per user turn; the router orders the buyer's allowed candidates.
+ * - `recordUsage`: observed prompt-cache reuse, given to the router with later candidates.
+ * The router's advertised protocol picks the adapter that speaks its wire format
+ * (`routing-adapters/`). It never sends inference; the buyer proxy dispatches the result.
+ */
+export declare class ModelRoutingClient {
+    private readonly lastRoutes;
+    readonly observations: CacheObservations;
+    recordUsage(observation: RoutingUsageObservation): void;
+    /** The adapter for a target's routing protocol, e.g. to read the options it accepts. */
+    adapterFor(target: RoutingServiceTarget, peers: PeerInfo[]): RoutingClientAdapter;
+    /** Validate router options for a target before any ranking is bought; throws `InvalidRouterOptionsError`. */
+    validateOptions(target: RoutingServiceTarget, peers: PeerInfo[], options: RouterOptions | undefined): RouterOptions;
+    listModels(target: RoutingServiceTarget, peers: PeerInfo[], context: RoutingModelsContext): Promise<RouterModelEntry[]>;
+    selectRoute(request: SerializedHttpRequest, peers: PeerInfo[], context: RouteSelectionContext): Promise<RouteRecommendation[] | null>;
+}
+/** The `ModelRoutingClient` surface the buyer proxy calls; tests can supply a stand-in. */
+export type ModelRoutingClientApi = Pick<ModelRoutingClient, 'listModels' | 'selectRoute'> & Partial<Pick<ModelRoutingClient, 'recordUsage'>>;
+//# sourceMappingURL=model-routing-client.d.ts.map

package/dist/model-routing-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-routing-client.d.ts","sourceRoot":"","sources":["../src/model-routing-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC3B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAE3D,OAAO,EAAyB,KAAK,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAgC9F,oEAAoE;AACpE,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,oBAAoB,GAAG,eAAe,GAAG,IAAI,CAI/G;AAqBD;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiC;IAC5D,QAAQ,CAAC,YAAY,oBAA0B;IAE/C,WAAW,CAAC,WAAW,EAAE,uBAAuB,GAAG,IAAI;IAIvD,wFAAwF;IACxF,UAAU,CAAC,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,oBAAoB;IAIjF,6GAA6G;IAC7G,eAAe,CAAC,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,aAAa;IAI7G,UAAU,CAAC,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAKvH,WAAW,CAAC,OAAO,EAAE,qBAAqB,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,EAAE,GAAG,IAAI,CAAC;CAmC5I;AAED,2FAA2F;AAC3F,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,kBAAkB,EAAE,YAAY,GAAG,aAAa,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC,CAAA"}

package/dist/model-routing-client.js

@@ -0,0 +1,124 @@
+import { routingProtocolOf, routingWireProtocol, } from '@antseed/node';
+import { CacheObservations } from './cache-observations.js';
+import { routingClientAdapter } from './routing-adapters/index.js';
+import { validateRouterOptions } from './routing-adapters/types.js';
+const MAX_CACHED_CONVERSATIONS = 500;
+const decodeJson = (body) => JSON.parse(new TextDecoder().decode(body));
+const encodeJson = (value) => new TextEncoder().encode(JSON.stringify(value));
+function contentText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content.map(block => typeof block?.text === 'string' ? block.text : '').join('\n');
+}
+/**
+ * The latest user-written text in a Chat Completions, Messages or Responses body. User messages
+ * without text (e.g. Anthropic `tool_result`-only turns) are skipped, so a tool loop keeps
+ * resolving to the prompt that started it.
+ */
+function latestUserText(body) {
+    const messages = Array.isArray(body.messages) ? body.messages : Array.isArray(body.input) ? body.input : [];
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message?.role !== 'user')
+            continue;
+        const text = contentText(message.content);
+        if (text.trim())
+            return text;
+    }
+    return typeof body.input === 'string' ? body.input : '';
+}
+/** The routing protocol a target service advertises on its peer. */
+export function routingProtocolOfTarget(peers, target) {
+    const peer = peers.find(entry => entry.peerId === target.peerId);
+    const provider = peer?.metadata?.providers?.find(entry => entry.provider === target.provider && entry.services.includes(target.serviceId));
+    return routingProtocolOf(provider?.serviceApiProtocols?.[target.serviceId]);
+}
+/** The selected router peer, checked to advertise this exact routing service, and its protocol. */
+function findRouterPeer(peers, target) {
+    const peer = peers.find(entry => entry.peerId === target.peerId);
+    if (peer && !Array.isArray(peer.metadata?.providers)) {
+        throw new Error('Selected router metadata is not available yet. Wait for discovery or restart the router.');
+    }
+    const provider = peer?.metadata?.providers?.find(entry => entry.provider === target.provider && entry.services.includes(target.serviceId));
+    if (!peer || !provider)
+        throw new Error('Selected routing service is not advertised by the selected peer');
+    const protocol = routingProtocolOf(provider.serviceApiProtocols?.[target.serviceId]);
+    if (!protocol)
+        throw new Error('Selected service does not advertise a routing protocol');
+    // Protocols whose paths name no service need the router peer to offer exactly one service of that protocol.
+    if (routingWireProtocol(protocol).oneServicePerSeller) {
+        const sameProtocol = peer.metadata.providers.flatMap(entry => entry.services
+            .filter(service => routingProtocolOf(entry.serviceApiProtocols?.[service]) === protocol));
+        if (sameProtocol.length !== 1)
+            throw new Error(`Selected peer advertises more than one ${protocol} routing service`);
+    }
+    return { peer, protocol };
+}
+/**
+ * Buyer side of routing services, independent of any routing protocol:
+ * - `listModels`: the models the router can rank (free).
+ * - `selectRoute`: one paid ranking per user turn; the router orders the buyer's allowed candidates.
+ * - `recordUsage`: observed prompt-cache reuse, given to the router with later candidates.
+ * The router's advertised protocol picks the adapter that speaks its wire format
+ * (`routing-adapters/`). It never sends inference; the buyer proxy dispatches the result.
+ */
+export class ModelRoutingClient {
+    lastRoutes = new Map();
+    observations = new CacheObservations();
+    recordUsage(observation) {
+        this.observations.record(observation);
+    }
+    /** The adapter for a target's routing protocol, e.g. to read the options it accepts. */
+    adapterFor(target, peers) {
+        return routingClientAdapter(findRouterPeer(peers, target).protocol);
+    }
+    /** Validate router options for a target before any ranking is bought; throws `InvalidRouterOptionsError`. */
+    validateOptions(target, peers, options) {
+        return validateRouterOptions(this.adapterFor(target, peers).options, options);
+    }
+    async listModels(target, peers, context) {
+        const { peer, protocol } = findRouterPeer(peers, target);
+        return routingClientAdapter(protocol).listModels(peer, context);
+    }
+    async selectRoute(request, peers, context) {
+        context.signal.throwIfAborted();
+        const { peer: router, protocol } = findRouterPeer(peers, context.routingService);
+        const adapter = routingClientAdapter(protocol);
+        const options = validateRouterOptions(adapter.options, context.options);
+        const body = decodeJson(request.body);
+        const text = latestUserText(body);
+        if (!text.trim())
+            throw new Error('Routing requires user text in messages or Responses input');
+        if (!context.candidates.length)
+            throw new Error('No eligible candidates supported by this router');
+        // Tool-loop continuations repeat the same user turn: reuse its recommendation instead of paying
+        // again, even when the candidate set changed in between (a peer refresh reorders, adds or drops
+        // sellers). A new ranking is bought only when none of the saved picks is still usable.
+        const key = context.conversationKey;
+        const fingerprint = JSON.stringify([context.routingService, Object.entries(options).sort(([a], [b]) => a.localeCompare(b))]);
+        const cached = key ? this.lastRoutes.get(key) : undefined;
+        if (cached?.text === text && cached.fingerprint === fingerprint && context.acceptRecommendations(cached.routes)) {
+            return structuredClone(cached.routes);
+        }
+        if (key)
+            this.lastRoutes.delete(key);
+        // Rough prompt size (characters / 4), used only to cap expected cache reuse.
+        const estimatedTokens = Math.ceil(encodeJson(body.messages ?? body.input ?? '').length / 4);
+        const candidates = context.candidates.map(candidate => ({
+            ...candidate,
+            expectedCachedInputTokens: this.observations.expectedCachedInputTokens(context.conversationKey, candidate, estimatedTokens),
+        }));
+        const routes = await adapter.rank({ request, body, router, candidates, options, context });
+        if (!context.acceptRecommendations(routes))
+            throw new Error('Router returned no usable recommendation');
+        if (key) {
+            this.lastRoutes.set(key, { text, fingerprint, routes: structuredClone(routes) });
+            if (this.lastRoutes.size > MAX_CACHED_CONVERSATIONS)
+                this.lastRoutes.delete(this.lastRoutes.keys().next().value);
+        }
+        return routes;
+    }
+}
+//# sourceMappingURL=model-routing-client.js.map

package/dist/model-routing-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-routing-client.js","sourceRoot":"","sources":["../src/model-routing-client.ts"],"names":[],"mappings":"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"}

package/dist/router-model-names.d.ts

@@ -0,0 +1,11 @@
+import { type RouterModelEntry, type RouterPricing } from '@antseed/node';
+/**
+ * Translate seller service IDs into the model names a router lists in its model catalog.
+ * An exact name match wins; otherwise names are compared by canonical model key (the same
+ * matching the savings baselines use), and the first listed router model wins a tie.
+ * When the router lists `*`, unmatched service IDs pass through unchanged.
+ * With `pricing`, a candidate priced above the matched entry's `maxPricing` is dropped.
+ * Returns `undefined` when the router lists no matching model and no `*`, or the price is over the limit.
+ */
+export declare function routerModelResolver(entries: readonly RouterModelEntry[]): (serviceId: string, pricing?: RouterPricing) => string | undefined;
+//# sourceMappingURL=router-model-names.d.ts.map

package/dist/router-model-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-model-names.d.ts","sourceRoot":"","sources":["../src/router-model-names.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyC,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AAGhH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,MAAM,GAAG,SAAS,CAoB5I"}

package/dist/router-model-names.js

@@ -0,0 +1,34 @@
+import { ROUTER_ANY_MODEL, withinRouterPricing } from '@antseed/node';
+import { canonicalModelKey } from '@antseed/node/model-identity';
+/**
+ * Translate seller service IDs into the model names a router lists in its model catalog.
+ * An exact name match wins; otherwise names are compared by canonical model key (the same
+ * matching the savings baselines use), and the first listed router model wins a tie.
+ * When the router lists `*`, unmatched service IDs pass through unchanged.
+ * With `pricing`, a candidate priced above the matched entry's `maxPricing` is dropped.
+ * Returns `undefined` when the router lists no matching model and no `*`, or the price is over the limit.
+ */
+export function routerModelResolver(entries) {
+    const exact = new Map();
+    const byKey = new Map();
+    let anyModel;
+    for (const entry of entries) {
+        if (entry.id === ROUTER_ANY_MODEL) {
+            anyModel = entry;
+            continue;
+        }
+        exact.set(entry.id, entry);
+        const key = canonicalModelKey(entry.id);
+        if (key && !byKey.has(key))
+            byKey.set(key, entry);
+    }
+    return (serviceId, pricing) => {
+        const key = canonicalModelKey(serviceId);
+        const named = exact.get(serviceId) ?? (key ? byKey.get(key) : undefined);
+        const entry = named ?? anyModel;
+        if (!entry || (pricing && !withinRouterPricing(pricing, entry.maxPricing)))
+            return undefined;
+        return named ? named.id : serviceId;
+    };
+}
+//# sourceMappingURL=router-model-names.js.map

package/dist/router-model-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-model-names.js","sourceRoot":"","sources":["../src/router-model-names.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAA6C,MAAM,eAAe,CAAA;AAChH,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAEhE;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAoC;IACtE,MAAM,KAAK,GAAG,IAAI,GAAG,EAA4B,CAAA;IACjD,MAAM,KAAK,GAAG,IAAI,GAAG,EAA4B,CAAA;IACjD,IAAI,QAAsC,CAAA;IAC1C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,EAAE,KAAK,gBAAgB,EAAE,CAAC;YAClC,QAAQ,GAAG,KAAK,CAAA;YAChB,SAAQ;QACV,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAA;QAC1B,MAAM,GAAG,GAAG,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QACvC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IACnD,CAAC;IACD,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE;QAC5B,MAAM,GAAG,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAA;QACxC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QACxE,MAAM,KAAK,GAAG,KAAK,IAAI,QAAQ,CAAA;QAC/B,IAAI,CAAC,KAAK,IAAI,CAAC,OAAO,IAAI,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;YAAE,OAAO,SAAS,CAAA;QAC5F,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;IACrC,CAAC,CAAA;AACH,CAAC"}

package/dist/routing-adapters/index.d.ts

@@ -0,0 +1,8 @@
+import { type RoutingProtocol } from '@antseed/node';
+import type { RoutingClientAdapter } from './types.js';
+export declare function routingClientAdapter(protocol: RoutingProtocol): RoutingClientAdapter;
+/** The adapter for a protocol string, or null when it is not a routing protocol this buyer speaks. */
+export declare function findRoutingClientAdapter(protocol: string | null | undefined): RoutingClientAdapter | null;
+export { irpSuggestAdapter, irpCandidateId } from './irp.js';
+export { candidatePricing, InvalidRouterOptionsError, RouterCannotRankError, validateRouterOptions, type RankCandidate, type RouterOptionSpec, type RoutingClientAdapter, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/routing-adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routing-adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAEvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAOtD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,oBAAoB,CAEpF;AAED,sGAAsG;AACtG,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,oBAAoB,GAAG,IAAI,CAEzG;AAED,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC5D,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,YAAY,CAAA"}

package/dist/routing-adapters/index.js

@@ -0,0 +1,16 @@
+import { isRoutingProtocol } from '@antseed/node';
+import { irpSuggestAdapter } from './irp.js';
+/** One buyer adapter per routing protocol. None is preferred: the router's advertised protocol picks it. */
+const ROUTING_CLIENT_ADAPTERS = {
+    'irp-suggest': irpSuggestAdapter,
+};
+export function routingClientAdapter(protocol) {
+    return ROUTING_CLIENT_ADAPTERS[protocol];
+}
+/** The adapter for a protocol string, or null when it is not a routing protocol this buyer speaks. */
+export function findRoutingClientAdapter(protocol) {
+    return isRoutingProtocol(protocol) ? ROUTING_CLIENT_ADAPTERS[protocol] : null;
+}
+export { irpSuggestAdapter, irpCandidateId } from './irp.js';
+export { candidatePricing, InvalidRouterOptionsError, RouterCannotRankError, validateRouterOptions, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/routing-adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/routing-adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAwB,MAAM,eAAe,CAAA;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAG5C,4GAA4G;AAC5G,MAAM,uBAAuB,GAAkD;IAC7E,aAAa,EAAE,iBAAiB;CACjC,CAAA;AAED,MAAM,UAAU,oBAAoB,CAAC,QAAyB;IAC5D,OAAO,uBAAuB,CAAC,QAAQ,CAAC,CAAA;AAC1C,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,wBAAwB,CAAC,QAAmC;IAC1E,OAAO,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,uBAAuB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAC/E,CAAC;AAED,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC5D,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,GAItB,MAAM,YAAY,CAAA"}

package/dist/routing-adapters/irp.d.ts

@@ -0,0 +1,16 @@
+import { type RouteCandidate } from '@antseed/node';
+import { type RoutingClientAdapter } from './types.js';
+/**
+ * IRP candidate `id`: `provider:model@peer`, readable in buyer and router logs. IDs longer than
+ * 128 characters become a SHA-256 of the same string. The buyer always maps IDs back through the
+ * candidates it sent and never parses them.
+ */
+export declare function irpCandidateId(candidate: Pick<RouteCandidate, 'peerId' | 'provider' | 'serviceId'>): string;
+/**
+ * `irp-suggest`: Inference Routing Protocol suggest-only mode.
+ * - catalog: free `GET /v1/routing/models`; `*` means any model, with optional `max_pricing`.
+ * - rank: paid `POST /v1/routing/rank`; the router orders the buyer's allowed candidates.
+ * - options: `cost_quality_tradeoff`, 0 (best quality) to 10 (cheapest), router default 5.
+ */
+export declare const irpSuggestAdapter: RoutingClientAdapter;
+//# sourceMappingURL=irp.d.ts.map

package/dist/routing-adapters/irp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"irp.d.ts","sourceRoot":"","sources":["../../src/routing-adapters/irp.ts"],"names":[],"mappings":"AACA,OAAO,EAkBL,KAAK,cAAc,EAKpB,MAAM,eAAe,CAAA;AACtB,OAAO,EAA2C,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAK/F;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC,GAAG,MAAM,CAG3G;AA8CD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,oBAuD/B,CAAA"}

package/dist/routing-adapters/irp.js

@@ -0,0 +1,122 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { IRP_ANY_MODEL, IRP_DEFAULT_COST_QUALITY_TRADEOFF, IRP_MAX_CANDIDATE_ID_LENGTH, IRP_MODELS_PATH, IRP_RANK_PATH, IRP_SUGGEST_PROTOCOL, ROUTER_ANY_MODEL, detectRequestServiceApiProtocol, parseIrpModelEntries, parseIrpProblem, renderRequestBodyAsOpenAIChat, validateIrpRankRequest, validateIrpRankResponse, } from '@antseed/node';
+import { candidatePricing, RouterCannotRankError } from './types.js';
+const decodeJson = (body) => JSON.parse(new TextDecoder().decode(body));
+const encodeJson = (value) => new TextEncoder().encode(JSON.stringify(value));
+/**
+ * IRP candidate `id`: `provider:model@peer`, readable in buyer and router logs. IDs longer than
+ * 128 characters become a SHA-256 of the same string. The buyer always maps IDs back through the
+ * candidates it sent and never parses them.
+ */
+export function irpCandidateId(candidate) {
+    const id = `${candidate.provider}:${candidate.serviceId}@${candidate.peerId}`;
+    return id.length <= IRP_MAX_CANDIDATE_ID_LENGTH ? id : `sha256:${createHash('sha256').update(id).digest('hex')}`;
+}
+function toIrpPricing(pricing) {
+    return { input: pricing.inputUsdPerMillion, cache_read: pricing.cachedInputUsdPerMillion, output: pricing.outputUsdPerMillion };
+}
+function fromIrpPricing(pricing) {
+    return {
+        ...(pricing.input !== undefined ? { inputUsdPerMillion: pricing.input } : {}),
+        ...(pricing.cache_read !== undefined ? { cachedInputUsdPerMillion: pricing.cache_read } : {}),
+        ...(pricing.output !== undefined ? { outputUsdPerMillion: pricing.output } : {}),
+    };
+}
+/**
+ * The request being routed as an OpenAI Chat Completions body (IRP `request`). Anthropic Messages
+ * and Responses bodies run through the same adapters used for dispatch. `model` and `stream` are
+ * dropped: routers ignore them and never forward the request.
+ */
+function irpInferenceRequest(request, body) {
+    const protocol = detectRequestServiceApiProtocol(request);
+    const chat = protocol ? renderRequestBodyAsOpenAIChat(protocol, body) : null;
+    if (!chat)
+        throw new Error('Routing supports Chat Completions, Anthropic Messages and Responses requests');
+    delete chat.model;
+    delete chat.stream;
+    delete chat.stream_options;
+    if (!Array.isArray(chat.messages) || chat.messages.length === 0)
+        throw new Error('Routing requires at least one message');
+    return chat;
+}
+/** Error text for a non-2xx router response, using IRP problem details when present. */
+function routerFailure(action, statusCode, body) {
+    let problem = null;
+    try {
+        problem = parseIrpProblem(decodeJson(body));
+    }
+    catch { /* not JSON */ }
+    const detail = problem?.detail ?? problem?.title;
+    const suffix = detail ? `: ${detail}` : '';
+    switch (statusCode) {
+        case 400: return new Error(`Router rejected the ${action} request${suffix}`);
+        case 402: return new Error('Routing payment could not be completed. The channel may have unpaid or disputed work. Select a model or another router.');
+        // IRP 422: no candidate could be scored; the buyer's model list may be stale.
+        case 422: return new RouterCannotRankError(`Router cannot rank any allowed candidate. Update the allowed models or choose another router${suffix}`);
+        case 503: return new Error(`Router is temporarily unavailable${suffix}`);
+        default: return new Error(`Routing ${action} failed (${statusCode})${suffix}`);
+    }
+}
+/**
+ * `irp-suggest`: Inference Routing Protocol suggest-only mode.
+ * - catalog: free `GET /v1/routing/models`; `*` means any model, with optional `max_pricing`.
+ * - rank: paid `POST /v1/routing/rank`; the router orders the buyer's allowed candidates.
+ * - options: `cost_quality_tradeoff`, 0 (best quality) to 10 (cheapest), router default 5.
+ */
+export const irpSuggestAdapter = {
+    protocol: IRP_SUGGEST_PROTOCOL,
+    options: [{
+            key: 'cost_quality_tradeoff',
+            type: 'integer',
+            label: 'Cost vs. quality',
+            description: '0 picks the best quality regardless of price; 10 picks the cheapest acceptable model.',
+            minimum: 0,
+            maximum: 10,
+            default: IRP_DEFAULT_COST_QUALITY_TRADEOFF,
+        }],
+    async listModels(router, context) {
+        const response = await context.sendRequest(router, {
+            requestId: randomUUID(), method: 'GET', path: IRP_MODELS_PATH,
+            headers: { accept: 'application/json' },
+            body: new Uint8Array(),
+        });
+        context.signal.throwIfAborted();
+        if (response.statusCode < 200 || response.statusCode >= 300)
+            throw routerFailure('models', response.statusCode, response.body);
+        return parseIrpModelEntries(decodeJson(response.body)).map((entry) => ({
+            id: entry.id === IRP_ANY_MODEL ? ROUTER_ANY_MODEL : entry.id,
+            ...(entry.max_pricing ? { maxPricing: fromIrpPricing(entry.max_pricing) } : {}),
+        }));
+    },
+    async rank({ request, body, router, candidates, options, context }) {
+        const sent = candidates.map((candidate) => ({
+            id: irpCandidateId(candidate),
+            model: candidate.routerModel ?? candidate.serviceId,
+            pricing: toIrpPricing(candidatePricing(candidate)),
+            // Absent means 0, so only send what was observed.
+            ...(candidate.expectedCachedInputTokens > 0 ? { expected_usage: { cache_read_tokens: candidate.expectedCachedInputTokens } } : {}),
+        }));
+        const rankRequest = {
+            request: irpInferenceRequest(request, body),
+            routing: {
+                ...(typeof options.cost_quality_tradeoff === 'number' ? { cost_quality_tradeoff: options.cost_quality_tradeoff } : {}),
+                candidates: sent,
+            },
+        };
+        validateIrpRankRequest(rankRequest);
+        const response = await context.sendRequest(router, {
+            requestId: randomUUID(), method: 'POST', path: IRP_RANK_PATH,
+            headers: { 'content-type': 'application/json' },
+            body: encodeJson(rankRequest),
+        }, { signal: context.signal });
+        context.signal.throwIfAborted();
+        if (response.statusCode < 200 || response.statusCode >= 300)
+            throw routerFailure('rank', response.statusCode, response.body);
+        const byId = new Map(sent.map((candidate, index) => [candidate.id, candidates[index]]));
+        return validateIrpRankResponse(decodeJson(response.body), sent).map((entry) => {
+            const { serviceId, peerId, provider } = byId.get(entry.candidate_id);
+            return { serviceId, peerId, provider, ...(entry.reasoning_effort ? { reasoningEffort: entry.reasoning_effort } : {}) };
+        });
+    },
+};
+//# sourceMappingURL=irp.js.map

package/dist/routing-adapters/irp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"irp.js","sourceRoot":"","sources":["../../src/routing-adapters/irp.ts"],"names":[],"mappings":"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"}

package/dist/routing-adapters/types.d.ts

@@ -0,0 +1,64 @@
+import type { PeerInfo, RouteCandidate, RouteRecommendation, RouterModelEntry, RouterOptions, RouterPricing, RoutingModelsContext, RoutingProtocol, RouteSelectionContext, SerializedHttpRequest } from '@antseed/node';
+/**
+ * One setting a router accepts with each ranking, described so a host (CLI, desktop) can
+ * validate it and render a control for it without knowing the routing protocol.
+ */
+export type RouterOptionSpec = {
+    key: string;
+    label: string;
+    description?: string;
+} & ({
+    type: 'integer' | 'number';
+    minimum?: number;
+    maximum?: number;
+    default?: number;
+} | {
+    type: 'boolean';
+    default?: boolean;
+} | {
+    type: 'string';
+    values?: readonly string[];
+    default?: string;
+});
+/** A candidate the buyer allows, with the prompt-cache reuse it observed for it. */
+export type RankCandidate = RouteCandidate & {
+    expectedCachedInputTokens: number;
+};
+/**
+ * Buyer side of one routing protocol. The protocol-neutral `ModelRoutingClient` picks the
+ * adapter by the protocol the router advertises; adding a routing API means adding an adapter
+ * here, its wire binding in `@antseed/protocol/routing`, and a provider plugin for sellers.
+ */
+export interface RoutingClientAdapter {
+    readonly protocol: RoutingProtocol;
+    /** Settings this protocol accepts with each ranking. Unknown keys are rejected. */
+    readonly options: readonly RouterOptionSpec[];
+    /** The models the router can rank: a free control-plane request. */
+    listModels(router: PeerInfo, context: RoutingModelsContext): Promise<RouterModelEntry[]>;
+    /**
+     * The paid ranking. Returns allowed candidates in the router's order, each at most once;
+     * a router can never name a destination the buyer did not send.
+     */
+    rank(args: {
+        request: SerializedHttpRequest;
+        /** `request.body`, decoded. */
+        body: Record<string, unknown>;
+        router: PeerInfo;
+        candidates: readonly RankCandidate[];
+        options: RouterOptions;
+        context: RouteSelectionContext;
+    }): Promise<RouteRecommendation[]>;
+}
+/** The router says none of the candidates can be ranked; the host may refresh the model list and retry once. */
+export declare class RouterCannotRankError extends Error {
+    constructor(message: string);
+}
+/** Router settings that the router's protocol does not accept; nothing was paid. */
+export declare class InvalidRouterOptionsError extends Error {
+    constructor(message: string);
+}
+/** Check `options` against a protocol's option specs; throws `InvalidRouterOptionsError`. */
+export declare function validateRouterOptions(specs: readonly RouterOptionSpec[], options: RouterOptions | undefined): RouterOptions;
+/** Candidate pricing for a router; sellers without a cached-input price bill cache reads at the input price. */
+export declare function candidatePricing(candidate: Pick<RouteCandidate, 'inputUsdPerMillion' | 'outputUsdPerMillion' | 'cachedInputUsdPerMillion'>): RouterPricing;
+//# sourceMappingURL=types.d.ts.map

package/dist/routing-adapters/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing-adapters/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,oBAAoB,EACpB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,eAAe,CAAA;AAEtB;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,CACA;IAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACpF;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CACnE,CAAA;AAED,oFAAoF;AACpF,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG;IAAE,yBAAyB,EAAE,MAAM,CAAA;CAAE,CAAA;AAElF;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;IAClC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAC7C,oEAAoE;IACpE,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAA;IACxF;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE;QACT,OAAO,EAAE,qBAAqB,CAAA;QAC9B,+BAA+B;QAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC7B,MAAM,EAAE,QAAQ,CAAA;QAChB,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;QACpC,OAAO,EAAE,aAAa,CAAA;QACtB,OAAO,EAAE,qBAAqB,CAAA;KAC/B,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAA;CACnC;AAED,gHAAgH;AAChH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,oFAAoF;AACpF,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED,6FAA6F;AAC7F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,EAAE,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,aAAa,CAwB3H;AAED,gHAAgH;AAChH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE,oBAAoB,GAAG,qBAAqB,GAAG,0BAA0B,CAAC,GAAG,aAAa,CAM1J"}

package/dist/routing-adapters/types.js

@@ -0,0 +1,54 @@
+/** The router says none of the candidates can be ranked; the host may refresh the model list and retry once. */
+export class RouterCannotRankError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RouterCannotRankError';
+    }
+}
+/** Router settings that the router's protocol does not accept; nothing was paid. */
+export class InvalidRouterOptionsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidRouterOptionsError';
+    }
+}
+/** Check `options` against a protocol's option specs; throws `InvalidRouterOptionsError`. */
+export function validateRouterOptions(specs, options) {
+    if (options === undefined)
+        return {};
+    const byKey = new Map(specs.map(spec => [spec.key, spec]));
+    const unknown = Object.keys(options).filter(key => !byKey.has(key));
+    if (unknown.length) {
+        const supported = specs.map(spec => spec.key).join(', ') || 'none';
+        throw new InvalidRouterOptionsError(`Unknown router option(s): ${unknown.join(', ')}. Supported: ${supported}.`);
+    }
+    for (const [key, value] of Object.entries(options)) {
+        const spec = byKey.get(key);
+        const fail = (expected) => { throw new InvalidRouterOptionsError(`Router option ${key} must be ${expected}.`); };
+        if (spec.type === 'boolean') {
+            if (typeof value !== 'boolean')
+                fail('true or false');
+        }
+        else if (spec.type === 'string') {
+            if (typeof value !== 'string' || (spec.values && !spec.values.includes(value)))
+                fail(spec.values ? `one of ${spec.values.join(', ')}` : 'a string');
+        }
+        else {
+            const range = spec.minimum !== undefined && spec.maximum !== undefined ? ` from ${spec.minimum} to ${spec.maximum}` : '';
+            if (typeof value !== 'number' || !Number.isFinite(value) || (spec.type === 'integer' && !Number.isInteger(value))
+                || (spec.minimum !== undefined && value < spec.minimum) || (spec.maximum !== undefined && value > spec.maximum)) {
+                fail(`${spec.type === 'integer' ? 'an integer' : 'a number'}${range}`);
+            }
+        }
+    }
+    return { ...options };
+}
+/** Candidate pricing for a router; sellers without a cached-input price bill cache reads at the input price. */
+export function candidatePricing(candidate) {
+    return {
+        inputUsdPerMillion: candidate.inputUsdPerMillion,
+        cachedInputUsdPerMillion: candidate.cachedInputUsdPerMillion ?? candidate.inputUsdPerMillion,
+        outputUsdPerMillion: candidate.outputUsdPerMillion,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/routing-adapters/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/routing-adapters/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antseed/router-core",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "Shared router infrastructure for Antseed plugins",
   "type": "module",
   "files": [
@@ -14,7 +14,7 @@
   "devDependencies": {
     "typescript": "^5.5.0",
     "vitest": "^2.0.0",
-    "@antseed/node": "0.2.142"
+    "@antseed/node": "0.2.143"
   },
   "scripts": {
     "prebuild": "node ../../scripts/remove-paths.mjs dist",