opencode-translate 0.0.2 → 0.0.4

package/README.md

@@ -32,7 +32,18 @@
 - No title translation or title-path English enforcement.
 - No subagent translation.
 - No translation of tool inputs, tool outputs, or reasoning parts.
-- No self-healing for edited historical translated user messages. Those abort with a stale-cache error.
+- Edited historical translated user messages are passed through as-is instead of being re-translated (the original edited text is what the LLM sees).
+
+## Hook Failure Handling
+
+Hooks never throw. If the translator fails (network error, auth failure, provider 4xx/5xx), the plugin:
+
+1. Logs the error via `client.app.log` (visible with `verbose: true`).
+2. Emits a `⚠️ Translation failed: …` synthetic part.
+3. Falls back to sending the original (untranslated) user text to the model.
+4. On first-turn activation failure, it also rolls back activation so the next turn retries cleanly.
+
+A stalled provider request is additionally bounded by a 60s hard timeout per translation call, so a hung upstream cannot block the OpenCode session.
 
 ## Install
 
@@ -89,15 +100,27 @@ Using this plugin means text goes to two model providers per turn:
 
 If you need strict single-provider or self-hosted-only behavior, do not enable this plugin.
 
-## Anthropic OAuth Warning
+## Anthropic OAuth Support
+
+If `translatorModel` uses Anthropic and OpenCode auth is backed by Anthropic OAuth (Claude Pro/Max), the plugin reuses those OAuth credentials for translation requests.
+
+Anthropic's `/v1/messages` endpoint rejects OAuth-authenticated requests that do not match the Claude Code CLI fingerprint (response: `429 rate_limit_error` with an empty `"Error"` message). To pass, the plugin applies the same transformation that `@ex-machina/opencode-anthropic-auth` uses for OpenCode's main chat, but only for its own translator requests:
+
+- `user-agent: claude-cli/2.1.87 (external, cli)`
+- Required `anthropic-beta` headers (`oauth-2025-04-20`, `interleaved-thinking-2025-05-14`)
+- `?beta=true` appended to the `/v1/messages` URL
+- `x-anthropic-billing-header` block prepended to `system[]` (deterministic CCH of the first user message)
+- `"You are a Claude agent, built on Anthropic's Claude Agent SDK."` injected as the next `system[]` block
+
+The technique and constants are documented in https://github.com/ex-machina-co/opencode-anthropic-auth. See `src/anthropic-oauth.ts`.
 
-If `translatorModel` uses Anthropic and OpenCode auth is backed by Anthropic OAuth, this plugin will attempt to reuse those OAuth credentials for translation requests.
+Tradeoffs:
 
-- This depends on undocumented Anthropic OAuth request shapes.
-- OpenCode upstream removed Anthropic OAuth support for legal / policy reasons.
-- `opencode-translate` does not spoof Claude CLI headers or reintroduce the evasions upstream removed.
+- Relies on an undocumented Anthropic OAuth request shape. Anthropic can change this at any time and force the plugin to stop using OAuth.
+- OpenCode upstream removed Anthropic OAuth support for legal / policy reasons. Installing this plugin reintroduces an equivalent code path in your environment.
+- Translator requests contribute to your Claude Pro/Max rate limit alongside OpenCode's main chat.
 
-If you do not want that risk, use a plain API key for Anthropic or choose a different translator provider.
+If you prefer a plain API key, set `ANTHROPIC_API_KEY` in the environment or pass `apiKey` in plugin options. The plugin prefers explicit `apiKey`, then `ANTHROPIC_API_KEY`, then OAuth.
 
 ## Manual Smoke Test
 
@@ -107,7 +130,7 @@ If you do not want that risk, use a plain API key for Anthropic or choose a diff
 4. Confirm the `→ EN: ...` preview appears under the user message.
 5. Confirm assistant text streams in English, then gains a translated trailer when the text part finishes.
 6. Confirm later messages in the same session translate without repeating `$en`.
-7. Confirm editing a historical translated user message aborts with the stale-cache error.
+7. Confirm editing a historical translated user message falls back to the edited text being sent as-is (with a log entry visible under `verbose: true`).
 8. Confirm task-tool child sessions are not translated.
 9. Confirm the title remains in the source language in v1.
 

package/package.json

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

package/src/activation.ts

@@ -124,6 +124,12 @@ function mergeTranslatedMetadata(state: TranslateState, part: TextPartLike, engl
   }
 }
 
+// OpenCode's flag semantics, observed from packages/opencode and packages/ui:
+//   synthetic: true  -> hidden from the user UI, still sent to the LLM
+//   ignored: true    -> hidden from the LLM, still shown in the user UI
+// The translation preview, activation banner, and failure notices are
+// user-facing status/diagnostic parts that must not leak into the LLM
+// prompt, so they use synthetic:false + ignored:true.
 function createSyntheticTextPart(
   sessionID: string,
   messageID: string,
@@ -136,7 +142,7 @@ function createSyntheticTextPart(
     messageID,
     type: "text",
     text,
-    synthetic: true,
+    synthetic: false,
     ignored: true,
     metadata,
   }
@@ -255,152 +261,194 @@ export function createHooks(ctx: PluginInput, rawOptions: PluginOptions = {}, de
 
   return {
     "chat.message": async (input, output) => {
-      const resolved = await resolveSessionState(client, ctx.directory, input.sessionID)
-      let activeState = resolved.state
-      let activatedThisTurn = false
-
-      if (!activeState && resolved.canActivate) {
-        const match = findTriggerMatch(output.parts as TextPartLike[], options.triggerKeywords)
-        if (match) {
-          const part = output.parts[match.partArrayIndex] as TextPartLike & { text: string }
-          part.text = stripTriggerKeyword(part.text, match.keyword, match.offset)
-          activeState = createState(options)
-          if (!NONCE_PATTERN.test(activeState.translate_nonce)) {
-            throw new Error("Generated invalid translation nonce")
+      // Hooks must never throw. A thrown error propagates into OpenCode's
+      // Effect runtime as a defect, kills the fiber, and stalls the session —
+      // to the user this looks like infinite loading with no error message.
+      // Instead, we log the failure and fall back to the untranslated text so
+      // the chat keeps moving.
+      try {
+        const resolved = await resolveSessionState(client, ctx.directory, input.sessionID)
+        let activeState = resolved.state
+        let activatedThisTurn = false
+
+        if (!activeState && resolved.canActivate) {
+          const match = findTriggerMatch(output.parts as TextPartLike[], options.triggerKeywords)
+          if (match) {
+            const part = output.parts[match.partArrayIndex] as TextPartLike & { text: string }
+            const originalText = part.text
+            part.text = stripTriggerKeyword(part.text, match.keyword, match.offset)
+            activeState = createState(options)
+            if (!NONCE_PATTERN.test(activeState.translate_nonce)) {
+              part.text = originalText
+              await logError(client, new Error("Generated invalid translation nonce"))
+              return
+            }
+            activatedThisTurn = true
+            sessionStateCache.set(input.sessionID, activeState)
           }
-          activatedThisTurn = true
-          sessionStateCache.set(input.sessionID, activeState)
         }
-      }
 
-      if (!activeState) return
+        if (!activeState) return
 
-      const nextParts: TextPartLike[] = []
-      let eligibleIndex = 0
+        const nextParts: TextPartLike[] = []
+        let eligibleIndex = 0
+        const translationErrors: { part: TextPartLike; error: unknown }[] = []
 
-      for (const part of output.parts as TextPartLike[]) {
-        nextParts.push(part)
-        if (!isUserAuthoredTextPart(part)) continue
+        for (const part of output.parts as TextPartLike[]) {
+          nextParts.push(part)
+          if (!isUserAuthoredTextPart(part)) continue
 
-        const currentEligibleIndex = eligibleIndex
-        eligibleIndex += 1
-        if (part.text.trim().length === 0) continue
+          const currentEligibleIndex = eligibleIndex
+          eligibleIndex += 1
+          if (part.text.trim().length === 0) continue
 
-        try {
-          const english = await translator.translateText({
-            text: part.text,
-            sourceLanguage: activeState.translate_source_lang,
-            targetLanguage: LLM_LANGUAGE,
-            direction: "inbound",
-          })
+          try {
+            const english = await translator.translateText({
+              text: part.text,
+              sourceLanguage: activeState.translate_source_lang,
+              targetLanguage: LLM_LANGUAGE,
+              direction: "inbound",
+            })
 
-          const sourceHash = hashText(part.text)
-          part.metadata = {
-            ...(part.metadata ?? {}),
-            ...mergeTranslatedMetadata(activeState, part, english),
+            const sourceHash = hashText(part.text)
+            part.metadata = {
+              ...(part.metadata ?? {}),
+              ...mergeTranslatedMetadata(activeState, part, english),
+            }
+
+            nextParts.push(
+              createSyntheticTextPart(part.sessionID, part.messageID, `→ EN: ${english}`, {
+                translate_role: "translation_preview",
+                translate_nonce: activeState.translate_nonce,
+                translate_source_hash: sourceHash,
+                translate_part_index: currentEligibleIndex,
+              }),
+            )
+          } catch (error) {
+            // Fall back to sending the original text to the LLM so the user
+            // still gets a response. Surface the error as a synthetic part.
+            translationErrors.push({ part, error })
+            const wrapped = buildInboundTranslationError(activeState.translate_source_lang, normalizeReason(error))
+            await logError(client, wrapped)
+            nextParts.push(
+              createSyntheticTextPart(
+                part.sessionID,
+                part.messageID,
+                `⚠️ Translation failed: ${normalizeReason(error)}. Original text will be sent to the model.`,
+                {
+                  translate_role: "translation_failure",
+                  translate_nonce: activeState.translate_nonce,
+                  translate_part_index: currentEligibleIndex,
+                },
+              ),
+            )
           }
+        }
 
+        // If we activated this turn but translation failed for every
+        // user-authored part, roll back activation so the next turn does a
+        // clean retry instead of cementing broken state.
+        if (activatedThisTurn && translationErrors.length > 0 && eligibleIndex === translationErrors.length) {
+          sessionStateCache.set(input.sessionID, null)
+          return
+        }
+
+        if (activatedThisTurn) {
           nextParts.push(
-            createSyntheticTextPart(part.sessionID, part.messageID, `→ EN: ${english}`, {
-              translate_role: "translation_preview",
-              translate_nonce: activeState.translate_nonce,
-              translate_source_hash: sourceHash,
-              translate_part_index: currentEligibleIndex,
+            createSyntheticTextPart(input.sessionID, output.message.id, createActivationBannerText(options), {
+              ...activeState,
+              translate_role: "activation_banner",
+              translate_spec_version: SPEC_VERSION,
             }),
           )
-        } catch (error) {
-          if (
-            error instanceof Error &&
-            (error.message.includes(":AUTH_UNAVAILABLE]") || error.message.includes(":OAUTH_REFRESH_FAILED]"))
-          ) {
-            throw error
-          }
-          throw buildInboundTranslationError(activeState.translate_source_lang, normalizeReason(error))
         }
-      }
 
-      if (activatedThisTurn) {
-        nextParts.push(
-          createSyntheticTextPart(input.sessionID, output.message.id, createActivationBannerText(options), {
-            ...activeState,
-            translate_role: "activation_banner",
-            translate_spec_version: SPEC_VERSION,
-          }),
-        )
+        output.parts.splice(0, output.parts.length, ...(nextParts as typeof output.parts))
+      } catch (error) {
+        await logError(client, error)
       }
-
-      output.parts.splice(0, output.parts.length, ...(nextParts as typeof output.parts))
     },
     "experimental.chat.messages.transform": async (_input, output) => {
-      const sessionID = output.messages[0]?.info.sessionID
-      if (!sessionID) return
-
-      const resolved = await resolveSessionState(client, ctx.directory, sessionID)
-      const activeState = resolved.state
-      if (!activeState) return
-
-      for (const message of output.messages as MessageWithPartsLike[]) {
-        if (message.info.role === "user") {
-          for (const part of message.parts) {
-            if (!isTextPart(part)) continue
-            if (!shouldRequireCache(part)) continue
-            const metadata = asMetadata(part)
-            const sourceHash = hashText(part.text)
-            if (
-              metadata.translate_enabled === true &&
-              metadata.translate_nonce === activeState.translate_nonce &&
-              metadata.translate_source_hash === sourceHash &&
-              typeof metadata.translate_en === "string"
-            ) {
-              part.text = metadata.translate_en
-              continue
+      try {
+        const sessionID = output.messages[0]?.info.sessionID
+        if (!sessionID) return
+
+        const resolved = await resolveSessionState(client, ctx.directory, sessionID)
+        const activeState = resolved.state
+        if (!activeState) return
+
+        for (const message of output.messages as MessageWithPartsLike[]) {
+          if (message.info.role === "user") {
+            for (const part of message.parts) {
+              if (!isTextPart(part)) continue
+              if (!shouldRequireCache(part)) continue
+              const metadata = asMetadata(part)
+              const sourceHash = hashText(part.text)
+              if (
+                metadata.translate_enabled === true &&
+                metadata.translate_nonce === activeState.translate_nonce &&
+                metadata.translate_source_hash === sourceHash &&
+                typeof metadata.translate_en === "string"
+              ) {
+                part.text = metadata.translate_en
+                continue
+              }
+
+              // Stale cache or untranslated text. Send it through as-is
+              // (English history would be ideal, but we shouldn't block the
+              // session). Also log so the user can diagnose if needed.
+              await logError(client, buildStaleCacheError())
             }
-
-            throw buildStaleCacheError()
           }
-        }
 
-        if (message.info.role === "assistant") {
-          for (const part of message.parts) {
-            if (!isTextPart(part)) continue
-            part.text = extractEnglishHistoryText(part.text, activeState.translate_nonce)
+          if (message.info.role === "assistant") {
+            for (const part of message.parts) {
+              if (!isTextPart(part)) continue
+              part.text = extractEnglishHistoryText(part.text, activeState.translate_nonce)
+            }
           }
         }
+      } catch (error) {
+        await logError(client, error)
       }
     },
     "experimental.text.complete": async (input, output) => {
-      const resolved = await resolveSessionState(client, ctx.directory, input.sessionID)
-      const activeState = resolved.state
-      if (!activeState) return
-
-      const message = unwrapData(
-        await client.session.message({
-          path: { id: input.sessionID, messageID: input.messageID },
-          query: { ...(ctx.directory ? { directory: ctx.directory } : {}) },
-          throwOnError: true,
-        }),
-      ) as MessageWithPartsLike & { info: Record<string, unknown> }
-
-      if (message.info.role !== "assistant") return
-      if (message.info.summary === true) return
-      if (activeState.translate_display_lang === LLM_LANGUAGE || output.text.length === 0) return
-
       try {
-        const translated = await translator.translateText({
-          text: output.text,
-          sourceLanguage: LLM_LANGUAGE,
-          targetLanguage: activeState.translate_display_lang,
-          direction: "outbound",
-        })
-
-        output.text = composeTranslatedAssistantText(
-          output.text,
-          getDisplayLanguageLabel(activeState.translate_display_lang),
-          translated,
-          activeState.translate_nonce,
-        )
+        const resolved = await resolveSessionState(client, ctx.directory, input.sessionID)
+        const activeState = resolved.state
+        if (!activeState) return
+
+        const message = unwrapData(
+          await client.session.message({
+            path: { id: input.sessionID, messageID: input.messageID },
+            query: { ...(ctx.directory ? { directory: ctx.directory } : {}) },
+            throwOnError: true,
+          }),
+        ) as MessageWithPartsLike & { info: Record<string, unknown> }
+
+        if (message.info.role !== "assistant") return
+        if (message.info.summary === true) return
+        if (activeState.translate_display_lang === LLM_LANGUAGE || output.text.length === 0) return
+
+        try {
+          const translated = await translator.translateText({
+            text: output.text,
+            sourceLanguage: LLM_LANGUAGE,
+            targetLanguage: activeState.translate_display_lang,
+            direction: "outbound",
+          })
+
+          output.text = composeTranslatedAssistantText(
+            output.text,
+            getDisplayLanguageLabel(activeState.translate_display_lang),
+            translated,
+            activeState.translate_nonce,
+          )
+        } catch (error) {
+          output.text = composeTranslationFailureText(output.text, activeState.translate_nonce)
+          await logError(client, error)
+        }
       } catch (error) {
-        output.text = composeTranslationFailureText(output.text, activeState.translate_nonce)
         await logError(client, error)
       }
     },

package/src/anthropic-oauth.ts

@@ -0,0 +1,148 @@
+// Anthropic OAuth request transformations.
+//
+// When using Anthropic's OAuth credentials (Claude Pro/Max) outside of the
+// official Claude Code client, the /v1/messages API responds with a
+// `429 rate_limit_error` and an empty "Error" message unless the request
+// shape matches the Claude Code CLI fingerprint: specific headers, a
+// `?beta=true` query, the Claude Code identity in `system[0]`, and a
+// deterministic billing header block.
+//
+// This module implements the minimum transformation that makes translator
+// requests pass those checks. The technique (including the identity string,
+// required beta headers, and CCH billing header format) is documented by the
+// `@ex-machina/opencode-anthropic-auth` plugin:
+//
+//   https://github.com/ex-machina-co/opencode-anthropic-auth
+//
+// We only apply these transformations to translator requests this plugin
+// originates. OpenCode's main chat already has its own auth loader (e.g.
+// `@ex-machina/opencode-anthropic-auth`) handling its requests independently.
+
+import { createHash } from "node:crypto"
+
+export const CLAUDE_CODE_IDENTITY = "You are a Claude agent, built on Anthropic's Claude Agent SDK."
+
+export const REQUIRED_BETAS = ["oauth-2025-04-20", "interleaved-thinking-2025-05-14"] as const
+
+export const CLAUDE_CODE_VERSION = "2.1.87"
+export const CLAUDE_CODE_ENTRYPOINT = "sdk-cli"
+export const CLAUDE_CLI_USER_AGENT = `claude-cli/${CLAUDE_CODE_VERSION} (external, cli)`
+
+// Deterministic billing header parameters — must match Claude Code's own derivation.
+const CCH_SALT = "59cf53e54c78"
+const CCH_POSITIONS = [4, 7, 20] as const
+
+type SystemBlock = { type: string; text: string; [key: string]: unknown }
+
+type MessageLike = {
+  role?: string
+  content?: string | Array<{ type?: string; text?: string }>
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === "object" && !Array.isArray(value)
+}
+
+function extractFirstUserMessageText(messages: MessageLike[] | undefined): string {
+  if (!Array.isArray(messages)) return ""
+  const first = messages.find((message) => message?.role === "user")
+  if (!first) return ""
+  const { content } = first
+  if (typeof content === "string") return content
+  if (Array.isArray(content)) {
+    const textBlock = content.find((block) => block?.type === "text")
+    if (textBlock?.text) return textBlock.text
+  }
+  return ""
+}
+
+function computeCCH(messageText: string): string {
+  return createHash("sha256").update(messageText).digest("hex").slice(0, 5)
+}
+
+function computeVersionSuffix(messageText: string, version: string): string {
+  const chars = CCH_POSITIONS.map((index) => messageText[index] ?? "0").join("")
+  return createHash("sha256").update(`${CCH_SALT}${chars}${version}`).digest("hex").slice(0, 3)
+}
+
+export function buildBillingHeaderValue(messages: MessageLike[] | undefined): string {
+  const text = extractFirstUserMessageText(messages)
+  const cch = computeCCH(text)
+  const suffix = computeVersionSuffix(text, CLAUDE_CODE_VERSION)
+  return (
+    "x-anthropic-billing-header: " +
+    `cc_version=${CLAUDE_CODE_VERSION}.${suffix}; ` +
+    `cc_entrypoint=${CLAUDE_CODE_ENTRYPOINT}; ` +
+    `cch=${cch};`
+  )
+}
+
+export function mergeBetaHeaders(headers: Headers): string {
+  const incoming = headers.get("anthropic-beta") || ""
+  const incomingList = incoming
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean)
+  return [...new Set([...REQUIRED_BETAS, ...incomingList])].join(",")
+}
+
+export function setOAuthHeaders(headers: Headers, accessToken: string): Headers {
+  headers.set("authorization", `Bearer ${accessToken}`)
+  headers.set("anthropic-beta", mergeBetaHeaders(headers))
+  headers.set("user-agent", CLAUDE_CLI_USER_AGENT)
+  headers.delete("x-api-key")
+  return headers
+}
+
+export function rewriteMessagesURL(input: URL): URL {
+  if (input.pathname === "/v1/messages" && !input.searchParams.has("beta")) {
+    input.searchParams.set("beta", "true")
+  }
+  return input
+}
+
+function normalizeSystem(raw: unknown): SystemBlock[] {
+  if (raw == null) return []
+  if (typeof raw === "string") return raw.length > 0 ? [{ type: "text", text: raw }] : []
+  if (isRecord(raw)) {
+    const type = typeof raw.type === "string" ? raw.type : "text"
+    const text = typeof raw.text === "string" ? raw.text : ""
+    return [{ ...raw, type, text }]
+  }
+  if (!Array.isArray(raw)) return []
+  return raw
+    .map((item): SystemBlock | null => {
+      if (typeof item === "string") return { type: "text", text: item }
+      if (isRecord(item) && typeof item.text === "string") {
+        const type = typeof item.type === "string" ? item.type : "text"
+        return { ...item, type, text: item.text }
+      }
+      return null
+    })
+    .filter((block): block is SystemBlock => block !== null)
+}
+
+export function buildOAuthSystem(rawSystem: unknown, messages: MessageLike[] | undefined): SystemBlock[] {
+  const identity: SystemBlock = { type: "text", text: CLAUDE_CODE_IDENTITY }
+  const existing = normalizeSystem(rawSystem).filter((block) => block.text !== CLAUDE_CODE_IDENTITY)
+  const billing: SystemBlock = { type: "text", text: buildBillingHeaderValue(messages) }
+  return [billing, identity, ...existing]
+}
+
+// Rewrite an /v1/messages POST body so its system prompt and billing header
+// satisfy Claude Code's OAuth fingerprint. Returns the original body on parse
+// failure so we never break a request that was already well-formed.
+export function rewriteMessagesBody(body: string): string {
+  try {
+    const parsed = JSON.parse(body) as Record<string, unknown>
+    const messages = Array.isArray(parsed.messages) ? (parsed.messages as MessageLike[]) : undefined
+    parsed.system = buildOAuthSystem(parsed.system, messages)
+    return JSON.stringify(parsed)
+  } catch {
+    return body
+  }
+}
+
+export function isAnthropicMessagesRequest(url: URL): boolean {
+  return url.pathname === "/v1/messages"
+}

package/src/auth.ts

@@ -2,6 +2,12 @@ import { readFile, stat } from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
 import { setTimeout as sleep } from "node:timers/promises"
+import {
+  isAnthropicMessagesRequest,
+  rewriteMessagesBody,
+  rewriteMessagesURL,
+  setOAuthHeaders as setAnthropicOAuthHeaders,
+} from "./anthropic-oauth"
 import {
   AUTH_ENV_FALLBACK,
   type AuthInfo,
@@ -385,13 +391,16 @@ export function createCredentialResolver(
       const inputUrl =
         input instanceof URL ? new URL(input.href) : new URL(typeof input === "string" ? input : input.url)
 
+      let nextBody = init?.body
+
       if (providerID === "anthropic") {
-        headers.set("Authorization", `Bearer ${info.access}`)
-        headers.set("anthropic-beta", "oauth-2025-04-20,interleaved-thinking-2025-05-14")
+        // Match the Claude Code CLI fingerprint so Anthropic's OAuth rate-limit
+        // guard doesn't reject third-party agents. See src/anthropic-oauth.ts.
+        setAnthropicOAuthHeaders(headers, info.access)
         headers.set("anthropic-version", "2023-06-01")
-        headers.delete("x-api-key")
-        if (inputUrl.pathname === "/v1/messages" && !inputUrl.searchParams.has("beta")) {
-          inputUrl.searchParams.set("beta", "true")
+        rewriteMessagesURL(inputUrl)
+        if (isAnthropicMessagesRequest(inputUrl) && typeof nextBody === "string") {
+          nextBody = rewriteMessagesBody(nextBody)
         }
       }
 
@@ -436,6 +445,7 @@ export function createCredentialResolver(
       return fetchImpl(inputUrl, {
         ...init,
         headers,
+        body: nextBody,
       })
     }
   }

package/src/translator.ts

@@ -20,6 +20,7 @@ interface TranslatorDependencies {
   sleep?: (ms: number) => Promise<void>
   now?: () => number
   credentialResolver?: ReturnType<typeof createCredentialResolver>
+  timeoutMs?: number
 }
 
 interface TranslateTextInput {
@@ -29,6 +30,26 @@ interface TranslateTextInput {
   direction: "inbound" | "outbound"
 }
 
+// Hard timeout for a single generateText call. Without this, a stalled
+// provider request can block the chat.message hook indefinitely.
+const DEFAULT_TRANSLATE_TIMEOUT_MS = 60_000
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs)
+    promise.then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      (error) => {
+        clearTimeout(timer)
+        reject(error)
+      },
+    )
+  })
+}
+
 const providerFactoryCache = new Map<string, unknown>()
 
 export function __resetTranslatorCachesForTest() {
@@ -193,6 +214,7 @@ export function createTranslator(
   const now = deps.now ?? (() => Date.now())
   const generateTextImpl = deps.generateTextImpl ?? generateText
   const credentialResolver = deps.credentialResolver ?? createCredentialResolver(client, options)
+  const timeoutMs = deps.timeoutMs ?? DEFAULT_TRANSLATE_TIMEOUT_MS
 
   async function translateText(input: TranslateTextInput): Promise<string> {
     if (!input.text) return input.text
@@ -213,21 +235,25 @@ export function createTranslator(
       try {
         const translated = await withRetry(async () => {
           try {
-            const result = (await generateTextImpl({
-              model: model as never,
-              system: buildSystemPrompt({
-                sourceLanguage: input.sourceLanguage,
-                targetLanguage: input.targetLanguage,
-                text: protectedText.text,
-                strictPlaceholderRetry: missingPlaceholders,
-              }),
-              temperature: 0,
-              prompt: buildUserPrompt({
-                sourceLanguage: input.sourceLanguage,
-                targetLanguage: input.targetLanguage,
-                text: protectedText.text,
-              }),
-            })) as { text: string }
+            const result = (await withTimeout(
+              generateTextImpl({
+                model: model as never,
+                system: buildSystemPrompt({
+                  sourceLanguage: input.sourceLanguage,
+                  targetLanguage: input.targetLanguage,
+                  text: protectedText.text,
+                  strictPlaceholderRetry: missingPlaceholders,
+                }),
+                temperature: 0,
+                prompt: buildUserPrompt({
+                  sourceLanguage: input.sourceLanguage,
+                  targetLanguage: input.targetLanguage,
+                  text: protectedText.text,
+                }),
+              }) as Promise<{ text: string }>,
+              timeoutMs,
+              "Translator generateText",
+            )) as { text: string }
             return result.text
           } catch (error) {
             if (isAuthMessage(error)) throw error