fix(native): classify cascade error traces

Author: dwgx

docs/native-bridge-protocol-notes.md

@@ -149,6 +149,21 @@ hashes, and safe classifications such as `looksPathLike` and
 `looksPromptLike`. Do not use the global raw-string trace switch for production
 traffic; it can capture prompts.
 
+Error trajectory steps also have a dedicated redacted summary. For `type=17`
+or any step carrying `error_message` field `24` / `error` field `31`, traces
+now expose `semantic.steps[].errorStep` with source field numbers, byte
+lengths, hashes, nested string paths, and classification flags such as
+`permissionDenied`, `failedPrecondition`, `modelNotAvailable`, and
+`internalError`. Raw previews stay off by default; for a gated lab run only:
+
+```text
+WINDSURFAPI_PROTO_TRACE_ERROR_STRINGS=1
+```
+
+This switch is narrower than `WINDSURFAPI_PROTO_TRACE_STRINGS=1` and still
+redacts emails and token-like values. It exists to diagnose LS executor
+preconditions without dumping complete prompts or account material.
+
 Trajectory parsing now recognizes the web step oneofs observed so far:
 
 - `read_url_content` = field `40`, body `{ url=1, summary=5 }`
@@ -197,6 +212,27 @@ separate first-party API bridge until we find the LS-side web executor
 precondition. The confirmed protobuf fields are useful for tracing and future
 matrix work, but not sufficient for production native bridge rollout.
 
+The v2.0.132 VPS pass rechecked the same area after the Read wrapper fixes:
+
+- Direct `GetWebSearchResults` succeeded for all ten loaded active/pro
+  accounts, returning two results per account for the control query.
+- A gated LS-native smoke enabled only `WebSearch,WebFetch` for
+  `claude-sonnet-4.6` with API-key gating and raw web subconfigs.
+- `SendUserCascadeMessage` did send web native configs:
+  `search_web` appeared as allowlist `["search_web"]` with subconfig field
+  `13`; `read_url_content` appeared as allowlist `["read_url_content"]` with
+  subconfig field `37`.
+- `GetCascadeTrajectorySteps` still emitted no `field=42 search_web` and no
+  `field=40 read_url_content` native oneof. The repeated shape was
+  `type=14`, `type=34`, then `type=17` error with field `24`.
+- The OpenAI-compatible smoke response surfaced HTTP `403` with
+  `type="model_not_available"` for both web scenarios.
+
+Updated conclusion: the proxy is not failing to send the WebFetch config; LS
+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.
+
 ## Direct Web Search API
 
 `GetWebSearchResults` is confirmed independently of the LS-native tool path:

docs/releases/RELEASE_NOTES_2.0.133.md

@@ -0,0 +1,21 @@
+# v2.0.133
+
+- Added redacted semantic summaries for Cascade error trajectory steps. Proto
+  traces now expose `semantic.steps[].errorStep` for `error_message` field `24`
+  and `error` field `31`, including field numbers, byte lengths, hashes,
+  nested string paths, and safe classification flags such as
+  `permissionDenied`, `failedPrecondition`, `modelNotAvailable`, and
+  `internalError`.
+- Added a dedicated lab-only preview switch:
+  `WINDSURFAPI_PROTO_TRACE_ERROR_STRINGS=1`. It is narrower than global string
+  tracing and still redacts emails and token-like values.
+- Documented the v2.0.132 VPS WebSearch/WebFetch canary. Direct
+  `GetWebSearchResults` remains confirmed, but LS-native WebSearch/WebFetch
+  still emitted no `search_web` / `read_url_content` oneof even though both
+  native configs were sent. WebFetch direct still has no descriptor-backed
+  endpoint and is not implemented from guesswork.
+
+Verification:
+
+- `node --check src/proto-trace.js`
+- `node --test test/proto-trace.test.js`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "windsurf-api",
-  "version": "2.0.132",
+  "version": "2.0.133",
   "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/proto-trace.js

@@ -50,6 +50,7 @@ function mostlyText(buf) {
 function redactPreview(s) {
   return String(s)
     .replace(/\b(?:devin-session-token|sessionToken|api[_-]?key|firebase_id_token|idToken|refreshToken)\b\s*[:=]\s*["']?[^"',\s)]+/gi, '<redacted-secret>')
+    .replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, '<redacted-email>')
     .replace(/\b[A-Za-z0-9_-]{32,}\b/g, '<redacted-token>')
     .slice(0, 240);
 }
@@ -423,6 +424,115 @@ function summarizeReadWrapperField19(wrapperBuf) {
   };
 }
 
+function classifyErrorText(text) {
+  const value = String(text || '').toLowerCase();
+  return {
+    permissionDenied: /permission[_\s-]?denied|forbidden|\b403\b|not authorized/.test(value),
+    failedPrecondition: /failed[_\s-]?precondition|precondition/.test(value),
+    modelNotAvailable: /model[_\s-]?not[_\s-]?available|model not available/.test(value),
+    internalError: /internal[_\s-]?error|an internal error occurred/.test(value),
+    unauthenticated: /unauthenticated|\b401\b|invalid api key|invalid token/.test(value),
+    rateLimited: /rate[_\s-]?limit|too many requests|\b429\b/.test(value),
+    quotaOrEntitlement: /quota|credit|billing|subscription|entitlement/.test(value),
+  };
+}
+
+function compactTrueFlags(flags) {
+  return Object.fromEntries(Object.entries(flags || {}).filter(([, v]) => !!v));
+}
+
+function mergeErrorClassifications(target, source) {
+  for (const [key, value] of Object.entries(source || {})) {
+    if (value) target[key] = true;
+  }
+  return target;
+}
+
+function summarizeErrorString(path, buf) {
+  const text = buf.toString('utf8');
+  const classifications = compactTrueFlags(classifyErrorText(text));
+  const out = {
+    path,
+    bytes: buf.length,
+    sha256: shortHash(buf),
+    classifications,
+  };
+  if (process.env.WINDSURFAPI_PROTO_TRACE_ERROR_STRINGS === '1') {
+    out.preview = redactPreview(text);
+  }
+  return out;
+}
+
+function collectErrorStrings(buf, path, out, depth = 0) {
+  if (!Buffer.isBuffer(buf) || out.length >= positiveIntEnv('WINDSURFAPI_PROTO_TRACE_ERROR_STRING_LIMIT', 8)) return;
+  const maxDepth = positiveIntEnv('WINDSURFAPI_PROTO_TRACE_ERROR_DEPTH', 4);
+  if (depth < maxDepth && looksLikeMessage(buf)) {
+    const before = out.length;
+    try {
+      const fields = parseFields(buf);
+      for (const f of fields) {
+        if (out.length >= positiveIntEnv('WINDSURFAPI_PROTO_TRACE_ERROR_STRING_LIMIT', 8)) return;
+        if (f.wireType !== 2 || !Buffer.isBuffer(f.value)) continue;
+        collectErrorStrings(f.value, `${path}.${f.field}`, out, depth + 1);
+      }
+      if (out.length > before) return;
+    } catch {}
+  }
+  if (mostlyText(buf)) {
+    out.push(summarizeErrorString(path, buf));
+  }
+}
+
+function summarizeErrorSource(field, payload) {
+  const source = {
+    field,
+    bytes: payload.length,
+    sha256: shortHash(payload),
+    fieldNumbers: [],
+    varints: [],
+    strings: [],
+    classifications: {},
+  };
+  try {
+    const fields = parseFields(payload);
+    source.fieldNumbers = fields.map(f => f.field);
+    source.varints = fields
+      .filter(f => f.wireType === 0)
+      .slice(0, 8)
+      .map(f => ({
+        field: f.field,
+        value: typeof f.value === 'bigint' ? f.value.toString() : f.value,
+      }));
+    collectErrorStrings(payload, String(field), source.strings);
+    for (const s of source.strings) {
+      mergeErrorClassifications(source.classifications, s.classifications);
+    }
+  } catch (err) {
+    source.parseError = err.message;
+  }
+  source.classifications = compactTrueFlags(source.classifications);
+  return source;
+}
+
+function summarizeErrorStep(fields) {
+  const sources = [];
+  for (const fieldNum of [24, 31]) {
+    for (const f of getAllFields(fields, fieldNum)) {
+      if (f.wireType !== 2 || !Buffer.isBuffer(f.value)) continue;
+      sources.push(summarizeErrorSource(fieldNum, f.value));
+    }
+  }
+  if (!sources.length) return null;
+  const classifications = {};
+  for (const source of sources) {
+    mergeErrorClassifications(classifications, source.classifications);
+  }
+  return {
+    sources,
+    classifications: compactTrueFlags(classifications),
+  };
+}
+
 function summarizeTrajectoryStep(stepBuf, index) {
   const fields = parseFields(stepBuf);
   const oneofFields = [];
@@ -445,6 +555,7 @@ function summarizeTrajectoryStep(stepBuf, index) {
     }));
   const type = numberField(fields, 1);
   const wrapper19 = type === 14 ? getField(fields, 19, 2) : null;
+  const errorStep = summarizeErrorStep(fields);
   return {
     index,
     type,
@@ -453,6 +564,7 @@ function summarizeTrajectoryStep(stepBuf, index) {
     nativeOneofs: oneofFields,
     messageFields: interestingFields,
     ...(wrapper19 ? { readWrapperField19: summarizeReadWrapperField19(wrapper19.value) } : {}),
+    ...(errorStep ? { errorStep } : {}),
   };
 }
 

test/proto-trace.test.js

@@ -405,4 +405,78 @@ describe('proto trace', () => {
     assert.match(promptChild.preview, /<redacted-secret>/);
     assert.doesNotMatch(promptChild.preview, /abcdefghijklmnopqrstuvwxyz1234567890abcdef/);
   });
+
+  it('classifies error trajectory steps without raw strings by default', () => {
+    process.env.WINDSURFAPI_PROTO_TRACE = '1';
+    const details = Buffer.concat([
+      writeStringField(1, 'permission_denied: LS web executor failed precondition for user@example.com'),
+      writeStringField(2, 'an internal error occurred'),
+    ]);
+    const errorMessage = Buffer.concat([
+      writeMessageField(3, details),
+      writeVarintField(5, 1),
+    ]);
+    const step = Buffer.concat([
+      writeVarintField(1, 17),
+      writeVarintField(4, 3),
+      writeMessageField(24, errorMessage),
+    ]);
+    traceGrpcPayload({
+      port: 42100,
+      path: '/exa.language_server_pb.LanguageServerService/GetCascadeTrajectorySteps',
+      direction: 'response',
+      body: writeMessageField(1, step),
+      transport: 'grpc',
+      framed: false,
+    });
+
+    const file = join(dir, `ls-proto-${process.pid}-GetCascadeTrajectorySteps.jsonl`);
+    const line = readFileSync(file, 'utf8').trim();
+    const rec = JSON.parse(line);
+    const errorStep = rec.semantic.steps[0].errorStep;
+    assert.deepEqual(errorStep.classifications, {
+      permissionDenied: true,
+      failedPrecondition: true,
+      internalError: true,
+    });
+    assert.equal(errorStep.sources[0].field, 24);
+    assert.deepEqual(errorStep.sources[0].fieldNumbers, [3, 5]);
+    assert.equal(errorStep.sources[0].strings.length, 2);
+    assert.ok(errorStep.sources[0].strings.every(s => s.sha256 && s.bytes > 0));
+    assert.ok(errorStep.sources[0].strings.every(s => s.preview === undefined));
+    assert.doesNotMatch(line, /user@example\.com/);
+    assert.doesNotMatch(line, /permission_denied: LS web executor/);
+  });
+
+  it('can include redacted error previews behind a dedicated switch', () => {
+    process.env.WINDSURFAPI_PROTO_TRACE = '1';
+    process.env.WINDSURFAPI_PROTO_TRACE_ERROR_STRINGS = '1';
+    const errorMessage = writeStringField(
+      3,
+      'model_not_available for tester@example.com api_key=abcdefghijklmnopqrstuvwxyz1234567890abcdef'
+    );
+    const step = Buffer.concat([
+      writeVarintField(1, 17),
+      writeVarintField(4, 3),
+      writeMessageField(24, errorMessage),
+    ]);
+    traceGrpcPayload({
+      port: 42100,
+      path: '/exa.language_server_pb.LanguageServerService/GetCascadeTrajectorySteps',
+      direction: 'response',
+      body: writeMessageField(1, step),
+      transport: 'grpc',
+      framed: false,
+    });
+
+    const file = join(dir, `ls-proto-${process.pid}-GetCascadeTrajectorySteps.jsonl`);
+    const rec = JSON.parse(readFileSync(file, 'utf8').trim());
+    const stringSummary = rec.semantic.steps[0].errorStep.sources[0].strings[0];
+    assert.equal(stringSummary.classifications.modelNotAvailable, true);
+    assert.match(stringSummary.preview, /model_not_available/);
+    assert.match(stringSummary.preview, /<redacted-email>/);
+    assert.match(stringSummary.preview, /<redacted-secret>/);
+    assert.doesNotMatch(stringSummary.preview, /tester@example\.com/);
+    assert.doesNotMatch(stringSummary.preview, /abcdefghijklmnopqrstuvwxyz1234567890abcdef/);
+  });
 });