surf-skill 2.1.0 → 2.1.1

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## v2.1.1 — Robust key rotation: Brave 422 now burns the key
+
+### Bug
+
+When a Brave key was malformed (wrong length/charset), the API returns
+HTTP **422** rather than 401. v2.1.0 classified 422 as `caller_4xx`, which
+made dispatch throw without burning the key or trying the next one. That
+violated the cross-provider fallback contract: a single bad-format key
+could short-circuit the chain instead of rotating.
+
+### Fix
+
+`src/lib/providers/brave.mjs::mapError` now classifies 422 as `auth`
+(burn key, rotate). The trade-off:
+
+- **Real malformed token** → burns the key, dispatch tries the next key
+  (or next provider if `--provider` not set). The user gets a result.
+- **Genuinely bad query param** → all keys fail with 422; surfaces as
+  `AllProvidersExhausted` with a hint, still actionable.
+
+### Verified
+
+Re-ran the 3 fallback tests with v2.1.1:
+
+- T1 same-provider rotation (tavily key #0 bad → key #1 succeeds): ✓
+- T2 cross-provider fallback (tavily/parallel both 401 → brave 200): ✓
+- T3 all keys bad incl. malformed Brave: **now burns Brave key + reports
+  AllProvidersExhausted** (instead of throwing on the 422)
+
+### Also fixed
+
+- `src/lib/dispatch.mjs::VERSION` was stuck at `1.0.0` since the initial
+  release; bumped to `2.1.1` so the `X-Client-Name` header surfaces
+  the correct CLI version to providers.
+- `SKILL.md::metadata.version` was missed in the v2.1.0 bump (still
+  showed `2.0.0`); now `2.1.1`.
+
+No breaking changes.
+
+---
+
 ## v2.1.0 — Brave Search as 3rd provider + `--mode` flag
 
 ### What's new

package/SKILL.md

@@ -4,7 +4,7 @@ description: Web search, content extraction, site crawl, URL mapping, and deep r
 license: MIT
 allowed-tools: bash
 metadata:
-  version: "2.0.0"
+  version: "2.1.1"
   requires: "node>=18; install via `npm i -g surf-skill`; keys via 'surf-skill setup' (multi-key wizard); per-project bash timeout via 'surf-skill project-config'"
 ---
 

package/bin/surf-skill.mjs

@@ -15,7 +15,7 @@ import { runProjectConfig, formatProjectConfigResult } from '../src/lib/project-
 import { providerFromRequestId } from '../src/lib/providers/index.mjs';
 import { progress, setSilent } from '../src/lib/progress.mjs';
 
-const VERSION = '2.1.0';
+const VERSION = '2.1.1';
 
 // Catch SIGTERM/SIGINT so a harness-driven kill surfaces a useful message
 // instead of dying silently. This is defense-in-depth: dispatch already

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-skill",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Multi-provider web skill (Tavily + Parallel AI + Brave Search) for AI coding agents — CLI + Node library + Anthropic Agent Skill. Auto-fallback, multi-key rotation, --mode tiers, per-project timeout config.",
   "type": "module",
   "main": "./src/index.mjs",

package/src/lib/dispatch.mjs

@@ -13,7 +13,7 @@ import { sleep } from './flags.mjs';
 import { progress } from './progress.mjs';
 
 const CACHEABLE = new Set(['search', 'extract', 'map']);
-const VERSION = '1.0.0';
+const VERSION = '2.1.1';
 
 // Detect the agent harness's bash timeout from env vars. The number is the
 // total time (ms) the harness will allow our process to live before SIGTERM.

package/src/lib/providers/brave.mjs

@@ -90,7 +90,13 @@ function mapError(status, body) {
   if (status === 401) return { kind: 'auth', statusCode: status, message: 'invalid Brave key' };
   if (status === 402) return { kind: 'auth', statusCode: status, message: msg || 'Brave: insufficient credits / billing required' };
   if (status === 403) return { kind: 'auth', statusCode: status, message: msg || 'forbidden (plan/billing)' };
-  if (status === 422) return { kind: 'caller_4xx', statusCode: status, message: msg || 'invalid params' };
+  // Brave returns 422 for several reasons: malformed token (length/charset
+  // wrong, fails BEFORE auth check), OR bad query params. We classify 422 as
+  // `auth` so the key gets burned and dispatch rotates. The trade-off: a
+  // genuinely-bad query param will fail across ALL keys and surface as
+  // AllProvidersExhausted, still actionable. A malformed token is the
+  // dominant cause in practice (real tokens hit 401 instead).
+  if (status === 422) return { kind: 'auth', statusCode: status, message: msg || 'Brave: malformed token or invalid params (key rotation will retry; if all keys fail, you likely have a bad query)' };
   if (status === 429) return { kind: 'rate_limit_429', statusCode: status, message: msg || 'Brave rate limit (50 RPS search)' };
   if (status >= 500)  return { kind: 'server_5xx', statusCode: status, message: msg || 'Brave server error' };
   if (status >= 400)  return { kind: 'caller_4xx', statusCode: status, message: msg || `HTTP ${status}` };