@antseed/cli 0.1.21 → 0.1.23

package/dist/proxy/buyer-proxy.js

@@ -10,6 +10,31 @@ function log(...args) {
     if (DEBUG())
         console.log('[proxy]', ...args);
 }
+const CLAUDE_PROVIDER_PREFERENCE = ['claude-oauth', 'anthropic', 'claude-code'];
+function inferPreferredProvidersForRequest(requestProtocol, requestedModel) {
+    const model = requestedModel?.trim().toLowerCase() ?? '';
+    if (model.length === 0) {
+        return [];
+    }
+    const providers = [];
+    const pushProvider = (value) => {
+        const provider = value?.trim().toLowerCase();
+        if (!provider || provider.length === 0 || providers.includes(provider)) {
+            return;
+        }
+        providers.push(provider);
+    };
+    const slashIndex = model.indexOf('/');
+    if (slashIndex > 0) {
+        pushProvider(model.slice(0, slashIndex));
+    }
+    if (requestProtocol === 'anthropic-messages' || model.startsWith('claude-') || model.includes('claude')) {
+        for (const provider of CLAUDE_PROVIDER_PREFERENCE) {
+            pushProvider(provider);
+        }
+    }
+    return providers;
+}
 function getExplicitProviderOverride(request) {
     const provider = request.headers['x-antseed-provider']?.trim().toLowerCase();
     return provider && provider.length > 0 ? provider : null;
@@ -21,23 +46,49 @@ function getExplicitPeerIdOverride(request, sessionPinnedPeerId) {
         return header;
     return sessionPinnedPeerId?.toLowerCase() ?? null;
 }
+function getPreferredPeerIdHint(request) {
+    const header = request.headers['x-antseed-prefer-peer']?.trim().toLowerCase();
+    if (!header || header.length === 0) {
+        return null;
+    }
+    return header;
+}
 function getPeerProviderProtocols(peer, provider, requestedModel) {
     const fromMetadata = peer.providerModelApiProtocols?.[provider]?.models;
     if (fromMetadata) {
         if (requestedModel && fromMetadata[requestedModel]?.length) {
+            log(`Model match: peer ${peer.peerId.slice(0, 8)} provider=${provider} model="${requestedModel}" → [${fromMetadata[requestedModel].join(',')}]`);
             return Array.from(new Set(fromMetadata[requestedModel]));
         }
-        // If the peer advertises specific models and the requested model is not among them, return empty
-        // so this peer is filtered out in favour of peers that actually serve the model.
-        if (requestedModel && Object.keys(fromMetadata).length > 0) {
-            return [];
-        }
         const merged = Object.values(fromMetadata).flat();
         if (merged.length > 0) {
+            if (requestedModel) {
+                log(`Model hint miss: peer ${peer.peerId.slice(0, 8)} provider=${provider} model="${requestedModel}" not in metadata; falling back to provider protocol set [${Array.from(new Set(merged)).join(',')}]`);
+            }
             return Array.from(new Set(merged));
         }
     }
-    return inferProviderDefaultModelApiProtocols(provider);
+    const inferred = inferProviderDefaultModelApiProtocols(provider);
+    log(`No metadata: peer ${peer.peerId.slice(0, 8)} provider=${provider} → inferred [${inferred.join(',')}]`);
+    return inferred;
+}
+function isProviderModelExplicitlyUnsupported(peer, provider, requestedModel) {
+    if (!requestedModel) {
+        return false;
+    }
+    const modelMatrix = peer.providerModelApiProtocols?.[provider]?.models;
+    if (!modelMatrix) {
+        return false;
+    }
+    const advertisedModels = Object.keys(modelMatrix);
+    if (advertisedModels.length === 0) {
+        return false;
+    }
+    if (Object.prototype.hasOwnProperty.call(modelMatrix, requestedModel)) {
+        return false;
+    }
+    log(`Model strict-miss: peer ${peer.peerId.slice(0, 8)} provider=${provider} does not advertise model="${requestedModel}"`);
+    return true;
 }
 function resolvePeerRoutePlan(peer, requestProtocol, requestedModel, explicitProvider) {
     const providers = peer.providers
@@ -56,6 +107,9 @@ function resolvePeerRoutePlan(peer, requestProtocol, requestedModel, explicitPro
     }
     let transformedFallback = null;
     for (const provider of candidates) {
+        if (!explicitProvider && isProviderModelExplicitlyUnsupported(peer, provider, requestedModel)) {
+            continue;
+        }
         const supportedProtocols = getPeerProviderProtocols(peer, provider, requestedModel);
         const selection = selectTargetProtocolForRequest(requestProtocol, supportedProtocols);
         if (!selection) {
@@ -241,6 +295,162 @@ function extractRequestedModel(request) {
         return null;
     }
 }
+function decodeJsonBody(body) {
+    if (!body || body.length === 0) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(body));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function summarizeMessageShape(messagesRaw) {
+    if (!Array.isArray(messagesRaw)) {
+        return 'msgShape=none';
+    }
+    const roleCounts = new Map();
+    const contentKindCounts = new Map();
+    const blockTypeCounts = new Map();
+    let invalidMessages = 0;
+    let firstRole = 'none';
+    let lastRole = 'none';
+    const bump = (map, key) => {
+        map.set(key, (map.get(key) ?? 0) + 1);
+    };
+    for (const entry of messagesRaw) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            invalidMessages += 1;
+            continue;
+        }
+        const message = entry;
+        const role = typeof message.role === 'string' && message.role.trim().length > 0
+            ? message.role.trim().toLowerCase()
+            : 'invalid-role';
+        bump(roleCounts, role);
+        if (firstRole === 'none') {
+            firstRole = role;
+        }
+        lastRole = role;
+        const content = message.content;
+        if (typeof content === 'string') {
+            bump(contentKindCounts, 'string');
+            continue;
+        }
+        if (Array.isArray(content)) {
+            bump(contentKindCounts, 'array');
+            for (const block of content) {
+                if (!block || typeof block !== 'object' || Array.isArray(block)) {
+                    bump(blockTypeCounts, 'invalid');
+                    continue;
+                }
+                const blockType = typeof block.type === 'string'
+                    ? String(block.type).trim().toLowerCase()
+                    : 'missing-type';
+                bump(blockTypeCounts, blockType || 'missing-type');
+            }
+            continue;
+        }
+        if (content && typeof content === 'object') {
+            bump(contentKindCounts, 'object');
+            continue;
+        }
+        bump(contentKindCounts, 'other');
+    }
+    const joinMap = (map) => ([...map.entries()]
+        .sort((left, right) => left[0].localeCompare(right[0]))
+        .map(([key, value]) => `${key}:${String(value)}`)
+        .join(','));
+    const roleSummary = joinMap(roleCounts) || 'none';
+    const contentSummary = joinMap(contentKindCounts) || 'none';
+    const blockSummary = joinMap(blockTypeCounts) || 'none';
+    return [
+        `msgShape=roles{${roleSummary}}`,
+        `content{${contentSummary}}`,
+        `blocks{${blockSummary}}`,
+        `firstRole=${firstRole}`,
+        `lastRole=${lastRole}`,
+        `invalidMsgs=${String(invalidMessages)}`,
+    ].join(' ');
+}
+function summarizeRequestShape(request) {
+    const contentType = (request.headers['content-type'] ?? request.headers['Content-Type'] ?? '').toLowerCase();
+    const accept = (request.headers['accept'] ?? request.headers['Accept'] ?? '').toLowerCase();
+    const providerHeader = request.headers['x-antseed-provider'] ?? 'none';
+    const preferPeerHeader = request.headers['x-antseed-prefer-peer'] ?? 'none';
+    const model = extractRequestedModel(request) ?? 'none';
+    const wantsStreaming = requestWantsStreaming(request.headers, request.body);
+    const baseParts = [
+        `method=${request.method}`,
+        `path=${request.path}`,
+        `provider=${providerHeader}`,
+        `preferPeer=${preferPeerHeader}`,
+        `contentType=${contentType || 'none'}`,
+        `accept=${accept || 'none'}`,
+        `stream=${String(wantsStreaming)}`,
+        `model=${model}`,
+        `bodyBytes=${String(request.body.length)}`,
+    ];
+    const jsonBody = decodeJsonBody(request.body);
+    if (!jsonBody) {
+        return baseParts.join(' ');
+    }
+    const messagesRaw = jsonBody.messages;
+    const toolsRaw = jsonBody.tools;
+    const messageCount = Array.isArray(messagesRaw) ? messagesRaw.length : 0;
+    const toolCount = Array.isArray(toolsRaw) ? toolsRaw.length : 0;
+    const maxTokens = Number(jsonBody.max_tokens ?? jsonBody.maxTokens);
+    const keys = Object.keys(jsonBody).sort().join(',');
+    baseParts.push(`messages=${String(messageCount)}`);
+    baseParts.push(`tools=${String(toolCount)}`);
+    if (Number.isFinite(maxTokens) && maxTokens > 0) {
+        baseParts.push(`maxTokens=${String(Math.floor(maxTokens))}`);
+    }
+    if (keys.length > 0) {
+        baseParts.push(`keys=[${keys}]`);
+    }
+    baseParts.push(summarizeMessageShape(messagesRaw));
+    return baseParts.join(' ');
+}
+function summarizeErrorResponse(response) {
+    const contentType = (response.headers['content-type'] ?? '').toLowerCase();
+    if (!response.body || response.body.length === 0) {
+        return 'empty response body';
+    }
+    const raw = new TextDecoder().decode(response.body).trim();
+    if (raw.length === 0) {
+        return 'empty response body';
+    }
+    if (contentType.includes('application/json')) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                const object = parsed;
+                const nestedError = object.error && typeof object.error === 'object' && !Array.isArray(object.error)
+                    ? object.error
+                    : null;
+                const message = ((typeof nestedError?.message === 'string' && nestedError.message)
+                    || (typeof object.message === 'string' && object.message)
+                    || (typeof object.detail === 'string' && object.detail));
+                if (message) {
+                    return `message="${message}"`;
+                }
+            }
+        }
+        catch {
+            // fall through to raw snippet
+        }
+    }
+    const compact = raw.replace(/\s+/g, ' ');
+    const maxChars = 280;
+    const snippet = compact.length > maxChars ? `${compact.slice(0, maxChars)}...` : compact;
+    return `body="${snippet}"`;
+}
 function toFiniteNumberOrNull(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
@@ -401,13 +611,20 @@ export class BuyerProxy {
     _node;
     _port;
     _bgRefreshIntervalMs;
+    _peerCacheTtlMs;
     _pinnedPeerId;
     _cachedPeers = [];
+    _cacheLastUpdatedAtMs = 0;
+    _peerRefreshPromise = null;
+    _lastStaleCacheLogAtMs = 0;
     _bgRefreshHandle = null;
+    _lastSuccessfulPeerId = null;
+    _lastSuccessfulPeerByRouteKey = new Map();
     constructor(config) {
         this._node = config.node;
         this._port = config.port;
         this._bgRefreshIntervalMs = config.backgroundRefreshIntervalMs ?? 5 * 60_000;
+        this._peerCacheTtlMs = Math.max(0, config.peerCacheTtlMs ?? 30_000);
         this._pinnedPeerId = config.pinnedPeerId?.toLowerCase();
         this._server = createServer((req, res) => {
             this._handleRequest(req, res).catch((err) => {
@@ -440,34 +657,60 @@ export class BuyerProxy {
     }
     _startBackgroundRefresh() {
         this._bgRefreshHandle = setInterval(() => {
-            this._node.discoverPeers().then((peers) => {
-                if (peers.length > 0) {
-                    this._mergePeers(peers);
-                }
-            }).catch(() => { });
+            void this._refreshPeersNow().catch(() => {
+                // background refresh failure is non-fatal
+            });
         }, this._bgRefreshIntervalMs);
     }
-    _mergePeers(incoming) {
-        const existing = new Map(this._cachedPeers.map((p) => [p.peerId, p]));
-        let added = 0;
-        for (const p of incoming) {
-            if (!existing.has(p.peerId)) {
-                existing.set(p.peerId, p);
-                added++;
-            }
-        }
-        if (added > 0) {
-            this._cachedPeers = Array.from(existing.values());
-            log(`[background] Merged ${added} new peer(s) into cache (total: ${this._cachedPeers.length})`);
-        }
+    _replacePeers(incoming) {
+        this._cachedPeers = incoming;
+        this._cacheLastUpdatedAtMs = Date.now();
     }
     _evictPeer(peerId) {
         const before = this._cachedPeers.length;
         this._cachedPeers = this._cachedPeers.filter((p) => p.peerId !== peerId);
         if (this._cachedPeers.length < before) {
+            this._cacheLastUpdatedAtMs = Date.now();
             log(`Evicted failing peer ${peerId.slice(0, 12)}... from cache (${this._cachedPeers.length} remaining)`);
         }
     }
+    _rememberSuccessfulPeer(routeKey, peerId) {
+        this._lastSuccessfulPeerId = peerId;
+        this._lastSuccessfulPeerByRouteKey.set(routeKey, peerId);
+        // Keep map bounded to prevent unbounded growth from long-running sessions.
+        const MAX_ROUTE_HISTORY = 200;
+        if (this._lastSuccessfulPeerByRouteKey.size > MAX_ROUTE_HISTORY) {
+            const oldestKey = this._lastSuccessfulPeerByRouteKey.keys().next().value;
+            if (typeof oldestKey === 'string') {
+                this._lastSuccessfulPeerByRouteKey.delete(oldestKey);
+            }
+        }
+    }
+    _forgetSuccessfulPeer(routeKey, peerId) {
+        const rememberedForRoute = this._lastSuccessfulPeerByRouteKey.get(routeKey);
+        if (rememberedForRoute === peerId) {
+            this._lastSuccessfulPeerByRouteKey.delete(routeKey);
+        }
+        if (this._lastSuccessfulPeerId === peerId) {
+            this._lastSuccessfulPeerId = null;
+        }
+    }
+    _buildRouteKey(path, requestProtocol, requestedModel, explicitProvider) {
+        const normalizedPath = path.split('?')[0]?.trim().toLowerCase() ?? '/';
+        const pathGroup = (normalizedPath.startsWith('/v1/messages')
+            ? '/v1/messages'
+            : normalizedPath.startsWith('/v1/chat/completions')
+                ? '/v1/chat/completions'
+                : normalizedPath.startsWith('/v1/models')
+                    ? '/v1/models'
+                    : normalizedPath);
+        return [
+            pathGroup,
+            requestProtocol ?? 'unknown-protocol',
+            requestedModel ?? 'unknown-model',
+            explicitProvider ?? 'auto-provider',
+        ].join('|');
+    }
     async _readLocalSeederFallback() {
         try {
             const raw = await readFile(DAEMON_STATE_FILE, 'utf-8');
@@ -511,27 +754,62 @@ export class BuyerProxy {
             return null;
         }
     }
-    async _getPeers() {
-        // Return cache immediately — no TTL expiry; peers are evicted on failure
-        // and refreshed in the background on a fixed interval.
-        if (this._cachedPeers.length > 0) {
-            return this._cachedPeers;
-        }
-        // Cache is empty — must block on discovery (first request or all peers evicted)
+    async _discoverAndCachePeers() {
         const localSeeder = await this._readLocalSeederFallback();
         if (localSeeder) {
-            this._cachedPeers = [localSeeder];
+            this._replacePeers([localSeeder]);
             log(`Using local seeder ${localSeeder.peerId.slice(0, 12)}... @ ${localSeeder.publicAddress} (skipping DHT lookup)`);
             return this._cachedPeers;
         }
         log('Discovering peers via DHT...');
         const peers = await this._node.discoverPeers();
+        this._replacePeers(peers);
         if (peers.length > 0) {
-            this._cachedPeers = peers;
             log(`Found ${peers.length} peer(s)`);
         }
         return peers;
     }
+    async _refreshPeersNow() {
+        if (this._peerRefreshPromise) {
+            return this._peerRefreshPromise;
+        }
+        const previousCachedPeers = this._cachedPeers;
+        this._peerRefreshPromise = (async () => {
+            const peers = await this._discoverAndCachePeers();
+            if (peers.length === 0 && previousCachedPeers.length > 0) {
+                // Preserve stale cache as fallback when discovery transiently fails.
+                log('Discovery returned 0 peers; keeping previous cached peers as fallback.');
+                this._replacePeers(previousCachedPeers);
+                return previousCachedPeers;
+            }
+            return peers;
+        })().finally(() => {
+            this._peerRefreshPromise = null;
+        });
+        return this._peerRefreshPromise;
+    }
+    async _getPeers(options) {
+        const forceRefresh = options?.forceRefresh === true;
+        const cacheAgeMs = Date.now() - this._cacheLastUpdatedAtMs;
+        const cacheFresh = this._cacheLastUpdatedAtMs > 0 && cacheAgeMs <= this._peerCacheTtlMs;
+        if (forceRefresh) {
+            log('Forcing peer refresh before routing.');
+            return this._refreshPeersNow();
+        }
+        if (this._cachedPeers.length > 0) {
+            if (cacheFresh) {
+                return this._cachedPeers;
+            }
+            const now = Date.now();
+            if (now - this._lastStaleCacheLogAtMs >= 10_000) {
+                this._lastStaleCacheLogAtMs = now;
+                log(`Peer cache stale (${cacheAgeMs}ms old); routing from cached peers.`);
+            }
+            return this._cachedPeers;
+        }
+        // No cached peers yet — block on initial discovery.
+        return this._refreshPeersNow();
+    }
     _formatPeerSelectionDiagnostics(peers) {
         if (peers.length === 0) {
             return 'No peers discovered.';
@@ -580,6 +858,20 @@ export class BuyerProxy {
             headers,
             body: new Uint8Array(body),
         };
+        const clientAbortController = new AbortController();
+        const onClientAbort = () => {
+            if (clientAbortController.signal.aborted) {
+                return;
+            }
+            clientAbortController.abort();
+            log(`Client disconnected; aborting upstream request reqId=${serializedReq.requestId.slice(0, 8)}`);
+        };
+        req.once('aborted', onClientAbort);
+        res.once('close', () => {
+            if (!res.writableEnded) {
+                onClientAbort();
+            }
+        });
         // Discover peers
         const peers = await this._getPeers();
         if (peers.length === 0) {
@@ -590,11 +882,25 @@ export class BuyerProxy {
         }
         const requestProtocol = detectRequestModelApiProtocol(serializedReq);
         const requestedModel = extractRequestedModel(serializedReq);
+        log(`Routing: protocol=${requestProtocol ?? 'null'} model=${requestedModel ?? 'null'}`);
         const explicitProvider = getExplicitProviderOverride(serializedReq);
         const explicitPeerId = getExplicitPeerIdOverride(serializedReq, this._pinnedPeerId);
+        const preferredPeerId = getPreferredPeerIdHint(serializedReq);
+        log(`Routing hints: provider=${explicitProvider ?? 'auto'} pin-peer=${explicitPeerId ?? 'none'} prefer-peer=${preferredPeerId ?? 'none'}`);
+        const routeKey = this._buildRouteKey(serializedReq.path, requestProtocol, requestedModel, explicitProvider);
         const { candidatePeers, routePlanByPeerId, } = selectCandidatePeersForRouting(peers, requestProtocol, requestedModel, explicitProvider);
-        if (candidatePeers.length === 0) {
-            const diagnostics = this._formatPeerSelectionDiagnostics(peers);
+        let routingPeers = candidatePeers;
+        let routingPlans = routePlanByPeerId;
+        let discoveredPeers = peers;
+        if (routingPeers.length === 0) {
+            // One forced refresh handles stale-cache routing mismatches (e.g. missing provider/model updates).
+            discoveredPeers = await this._getPeers({ forceRefresh: true });
+            const refreshedSelection = selectCandidatePeersForRouting(discoveredPeers, requestProtocol, requestedModel, explicitProvider);
+            routingPeers = refreshedSelection.candidatePeers;
+            routingPlans = refreshedSelection.routePlanByPeerId;
+        }
+        if (routingPeers.length === 0) {
+            const diagnostics = this._formatPeerSelectionDiagnostics(discoveredPeers);
             res.writeHead(502, { 'content-type': 'text/plain' });
             if (requestProtocol) {
                 const protocolLabel = requestProtocol;
@@ -606,21 +912,40 @@ export class BuyerProxy {
             }
             return;
         }
+        log(`Routing candidates: ${routingPeers.length} peer(s)`);
         // Select peer: explicit pin bypasses the router (and retry)
         const router = this._node.router;
-        const RETRYABLE_STATUS_CODES = new Set([400, 404, 408, 429, 500, 502, 503, 504]);
+        const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
         if (explicitPeerId) {
-            const selectedPeer = candidatePeers.find((p) => p.peerId.toLowerCase() === explicitPeerId) ?? null;
+            let pinnedRoutingPeers = routingPeers;
+            let pinnedRoutePlans = routingPlans;
+            let selectedPeer = pinnedRoutingPeers.find((p) => p.peerId.toLowerCase() === explicitPeerId) ?? null;
+            if (!selectedPeer) {
+                log(`Pinned peer ${explicitPeerId.slice(0, 12)}... not in current candidate set; forcing refresh.`);
+                discoveredPeers = await this._getPeers({ forceRefresh: true });
+                const refreshedSelection = selectCandidatePeersForRouting(discoveredPeers, requestProtocol, requestedModel, explicitProvider);
+                pinnedRoutingPeers = refreshedSelection.candidatePeers;
+                pinnedRoutePlans = refreshedSelection.routePlanByPeerId;
+                selectedPeer = pinnedRoutingPeers.find((p) => p.peerId.toLowerCase() === explicitPeerId) ?? null;
+            }
             if (!selectedPeer) {
                 const source = serializedReq.headers['x-antseed-pin-peer'] ? 'x-antseed-pin-peer header' : '--peer flag';
+                const peerDiscovered = discoveredPeers.some((peer) => peer.peerId.toLowerCase() === explicitPeerId);
+                const protocolLabel = requestProtocol ? `protocol=${requestProtocol}` : 'protocol=unknown';
+                const providerLabel = explicitProvider ? `provider=${explicitProvider}` : 'provider=auto';
+                const modelLabel = requestedModel ? `model=${requestedModel}` : 'model=none';
+                const mismatchHint = peerDiscovered
+                    ? `Peer is discoverable but filtered as incompatible (${protocolLabel}, ${providerLabel}, ${modelLabel}).`
+                    : 'Peer is not discoverable right now.';
                 log(`Pinned peer ${explicitPeerId.slice(0, 12)}... not found in candidate list (${source})`);
                 res.writeHead(502, { 'content-type': 'text/plain' });
-                res.end(`Pinned peer ${explicitPeerId.slice(0, 12)}... is not available or does not support this request.`);
+                res.end(`Pinned peer ${explicitPeerId.slice(0, 12)}... is not available or does not support this request. ${mismatchHint}`);
                 return;
             }
             log(`Using pinned peer ${selectedPeer.peerId.slice(0, 12)}...`);
-            const result = await this._dispatchToPeer(res, serializedReq, selectedPeer, routePlanByPeerId, requestProtocol, requestedModel, explicitProvider, router, RETRYABLE_STATUS_CODES);
+            const result = await this._dispatchToPeer(res, serializedReq, selectedPeer, routeKey, pinnedRoutePlans, requestProtocol, requestedModel, explicitProvider, router, RETRYABLE_STATUS_CODES, clientAbortController.signal);
             if (!result.done) {
+                this._forgetSuccessfulPeer(routeKey, selectedPeer.peerId);
                 // Pinned peer returned a retryable error, but we don't retry — send error to client
                 res.writeHead(result.statusCode, result.responseHeaders);
                 res.end(result.responseBody);
@@ -630,16 +955,80 @@ export class BuyerProxy {
         // Non-pinned: retry with failover on provider errors
         const MAX_ATTEMPTS = 3;
         const triedPeerIds = new Set();
+        const preferredProviders = explicitProvider
+            ? []
+            : inferPreferredProvidersForRequest(requestProtocol, requestedModel);
+        const hasPreferredProviderCandidate = preferredProviders.length > 0
+            && routingPeers.some((peer) => {
+                const provider = routingPlans.get(peer.peerId)?.provider?.trim().toLowerCase();
+                return Boolean(provider && preferredProviders.includes(provider));
+            });
+        const restrictFailoverToPreferredProviders = preferredProviders.length > 0 && hasPreferredProviderCandidate;
+        if (restrictFailoverToPreferredProviders) {
+            log(`Provider-family failover lock active: [${preferredProviders.join(',')}]`);
+        }
         let lastStatusCode = 502;
         let lastResponseBody = null;
         let lastResponseHeaders = { 'content-type': 'text/plain' };
         for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
-            const availableCandidates = candidatePeers.filter((p) => !triedPeerIds.has(p.peerId));
+            const availableCandidates = routingPeers.filter((peer) => {
+                if (triedPeerIds.has(peer.peerId)) {
+                    return false;
+                }
+                if (!restrictFailoverToPreferredProviders) {
+                    return true;
+                }
+                const provider = routingPlans.get(peer.peerId)?.provider?.trim().toLowerCase();
+                return Boolean(provider && preferredProviders.includes(provider));
+            });
             if (availableCandidates.length === 0)
                 break;
             let selectedPeer = null;
-            // Prefer local peers on first attempt
+            // Prefer a recently successful peer for the same request route.
             if (attempt === 0) {
+                const routePreferredPeerId = this._lastSuccessfulPeerByRouteKey.get(routeKey);
+                if (routePreferredPeerId) {
+                    const remembered = availableCandidates.find((peer) => peer.peerId === routePreferredPeerId) ?? null;
+                    if (remembered) {
+                        selectedPeer = remembered;
+                        log(`Reusing last successful route peer ${selectedPeer.peerId.slice(0, 12)}...`);
+                    }
+                }
+            }
+            // Fallback to the latest globally successful peer.
+            if (!selectedPeer && attempt === 0 && this._lastSuccessfulPeerId && !requestedModel) {
+                const remembered = availableCandidates.find((peer) => peer.peerId === this._lastSuccessfulPeerId) ?? null;
+                if (remembered) {
+                    selectedPeer = remembered;
+                    log(`Reusing last successful peer ${selectedPeer.peerId.slice(0, 12)}...`);
+                }
+            }
+            // Soft peer affinity: try caller-preferred peer first, but allow normal fallback.
+            if (!selectedPeer && attempt === 0 && preferredPeerId) {
+                const preferred = availableCandidates.find((peer) => peer.peerId.toLowerCase() === preferredPeerId) ?? null;
+                if (preferred) {
+                    selectedPeer = preferred;
+                    log(`Preferring requested peer ${selectedPeer.peerId.slice(0, 12)}...`);
+                }
+            }
+            // Strongly prefer providers that match the requested model family (e.g. claude-* -> claude/anthropic providers).
+            if (!selectedPeer && attempt === 0 && preferredProviders.length > 0) {
+                const providerMatchedPeers = availableCandidates.filter((peer) => {
+                    const plannedProvider = routingPlans.get(peer.peerId)?.provider?.trim().toLowerCase();
+                    return plannedProvider ? preferredProviders.includes(plannedProvider) : false;
+                });
+                if (providerMatchedPeers.length > 0) {
+                    selectedPeer = router
+                        ? router.selectPeer(serializedReq, providerMatchedPeers)
+                        : providerMatchedPeers[0] ?? null;
+                    if (selectedPeer) {
+                        const plannedProvider = routingPlans.get(selectedPeer.peerId)?.provider ?? 'unknown';
+                        log(`Preferring model-matched provider "${plannedProvider}" for model "${requestedModel ?? 'unknown'}"`);
+                    }
+                }
+            }
+            // Prefer local peers on first attempt
+            if (!selectedPeer && attempt === 0) {
                 const localPeers = availableCandidates.filter((peer) => isLoopbackPeer(peer));
                 if (localPeers.length > 0) {
                     selectedPeer = router
@@ -650,6 +1039,26 @@ export class BuyerProxy {
                     }
                 }
             }
+            // Prefer peers that can serve the request protocol directly without adapter transform.
+            if (!selectedPeer && requestProtocol === 'anthropic-messages') {
+                const shouldPreferDirect = !requestedModel || /claude|anthropic/i.test(requestedModel);
+                if (shouldPreferDirect) {
+                    const directPeers = availableCandidates.filter((peer) => {
+                        const plan = routingPlans.get(peer.peerId);
+                        if (!plan)
+                            return false;
+                        return !plan.selection || !plan.selection.requiresTransform;
+                    });
+                    if (directPeers.length > 0) {
+                        selectedPeer = router
+                            ? router.selectPeer(serializedReq, directPeers)
+                            : directPeers[0] ?? null;
+                        if (selectedPeer) {
+                            log(`Preferring direct protocol peer ${selectedPeer.peerId.slice(0, 12)}...`);
+                        }
+                    }
+                }
+            }
             if (!selectedPeer) {
                 selectedPeer = router
                     ? router.selectPeer(serializedReq, availableCandidates)
@@ -658,9 +1067,10 @@ export class BuyerProxy {
             if (!selectedPeer)
                 break;
             triedPeerIds.add(selectedPeer.peerId);
-            const result = await this._dispatchToPeer(res, serializedReq, selectedPeer, routePlanByPeerId, requestProtocol, requestedModel, explicitProvider, router, RETRYABLE_STATUS_CODES);
+            const result = await this._dispatchToPeer(res, serializedReq, selectedPeer, routeKey, routingPlans, requestProtocol, requestedModel, explicitProvider, router, RETRYABLE_STATUS_CODES, clientAbortController.signal);
             if (result.done)
                 return;
+            this._forgetSuccessfulPeer(routeKey, selectedPeer.peerId);
             // Request failed with a retryable error — try another peer
             lastStatusCode = result.statusCode;
             lastResponseBody = result.responseBody;
@@ -677,7 +1087,7 @@ export class BuyerProxy {
                 res.end(lastResponseBody);
             }
             else {
-                const diagnostics = this._formatPeerSelectionDiagnostics(candidatePeers);
+                const diagnostics = this._formatPeerSelectionDiagnostics(routingPeers);
                 log('No peers available for request');
                 res.writeHead(502, { 'content-type': 'text/plain' });
                 res.end(`Router could not select a suitable peer. ${diagnostics}`);
@@ -689,13 +1099,13 @@ export class BuyerProxy {
      * was sent to the client (success or non-retryable error), or retry info if the
      * caller should try another peer.
      */
-    async _dispatchToPeer(res, serializedReq, selectedPeer, routePlanByPeerId, requestProtocol, requestedModel, explicitProvider, router, retryableStatusCodes) {
+    async _dispatchToPeer(res, serializedReq, selectedPeer, routeKey, routePlanByPeerId, requestProtocol, requestedModel, explicitProvider, router, retryableStatusCodes, requestSignal) {
         const selectedRoutePlan = routePlanByPeerId.get(selectedPeer.peerId)
             ?? resolvePeerRoutePlan(selectedPeer, requestProtocol, requestedModel, explicitProvider);
         if (!selectedRoutePlan) {
             return { done: false, statusCode: 502, responseBody: Buffer.from('No compatible provider route'), responseHeaders: { 'content-type': 'text/plain' }, errorMessage: null };
         }
-        const { 'x-antseed-pin-peer': _pinPeer, ...headersForPeer } = serializedReq.headers;
+        const { 'x-antseed-pin-peer': _pinPeer, 'x-antseed-prefer-peer': _preferPeer, ...headersForPeer } = serializedReq.headers;
         let requestForPeer = {
             ...serializedReq,
             headers: {
@@ -734,6 +1144,7 @@ export class BuyerProxy {
                 return { done: true };
             }
         }
+        log(`Outbound request shape: ${summarizeRequestShape(requestForPeer)}`);
         log(`Routing to peer ${selectedPeer.peerId.slice(0, 12)}...`);
         // Forward through P2P
         const wantsStreaming = !forceDisableUpstreamStreaming
@@ -748,7 +1159,12 @@ export class BuyerProxy {
                             return;
                         streamed = true;
                         const streamingHeaders = attachStreamingAntseedHeaders(startResponse.headers, selectedPeer, requestForPeer.requestId);
+                        // Ensure SSE-friendly headers so intermediaries don't buffer
+                        /* streamingHeaders['cache-control'] = 'no-cache, no-transform'
+                        streamingHeaders['x-accel-buffering'] = 'no' */
                         res.writeHead(startResponse.statusCode, streamingHeaders);
+                        // Disable Nagle's algorithm on the underlying socket for low-latency streaming
+                        // res.socket?.setNoDelay(true)
                         if (startResponse.body.length > 0) {
                             res.write(Buffer.from(startResponse.body));
                         }
@@ -760,9 +1176,12 @@ export class BuyerProxy {
                             res.write(Buffer.from(chunk.data));
                         }
                     },
-                });
+                }, { signal: requestSignal });
                 const latencyMs = Date.now() - startTime;
                 log(`Response: ${response.statusCode} (${latencyMs}ms, ${response.body.length} bytes)`);
+                if (response.statusCode >= 400) {
+                    log(`Upstream error detail: ${summarizeErrorResponse(response)}`);
+                }
                 const telemetry = computeResponseTelemetry(requestForPeer, response.headers, response.body, selectedPeer);
                 if (router) {
                     router.onResult(selectedPeer, {
@@ -773,6 +1192,9 @@ export class BuyerProxy {
                 }
                 if (streamed) {
                     // Headers already sent to client, can't retry
+                    if (response.statusCode >= 200 && response.statusCode < 400) {
+                        this._rememberSuccessfulPeer(routeKey, selectedPeer.peerId);
+                    }
                     if (!res.writableEnded) {
                         res.end();
                     }
@@ -783,17 +1205,27 @@ export class BuyerProxy {
                 if (retryableStatusCodes.has(response.statusCode)) {
                     return { done: false, statusCode: response.statusCode, responseBody: Buffer.from(response.body), responseHeaders, errorMessage: null };
                 }
+                if (response.statusCode >= 200 && response.statusCode < 400) {
+                    this._rememberSuccessfulPeer(routeKey, selectedPeer.peerId);
+                }
                 res.writeHead(response.statusCode, responseHeaders);
                 res.end(Buffer.from(response.body));
                 return { done: true };
             }
             else {
-                let response = await this._node.sendRequest(selectedPeer, requestForPeer);
+                const upstreamResponse = await this._node.sendRequest(selectedPeer, requestForPeer, { signal: requestSignal });
+                if (upstreamResponse.statusCode >= 400) {
+                    log(`Upstream raw error detail: ${summarizeErrorResponse(upstreamResponse)}`);
+                }
+                let response = upstreamResponse;
                 if (adaptResponse) {
                     response = adaptResponse(response);
                 }
                 const latencyMs = Date.now() - startTime;
                 log(`Response: ${response.statusCode} (${latencyMs}ms, ${response.body.length} bytes)`);
+                if (response.statusCode >= 400) {
+                    log(`Upstream error detail: ${summarizeErrorResponse(response)}`);
+                }
                 const telemetry = computeResponseTelemetry(requestForPeer, response.headers, response.body, selectedPeer);
                 const responseHeaders = attachAntseedTelemetryHeaders(response.headers, selectedPeer, telemetry, requestForPeer.requestId, latencyMs);
                 // Report result to router for learning
@@ -808,6 +1240,9 @@ export class BuyerProxy {
                 if (retryableStatusCodes.has(response.statusCode)) {
                     return { done: false, statusCode: response.statusCode, responseBody: Buffer.from(response.body), responseHeaders, errorMessage: null };
                 }
+                if (response.statusCode >= 200 && response.statusCode < 400) {
+                    this._rememberSuccessfulPeer(routeKey, selectedPeer.peerId);
+                }
                 // Forward response headers and body to the HTTP client
                 res.writeHead(response.statusCode, responseHeaders);
                 res.end(Buffer.from(response.body));
@@ -817,7 +1252,18 @@ export class BuyerProxy {
         catch (err) {
             const latencyMs = Date.now() - startTime;
             const message = err instanceof Error ? err.message : String(err);
+            const abortedLocally = requestSignal.aborted || /\baborted\b/i.test(message);
             log(`Request failed after ${latencyMs}ms: ${message}`);
+            if (abortedLocally) {
+                log(`Request ${requestForPeer.requestId.slice(0, 8)} aborted locally; skipping retry, router penalty, and peer eviction.`);
+                if (res.headersSent) {
+                    if (!res.writableEnded) {
+                        res.end();
+                    }
+                    return { done: true };
+                }
+                return { done: true };
+            }
             if (router) {
                 router.onResult(selectedPeer, {
                     success: false,
@@ -825,8 +1271,18 @@ export class BuyerProxy {
                     tokens: 0,
                 });
             }
-            // Evict only the failing peer — others remain usable
-            this._evictPeer(selectedPeer.peerId);
+            // Avoid poisoning routing cache from control-plane model enumeration failures.
+            // Some peers can time out on /v1/models while still serving inference paths.
+            const normalizedPath = requestForPeer.path.toLowerCase();
+            const isControlPlaneModelsRequest = normalizedPath.startsWith('/v1/models');
+            if (isControlPlaneModelsRequest) {
+                log(`Skipping peer eviction for control-plane failure on ${requestForPeer.path}`);
+            }
+            else {
+                // Evict only the failing peer — others remain usable.
+                this._evictPeer(selectedPeer.peerId);
+            }
+            this._forgetSuccessfulPeer(routeKey, selectedPeer.peerId);
             if (res.headersSent) {
                 // Headers already sent (streaming), can't retry
                 if (!res.writableEnded) {