feat(native): add lab WebFetch approval probe

Author: dwgx

docs/native-bridge-protocol-notes.md

@@ -249,6 +249,24 @@ receives the `read_url_content` config but still fails before emitting the web
 oneof. The missing piece remains an LS-side web executor precondition or a
 descriptor-backed direct WebFetch/read-url API.
 
+The v2.0.134 VPS pass tested `read_url_content` alone with an explicit
+allowlist subconfig for `https://example.com/`:
+
+- `SendUserCascadeMessage` enabled the bridge decision for mapped WebFetch and
+  sent `read_url_content` in the native allowlist.
+- `GetCascadeTrajectorySteps` repeatedly returned a pending
+  `requested_interaction.read_url_content` for the target URL/origin.
+- The matching native step body had fields `[1, 7]`: URL plus
+  `autoRunDecision=8`; there was no `web_document` yet and no executor error.
+- Both streaming and non-streaming canaries timed out because the proxy did not
+  answer the official permission prompt.
+
+Updated direction: do not search for a guessed direct WebFetch endpoint first.
+The observed blocker is now the official LS permission interaction. The next
+valid canary must send `HandleCascadeUserInteraction` and then verify whether
+the same trajectory advances to `read_url_content.web_document`, an error step,
+or another requested interaction.
+
 ## Direct Web Search API
 
 `GetWebSearchResults` is confirmed independently of the LS-native tool path:
@@ -319,9 +337,25 @@ User settings that influence auto-approval:
   (`1` disabled, `2` allowlist, `3` turbo)
 
 `WINDSURFAPI_PROTO_TRACE` now summarizes `requested_interaction=56` and its
-read-url body with byte lengths and hashes only. The next valid WebFetch canary
-decision point is: did the LS emit a read-url requested interaction, a completed
-`field=40` step with `web_document`, or an error step before either?
+read-url body with byte lengths and hashes only. It also summarizes
+`HandleCascadeUserInteraction` requests, including cascade/trajectory ID hashes,
+step index, action enum, and URL/origin hashes. The next valid WebFetch canary
+decision point is: after approval, did the LS emit a completed `field=40` step
+with `web_document`, an error step, or another requested interaction?
+
+v2.0.135 adds a lab-only auto-approval hook for this canary:
+
+```text
+WINDSURFAPI_NATIVE_TOOL_BRIDGE_WEBFETCH_AUTO_APPROVE=1
+WINDSURFAPI_NATIVE_TOOL_BRIDGE_WEBFETCH_AUTO_APPROVE_ORIGINS=https://example.com
+```
+
+The hook is still behind normal native bridge gating and only runs when
+`read_url_content` is in the native allowlist. It is not a production default.
+Pending `read_url_content` steps that only contain the permission request are
+not surfaced as completed native tool calls; the proxy waits for an actual
+`web_document` or legacy result before returning WebFetch content to the
+client. The origin list must explicitly match the requested origin or URL.
 
 ## Experiment Hooks
 

docs/releases/RELEASE_NOTES_2.0.135.md

@@ -0,0 +1,32 @@
+# v2.0.135
+
+- Added a lab-only WebFetch permission POC. When
+  `WINDSURFAPI_NATIVE_TOOL_BRIDGE_WEBFETCH_AUTO_APPROVE=1` and
+  `WINDSURFAPI_NATIVE_TOOL_BRIDGE_WEBFETCH_AUTO_APPROVE_ORIGINS` explicitly
+  matches the requested origin or URL, the Cascade polling loop responds to
+  `requested_interaction.read_url_content` through
+  `HandleCascadeUserInteraction` with `ALLOW_ONCE`.
+- Added protobuf builders/parsers for the official interaction path:
+  `GetCascadeTrajectoryResponse.trajectory.trajectory_id`,
+  `CortexTrajectoryStep.requested_interaction`, and
+  `HandleCascadeUserInteractionRequest`.
+- Added a redacted proto trace summary for
+  `HandleCascadeUserInteraction` requests so canaries can prove which
+  trajectory/step/action was approved without logging raw URLs or IDs.
+- Pending WebFetch permission steps are no longer surfaced as completed native
+  tool calls. The proxy waits for a real `web_document` or legacy result, which
+  prevents an empty pending step from deduping away the later completed fetch.
+- WebFetch remains outside the default native bridge allowlist. This release
+  only gives protocol canaries a safe way to test whether LS can continue from
+  the official permission prompt to a completed `read_url_content.web_document`
+  step.
+
+Verification:
+
+- `node --check src/client.js`
+- `node --check src/windsurf.js`
+- `node --check src/proto-trace.js`
+- `node --test test/proto-trace.test.js`
+- `node --test test/v2070-issue-fixes.test.js`
+- `node --test test/client-panel-retry.test.js`
+- `npm test`

package.json

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

@@ -23,7 +23,8 @@ import {
   buildUpdatePanelStateWithUserStatusRequest,
   buildStartCascadeRequest, parseStartCascadeResponse,
   buildSendCascadeMessageRequest,
-  buildGetTrajectoryRequest, parseTrajectoryStatus,
+  buildGetTrajectoryRequest,
+  parseTrajectoryInfo, buildHandleReadUrlContentInteractionRequest,
   buildGetTrajectoryStepsRequest, parseTrajectorySteps,
   buildGetGeneratorMetadataRequest, parseGeneratorMetadata,
   buildGetUserStatusRequest, extractUserStatusBytes, parseGetUserStatusResponse,
@@ -65,6 +66,21 @@ function resetCascadeTransportState(port) {
   lsEntry.sessionId = null;
 }
 
+function csvSetEnv(name) {
+  return new Set(String(process.env[name] || '')
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean));
+}
+
+function isReadUrlAutoApproveAllowed(url, origin) {
+  if (process.env.WINDSURFAPI_NATIVE_TOOL_BRIDGE_WEBFETCH_AUTO_APPROVE !== '1') return false;
+  const allow = csvSetEnv('WINDSURFAPI_NATIVE_TOOL_BRIDGE_WEBFETCH_AUTO_APPROVE_ORIGINS');
+  if (!allow.size) return false;
+  const candidates = [origin, url].map(v => String(v || '').trim()).filter(Boolean);
+  return candidates.some(v => allow.has(v) || allow.has(v.replace(/\/+$/, '')));
+}
+
 function isImageLikeBlock(part) {
   const type = String(part?.type || '').toLowerCase();
   return type === 'image' || type === 'image_url' || type === 'input_image'
@@ -836,6 +852,8 @@ export class WindsurfClient {
       const usageByStep = new Map();
       const seenToolCallIds = new Set();
       const toolCalls = [];
+      const approvedReadUrlInteractions = new Set();
+      let cascadeTrajectoryId = '';
       let totalYielded = 0;
       let totalThinking = 0;
       let idleCount = 0;
@@ -871,6 +889,48 @@ export class WindsurfClient {
           && steps.some(step => Array.isArray(step?.toolCalls)
             && step.toolCalls.some(tc => tc?.cascade_native));
 
+        if (nativeMode && (nativeAllowlist || []).includes('read_url_content')) {
+          for (let i = 0; i < steps.length; i++) {
+            const pending = steps[i]?.requestedInteraction;
+            if (pending?.kind !== 'read_url_content') continue;
+            const url = pending.url || '';
+            const origin = pending.origin || '';
+            if (!isReadUrlAutoApproveAllowed(url, origin)) continue;
+            if (!cascadeTrajectoryId) {
+              const statusResp = await grpcUnary(
+                this.port, this.csrfToken,
+                `${LS_SERVICE}/GetCascadeTrajectory`,
+                grpcFrame(buildGetTrajectoryRequest(cascadeId))
+              );
+              const info = parseTrajectoryInfo(statusResp);
+              cascadeTrajectoryId = info.trajectoryId || '';
+              lastStatus = info.status;
+            }
+            if (!cascadeTrajectoryId) {
+              log.warn('WebFetch auto-approve skipped: missing trajectory_id');
+              continue;
+            }
+            const approvalKey = `${cascadeTrajectoryId}:${stepOffset + i}:${url}:${origin}`;
+            if (approvedReadUrlInteractions.has(approvalKey)) continue;
+            approvedReadUrlInteractions.add(approvalKey);
+            const req = buildHandleReadUrlContentInteractionRequest(cascadeId, {
+              trajectoryId: cascadeTrajectoryId,
+              stepIndex: stepOffset + i,
+              action: 1, // READ_URL_CONTENT_ACTION_ALLOW_ONCE
+              url,
+              origin,
+            });
+            await grpcUnary(
+              this.port, this.csrfToken,
+              `${LS_SERVICE}/HandleCascadeUserInteraction`,
+              grpcFrame(req),
+              10000
+            );
+            lastGrowthAt = Date.now();
+            log.warn(`WebFetch auto-approved read_url_content for allowed origin ${origin || '(unknown)'}`);
+          }
+        }
+
         // CORTEX_STEP_TYPE_ERROR_MESSAGE = 17. An error step means the cascade
         // refused the request (permission denied, model unavailable, etc.) —
         // raise it as a model-level error so the account isn't blamed.
@@ -1070,7 +1130,9 @@ export class WindsurfClient {
         const statusResp = await grpcUnary(
           this.port, this.csrfToken, `${LS_SERVICE}/GetCascadeTrajectory`, grpcFrame(statusProto)
         );
-        const status = parseTrajectoryStatus(statusResp);
+        const statusInfo = parseTrajectoryInfo(statusResp);
+        const status = statusInfo.status;
+        if (statusInfo.trajectoryId) cascadeTrajectoryId = statusInfo.trajectoryId;
         lastStatus = status;
 
         if (status !== 1) sawActive = true;

src/proto-trace.js

@@ -196,6 +196,12 @@ const CASCADE_WEB_REQUESTS_AUTO_EXECUTION = new Map([
   [3, 'TURBO'],
 ]);
 
+const READ_URL_CONTENT_ACTION = new Map([
+  [1, 'ALLOW_ONCE'],
+  [2, 'REJECT'],
+  [3, 'ALWAYS_ALLOW_ORIGIN'],
+]);
+
 function enumSummary(value, names) {
   return value == null ? null : {
     value,
@@ -467,6 +473,42 @@ function summarizeRequestedInteraction(buf) {
   };
 }
 
+function summarizeHandleCascadeUserInteraction(payload) {
+  const fields = parseFields(payload);
+  const cascadeId = stringField(fields, 1);
+  const interactionField = getField(fields, 2, 2);
+  const out = {
+    cascadeIdBytes: cascadeId.length,
+    cascadeIdHash: cascadeId ? shortHash(Buffer.from(cascadeId, 'utf8')) : null,
+    fieldNumbers: fields.map(f => f.field),
+  };
+  if (!interactionField) return out;
+
+  const interaction = parseFields(interactionField.value);
+  const trajectoryId = stringField(interaction, 1);
+  const readUrlField = getField(interaction, 15, 2);
+  out.interaction = {
+    trajectoryIdBytes: trajectoryId.length,
+    trajectoryIdHash: trajectoryId ? shortHash(Buffer.from(trajectoryId, 'utf8')) : null,
+    stepIndex: numberField(interaction, 2),
+    fieldNumbers: interaction.map(f => f.field),
+  };
+  if (!readUrlField) return out;
+
+  const readUrl = parseFields(readUrlField.value);
+  const url = stringField(readUrl, 2);
+  const origin = stringField(readUrl, 3);
+  out.interaction.readUrlContent = {
+    action: enumSummary(numberField(readUrl, 1), READ_URL_CONTENT_ACTION),
+    urlBytes: url.length,
+    urlHash: url ? shortHash(Buffer.from(url, 'utf8')) : null,
+    originBytes: origin.length,
+    originHash: origin ? shortHash(Buffer.from(origin, 'utf8')) : null,
+    fieldNumbers: readUrl.map(f => f.field),
+  };
+  return out;
+}
+
 function summarizeReadWrapperField19(wrapperBuf) {
   const fields = parseFields(wrapperBuf);
   return {
@@ -676,6 +718,9 @@ function semanticSummary(method, direction, payload) {
     if (method === 'GetCascadeTrajectorySteps' && direction === 'response') {
       return summarizeGetCascadeTrajectorySteps(payload);
     }
+    if (method === 'HandleCascadeUserInteraction' && direction === 'request') {
+      return summarizeHandleCascadeUserInteraction(payload);
+    }
   } catch (err) {
     return { error: err.message };
   }

src/windsurf.js

@@ -792,6 +792,87 @@ export function buildGetTrajectoryRequest(cascadeId) {
   return writeStringField(1, cascadeId);
 }
 
+/**
+ * Parse GetCascadeTrajectoryResponse.
+ *
+ * Response {
+ *   CortexTrajectory trajectory = 1; // trajectory_id=1, cascade_id=6
+ *   CascadeRunStatus status = 2;
+ * }
+ */
+export function parseTrajectoryInfo(buf) {
+  const fields = parseFields(buf);
+  const statusField = getField(fields, 2, 0);
+  const trajectoryField = getField(fields, 1, 2);
+  let trajectoryId = '';
+  let cascadeId = '';
+  if (trajectoryField) {
+    try {
+      const trajectory = parseFields(trajectoryField.value);
+      trajectoryId = getField(trajectory, 1, 2)?.value?.toString('utf8') || '';
+      cascadeId = getField(trajectory, 6, 2)?.value?.toString('utf8') || '';
+    } catch {}
+  }
+  return {
+    status: statusField ? statusField.value : 0,
+    trajectoryId,
+    cascadeId,
+  };
+}
+
+function parseReadUrlRequestedInteraction(stepFields) {
+  const requested = getField(stepFields, 56, 2);
+  if (!requested) return null;
+  try {
+    const requestedFields = parseFields(requested.value);
+    const readUrl = getField(requestedFields, 14, 2);
+    if (!readUrl) return null;
+    const spec = parseFields(readUrl.value);
+    const url = getField(spec, 1, 2)?.value?.toString('utf8') || '';
+    const origin = getField(spec, 2, 2)?.value?.toString('utf8') || '';
+    if (!url) return null;
+    return { url, origin };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build HandleCascadeUserInteractionRequest for ReadUrlContent approval.
+ *
+ * HandleCascadeUserInteractionRequest {
+ *   string cascade_id = 1;
+ *   CascadeUserInteraction interaction = 2;
+ * }
+ * CascadeUserInteraction {
+ *   string trajectory_id = 1;
+ *   uint32 step_index = 2;
+ *   CascadeReadUrlContentInteraction read_url_content = 15;
+ * }
+ */
+export function buildHandleReadUrlContentInteractionRequest(cascadeId, {
+  trajectoryId = '',
+  stepIndex = 0,
+  action = 1,
+  url = '',
+  origin = '',
+} = {}) {
+  const readUrlInteraction = Buffer.concat([
+    writeVarintField(1, action),
+    writeStringField(2, url),
+    writeStringField(3, origin),
+  ]);
+  const interaction = Buffer.concat([
+    writeStringField(1, trajectoryId),
+    writeVarintField(2, stepIndex),
+    writeMessageField(15, readUrlInteraction),
+  ]);
+  return Buffer.concat([
+    writeStringField(1, cascadeId),
+    writeMessageField(2, interaction),
+  ]);
+}
+
 /**
  * Build GetCascadeTrajectoryGeneratorMetadataRequest.
  *
@@ -892,9 +973,7 @@ export function parseStartCascadeResponse(buf) {
 
 /** Parse GetCascadeTrajectoryResponse → status (field 2). */
 export function parseTrajectoryStatus(buf) {
-  const fields = parseFields(buf);
-  const f2 = getField(fields, 2, 0);
-  return f2 ? f2.value : 0;
+  return parseTrajectoryInfo(buf).status;
 }
 
 /**
@@ -963,6 +1042,13 @@ export function parseTrajectorySteps(buf) {
       toolCalls: [], // [{id, name, argumentsJson, result?}]
       usage: null,  // {inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens}
     };
+    const readUrlRequestedInteraction = parseReadUrlRequestedInteraction(sf);
+    if (readUrlRequestedInteraction) {
+      entry.requestedInteraction = {
+        kind: 'read_url_content',
+        ...readUrlRequestedInteraction,
+      };
+    }
 
     // CortexTrajectoryStep.metadata (field 5) → CortexStepMetadata.
     // CortexStepMetadata.model_usage (field 9) → ModelUsageStats.
@@ -1176,6 +1262,7 @@ export function parseTrajectorySteps(buf) {
           const webDocument = getField(body, 2, 2);
           result = webDocument ? decodeKnowledgeBaseItemText(webDocument.value) : '';
           if (!result) result = getField(body, 5, 2)?.value?.toString('utf8') || '';
+          if (!result && readUrlRequestedInteraction) continue;
         } else if (kind === 'search_web') {
           const args = {
             query: getField(body, 1, 2)?.value?.toString('utf8') || '',