fix(native): trace web steps without widening defaults

Author: dwgx

.env.example

@@ -53,6 +53,10 @@ LS_PORT=42100
 # Also prewarm/probe LS when adding accounts from Dashboard/batch/OAuth.
 # Default off so bulk account import cannot spawn many heavy LSPs at once.
 # LS_PREWARM_ON_ACCOUNT_ADD=0
+# Background credit/token refresh skips accounts currently serving chat,
+# account maintenance, or LS maintenance by default. Set 0 only if you want
+# scheduled maintenance to run even when an account is busy.
+# WINDSURFAPI_BACKGROUND_MAINTENANCE_SKIP_BUSY=1
 
 # Native Cascade tool bridge. Default off because Cascade executes native
 # Read/Bash-style tools in the remote Windsurf workspace, while most clients

docs/native-bridge-protocol-notes.md

@@ -8,8 +8,9 @@ is a default production enablement decision.
 Default production canary scope is intentionally limited to
 `Bash` / `shell_command` / `run_command`.
 
-`Read`, `Grep`, and `Glob` stay in `TOOL_MAP` for protocol matrix testing, but
-they are not in the default native bridge tool allowlist. To test them, set
+`Read`, `Grep`, `Glob`, `WebSearch`, and `WebFetch` stay in `TOOL_MAP` for
+protocol matrix testing, but they are not in the default native bridge tool
+allowlist. To test them, set
 `WINDSURFAPI_NATIVE_TOOL_BRIDGE_TOOLS=Read,Bash,Grep,Glob` or a narrower list
 for a gated account/API key/model. Do not treat successful protobuf
 encode/decode round-trips as production readiness.
@@ -27,6 +28,13 @@ encode/decode round-trips as production readiness.
 
 Confirmed from LS binary protobuf struct tags and runtime trace.
 
+Not confirmed yet:
+
+- `search_web` tool-config submessage field.
+- `read_url_content` tool-config submessage field.
+- Exact web result/document payload shape beyond the summary field currently
+  surfaced in trajectory steps.
+
 `FindToolConfig`:
 
 - `max_find_results` = field `1`
@@ -69,6 +77,15 @@ show `type=14` with payload on `field=19`, and `type=15` with `field=20`
 planner response data. Keep parsing based on actual oneof/message fields and
 trace unknown message-field children before promoting a new mapping.
 
+Trajectory parsing now recognizes the web step oneofs observed so far:
+
+- `read_url_content` = field `40`, body `{ url=1, summary=5 }`
+- `search_web` = field `42`, body `{ query=1, domain=3, summary=5 }`
+
+This is trace visibility, not a production enablement decision. The bridge can
+decode these steps when Cascade emits them, but WebSearch/WebFetch still need
+gated live smoke before they can join the default native bridge allowlist.
+
 ## Experiment Hooks
 
 `WINDSURFAPI_NATIVE_TOOL_BRIDGE_CONFIG_RAW` can inject exact protobuf bytes
@@ -81,6 +98,8 @@ read_file:<hex>;grep_v2:base64:<base64>;find:<hex>;list_dir:<hex>
 The hook is default-off and exists only for matrix testing. Smoke must still
 require native source plus argument validation; a raw subconfig that merely
 causes natural-language or degraded `pattern:"*"` output is not a success.
+There is intentionally no `search_web` / `read_url_content` raw-config alias
+until the tool-config field numbers are proven.
 
 ## Next Matrix
 

docs/releases/RELEASE_NOTES_2.0.124.md

@@ -0,0 +1,31 @@
+## v2.0.124 - JSON-safe identity cleanup, web-step tracing, and quieter LS maintenance
+
+- #185 follow-up: response-side Cascade identity neutralization now leaves
+  parseable JSON payloads unchanged, including fenced JSON and JSON arrays. This
+  prevents the cleanup layer from rewriting model-info JSON bodies that some
+  clients surface during upstream failures.
+- Native trajectory parsing now recognizes web tool steps emitted as
+  `read_url_content` field `40` and `search_web` field `42`, surfacing the
+  observed argument fields plus summary/result text for protocol tracing.
+- WebSearch/WebFetch remain outside the default native bridge allowlist. Their
+  trajectory steps are visible now, but the tool-config submessage fields are
+  still unproven and require gated live smoke before production enablement.
+- `scripts/native-bridge-smoke.mjs` can now explicitly run `WebSearch` and
+  `WebFetch` scenarios for protocol experiments. `NATIVE_BRIDGE_SMOKE_TOOLS=all`
+  still excludes them.
+- Background credit refresh and Firebase token refresh now skip accounts that
+  are currently serving chat, account maintenance, or LS maintenance by
+  default. Set `WINDSURFAPI_BACKGROUND_MAINTENANCE_SKIP_BUSY=0` only if you
+  want scheduled maintenance to compete with production traffic.
+- `docs/native-bridge-protocol-notes.md` and `.env.example` document the new
+  web-step tracing boundary and maintenance skip knob.
+
+Verification:
+
+- `node --check src\handlers\chat.js`
+- `node --check src\windsurf.js`
+- `node --check src\auth.js`
+- `node --check scripts\native-bridge-smoke.mjs`
+- `node --test test\identity-neutralization.test.js test\v2070-issue-fixes.test.js test\langserver-resource.test.js`
+- `node --test test\cascade-native-bridge.test.js test\native-tool-routing.test.js test\native-bridge-smoke.test.js test\identity-neutralization.test.js test\v2070-issue-fixes.test.js test\langserver-resource.test.js`
+- `node --test --test-timeout=120000 --test-force-exit test\*.test.js` passes: 1021/1021.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "windsurf-api",
-  "version": "2.0.123",
+  "version": "2.0.124",
   "description": "Windsurf to OpenAI + Anthropic compatible API proxy. Turns Windsurf's 107 AI models (Claude, GPT, Gemini, DeepSeek, Grok, Qwen, Kimi, GLM, SWE) into dual-protocol API endpoints. Zero npm deps.",
   "type": "module",
   "main": "src/index.js",

scripts/native-bridge-smoke.mjs

@@ -94,6 +94,13 @@ const TOOL = {
     pattern: { type: 'string' },
     path: { type: 'string' },
   }, ['pattern']),
+  WebSearch: fnTool('WebSearch', {
+    query: { type: 'string' },
+    domains: { type: 'array', items: { type: 'string' } },
+  }, ['query']),
+  WebFetch: fnTool('WebFetch', {
+    url: { type: 'string' },
+  }, ['url']),
 };
 
 const SCENARIOS = {
@@ -140,6 +147,24 @@ const SCENARIOS = {
     choice: null,
     prompt: `Choose exactly one appropriate tool from Read, Bash, Grep, Glob to inspect ${smokeFile} for ${marker}. Do not answer in prose.`,
   },
+  WebSearch: {
+    tools: [TOOL.WebSearch],
+    choice: 'WebSearch',
+    prompt: `Use the WebSearch tool exactly once with query "WindsurfAPI native bridge ${marker}". Do not answer in prose.`,
+    expectArgs: `query containing ${marker}`,
+    validateArgs(args) {
+      return String(args.query || '').includes(marker);
+    },
+  },
+  WebFetch: {
+    tools: [TOOL.WebFetch],
+    choice: 'WebFetch',
+    prompt: `Use the WebFetch tool exactly once with url https://example.com/. Marker: ${marker}. Do not answer in prose.`,
+    expectArgs: 'url exactly https://example.com/',
+    validateArgs(args) {
+      return String(args.url || '').trim() === 'https://example.com/';
+    },
+  },
 };
 
 function expandScenarios(names) {

src/auth.js

@@ -52,6 +52,17 @@ function isAccountBusyForProbe(account) {
   return accountInflight(account) > 0 || accountMaintenance(account) > 0 || accountLsMaintenance(account) > 0;
 }
 
+function maintenanceBusyReason(account) {
+  if (accountInflight(account) > 0) return 'account_inflight';
+  if (accountMaintenance(account) > 0) return 'account_maintenance';
+  if (accountLsMaintenance(account) > 0) return 'ls_maintenance';
+  return '';
+}
+
+function shouldSkipBusyBackgroundMaintenance() {
+  return process.env.WINDSURFAPI_BACKGROUND_MAINTENANCE_SKIP_BUSY !== '0';
+}
+
 function isAccountInMaintenance(account) {
   return accountMaintenance(account) > 0 || accountLsMaintenance(account) > 0;
 }
@@ -1400,10 +1411,17 @@ export async function refreshCredits(id) {
   }
 }
 
-export async function refreshAllCredits() {
+export async function refreshAllCredits({ skipBusy = false } = {}) {
   const results = [];
   for (const a of accounts) {
     if (a.status !== 'active') continue;
+    if (skipBusy) {
+      const busyReason = maintenanceBusyReason(a);
+      if (busyReason) {
+        results.push({ id: a.id, email: a.email, ok: false, skipped: true, reason: busyReason });
+        continue;
+      }
+    }
     const r = await refreshCredits(a.id);
     results.push({ id: a.id, email: a.email, ok: r.ok, error: r.error });
   }
@@ -1931,10 +1949,17 @@ export function emitNoAuthWarnings(bindHost = '0.0.0.0') {
  * Refresh Firebase tokens for all accounts that have a stored refreshToken.
  * Re-registers with Codeium to get a fresh API key and updates the account.
  */
-async function refreshAllFirebaseTokens() {
+async function refreshAllFirebaseTokens({ skipBusy = false } = {}) {
   const { refreshFirebaseToken, reRegisterWithCodeium } = await import('./dashboard/windsurf-login.js');
   for (const a of accounts) {
     if (a.status !== 'active' || !a.refreshToken) continue;
+    if (skipBusy) {
+      const busyReason = maintenanceBusyReason(a);
+      if (busyReason) {
+        log.debug(`Firebase refresh ${a.id} skipped: ${busyReason}`);
+        continue;
+      }
+    }
     try {
       const proxy = getEffectiveProxy(a.id) || null;
       const { idToken, refreshToken: newRefresh } = await refreshFirebaseToken(a.refreshToken, proxy);
@@ -2002,9 +2027,10 @@ export async function initAuth() {
   // Periodic credit refresh (every 15 min). First run is fire-and-forget so
   // startup isn't blocked by cloud round-trips.
   const CREDIT_INTERVAL = 15 * 60 * 1000;
-  refreshAllCredits().catch(e => log.warn(`Initial credit refresh: ${e.message}`));
+  const skipBusyMaintenance = shouldSkipBusyBackgroundMaintenance();
+  refreshAllCredits({ skipBusy: skipBusyMaintenance }).catch(e => log.warn(`Initial credit refresh: ${e.message}`));
   setInterval(() => {
-    refreshAllCredits().catch(e => log.warn(`Scheduled credit refresh: ${e.message}`));
+    refreshAllCredits({ skipBusy: skipBusyMaintenance }).catch(e => log.warn(`Scheduled credit refresh: ${e.message}`));
   }, CREDIT_INTERVAL).unref?.();
 
   // Fetch live model catalog from cloud and merge into hardcoded catalog.
@@ -2014,9 +2040,9 @@ export async function initAuth() {
   // Periodic Firebase token refresh (every 50 min). Firebase ID tokens expire
   // after 60 min; refreshing at 50 keeps a comfortable margin.
   const TOKEN_REFRESH_INTERVAL = 50 * 60 * 1000;
-  refreshAllFirebaseTokens().catch(e => log.warn(`Initial token refresh: ${e.message}`));
+  refreshAllFirebaseTokens({ skipBusy: skipBusyMaintenance }).catch(e => log.warn(`Initial token refresh: ${e.message}`));
   setInterval(() => {
-    refreshAllFirebaseTokens().catch(e => log.warn(`Scheduled token refresh: ${e.message}`));
+    refreshAllFirebaseTokens({ skipBusy: skipBusyMaintenance }).catch(e => log.warn(`Scheduled token refresh: ${e.message}`));
   }, TOKEN_REFRESH_INTERVAL).unref?.();
 
   // Warm up the default LS so first chat avoids spawn cost. Proxy-specific

src/handlers/chat.js

@@ -775,6 +775,7 @@ const MODEL_PROVIDERS = {
 
 export function neutralizeCascadeIdentity(text, modelName) {
   if (!text || !modelName) return text;
+  if (looksLikeJsonPayload(text)) return text;
   const provider = MODEL_PROVIDERS[Object.keys(MODEL_PROVIDERS).find(k => modelName.toLowerCase().startsWith(k)) || ''];
   if (!provider) return text;
   return text
@@ -801,6 +802,22 @@ export function neutralizeCascadeIdentity(text, modelName) {
     .replace(/\b(?:the )?Cascade(?:['’]s)? workspace\b/gi, 'the workspace');
 }
 
+function looksLikeJsonPayload(text) {
+  if (typeof text !== 'string') return false;
+  const s = text.trim();
+  if (!s) return false;
+  if ((s.startsWith('{') && s.endsWith('}')) || (s.startsWith('[') && s.endsWith(']'))) {
+    return safeJsonParse(s) !== undefined;
+  }
+  const fenced = s.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  if (!fenced) return false;
+  const inner = fenced[1].trim();
+  if (!((inner.startsWith('{') && inner.endsWith('}')) || (inner.startsWith('[') && inner.endsWith(']')))) {
+    return false;
+  }
+  return safeJsonParse(inner) !== undefined;
+}
+
 /**
  * Lift authoritative environment facts from the caller's request so they
  * can be re-emitted into the proto-level tool_calling_section override.

src/windsurf.js

@@ -1002,6 +1002,8 @@ export function parseTrajectorySteps(buf) {
     //   23  CortexStepWriteToFile        {target_file_uri=1, code_content=2*}
     //   28  CortexStepRunCommand         {command_line=23, combined_output=21, ...}
     //   34  CortexStepFind               {pattern=1, search_directory=10, ...}
+    //   40  CortexStepReadUrlContent     {url=1, summary=5}
+    //   42  CortexStepSearchWeb          {query=1, domain=3, summary=5}
     //   105 CortexStepGrepSearchV2       {pattern=2, path=3, raw_output=15, ...}
     //
     // We surface these as toolCalls entries shaped like the wrapped
@@ -1018,6 +1020,8 @@ export function parseTrajectorySteps(buf) {
       [28,  'run_command'],
       [13,  'grep_search'],
       [34,  'find'],
+      [40,  'read_url_content'],
+      [42,  'search_web'],
       [105, 'grep_search_v2'],
     ];
     for (const [fieldNum, kind] of NATIVE_STEP_FIELDS) {
@@ -1098,6 +1102,19 @@ export function parseTrajectorySteps(buf) {
             code_content: lines,
           };
           argumentsJson = JSON.stringify(args);
+        } else if (kind === 'read_url_content') {
+          const args = {
+            url: getField(body, 1, 2)?.value?.toString('utf8') || '',
+          };
+          argumentsJson = JSON.stringify(args);
+          result = getField(body, 5, 2)?.value?.toString('utf8') || '';
+        } else if (kind === 'search_web') {
+          const args = {
+            query: getField(body, 1, 2)?.value?.toString('utf8') || '',
+            domain: getField(body, 3, 2)?.value?.toString('utf8') || '',
+          };
+          argumentsJson = JSON.stringify(args);
+          result = getField(body, 5, 2)?.value?.toString('utf8') || '';
         }
       } catch {
         argumentsJson = argumentsJson || '{}';

test/identity-neutralization.test.js

@@ -84,6 +84,21 @@ describe('neutralizeCascadeIdentity', () => {
     assert.equal(neutralizeCascadeIdentity(text, model), text);
   });
 
+  it('does not rewrite parseable JSON payloads', () => {
+    const json = '{"model":"Cascade","message":"I am Cascade","provider":"Codeium"}';
+    assert.equal(neutralizeCascadeIdentity(json, model), json);
+  });
+
+  it('does not rewrite fenced JSON payloads', () => {
+    const json = '```json\n{"message":"Cascade is an AI coding assistant built by Windsurf."}\n```';
+    assert.equal(neutralizeCascadeIdentity(json, model), json);
+  });
+
+  it('does not rewrite parseable JSON arrays', () => {
+    const json = '[{"message":"I was created by Windsurf."}]';
+    assert.equal(neutralizeCascadeIdentity(json, model), json);
+  });
+
   it('returns text unchanged when modelName has no known provider mapping', () => {
     const text = 'I am Cascade.';
     assert.equal(neutralizeCascadeIdentity(text, 'mystery-model'), text);

test/langserver-resource.test.js

@@ -156,6 +156,18 @@ describe('language server resource policy', () => {
     assert.match(AUTH_JS, /probeAccount\(a\.id, \{ allowLsStart: false \}\)/);
   });
 
+  test('background account maintenance skips busy production accounts by default', () => {
+    assert.match(AUTH_JS, /function maintenanceBusyReason\(account\)/);
+    assert.match(AUTH_JS, /function shouldSkipBusyBackgroundMaintenance\(\)/);
+    assert.match(AUTH_JS, /WINDSURFAPI_BACKGROUND_MAINTENANCE_SKIP_BUSY !== '0'/);
+    assert.match(AUTH_JS, /export async function refreshAllCredits\(\{ skipBusy = false \} = \{\}\)/);
+    assert.match(AUTH_JS, /async function refreshAllFirebaseTokens\(\{ skipBusy = false \} = \{\}\)/);
+    assert.match(AUTH_JS, /const skipBusyMaintenance = shouldSkipBusyBackgroundMaintenance\(\)/);
+    assert.match(AUTH_JS, /refreshAllCredits\(\{ skipBusy: skipBusyMaintenance \}\)/);
+    assert.match(AUTH_JS, /refreshAllFirebaseTokens\(\{ skipBusy: skipBusyMaintenance \}\)/);
+    assert.match(AUTH_JS, /skipped: true, reason: busyReason/);
+  });
+
   test('predictive prewarm is admission-gated and reports structured failures', () => {
     assert.match(AUTH_JS, /const admission = getLsAdmissionForAccount\(nextAccount\.id\)/);
     assert.match(AUTH_JS, /admission\.reason !== 'already_running'/);