fix(native): add web tool protocol lab hooks

Author: dwgx

docs/native-bridge-protocol-notes.md

@@ -89,17 +89,24 @@ 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
-for native tool subconfigs:
+for native tool subconfigs or unknown top-level `CascadeToolConfig` fields:
 
 ```text
-read_file:<hex>;grep_v2:base64:<base64>;find:<hex>;list_dir:<hex>
+read_file:<hex>;grep_v2:base64:<base64>;find:<hex>;list_dir:<hex>;field42:<hex>;field40:
 ```
 
 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.
+until the tool-config field numbers are proven. Use `fieldNN:<hex>`,
+`field_NN:<hex>`, or `fNN:<hex>` only in a gated lab account.
+
+`WINDSURFAPI_NATIVE_TOOL_BRIDGE_POLL_AFTER_TOOL=1` is also lab-only. It keeps
+polling Cascade after the first `cascade_native` tool call so protobuf traces
+can capture post-tool result/document payloads. Production bridge traffic should
+leave it unset; the default behavior stops at the tool proposal so OpenAI
+clients execute the tool locally instead of the remote LS workspace doing it.
 
 ## Next Matrix
 

docs/releases/RELEASE_NOTES_2.0.125.md

@@ -0,0 +1,27 @@
+## v2.0.125 - Web tool protocol-lab hooks
+
+- Added a lab-only `WINDSURFAPI_NATIVE_TOOL_BRIDGE_POLL_AFTER_TOOL=1` switch
+  for protocol tracing. When enabled with the native bridge, Cascade polling
+  continues after the first `cascade_native` tool proposal so traces can capture
+  post-tool result payloads. The default production behavior is unchanged: stop
+  at the native tool proposal and let the OpenAI client execute the tool.
+- `WINDSURFAPI_NATIVE_TOOL_BRIDGE_CONFIG_RAW` can now inject unknown top-level
+  `CascadeToolConfig` fields with `fieldNN:<hex>`, `field_NN:<hex>`, or
+  `fNN:<hex>`. This is for WebSearch/WebFetch field-matrix canaries; field 32
+  remains reserved for the managed allowlist.
+- Proto tracing now summarizes unknown native tool-config fields and richer
+  `search_web` / `read_url_content` trajectory shapes, including nested message
+  fields that should reveal `web_documents` payload placement during real
+  smoke tests.
+- WebSearch/WebFetch are still not in the default native bridge allowlist. This
+  release only makes the gated canary measurable enough to decide the next
+  mapping safely.
+
+Verification:
+
+- `node --check src\client.js`
+- `node --check src\windsurf.js`
+- `node --check src\proto-trace.js`
+- `node --test test\client-panel-retry.test.js`
+- `node --test test\cascade-native-bridge.test.js test\proto-trace.test.js test\native-tool-routing.test.js`
+- `node --test --test-timeout=120000 --test-force-exit test\*.test.js` passes: 1025/1025.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "windsurf-api",
-  "version": "2.0.124",
+  "version": "2.0.125",
   "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",

src/client.js

@@ -852,6 +852,8 @@ export class WindsurfClient {
       const { maxWaitMs: maxWait, pollIntervalMs: pollInterval, idleGraceMs: IDLE_GRACE_MS, warmStallMs: NO_GROWTH_STALL_MS, stallRetryMinText: STALL_RETRY_MIN_TEXT } = CASCADE_TIMEOUTS;
       const startTime = Date.now();
       let endReason = 'unknown';
+      const nativeBridgePollAfterTool = nativeMode && process.env.WINDSURFAPI_NATIVE_TOOL_BRIDGE_POLL_AFTER_TOOL === '1';
+      let nativeBridgePollAfterToolLogged = false;
 
       while (Date.now() - startTime < maxWait) {
         if (aborted()) { endReason = 'aborted'; break; }
@@ -959,8 +961,14 @@ export class WindsurfClient {
             // polling immediately so the LS does not keep executing the
             // built-in tool in the remote workspace while the client waits.
             if (nativeMode && step.toolCalls.some(tc => tc.cascade_native)) {
-              endReason = 'native_tool_call';
-              break;
+              if (!nativeBridgePollAfterTool) {
+                endReason = 'native_tool_call';
+                break;
+              }
+              if (!nativeBridgePollAfterToolLogged) {
+                nativeBridgePollAfterToolLogged = true;
+                log.warn('Native bridge protocol lab is polling after a cascade-native tool call; remote LS may execute the built-in tool');
+              }
             }
           }
 

src/proto-trace.js

@@ -120,9 +120,19 @@ function summarizeNativeToolConfig(toolCfgBuf) {
   const subconfigs = [...NATIVE_TOOL_CONFIG_FIELDS.keys()]
     .map(num => summarizeNativeToolSubconfig(fields, num))
     .filter(Boolean);
+  const known = new Set([...NATIVE_TOOL_CONFIG_FIELDS.keys(), 32]);
+  const unknownFields = fields
+    .filter(f => f.wireType === 2 && !known.has(f.field))
+    .slice(0, positiveIntEnv('WINDSURFAPI_PROTO_TRACE_TOOL_CONFIG_UNKNOWN_LIMIT', 24))
+    .map(f => ({
+      field: f.field,
+      bytes: f.value.length,
+      summary: summarizeMessageChildren(f.value, 10),
+    }));
   return {
     subconfigFields: subconfigs.map(s => s.field),
     subconfigs,
+    unknownFields,
     allowlist: getAllFields(fields, 32)
       .filter(f => f.wireType === 2)
       .map(f => f.value.toString('utf8')),
@@ -232,6 +242,30 @@ function summarizeNativeStepBody(kind, bodyBuf) {
       childCount: getAllFields(f, 2).filter(x => x.wireType === 2).length,
     };
   }
+  if (kind === 'search_web') {
+    return {
+      queryBytes: stringField(f, 1).length,
+      webDocumentCount: getAllFields(f, 2).filter(x => x.wireType === 2).length,
+      domainBytes: stringField(f, 3).length,
+      summaryBytes: stringField(f, 5).length,
+      fieldNumbers: f.map(x => x.field),
+      messageFields: f
+        .filter(x => x.wireType === 2 && ![1, 3, 5].includes(x.field))
+        .slice(0, 8)
+        .map(x => ({ field: x.field, ...summarizeMessageChildren(x.value, 8) })),
+    };
+  }
+  if (kind === 'read_url_content') {
+    return {
+      urlBytes: stringField(f, 1).length,
+      summaryBytes: stringField(f, 5).length,
+      fieldNumbers: f.map(x => x.field),
+      messageFields: f
+        .filter(x => x.wireType === 2 && ![1, 5].includes(x.field))
+        .slice(0, 8)
+        .map(x => ({ field: x.field, ...summarizeMessageChildren(x.value, 8) })),
+    };
+  }
   return { fieldCount: f.length };
 }
 

src/windsurf.js

@@ -657,6 +657,9 @@ function buildNativeCascadeToolConfig(allowlist = null) {
   if (enabled.find) {
     parts.push(writeNativeToolConfigField(5, 'find', rawSubconfigs));
   }
+  for (const [field, payload] of rawSubconfigs.unknownFields) {
+    parts.push(writeBytesField(field, payload));
+  }
   // tool_allowlist (field 32, repeated string)
   for (const name of list) {
     parts.push(writeStringField(32, name));
@@ -672,22 +675,32 @@ function writeNativeToolConfigField(field, kind, rawSubconfigs) {
 
 function parseNativeToolConfigRawOverrides() {
   const raw = String(process.env.WINDSURFAPI_NATIVE_TOOL_BRIDGE_CONFIG_RAW || '').trim();
-  if (!raw) return new Map();
   const out = new Map();
+  out.unknownFields = new Map();
+  if (!raw) return out;
   for (const entry of raw.split(';')) {
     const item = entry.trim();
     if (!item) continue;
     const sep = item.indexOf(':');
     if (sep <= 0) throw new Error(`Invalid WINDSURFAPI_NATIVE_TOOL_BRIDGE_CONFIG_RAW entry: ${item}`);
     const kind = normalizeNativeToolConfigKind(item.slice(0, sep));
     const payload = decodeNativeToolConfigRawPayload(item.slice(sep + 1));
-    out.set(kind, payload);
+    if (typeof kind === 'number') out.unknownFields.set(kind, payload);
+    else out.set(kind, payload);
   }
   return out;
 }
 
 function normalizeNativeToolConfigKind(kind) {
   const key = String(kind || '').trim();
+  const fieldMatch = key.match(/^(?:field_|field|f)([1-9]\d{0,8})$/i);
+  if (fieldMatch) {
+    const n = Number(fieldMatch[1]);
+    if (!Number.isInteger(n) || n <= 0 || n > 536870911 || n === 32) {
+      throw new Error(`Invalid native tool config field override: ${key}`);
+    }
+    return n;
+  }
   const map = new Map([
     ['run_command', 'run_command'],
     ['shell_command', 'run_command'],

test/cascade-native-bridge.test.js

@@ -599,6 +599,25 @@ describe('buildSendCascadeMessageRequest — additional_steps on field 9', () =>
     }
   });
 
+  it('native tool config raw overrides can inject unknown top-level fields for matrix experiments', () => {
+    process.env.WINDSURFAPI_NATIVE_TOOL_BRIDGE_CONFIG_RAW = 'field42:0a03776562;field40:';
+    try {
+      const proto = buildSendCascadeMessageRequest('k', 'cid', 'hi', 12345, 'MODEL_TEST', 'sess', {
+        nativeMode: true,
+        nativeAllowlist: ['search_web', 'read_url_content'],
+      });
+      const top = parseFields(proto);
+      const cfg = parseFields(getField(top, 5, 2).value);
+      const planner = parseFields(getField(cfg, 1, 2).value);
+      const tc = parseFields(getField(planner, 13, 2).value);
+      assert.equal(getField(tc, 42, 2).value.toString('hex'), '0a03776562');
+      assert.equal(getField(tc, 40, 2).value.length, 0);
+      assert.deepEqual(getAllFields(tc, 32).map(f => f.value.toString('utf8')), ['search_web', 'read_url_content']);
+    } finally {
+      delete process.env.WINDSURFAPI_NATIVE_TOOL_BRIDGE_CONFIG_RAW;
+    }
+  });
+
   it('nativeMode=true can carry environment facts without tool emulation schema', () => {
     const proto = buildSendCascadeMessageRequest('k', 'cid', 'hi', 12345, 'MODEL_TEST', 'sess', {
       nativeMode: true,

test/client-panel-retry.test.js

@@ -368,4 +368,83 @@ describe('WindsurfClient cascade panel retry', () => {
       assert.equal(streamed.filter(c => c.nativeToolCall).length, 1);
     });
   });
+
+  it('native bridge protocol lab can poll after a cascade-native tool call', async () => {
+    const prevPollAfterTool = process.env.WINDSURFAPI_NATIVE_TOOL_BRIDGE_POLL_AFTER_TOOL;
+    process.env.WINDSURFAPI_NATIVE_TOOL_BRIDGE_POLL_AFTER_TOOL = '1';
+    process.env.CASCADE_POLL_INTERVAL_MS = '10';
+    process.env.CASCADE_IDLE_GRACE_MS = '1';
+    process.env.CASCADE_MAX_WAIT_MS = '700';
+    process.env.CASCADE_COLD_STALL_BASE_MS = '700';
+    process.env.CASCADE_WARM_STALL_MS = '700';
+    process.env.GRPC_PROTOCOL = 'connect';
+
+    let statusPolls = 0;
+    let stepPolls = 0;
+    const streamed = [];
+
+    try {
+      await withFakeLanguageServer((stream, headers) => {
+        const chunks = [];
+        stream.on('data', chunk => chunks.push(chunk));
+        stream.on('end', () => {
+          const path = String(headers[':path'] || '');
+          const method = path.split('/').pop();
+
+          if (method === 'StartCascade') {
+            stream.respond({ ':status': 200, 'content-type': headers['content-type'] || 'application/grpc' });
+            stream.end(responseBody(startCascadeResponse('native-cascade-lab'), headers));
+            return;
+          }
+
+          if (method === 'SendUserCascadeMessage') {
+            stream.respond({ ':status': 200, 'content-type': headers['content-type'] || 'application/grpc' });
+            stream.end(responseBody(Buffer.alloc(0), headers));
+            return;
+          }
+
+          if (method === 'GetCascadeTrajectorySteps') {
+            stepPolls++;
+            stream.respond({ ':status': 200, 'content-type': headers['content-type'] || 'application/grpc' });
+            stream.end(responseBody(runCommandStepResponse('printf LAB'), headers));
+            return;
+          }
+
+          if (method === 'GetCascadeTrajectory') {
+            statusPolls++;
+            stream.respond({ ':status': 200, 'content-type': headers['content-type'] || 'application/grpc' });
+            stream.end(responseBody(trajectoryStatusResponse(1), headers));
+            return;
+          }
+
+          if (method === 'GetCascadeTrajectoryGeneratorMetadata') {
+            stream.respond({ ':status': 200, 'content-type': headers['content-type'] || 'application/grpc' });
+            stream.end(responseBody(Buffer.alloc(0), headers));
+            return;
+          }
+
+          stream.respond({ ':status': 404 });
+          stream.end();
+        });
+      }, async (port) => {
+        const { WindsurfClient } = await import('../src/client.js');
+        const client = new WindsurfClient('test-api-key', port, 'csrf-token');
+        const chunks = await client.cascadeChat([{ role: 'user', content: 'run it' }], 0, 'claude-4.5-haiku', {
+          nativeMode: true,
+          nativeAllowlist: ['run_command'],
+          onChunk: c => streamed.push(c),
+        });
+
+        assert.ok(stepPolls > 1, 'lab mode should keep polling trajectory steps after the native tool call');
+        assert.ok(statusPolls > 0, 'lab mode should poll trajectory status instead of returning immediately');
+        assert.equal(chunks.toolCalls.length, 1);
+        assert.equal(chunks.toolCalls[0].name, 'run_command');
+        assert.match(chunks.toolCalls[0].argumentsJson, /printf LAB/);
+        assert.equal(streamed.filter(c => c.nativeToolCall).length, 1);
+      });
+    } finally {
+      if (prevPollAfterTool === undefined) delete process.env.WINDSURFAPI_NATIVE_TOOL_BRIDGE_POLL_AFTER_TOOL;
+      else process.env.WINDSURFAPI_NATIVE_TOOL_BRIDGE_POLL_AFTER_TOOL = prevPollAfterTool;
+    }
+  });
 });

test/proto-trace.test.js

@@ -5,7 +5,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { grpcFrame } from '../src/grpc.js';
-import { writeBoolField, writeMessageField, writeStringField, writeVarintField } from '../src/proto.js';
+import { writeBoolField, writeBytesField, writeMessageField, writeStringField, writeVarintField } from '../src/proto.js';
 import { buildSendCascadeMessageRequest } from '../src/windsurf.js';
 import {
   _resetProtoTraceForTests,
@@ -139,6 +139,36 @@ describe('proto trace', () => {
     assert.ok(grep.bytes > 0);
   });
 
+  it('summarizes unknown native tool config fields for web matrix experiments', () => {
+    process.env.WINDSURFAPI_PROTO_TRACE = '1';
+    const toolConfig = Buffer.concat([
+      writeMessageField(42, writeStringField(1, 'web')),
+      writeBytesField(40, Buffer.alloc(0)),
+      writeStringField(32, 'search_web'),
+      writeStringField(32, 'read_url_content'),
+    ]);
+    const planner = writeMessageField(13, toolConfig);
+    const cascadeConfig = writeMessageField(1, planner);
+    const proto = writeMessageField(5, cascadeConfig);
+
+    traceGrpcPayload({
+      port: 42100,
+      path: '/exa.language_server_pb.LanguageServerService/SendUserCascadeMessage',
+      direction: 'request',
+      body: grpcFrame(proto),
+      transport: 'grpc',
+      framed: true,
+    });
+
+    const file = join(dir, `ls-proto-${process.pid}-SendUserCascadeMessage.jsonl`);
+    const rec = JSON.parse(readFileSync(file, 'utf8').trim());
+    assert.deepEqual(rec.semantic.nativeToolConfig.allowlist, ['search_web', 'read_url_content']);
+    assert.deepEqual(rec.semantic.nativeToolConfig.subconfigFields, []);
+    assert.deepEqual(rec.semantic.nativeToolConfig.unknownFields.map(f => f.field), [42, 40]);
+    assert.deepEqual(rec.semantic.nativeToolConfig.unknownFields[0].summary.fieldNumbers, [1]);
+    assert.equal(rec.semantic.nativeToolConfig.unknownFields[1].bytes, 0);
+  });
+
   it('adds semantic GetCascadeTrajectorySteps native oneof summaries', () => {
     process.env.WINDSURFAPI_PROTO_TRACE = '1';
     const grepBody = Buffer.concat([
@@ -172,6 +202,57 @@ describe('proto trace', () => {
     assert.equal(rec.semantic.steps[0].nativeOneofs[0].body.rawOutputBytes, 'README.md\n'.length);
   });
 
+  it('summarizes web trajectory payload shapes for protocol diffing', () => {
+    process.env.WINDSURFAPI_PROTO_TRACE = '1';
+    const doc = Buffer.concat([
+      writeStringField(1, 'title'),
+      writeStringField(2, 'https://example.com/'),
+    ]);
+    const searchBody = Buffer.concat([
+      writeStringField(1, 'WindsurfAPI native bridge'),
+      writeMessageField(2, doc),
+      writeStringField(3, 'example.com'),
+      writeStringField(5, 'summary'),
+    ]);
+    const fetchBody = Buffer.concat([
+      writeStringField(1, 'https://example.com/'),
+      writeMessageField(2, doc),
+      writeStringField(5, 'body summary'),
+    ]);
+    const response = Buffer.concat([
+      writeMessageField(1, Buffer.concat([
+        writeVarintField(1, 42),
+        writeVarintField(4, 3),
+        writeMessageField(42, searchBody),
+      ])),
+      writeMessageField(1, Buffer.concat([
+        writeVarintField(1, 40),
+        writeVarintField(4, 3),
+        writeMessageField(40, fetchBody),
+      ])),
+    ]);
+    traceGrpcPayload({
+      port: 42100,
+      path: '/exa.language_server_pb.LanguageServerService/GetCascadeTrajectorySteps',
+      direction: 'response',
+      body: response,
+      transport: 'grpc',
+      framed: false,
+    });
+
+    const file = join(dir, `ls-proto-${process.pid}-GetCascadeTrajectorySteps.jsonl`);
+    const rec = JSON.parse(readFileSync(file, 'utf8').trim());
+    const search = rec.semantic.steps[0].nativeOneofs[0];
+    assert.equal(search.kind, 'search_web');
+    assert.equal(search.body.webDocumentCount, 1);
+    assert.deepEqual(search.body.fieldNumbers, [1, 2, 3, 5]);
+    assert.equal(search.body.messageFields[0].field, 2);
+    const fetch = rec.semantic.steps[1].nativeOneofs[0];
+    assert.equal(fetch.kind, 'read_url_content');
+    assert.deepEqual(fetch.body.fieldNumbers, [1, 2, 5]);
+    assert.equal(fetch.body.messageFields[0].field, 2);
+  });
+
   it('summarizes non-oneof step message fields for protocol diffing', () => {
     process.env.WINDSURFAPI_PROTO_TRACE = '1';
     const viewWrapper = Buffer.concat([