fix: don't waste 5 retries on schema errors

When o3 rejected the Task tool schema, users saw '503: 400 Invalid
schema for function Task' and the loop retried 5 times, each hitting
the same schema error. Total wait: ~30 seconds of pointless retries
before surfacing a suggestion.

The classifier saw '503' and marked it transient. But schema errors
are wrapped in 5xx responses and are NOT transient — they'll fail
identically every time.

Added a 'schema' error category that's checked BEFORE the generic 5xx
branch. Matches on: 'invalid schema', 'array schema missing items',
'invalid tool_use', 'invalid function', 'unsupported parameter',
'invalid request'. Sets isTransient: false and maxRetries: 0 so the
error surfaces immediately with the suggestion:

  'Tool schema rejected by this model. Try /model to switch to a more
   permissive model (e.g. sonnet), or upgrade Franklin.'

Combined with yesterday's Task schema fix + MCP sanitizer, users now
either succeed (99% case) or fail fast with actionable guidance.

Author: 1bcMax

dist/agent/error-classifier.d.ts

@@ -6,10 +6,10 @@
  * - Auth errors (401) get special handling (token refresh, not retry)
  * - EPIPE/connection reset handled as network errors (retryable)
  */
-export type AgentErrorCategory = 'rate_limit' | 'payment' | 'network' | 'timeout' | 'context_limit' | 'overloaded' | 'server' | 'auth' | 'unknown';
+export type AgentErrorCategory = 'rate_limit' | 'payment' | 'network' | 'timeout' | 'context_limit' | 'overloaded' | 'server' | 'auth' | 'schema' | 'unknown';
 export interface AgentErrorInfo {
     category: AgentErrorCategory;
-    label: 'RateLimit' | 'Payment' | 'Network' | 'Timeout' | 'Context' | 'Overloaded' | 'Server' | 'Auth' | 'Unknown';
+    label: 'RateLimit' | 'Payment' | 'Network' | 'Timeout' | 'Context' | 'Overloaded' | 'Server' | 'Auth' | 'Schema' | 'Unknown';
     isTransient: boolean;
     /** Max retries for this error type (overrides default). undefined = use default. */
     maxRetries?: number;

dist/agent/error-classifier.js

@@ -103,6 +103,24 @@ export function classifyAgentError(message) {
             suggestion: 'The model is overloaded. Try /model to switch, or wait and /retry.',
         };
     }
+    // Schema / tool-definition errors — NOT transient, retrying won't help.
+    // These can be wrapped in 5xx responses (e.g. '503: 400 Invalid schema'),
+    // so classify them BEFORE the generic server-error branch below.
+    if (includesAny(err, [
+        'invalid schema',
+        'array schema missing items',
+        'schema missing',
+        'invalid tool_use',
+        'invalid function',
+        'tool_use_id',
+        'unsupported parameter',
+        'invalid request',
+    ])) {
+        return {
+            category: 'schema', label: 'Schema', isTransient: false, maxRetries: 0,
+            suggestion: 'Tool schema rejected by this model. Try /model to switch to a more permissive model (e.g. sonnet), or upgrade Franklin.',
+        };
+    }
     if (includesAny(err, [
         '500',
         '502',

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.6.22",
+  "version": "3.6.23",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {

src/agent/error-classifier.ts

@@ -16,11 +16,12 @@ export type AgentErrorCategory =
   | 'overloaded'
   | 'server'
   | 'auth'
+  | 'schema'
   | 'unknown';
 
 export interface AgentErrorInfo {
   category: AgentErrorCategory;
-  label: 'RateLimit' | 'Payment' | 'Network' | 'Timeout' | 'Context' | 'Overloaded' | 'Server' | 'Auth' | 'Unknown';
+  label: 'RateLimit' | 'Payment' | 'Network' | 'Timeout' | 'Context' | 'Overloaded' | 'Server' | 'Auth' | 'Schema' | 'Unknown';
   isTransient: boolean;
   /** Max retries for this error type (overrides default). undefined = use default. */
   maxRetries?: number;
@@ -134,6 +135,25 @@ export function classifyAgentError(message: string): AgentErrorInfo {
     };
   }
 
+  // Schema / tool-definition errors — NOT transient, retrying won't help.
+  // These can be wrapped in 5xx responses (e.g. '503: 400 Invalid schema'),
+  // so classify them BEFORE the generic server-error branch below.
+  if (includesAny(err, [
+    'invalid schema',
+    'array schema missing items',
+    'schema missing',
+    'invalid tool_use',
+    'invalid function',
+    'tool_use_id',
+    'unsupported parameter',
+    'invalid request',
+  ])) {
+    return {
+      category: 'schema', label: 'Schema', isTransient: false, maxRetries: 0,
+      suggestion: 'Tool schema rejected by this model. Try /model to switch to a more permissive model (e.g. sonnet), or upgrade Franklin.',
+    };
+  }
+
   if (includesAny(err, [
     '500',
     '502',