@north-light/crouter 0.3.273 → 0.3.275

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/dist/core/runtime/surface-bg.d.ts

@@ -1,10 +1,12 @@
-/** The SGR escape that turns ON the distinct-surface background (theme
- *  `selectedBg`), e.g. `\x1b[48;2;58;58;74m`. Pair with `\x1b[49m` to reset just
+/** The SGR escape that turns ON the distinct-surface background (the theme's
+ *  card plane), e.g. `\x1b[48;2;52;53;65m`. Pair with `\x1b[49m` to reset just
  *  the background. Throws if no process has initialized the theme — callers on a
  *  render path (the attach overlay) always have, by construction. */
 export declare function surfaceBgAnsi(): string;
-/** tmux flags that frame a `display-menu` / `display-popup` on the distinct
- *  surface background — a rounded border + the surface bg on the body and border.
+/** tmux flags that frame a `display-menu` / `display-popup` as a distinct
+ *  surface — a rounded border in the theme accent around a body painted with the
+ *  theme's card plane. The accent border is what carries the "you are somewhere
+ *  else" signal, because a card sits close to the page by design.
  *  Empty when the theme is unavailable in this process (chrome stays default; the
  *  attach viewer re-installs the menu with these once it has themed). One knob:
  *  every crtr tmux float shares this single definition. */

package/dist/core/runtime/surface-bg.js

@@ -3,10 +3,24 @@
 // crtr's overlays and popups must read as a SEPARATE surface from the normal one
 // (CTO ruling, insights/terminal-ui/inline-ui-placement #11): a popup whose background matches
 // the surface has invisible edges, so you can't tell where the float begins. We
-// paint them with the active pi theme's `selectedBg` role — theme-derived, so it
-// adapts to light/dark and is ONE centralized knob, not a scattered hardcode.
+// paint them from the active pi theme — theme-derived, so it adapts to light/dark
+// and is ONE centralized knob, not a scattered hardcode.
 //
-// pi 0.79 does not re-export `selectedBg` through its public API (the `.` entry
+// WHICH ROLE: `userMessageBg`, the theme's CARD plane — not `selectedBg`. Every
+// theme places its card one step off the page background (gruvbox-material
+// #32302f vs #282828; pi's own dark #343541, light #e8e8e8) while `selectedBg` is
+// a SELECTION BAND, deliberately pushed far off the page so a highlighted row
+// lifts. Painting a 90%×85% takeover with the selection band made the whole
+// screen that band: every dim/muted role lost the contrast it was designed
+// against (gruvbox dim text fell to 2.1:1), and the row highlight drawn ON TOP
+// had nowhere left to go. The card plane keeps content legibility and leaves the
+// selection band free to do its actual job inside the popup.
+//
+// A card sits close to the page by design, so the EDGE signal rule 11 demands
+// comes from the border, not the fill: we paint the rounded border in the theme
+// accent so the float's boundary is unmistakable.
+//
+// pi 0.79 does not re-export these roles through its public API (the `.` entry
 // omits `getResolvedThemeColors` and the live `theme` singleton). It DOES publish
 // the live `Theme` instance on a process-global symbol once `initTheme()` has run
 // — the same hook pi's own SDK reads (see broker.ts `ctx.ui.theme`). We read it
@@ -26,43 +40,46 @@ function liveTheme() {
     const t = globalThis[THEME_SYMBOL];
     return (t ?? undefined);
 }
-/** The SGR escape that turns ON the distinct-surface background (theme
- *  `selectedBg`), e.g. `\x1b[48;2;58;58;74m`. Pair with `\x1b[49m` to reset just
+/** The SGR escape that turns ON the distinct-surface background (the theme's
+ *  card plane), e.g. `\x1b[48;2;52;53;65m`. Pair with `\x1b[49m` to reset just
  *  the background. Throws if no process has initialized the theme — callers on a
  *  render path (the attach overlay) always have, by construction. */
 export function surfaceBgAnsi() {
     const t = liveTheme();
     if (t === undefined)
         throw new Error('surfaceBgAnsi: pi theme not initialized in this process');
-    return t.getBgAnsi('selectedBg');
+    return t.getBgAnsi('userMessageBg');
 }
-/** The distinct-surface background as a tmux colour token (`#rrggbb` on a
- *  truecolor theme, `colourN` on a 256-colour theme), or undefined when the theme
- *  is not yet loaded in this process OR defines no selection background. tmux
- *  cannot read pi's theme, so we translate the SGR pi resolved for us. */
-function surfaceBgTmux() {
-    const t = liveTheme();
-    if (t === undefined)
-        return undefined;
-    const ansi = t.getBgAnsi('selectedBg');
-    const tc = /48;2;(\d+);(\d+);(\d+)/.exec(ansi);
+/** An SGR colour parameter (`48;2;r;g;b` or `38;5;n`) as a tmux colour token —
+ *  `#rrggbb` on a truecolor theme, `colourN` on a 256-colour one. tmux cannot
+ *  read pi's theme, so we translate the SGR pi already resolved for us.
+ *  undefined when the role is empty (the SGR is a bare default-colour reset). */
+function tmuxColor(ansi) {
+    const tc = /[34]8;2;(\d+);(\d+);(\d+)/.exec(ansi);
     if (tc !== null) {
         const hex = (n) => Number(n).toString(16).padStart(2, '0');
         return `#${hex(tc[1])}${hex(tc[2])}${hex(tc[3])}`;
     }
-    const c256 = /48;5;(\d+)/.exec(ansi);
+    const c256 = /[34]8;5;(\d+)/.exec(ansi);
     if (c256 !== null)
         return `colour${c256[1]}`;
-    return undefined; // empty/default selectedBg → nothing distinct to paint
+    return undefined;
 }
-/** tmux flags that frame a `display-menu` / `display-popup` on the distinct
- *  surface background — a rounded border + the surface bg on the body and border.
+/** tmux flags that frame a `display-menu` / `display-popup` as a distinct
+ *  surface — a rounded border in the theme accent around a body painted with the
+ *  theme's card plane. The accent border is what carries the "you are somewhere
+ *  else" signal, because a card sits close to the page by design.
  *  Empty when the theme is unavailable in this process (chrome stays default; the
  *  attach viewer re-installs the menu with these once it has themed). One knob:
  *  every crtr tmux float shares this single definition. */
 export function surfaceTmuxStyleArgs() {
-    const bg = surfaceBgTmux();
+    const t = liveTheme();
+    if (t === undefined)
+        return [];
+    const bg = tmuxColor(t.getBgAnsi('userMessageBg'));
     if (bg === undefined)
         return [];
-    return ['-b', 'rounded', '-s', `bg=${bg}`, '-S', `bg=${bg}`];
+    const accent = tmuxColor(t.getFgAnsi('accent'));
+    const border = accent === undefined ? `bg=${bg}` : `fg=${accent},bg=${bg}`;
+    return ['-b', 'rounded', '-s', `bg=${bg}`, '-S', border];
 }

package/dist/core/tui/draw.d.ts

@@ -1,3 +1,5 @@
+export declare const META_FG = "38;5;246";
+export declare const RECESSIVE_FG = "38;5;243";
 export interface Size {
     cols: number;
     rows: number;

package/dist/core/tui/draw.js

@@ -22,6 +22,21 @@ const REVERSE = `${ESC}7m`;
 const DIM = `${ESC}2m`;
 const BOLD = `${ESC}1m`;
 const ITALIC = `${ESC}3m`;
+// ── The recessive text ramp ────────────────────────────────────────────
+//
+// Two explicit greys for text that must sit BEHIND the primary content without
+// disappearing into it. Use these instead of the two things that look equivalent
+// and are not:
+//
+//   - basic-16 bright-black (`90`) resolves against the TERMINAL's palette, which
+//     a dark theme routinely sets within a hair of its own background;
+//   - SGR DIM (`2`) is a multiplier, so stacking it on an already-dark grey lands
+//     at mud — and stacking it on THESE would undo the contrast they encode.
+//
+// Never combine either with these. Ratios below are against the two planes a
+// raw-ANSI view can render on: a bare dark terminal and a themed popup card.
+export const META_FG = '38;5;246'; // 4.3–4.9:1 — metadata you actively scan
+export const RECESSIVE_FG = '38;5;243'; // 2.9–3.3:1 — deliberately behind, still read
 /** An SGR fg/bg parameter is digits and semicolons only (e.g. '32', '1;36', '236').
  *  Guards styleSpan against a non-numeric value (a color name) producing a broken
  *  escape sequence. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.273",
+  "version": "0.3.275",
   "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.275",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.273",
+      "version": "0.3.275",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {