@north-light/crouter 0.3.273 → 0.3.274

package/dist/core/__tests__/fault-classifier.test.js

@@ -9,6 +9,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { classify } from '../fault-classifier.js';
+import { __classifyProviderErrorForTest } from '../../builtin-pi-packages/pi-crtr-extensions/extensions/provider-rotation.js';
 test('invalid_grant text classifies as fatal auth (issue #94)', () => {
     const c = classify('pi→provider', 'Anthropic token refresh failed: invalid_grant');
     assert.equal(c.kind, 'auth');
@@ -89,3 +90,49 @@ test('"terminated" matches as a whole word only (no false positive on substrings
     // guard the word-boundary choice explicitly.
     assert.notEqual(classify('pi→provider', 'preterminated').kind, 'connection');
 });
+test('shared recognition preserves each existing policy eligibility, except bare quota', () => {
+    const assertPair = (raw, faultKind, rotationKind, observed = {}) => {
+        assert.equal(classify('pi→provider', raw).kind, faultKind, `fault: ${JSON.stringify(raw)}`);
+        const error = typeof raw === 'string' ? { message: raw } : raw;
+        assert.equal(__classifyProviderErrorForTest(error, observed).kind, rotationKind, `rotation: ${JSON.stringify(raw)}`);
+    };
+    for (const [status, faultKind, rotationKind] of [
+        [401, 'auth', 'fatal'], [403, 'auth', 'fatal'], [429, 'rate-limit', 'rate_limit'],
+        [500, 'overloaded', 'transient'], [502, 'overloaded', 'transient'], [503, 'overloaded', 'transient'], [504, 'overloaded', 'transient'],
+        [529, 'overloaded', 'fatal'], [501, 'overloaded', 'fatal'], [400, 'protocol', 'fatal'], [413, 'protocol', 'fatal'],
+    ])
+        assertPair({ status }, faultKind, rotationKind);
+    assertPair({ status: 503 }, 'overloaded', 'rate_limit', { retryAfterMs: 1 });
+    for (const code of ['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOENT', 'ENOTFOUND', 'EAI_AGAIN', 'EPIPE', 'EHOSTUNREACH', 'ENETUNREACH']) {
+        assertPair({ code }, 'connection', 'fatal');
+    }
+    assertPair({ code: 'ELOCKED' }, 'overloaded', 'fatal');
+    assertPair({ code: 1008 }, 'protocol', 'fatal');
+    assertPair({ code: 1006 }, 'connection', 'fatal');
+    assertPair({ code: 1011, reason: 'no running broker' }, 'connection', 'fatal');
+    assertPair({ code: 1011, reason: 'unrelated failure' }, 'other', 'fatal');
+    for (const text of ['rate limit', '429', 'too many requests', 'usage limit', 'usage_not_included', 'usagelimiterror', 'insufficient_quota', 'quota exceeded']) {
+        assertPair(text, 'rate-limit', 'rate_limit');
+    }
+    assertPair('quota', 'other', 'fatal');
+    assertPair('ordinary usage discussion', 'other', 'fatal');
+    for (const text of ['connection', 'network', 'fetch failed', 'econnreset', 'econnrefused', 'enotfound', 'etimedout', 'timed out', 'timeout', 'WebSocket closed', 'WebSocket stream closed before response.completed', 'WebSocket error', 'WebSocket interruption', 'socket hang', 'overloaded', 'temporarily unavailable']) {
+        const faultKind = text === 'overloaded' || text === 'temporarily unavailable' ? 'overloaded' : 'connection';
+        assertPair(text, faultKind, 'transient');
+    }
+    for (const text of ['socket', 'service unavailable'])
+        assertPair(text, 'other', 'transient');
+    for (const text of ['network error: rate limit exceeded', 'service unavailable: too many requests'])
+        assertPair(text, 'rate-limit', 'transient');
+    for (const text of ['413 Payload Too Large', 'invalid_grant', 'context overflow recovery failed']) {
+        const faultKind = text.includes('413') ? 'protocol' : text.includes('invalid_grant') ? 'auth' : 'context-overflow';
+        assertPair(text, faultKind, 'fatal');
+    }
+    assertPair('WebSocket closed: 1008 policy violation', 'protocol', 'transient');
+    for (const text of ['lock file is already being held', 'Internal server error', 'APIError', '500', 'capacity', 'server busy']) {
+        assertPair(text, 'overloaded', 'fatal');
+    }
+    for (const text of ['EPIPE', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH', 'terminated', 'other side closed', 'premature close']) {
+        assertPair(text, 'connection', 'fatal');
+    }
+});

package/dist/core/fault-classifier.d.ts

@@ -25,19 +25,4 @@ export interface FaultClassification {
     disposition: FaultRetryDisposition;
 }
 export declare function errorClassFromFault(fault: Pick<Fault, 'kind' | 'retry'>): ErrorClass;
-export interface FaultErrnoLike {
-    code?: unknown;
-    errno?: unknown;
-    message?: unknown;
-}
-export interface FaultHttpLike {
-    status?: unknown;
-    statusText?: unknown;
-    ok?: unknown;
-    message?: unknown;
-}
-export interface FaultWsCloseLike {
-    code?: unknown;
-    reason?: unknown;
-}
 export declare function classify(link: FaultLink, raw: unknown): FaultClassification;

package/dist/core/fault-classifier.js

@@ -1,4 +1,5 @@
 import { hasManagedProviderCoolingDiagnostic } from './runtime/managed-provider-cooling.js';
+import { recognizeProviderError } from './provider-error-recognition.js';
 import { isRecord } from '../shared/predicates.js';
 const errorClassByFaultKind = {
     'rate-limit': 'rate_limit',
@@ -17,85 +18,21 @@ export function errorClassFromFault(fault) {
         retry_disposition: fault.retry.disposition,
     };
 }
-function text(value) {
-    return typeof value === 'string' ? value : '';
-}
-function classifyProviderText(message) {
-    const m = message ?? '';
-    // ORDER MATTERS: rate-limit → auth/protocol → overloaded → connection → other.
-    // Auth must win over a generic API-error wrapper, and a policy-violation close
-    // must not become a retryable transport interruption.
-    if (/rate.?limit|\b429\b|too many requests|quota/i.test(m))
-        return 'rate-limit';
-    // A body the other side refuses for SIZE is the request itself being
-    // unacceptable, never a transient server condition: the retry re-posts the
-    // same conversation and fails identically, forever. This must precede the
-    // overloaded rule, which otherwise claims a size rejection wrapped in 5xx
-    // prose ("500 ... request entity too large") and arms an unwinnable retry.
-    if (/\b413\b|payload too large|entity too large|request too large|entity\.too\.large|body exceeds/i.test(m))
-        return 'protocol';
-    if (/invalid_grant|refresh token|unauthori[sz]ed|invalid.?api.?key|authentication failed|\b401\b|\b403\b/i.test(m))
-        return 'auth';
-    // pi compacts and retries a raw provider overflow. Its failed-recovery result
-    // is the point at which the session cannot become viable without a new launch.
-    if (/context overflow recovery failed/i.test(m))
-        return 'context-overflow';
-    if (/websocket.*(?:closed.*\b(?:1002|1003|1007|1008|1009|1010)\b|protocol error|policy violation|unsupported data|invalid (?:frame|payload)|message too big|mandatory extension)/i.test(m))
-        return 'protocol';
-    // proper-lockfile contention on a credential file: another process holds the
-    // mutex right now, so the same request wins once it releases.
-    if (/lock file is already being held/i.test(m))
-        return 'overloaded';
-    if (/overloaded|\b5\d\d\b|internal server error|api.?error|capacity|server.{0,3}busy|temporarily unavailable/i.test(m))
-        return 'overloaded';
-    if (/connection|econnreset|etimedout|enotfound|econnrefused|network|fetch failed|socket hang|timed? out|timeout|\bterminated\b|other side closed|premature close|websocket\s+(?:was\s+)?closed|websocket stream closed before response\.completed|websocket\s+error|websocket.*interrupt/i.test(m))
-        return 'connection';
-    return 'other';
-}
-function classifyErrno(raw) {
-    const code = text(raw.code) || text(raw.errno);
-    if (code === '')
-        return null;
-    if (/^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOENT|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH)$/i.test(code)) {
-        return 'connection';
-    }
-    // A held filesystem mutex, not a broken link: back off on time rather than
-    // behind the online probe a connection fault waits on.
-    if (/^ELOCKED$/i.test(code))
-        return 'overloaded';
-    return null;
-}
-function classifyHttp(raw) {
-    const status = typeof raw.status === 'number' ? raw.status : null;
-    if (status === null)
-        return null;
-    if (status === 401 || status === 403)
-        return 'auth';
-    if (status === 429)
-        return 'rate-limit';
-    if (status === 503 || status === 529)
-        return 'overloaded';
-    if (status >= 500 && status <= 599)
-        return 'overloaded';
-    if (status >= 400 && status <= 499)
-        return 'protocol';
-    return null;
-}
-function classifyWsClose(raw) {
-    const code = typeof raw.code === 'number' ? raw.code : null;
-    if (code === null)
-        return null;
-    if (code === 1008)
-        return 'protocol';
-    if (code === 1006)
-        return 'connection';
-    if (code === 1011) {
-        const reason = text(raw.reason);
-        if (/no running broker/i.test(reason))
-            return 'connection';
-        return classifyProviderText(reason) === 'connection' ? 'connection' : 'other';
+function faultKindFromProviderSignal(signal) {
+    switch (signal.kind) {
+        case 'rate-limit': return 'rate-limit';
+        case 'auth': return 'auth';
+        case 'protocol': return 'protocol';
+        case 'context-overflow': return 'context-overflow';
+        case 'overloaded':
+        case 'overloaded-only':
+        case 'transient-http': return 'overloaded';
+        case 'connection':
+        case 'connection-only': return 'connection';
+        case 'socket':
+        case 'service-unavailable':
+        case 'other': return 'other';
     }
-    return null;
 }
 function classifyDisposition(link, kind) {
     if (kind === 'auth' || kind === 'protocol' || kind === 'context-overflow')
@@ -140,17 +77,15 @@ export function classify(link, raw) {
     if (link === 'pi→provider' && hasManagedProviderCoolingDiagnostic(raw)) {
         return { kind: 'rate-limit', disposition: 'auto' };
     }
-    if (isRecord(raw)) {
-        const errno = classifyErrno(raw);
-        if (errno !== null)
-            return { kind: errno, disposition: classifyDisposition(link, errno) };
-        const http = classifyHttp(raw);
-        if (http !== null)
-            return { kind: http, disposition: classifyDisposition(link, http) };
-        const ws = classifyWsClose(raw);
-        if (ws !== null)
-            return { kind: ws, disposition: classifyDisposition(link, ws) };
-    }
-    const kind = classifyProviderText(rawText(raw));
+    const value = isRecord(raw) ? raw : {};
+    const signal = recognizeProviderError({
+        code: value['code'],
+        errno: value['errno'],
+        status: value['status'],
+        wsCloseCode: value['code'],
+        wsCloseReason: value['reason'],
+        message: rawText(raw),
+    });
+    const kind = faultKindFromProviderSignal(signal);
     return { kind, disposition: classifyDisposition(link, kind) };
 }

package/dist/core/provider-error-recognition.d.ts

@@ -0,0 +1,27 @@
+export type ProviderErrorSignalKind = 'rate-limit' | 'auth' | 'protocol' | 'context-overflow' | 'overloaded' | 'overloaded-only' | 'transient-http' | 'connection' | 'connection-only' | 'socket' | 'service-unavailable' | 'other';
+export type ProviderErrorMatchedOn = 'errno' | 'status' | 'websocket-close' | 'text' | 'none';
+export interface ProviderErrorTextMatch {
+    kind: ProviderErrorSignalKind;
+    match: string;
+}
+export interface ProviderErrorSignal {
+    kind: ProviderErrorSignalKind;
+    matchedOn: ProviderErrorMatchedOn;
+    status?: number;
+    retryAfterMs?: number;
+    match?: string;
+    textKind?: ProviderErrorSignalKind;
+    textMatch?: string;
+    textMatches?: readonly ProviderErrorTextMatch[];
+}
+export interface ProviderErrorRecognitionInput {
+    status?: unknown;
+    retryAfterMs?: number;
+    code?: unknown;
+    errno?: unknown;
+    wsCloseCode?: unknown;
+    wsCloseReason?: unknown;
+    message?: string;
+}
+/** Recognizes provider failure facts. Consumers apply their own retry policy. */
+export declare function recognizeProviderError(input: ProviderErrorRecognitionInput): ProviderErrorSignal;

package/dist/core/provider-error-recognition.js

@@ -0,0 +1,74 @@
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+function signal(kind, matchedOn, options = {}) {
+    return { kind, matchedOn, ...options };
+}
+function withTextMatch(signal, textSignal) {
+    return textSignal.matchedOn === 'text'
+        ? { ...signal, textKind: textSignal.kind, textMatch: textSignal.match, textMatches: textSignal.textMatches }
+        : signal;
+}
+const TEXT_PATTERNS = [
+    ['rate-limit', /rate.?limit|\b429\b|too many requests|usage[ _]limit|usage_not_included|usagelimiterror|insufficient_quota|quota exceeded/i],
+    ['protocol', /\b413\b|payload too large|entity too large|request too large|entity\.too\.large|body exceeds/i],
+    ['auth', /invalid_grant|refresh token|unauthori[sz]ed|invalid.?api.?key|authentication failed|\b401\b|\b403\b/i],
+    ['context-overflow', /context overflow recovery failed/i],
+    ['protocol', /websocket.*(?:closed.*\b(?:1002|1003|1007|1008|1009|1010)\b|protocol error|policy violation|unsupported data|invalid (?:frame|payload)|message too big|mandatory extension)/i],
+    ['overloaded-only', /lock file is already being held/i],
+    ['overloaded', /overloaded|temporarily unavailable/i],
+    ['service-unavailable', /service.?unavailable/i],
+    ['overloaded-only', /internal server error|api.?error|\b5\d\d\b|capacity|server.{0,3}busy/i],
+    ['connection', /connection|econnreset|etimedout|enotfound|econnrefused|network|fetch failed|socket hang|timed? out|timeout|websocket\s+(?:was\s+)?closed|websocket stream closed before response\.completed|websocket\s+error|websocket.*interrupt/i],
+    ['socket', /socket/i],
+    ['connection-only', /eai_again|epipe|ehostunreach|enetunreach|\bterminated\b|other side closed|premature close/i],
+];
+function recognizeText(message) {
+    // The order preserves the canonical taxonomy: size wins over wrapped 5xx prose,
+    // and auth wins over a generic API-error wrapper. Every match remains available
+    // because rotation deliberately gives transient text priority over rate-limit text.
+    const matches = TEXT_PATTERNS.flatMap(([kind, pattern]) => {
+        const match = message.match(pattern);
+        return match ? [{ kind, match: match[0] }] : [];
+    });
+    const first = matches[0];
+    return first === undefined ? signal('other', 'none') : { ...signal(first.kind, 'text', { match: first.match }), textMatches: matches };
+}
+/** Recognizes provider failure facts. Consumers apply their own retry policy. */
+export function recognizeProviderError(input) {
+    const retryAfterMs = input.retryAfterMs;
+    const textSignal = recognizeText(input.message ?? '');
+    const errno = text(input.code) || text(input.errno);
+    if (/^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOENT|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH)$/i.test(errno)) {
+        return withTextMatch(signal('connection', 'errno', { retryAfterMs }), textSignal);
+    }
+    if (/^ELOCKED$/i.test(errno))
+        return withTextMatch(signal('overloaded', 'errno', { retryAfterMs }), textSignal);
+    const status = typeof input.status === 'number' ? input.status : undefined;
+    if (status !== undefined) {
+        if (status === 401 || status === 403)
+            return withTextMatch(signal('auth', 'status', { status, retryAfterMs }), textSignal);
+        if (status === 429)
+            return withTextMatch(signal('rate-limit', 'status', { status, retryAfterMs }), textSignal);
+        if (status === 500 || status === 502 || status === 503 || status === 504)
+            return withTextMatch(signal('transient-http', 'status', { status, retryAfterMs }), textSignal);
+        if (status >= 500 && status <= 599)
+            return withTextMatch(signal('overloaded', 'status', { status, retryAfterMs }), textSignal);
+        if (status >= 400 && status <= 499)
+            return withTextMatch(signal('protocol', 'status', { status, retryAfterMs }), textSignal);
+    }
+    const wsCloseCode = typeof input.wsCloseCode === 'number' ? input.wsCloseCode : undefined;
+    if (wsCloseCode === 1008)
+        return withTextMatch(signal('protocol', 'websocket-close', { retryAfterMs }), textSignal);
+    if (wsCloseCode === 1006)
+        return withTextMatch(signal('connection', 'websocket-close', { retryAfterMs }), textSignal);
+    if (wsCloseCode === 1011) {
+        const reason = text(input.wsCloseReason);
+        const reasonSignal = recognizeText(reason);
+        if (/no running broker/i.test(reason) || reasonSignal.kind === 'connection' || reasonSignal.kind === 'connection-only') {
+            return withTextMatch(signal('connection', 'websocket-close', { retryAfterMs }), textSignal);
+        }
+        return withTextMatch(signal('other', 'websocket-close', { retryAfterMs }), textSignal);
+    }
+    return retryAfterMs === undefined ? textSignal : { ...textSignal, retryAfterMs };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.273",
+  "version": "0.3.274",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.273",
+  "version": "0.3.274",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.273",
+      "version": "0.3.274",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {