From 7169ceb0f72930cf261b54bbc531d9d2b1106a67 Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Wed, 21 Oct 2026 00:16:01 +0200 Subject: [PATCH 1/3] fix(opencode): send the request shape the Zen free tier requires The OpenCode Zen free tier refuses requests that do not look like they came from the official client. Every free model failed with 403 {"type":"FreeTierError","message":"OpenCode's free tier can only be used from within OpenCode. Download it at https://opencode.ai"} Three of the four required conditions were missing: * The session id used a 32-hex uuid. The gate requires `ses_` + 12 lowercase hex + 14 base62 = 30 characters in total. * No User-Agent was sent. The gate requires an `opencode/` value. * The request body was forwarded unchanged, so it carried neither `stream: true` nor a tool named exactly `read`. An ablation against the live endpoint confirms each one is required on its own: changing any single element back to its previous value reproduces the 403. A `You are opencode` system message is *not* required, so it is only added when the caller did not supply one. With this change the free models route successfully instead of 403ing, and the relay's own health check reports them as `up` rather than `down`. Note that a `403` here is a request-shape refusal, not a model that is gone: these models are alive and answer through a client that sends the right shape. --- lib/server.js | 90 ++++++++++++++++++++++++++++++++++++++++++++++++--- test/test.js | 72 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 157 insertions(+), 5 deletions(-) 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/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', From 7bc46e81100436adda679dd6e89d2f3b20821462 Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Wed, 21 Oct 2026 00:30:43 +0200 Subject: [PATCH 2/3] docs: describe the OpenCode Zen request shape and bump to 1.28.1 The free-tiers page stated that "a router cannot use them with any key", which the request-shape fix makes incorrect: the free models are restricted by the shape of the request, not by the account or the key. Documents the four required elements (User-Agent, session id shape, stream, read tool) and the two details that are easy to get wrong: the session id is validated by shape rather than by value, and the tool has to be named exactly `read`. --- docs/free-tiers.md | 32 +++++++++++++++++++++++++++++++- package-lock.json | 4 ++-- package.json | 2 +- 3 files changed, 34 insertions(+), 4 deletions(-) diff --git a/docs/free-tiers.md b/docs/free-tiers.md index 3c890f2..9680733 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,36 @@ 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. The API key +is not what makes them work — a request with the right shape is accepted even without a key. + ## 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/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", From f2da4bdcfcad58dded7d7dba0c3df61b2a526bea Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Wed, 21 Oct 2026 00:41:24 +0200 Subject: [PATCH 3/3] docs: note that the OpenCode Zen free tier needs no API key Measured against the live endpoint, the free models are gated by the request shape alone. A missing Authorization header, `Bearer public` and an empty `Bearer ` are all accepted; only a key that is not a real OpenCode key fails (with a 500 "Invalid credential", not a 403). 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. --- docs/free-tiers.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/free-tiers.md b/docs/free-tiers.md index 9680733..f99a660 100644 --- a/docs/free-tiers.md +++ b/docs/free-tiers.md @@ -47,8 +47,22 @@ Two details are easy to get wrong: - 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. The API key -is not what makes them work — a request with the right shape is accepted even without a key. +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