opencode-translate 2.0.0 → 2.0.2

package/README.md

@@ -64,22 +64,76 @@ $en 프로젝트 루트의 package.json을 읽고 요약해줘
 All subsequent messages in the same session are translated automatically — no need to repeat `$en`.
 
 - Your original message and its English translation remain visible in the transcript.
+- The first successful `$en` prompt includes a `Translation enabled:` confirmation with the language and translator model.
 - English assistant text streams normally; a translated Markdown section is appended when the text segment completes.
 - Both the **terminal and web UI** display the same persisted bilingual assistant text. No UI-specific plugin is needed.
 - Question forms are translated, with selected labels and custom answers converted back to English for the model.
 - Translation activates only in root sessions. Its state survives plugin/server restarts.
 
 Before model requests, the plugin removes its recorded display translations from context. It does not remove arbitrary
-Markdown based on its appearance. On inbound translation failure, the original prompt is sent unchanged; on outbound
-failure, the English response is retained with a translation-unavailable notice.
+Markdown based on its appearance. On inbound translation failure, the transcript shows `Translation failed:` and the
+error reason. The main model receives the original text without `$en` or the diagnostic; failed first-time activation
+remains inactive, so retry with `$en` after fixing the error. On outbound failure, the English response is retained with
+a translation-unavailable notice.
+
+### If `$en` has no effect
+
+`$en` is a plugin control keyword, not an instruction for the main model. If the model comments on `$en`, inbound
+translation did not complete. In version 2.0.0, an inbound failure was only logged on the server and left `$en` in the
+prompt, making it indistinguishable from an unloaded plugin in the transcript.
+
+Check the active server's plugin list and configuration, including the selected project location. It must load the v2
+package, not an old pinned `opencode-translate@1.x`. Also check the configured **translation** model and variant; changing
+the main-chat model does not change the translator. An API-key login or OAuth connection must exist on that server.
+The server log message `[opencode-translate] inbound translation failed` contains the underlying generation error.
+
+OpenCode 2.0.3 also normalizes the legacy `"plugin": [["package", { ...options }]]` tuple syntax; that syntax alone
+does not prevent this plugin from loading. The `plugins` object form shown above is the recommended v2 format.
+Make sure the configuration is a complete JSON/JSONC object, including its opening `{`.
+
+If there is neither an activation confirmation nor a failure notice, inspect the running server's plugin state for the
+same directory as the session:
+
+```sh
+opencode api v2.plugin.awaitActivation --param 'location[directory]=/absolute/path/to/project'
+opencode api v2.plugin.list --param 'location[directory]=/absolute/path/to/project'
+```
+
+Find `opencode-translate`, check `source.version` and `state.status`, and inspect `state.error` if setup failed. If the UI
+uses a remote or explicitly selected server, pass `--server` with that same server URL. A client version or a globally
+installed npm version alone does not establish what the session's server has loaded.
 
 ## Authentication
 
 Connect the translation model's provider in **OpenCode itself**. Translation uses the public `ctx.generate.text()` API,
-so OpenCode owns provider selection, model variants, API keys, SQLite credentials, and OAuth refresh/persistence.
+with a `ctx.session.generate()` fallback for providers that require an OpenCode session. OpenCode owns provider
+selection, model variants, API keys, SQLite credentials, and OAuth refresh/persistence.
 The plugin does not read `auth.json`/`auth-v2.json`, query the credential database, or maintain separate tokens.
 Provider and OAuth support for the translation model is the support available in your OpenCode installation.
 
+Verified on OpenCode 2.0.3 using the host's saved credentials:
+
+| Translation model | Result |
+| --- | --- |
+| `openai/gpt-5.6-luna` | Inbound, outbound, and follow-up translation passed through stateless generation with ChatGPT OAuth. |
+| `opencode/muse-spark-1.3-contributor-free` | Passed through the session-aware fallback described below. |
+| `anthropic/claude-sonnet-5` with `@henadev/opencode-anthropic-auth@0.2.0` | Works as the main chat model, but not as the translator in this release: its auth plugin depends on session HTTP hooks that stateless generation skips. |
+
+Anthropic translation succeeded in a session-aware experiment, but the automatic fallback in this release is limited
+to the explicit OpenCode free-tier rejection. It does not retry generic authentication errors through another path.
+
+### OpenCode free-tier translation models
+
+OpenCode 2.0.3 can reject stateless generation for free-tier models with `OpenCode's free tier can only be used in
+OpenCode.` This was reproduced with `opencode/muse-spark-1.3-contributor-free`: normal session generation succeeds,
+but `ctx.generate.text()` lacks the session request metadata accepted by that provider.
+
+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, they cannot execute tools, and each
+generation receives only the current translation prompt plus OpenCode's system instructions. The helper ID survives
+plugin/server restarts. Other authentication or model-selection failures still report their original error.
+
 ## Inline reply support
 
 V2 has no `experimental.text.complete` hook or public display-only message append operation. Inline translations use
@@ -114,11 +168,22 @@ bun run test:package
 
 # Requires Node 24 and an OpenCode v2 binary; uses an isolated server and fake provider.
 OPENCODE_BINARY=/path/to/opencode bun run test:host
+
+# Exercise a registry-installed package through OpenCode's actual package loader.
+OPENCODE_BINARY=/path/to/opencode OPENCODE_TRANSLATE_PACKAGE=opencode-translate@latest bun run test:host
+
+# Verify OpenCode's normalization of legacy plugin tuples as well.
+OPENCODE_BINARY=/path/to/opencode OPENCODE_TRANSLATE_LEGACY_CONFIG=1 bun run test:host
+
+# Verify providers that support ordinary stateless generation.
+OPENCODE_BINARY=/path/to/opencode OPENCODE_TRANSLATE_REQUIRE_SESSION=0 bun run test:host
 ```
 
 Tests include OpenCode's actual native protocol parsers. The real-host smoke test loads the built plugin, creates and
 rotates a test credential in an isolated SQLite database, checks bilingual persisted messages and English-only model
 requests, and restarts the server to verify recovery. It does not use your live server, credentials, or paid models.
+CI covers both configuration formats and both generation paths. The publish workflow tests the candidate before
+publishing, then installs the exact version from npm in OpenCode before creating its GitHub release.
 
 The old `opencode2 v0.0.0-dev-18322` binary does not pass this migration's host smoke test. Use the verified 2.0.3 release
 rather than assuming that any binary named `opencode2` exposes the current plugin API.

package/dist/index.js

@@ -636,7 +636,7 @@ function readMetadata(value) {
     return;
   const item = value;
   if (typeof item.lang === "string" && typeof item.english === "string" && typeof item.display === "string") {
-    return { lang: item.lang, english: item.english, display: item.display };
+    return { lang: item.lang, english: item.english, display: item.display, enabled: item.enabled !== false };
   }
 }
 function createState(ctx) {
@@ -667,7 +667,7 @@ function createState(ctx) {
       const messages = await ctx.session.context({ sessionID });
       for (const message of messages) {
         const data = readMetadata(message.metadata?.[METADATA_KEY]);
-        if (message.type === "user" && data) {
+        if (message.type === "user" && data?.enabled) {
           await ctx.storage.set(`sessions/${sessionID}`, data.lang);
           return data.lang;
         }
@@ -713,9 +713,62 @@ function createState(ctx) {
 }
 
 // src/translator.ts
+import { createHash as createHash2 } from "node:crypto";
 function createTranslator(ctx, options, signal) {
   const { providerID, modelID } = parseTranslatorModel(options.model);
   const model = { providerID, id: modelID, ...options.variant ? { variant: options.variant } : {} };
+  let sessionRequired = false;
+  let helper;
+  function helperSession() {
+    if (helper)
+      return helper;
+    helper = (async () => {
+      const key = `translator-session/${createHash2("sha256").update(JSON.stringify({ directory: ctx.location.directory, workspaceID: ctx.location.workspaceID ?? null, model })).digest("hex")}`;
+      const saved = await ctx.storage.get(key);
+      const previous = typeof saved === "string" ? await ctx.session.get({ sessionID: saved }).catch((error) => {
+        if (error && typeof error === "object" && "_tag" in error && /NotFound/.test(String(error._tag)))
+          return;
+        throw error;
+      }) : undefined;
+      const session = previous ?? await ctx.session.create({
+        title: `Translation helper (${options.model})`,
+        model,
+        location: {
+          directory: ctx.location.directory,
+          ...ctx.location.workspaceID ? { workspaceID: ctx.location.workspaceID } : {}
+        },
+        metadata: { "opencode-translate": { helper: true } }
+      });
+      await ctx.storage.set(key, session.id);
+      await ctx.session.hook(Number.parseInt(ctx.app.version, 10) >= 2 ? "generate" : "context", (event) => {
+        if (event.sessionID !== session.id)
+          return;
+        event.messages = event.messages.slice(-1);
+        event.tools = {};
+      });
+      return session.id;
+    })().catch((error) => {
+      helper = undefined;
+      throw error;
+    });
+    return helper;
+  }
+  async function request(prompt, abort) {
+    if (!sessionRequired) {
+      try {
+        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);
+        if (!message.includes("free tier can only be used in OpenCode"))
+          throw error;
+        abort.throwIfAborted();
+        sessionRequired = true;
+      }
+    }
+    const sessionID = await helperSession();
+    abort.throwIfAborted();
+    return ctx.session.generate({ sessionID, prompt }, { signal: abort });
+  }
   async function generate(prompt, requestSignal) {
     const started = Date.now();
     const abort = AbortSignal.any([signal, AbortSignal.timeout(180000), ...requestSignal ? [requestSignal] : []]);
@@ -727,7 +780,7 @@ function createTranslator(ctx, options, signal) {
     const stop = () => rejectCancelled(abort.reason);
     abort.addEventListener("abort", stop, { once: true });
     try {
-      const result = await Promise.race([ctx.generate.text({ model, prompt }, { signal: abort }), cancelled]);
+      const result = await Promise.race([request(prompt, abort), cancelled]);
       if (options.verbose)
         console.info(`[${PLUGIN_NAME}] translated with ${options.model} in ${Date.now() - started}ms`);
       return result.text;
@@ -784,13 +837,7 @@ async function setup(ctx) {
     if (source === undefined)
       return;
     const userLanguage = lang ?? options.lang;
-    try {
-      const english = await translator.text(source, userLanguage, LLM_LANGUAGE);
-      const display = source === english ? source : `${source}
-
-→ EN: ${english}`;
-      await state.remember(event.sessionID, display, english);
-      await ctx.storage.set(`sessions/${event.sessionID}`, userLanguage);
+    function apply(display, english, enabled) {
       event.prompt.text = display;
       for (const attachment of [
         ...event.prompt.files ?? [],
@@ -799,9 +846,26 @@ async function setup(ctx) {
       ]) {
         delete attachment.mention;
       }
-      event.metadata = { ...event.metadata, [METADATA_KEY]: { lang: userLanguage, english, display } };
+      event.metadata = { ...event.metadata, [METADATA_KEY]: { lang: userLanguage, english, display, enabled } };
+    }
+    try {
+      const english = await translator.text(source, userLanguage, LLM_LANGUAGE);
+      const content = source === english ? source : `${source}
+
+→ EN: ${english}`;
+      const display = lang ? content : `${content}
+
+\uD83C\uDF10 Translation enabled: ${userLanguage} ↔ ${LLM_LANGUAGE} (${options.model})`;
+      await state.remember(event.sessionID, display, english);
+      await ctx.storage.set(`sessions/${event.sessionID}`, userLanguage);
+      apply(display, english, true);
     } catch (error) {
       console.error(`[${PLUGIN_NAME}] inbound translation failed; sending original text`, error);
+      const reason = error && typeof error === "object" && "message" in error && typeof error.message === "string" ? error.message : String(error);
+      const display = `${source}
+
+⚠️ Translation failed: ${reason}. Original text was sent to the model.`;
+      apply(display, source, Boolean(lang));
     }
   });
   async function context(event) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-translate",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "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",