fix(native): trace read wrapper fields

Author: dwgx

.dockerignore

@@ -18,6 +18,7 @@ docs
 audit
 scripts/*
 !scripts/native-bridge-smoke.mjs
+!scripts/special-agent-smoke.mjs
 !scripts/lsp-capacity-matrix.mjs
 !scripts/web-search-direct-probe.mjs
 bugsy

.env.example

@@ -76,6 +76,10 @@ LS_PORT=42100
 # WINDSURFAPI_NATIVE_TOOL_BRIDGE_OFF=1
 # Smoke an already-running native bridge deployment with:
 # API_KEY=... BASE_URL=http://127.0.0.1:3003 npm run smoke:native-bridge
+# Protocol trace is lab-only. For Read wrapper reverse engineering, prefer the
+# dedicated child summary over global raw string dumps:
+# WINDSURFAPI_PROTO_TRACE=1
+# WINDSURFAPI_PROTO_TRACE_READ_WRAPPER_STRINGS=0
 
 # Optional special-agent backend for models that do not work through direct
 # Cascade chat (currently swe-1.6 / swe-1.6-fast / adaptive / arena-*).
@@ -98,6 +102,8 @@ LS_PORT=42100
 # be used before enabling these in production.
 # DEVIN_CLI_ALLOW_CLIENT_TOOLS=0
 # DEVIN_CLI_ALLOW_MEDIA=0
+# After configuring Devin CLI/ACP, validate the route with:
+# API_KEY=... BASE_URL=http://127.0.0.1:3003 npm run smoke:special-agent
 
 # ========== Dashboard ==========
 # Dashboard password — protects /dashboard and all /dashboard/api/* endpoints.

.gitignore

@@ -7,6 +7,7 @@ sshpass2.sh
 deploy-us.py
 scripts/*
 !scripts/native-bridge-smoke.mjs
+!scripts/special-agent-smoke.mjs
 !scripts/lsp-capacity-matrix.mjs
 !scripts/web-search-direct-probe.mjs
 src/get-token.js

Dockerfile

@@ -26,6 +26,7 @@ RUN apt-get update \
 COPY package.json ./
 COPY src ./src
 COPY scripts/native-bridge-smoke.mjs ./scripts/native-bridge-smoke.mjs
+COPY scripts/special-agent-smoke.mjs ./scripts/special-agent-smoke.mjs
 COPY scripts/lsp-capacity-matrix.mjs ./scripts/lsp-capacity-matrix.mjs
 COPY scripts/web-search-direct-probe.mjs ./scripts/web-search-direct-probe.mjs
 COPY install-ls.sh setup.sh .env.example ./

docs/native-bridge-protocol-notes.md

@@ -132,6 +132,23 @@ 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.
 
+For the observed Read wrapper (`type=14`, `field=19`), v2.0.131 only promotes
+field `1` or `2` when the candidate is clearly path-like. Live traces showed
+field `2` can also contain the full prompt/environment text, so this is a
+stop-loss guard, not a confirmed schema. Enable proto trace to inspect
+`semantic.steps[].readWrapperField19` before changing the parser again:
+
+```text
+WINDSURFAPI_PROTO_TRACE=1
+# Optional, only for a gated lab run. Redaction still applies.
+WINDSURFAPI_PROTO_TRACE_READ_WRAPPER_STRINGS=1
+```
+
+The dedicated summary records child field numbers, wire types, byte lengths,
+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.
+
 Trajectory parsing now recognizes the web step oneofs observed so far:
 
 - `read_url_content` = field `40`, body `{ url=1, summary=5 }`

docs/releases/RELEASE_NOTES_2.0.132.md

@@ -0,0 +1,27 @@
+# v2.0.132
+
+- Added dedicated proto trace summaries for the Read `type=14` / `field=19`
+  wrapper. Traces now expose `semantic.steps[].readWrapperField19` with child
+  field numbers, byte lengths, hashes, and safe `looksPathLike` /
+  `looksPromptLike` classifications. Raw previews stay off by default and
+  require `WINDSURFAPI_PROTO_TRACE_READ_WRAPPER_STRINGS=1` for gated lab runs.
+- Kept Read promotion conservative. v2.0.131's path guard remains the runtime
+  boundary; nested wrapper fields are not promoted until live traces confirm the
+  schema.
+- Added coverage for generic `BUILD_*` health metadata. The VPS deployment can
+  inject `WINDSURFAPI_BUILD_VERSION`, `WINDSURFAPI_BUILD_COMMIT`, commit
+  message/date, and branch through `.env` so `/health` reports the deployed
+  revision. Automatic GHCR build-arg wiring still requires a workflow-scope
+  GitHub token and is intentionally left out of this tag.
+- Added `npm run smoke:special-agent` for the SWE/Devin special-agent POC. The
+  smoke preflights `/health?verbose=1`, sends a text-only `swe-1.6-fast`
+  request, and refuses to run unless the backend is explicitly enabled.
+- WebSearch remains on the direct `GetWebSearchResults` probe path, and
+  WebFetch has no guessed direct endpoint. LS-native WebSearch/WebFetch stay
+  out of the production native bridge defaults.
+
+Verification:
+
+- `node --check src/proto-trace.js`
+- `node --check scripts/special-agent-smoke.mjs`
+- `node --test test/proto-trace.test.js test/native-read-wrapper.test.js test/version.test.js test/special-agent-smoke.test.js test/docker-script-packaging.test.js test/web-search-direct-probe.test.js`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "windsurf-api",
-  "version": "2.0.131",
+  "version": "2.0.132",
   "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",
@@ -9,6 +9,7 @@
     "dev": "node --watch src/index.js",
     "test": "node --test test/*.test.js",
     "smoke:native-bridge": "node scripts/native-bridge-smoke.mjs",
+    "smoke:special-agent": "node scripts/special-agent-smoke.mjs",
     "smoke:lsp-matrix": "node scripts/lsp-capacity-matrix.mjs",
     "probe:web-search": "node scripts/web-search-direct-probe.mjs"
   },

scripts/special-agent-smoke.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+const baseUrl = (process.env.BASE_URL || process.env.WINDSURFAPI_BASE_URL || 'http://127.0.0.1:3003').replace(/\/+$/, '');
+const apiKey = process.env.API_KEY || process.env.WINDSURFAPI_API_KEY || '';
+const model = process.env.MODEL || process.env.SPECIAL_AGENT_SMOKE_MODEL || 'swe-1.6-fast';
+const requestTimeoutMs = Math.max(5_000, Number(process.env.SPECIAL_AGENT_SMOKE_TIMEOUT_MS || 180_000));
+const requireEnabled = process.env.SPECIAL_AGENT_SMOKE_REQUIRE_ENABLED !== '0';
+const prompt = process.env.SPECIAL_AGENT_SMOKE_PROMPT || 'Reply exactly SPECIAL_AGENT_OK.';
+
+if (!apiKey) {
+  console.error('API_KEY is required.');
+  process.exit(2);
+}
+
+function compactText(text, max = 1200) {
+  const s = String(text || '').replace(/\s+/g, ' ').trim();
+  return s.length > max ? `${s.slice(0, max)}...<truncated ${s.length - max} chars>` : s;
+}
+
+async function fetchJson(path, opts = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
+  try {
+    const res = await fetch(`${baseUrl}${path}`, {
+      ...opts,
+      signal: controller.signal,
+      headers: {
+        authorization: `Bearer ${apiKey}`,
+        ...(opts.headers || {}),
+      },
+    });
+    const text = await res.text();
+    let body = null;
+    try { body = text ? JSON.parse(text) : null; } catch {}
+    return { status: res.status, body, text };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const health = await fetchJson('/health?verbose=1');
+const specialAgent = health.body?.specialAgent || null;
+if (requireEnabled && !specialAgent?.enabled) {
+  console.log(JSON.stringify({
+    ok: false,
+    stage: 'preflight',
+    error: 'special-agent backend is disabled',
+    specialAgent,
+    hint: 'Set WINDSURFAPI_SPECIAL_AGENT_BACKEND=devin-cli and DEVIN_CLI_MODE=print or acp before running this smoke.',
+  }, null, 2));
+  process.exit(1);
+}
+
+const started = Date.now();
+const chat = await fetchJson('/v1/chat/completions', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({
+    model,
+    stream: false,
+    max_tokens: 128,
+    messages: [{ role: 'user', content: prompt }],
+  }),
+});
+
+const content = chat.body?.choices?.[0]?.message?.content || '';
+const out = {
+  ok: chat.status >= 200 && chat.status < 300 && !chat.body?.error,
+  model,
+  status: chat.status,
+  latencyMs: Date.now() - started,
+  specialAgent,
+  content: compactText(content),
+  error: chat.body?.error || null,
+};
+
+console.log(JSON.stringify(out, null, 2));
+if (!out.ok) process.exit(1);

src/proto-trace.js

@@ -54,6 +54,42 @@ function redactPreview(s) {
     .slice(0, 240);
 }
 
+function looksPathLike(s) {
+  const value = String(s || '').trim();
+  if (!value || value.length > 1024 || /[\r\n<>]/.test(value)) return false;
+  if (/^file:\/\/\/?(?:[A-Za-z]:[\\/]|\/|~[\\/])/.test(value)) return true;
+  if (/^(?:[A-Za-z]:[\\/]|\/|~[\\/]|\.{1,2}[\\/])\S+/.test(value)) return true;
+  return /^[A-Za-z0-9._-]+(?:[\\/][A-Za-z0-9._-]+)*\.[A-Za-z0-9]{1,12}$/.test(value);
+}
+
+function looksPromptLike(s) {
+  const value = String(s || '');
+  if (!value) return false;
+  if (value.includes('Working directory:') || value.includes('Use the Read tool')) return true;
+  if (value.includes('<env>') || value.includes('</env>') || value.includes('<system-reminder>')) return true;
+  return value.length > 512 && /(?:tool|prompt|environment|platform|workspace)/i.test(value);
+}
+
+function basenameOfPath(s) {
+  const value = String(s || '').trim().replace(/^file:\/+/, '');
+  const parts = value.split(/[\\/]+/).filter(Boolean);
+  return parts.length ? parts[parts.length - 1].slice(0, 120) : '';
+}
+
+function looksLikeMessage(buf) {
+  if (!buf?.length) return false;
+  const key = buf[0];
+  const wireType = key & 7;
+  const field = key >> 3;
+  if (!field || ![0, 1, 2, 5].includes(wireType)) return false;
+  try {
+    const parsed = parseFields(buf);
+    return parsed.length > 0 && parsed.every(f => f.field > 0);
+  } catch {
+    return false;
+  }
+}
+
 function stringField(fields, num) {
   const f = getField(fields, num, 2);
   return f ? f.value.toString('utf8') : '';
@@ -343,6 +379,50 @@ function summarizeNativeStepBody(kind, bodyBuf) {
   return { fieldCount: f.length };
 }
 
+function summarizeReadWrapperField19(wrapperBuf) {
+  const fields = parseFields(wrapperBuf);
+  return {
+    bytes: wrapperBuf.length,
+    fieldNumbers: fields.map(f => f.field),
+    children: fields.slice(0, positiveIntEnv('WINDSURFAPI_PROTO_TRACE_READ_WRAPPER_CHILD_LIMIT', 24))
+      .map((f) => {
+        const out = {
+          field: f.field,
+          wireType: f.wireType,
+        };
+        if (f.wireType === 0) {
+          out.type = 'varint';
+          out.value = typeof f.value === 'bigint' ? f.value.toString() : f.value;
+          return out;
+        }
+        if (!Buffer.isBuffer(f.value)) return out;
+        out.bytes = f.value.length;
+        out.sha256 = shortHash(f.value);
+        if (looksLikeMessage(f.value)) {
+          out.type = 'message_or_bytes';
+          out.summary = summarizeMessageChildren(f.value, 8);
+          return out;
+        }
+        if (mostlyText(f.value)) {
+          const text = f.value.toString('utf8');
+          out.type = 'string';
+          out.hasNewline = /[\r\n]/.test(text);
+          out.hasAngleBracket = /[<>]/.test(text);
+          out.looksPathLike = looksPathLike(text);
+          out.looksPromptLike = looksPromptLike(text);
+          out.basename = out.looksPathLike ? basenameOfPath(text) : '';
+          if (process.env.WINDSURFAPI_PROTO_TRACE_READ_WRAPPER_STRINGS === '1') {
+            out.preview = redactPreview(text);
+          }
+          return out;
+        }
+        out.type = 'message_or_bytes';
+        out.summary = summarizeMessageChildren(f.value, 8);
+        return out;
+      }),
+  };
+}
+
 function summarizeTrajectoryStep(stepBuf, index) {
   const fields = parseFields(stepBuf);
   const oneofFields = [];
@@ -363,13 +443,16 @@ function summarizeTrajectoryStep(stepBuf, index) {
       field: f.field,
       ...summarizeMessageChildren(f.value, 8),
     }));
+  const type = numberField(fields, 1);
+  const wrapper19 = type === 14 ? getField(fields, 19, 2) : null;
   return {
     index,
-    type: numberField(fields, 1),
+    type,
     status: numberField(fields, 4),
     fieldNumbers: fields.map(f => f.field),
     nativeOneofs: oneofFields,
     messageFields: interestingFields,
+    ...(wrapper19 ? { readWrapperField19: summarizeReadWrapperField19(wrapper19.value) } : {}),
   };
 }
 

test/native-read-wrapper.test.js

@@ -118,6 +118,38 @@ describe('native Read wrapper trajectory parsing', () => {
     assert.equal(calls.length, 0);
   });
 
+  it('prefers wrapper field 1 path over field 2 prompt text', () => {
+    const wrapper = Buffer.concat([
+      writeStringField(1, 'file:///home/user/projects/workspace-abc123/README.md'),
+      writeStringField(2, '- Working directory: /tmp/project\n\nUse the Read tool exactly once for README.md.'),
+      writeStringField(4, 'observed content'),
+    ]);
+    const step = Buffer.concat([
+      writeVarintField(1, 14),
+      writeVarintField(4, 3),
+      writeMessageField(19, wrapper),
+    ]);
+    const steps = parseTrajectorySteps(trajectoryStepsResponse(step));
+    const calls = steps[0].toolCalls.filter(tc => tc.cascade_native);
+    assert.equal(calls.length, 1);
+    assert.equal(JSON.parse(calls[0].argumentsJson).absolute_path_uri, 'file:///home/user/projects/workspace-abc123/README.md');
+  });
+
+  it('does not promote a nested wrapper field before the field role is confirmed', () => {
+    const wrapper = Buffer.concat([
+      writeMessageField(3, writeStringField(1, 'file:///home/user/projects/workspace-abc123/README.md')),
+      writeStringField(4, 'observed content'),
+    ]);
+    const step = Buffer.concat([
+      writeVarintField(1, 14),
+      writeVarintField(4, 3),
+      writeMessageField(19, wrapper),
+    ]);
+    const steps = parseTrajectorySteps(trajectoryStepsResponse(step));
+    const calls = steps[0].toolCalls.filter(tc => tc.cascade_native);
+    assert.equal(calls.length, 0);
+  });
+
   it('repairs native Read workspace paths to caller cwd-relative paths before sanitizing', () => {
     const tc = {
       name: 'Read',