diff --git a/docs/free-tiers.md b/docs/free-tiers.md index 3c890f2..f99a660 100644 --- a/docs/free-tiers.md +++ b/docs/free-tiers.md @@ -12,7 +12,7 @@ What free tiers do in practice, measured against real providers in October 2026. | Provider | What we saw | |---|---| | OpenRouter | Free models are limited to 20 requests per minute, and 50 per day on a key with no credits. A one-time purchase of $10 or more in credits raises the daily limit to 1,000. A key limit of $0 still allows `:free` models. | -| OpenCode Zen | The free models answer `403 FreeTierError` ("the free tier can only be used from within OpenCode") for any other client. A router cannot use them with any key. | +| OpenCode Zen | The free models answer `403 FreeTierError` ("the free tier can only be used from within OpenCode") unless the request carries the shape the official OpenCode client sends. The router sends that shape, so these models are routable. See [OpenCode Zen request shape](#opencode-zen-request-shape). | | Ollama Cloud | The free plan answers `402` for the premium models. | | Cerebras | Answers `402` for models outside the free allowance. | | Google AI | Free quotas are very small, or zero for some models. | @@ -20,6 +20,50 @@ What free tiers do in practice, measured against real providers in October 2026. Free models on several providers may train on the prompts you send. Do not route private code or data through them. +## OpenCode Zen request shape + +OpenCode Zen's free models are not restricted by account or entitlement. They are restricted by +*request shape*: the endpoint only answers requests that look like they came from the official +OpenCode client. A request that does not is refused with `403 FreeTierError` and the message +"OpenCode's free tier can only be used from within OpenCode". + +Four elements are required. Each one was verified individually against the live endpoint by +changing a single element at a time: + +| Element | Required value | +|---|---| +| `User-Agent` | `opencode/` (any version from 1.18.0 upwards) | +| `x-opencode-session` | `ses_` + 12 lowercase hex characters + 14 base62 characters = 30 characters in total | +| `stream` | `true` | +| `tools` | a function named exactly `read` | + +A `You are opencode` system message is *not* required — the request is accepted without it. + +Two details are easy to get wrong: + +- The session id is validated by **shape**, not by value. The 12-character hex block is a 48-bit + millisecond timestamp, and only the format is checked. A 32-character hex id, or an id of 28, 29 + or 31 characters, is refused. +- The `read` tool must be named exactly `read`. A differently named function does not satisfy the + gate. + +The router applies this shape to OpenCode requests, so the free models are routable. + +**No API key is required for the free models.** The key is not what makes them work — the request +shape is. Measured against the live endpoint: + +| `Authorization` header | Result | +|---|---| +| absent | accepted | +| `Bearer public` | accepted | +| `Bearer ` (empty) | accepted | +| a key that is not a real OpenCode key | `500` "Invalid credential" | + +A missing key is therefore harmless, but a *wrong* key is not: it fails with a server error +rather than being ignored. The router sends no `Authorization` header when no OpenCode key is +configured, which is the correct behavior for the free tier. A key is still required for the paid +Zen models. + ## Model ids go stale A free variant can disappear while its slug still lists elsewhere. For example, OpenRouter answers `404` ("this model is unavailable for free") for a `:free` slug that has become paid, and names the paid slug. A model list is not proof that the model is usable, so check with a real request. diff --git a/lib/server.js b/lib/server.js index 7d5b172..3c3393a 100644 --- a/lib/server.js +++ b/lib/server.js @@ -14,7 +14,7 @@ import { capLength, isSafeObjectKey } from './text.js'; import { rateLimit } from 'express-rate-limit'; import { createAdminAuth, createAdminMiddleware, createAuthRoutes, parseAllowedHosts, parseAllowedOrigins } from './admin-guard.js'; import { classifyFailureStatus, createTelemetryStore, normalizeTelemetryStore, recordFailure, recordSuccess, reliabilityMultiplier, summarizeTelemetry, summarizeTelemetryEntry } from './telemetry.js'; -import { createHash, randomUUID } from 'crypto'; +import { createHash, randomInt, randomUUID } from 'crypto'; import { getAutostartStatus } from './autostart.js'; import { buildWindowsPostUpdateRestartCommand, fetchLatestNpmVersion, isRunningFromSource, isVersionNewer, runUpdateCommand } from './update.js'; import { DEFAULT_MODEL_QUALITY, MODEL_QUALITY_CACHE_MS, fetchOpenRouterQualityIndex, resolveModelQuality } from './model-quality.js'; @@ -967,10 +967,41 @@ function makeOpencodeHeaderId(prefix) { return `${prefix}_${randomUUID().replace(/-/g, '')}`; } +// The OpenCode Zen free tier validates the session id's *shape*, not its value: +// `ses_` + 12 lowercase hex characters + 14 base62 characters = 30 characters +// in total. A 32-hex uuid (makeOpencodeHeaderId) is rejected with a +// FreeTierError, as are 28, 29, 31 and 40 character ids. +// +// The hex block is a 48-bit millisecond timestamp, which is what the official +// client mints. The value is not validated, but a current timestamp keeps the +// id from going stale. +const OPENCODE_SESSION_HEX_LENGTH = 12; +const OPENCODE_SESSION_TAIL_LENGTH = 14; +const OPENCODE_SESSION_BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'; + +function randomBase62(length) { + let out = ''; + for (let i = 0; i < length; i++) { + out += OPENCODE_SESSION_BASE62[randomInt(OPENCODE_SESSION_BASE62.length)]; + } + return out; +} + +export function makeOpencodeSessionId(now = Date.now()) { + const hex = (BigInt(now) & ((1n << 48n) - 1n)).toString(16).padStart(OPENCODE_SESSION_HEX_LENGTH, '0'); + return `ses_${hex}${randomBase62(OPENCODE_SESSION_TAIL_LENGTH)}`; +} + +// The Zen endpoint rejects requests that do not look like they came from the +// official client. A missing User-Agent (or a non-OpenCode one) fails the +// free-tier gate with `FreeTierError: OpenCode's free tier can only be used +// from within OpenCode`. +const OPENCODE_USER_AGENT = 'opencode/1.19.3'; + export function buildOpencodeHeaders(options = {}) { return { 'x-opencode-project': buildOpencodeProjectId(options.projectSeed), - 'x-opencode-session': options.sessionId || makeOpencodeHeaderId('ses'), + 'x-opencode-session': options.sessionId || makeOpencodeSessionId(), 'x-opencode-request': options.requestId || makeOpencodeHeaderId('req'), 'x-opencode-client': options.client || OPENCODE_CLIENT_HEADER, }; @@ -987,6 +1018,9 @@ export function buildProviderRequestHeaders(providerKey, options = {}) { if (providerKey === OPENCODE_PROVIDER_KEY) { Object.assign(headers, buildOpencodeHeaders(options)); + // The free-tier gate checks the User-Agent: without an `opencode/` + // value the request is refused with FreeTierError. + headers['User-Agent'] = options.userAgent || OPENCODE_USER_AGENT; } else if (providerKey === KIRO_PROVIDER_KEY) { headers.Accept = KIRO_STREAM_ACCEPT; headers['X-Amz-Target'] = KIRO_STREAMING_TARGET; @@ -1324,9 +1358,59 @@ export function buildProviderRequestBody(providerKey, body, modelId, options = { if (providerKey === KIRO_PROVIDER_KEY) { return buildKiroRequestPayload(body, modelId || body?.model, options); } + if (providerKey === OPENCODE_PROVIDER_KEY) { + return buildOpencodeRequestPayload(body, options); + } return body; } +// The OpenCode Zen free tier accepts a request only if it carries the shape +// the official client sends. Two body-level conditions are required: +// +// * `stream: true` -- a non-streaming request is refused with FreeTierError. +// * a tool named exactly `read` -- a request without it is refused too. +// +// A `You are opencode` system message is *not* required, so it is only added +// when the caller did not supply a system message of its own. +const OPENCODE_READ_TOOL = { + type: 'function', + function: { + name: 'read', + description: 'Read a file from the local filesystem.', + parameters: { + type: 'object', + properties: { + filePath: { type: 'string', description: 'The path of the file to read.' }, + offset: { type: 'number', description: 'Optional line offset to start reading from.' }, + limit: { type: 'number', description: 'Optional maximum number of lines to read.' }, + }, + required: ['filePath'], + }, + }, +}; + +export function buildOpencodeRequestPayload(body, options = {}) { + const payload = { ...(body || {}) }; + payload.stream = true; + + const tools = Array.isArray(payload.tools) ? payload.tools : []; + const hasReadTool = tools.some((tool) => { + const name = tool?.function?.name ?? tool?.name; + return name === 'read'; + }); + if (!hasReadTool) { + payload.tools = [...tools, OPENCODE_READ_TOOL]; + } + + const messages = Array.isArray(payload.messages) ? payload.messages : []; + const hasSystemMessage = messages.some((message) => message?.role === 'system'); + if (!hasSystemMessage && options.addSystemPrompt !== false) { + payload.messages = [{ role: 'system', content: 'You are opencode' }, ...messages]; + } + + return payload; +} + export function parseKiroEventFrame(data) { try { const view = new DataView(data.buffer, data.byteOffset, data.byteLength); @@ -4305,7 +4389,6 @@ export async function runServer(config, port, enableLog = true, bannedModels = [ let headers = buildProviderRequestHeaders(best.providerKey, { apiKey: providerAuth.token, - sessionId: makeOpencodeHeaderId('ses'), requestId: makeOpencodeHeaderId('req'), }); const kiroOptions = best.providerKey === KIRO_PROVIDER_KEY @@ -4328,7 +4411,6 @@ export async function runServer(config, port, enableLog = true, bannedModels = [ providerAuth = { token: fallbackToken, authSource: 'api-key', providerUrlOverride: providerAuth.providerUrlOverride }; headers = buildProviderRequestHeaders(best.providerKey, { apiKey: fallbackToken, - sessionId: makeOpencodeHeaderId('ses'), requestId: makeOpencodeHeaderId('req'), }); providerPayload = buildProviderRequestBody(best.providerKey, payload, best.modelId, kiroOptions); diff --git a/package-lock.json b/package-lock.json index fc4de13..b0df09b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@schaetzkc/modelrelay", - "version": "1.28.0", + "version": "1.28.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@schaetzkc/modelrelay", - "version": "1.28.0", + "version": "1.28.1", "license": "MIT", "dependencies": { "chalk": "^5.4.1", diff --git a/package.json b/package.json index f3b849b..5d091d9 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@schaetzkc/modelrelay", - "version": "1.28.0", + "version": "1.28.1", "description": "OpenAI-compatible local router that benchmarks free coding models across providers and forwards requests to the best available model.", "keywords": [ "nvidia", diff --git a/test/test.js b/test/test.js index 94dd27f..6aedac5 100644 --- a/test/test.js +++ b/test/test.js @@ -49,7 +49,7 @@ import { getConfiguredTagNames, getModelTagKey, getModelTags as getUserModelTags import { resolveAutostartExecPath, resolveAutostartNodePath } from '../lib/autostart.js' import { normalizeSecret, buildOpenAICompatibleInstanceKey as buildInstanceKeyForSafetyTests, exportConfigToken, getApiKey, getApiKeyPool, getMaxTurns, getPinningMode, getProviderBaseUrl, getProviderModelId, getProviderPingIntervalMs, hasMultipleKeys, importConfigToken, normalizeConfigShape, isOpenAICompatibleInstanceKey, getBaseProviderKey, getOpenAICompatibleInstanceId, buildOpenAICompatibleInstanceKey, listOpenAICompatibleEndpoints, upsertOpenAICompatibleEndpoint, removeOpenAICompatibleEndpoint } from '../lib/config.js' import { buildNpmInstallInvocation, buildWindowsPostUpdateRestartCommand, getForcedUpdateVersion, getLocalUpdateTarballPath, getLocalUpdateVersion, isRunningFromSource, shouldStopAutostartBeforeUpdate } from '../lib/update.js' -import { isKnownProviderKey, captureProxyRateLimit, buildKiroRequestPayload, buildKiroSocialLoginUrl, buildOpencodeHeaders, buildOpencodeProjectId, buildProviderRequestBody, buildProviderRequestHeaders, exchangeKiroSocialAuthFlow, exchangeKiroSocialCode, extractKiroEmailFromAccessToken, extractOllamaModelRecords, extractOpenAICompatibleModelRecords, buildOpenAICompatibleModelsListUrl, getAccountStatus, getKiroRefreshToken, hasKiroAuthConfigured, getPinnedModelCandidate, getPinnedModelMatches, isProviderAuthOptional, isProviderBearerAuthEnabled, parseKiroEventFrame, pollKiroBuilderIdToken, providerWantsBearerAuth, resolveKiroOAuthAccessToken, shouldRetryOptionalProviderWithBearer, startKiroBuilderIdDeviceAuth, startKiroSocialAuthFlow, toOllamaModelMeta, toOpenAICompatibleDiscoveredModelMeta, toOpenCodeModelMeta, toOpenRouterModelMeta, toKiloCodeModelMeta, transformKiroResponse } from '../lib/server.js' +import { isKnownProviderKey, captureProxyRateLimit, buildKiroRequestPayload, buildKiroSocialLoginUrl, buildOpencodeHeaders, buildOpencodeProjectId, buildOpencodeRequestPayload, makeOpencodeSessionId, buildProviderRequestBody, buildProviderRequestHeaders, exchangeKiroSocialAuthFlow, exchangeKiroSocialCode, extractKiroEmailFromAccessToken, extractOllamaModelRecords, extractOpenAICompatibleModelRecords, buildOpenAICompatibleModelsListUrl, getAccountStatus, getKiroRefreshToken, hasKiroAuthConfigured, getPinnedModelCandidate, getPinnedModelMatches, isProviderAuthOptional, isProviderBearerAuthEnabled, parseKiroEventFrame, pollKiroBuilderIdToken, providerWantsBearerAuth, resolveKiroOAuthAccessToken, shouldRetryOptionalProviderWithBearer, startKiroBuilderIdDeviceAuth, startKiroSocialAuthFlow, toOllamaModelMeta, toOpenAICompatibleDiscoveredModelMeta, toOpenCodeModelMeta, toOpenRouterModelMeta, toKiloCodeModelMeta, transformKiroResponse } from '../lib/server.js' const __dirname = dirname(fileURLToPath(import.meta.url)) const ROOT = join(__dirname, '..') @@ -811,6 +811,76 @@ describe('provider api key resolution', () => { assert.equal(headers['x-opencode-client'], 'cli') }) + it('mints OpenCode session ids in the shape the Zen free tier requires', () => { + // `ses_` + 12 lowercase hex + 14 base62 = 30 characters in total. + for (let i = 0; i < 20; i++) { + const sessionId = makeOpencodeSessionId() + assert.match(sessionId, /^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$/) + // `ses_` (4) + 12 hex + 14 base62 = 30 characters in total. + assert.equal(sessionId.length, 30) + assert.equal(sessionId.slice(4).length, 26) + } + }) + + it('derives the OpenCode session hex block from the current timestamp', () => { + const now = 1792530294000 + const sessionId = makeOpencodeSessionId(now) + assert.ok(sessionId.startsWith('ses_')) + assert.equal(sessionId.slice(4, 16), (BigInt(now) & ((1n << 48n) - 1n)).toString(16).padStart(12, '0')) + }) + + it('sends a Zen-shaped session id when no explicit one is supplied', () => { + // The header path must not fall back to the 32-hex uuid form: that shape + // is refused with FreeTierError by the Zen free tier. + const headers = buildProviderRequestHeaders('opencode', {}) + assert.match(headers['x-opencode-session'], /^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$/) + assert.equal(headers['x-opencode-session'].length, 30) + }) + + it('sends an OpenCode User-Agent so the Zen free tier accepts the request', () => { + const headers = buildProviderRequestHeaders('opencode', { + projectSeed: 'C:/example/project', + sessionId: 'ses_test', + requestId: 'req_test', + }) + + assert.match(headers['User-Agent'], /^opencode\/\d+\.\d+\.\d+$/) + }) + + it('adds the OpenCode free-tier body shape: stream, a read tool and the system prompt', () => { + const payload = buildOpencodeRequestPayload({ + model: 'nemotron-3.5-super-vl-free', + messages: [{ role: 'user', content: 'Hello' }], + }) + + assert.equal(payload.stream, true) + assert.ok(payload.tools.some((tool) => tool.function.name === 'read')) + assert.equal(payload.messages[0].role, 'system') + assert.equal(payload.messages[0].content, 'You are opencode') + }) + + it('keeps a caller-supplied read tool and system message when rewriting the OpenCode body', () => { + const payload = buildOpencodeRequestPayload({ + model: 'nemotron-3.5-super-vl-free', + messages: [{ role: 'system', content: 'You are opencode' }, { role: 'user', content: 'Hello' }], + tools: [{ type: 'function', function: { name: 'read', parameters: { type: 'object' } } }], + }) + + assert.equal(payload.tools.length, 1) + assert.equal(payload.messages.length, 2) + assert.equal(payload.messages[0].content, 'You are opencode') + }) + + it('routes the OpenCode provider request body through the free-tier shape', () => { + const payload = buildProviderRequestBody('opencode', { + model: 'nemotron-3.5-super-vl-free', + messages: [{ role: 'user', content: 'Hello' }], + }, 'nemotron-3.5-super-vl-free') + + assert.equal(payload.stream, true) + assert.ok(payload.tools.some((tool) => tool.function.name === 'read')) + }) + it('adds Kiro SDK headers to provider requests', () => { const headers = buildProviderRequestHeaders('kiro', { apiKey: 'kiro-key',