@bxb1337/windsurf-fast-context 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,337 @@
+# @bxb1337/windsurf-fast-context
+
+An AI SDK V3 compatible provider for Windsurf's Devstral code search API. This provider exposes tool calls for code search operations, allowing tools like OpenCode to execute them.
+
+**Important**: This provider exposes tool calls but does **not** execute them. Tool execution is delegated to the caller (e.g., OpenCode, your application).
+
+## Installation
+
+```bash
+npm install @bxb1337/windsurf-fast-context
+# or
+pnpm add @bxb1337/windsurf-fast-context
+# or
+yarn add @bxb1337/windsurf-fast-context
+```
+
+### Peer Dependencies
+
+This package requires `ai` as a peer dependency:
+
+```bash
+npm install ai
+```
+
+## Quick Start
+
+```typescript
+import { createWindsurfProvider } from '@bxb1337/windsurf-fast-context';
+import { generateText } from 'ai';
+
+// Create the provider with your API key
+const windsurf = createWindsurfProvider({
+  apiKey: process.env.WINDSURF_API_KEY,
+});
+
+// Use with AI SDK
+const result = await generateText({
+  model: windsurf('MODEL_SWE_1_6_FAST'),
+  prompt: 'Find authentication logic in the codebase',
+  tools: {
+    ripgrep: {
+      description: 'Search for patterns in files',
+      parameters: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string' },
+          path: { type: 'string' },
+        },
+        required: ['pattern'],
+      },
+    },
+    readfile: {
+      description: 'Read file contents',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+        },
+        required: ['path'],
+      },
+    },
+  },
+});
+
+// Tool calls are exposed for you to execute
+for (const part of result.content) {
+  if (part.type === 'tool-call') {
+    console.log(`Tool: ${part.toolName}`);
+    console.log(`Args: ${JSON.stringify(part.args)}`);
+    // Execute the tool yourself...
+  }
+}
+```
+
+## API Reference
+
+### `createWindsurfProvider(options?)`
+
+Creates a Windsurf provider factory function.
+
+```typescript
+import { createWindsurfProvider } from '@bxb1337/windsurf-fast-context';
+
+const windsurf = createWindsurfProvider({
+  apiKey: 'your-api-key',
+  baseURL: 'https://custom-endpoint.com',
+  headers: { 'X-Custom': 'value' },
+});
+```
+
+#### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `apiKey` | `string` | Windsurf API key. Falls back to `WINDSURF_API_KEY` environment variable. Required. |
+| `baseURL` | `string` | Custom API endpoint. Default: `https://server.self-serve.windsurf.com` |
+| `headers` | `Record<string, string>` | Custom headers to send with each request. |
+| `fetch` | `FetchFn` | Custom fetch function for testing or proxying. |
+| `generateId` | `() => string` | Custom ID generator for tool calls. |
+
+#### Returns
+
+A function that accepts a model ID and returns a `LanguageModelV3` instance:
+
+```typescript
+const model = windsurf('MODEL_SWE_1_6_FAST');
+```
+
+### `windsurf` (named export)
+
+A pre-configured provider instance that reads the API key from `WINDSURF_API_KEY`:
+
+```typescript
+import { windsurf } from '@bxb1337/windsurf-fast-context';
+
+const model = windsurf('MODEL_SWE_1_6_FAST');
+```
+
+### Default Export
+
+The default export is the `windsurf` provider:
+
+```typescript
+import windsurf from '@bxb1337/windsurf-fast-context';
+
+const model = windsurf('MODEL_SWE_1_6_FAST');
+```
+
+### Supported Models
+
+| Model ID | Description |
+|----------|-------------|
+| `MODEL_SWE_1_6_FAST` | Fast variant for quick responses |
+| `MODEL_SWE_1_6` | Standard variant with more capability |
+
+Custom model IDs are also accepted as strings.
+
+## Configuration
+
+### Environment Variable
+
+Set your API key via environment variable:
+
+```bash
+export WINDSURF_API_KEY="your-api-key"
+```
+
+Then use the default export:
+
+```typescript
+import windsurf from '@bxb1337/windsurf-fast-context';
+
+// Reads WINDSURF_API_KEY automatically
+const model = windsurf('MODEL_SWE_1_6_FAST');
+```
+
+### OpenCode Integration
+
+Add to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "windsurf": {
+      "npm": "@bxb1337/windsurf-fast-context",
+      "name": "Windsurf Devstral",
+      "options": {
+        "apiKey": "your-api-key",
+        "baseURL": "https://server.self-serve.windsurf.com"
+      },
+      "models": {
+        "MODEL_SWE_1_6_FAST": {
+          "name": "Devstral Fast",
+          "limit": {
+            "context": 128000,
+            "output": 8192
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Custom Fetch for Testing
+
+```typescript
+import { createWindsurfProvider } from '@bxb1337/windsurf-fast-context';
+
+const mockFetch = async (url: string | URL | Request, init?: RequestInit) => {
+  // Return mock responses for testing
+  return new Response(JSON.stringify({ result: 'mocked' }), {
+    headers: { 'Content-Type': 'application/json' },
+  });
+};
+
+const windsurf = createWindsurfProvider({
+  apiKey: 'test-key',
+  fetch: mockFetch,
+});
+```
+
+## Examples
+
+### Basic Code Search
+
+```typescript
+import windsurf from '@bxb1337/windsurf-fast-context';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: windsurf('MODEL_SWE_1_6_FAST'),
+  prompt: 'Search for TODO comments in the codebase',
+  tools: {
+    ripgrep: {
+      description: 'Search files using regex patterns',
+      parameters: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string', description: 'Regex pattern to search' },
+          path: { type: 'string', description: 'Directory to search in' },
+        },
+        required: ['pattern'],
+      },
+    },
+  },
+});
+
+console.log(result.text);
+```
+
+### Streaming Responses
+
+```typescript
+import windsurf from '@bxb1337/windsurf-fast-context';
+import { streamText } from 'ai';
+
+const stream = await streamText({
+  model: windsurf('MODEL_SWE_1_6_FAST'),
+  prompt: 'Analyze the project structure',
+  tools: {
+    tree: {
+      description: 'List directory tree',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          depth: { type: 'number' },
+        },
+        required: ['path'],
+      },
+    },
+  },
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+### Multi-turn Conversation
+
+```typescript
+import windsurf from '@bxb1337/windsurf-fast-context';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: windsurf('MODEL_SWE_1_6_FAST'),
+  messages: [
+    { role: 'system', content: 'You are a code search assistant.' },
+    { role: 'user', content: 'Find all API routes' },
+    { role: 'assistant', content: 'I found routes in src/routes/' },
+    { role: 'user', content: 'Show me the auth routes' },
+  ],
+  tools: {
+    glob: {
+      description: 'Find files matching a pattern',
+      parameters: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string' },
+        },
+        required: ['pattern'],
+      },
+    },
+  },
+});
+```
+
+## Troubleshooting
+
+### "WINDSURF_API_KEY is required"
+
+The API key was not provided. Either:
+1. Pass `apiKey` to `createWindsurfProvider()`
+2. Set the `WINDSURF_API_KEY` environment variable
+
+### Authentication Errors
+
+If you see authentication failures:
+1. Verify your API key is valid and not expired
+2. Check that the key starts with the expected prefix
+3. Ensure no extra whitespace in the environment variable
+
+### Tool Calls Not Executed
+
+This is expected behavior. This provider exposes tool calls for you to execute. The `restricted_exec` and `answer` tools are returned as `tool-call` content parts. Your application is responsible for executing them.
+
+### Integration Tests Skipped
+
+Integration tests are gated by `WINDSURF_API_KEY`. To run them:
+
+```bash
+export WINDSURF_API_KEY="your-api-key"
+pnpm test test/integration/
+```
+
+### Custom Endpoint Issues
+
+When using `baseURL`, ensure:
+1. The URL includes the protocol (`https://`)
+2. No trailing slash
+3. The endpoint is accessible from your network
+
+## What This Package Does NOT Do
+
+Per the design scope:
+
+- **No built-in tool execution**: Tools like `rg`, `readfile`, `tree`, `ls`, `glob` are exposed as tool calls, not executed
+- **No MCP server**: This is an AI SDK provider, not an MCP server implementation
+- **No local key extraction**: API keys must be provided explicitly via constructor or environment variable
+- **No Chat/Completions API compatibility**: This is an AI SDK V3 provider, not an OpenAI-compatible API
+
+## License
+
+MIT

package/dist/auth/api-key.d.ts

@@ -0,0 +1,2 @@
+import type { WindsurfProviderOptions } from '../types';
+export declare function resolveApiKey(options?: WindsurfProviderOptions): string;

package/dist/auth/api-key.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth/jwt-manager.d.ts

@@ -0,0 +1,18 @@
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export declare const AUTH_BASE = "https://server.self-serve.windsurf.com/exa.auth_pb.AuthService";
+export interface JwtManagerOptions {
+    fetch?: FetchLike;
+    authBase?: string;
+    now?: () => number;
+}
+export declare class JwtManager {
+    private readonly fetchFn;
+    private readonly authBase;
+    private readonly now;
+    private readonly cache;
+    private readonly inFlight;
+    constructor(options?: JwtManagerOptions);
+    getJwt(apiKey: string): Promise<string>;
+    private fetchJwt;
+}
+export {};

package/dist/auth/jwt-manager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/auth/api-key.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveApiKey = resolveApiKey;
+function resolveApiKey(options) {
+    if (options?.apiKey)
+        return options.apiKey;
+    if (process.env.WINDSURF_API_KEY)
+        return process.env.WINDSURF_API_KEY;
+    throw new Error('WINDSURF_API_KEY is required');
+}

package/dist/cjs/auth/api-key.test.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const api_key_1 = require("./api-key");
+(0, vitest_1.describe)('api key resolver', () => {
+    const ORIGINAL = process.env.WINDSURF_API_KEY;
+    (0, vitest_1.afterEach)(() => {
+        // restore original env to avoid leakage
+        if (ORIGINAL === undefined) {
+            delete process.env.WINDSURF_API_KEY;
+        }
+        else {
+            process.env.WINDSURF_API_KEY = ORIGINAL;
+        }
+    });
+    (0, vitest_1.it)('constructor', () => {
+        const key = (0, api_key_1.resolveApiKey)({ apiKey: 'ctor-key' });
+        (0, vitest_1.expect)(key).toBe('ctor-key');
+    });
+    (0, vitest_1.it)('env', () => {
+        process.env.WINDSURF_API_KEY = 'test-key';
+        const key = (0, api_key_1.resolveApiKey)();
+        (0, vitest_1.expect)(key).toBe('test-key');
+    });
+    (0, vitest_1.it)('missing', () => {
+        delete process.env.WINDSURF_API_KEY;
+        (0, vitest_1.expect)(() => (0, api_key_1.resolveApiKey)()).toThrowError(new Error('WINDSURF_API_KEY is required'));
+    });
+});

package/dist/cjs/auth/jwt-manager.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwtManager = exports.AUTH_BASE = void 0;
+const protobuf_js_1 = require("../protocol/protobuf.js");
+exports.AUTH_BASE = 'https://server.self-serve.windsurf.com/exa.auth_pb.AuthService';
+const WS_APP = 'windsurf';
+const WS_APP_VER = process.env.WS_APP_VER ?? '1.48.2';
+const WS_LS_VER = process.env.WS_LS_VER ?? '1.9544.35';
+const JWT_PATTERN = /eyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*/;
+class JwtManager {
+    fetchFn;
+    authBase;
+    now;
+    cache = new Map();
+    inFlight = new Map();
+    constructor(options = {}) {
+        this.fetchFn = options.fetch ?? fetch;
+        this.authBase = options.authBase ?? exports.AUTH_BASE;
+        this.now = options.now ?? Date.now;
+    }
+    async getJwt(apiKey) {
+        if (!apiKey) {
+            throw new Error('API key is required');
+        }
+        const nowSeconds = Math.floor(this.now() / 1000);
+        const cached = this.cache.get(apiKey);
+        if (cached && cached.expiresAt > nowSeconds + 60) {
+            return cached.token;
+        }
+        const inFlight = this.inFlight.get(apiKey);
+        if (inFlight) {
+            return inFlight;
+        }
+        const pending = this.fetchJwt(apiKey)
+            .then((token) => {
+            const expiresAt = getJwtExp(token) || Math.floor(this.now() / 1000) + 3600;
+            this.cache.set(apiKey, { token, expiresAt });
+            return token;
+        })
+            .finally(() => {
+            this.inFlight.delete(apiKey);
+        });
+        this.inFlight.set(apiKey, pending);
+        return pending;
+    }
+    async fetchJwt(apiKey) {
+        const metadata = new protobuf_js_1.ProtobufEncoder();
+        metadata.writeString(1, WS_APP);
+        metadata.writeString(2, WS_APP_VER);
+        metadata.writeString(3, apiKey);
+        metadata.writeString(4, 'zh-cn');
+        metadata.writeString(7, WS_LS_VER);
+        metadata.writeString(12, WS_APP);
+        metadata.writeBytes(30, Buffer.from([0x00, 0x01]));
+        const requestBody = new protobuf_js_1.ProtobufEncoder();
+        requestBody.writeMessage(1, metadata);
+        const response = await this.fetchFn(`${this.authBase}/GetUserJwt`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/proto',
+                'Connect-Protocol-Version': '1',
+                'User-Agent': 'connect-go/1.18.1 (go1.25.5)',
+            },
+            body: requestBody.toBuffer(),
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        const bytes = Buffer.from(await response.arrayBuffer());
+        const token = extractJwt(bytes);
+        if (!token) {
+            throw new Error('Failed to extract JWT from GetUserJwt response');
+        }
+        return token;
+    }
+}
+exports.JwtManager = JwtManager;
+function extractJwt(value) {
+    const match = value.toString('utf8').match(JWT_PATTERN);
+    return match?.[0] ?? null;
+}
+function getJwtExp(jwt) {
+    try {
+        const payloadPart = jwt.split('.')[1];
+        if (!payloadPart) {
+            return 0;
+        }
+        const payload = JSON.parse(Buffer.from(payloadPart, 'base64url').toString('utf8'));
+        return typeof payload.exp === 'number' ? payload.exp : 0;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/cjs/auth/jwt-manager.test.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const protobuf_js_1 = require("../protocol/protobuf.js");
+const jwt_manager_js_1 = require("./jwt-manager.js");
+function makeJwt(exp, tag) {
+    const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+    const payload = Buffer.from(JSON.stringify({ exp, tag })).toString('base64url');
+    return `${header}.${payload}.signature`;
+}
+function makeJwtResponse(token) {
+    const encoder = new protobuf_js_1.ProtobufEncoder();
+    encoder.writeString(1, `prefix:${token}:suffix`);
+    return new Response(Uint8Array.from(encoder.toBuffer()), { status: 200 });
+}
+function bufferFromBody(body) {
+    if (body == null) {
+        return Buffer.alloc(0);
+    }
+    if (typeof body === 'string') {
+        return Buffer.from(body, 'utf8');
+    }
+    if (body instanceof ArrayBuffer) {
+        return Buffer.from(body);
+    }
+    if (ArrayBuffer.isView(body)) {
+        return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+    }
+    throw new Error(`Unsupported request body type: ${typeof body}`);
+}
+(0, vitest_1.describe)('jwt manager fetch', () => {
+    (0, vitest_1.it)('fetch exchanges api key to jwt and caches result', async () => {
+        const exp = 4_000_000_000;
+        const token = makeJwt(exp, 'first');
+        const calls = [];
+        const fakeFetch = async (input, init) => {
+            calls.push({ input, init });
+            return makeJwtResponse(token);
+        };
+        const manager = new jwt_manager_js_1.JwtManager({ fetch: fakeFetch, now: () => (exp - 3_600) * 1000 });
+        const jwt1 = await manager.getJwt('test-api-key');
+        const jwt2 = await manager.getJwt('test-api-key');
+        (0, vitest_1.expect)(jwt1).toBe(token);
+        (0, vitest_1.expect)(jwt2).toBe(token);
+        (0, vitest_1.expect)(calls).toHaveLength(1);
+        (0, vitest_1.expect)(calls[0]?.input).toBe(`${jwt_manager_js_1.AUTH_BASE}/GetUserJwt`);
+        (0, vitest_1.expect)(calls[0]?.init?.method).toBe('POST');
+        (0, vitest_1.expect)(new Headers(calls[0]?.init?.headers).get('content-type')).toBe('application/proto');
+        const requestBody = bufferFromBody(calls[0]?.init?.body);
+        (0, vitest_1.expect)(requestBody.length).toBeGreaterThan(0);
+        (0, vitest_1.expect)(requestBody.toString('utf8')).toContain('test-api-key');
+    });
+});
+(0, vitest_1.describe)('jwt manager expiry', () => {
+    (0, vitest_1.it)('expiry refreshes token when less than sixty seconds remain', async () => {
+        let nowMs = 0;
+        const token1 = makeJwt(10_000, 'first');
+        const token2 = makeJwt(20_000, 'second');
+        const queue = [makeJwtResponse(token1), makeJwtResponse(token2)];
+        let callCount = 0;
+        const fakeFetch = async () => {
+            callCount += 1;
+            const next = queue.shift();
+            if (!next) {
+                throw new Error('No fake fetch response queued');
+            }
+            return next;
+        };
+        const manager = new jwt_manager_js_1.JwtManager({ fetch: fakeFetch, now: () => nowMs });
+        const first = await manager.getJwt('exp-api-key');
+        nowMs = (10_000 - 59) * 1000;
+        const second = await manager.getJwt('exp-api-key');
+        (0, vitest_1.expect)(first).toBe(token1);
+        (0, vitest_1.expect)(second).toBe(token2);
+        (0, vitest_1.expect)(callCount).toBe(2);
+    });
+});
+(0, vitest_1.describe)('jwt manager concurrent', () => {
+    (0, vitest_1.it)('concurrent getJwt calls share one in-flight fetch', async () => {
+        const token = makeJwt(50_000, 'concurrent');
+        let fetchCalls = 0;
+        let resolveFetch;
+        const pending = new Promise((resolve) => {
+            resolveFetch = resolve;
+        });
+        const fakeFetch = async () => {
+            fetchCalls += 1;
+            return pending;
+        };
+        const manager = new jwt_manager_js_1.JwtManager({ fetch: fakeFetch, now: () => 0 });
+        const p1 = manager.getJwt('same-key');
+        const p2 = manager.getJwt('same-key');
+        resolveFetch(makeJwtResponse(token));
+        const [jwt1, jwt2] = await Promise.all([p1, p2]);
+        (0, vitest_1.expect)(fetchCalls).toBe(1);
+        (0, vitest_1.expect)(jwt1).toBe(token);
+        (0, vitest_1.expect)(jwt2).toBe(token);
+    });
+});

package/dist/cjs/conversion/prompt-converter.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertPrompt = convertPrompt;
+function toContentString(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    return JSON.stringify(value);
+}
+function convertPrompt(prompt) {
+    const messages = [];
+    for (const message of prompt) {
+        if (message.role === 'system') {
+            messages.push({ role: 5, content: message.content });
+            continue;
+        }
+        if (message.role === 'user') {
+            const text = message.content
+                .filter((part) => part.type === 'text')
+                .map((part) => part.text)
+                .join('');
+            messages.push({ role: 1, content: text });
+            continue;
+        }
+        if (message.role === 'assistant') {
+            for (const part of message.content) {
+                if (part.type === 'text') {
+                    messages.push({ role: 2, content: part.text });
+                    continue;
+                }
+                if (part.type === 'tool-call') {
+                    messages.push({
+                        role: 2,
+                        content: '',
+                        metadata: {
+                            toolCallId: part.toolCallId,
+                            toolName: part.toolName,
+                            toolArgsJson: JSON.stringify(part.args),
+                        },
+                    });
+                }
+            }
+            continue;
+        }
+        // Tool result messages - use refCallId to reference the original tool call
+        for (const part of message.content) {
+            messages.push({
+                role: 4,
+                content: toContentString(part.result),
+                metadata: {
+                    refCallId: part.toolCallId, // This links back to the tool call
+                },
+            });
+        }
+    }
+    return messages;
+}