release: v2.0.8 - route Console providers by ID instead of by error wording

v2.0.6 and v2.0.7 each fixed a case where the session-metadata fallback
failed to trigger because isFreeTierSessionRequired/isSessionMetadataRequired
didn't match Console's latest rejection wording. Message matching is
inherently reactive: it can only ever catch wording Console has already
shipped, and each new tier or phrasing needs its own plugin release.

Replace that as the primary path with something that can't go stale: the
configured provider ID is already known before any request is sent, and
every Console tier observed so far -- Zen "opencode", Go "opencode-go" --
needs session metadata unconditionally. isSessionOnlyProvider() checks the
provider ID at translator creation time and, for those providers, skips
the stateless attempt entirely rather than sending a request known to be
rejected and parsing the rejection.

- Add isSessionOnlyProvider(providerID): true for "opencode" and any
  "opencode-*" provider. sessionRequired now starts true for these instead
  of false, so ctx.generate.text() is never called for them.
- Keep isSessionMetadataRequired() (the message matcher from v2.0.6/2.0.7)
  as a safety net for providers isSessionOnlyProvider doesn't recognize --
  a not-yet-seen Console tier, or an unrelated provider that happens to
  need session metadata for its own reasons. Wording drift there still
  self-heals the way it does today; it just isn't the primary mechanism
  for Console's own providers anymore.
- Add unit coverage: isSessionOnlyProvider's id matching (including that it
  doesn't false-positive on providers that merely contain "opencode"), and
  an end-to-end test asserting ctx.generate.text() is never invoked for a
  session-only provider (the mock throws if it's called at all).
- Verified against the real opencode-go/gpt-5.6-luna backend: translation
  succeeds with no stateless attempt in the request path.

Author: ysm-dev

README.md

@@ -137,21 +137,28 @@ errors through another path.
 
 ### OpenCode session-metadata-only translation models
 
-OpenCode can reject stateless generation because `ctx.generate.text()` omits the session request metadata some
-providers require. Console has phrased this rejection differently by tier and release: the free Zen tier says
-`OpenCode's free tier can only be used in OpenCode.` (also seen as `...from within OpenCode.`), while the paid Go
-tier says `Request is missing x-opencode-session and cannot be routed efficiently.` The plugin matches on stable
-signals -- the free-tier phrase, or the literal `x-opencode-session` header name -- rather than either exact
-sentence. This was reproduced with `opencode/muse-spark-1.3-contributor-free` (Zen) and `opencode-go/gpt-5.6-luna`
-(Go): normal session generation succeeds on both, but `ctx.generate.text()` lacks the session request metadata
-either provider accepts.
-
-On this specific rejection, the plugin switches to public session-aware generation using a reusable **Translation
-helper** session for the configured model and location. The helper may appear in the session list. Translation prompts
-are transient: they do not append messages to either the helper or your chat, and each generation receives only the
+`ctx.generate.text()` omits the session request metadata every Console tier requires (Zen `opencode` and Go
+`opencode-go`, and presumably any tier Console adds later). The plugin recognizes this **upfront, from the
+configured provider ID** -- `isSessionOnlyProvider()` -- and routes those providers straight to session-aware
+generation without ever attempting the stateless call. This is deliberate: Console has phrased the rejection
+differently by tier and release (the free Zen tier: `OpenCode's free tier can only be used in/from within
+OpenCode.`; the paid Go tier: `Request is missing x-opencode-session and cannot be routed efficiently.`), and a
+provider-ID check that's known before the request is sent can't be broken by wording changes on Console's side --
+unlike matching the rejection message, which has already needed two updates.
+
+Matching the rejection message (`isSessionMetadataRequired()`) still exists as a safety net for providers
+`isSessionOnlyProvider()` doesn't recognize: on that specific rejection, mid-translation, the plugin switches the
+same way. Both paths converge on public session-aware generation using a reusable **Translation helper** session
+for the configured model and location. The helper may appear in the session list. Translation prompts are
+transient: they do not append messages to either the helper or your chat, and each generation receives only the
 current translation prompt plus OpenCode's system instructions and tool definitions. The helper ID survives
 plugin/server restarts. Other authentication or model-selection failures still report their original error.
 
+This was verified with `opencode/muse-spark-1.3-contributor-free` (Zen) and `opencode-go/gpt-5.6-luna` (Go): normal
+session generation succeeds on both, `ctx.generate.text()` lacks the session request metadata either provider
+accepts, and with the provider ID recognized upfront, the plugin never attempts the stateless call in the first
+place for either one.
+
 Tool definitions are deliberately kept in the helper session's requests. Console's free tier reads a request with an
 emptied tool list as non-agent traffic and rejects it with the same `free tier can only be used within OpenCode`
 error, even when the request otherwise carries correct session headers -- confirmed by comparing requests with and

package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-translate",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "description": "OpenCode plugin that lets the user chat in a configured language while the main chat loop only sees English.",
   "type": "module",
   "main": "dist/index.js",

src/translator.ts

@@ -15,14 +15,24 @@ export interface Translator {
   texts(texts: readonly string[], sourceLanguage: string, targetLanguage: string): Promise<string[]>
 }
 
-// Console rejects stateless generation whenever it can't see real OpenCode
-// session metadata, but has worded the rejection differently by tier and
-// release: the free Zen tier ("...free tier can only be used in/from within
-// OpenCode.") and the paid Go tier ("Request is missing x-opencode-session
-// and cannot be routed efficiently. Please see .../docs/go/#where-can-i-use-it.").
-// Match on stable signals -- the literal header name, or the free-tier phrase
-// -- rather than either exact sentence, so wording drift on either tier does
-// not silently disable the session fallback below.
+// Every Console tier (Zen "opencode", Go "opencode-go", and whatever tier
+// comes next) requires real OpenCode session metadata that ctx.generate.text()
+// never sends. Known upfront from the configured provider ID -- not observed
+// from a failure -- so these providers skip the stateless attempt entirely
+// and go straight to the session path below. This is what actually makes the
+// fallback robust: it does not depend on Console's error wording at all.
+export function isSessionOnlyProvider(providerID: string): boolean {
+  return providerID === "opencode" || providerID.startsWith("opencode-")
+}
+
+// Safety net for session-metadata requirements on providers isSessionOnlyProvider
+// doesn't (yet) recognize. Console has worded this rejection differently by tier
+// and release: the free Zen tier ("...free tier can only be used in/from within
+// OpenCode.") and the paid Go tier ("Request is missing x-opencode-session and
+// cannot be routed efficiently. Please see .../docs/go/#where-can-i-use-it.").
+// Match on stable signals -- the literal header name, or the free-tier phrase --
+// rather than either exact sentence, so wording drift keeps landing here even
+// when it silently changes again.
 export function isSessionMetadataRequired(message: string): boolean {
   return /free tier can only be used\b.*\bopencode/i.test(message) || /x-opencode-session/i.test(message)
 }
@@ -36,7 +46,7 @@ export function createTranslator(
 ): Translator {
   const { providerID, modelID } = parseTranslatorModel(options.model)
   const model = { providerID, id: modelID, ...(options.variant ? { variant: options.variant } : {}) }
-  let sessionRequired = false
+  let sessionRequired = isSessionOnlyProvider(providerID)
   let helper: Promise<string> | undefined
 
   function helperSession() {
@@ -95,8 +105,8 @@ export function createTranslator(
         return await ctx.generate.text({ model, prompt }, { signal: abort })
       } catch (error) {
         const message = error && typeof error === "object" && "message" in error ? String(error.message) : String(error)
-        // OpenCode's stateless path omits the session metadata some providers
-        // require. Use a real OpenCode session request rather than fabricating headers.
+        // Reached only for providers isSessionOnlyProvider didn't flag upfront.
+        // Use a real OpenCode session request rather than fabricating headers.
         if (!isSessionMetadataRequired(message)) throw error
         abort.throwIfAborted()
         sessionRequired = true

test/translator.test.ts

@@ -1,8 +1,33 @@
 import { expect, test } from "bun:test"
 import { resolveOptions } from "../src/constants"
-import { createTranslator, isSessionMetadataRequired } from "../src/translator"
+import { createTranslator, isSessionMetadataRequired, isSessionOnlyProvider } from "../src/translator"
 import { host, requestContext } from "./helpers"
 
+test("session-only providers are recognized by ID alone", () => {
+  expect(isSessionOnlyProvider("opencode")).toBe(true)
+  expect(isSessionOnlyProvider("opencode-go")).toBe(true)
+  expect(isSessionOnlyProvider("opencode-anything-future")).toBe(true)
+  expect(isSessionOnlyProvider("openai")).toBe(false)
+  expect(isSessionOnlyProvider("anthropic")).toBe(false)
+  // Must not match unrelated providers that merely contain the substring.
+  expect(isSessionOnlyProvider("my-opencode-fork")).toBe(false)
+})
+
+test("session-only providers skip the stateless attempt entirely, regardless of wording", async () => {
+  const h = host({ model: "opencode/muse-spark-1.3-contributor-free" })
+  h.generate(async () => {
+    throw new Error("stateless generate.text must never be called for a session-only provider")
+  })
+  h.sessionGenerate(async () => "안녕하세요")
+  const translator = createTranslator(h.ctx, resolveOptions(h.ctx.options), new AbortController().signal)
+  expect(await translator.text("Hello", "English", "Korean")).toBe("안녕하세요")
+  expect(h.requests).toHaveLength(0)
+  expect(h.createdSessions).toHaveLength(1)
+  expect(h.createdSessions[0]).toMatchObject({
+    model: { providerID: "opencode", id: "muse-spark-1.3-contributor-free" },
+  })
+})
+
 test("session metadata requirement is detected across Console's observed wordings", () => {
   // Free Zen tier.
   expect(isSessionMetadataRequired("OpenCode's free tier can only be used in OpenCode.")).toBe(true)