7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
TypeScript
feat(providers): add Sail Research adapter (#1125)
Tashfeen36de660fab25
diff --git a/client/src/components/keys/shared.tsx b/client/src/components/keys/shared.tsxindex 9ef39594..0be6b2d1 100644--- a/client/src/components/keys/shared.tsx+++ b/client/src/components/keys/shared.tsx@@ -29,6 +29,7 @@ export const PLATFORMS: { value: Platform; label: string; url: string; keyless?:{ value: 'google', label: 'Google AI Studio', url: 'https://aistudio.google.com/apikey' },{ value: 'groq', label: 'Groq', url: 'https://console.groq.com/keys' },{ value: 'cerebras', label: 'Cerebras', url: 'https://cloud.cerebras.ai' },+ { value: 'sail', label: 'Sail Research ($5 monthly with payment method)', url: 'https://app.sailresearch.com' },{ value: 'bai', label: 'B.AI (promotional free model)', url: 'https://b.ai' },{ value: 'nvidia', label: 'NVIDIA NIM', url: 'https://build.nvidia.com/settings/api-keys' },{ value: 'mistral', label: 'Mistral', url: 'https://console.mistral.ai/api-keys/' },diff --git a/client/src/lib/routing.ts b/client/src/lib/routing.tsindex 10931343..68be2db9 100644--- a/client/src/lib/routing.ts+++ b/client/src/lib/routing.ts@@ -376,6 +376,7 @@ export const platformColors: Record<string, string> = {google: '#4285f4',groq: '#f55036',cerebras: '#8b5cf6',+ sail: '#0ea5e9',bai: '#111827',nvidia: '#76b900',mistral: '#f59e0b',diff --git a/docs/providers/01-supported-platforms.md b/docs/providers/01-supported-platforms.mdindex 2c31d133..7809d08f 100644--- a/docs/providers/01-supported-platforms.md+++ b/docs/providers/01-supported-platforms.md@@ -1,12 +1,12 @@# Supported platforms-The `Platform` union in [`shared/types.ts` (line 59)](../../shared/types.ts) is the single source of truth for platform identity; the runtime registry in [`server/src/providers/index.ts`](../../server/src/providers/index.ts) must match it. The union currently declares **41 members**:+The `Platform` union in [`shared/types.ts` (line 59)](../../shared/types.ts) is the single source of truth for platform identity; the runtime registry in [`server/src/providers/index.ts`](../../server/src/providers/index.ts) must match it. The union currently declares **42 members**:-- **39 built-in platforms** registered as adapters at startup,-- plus the **`custom`** placeholder (a real OpenAI-compatible adapter built per API key, since its base URL is user-supplied), giving **40 entries** in the registry map,+- **40 built-in platforms** registered as adapters at startup,+- plus the **`custom`** placeholder (a real OpenAI-compatible adapter built per API key, since its base URL is user-supplied), giving **41 entries** in the registry map,- plus **`sambanova`**, retained in the type union but no longer registered — it was dropped in V23 (June 2026) when its free tier was permanently retired (every chat call returns 402 "payment method required" once the one-time $5 trial credit lapses).-Of the 39 built-in platforms, **7 use dedicated native adapters** and **32 ride `OpenAICompatProvider`** against a provider-specific base URL. Three platforms are registered keyless (`kilo`, `ovh`, and `aihorde`, which auto-configures with its documented anonymous sentinel key). The public catalog headline in the README counts ~34 free providers / 474 model families / 635 free endpoints (~7.4 billion tokens/month of listed capacity) — fewer than the union because several registered gateways keep their free rosters in the hosted catalog rather than shipping them to every binary.+Of the 40 built-in platforms, **8 use dedicated native adapters** and **32 ride `OpenAICompatProvider`** against a provider-specific base URL. Three platforms are registered keyless (`kilo`, `ovh`, and `aihorde`, which auto-configures with its documented anonymous sentinel key). The public catalog headline in the README counts ~34 free providers / 474 model families / 635 free endpoints (~7.4 billion tokens/month of listed capacity) — fewer than the union because several registered gateways keep their free rosters in the hosted catalog rather than shipping them to every binary.## Catalog@@ -15,6 +15,7 @@ Of the 39 built-in platforms, **7 use dedicated native adapters** and **32 ride| `google` | Google Gemini | Keyed | Native (`GoogleProvider`) | Gemini wire format; 60s default timeout because Gemma reasoning variants take 20–60s on cold start. || `groq` | Groq | Keyed | OpenAI-compat | Standard compatible endpoint at `api.groq.com/openai/v1`. || `cerebras` | Cerebras | Keyed | OpenAI-compat | `api.cerebras.ai/v1`. |+| `sail` | Sail Research | Keyed (payment method required for recurring credit) | Native (`SailProvider`) | Stable `/v1/responses` integration submits background jobs and polls them to completion; flex-only models use the `flex` completion window. Sail grants $5 in monthly credits while a payment method is attached, then charges usage beyond that credit. || `bai` | B.AI | Keyed | OpenAI-compat | Gateway added in #918; only catalog row is a limited-time 0-credit promo, kept in the hosted catalog. || `anyapi` | AnyAPI | Keyed | OpenAI-compat | Free tier $0/no card/recurring, capped at 100K tokens/day over "free and basic" models; no RPM/RPD published (#772). Model ids arrive via catalog-sync, never seeded blind. || `nvidia` | NVIDIA NIM | Keyed | OpenAI-compat | `parallel_tool_calls` pinned false (#255); 180s timeout doubles as streaming first-byte grace (#584). |diff --git a/docs/providers/03-adding-a-new-provider.md b/docs/providers/03-adding-a-new-provider.mdindex c8c42b26..f189d16b 100644--- a/docs/providers/03-adding-a-new-provider.md+++ b/docs/providers/03-adding-a-new-provider.md@@ -1,6 +1,6 @@# Adding a new provider-A contributor walkthrough that mirrors how the existing 37 built-in platforms are wired. Read [`server/src/providers/index.ts`](../../server/src/providers/index.ts) alongside this guide — it is both the registry and the best documentation of per-platform judgment calls.+A contributor walkthrough that mirrors how the existing 40 built-in platforms are wired. Read [`server/src/providers/index.ts`](../../server/src/providers/index.ts) alongside this guide — it is both the registry and the best documentation of per-platform judgment calls.## 1. Declare the platformdiff --git a/docs/providers/CHANGELOG.md b/docs/providers/CHANGELOG.mdindex 870f74ec..3a45e4ab 100644--- a/docs/providers/CHANGELOG.md+++ b/docs/providers/CHANGELOG.md@@ -4,6 +4,7 @@ Revision history for `docs/providers/`, listing the upstream commits that shaped| Commit | Date | Summary || --- | --- | --- |+| Unreleased | 2026-09-01 | Add the native Sail Research background Responses adapter and catalog-ready platform wiring. || `ef4519a` | 2026-08-23 | feat(providers): add xkiro.com as OpenAI-compatible provider (#967) || `68ddca4` | 2026-08-23 | feat(providers): add UnoRouter (unorouter.com) as OpenAI-compatible provider (#875) || `df1000a` | 2026-08-20 | Qianfan/Volcengine Ark/LongCat/iFlytek Spark (#936) — four Chinese domestic OpenAI-compat platforms. |diff --git a/server/src/__tests__/lib/key-parser.test.ts b/server/src/__tests__/lib/key-parser.test.tsindex db0f0a57..1744bb68 100644--- a/server/src/__tests__/lib/key-parser.test.ts+++ b/server/src/__tests__/lib/key-parser.test.ts@@ -65,6 +65,8 @@ describe('key parser', () => {expect(detectPlatform('ANY_API_')).toBe('anyapi');expect(detectPlatform('BAI_')).toBe('bai');expect(detectPlatform('B_AI_')).toBe('bai');+ expect(detectPlatform('SAIL_')).toBe('sail');+ expect(detectPlatform('SAIL_RESEARCH_')).toBe('sail');expect(detectPlatform('SAMBANOVA_')).toBeNull();});@@ -80,6 +82,7 @@ describe('key parser', () => {expect(AUTH_JSON_PROVIDER_MAP['model-scope']).toBe('modelscope');expect(AUTH_JSON_PROVIDER_MAP['any-api']).toBe('anyapi');expect(AUTH_JSON_PROVIDER_MAP['b-ai']).toBe('bai');+ expect(AUTH_JSON_PROVIDER_MAP['sail-research']).toBe('sail');const result = parseAuthJson(JSON.stringify({credential_pool: {gemini: [{ id: '1', label: 'Gemini', auth_type: 'api_key', access_token: 'AIza-test' }],diff --git a/server/src/__tests__/providers/sail.test.ts b/server/src/__tests__/providers/sail.test.tsnew file mode 100644index 00000000..c5ab14d9--- /dev/null+++ b/server/src/__tests__/providers/sail.test.ts@@ -0,0 +1,168 @@+import { afterEach, describe, expect, it, vi } from 'vitest';+import { SailProvider } from '../../providers/sail.js';++function jsonResponse(body: unknown, status = 200): Response {+ return new Response(JSON.stringify(body), {+ status,+ headers: { 'Content-Type': 'application/json' },+ });+}++function completed(id = 'resp_done', model = 'zai-org/GLM-5.2-FP8') {+ return {+ id,+ model,+ created_at: 1_700_000_000,+ status: 'completed',+ output: [{+ type: 'message',+ role: 'assistant',+ content: [{ type: 'output_text', text: 'OK' }],+ }],+ usage: {+ input_tokens: 12,+ output_tokens: 3,+ total_tokens: 15,+ input_tokens_details: { cached_tokens: 2 },+ output_tokens_details: { reasoning_tokens: 1 },+ },+ };+}++describe('SailProvider', () => {+ afterEach(() => vi.restoreAllMocks());++ it('submits a background Responses job, polls it, and normalizes the result', async () => {+ const calls: Array<{ url: string; init?: RequestInit; body?: any }> = [];+ vi.spyOn(global, 'fetch').mockImplementation(async (url, init) => {+ calls.push({+ url: String(url),+ init,+ body: init?.body ? JSON.parse(String(init.body)) : undefined,+ });+ if (calls.length === 1) {+ return jsonResponse({ id: 'resp_1', status: 'queued' }, 202);+ }+ return jsonResponse(completed('resp_1'));+ });++ const provider = new SailProvider({ pollIntervalMs: 0, timeoutMs: 1_000 });+ const result = await provider.chatCompletion(+ 'sail-key',+ [{ role: 'user', content: 'Reply OK' }],+ 'zai-org/GLM-5.2-FP8',+ { max_tokens: 64, reasoning_effort: 'none', temperature: 0 },+ );++ expect(calls.map(call => call.url)).toEqual([+ 'https://api.sailresearch.com/v1/responses',+ 'https://api.sailresearch.com/v1/responses/resp_1',+ ]);+ expect((calls[0].init?.headers as Record<string, string>).Authorization).toBe('Bearer sail-key');+ expect(calls[0].body).toMatchObject({+ model: 'zai-org/GLM-5.2-FP8',+ input: [{ role: 'user', content: 'Reply OK' }],+ background: true,+ max_output_tokens: 64,+ metadata: { completion_window: 'asap' },+ reasoning: { effort: 'none' },+ temperature: 0,+ });+ expect(result.choices[0].message.content).toBe('OK');+ expect(result.choices[0].finish_reason).toBe('stop');+ expect(result.usage).toEqual({+ prompt_tokens: 12,+ completion_tokens: 3,+ total_tokens: 15,+ prompt_tokens_details: { cached_tokens: 2 },+ completion_tokens_details: { reasoning_tokens: 1 },+ });+ expect(result._routed_via).toEqual({ platform: 'sail', model: 'zai-org/GLM-5.2-FP8' });+ });++ it('maps Chat Completions tools and tool history onto Responses items', async () => {+ let body: any;+ vi.spyOn(global, 'fetch').mockImplementation(async (_url, init) => {+ body = JSON.parse(String(init?.body));+ return jsonResponse({+ id: 'resp_tools',+ model: 'moonshotai/Kimi-K2.6',+ status: 'completed',+ output: [{ type: 'function_call', call_id: 'call_new', name: 'weather', arguments: '{"city":"Dublin"}' }],+ usage: { input_tokens: 10, output_tokens: 5, total_tokens: 15 },+ });+ });++ const provider = new SailProvider({ pollIntervalMs: 0 });+ const result = await provider.chatCompletion('k', [+ { role: 'assistant', content: '', tool_calls: [{ id: 'call_old', type: 'function', function: { name: 'weather', arguments: '{"city":"Cork"}' } }] },+ { role: 'tool', content: 'rain', tool_call_id: 'call_old' },+ { role: 'user', content: 'How about Dublin?' },+ ], 'moonshotai/Kimi-K2.6', {+ tools: [{ type: 'function', function: { name: 'weather', description: 'Get weather', parameters: { type: 'object' }, strict: true } }],+ tool_choice: { type: 'function', function: { name: 'weather' } },+ });++ expect(body.input).toEqual([+ { type: 'function_call', call_id: 'call_old', name: 'weather', arguments: '{"city":"Cork"}' },+ { type: 'function_call_output', call_id: 'call_old', output: 'rain' },+ { role: 'user', content: 'How about Dublin?' },+ ]);+ expect(body.tools[0]).toMatchObject({ type: 'function', name: 'weather', strict: true });+ expect(body.tool_choice).toEqual({ type: 'function', name: 'weather' });+ expect(result.choices[0].finish_reason).toBe('tool_calls');+ expect(result.choices[0].message.tool_calls?.[0]).toMatchObject({+ id: 'call_new',+ function: { name: 'weather', arguments: '{"city":"Dublin"}' },+ });+ });++ it('uses flex background mode and clamps gpt-oss none reasoning to low', async () => {+ const bodies: any[] = [];+ vi.spyOn(global, 'fetch').mockImplementation(async (_url, init) => {+ const body = JSON.parse(String(init?.body));+ bodies.push(body);+ return jsonResponse(completed(`resp_${bodies.length}`, body.model));+ });+ const provider = new SailProvider({ pollIntervalMs: 0 });++ await provider.chatCompletion('k', [{ role: 'user', content: 'hi' }],+ 'nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16');+ await provider.chatCompletion('k', [{ role: 'user', content: 'hi' }],+ 'openai/gpt-oss-120b', { reasoning_effort: 'none' });++ expect(bodies[0].metadata).toEqual({ completion_window: 'flex' });+ expect(bodies[0].background).toBe(true);+ expect(bodies[1].metadata).toEqual({ completion_window: 'asap' });+ expect(bodies[1].reasoning).toEqual({ effort: 'low' });+ });++ it('synthesizes streaming chunks from the completed background response', async () => {+ vi.spyOn(global, 'fetch').mockResolvedValue(jsonResponse(completed()));+ const provider = new SailProvider({ pollIntervalMs: 0 });+ const chunks = [];+ for await (const chunk of provider.streamChatCompletion(+ 'k', [{ role: 'user', content: 'hi' }], 'zai-org/GLM-5.2-FP8',+ )) chunks.push(chunk);++ expect(chunks.map(chunk => chunk.choices[0].delta)).toEqual([+ { role: 'assistant' },+ { content: 'OK' },+ {},+ ]);+ expect(chunks.at(-1)?.choices[0].finish_reason).toBe('stop');+ });++ it('validates keys against the authenticated model roster and preserves errors', async () => {+ vi.spyOn(global, 'fetch')+ .mockResolvedValueOnce(jsonResponse({ object: 'list', data: [] }))+ .mockResolvedValueOnce(jsonResponse({ error: { message: 'Invalid API key' } }, 401));+ const provider = new SailProvider();++ await expect(provider.validateKey('good')).resolves.toBe(true);+ await expect(provider.validateKey('bad')).resolves.toEqual({+ valid: false,+ error: 'Sail Research key validation failed (HTTP 401): Invalid API key',+ });+ });+});diff --git a/server/src/lib/key-parser.ts b/server/src/lib/key-parser.tsindex 44a73243..95158d85 100644--- a/server/src/lib/key-parser.ts+++ b/server/src/lib/key-parser.ts@@ -42,6 +42,9 @@ export const PREFIX_MAP: Record<string, string> = {GEMINI_: 'google',GROQ_: 'groq',CEREBRAS_: 'cerebras',+ SAIL_: 'sail',+ SAILRESEARCH_: 'sail',+ SAIL_RESEARCH_: 'sail',BAI_: 'bai',B_AI_: 'bai',NVIDIA_: 'nvidia',@@ -102,6 +105,9 @@ export const AUTH_JSON_PROVIDER_MAP: Record<string, string> = {gemini: 'google',google: 'google',groq: 'groq',+ sail: 'sail',+ 'sail-research': 'sail',+ sailresearch: 'sail',bai: 'bai','b-ai': 'bai',openrouter: 'openrouter',diff --git a/server/src/lib/sampling-params.ts b/server/src/lib/sampling-params.tsindex 1e1ca80b..1ba4ac8b 100644--- a/server/src/lib/sampling-params.ts+++ b/server/src/lib/sampling-params.ts@@ -238,6 +238,13 @@ export const GITHUB_MAX_OUTPUT_TOKENS = 400;// silently no-op'ing the policy; the string-typed accessors below cast at the// boundary since routes carry platform ids as plain strings.export const PLATFORM_PARAM_POLICIES: Partial<Record<Platform, PlatformParamPolicy>> = {+ // Sail's stable Responses API accepts temperature/top_p, JSON Schema output,+ // tools and reasoning effort. The remaining Chat Completions knobs are not+ // supported and are intentionally omitted by the dedicated adapter.+ sail: {+ drop: ['top_k', 'min_p', 'seed', 'presence_penalty', 'frequency_penalty', 'repetition_penalty', 'logit_bias', 'logprobs', 'top_logprobs'],+ jsonObjectToSchema: true,+ },// Mistral's API is strict (422 on unknown body keys) and names its seed// `random_seed`. It has no top_k/min_p/logit_bias/logprobs equivalents, and// no reasoning_effort (Magistral's reasoning has no request-side knob).diff --git a/server/src/providers/index.ts b/server/src/providers/index.tsindex 6a6e4fbf..5b55fc03 100644--- a/server/src/providers/index.ts+++ b/server/src/providers/index.ts@@ -8,6 +8,7 @@ import { AIHordeProvider } from './aihorde.js';import { ModelScopeProvider } from './modelscope.js';import { PollinationsProvider } from './pollinations.js';import { ZhipuProvider } from './zhipu.js';+import { SailProvider } from './sail.js';const providers = new Map<Platform, BaseProvider>();@@ -34,6 +35,14 @@ register(new OpenAICompatProvider({baseUrl: 'https://api.cerebras.ai/v1',}));+// Sail Research — its stable API is /v1/responses and all calls are submitted+// as background jobs, then polled. The dedicated adapter translates terminal+// Responses objects back to Chat Completions and handles flex-only models.+// Sail grants $5 in free credits every month when a payment method is attached;+// usage beyond that grant is pay-as-you-go. Live-tested 2026-09-01. Model rows+// stay in Oracle so the existing Premium-now / Free-after-30-days gate applies.+register(new SailProvider());+// B.AI — OpenAI-compatible gateway. Provider support is first-class, but the// only free catalog row currently published is a limited-time 0-credit promo;// keep commercial eligibility in the hosted catalog rather than seeding it.diff --git a/server/src/providers/sail.ts b/server/src/providers/sail.tsnew file mode 100644index 00000000..fe0b7aff--- /dev/null+++ b/server/src/providers/sail.ts@@ -0,0 +1,404 @@+import type {+ ChatCompletionChunk,+ ChatCompletionResponse,+ ChatMessage,+ ChatToolCall,+ ChatToolChoice,+ Platform,+ TokenUsage,+} from '@freellmapi/shared/types.js';+import {+ BaseProvider,+ providerHttpError,+ type CompletionOptions,+ type KeyValidationResult,+} from './base.js';+import { contentToString } from '../lib/content.js';+import { resolveMaxTokens } from '../lib/sampling-params.js';+import {+ recordQuotaObservationsFromResponse,+ type QuotaObservationContext,+} from '../services/provider-quota.js';+import { providerTimeoutMs } from '../lib/provider-timeout.js';++const BASE_URL = 'https://api.sailresearch.com/v1';+const DEFAULT_TIMEOUT_MS = 10 * 60_000;+const DEFAULT_POLL_INTERVAL_MS = 1_000;+const POLL_REQUEST_TIMEOUT_MS = 30_000;++// Sail serves these models only through its best-effort flex completion window.+// Flex requests must use the Responses API in background mode and be polled.+const FLEX_ONLY_MODELS = new Set([+ 'Qwen/Qwen3.6-35B-A3B',+ 'nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16',+]);++type SailStatus = 'queued' | 'in_progress' | 'completed' | 'incomplete' | 'failed' | 'cancelled';++interface SailUsage {+ input_tokens?: number;+ output_tokens?: number;+ total_tokens?: number;+ input_tokens_details?: { cached_tokens?: number };+ output_tokens_details?: { reasoning_tokens?: number };+}++interface SailOutputContent {+ type?: string;+ text?: string;+}++interface SailOutputItem {+ id?: string;+ type?: string;+ role?: string;+ content?: SailOutputContent[];+ call_id?: string;+ name?: string;+ arguments?: string;+}++interface SailResponse {+ id?: string;+ model?: string;+ created_at?: number;+ status?: SailStatus;+ output?: SailOutputItem[];+ usage?: SailUsage;+ error?: { message?: string } | null;+ incomplete_details?: { reason?: string } | null;+}++interface SailProviderOptions {+ timeoutMs?: number;+ pollIntervalMs?: number;+}++/**+ * Sail Research adapter.+ *+ * Sail's stable surface is the OpenAI Responses API, not streaming Chat+ * Completions. Every request is submitted with `background: true`, then polled+ * until terminal. That is required for its flex-only models and avoids proxy+ * timeouts for core models that spend several minutes queued. The completed+ * Responses object is normalized back into FreeLLMAPI's Chat Completions shape;+ * streaming callers receive a small synthesized role/content/finish sequence.+ */+export class SailProvider extends BaseProvider {+ readonly platform: Platform = 'sail';+ readonly name = 'Sail Research';+ private readonly timeoutMs: number;+ private readonly pollIntervalMs: number;++ constructor(options: SailProviderOptions = {}) {+ super();+ this.timeoutMs = providerTimeoutMs('sail', options.timeoutMs ?? DEFAULT_TIMEOUT_MS);+ this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;+ }++ private authHeaders(apiKey: string): Record<string, string> {+ return {+ 'Authorization': `Bearer ${apiKey}`,+ 'Content-Type': 'application/json',+ };+ }++ private completionWindow(modelId: string): 'asap' | 'flex' {+ return FLEX_ONLY_MODELS.has(modelId) ? 'flex' : 'asap';+ }++ private reasoningEffort(modelId: string, options?: CompletionOptions): string | undefined {+ const requested = options?.reasoning_effort;+ if (!requested) return undefined;+ // Live API validation: gpt-oss rejects none/minimal and accepts+ // low/medium/high/xhigh/max. Clamp the two weaker OpenAI spellings to low.+ if (modelId === 'openai/gpt-oss-120b' && (requested === 'none' || requested === 'minimal')) {+ return 'low';+ }+ return requested;+ }++ /** Translate Chat Completions history into Responses input items. */+ private inputItems(messages: ChatMessage[]): Array<Record<string, unknown>> {+ const input: Array<Record<string, unknown>> = [];+ for (const message of messages) {+ const text = contentToString(message.content);+ if (message.role === 'tool') {+ input.push({+ type: 'function_call_output',+ call_id: message.tool_call_id ?? message.name ?? 'unknown_call',+ output: text,+ });+ continue;+ }++ if (text || !message.tool_calls?.length) {+ input.push({ role: message.role, content: text });+ }+ for (const call of message.tool_calls ?? []) {+ input.push({+ type: 'function_call',+ call_id: call.id,+ name: call.function.name,+ arguments: call.function.arguments,+ });+ }+ }+ return input;+ }++ private toolChoice(choice: ChatToolChoice | undefined): unknown {+ if (!choice || typeof choice === 'string') return choice;+ return { type: 'function', name: choice.function.name };+ }++ private textFormat(options?: CompletionOptions): Record<string, unknown> | undefined {+ const format = options?.response_format;+ if (!format) return undefined;+ if (format.type === 'json_schema') {+ return {+ type: 'json_schema',+ name: format.json_schema?.name ?? 'response',+ schema: format.json_schema?.schema ?? { type: 'object' },+ strict: format.json_schema?.strict ?? false,+ };+ }+ // Sail rejects Responses `json_object`; preserve the caller's intent with+ // a permissive JSON schema, the supported equivalent.+ return {+ type: 'json_schema',+ name: 'response',+ schema: { type: 'object', additionalProperties: true },+ strict: false,+ };+ }++ private buildBody(messages: ChatMessage[], modelId: string, options?: CompletionOptions): Record<string, unknown> {+ const maxOutputTokens = resolveMaxTokens(this.platform, options?.max_tokens);+ const reasoningEffort = this.reasoningEffort(modelId, options);+ const textFormat = this.textFormat(options);+ const tools = options?.tools?.map(tool => ({+ type: 'function',+ name: tool.function.name,+ description: tool.function.description,+ parameters: tool.function.parameters,+ strict: tool.function.strict,+ }));++ return {+ model: modelId,+ input: this.inputItems(messages),+ background: true,+ metadata: { completion_window: this.completionWindow(modelId) },+ ...(maxOutputTokens !== undefined ? { max_output_tokens: maxOutputTokens } : {}),+ ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),+ ...(options?.top_p !== undefined ? { top_p: options.top_p } : {}),+ ...(reasoningEffort ? { reasoning: { effort: reasoningEffort } } : {}),+ ...(tools?.length ? { tools } : {}),+ ...(options?.tool_choice !== undefined ? { tool_choice: this.toolChoice(options.tool_choice) } : {}),+ ...(textFormat ? { text: { format: textFormat } } : {}),+ // `stop`, `parallel_tool_calls`, seed/penalties/logprobs and multimodal+ // input are not supported on Sail's stable Responses API.+ };+ }++ private errorText(body: unknown, status: number, statusText: string): string {+ const parsed = body as { error?: { message?: unknown }; detail?: unknown; message?: unknown };+ if (typeof parsed?.error?.message === 'string' && parsed.error.message) return parsed.error.message;+ if (typeof parsed?.detail === 'string' && parsed.detail) return parsed.detail;+ if (typeof parsed?.message === 'string' && parsed.message) return parsed.message;+ return statusText || `HTTP ${status}`;+ }++ private recordQuota(res: Response, modelId: string | undefined, quotaContext?: QuotaObservationContext): void {+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'responses',+ });+ }++ private async parseResponse(res: Response): Promise<SailResponse> {+ const body = await res.json().catch(() => ({})) as SailResponse;+ if (!res.ok) {+ throw providerHttpError(+ res,+ `${this.name} API error ${res.status}: ${this.errorText(body, res.status, res.statusText)}`,+ body,+ );+ }+ return body;+ }++ private async wait(ms: number, signal?: AbortSignal): Promise<void> {+ if (ms <= 0) return;+ if (signal?.aborted) throw signal.reason ?? new Error('Sail request aborted');+ await new Promise<void>((resolve, reject) => {+ let timer: ReturnType<typeof setTimeout>;+ let onAbort: () => void;+ const finish = (error?: unknown) => {+ clearTimeout(timer);+ signal?.removeEventListener('abort', onAbort);+ if (error !== undefined) reject(error);+ else resolve();+ };+ onAbort = () => {+ finish(signal?.reason ?? new Error('Sail request aborted'));+ };+ timer = setTimeout(() => finish(), ms);+ signal?.addEventListener('abort', onAbort, { once: true });+ });+ }++ private async runResponse(+ apiKey: string,+ messages: ChatMessage[],+ modelId: string,+ options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,+ ): Promise<SailResponse> {+ const timeoutMs = options?.timeoutMs ?? this.timeoutMs;+ const startedAt = Date.now();+ const remaining = () => timeoutMs <= 0 ? POLL_REQUEST_TIMEOUT_MS : Math.max(1, timeoutMs - (Date.now() - startedAt));+ const requestTimeout = () => Math.min(POLL_REQUEST_TIMEOUT_MS, remaining());++ const submit = await this.fetchWithTimeout(`${BASE_URL}/responses`, {+ method: 'POST',+ headers: this.authHeaders(apiKey),+ body: JSON.stringify(this.buildBody(messages, modelId, options)),+ }, requestTimeout(), { signal: options?.signal, timeoutBounds: 'request' });+ this.recordQuota(submit, modelId, quotaContext);+ let response = await this.parseResponse(submit);++ if (!response.id) throw new Error(`${this.name} returned no response id`);+ const responseId = response.id;+ while (response.status === 'queued' || response.status === 'in_progress') {+ if (timeoutMs > 0 && Date.now() - startedAt >= timeoutMs) {+ throw new Error(`${this.name} response ${responseId} did not complete within ${timeoutMs}ms`);+ }+ await this.wait(Math.min(this.pollIntervalMs, remaining()), options?.signal);+ const poll = await this.fetchWithTimeout(`${BASE_URL}/responses/${encodeURIComponent(responseId)}`, {+ method: 'GET',+ headers: this.authHeaders(apiKey),+ }, requestTimeout(), { signal: options?.signal, timeoutBounds: 'request' });+ this.recordQuota(poll, modelId, quotaContext);+ response = await this.parseResponse(poll);+ }++ if (response.status === 'failed' || response.status === 'cancelled') {+ const reason = response.error?.message ?? response.status;+ throw new Error(`${this.name} response ${response.id} ${reason}`);+ }+ if (response.status !== 'completed' && response.status !== 'incomplete') {+ throw new Error(`${this.name} returned unexpected response status: ${response.status ?? 'missing'}`);+ }+ return response;+ }++ private usageOf(usage?: SailUsage): TokenUsage {+ return {+ prompt_tokens: usage?.input_tokens ?? 0,+ completion_tokens: usage?.output_tokens ?? 0,+ total_tokens: usage?.total_tokens ?? (usage?.input_tokens ?? 0) + (usage?.output_tokens ?? 0),+ prompt_tokens_details: { cached_tokens: usage?.input_tokens_details?.cached_tokens ?? 0 },+ completion_tokens_details: { reasoning_tokens: usage?.output_tokens_details?.reasoning_tokens ?? 0 },+ };+ }++ private normalize(response: SailResponse, modelId: string): ChatCompletionResponse {+ const text = (response.output ?? [])+ .filter(item => item.type === 'message')+ .flatMap(item => item.content ?? [])+ .filter(content => content.type === 'output_text' && typeof content.text === 'string')+ .map(content => content.text as string)+ .join('');+ const toolCalls: ChatToolCall[] = (response.output ?? [])+ .filter(item => item.type === 'function_call' && typeof item.name === 'string')+ .map((item, index) => ({+ id: item.call_id ?? item.id ?? `call_sail_${index + 1}`,+ type: 'function',+ function: {+ name: item.name as string,+ arguments: item.arguments ?? '{}',+ },+ }));+ const incomplete = response.status === 'incomplete';+ const finishReason = toolCalls.length > 0+ ? 'tool_calls'+ : incomplete && response.incomplete_details?.reason === 'max_output_tokens' ? 'length' : 'stop';+ const out: ChatCompletionResponse = {+ id: response.id ?? this.makeId(),+ object: 'chat.completion',+ created: response.created_at ?? Math.floor(Date.now() / 1000),+ model: response.model ?? modelId,+ choices: [{+ index: 0,+ message: {+ role: 'assistant',+ content: text,+ ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),+ },+ finish_reason: finishReason,+ }],+ usage: this.usageOf(response.usage),+ };+ out._routed_via = { platform: this.platform, model: modelId };+ return out;+ }++ async chatCompletion(+ apiKey: string,+ messages: ChatMessage[],+ modelId: string,+ options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,+ ): Promise<ChatCompletionResponse> {+ return this.normalize(+ await this.runResponse(apiKey, messages, modelId, options, quotaContext),+ modelId,+ );+ }++ async *streamChatCompletion(+ apiKey: string,+ messages: ChatMessage[],+ modelId: string,+ options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,+ ): AsyncGenerator<ChatCompletionChunk> {+ const data = await this.chatCompletion(apiKey, messages, modelId, options, quotaContext);+ const choice = data.choices[0];+ const content = contentToString(choice.message.content);+ const toolCalls = choice.message.tool_calls ?? [];+ const base = {+ id: data.id,+ object: 'chat.completion.chunk' as const,+ created: data.created,+ model: data.model,+ };+ yield { ...base, choices: [{ index: 0, delta: { role: 'assistant' }, finish_reason: null }] };+ if (content) yield { ...base, choices: [{ index: 0, delta: { content }, finish_reason: null }] };+ if (toolCalls.length > 0) {+ yield { ...base, choices: [{ index: 0, delta: { tool_calls: toolCalls }, finish_reason: null }] };+ }+ yield { ...base, choices: [{ index: 0, delta: {}, finish_reason: choice.finish_reason }] };+ }++ async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<KeyValidationResult> {+ const res = await this.fetchWithTimeout(`${BASE_URL}/models`, {+ method: 'GET',+ headers: this.authHeaders(apiKey),+ }, POLL_REQUEST_TIMEOUT_MS, { timeoutBounds: 'request' });+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'models',+ });+ return this.validationResult(res);+ }+}diff --git a/server/src/routes/keys.ts b/server/src/routes/keys.tsindex b104ca1c..00c003a7 100644--- a/server/src/routes/keys.ts+++ b/server/src/routes/keys.ts@@ -30,7 +30,7 @@ export const keysRouter = Router();// was dropped in V4 and re-added in V13 via the router.huggingface.co route.// SambaNova was dropped in V23 (free tier permanently retired).const PLATFORMS = [- 'google', 'groq', 'cerebras', 'bai', 'nvidia', 'mistral',+ 'google', 'groq', 'cerebras', 'sail', 'bai', 'nvidia', 'mistral','openrouter', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama','kilo', 'pollinations', 'llm7', 'huggingface', 'opencode', 'ovh', 'agnes', 'reka', 'siliconflow','routeway', 'bazaarlink', 'ainative', 'aion', 'anyapi', 'requesty', 'navy', 'nara', 'sealion', 'orcarouter', 'unorouter', 'xkiro', 'modelscope',diff --git a/server/src/services/provider-quota.ts b/server/src/services/provider-quota.tsindex 5835e48a..bf4b1a41 100644--- a/server/src/services/provider-quota.ts+++ b/server/src/services/provider-quota.ts@@ -115,6 +115,7 @@ function inferPoolForPlatform(platform: Platform, modelId?: string | null): striif (platform === 'google') return 'google::project';if (platform === 'groq') return 'groq::account';if (platform === 'cerebras') return 'cerebras::shared';+ if (platform === 'sail') return 'sail::monthly-credit';if (platform === 'bai') return 'bai::promo';if (platform === 'sambanova') return 'sambanova::shared';if (platform === 'nvidia') return 'nvidia::credit-pool';@@ -162,7 +163,7 @@ function inferPoolForPlatform(platform: Platform, modelId?: string | null): stri}function isSharedPool(platform: Platform): boolean {- return ['openrouter', 'google', 'groq', 'cerebras', 'bai', 'sambanova', 'nvidia', 'mistral', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama', 'kilo', 'pollinations', 'llm7', 'huggingface', 'opencode', 'routeway', 'bazaarlink', 'ainative', 'aion', 'requesty', 'navy', 'nara', 'sealion', 'orcarouter', 'unorouter', 'xkiro', 'anyapi', 'modelscope', 'aihorde'].includes(platform);+ return ['openrouter', 'google', 'groq', 'cerebras', 'sail', 'bai', 'sambanova', 'nvidia', 'mistral', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama', 'kilo', 'pollinations', 'llm7', 'huggingface', 'opencode', 'routeway', 'bazaarlink', 'ainative', 'aion', 'requesty', 'navy', 'nara', 'sealion', 'orcarouter', 'unorouter', 'xkiro', 'anyapi', 'modelscope', 'aihorde'].includes(platform);}type HeaderSpec = { metric: QuotaMetric; limit: string; remaining?: string; reset?: string; strategy?: QuotaResetStrategy };diff --git a/shared/types.ts b/shared/types.tsindex ea3ab5e4..06dfacc3 100644--- a/shared/types.ts+++ b/shared/types.ts@@ -64,6 +64,10 @@ export type Platform =| 'google'| 'groq'| 'cerebras'+ // Sail Research — native Responses API provider. $5 in free credits refreshes+ // monthly when a payment method is attached; usage beyond the grant is+ // pay-as-you-go. Background polling is required for its flex-only models.+ | 'sail'// B.AI — OpenAI-compatible gateway. Its catalog row is a live-tested,// limited-time 0-credit promotion, not a recurring free allowance.| 'bai'