@north-light/api 0.3.445 → 0.3.447

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/dist/core/provider-failure.d.ts

@@ -0,0 +1,27 @@
+import type { AssistantMessageDiagnostic } from '@earendil-works/pi-ai';
+export declare const PROVIDER_FAILURE_DIAGNOSTIC = "crtr:provider-failure";
+export interface ProviderFailureCause {
+    message?: string;
+    status?: number;
+    code?: string | number;
+    errno?: string;
+    body?: string;
+}
+export interface ProviderFailureDetails {
+    status?: number;
+    code?: string | number;
+    errno?: string;
+    body?: string;
+    causes?: ProviderFailureCause[];
+}
+export interface NormalizedProviderFailure extends ProviderFailureDetails {
+    message: string;
+}
+/** Converts an arbitrary provider failure into serializable facts before an SDK stream flattens it to `errorMessage`. */
+export declare function normalizeProviderFailure(error: unknown, observed?: {
+    status?: number;
+}): NormalizedProviderFailure;
+/** The stable diagnostic carrier for normalized provider error facts on an assistant error message. */
+export declare function providerFailureDiagnostic(details: ProviderFailureDetails): AssistantMessageDiagnostic;
+/** Reads provider facts from the assistant-message diagnostic without trusting arbitrary nested error objects. */
+export declare function extractProviderFailureDetails(message: unknown): ProviderFailureDetails | undefined;

package/dist/core/provider-failure.js

@@ -0,0 +1,109 @@
+import { isRecord } from '../shared/predicates.js';
+export const PROVIDER_FAILURE_DIAGNOSTIC = 'crtr:provider-failure';
+const CAUSE_LIMIT = 8;
+function text(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function status(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function code(value) {
+    return typeof value === 'string' || typeof value === 'number' ? value : undefined;
+}
+function record(value) {
+    return isRecord(value) ? value : undefined;
+}
+function failureCause(value) {
+    const message = text(value['errorMessage']) ?? text(value['message']) ?? text(value['reason']) ?? text(value['statusText']);
+    const cause = {
+        ...(message === undefined ? {} : { message }),
+        ...(status(value['status']) === undefined ? {} : { status: status(value['status']) }),
+        ...(code(value['code']) === undefined ? {} : { code: code(value['code']) }),
+        ...(text(value['errno']) === undefined ? {} : { errno: text(value['errno']) }),
+        ...(text(value['body']) === undefined ? {} : { body: text(value['body']) }),
+    };
+    return Object.keys(cause).length === 0 ? undefined : cause;
+}
+/** Converts an arbitrary provider failure into serializable facts before an SDK stream flattens it to `errorMessage`. */
+export function normalizeProviderFailure(error, observed = {}) {
+    const root = record(error);
+    const rootCause = root === undefined ? undefined : failureCause(root);
+    const causes = [];
+    const seen = new Set([error]);
+    let current = root === undefined ? undefined : record(root['cause']);
+    while (current !== undefined && !seen.has(current) && causes.length < CAUSE_LIMIT) {
+        seen.add(current);
+        const cause = failureCause(current);
+        if (cause !== undefined)
+            causes.push(cause);
+        current = record(current['cause']);
+    }
+    const message = rootCause?.message ?? (error instanceof Error ? error.message : undefined) ?? String(error ?? 'Provider request failed');
+    return {
+        message,
+        ...((observed.status ?? rootCause?.status) === undefined ? {} : { status: observed.status ?? rootCause?.status }),
+        ...(rootCause?.code === undefined ? {} : { code: rootCause.code }),
+        ...(rootCause?.errno === undefined ? {} : { errno: rootCause.errno }),
+        ...(rootCause?.body === undefined ? {} : { body: rootCause.body }),
+        ...(causes.length === 0 ? {} : { causes }),
+    };
+}
+/** The stable diagnostic carrier for normalized provider error facts on an assistant error message. */
+export function providerFailureDiagnostic(details) {
+    return { type: PROVIDER_FAILURE_DIAGNOSTIC, timestamp: Date.now(), details: jsonDetails(details) };
+}
+/** pi types diagnostic details as strict JSON, which excludes `undefined`; every
+ *  field here is a JSON scalar or a list of them by declaration, so dropping the
+ *  absent keys is the only conversion needed. */
+function jsonDetails(details) {
+    const out = jsonCause(details);
+    if (details.causes !== undefined)
+        out['causes'] = details.causes.map(jsonCause);
+    return out;
+}
+function jsonCause(cause) {
+    const out = {};
+    if (cause.message !== undefined)
+        out['message'] = cause.message;
+    if (cause.status !== undefined)
+        out['status'] = cause.status;
+    if (cause.code !== undefined)
+        out['code'] = cause.code;
+    if (cause.errno !== undefined)
+        out['errno'] = cause.errno;
+    if (cause.body !== undefined)
+        out['body'] = cause.body;
+    return out;
+}
+function providerFailureDetails(value) {
+    const diagnostics = record(value)?.['diagnostics'];
+    if (!Array.isArray(diagnostics))
+        return undefined;
+    for (const diagnostic of diagnostics) {
+        const diagnosticRecord = record(diagnostic);
+        if (diagnosticRecord?.['type'] !== PROVIDER_FAILURE_DIAGNOSTIC)
+            continue;
+        const details = record(diagnosticRecord['details']);
+        if (details === undefined)
+            continue;
+        const causes = Array.isArray(details['causes'])
+            ? details['causes'].flatMap((item) => {
+                const cause = record(item);
+                const normalized = cause === undefined ? undefined : failureCause(cause);
+                return normalized === undefined ? [] : [normalized];
+            })
+            : undefined;
+        return {
+            ...(status(details['status']) === undefined ? {} : { status: status(details['status']) }),
+            ...(code(details['code']) === undefined ? {} : { code: code(details['code']) }),
+            ...(text(details['errno']) === undefined ? {} : { errno: text(details['errno']) }),
+            ...(text(details['body']) === undefined ? {} : { body: text(details['body']) }),
+            ...(causes === undefined || causes.length === 0 ? {} : { causes }),
+        };
+    }
+    return undefined;
+}
+/** Reads provider facts from the assistant-message diagnostic without trusting arbitrary nested error objects. */
+export function extractProviderFailureDetails(message) {
+    return providerFailureDetails(message);
+}