@illuma-ai/agents 1.3.0 → 1.3.1

package/dist/esm/main.mjs

@@ -60,6 +60,7 @@ export { buildMultiDocHintContent, buildPostPruneNote, detectDocuments, hasTaskT
 export { ToolDiscoveryCache } from './utils/toolDiscoveryCache.mjs';
 export { applyCalibration, createPruneCalibration, updatePruneCalibration } from './utils/pruneCalibration.mjs';
 export { FILE_MANIFEST_PREFIX, buildFileManifestBlock } from './utils/fileManifest.mjs';
+export { extractErrorMessage, isContextOverflowError, isLikelyContextOverflowError } from './utils/errors.mjs';
 export { CustomOpenAIClient } from './llm/openai/index.mjs';
 export { ChatOpenRouter } from './llm/openrouter/index.mjs';
 export { getChatModelClass, llmProviders } from './llm/providers.mjs';

package/dist/esm/main.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"main.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"main.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/utils/errors.mjs

@@ -0,0 +1,109 @@
+/**
+ * Context-overflow error detection helpers.
+ *
+ * Provider error messages vary — Anthropic returns "prompt is too long",
+ * OpenAI returns "context_length_exceeded", Bedrock returns "Input is too
+ * long", Google returns a size-limit phrase. This module centralises the
+ * phrase list so the agent graph's emergency-prune retry can classify
+ * errors consistently instead of duplicating inline substring matches at
+ * each call site.
+ *
+ * The strict check (`isContextOverflowError`) matches only known phrases.
+ * The loose check (`isLikelyContextOverflowError`) also matches a heuristic
+ * regex for providers we haven't explicitly catalogued. Both filter out
+ * false positives (rate-limit, auth, quota, billing) that might otherwise
+ * trigger an unnecessary prune retry.
+ */
+const CONTEXT_OVERFLOW_PHRASES = [
+    'request_too_large',
+    'context length exceeded',
+    'maximum context length',
+    'prompt is too long',
+    'exceeds model context window',
+    'exceeds the model',
+    'too large for model',
+    'context_length_exceeded',
+    'max_tokens',
+    'token limit',
+    'input too long',
+    'input is too long',
+    'payload too large',
+    'content_too_large',
+];
+const CONTEXT_OVERFLOW_HINT_RE = /413|too large|too long|context.*exceed|exceed.*context|token.*limit|limit.*token|prompt.*size|size.*limit|maximum.*length|length.*maximum/i;
+const FALSE_POSITIVE_RE = /rate.?limit|too many requests|quota|billing|auth|permission|forbidden/i;
+/**
+ * Extracts a human-readable error message from an unknown error value.
+ * Walks common shapes: strings, Error instances, `{ message }`,
+ * `{ error: string }`, `{ error: { message } }`. Falls back to
+ * JSON.stringify or String() so callers never have to null-check.
+ */
+function extractErrorMessage(error) {
+    if (error == null) {
+        return '';
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'object') {
+        const record = error;
+        if (typeof record.message === 'string') {
+            return record.message;
+        }
+        if (typeof record.error === 'string') {
+            return record.error;
+        }
+        if (typeof record.error === 'object' &&
+            record.error != null &&
+            typeof record.error.message === 'string') {
+            return record.error.message;
+        }
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+/**
+ * Strict check: returns true only for known, unambiguous context-overflow
+ * phrases. Use when the recovery action is expensive (full prune + retry)
+ * and false positives are undesirable.
+ */
+function isContextOverflowError(errorMessage) {
+    if (!errorMessage) {
+        return false;
+    }
+    const lower = errorMessage.toLowerCase();
+    if (FALSE_POSITIVE_RE.test(lower)) {
+        return false;
+    }
+    return CONTEXT_OVERFLOW_PHRASES.some((phrase) => lower.includes(phrase));
+}
+/**
+ * Loose check: returns true for known phrases OR heuristic regex matches.
+ * Preferred by the graph's emergency-prune retry because the cost of a
+ * false positive is one extra retry with a smaller context, while the
+ * cost of a false negative is an opaque provider failure surfaced to
+ * the user.
+ */
+function isLikelyContextOverflowError(errorMessage) {
+    if (!errorMessage) {
+        return false;
+    }
+    if (isContextOverflowError(errorMessage)) {
+        return true;
+    }
+    const lower = errorMessage.toLowerCase();
+    if (FALSE_POSITIVE_RE.test(lower)) {
+        return false;
+    }
+    return CONTEXT_OVERFLOW_HINT_RE.test(lower);
+}
+
+export { extractErrorMessage, isContextOverflowError, isLikelyContextOverflowError };
+//# sourceMappingURL=errors.mjs.map

package/dist/esm/utils/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","sources":["../../../src/utils/errors.ts"],"sourcesContent":["/**\n * Context-overflow error detection helpers.\n *\n * Provider error messages vary — Anthropic returns \"prompt is too long\",\n * OpenAI returns \"context_length_exceeded\", Bedrock returns \"Input is too\n * long\", Google returns a size-limit phrase. This module centralises the\n * phrase list so the agent graph's emergency-prune retry can classify\n * errors consistently instead of duplicating inline substring matches at\n * each call site.\n *\n * The strict check (`isContextOverflowError`) matches only known phrases.\n * The loose check (`isLikelyContextOverflowError`) also matches a heuristic\n * regex for providers we haven't explicitly catalogued. Both filter out\n * false positives (rate-limit, auth, quota, billing) that might otherwise\n * trigger an unnecessary prune retry.\n */\n\nconst CONTEXT_OVERFLOW_PHRASES = [\n  'request_too_large',\n  'context length exceeded',\n  'maximum context length',\n  'prompt is too long',\n  'exceeds model context window',\n  'exceeds the model',\n  'too large for model',\n  'context_length_exceeded',\n  'max_tokens',\n  'token limit',\n  'input too long',\n  'input is too long',\n  'payload too large',\n  'content_too_large',\n] as const;\n\nconst CONTEXT_OVERFLOW_HINT_RE =\n  /413|too large|too long|context.*exceed|exceed.*context|token.*limit|limit.*token|prompt.*size|size.*limit|maximum.*length|length.*maximum/i;\n\nconst FALSE_POSITIVE_RE =\n  /rate.?limit|too many requests|quota|billing|auth|permission|forbidden/i;\n\n/**\n * Extracts a human-readable error message from an unknown error value.\n * Walks common shapes: strings, Error instances, `{ message }`,\n * `{ error: string }`, `{ error: { message } }`. Falls back to\n * JSON.stringify or String() so callers never have to null-check.\n */\nexport function extractErrorMessage(error: unknown): string {\n  if (error == null) {\n    return '';\n  }\n  if (typeof error === 'string') {\n    return error;\n  }\n  if (error instanceof Error) {\n    return error.message;\n  }\n  if (typeof error === 'object') {\n    const record = error as Record<string, unknown>;\n    if (typeof record.message === 'string') {\n      return record.message;\n    }\n    if (typeof record.error === 'string') {\n      return record.error;\n    }\n    if (\n      typeof record.error === 'object' &&\n      record.error != null &&\n      typeof (record.error as Record<string, unknown>).message === 'string'\n    ) {\n      return (record.error as Record<string, unknown>).message as string;\n    }\n  }\n  try {\n    return JSON.stringify(error);\n  } catch {\n    return String(error);\n  }\n}\n\n/**\n * Strict check: returns true only for known, unambiguous context-overflow\n * phrases. Use when the recovery action is expensive (full prune + retry)\n * and false positives are undesirable.\n */\nexport function isContextOverflowError(errorMessage?: string): boolean {\n  if (!errorMessage) {\n    return false;\n  }\n  const lower = errorMessage.toLowerCase();\n  if (FALSE_POSITIVE_RE.test(lower)) {\n    return false;\n  }\n  return CONTEXT_OVERFLOW_PHRASES.some((phrase) => lower.includes(phrase));\n}\n\n/**\n * Loose check: returns true for known phrases OR heuristic regex matches.\n * Preferred by the graph's emergency-prune retry because the cost of a\n * false positive is one extra retry with a smaller context, while the\n * cost of a false negative is an opaque provider failure surfaced to\n * the user.\n */\nexport function isLikelyContextOverflowError(errorMessage?: string): boolean {\n  if (!errorMessage) {\n    return false;\n  }\n  if (isContextOverflowError(errorMessage)) {\n    return true;\n  }\n  const lower = errorMessage.toLowerCase();\n  if (FALSE_POSITIVE_RE.test(lower)) {\n    return false;\n  }\n  return CONTEXT_OVERFLOW_HINT_RE.test(lower);\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;AAeG;AAEH,MAAM,wBAAwB,GAAG;IAC/B,mBAAmB;IACnB,yBAAyB;IACzB,wBAAwB;IACxB,oBAAoB;IACpB,8BAA8B;IAC9B,mBAAmB;IACnB,qBAAqB;IACrB,yBAAyB;IACzB,YAAY;IACZ,aAAa;IACb,gBAAgB;IAChB,mBAAmB;IACnB,mBAAmB;IACnB,mBAAmB;CACX;AAEV,MAAM,wBAAwB,GAC5B,4IAA4I;AAE9I,MAAM,iBAAiB,GACrB,wEAAwE;AAE1E;;;;;AAKG;AACG,SAAU,mBAAmB,CAAC,KAAc,EAAA;AAChD,IAAA,IAAI,KAAK,IAAI,IAAI,EAAE;AACjB,QAAA,OAAO,EAAE;IACX;AACA,IAAA,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;AAC7B,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI,KAAK,YAAY,KAAK,EAAE;QAC1B,OAAO,KAAK,CAAC,OAAO;IACtB;AACA,IAAA,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;QAC7B,MAAM,MAAM,GAAG,KAAgC;AAC/C,QAAA,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE;YACtC,OAAO,MAAM,CAAC,OAAO;QACvB;AACA,QAAA,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE;YACpC,OAAO,MAAM,CAAC,KAAK;QACrB;AACA,QAAA,IACE,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ;YAChC,MAAM,CAAC,KAAK,IAAI,IAAI;YACpB,OAAQ,MAAM,CAAC,KAAiC,CAAC,OAAO,KAAK,QAAQ,EACrE;AACA,YAAA,OAAQ,MAAM,CAAC,KAAiC,CAAC,OAAiB;QACpE;IACF;AACA,IAAA,IAAI;AACF,QAAA,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;IAC9B;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB;AACF;AAEA;;;;AAIG;AACG,SAAU,sBAAsB,CAAC,YAAqB,EAAA;IAC1D,IAAI,CAAC,YAAY,EAAE;AACjB,QAAA,OAAO,KAAK;IACd;AACA,IAAA,MAAM,KAAK,GAAG,YAAY,CAAC,WAAW,EAAE;AACxC,IAAA,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;AACjC,QAAA,OAAO,KAAK;IACd;AACA,IAAA,OAAO,wBAAwB,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC1E;AAEA;;;;;;AAMG;AACG,SAAU,4BAA4B,CAAC,YAAqB,EAAA;IAChE,IAAI,CAAC,YAAY,EAAE;AACjB,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI,sBAAsB,CAAC,YAAY,CAAC,EAAE;AACxC,QAAA,OAAO,IAAI;IACb;AACA,IAAA,MAAM,KAAK,GAAG,YAAY,CAAC,WAAW,EAAE;AACxC,IAAA,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;AACjC,QAAA,OAAO,KAAK;IACd;AACA,IAAA,OAAO,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC;AAC7C;;;;"}

package/dist/types/utils/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Context-overflow error detection helpers.
+ *
+ * Provider error messages vary — Anthropic returns "prompt is too long",
+ * OpenAI returns "context_length_exceeded", Bedrock returns "Input is too
+ * long", Google returns a size-limit phrase. This module centralises the
+ * phrase list so the agent graph's emergency-prune retry can classify
+ * errors consistently instead of duplicating inline substring matches at
+ * each call site.
+ *
+ * The strict check (`isContextOverflowError`) matches only known phrases.
+ * The loose check (`isLikelyContextOverflowError`) also matches a heuristic
+ * regex for providers we haven't explicitly catalogued. Both filter out
+ * false positives (rate-limit, auth, quota, billing) that might otherwise
+ * trigger an unnecessary prune retry.
+ */
+/**
+ * Extracts a human-readable error message from an unknown error value.
+ * Walks common shapes: strings, Error instances, `{ message }`,
+ * `{ error: string }`, `{ error: { message } }`. Falls back to
+ * JSON.stringify or String() so callers never have to null-check.
+ */
+export declare function extractErrorMessage(error: unknown): string;
+/**
+ * Strict check: returns true only for known, unambiguous context-overflow
+ * phrases. Use when the recovery action is expensive (full prune + retry)
+ * and false positives are undesirable.
+ */
+export declare function isContextOverflowError(errorMessage?: string): boolean;
+/**
+ * Loose check: returns true for known phrases OR heuristic regex matches.
+ * Preferred by the graph's emergency-prune retry because the cost of a
+ * false positive is one extra retry with a smaller context, while the
+ * cost of a false negative is an opaque provider failure surfaced to
+ * the user.
+ */
+export declare function isLikelyContextOverflowError(errorMessage?: string): boolean;

package/dist/types/utils/index.d.ts

@@ -12,3 +12,4 @@ export * from './contextPressure';
 export * from './toolDiscoveryCache';
 export * from './pruneCalibration';
 export * from './fileManifest';
+export * from './errors';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/graphs/Graph.ts

@@ -82,6 +82,7 @@ import { safeDispatchCustomEvent } from '@/utils/events';
 import { mlog, mwarn } from '@/utils/logging';
 import { normalizeMessageToolCalls } from '@/utils/toolCallNormalization';
 import { isTruncationReason } from '@/utils/finishReasons';
+import { isLikelyContextOverflowError } from '@/utils/errors';
 import {
   detectDocuments,
   shouldInjectMultiDocHint,
@@ -2148,15 +2149,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           config
         );
       } catch (primaryError) {
-        // Check if this is a "input too long" error from Bedrock/Anthropic
-        const errorMessage = (primaryError as Error).message.toLowerCase();
-        const isInputTooLongError =
-          errorMessage.includes('too long') ||
-          errorMessage.includes('input is too long') ||
-          errorMessage.includes('context length') ||
-          errorMessage.includes('maximum context') ||
-          errorMessage.includes('validationexception') ||
-          errorMessage.includes('prompt is too long');
+        const errorMessage = (primaryError as Error).message;
+        const isInputTooLongError = isLikelyContextOverflowError(errorMessage);
 
         // Log when we detect the error
         if (isInputTooLongError) {
@@ -2298,11 +2292,8 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
                 `[Graph] ✅ Retry successful at ${reductionFactor * 100}% with ${reducedMessages.length} messages (reduced from ${finalMessages.length})`
               );
             } catch (retryError) {
-              const retryErrorMsg = (retryError as Error).message.toLowerCase();
-              const stillTooLong =
-                retryErrorMsg.includes('too long') ||
-                retryErrorMsg.includes('context length') ||
-                retryErrorMsg.includes('validationexception');
+              const retryErrorMsg = (retryError as Error).message;
+              const stillTooLong = isLikelyContextOverflowError(retryErrorMsg);
 
               if (stillTooLong && reductionFactor > 0.1) {
                 mwarn(

package/src/utils/__tests__/errors.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Unit tests for context-overflow error classification.
+ *
+ * The graph's emergency-prune retry relies on these helpers to decide
+ * whether a provider failure warrants a truncated retry. False positives
+ * cost one extra retry; false negatives surface an opaque failure to the
+ * user. Both are cheaper than the previous inline substring matching,
+ * which missed phrases like "request_too_large" (Anthropic 429-adjacent)
+ * and could falsely trigger on rate-limit errors mentioning "too many".
+ */
+import {
+  extractErrorMessage,
+  isContextOverflowError,
+  isLikelyContextOverflowError,
+} from '../errors';
+
+describe('extractErrorMessage', () => {
+  it('returns empty string for null/undefined', () => {
+    expect(extractErrorMessage(null)).toBe('');
+    expect(extractErrorMessage(undefined)).toBe('');
+  });
+
+  it('returns the string directly', () => {
+    expect(extractErrorMessage('something broke')).toBe('something broke');
+  });
+
+  it('reads Error.message', () => {
+    expect(extractErrorMessage(new Error('boom'))).toBe('boom');
+  });
+
+  it('reads plain-object message/error fields', () => {
+    expect(extractErrorMessage({ message: 'm' })).toBe('m');
+    expect(extractErrorMessage({ error: 'e' })).toBe('e');
+    expect(extractErrorMessage({ error: { message: 'nested' } })).toBe(
+      'nested'
+    );
+  });
+
+  it('falls back to JSON stringify for unknown shapes', () => {
+    expect(extractErrorMessage({ status: 500 })).toBe('{"status":500}');
+  });
+});
+
+describe('isContextOverflowError (strict)', () => {
+  it('returns false for empty input', () => {
+    expect(isContextOverflowError()).toBe(false);
+    expect(isContextOverflowError('')).toBe(false);
+  });
+
+  it('matches Anthropic prompt-too-long', () => {
+    expect(
+      isContextOverflowError('prompt is too long: 250000 tokens > 200000')
+    ).toBe(true);
+  });
+
+  it('matches OpenAI context_length_exceeded', () => {
+    expect(
+      isContextOverflowError(
+        "This model's maximum context length is 128000 tokens. context_length_exceeded"
+      )
+    ).toBe(true);
+  });
+
+  it('matches Bedrock input-too-long', () => {
+    expect(
+      isContextOverflowError(
+        'ValidationException: Input is too long for requested model.'
+      )
+    ).toBe(true);
+  });
+
+  it('matches request_too_large', () => {
+    expect(
+      isContextOverflowError('Error code 413: request_too_large')
+    ).toBe(true);
+  });
+
+  it('is case-insensitive', () => {
+    expect(isContextOverflowError('PROMPT IS TOO LONG')).toBe(true);
+  });
+
+  it('rejects rate-limit errors even if they mention "too many"', () => {
+    expect(
+      isContextOverflowError('429 rate_limit_exceeded: too many requests')
+    ).toBe(false);
+  });
+
+  it('rejects auth / billing errors', () => {
+    expect(isContextOverflowError('insufficient quota on billing plan')).toBe(
+      false
+    );
+    expect(isContextOverflowError('forbidden: missing permission')).toBe(false);
+  });
+
+  it('does not match loose phrases like bare "too long"', () => {
+    // Strict check should NOT fire on just "too long" — that's for the
+    // loose variant. Keeps the retry budget tight.
+    expect(isContextOverflowError('the response was too long')).toBe(false);
+  });
+});
+
+describe('isLikelyContextOverflowError (loose)', () => {
+  it('matches everything the strict check matches', () => {
+    expect(isLikelyContextOverflowError('prompt is too long')).toBe(true);
+    expect(isLikelyContextOverflowError('context_length_exceeded')).toBe(true);
+  });
+
+  it('matches heuristic regex: bare "too long"', () => {
+    expect(isLikelyContextOverflowError('response was too long')).toBe(true);
+  });
+
+  it('matches heuristic regex: 413 status code', () => {
+    expect(isLikelyContextOverflowError('HTTP 413 payload')).toBe(true);
+  });
+
+  it('matches "context ... exceed" in either order', () => {
+    expect(isLikelyContextOverflowError('your context exceeds limits')).toBe(
+      true
+    );
+    expect(isLikelyContextOverflowError('exceeds context window')).toBe(true);
+  });
+
+  it('still rejects rate-limit / auth even on loose match', () => {
+    expect(
+      isLikelyContextOverflowError('rate limit: too many requests queued')
+    ).toBe(false);
+    expect(
+      isLikelyContextOverflowError('authorization exceeds allowed quota')
+    ).toBe(false);
+  });
+
+  it('returns false for unrelated errors', () => {
+    expect(isLikelyContextOverflowError('ECONNREFUSED')).toBe(false);
+    expect(isLikelyContextOverflowError('unexpected token in JSON')).toBe(false);
+  });
+});

package/src/utils/errors.ts

@@ -0,0 +1,115 @@
+/**
+ * Context-overflow error detection helpers.
+ *
+ * Provider error messages vary — Anthropic returns "prompt is too long",
+ * OpenAI returns "context_length_exceeded", Bedrock returns "Input is too
+ * long", Google returns a size-limit phrase. This module centralises the
+ * phrase list so the agent graph's emergency-prune retry can classify
+ * errors consistently instead of duplicating inline substring matches at
+ * each call site.
+ *
+ * The strict check (`isContextOverflowError`) matches only known phrases.
+ * The loose check (`isLikelyContextOverflowError`) also matches a heuristic
+ * regex for providers we haven't explicitly catalogued. Both filter out
+ * false positives (rate-limit, auth, quota, billing) that might otherwise
+ * trigger an unnecessary prune retry.
+ */
+
+const CONTEXT_OVERFLOW_PHRASES = [
+  'request_too_large',
+  'context length exceeded',
+  'maximum context length',
+  'prompt is too long',
+  'exceeds model context window',
+  'exceeds the model',
+  'too large for model',
+  'context_length_exceeded',
+  'max_tokens',
+  'token limit',
+  'input too long',
+  'input is too long',
+  'payload too large',
+  'content_too_large',
+] as const;
+
+const CONTEXT_OVERFLOW_HINT_RE =
+  /413|too large|too long|context.*exceed|exceed.*context|token.*limit|limit.*token|prompt.*size|size.*limit|maximum.*length|length.*maximum/i;
+
+const FALSE_POSITIVE_RE =
+  /rate.?limit|too many requests|quota|billing|auth|permission|forbidden/i;
+
+/**
+ * Extracts a human-readable error message from an unknown error value.
+ * Walks common shapes: strings, Error instances, `{ message }`,
+ * `{ error: string }`, `{ error: { message } }`. Falls back to
+ * JSON.stringify or String() so callers never have to null-check.
+ */
+export function extractErrorMessage(error: unknown): string {
+  if (error == null) {
+    return '';
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === 'object') {
+    const record = error as Record<string, unknown>;
+    if (typeof record.message === 'string') {
+      return record.message;
+    }
+    if (typeof record.error === 'string') {
+      return record.error;
+    }
+    if (
+      typeof record.error === 'object' &&
+      record.error != null &&
+      typeof (record.error as Record<string, unknown>).message === 'string'
+    ) {
+      return (record.error as Record<string, unknown>).message as string;
+    }
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+/**
+ * Strict check: returns true only for known, unambiguous context-overflow
+ * phrases. Use when the recovery action is expensive (full prune + retry)
+ * and false positives are undesirable.
+ */
+export function isContextOverflowError(errorMessage?: string): boolean {
+  if (!errorMessage) {
+    return false;
+  }
+  const lower = errorMessage.toLowerCase();
+  if (FALSE_POSITIVE_RE.test(lower)) {
+    return false;
+  }
+  return CONTEXT_OVERFLOW_PHRASES.some((phrase) => lower.includes(phrase));
+}
+
+/**
+ * Loose check: returns true for known phrases OR heuristic regex matches.
+ * Preferred by the graph's emergency-prune retry because the cost of a
+ * false positive is one extra retry with a smaller context, while the
+ * cost of a false negative is an opaque provider failure surfaced to
+ * the user.
+ */
+export function isLikelyContextOverflowError(errorMessage?: string): boolean {
+  if (!errorMessage) {
+    return false;
+  }
+  if (isContextOverflowError(errorMessage)) {
+    return true;
+  }
+  const lower = errorMessage.toLowerCase();
+  if (FALSE_POSITIVE_RE.test(lower)) {
+    return false;
+  }
+  return CONTEXT_OVERFLOW_HINT_RE.test(lower);
+}

package/src/utils/index.ts

@@ -12,3 +12,4 @@ export * from './contextPressure';
 export * from './toolDiscoveryCache';
 export * from './pruneCalibration';
 export * from './fileManifest';
+export * from './errors';