pi-openai-toolkit 0.4.1 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 # pi-openai-toolkit
 
 <p align="center">
-  <strong>OpenAI-focused toolkit for <a href="https://github.com/badlogic/pi">Pi</a>: Native Remote Compaction v2 & Hosted Web Search</strong>
+  <strong>OpenAI-focused toolkit for <a href="https://github.com/badlogic/pi">Pi</a>: Native Remote Compaction v2, Hosted Web Search & Real-time Reasoning Translation</strong>
 </p>
 
 <p align="center">
@@ -10,10 +10,11 @@
 
 ---
 
-`pi-openai-toolkit` is an all-in-one OpenAI enhancement package for **Pi (>= 0.84.x)**. It bundles two high-performance extensions designed for OpenAI Responses endpoints:
+`pi-openai-toolkit` is an all-in-one OpenAI enhancement package for **Pi (>= 0.84.x)**. It bundles three independent extensions:
 
 1. **Remote Responses Compaction v2** (`extensions/compaction.ts`): Server-side opaque context compaction using the `remote_compaction_v2` SSE streaming protocol. Preserves context fidelity without lossy text re-summarization.
 2. **Model-Scoped Web Search** (`extensions/web-search.ts`): Toolkit-owned hosted Web Search for an exact `provider/model-id` allowlist configured with `webSearch.models`, across the supported `openai-responses` and `openai-codex-responses` APIs.
+3. **Real-time Reasoning Translation** (`extensions/reasoning-translation.ts`): TUI-only, display-layer translation of streaming thinking/reasoning segments through a separately configured model. It never changes the assistant message or the model context.
 
 ## Installation
 
@@ -57,6 +58,9 @@ pi --no-extensions -e /absolute/path/to/pi-openai-toolkit/extensions/compaction.
 
 # Web Search only
 pi --no-extensions -e /absolute/path/to/pi-openai-toolkit/extensions/web-search.ts
+
+# Reasoning Translation only
+pi --no-extensions -e /absolute/path/to/pi-openai-toolkit/extensions/reasoning-translation.ts
 ```
 
 > ⚠️ **Conflict Warning**: Do not run `pi-remote-compact`, `@lll9p/pi-better-compaction`, or standalone `pi-openai-web-search` alongside `pi-openai-toolkit`. Duplicate hooks cause race conditions and duplicated system prompts.
@@ -103,6 +107,14 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
     "models": [
       "uwoacrimson/gpt-5.6-luna"
     ]
+  },
+  "reasoningTranslation": {
+    "enabled": true,
+    "models": [
+      "uwoacrimson/gpt-5.6-luna"
+    ],
+    "model": "openai/gpt-4o-mini",
+    "targetLanguage": "Simplified Chinese"
   }
 }
 ```
@@ -128,6 +140,19 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 - `enabled` (*boolean*, default: `true`): Enable or disable native OpenAI Web Search injection.
 - `models` (*string[]*): Exact `provider/model-id` allowlist. Toolkit Web Search is used only for listed models running on `openai-responses` or `openai-codex-responses`. An empty list disables toolkit Web Search for all models.
 
+#### `reasoningTranslation`
+
+- `enabled` (*boolean*, default: `true`): Enable display-only reasoning translation when the other fields also match.
+- `models` (*string[]*): Exact source-model allowlist. The key must be `provider/model-id`; an empty list disables translation.
+- `model` (*string | null*, default: `null`): Separate `provider/model-id` used for translation requests. It is never selected as Pi's active model and is called with thinking/reasoning disabled.
+- `targetLanguage` (*string*, default: `"Simplified Chinese"`): Natural-language name passed to the translator prompt.
+
+Reasoning Translation runs only in Pi's interactive **TUI** mode and only while the thinking area is visible. It listens to streaming `thinking_delta` events, groups text at sentence/newline boundaries, cuts unbroken text at about 400 UTF-16 characters, and flushes an idle tail after about 800 ms or at `thinking_end`. Requests run one at a time in FIFO order, so a slow segment cannot reorder the display.
+
+The Markdown transformer replaces only what the TUI renders. Original assistant thinking remains in the session and in every later provider/context payload; no custom message or tool call is sent to the main model. Completed display projections are stored as invisible custom session entries so resumed sessions can restore the same presentation. RPC, JSON, and print modes never call the translator and preserve Pi's original stream output.
+
+Translation adds model latency and usage cost. If the translator is missing, unavailable, rate-limited, times out, returns empty output, or fails for one segment, the main response continues; that segment falls back to its exact source text and later segments continue. Aborting, switching models/sessions, reloading, or quitting cancels the active queue and ignores late results.
+
 ---
 
 ## Core Mechanics
@@ -169,6 +194,10 @@ For allowlisted models using `openai-responses` or `openai-codex-responses`, the
 - **Zero-Latency**: Uses Pi's existing connection, auth headers, and base URL without standalone HTTP overhead.
 - **Toolkit Ownership**: For an eligible model, the outgoing payload removes the local function tool named `web_search` so native search is the only search path. Switching to an ineligible model restores that local tool's previous active state.
 
+### 3. Real-time Reasoning Translation
+
+The translation extension is intentionally independent from compaction and Web Search. It registers lifecycle listeners and one synchronous Markdown transformer, but no Function Tool and no provider-request rewrite. A nested `streamSimple()` call is made directly on the configured translator provider, which avoids switching the active Pi model and avoids recursive toolkit hooks. The TUI invalidation bridge refreshes the existing thinking container after each completed segment, preserving Pi's color, italic, and folding behavior.
+
 ---
 
 ## Development & Testing

package/README_zh.md

@@ -1,7 +1,7 @@
 # pi-openai-toolkit
 
 <p align="center">
-  <strong>专为 <a href="https://github.com/badlogic/pi">Pi</a> 打造的 OpenAI 全功能增强工具包：远端无损压缩 v2 & 原生托管联网搜索</strong>
+  <strong>专为 <a href="https://github.com/badlogic/pi">Pi</a> 打造的 OpenAI 全功能增强工具包：远端无损压缩 v2、原生托管联网搜索与实时思考翻译</strong>
 </p>
 
 <p align="center">
@@ -10,10 +10,11 @@
 
 ---
 
-`pi-openai-toolkit` 是专为 **Pi (>= 0.84.x)** 打造的 OpenAI 全功能增强工具包，集成了两项针对 OpenAI Responses 协议的核心扩展：
+`pi-openai-toolkit` 是专为 **Pi (>= 0.84.x)** 打造的 OpenAI 全功能增强工具包，集成了三个可独立加载的扩展：
 
 1. **远端无损压缩 (Remote Compaction v2)** (`extensions/compaction.ts`): 基于 `remote_compaction_v2` SSE 流式协议实现的服务端密文无损会话压缩，彻底告别会话变长后丢失细节的文本二次摘要。
 2. **按模型启用的联网搜索** (`extensions/web-search.ts`): 通过 `webSearch.models` 精确匹配 `provider/model-id`，由 Toolkit 为符合条件的 `openai-responses` 与 `openai-codex-responses` 会话提供并拥有原生联网搜索。
+3. **实时思考翻译** (`extensions/reasoning-translation.ts`): 仅在 TUI 展示层把流式 thinking/reasoning 分段翻译为目标语言。它使用独立配置的翻译模型，不修改 assistant 消息、会话原文或主模型上下文。
 
 ## 安装使用
 
@@ -57,6 +58,9 @@ pi --no-extensions -e /本地绝对路径/pi-openai-toolkit/extensions/compactio
 
 # 仅加载原生联网搜索
 pi --no-extensions -e /本地绝对路径/pi-openai-toolkit/extensions/web-search.ts
+
+# 仅加载实时思考翻译
+pi --no-extensions -e /本地绝对路径/pi-openai-toolkit/extensions/reasoning-translation.ts
 ```
 
 > ⚠️ **冲突提示**：请勿同时启用 `pi-remote-compact`、`@lll9p/pi-better-compaction` 或独立的 `pi-openai-web-search`。多重钩子会产生竞态或注入重复的 System Prompt。
@@ -103,6 +107,14 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
     "models": [
       "uwoacrimson/gpt-5.6-luna"
     ]
+  },
+  "reasoningTranslation": {
+    "enabled": true,
+    "models": [
+      "uwoacrimson/gpt-5.6-luna"
+    ],
+    "model": "openai/gpt-4o-mini",
+    "targetLanguage": "Simplified Chinese"
   }
 }
 ```
@@ -128,6 +140,19 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 - `enabled` (*boolean*, 默认 `true`): 是否启用原生 OpenAI 联网搜索注入。
 - `models` (*string[]*): 精确的 `provider/model-id` 模型白名单。只有列表中的模型在 `openai-responses` 或 `openai-codex-responses` 端点上运行时，才会使用 Toolkit Web Search。空列表表示所有模型都不启用 Toolkit Web Search。
 
+#### `reasoningTranslation`（实时思考翻译配置）
+
+- `enabled` (*boolean*, 默认 `true`): 是否启用展示层思考翻译。
+- `models` (*string[]*): 主模型的精确 `provider/model-id` 白名单。空列表表示不翻译任何模型。
+- `model` (*string | null*, 默认 `null`): 独立的翻译模型，格式为 `provider/model-id`。它不会被设置为 Pi 当前模型，翻译请求也不会启用 thinking/reasoning。
+- `targetLanguage` (*string*, 默认 `"Simplified Chinese"`): 传给翻译模型的目标语言名称，可以改为其他自然语言。
+
+实时思考翻译只在 Pi 交互式 **TUI** 模式运行，并且要求 Pi 没有全局隐藏 thinking 区域。扩展监听流式 `thinking_delta`，优先在句号、问号、分号或换行处分段；没有自然边界时约每 400 个 UTF-16 字符切分，空闲约 800 ms 或收到 `thinking_end` 时刷新尾部。翻译请求严格按 FIFO 单并发执行，不会因为响应速度不同而乱序。
+
+替换只发生在 TUI 的 Markdown 展示层。session 中的原始 assistant thinking、后续 Provider payload、LLM 上下文和压缩输入都保持不变；扩展不会注册 Function Tool，也不会向主模型发送 custom message。已完成的展示映射会作为不可见的 custom entry 保存，恢复 session 或切换会话树后可以继续替换对应原文。RPC、JSON 与 print 模式不会调用翻译模型，也不会改变 Pi 原始输出。
+
+翻译会增加额外延迟和模型费用。翻译模型未配置、认证失败、模型不存在、超时、限流、空输出或某个分段失败时，主模型响应仍会继续；失败分段精确回退为原文，后续分段继续处理。中止、切换模型/会话、扩展重载或退出时会取消当前队列并忽略迟到结果。
+
 ---
 
 ## 核心工作原理解析
@@ -169,6 +194,10 @@ Content-Type: application/json
 - **零额外网络延迟**：复用 Pi 当前活跃的 Provider 配置、认证凭据与 Base URL；
 - **Toolkit 接管搜索**：对于符合条件的模型，发给 Provider 的载荷会移除名为 `web_search` 的本地 Function Tool，只保留原生搜索；切换到不符合条件的模型后，会恢复该本地工具原先的 active 状态。
 
+### 3. 实时思考翻译
+
+该扩展与压缩、联网搜索彼此独立：只注册生命周期监听器和一个同步 Markdown transformer，不注册 Function Tool，也不改写主模型的 Provider request。翻译直接调用配置模型所属 Provider 的 `streamSimple()`，因此不会切换当前模型，也不会递归触发 Toolkit 的其他请求钩子。每个分段完成后通过 Pi 公共的 `setHiddenThinkingLabel()` 触发展示刷新，继续使用 Pi 原有 thinking 容器的颜色、斜体和折叠行为。
+
 ---
 
 ## 测试与验证

package/extensions/reasoning-translation.ts

@@ -0,0 +1,2 @@
+export { default } from "../src/reasoning-translation/extension.ts";
+export { registerReasoningTranslationExtension } from "../src/reasoning-translation/extension.ts";

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
-  "description": "OpenAI-focused Pi toolkit providing remote Responses compaction and native Web Search.",
+  "description": "OpenAI-focused Pi toolkit providing remote Responses compaction, native Web Search, and TUI reasoning translation.",
   "author": "awoaCrim and contributors",
   "license": "MIT",
   "repository": {
@@ -24,18 +24,21 @@
     "openai",
     "compaction",
     "web-search",
+    "reasoning-translation",
     "codex",
     "responses"
   ],
   "pi": {
     "extensions": [
       "./extensions/compaction.ts",
-      "./extensions/web-search.ts"
+      "./extensions/web-search.ts",
+      "./extensions/reasoning-translation.ts"
     ]
   },
   "files": [
     "extensions/compaction.ts",
     "extensions/web-search.ts",
+    "extensions/reasoning-translation.ts",
     "src/compact-client.ts",
     "src/config.ts",
     "src/debug.ts",
@@ -54,6 +57,12 @@
     "src/web-search/payload.ts",
     "src/web-search/prompt.ts",
     "src/web-search/types.ts",
+    "src/reasoning-translation/client.ts",
+    "src/reasoning-translation/extension.ts",
+    "src/reasoning-translation/persistence.ts",
+    "src/reasoning-translation/segmenter.ts",
+    "src/reasoning-translation/state.ts",
+    "src/reasoning-translation/types.ts",
     "README.md",
     "README_zh.md",
     "LICENSE",

package/src/config.ts

@@ -2,8 +2,10 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { parseModelSpec } from "./runtime";
 import {
 	DEFAULT_COMPACTION_CONFIG,
+	DEFAULT_REASONING_TRANSLATION_CONFIG,
 	DEFAULT_TOOLKIT_CONFIG,
 	DEFAULT_WEB_SEARCH_CONFIG,
 	RESPONSES_COMPACT_CAPABLE_APIS,
@@ -11,6 +13,7 @@ import {
 	TOOLKIT_ID,
 	type CompactionConfig,
 	type LoadedToolkitConfig,
+	type ReasoningTranslationConfig,
 	type ToolkitConfig,
 	type WebSearchConfig,
 } from "./types";
@@ -18,7 +21,7 @@ import {
 export const CONFIG_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", TOOLKIT_ID);
 export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 
-const TOP_LEVEL_FIELDS = new Set(["compaction", "webSearch"]);
+const TOP_LEVEL_FIELDS = new Set(["compaction", "webSearch", "reasoningTranslation"]);
 const COMPACTION_FIELDS = new Set([
 	"enabled",
 	"allowCompactionContinuityBreak",
@@ -34,6 +37,7 @@ const COMPACTION_FIELDS = new Set([
 	"artifactRoot",
 ]);
 const WEB_SEARCH_FIELDS = new Set(["enabled", "models"]);
+const REASONING_TRANSLATION_FIELDS = new Set(["enabled", "models", "model", "targetLanguage"]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object" && !Array.isArray(value);
@@ -158,6 +162,10 @@ function cloneDefaults(): ToolkitConfig {
 			...DEFAULT_WEB_SEARCH_CONFIG,
 			models: [...DEFAULT_WEB_SEARCH_CONFIG.models],
 		},
+		reasoningTranslation: {
+			...DEFAULT_REASONING_TRANSLATION_CONFIG,
+			models: [...DEFAULT_REASONING_TRANSLATION_CONFIG.models],
+		},
 	};
 }
 
@@ -236,6 +244,40 @@ function applyWebSearchConfig(
 	}
 }
 
+function applyReasoningTranslationConfig(
+	raw: Record<string, unknown>,
+	resolved: ReasoningTranslationConfig,
+	warnings: string[],
+): void {
+	warnUnknownFields(raw, REASONING_TRANSLATION_FIELDS, "reasoningTranslation", warnings);
+	resolved.enabled =
+		toBoolean(raw.enabled, "reasoningTranslation.enabled", warnings) ?? resolved.enabled;
+
+	const models = toModelAllowlist(raw.models, "reasoningTranslation.models", warnings);
+	if (models !== undefined) {
+		resolved.models = models;
+	}
+
+	const modelSpec = toModelSpec(raw.model, "reasoningTranslation.model", warnings);
+	if (modelSpec !== undefined) {
+		if (modelSpec !== null && !parseModelSpec(modelSpec)) {
+			warnings.push(
+				"Ignoring reasoningTranslation.model: expected \"provider/model-id\" or null.",
+			);
+		} else {
+			resolved.model = modelSpec === null ? undefined : modelSpec;
+		}
+	}
+
+	if (raw.targetLanguage !== undefined) {
+		if (typeof raw.targetLanguage === "string" && raw.targetLanguage.trim().length > 0) {
+			resolved.targetLanguage = raw.targetLanguage.trim();
+		} else {
+			warnings.push("Ignoring reasoningTranslation.targetLanguage: expected a non-empty string.");
+		}
+	}
+}
+
 /**
  * Load the canonical toolkit config from
  * `~/.pi/agent/extensions/pi-openai-toolkit/config.json`.
@@ -266,6 +308,14 @@ export function loadToolkitConfig(configPath: string = CONFIG_PATH): LoadedToolk
 				warnings.push("Ignoring webSearch: expected a JSON object.");
 			}
 		}
+
+		if (raw.reasoningTranslation !== undefined) {
+			if (isRecord(raw.reasoningTranslation)) {
+				applyReasoningTranslationConfig(raw.reasoningTranslation, resolved.reasoningTranslation, warnings);
+			} else {
+				warnings.push("Ignoring reasoningTranslation: expected a JSON object.");
+			}
+		}
 	}
 
 	resolved.compaction.artifactRoot = resolveConfiguredPath(

package/src/reasoning-translation/client.ts

@@ -0,0 +1,187 @@
+import type { Api, AssistantMessage, Context, Model, Provider, Usage } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { parseModelSpec } from "../runtime";
+import { MAX_TRANSLATION_OUTPUT_TOKENS, TRANSLATION_TIMEOUT_MS } from "./types";
+
+export type TranslatorFailureReason =
+	| "invalid-model-spec"
+	| "model-not-found"
+	| "provider-not-found"
+	| "auth-failed"
+	| "aborted"
+	| "request-failed"
+	| "empty-output";
+
+export type TranslateSegmentResult =
+	| { ok: true; text: string; usage?: Usage }
+	| { ok: false; reason: TranslatorFailureReason; errorMessage?: string };
+
+export type ResolvedTranslator = {
+	model: Model<Api>;
+	provider: Provider;
+	apiKey?: string;
+	headers?: Record<string, string | null>;
+	env?: Record<string, string>;
+};
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function isAbortError(error: unknown): boolean {
+	return (
+		(error instanceof DOMException && error.name === "AbortError") ||
+		(error instanceof Error && (error.name === "AbortError" || error.name === "ABORT_ERR"))
+	);
+}
+
+export function buildTranslationPrompt(targetLanguage: string): string {
+	return [
+		`Translate the following reasoning into ${targetLanguage}.`,
+		"Return only the faithful translation, with no summary, explanation, commentary, or added content.",
+		"Preserve code, commands, file paths, URLs, identifiers, formatting markers, and technical terms exactly unless they must be translated for grammatical context.",
+	].join(" ");
+}
+
+export async function resolveTranslator(
+	ctx: ExtensionContext,
+	modelSpec: string | undefined,
+): Promise<ResolvedTranslator | { ok: false; reason: TranslatorFailureReason; errorMessage?: string }> {
+	if (!modelSpec) return { ok: false, reason: "invalid-model-spec" };
+	const parsed = parseModelSpec(modelSpec);
+	if (!parsed) return { ok: false, reason: "invalid-model-spec" };
+
+	let model: Model<Api> | undefined;
+	try {
+		model = ctx.modelRegistry.find(parsed.provider, parsed.modelId);
+	} catch (error) {
+		return { ok: false, reason: "model-not-found", errorMessage: errorMessage(error) };
+	}
+	if (!model) {
+		return { ok: false, reason: "model-not-found" };
+	}
+
+	let provider: Provider | undefined;
+	try {
+		provider = ctx.modelRegistry.getProvider(parsed.provider);
+	} catch (error) {
+		return { ok: false, reason: "provider-not-found", errorMessage: errorMessage(error) };
+	}
+	if (!provider) {
+		return { ok: false, reason: "provider-not-found" };
+	}
+
+	try {
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (!auth.ok) return { ok: false, reason: "auth-failed", errorMessage: auth.error };
+		return {
+			// Auth resolution may provide an OAuth-specific endpoint. The provider
+			// receives the effective model directly, so preserve that base URL while
+			// disabling reasoning on the cloned translator model.
+			model: {
+				...model,
+				...(auth.baseUrl ? { baseUrl: auth.baseUrl } : {}),
+				reasoning: false,
+			},
+			provider,
+			apiKey: auth.apiKey,
+			headers: auth.headers,
+			env: auth.env,
+		};
+	} catch (error) {
+		return { ok: false, reason: "auth-failed", errorMessage: errorMessage(error) };
+	}
+}
+
+function extractText(message: AssistantMessage): string {
+	return message.content
+		.filter((content): content is Extract<AssistantMessage["content"][number], { type: "text" }> => content.type === "text")
+		.map((content) => content.text)
+		.join("")
+		.trim();
+}
+
+export async function translateSegment(args: {
+	translator: ResolvedTranslator;
+	targetLanguage: string;
+	sourceSegment: string;
+	signal: AbortSignal;
+}): Promise<TranslateSegmentResult> {
+	if (args.signal.aborted) return { ok: false, reason: "aborted" };
+
+	const context: Context = {
+		systemPrompt: buildTranslationPrompt(args.targetLanguage),
+		messages: [{ role: "user", content: args.sourceSegment, timestamp: Date.now() }],
+	};
+
+	const controller = new AbortController();
+	let rejectAbort: ((reason?: unknown) => void) | undefined;
+	let timedOut = false;
+	const abortPromise = new Promise<never>((_, reject) => {
+		rejectAbort = reject;
+	});
+	const onAbort = () => {
+		controller.abort();
+		rejectAbort?.(new DOMException("Translation request aborted", "AbortError"));
+	};
+	args.signal.addEventListener("abort", onAbort, { once: true });
+	let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+	try {
+		// Keep the call safe even when a ResolvedTranslator is supplied by a test
+		// seam or another internal caller instead of resolveTranslator().
+		const effectiveModel = args.translator.model.reasoning
+			? { ...args.translator.model, reasoning: false }
+			: args.translator.model;
+		const stream = args.translator.provider.streamSimple(effectiveModel, context, {
+			apiKey: args.translator.apiKey,
+			headers: args.translator.headers,
+			env: args.translator.env,
+			signal: controller.signal,
+			timeoutMs: TRANSLATION_TIMEOUT_MS,
+			maxTokens: Math.max(1, Math.min(args.translator.model.maxTokens, MAX_TRANSLATION_OUTPUT_TOKENS)),
+		});
+		const timeoutPromise = new Promise<never>((_, reject) => {
+			timeoutId = setTimeout(() => {
+				timedOut = true;
+				controller.abort();
+				reject(new Error(`Translation request timed out after ${TRANSLATION_TIMEOUT_MS} ms.`));
+			}, TRANSLATION_TIMEOUT_MS);
+		});
+		const message = await Promise.race([stream.result(), abortPromise, timeoutPromise]);
+		if (args.signal.aborted) return { ok: false, reason: "aborted" };
+		if (timedOut) {
+			return {
+				ok: false,
+				reason: "request-failed",
+				errorMessage: `Translation request timed out after ${TRANSLATION_TIMEOUT_MS} ms.`,
+			};
+		}
+		if (message.stopReason === "aborted") {
+			return { ok: false, reason: "request-failed", errorMessage: "Translator aborted the request." };
+		}
+		if (message.stopReason !== "stop" && message.stopReason !== "length") {
+			return { ok: false, reason: "request-failed", errorMessage: message.errorMessage };
+		}
+		const text = extractText(message);
+		return text.length > 0
+			? { ok: true, text, usage: message.usage }
+			: { ok: false, reason: "empty-output" };
+	} catch (error) {
+		if (args.signal.aborted) return { ok: false, reason: "aborted" };
+		if (timedOut) {
+			return {
+				ok: false,
+				reason: "request-failed",
+				errorMessage: `Translation request timed out after ${TRANSLATION_TIMEOUT_MS} ms.`,
+			};
+		}
+		if (isAbortError(error)) {
+			return { ok: false, reason: "request-failed", errorMessage: errorMessage(error) };
+		}
+		return { ok: false, reason: "request-failed", errorMessage: errorMessage(error) };
+	} finally {
+		if (timeoutId !== undefined) clearTimeout(timeoutId);
+		args.signal.removeEventListener("abort", onAbort);
+	}
+}

package/src/reasoning-translation/extension.ts

@@ -0,0 +1,105 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadToolkitConfig } from "../config";
+import type { LoadedToolkitConfig } from "../types";
+import { ReasoningTranslationState } from "./state";
+
+function refreshThinkingDisplay(ctx: ExtensionContext | undefined): void {
+	if (!ctx || ctx.mode !== "tui" || !ctx.hasUI) return;
+	try {
+		// Pi exposes no direct transcript invalidation API. Calling the public
+		// setter rebuilds assistant components and reruns transformers, while the
+		// no-argument form avoids leaving "Translating…" as the global hidden label.
+		ctx.ui.setHiddenThinkingLabel();
+	} catch {
+		// A display refresh is additive; never break the main model stream.
+	}
+}
+
+function restoreThinkingDisplay(ctx: ExtensionContext | undefined): void {
+	if (!ctx || ctx.mode !== "tui" || !ctx.hasUI) return;
+	try {
+		ctx.ui.setHiddenThinkingLabel();
+	} catch {
+		// Shutdown/reload must remain failure-open.
+	}
+}
+
+export function registerReasoningTranslationExtension(
+	pi: ExtensionAPI,
+	loadConfig: typeof loadToolkitConfig = loadToolkitConfig,
+): void {
+	let latestContext: ExtensionContext | undefined;
+	const state = new ReasoningTranslationState({
+		onDisplayChanged: () => refreshThinkingDisplay(latestContext),
+		appendEntry: (customType, data) => pi.appendEntry(customType, data),
+	});
+
+	pi.registerMarkdownTransformer((markdown, context) => {
+		if (context.messageType !== "assistant-thinking" || latestContext?.mode !== "tui") return markdown;
+		return state.lookupDisplay(markdown) ?? markdown;
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		latestContext = ctx;
+		state.abortActive();
+		const { config } = loadConfig() as LoadedToolkitConfig;
+		state.hydrate(ctx, config.reasoningTranslation);
+	});
+
+	pi.on("session_tree", (_event, ctx) => {
+		latestContext = ctx;
+		state.abortActive();
+		const { config } = loadConfig() as LoadedToolkitConfig;
+		state.hydrate(ctx, config.reasoningTranslation);
+	});
+
+	pi.on("session_before_switch", () => {
+		state.abortActive();
+	});
+
+	pi.on("session_before_fork", () => {
+		state.abortActive();
+	});
+
+	pi.on("session_before_tree", () => {
+		state.abortActive();
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		if (latestContext === ctx) latestContext = undefined;
+		state.abortActive();
+		restoreThinkingDisplay(ctx);
+	});
+
+	pi.on("model_select", (_event, ctx) => {
+		latestContext = ctx;
+		state.abortActive();
+		const { config } = loadConfig() as LoadedToolkitConfig;
+		state.setDisplayEligibility(ctx, config.reasoningTranslation);
+	});
+
+	pi.on("message_start", (event, ctx) => {
+		latestContext = ctx;
+		const { config } = loadConfig() as LoadedToolkitConfig;
+		state.beginMessage(event.message, ctx, config.reasoningTranslation);
+	});
+
+	pi.on("message_update", (event, ctx) => {
+		latestContext = ctx;
+		if (ctx.mode !== "tui") return;
+		const update = event.assistantMessageEvent;
+		if (update.type !== "thinking_delta" && update.type !== "thinking_end") return;
+		state.handleMessageUpdate(event.message, update.type, update.contentIndex);
+	});
+
+	pi.on("message_end", (event, ctx) => {
+		latestContext = ctx;
+		if (ctx.mode !== "tui") return;
+		state.finishMessage(event.message);
+	});
+
+}
+
+export default function reasoningTranslationExtension(pi: ExtensionAPI): void {
+	registerReasoningTranslationExtension(pi);
+}

package/src/reasoning-translation/persistence.ts

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import {
+	REASONING_TRANSLATION_ENTRY_TYPE,
+	type ReasoningTranslationEntryV1,
+	cloneUsage,
+	isReasoningTranslationEntry,
+} from "./types";
+
+export type ThinkingRunProjection = {
+	runKey: number;
+	sourceMarkdown: string;
+};
+
+export function projectThinkingRuns(message: Pick<AssistantMessage, "content">): ThinkingRunProjection[] {
+	const runs: ThinkingRunProjection[] = [];
+	for (let index = 0; index < message.content.length; index++) {
+		const content = message.content[index];
+		if (content.type !== "thinking") continue;
+
+		const runKey = index;
+		const blocks: string[] = [];
+		for (; index < message.content.length; index++) {
+			const block = message.content[index];
+			if (block.type !== "thinking") break;
+			const thinking = block.thinking.trim();
+			if (thinking) blocks.push(thinking);
+		}
+		index--;
+		if (blocks.length > 0) {
+			runs.push({ runKey, sourceMarkdown: blocks.join("\n\n") });
+		}
+	}
+	return runs;
+}
+
+export function hashThinkingMarkdown(sourceMarkdown: string): string {
+	return createHash("sha256").update(sourceMarkdown, "utf8").digest("hex");
+}
+
+export function createReasoningTranslationEntry(args: {
+	sourceMarkdown: string;
+	displayText: string;
+	targetLanguage: string;
+	translator: { provider: string; model: string };
+	usage?: import("@earendil-works/pi-ai").Usage;
+}): ReasoningTranslationEntryV1 {
+	return {
+		version: 1,
+		sourceHash: hashThinkingMarkdown(args.sourceMarkdown),
+		displayText: args.displayText,
+		targetLanguage: args.targetLanguage,
+		translator: { ...args.translator },
+		usage: cloneUsage(args.usage),
+	};
+}
+
+export function replayReasoningTranslations(
+	entries: readonly SessionEntry[],
+): Map<string, ReasoningTranslationEntryV1> {
+	const translations = new Map<string, ReasoningTranslationEntryV1>();
+	for (const entry of entries) {
+		if (entry.type !== "custom" || entry.customType !== REASONING_TRANSLATION_ENTRY_TYPE) continue;
+		if (!isReasoningTranslationEntry(entry.data)) continue;
+		translations.set(entry.data.sourceHash, {
+			...entry.data,
+			translator: { ...entry.data.translator },
+			usage: cloneUsage(entry.data.usage),
+		});
+	}
+	return translations;
+}

package/src/reasoning-translation/segmenter.ts

@@ -0,0 +1,60 @@
+import { MAX_SEGMENT_LENGTH } from "./types";
+
+export type SegmentationResult = {
+	segments: string[];
+	remainder: string;
+};
+
+function isNaturalBoundaryCharacter(character: string): boolean {
+	return "\n.!?。！？；;".includes(character);
+}
+
+function findLatestNaturalBoundary(source: string, limit: number): number | undefined {
+	const end = Math.min(limit, source.length);
+	for (let index = end - 1; index >= 0; index--) {
+		if (!isNaturalBoundaryCharacter(source[index])) continue;
+		let boundary = index + 1;
+		while (boundary < end && /\s/u.test(source[boundary])) boundary++;
+		return boundary;
+	}
+	return undefined;
+}
+
+function addSegment(segments: string[], candidate: string): void {
+	if (candidate.trim().length > 0) segments.push(candidate);
+}
+
+/**
+ * Extract complete thinking segments without changing their source text. Natural
+ * boundaries are preferred; long unbroken text is cut at the hard UTF-16 limit.
+ */
+export function segmentThinkingSource(source: string, flush = false): SegmentationResult {
+	let remainder = source;
+	const segments: string[] = [];
+
+	while (remainder.length > 0) {
+		const boundary = findLatestNaturalBoundary(remainder, MAX_SEGMENT_LENGTH);
+		if (boundary !== undefined) {
+			addSegment(segments, remainder.slice(0, boundary));
+			remainder = remainder.slice(boundary);
+			continue;
+		}
+		if (remainder.length > MAX_SEGMENT_LENGTH) {
+			addSegment(segments, remainder.slice(0, MAX_SEGMENT_LENGTH));
+			remainder = remainder.slice(MAX_SEGMENT_LENGTH);
+			continue;
+		}
+		break;
+	}
+
+	if (flush && remainder.trim().length > 0) {
+		addSegment(segments, remainder);
+		remainder = "";
+	}
+
+	return { segments, remainder };
+}
+
+export function flushThinkingSource(source: string): SegmentationResult {
+	return segmentThinkingSource(source, true);
+}

package/src/reasoning-translation/state.ts

@@ -0,0 +1,399 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { AssistantMessage, Usage } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { parseModelSpec } from "../runtime";
+import type { ReasoningTranslationConfig } from "../types";
+import {
+	resolveTranslator,
+	translateSegment,
+	type ResolvedTranslator,
+	type TranslateSegmentResult,
+} from "./client";
+import {
+	createReasoningTranslationEntry,
+	hashThinkingMarkdown,
+	projectThinkingRuns,
+	replayReasoningTranslations,
+	type ThinkingRunProjection,
+} from "./persistence";
+import { flushThinkingSource, segmentThinkingSource } from "./segmenter";
+import {
+	IDLE_FLUSH_MS,
+	REASONING_TRANSLATION_ENTRY_TYPE,
+	TRANSLATING_LABEL,
+	type ReasoningTranslationEntryV1,
+} from "./types";
+
+export type ReasoningTranslationStateOptions = {
+	resolveTranslator?: typeof resolveTranslator;
+	translateSegment?: typeof translateSegment;
+	setTimeout?: typeof globalThis.setTimeout;
+	clearTimeout?: typeof globalThis.clearTimeout;
+	onDisplayChanged?: () => void;
+	appendEntry?: (customType: string, data: ReasoningTranslationEntryV1) => void;
+};
+
+type ThinkingRunState = {
+	runKey: number;
+	sourceMarkdown: string;
+	pendingSource: string;
+	displayedText: string;
+	usage?: Usage;
+	idleTimer?: ReturnType<typeof setTimeout>;
+	/** A natural/idle/final flush requested before the translator was ready. */
+	flushRequested: boolean;
+};
+
+type ActiveTranslation = {
+	generation: number;
+	sourceModelKey: string;
+	targetLanguage: string;
+	translator?: ResolvedTranslator;
+	translatorReady: boolean;
+	translatorFailed: boolean;
+	translatorPromise?: Promise<void>;
+	abortController: AbortController;
+	queue: Promise<void>;
+	runs: Map<number, ThinkingRunState>;
+	ctx: ExtensionContext;
+	finalized: boolean;
+};
+
+function isAssistantMessage(message: AgentMessage): message is AssistantMessage {
+	return message.role === "assistant";
+}
+
+function getModelKey(ctx: ExtensionContext): string | undefined {
+	return ctx.model?.provider && ctx.model.id ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+}
+
+function isEligible(ctx: ExtensionContext, config: ReasoningTranslationConfig): boolean {
+	const modelKey = getModelKey(ctx);
+	return (
+		ctx.mode === "tui" &&
+		config.enabled &&
+		modelKey !== undefined &&
+		config.models.includes(modelKey) &&
+		config.model !== undefined &&
+		parseModelSpec(config.model) !== undefined
+	);
+}
+
+function preserveSourceWhitespace(source: string, translated: string): string {
+	const leading = source.match(/^\s*/u)?.[0] ?? "";
+	const trailing = source.match(/\s*$/u)?.[0] ?? "";
+	const core = translated.trim();
+	return `${leading}${core}${trailing}`;
+}
+
+function addUsage(left: Usage | undefined, right: Usage | undefined): Usage | undefined {
+	if (!left) return right;
+	if (!right) return left;
+	return {
+		input: left.input + right.input,
+		output: left.output + right.output,
+		cacheRead: left.cacheRead + right.cacheRead,
+		cacheWrite: left.cacheWrite + right.cacheWrite,
+		...(left.cacheWrite1h !== undefined || right.cacheWrite1h !== undefined
+			? { cacheWrite1h: (left.cacheWrite1h ?? 0) + (right.cacheWrite1h ?? 0) }
+			: {}),
+		...(left.reasoning !== undefined || right.reasoning !== undefined
+			? { reasoning: (left.reasoning ?? 0) + (right.reasoning ?? 0) }
+			: {}),
+		totalTokens: left.totalTokens + right.totalTokens,
+		cost: {
+			input: left.cost.input + right.cost.input,
+			output: left.cost.output + right.cost.output,
+			cacheRead: left.cost.cacheRead + right.cost.cacheRead,
+			cacheWrite: left.cost.cacheWrite + right.cost.cacheWrite,
+			total: left.cost.total + right.cost.total,
+		},
+	};
+}
+
+function findRunForContentIndex(runs: readonly ThinkingRunProjection[], contentIndex: number): ThinkingRunProjection | undefined {
+	let selected: ThinkingRunProjection | undefined;
+	for (const run of runs) {
+		if (run.runKey <= contentIndex) selected = run;
+		else break;
+	}
+	return selected;
+}
+
+/**
+ * Lifecycle-local state for one translation extension instance. It owns no Pi
+ * session data; persisted projections are rebuilt from the active branch.
+ */
+export class ReasoningTranslationState {
+	private readonly options: Required<Pick<ReasoningTranslationStateOptions, "resolveTranslator" | "translateSegment" | "setTimeout" | "clearTimeout">> &
+		Pick<ReasoningTranslationStateOptions, "onDisplayChanged" | "appendEntry">;
+	private generation = 0;
+	private active: ActiveTranslation | undefined;
+	private persisted = new Map<string, ReasoningTranslationEntryV1>();
+	private displayEnabled = false;
+
+	constructor(options: ReasoningTranslationStateOptions = {}) {
+		this.options = {
+			resolveTranslator: options.resolveTranslator ?? resolveTranslator,
+			translateSegment: options.translateSegment ?? translateSegment,
+			setTimeout: options.setTimeout ?? globalThis.setTimeout,
+			clearTimeout: options.clearTimeout ?? globalThis.clearTimeout,
+			onDisplayChanged: options.onDisplayChanged,
+			appendEntry: options.appendEntry,
+		};
+	}
+
+	hydrate(ctx: ExtensionContext, config?: ReasoningTranslationConfig): void {
+		this.persisted = replayReasoningTranslations(ctx.sessionManager.getBranch());
+		this.displayEnabled = config ? isEligible(ctx, config) : false;
+	}
+
+	setDisplayEligibility(ctx: ExtensionContext, config: ReasoningTranslationConfig): void {
+		this.displayEnabled = isEligible(ctx, config);
+	}
+
+	getPersistedDisplay(markdown: string): string | undefined {
+		if (!this.displayEnabled) return undefined;
+		return this.persisted.get(hashThinkingMarkdown(markdown))?.displayText;
+	}
+
+	getActiveDisplay(markdown: string): string | undefined {
+		const active = this.active;
+		if (!active || active.ctx.mode !== "tui") return undefined;
+		for (const run of active.runs.values()) {
+			if (run.sourceMarkdown !== markdown) continue;
+			if (run.displayedText.length > 0) return run.displayedText;
+			if (!active.translatorFailed) return TRANSLATING_LABEL;
+		}
+		return undefined;
+	}
+
+	lookupDisplay(markdown: string): string | undefined {
+		return this.getActiveDisplay(markdown) ?? this.getPersistedDisplay(markdown);
+	}
+
+	beginMessage(message: AgentMessage, ctx: ExtensionContext, config: ReasoningTranslationConfig): void {
+		const eligible = isEligible(ctx, config);
+		this.displayEnabled = eligible;
+		// message_start also fires for toolResult and user messages. They must not
+		// cancel a finished assistant translation before its FIFO queue can settle.
+		if (!isAssistantMessage(message)) return;
+		this.abortActive();
+		if (!eligible) return;
+
+		const sourceModelKey = getModelKey(ctx);
+		if (!sourceModelKey) return;
+		const generation = ++this.generation;
+		const abortController = new AbortController();
+		const active: ActiveTranslation = {
+			generation,
+			sourceModelKey,
+			targetLanguage: config.targetLanguage,
+			translatorReady: false,
+			translatorFailed: false,
+			abortController,
+			queue: Promise.resolve(),
+			runs: new Map(),
+			ctx,
+			finalized: false,
+		};
+		this.active = active;
+
+		if (ctx.signal) {
+			if (ctx.signal.aborted) {
+				this.abortActive();
+				return;
+			}
+			ctx.signal.addEventListener("abort", () => {
+				if (this.active?.generation === generation) this.abortActive();
+			}, { once: true });
+		}
+
+		const resolve = this.options.resolveTranslator(ctx, config.model).then((result) => {
+			if (this.active?.generation !== generation) return;
+			if (!("model" in result) || !("provider" in result)) {
+				active.translatorFailed = true;
+				this.displayEnabled = false;
+				this.abortActive();
+				return;
+			}
+			active.translator = result;
+			active.translatorReady = true;
+			for (const run of active.runs.values()) this.enqueuePending(active, run, run.flushRequested);
+		});
+		active.translatorPromise = resolve.catch(() => {
+			if (this.active?.generation === generation) {
+				active.translatorFailed = true;
+				this.displayEnabled = false;
+				this.abortActive();
+			}
+		});
+	}
+
+	handleMessageUpdate(message: AgentMessage, updateType: string, contentIndex: number): void {
+		const active = this.active;
+		if (!active || !isAssistantMessage(message) || active.ctx.mode !== "tui") return;
+		if (active.ctx.signal?.aborted) {
+			this.abortActive();
+			return;
+		}
+
+		const projections = projectThinkingRuns(message);
+		for (const projection of projections) this.updateRunSource(active, projection);
+		if (updateType === "thinking_end") {
+			const projection = findRunForContentIndex(projections, contentIndex);
+			if (projection) {
+				const run = active.runs.get(projection.runKey);
+				if (run) this.enqueuePending(active, run, true);
+			}
+		}
+	}
+
+	finishMessage(message: AgentMessage): void {
+		if (isAssistantMessage(message) && (message.stopReason === "aborted" || message.stopReason === "error")) {
+			this.abortActive();
+			return;
+		}
+		const active = this.active;
+		if (!active || !isAssistantMessage(message) || active.finalized) return;
+		const projections = projectThinkingRuns(message);
+		for (const projection of projections) this.updateRunSource(active, projection);
+		for (const run of active.runs.values()) this.enqueuePending(active, run, true);
+		active.finalized = true;
+
+		const generation = active.generation;
+		void (active.translatorPromise ?? Promise.resolve())
+			.then(() => active.queue)
+			.then(() => {
+			if (this.active?.generation !== generation || !this.active || !active.translator) return;
+			for (const run of active.runs.values()) {
+				if (!run.sourceMarkdown || !run.displayedText) continue;
+				const entry = createReasoningTranslationEntry({
+					sourceMarkdown: run.sourceMarkdown,
+					displayText: run.displayedText,
+					targetLanguage: active.targetLanguage,
+					translator: { provider: active.translator.model.provider, model: active.translator.model.id },
+					usage: run.usage,
+				});
+				this.persisted.set(entry.sourceHash, entry);
+				try {
+					this.options.appendEntry?.(REASONING_TRANSLATION_ENTRY_TYPE, entry);
+				} catch {
+					// Persistence is additive and must not affect the completed response.
+				}
+			}
+			});
+	}
+
+	abortActive(): void {
+		const active = this.active;
+		if (!active) return;
+		for (const run of active.runs.values()) {
+			if (run.idleTimer !== undefined) this.options.clearTimeout(run.idleTimer);
+		}
+		active.abortController.abort();
+		this.generation++;
+		this.active = undefined;
+	}
+
+	private updateRunSource(active: ActiveTranslation, projection: ThinkingRunProjection): void {
+		let run = active.runs.get(projection.runKey);
+		if (!run) {
+			run = {
+				runKey: projection.runKey,
+				sourceMarkdown: "",
+				pendingSource: "",
+				displayedText: "",
+				flushRequested: false,
+			};
+			active.runs.set(projection.runKey, run);
+		}
+
+		if (projection.sourceMarkdown === run.sourceMarkdown) return;
+		const previous = run.sourceMarkdown;
+		const suffix = projection.sourceMarkdown.startsWith(previous)
+			? projection.sourceMarkdown.slice(previous.length)
+			: projection.sourceMarkdown.slice(commonPrefixLength(previous, projection.sourceMarkdown));
+		run.sourceMarkdown = projection.sourceMarkdown;
+		if (suffix.length > 0) run.pendingSource += suffix;
+		this.scheduleIdleFlush(active, run);
+		if (active.translatorReady) this.enqueuePending(active, run, false);
+	}
+
+	private scheduleIdleFlush(active: ActiveTranslation, run: ThinkingRunState): void {
+		if (run.idleTimer !== undefined) this.options.clearTimeout(run.idleTimer);
+		const generation = active.generation;
+		run.idleTimer = this.options.setTimeout(() => {
+			if (this.active?.generation !== generation) return;
+			this.enqueuePending(active, run, true);
+		}, IDLE_FLUSH_MS);
+	}
+
+	private enqueuePending(active: ActiveTranslation, run: ThinkingRunState, flush: boolean): void {
+		if (flush) run.flushRequested = true;
+		if (!active.translatorReady || !active.translator) return;
+
+		const shouldFlush = run.flushRequested;
+		const segmented = shouldFlush
+			? flushThinkingSource(run.pendingSource)
+			: segmentThinkingSource(run.pendingSource);
+		run.pendingSource = segmented.remainder;
+		if (shouldFlush && run.pendingSource.length === 0) run.flushRequested = false;
+		for (const segment of segmented.segments) {
+			const generation = active.generation;
+			active.queue = active.queue
+				.then(async () => {
+					if (this.active?.generation !== generation || active.abortController.signal.aborted) return;
+					const result = await this.options.translateSegment!({
+						translator: active.translator!,
+						targetLanguage: active.targetLanguage,
+						sourceSegment: segment,
+						signal: active.abortController.signal,
+					});
+					this.publishSegment(active, run, segment, result);
+				})
+				.catch(() => {
+					if (this.active?.generation === generation && !active.abortController.signal.aborted) {
+						this.publishSegment(active, run, segment, { ok: false, reason: "request-failed" });
+					}
+				});
+		}
+		if (shouldFlush && run.idleTimer !== undefined) {
+			this.options.clearTimeout(run.idleTimer);
+			run.idleTimer = undefined;
+		}
+	}
+
+	private publishSegment(
+		active: ActiveTranslation,
+		run: ThinkingRunState,
+		sourceSegment: string,
+		result: TranslateSegmentResult,
+	): void {
+		if (this.active?.generation !== active.generation) return;
+		if (result.ok) {
+			run.displayedText += preserveSourceWhitespace(sourceSegment, result.text);
+			run.usage = addUsage(run.usage, result.usage);
+		} else {
+			// A stale result is filtered by the generation check above. Any failure
+			// that reaches this method is therefore a per-segment fallback, including
+			// a provider-reported abort that did not abort this active session.
+			run.displayedText += sourceSegment;
+		}
+		this.options.onDisplayChanged?.();
+	}
+}
+
+function commonPrefixLength(left: string, right: string): number {
+	const limit = Math.min(left.length, right.length);
+	let index = 0;
+	while (index < limit && left[index] === right[index]) index++;
+	return index;
+}
+
+export function isReasoningTranslationEligible(
+	ctx: ExtensionContext,
+	config: ReasoningTranslationConfig,
+): boolean {
+	return isEligible(ctx, config);
+}

package/src/reasoning-translation/types.ts

@@ -0,0 +1,64 @@
+import type { Usage } from "@earendil-works/pi-ai";
+import { REASONING_TRANSLATION_EXTENSION_ID } from "../types";
+
+export const REASONING_TRANSLATION_ENTRY_TYPE = REASONING_TRANSLATION_EXTENSION_ID;
+export const TRANSLATING_LABEL = "Translating…";
+export const IDLE_FLUSH_MS = 800;
+export const MAX_SEGMENT_LENGTH = 400;
+export const MAX_TRANSLATION_OUTPUT_TOKENS = 2048;
+/** Hard upper bound so an uncooperative provider cannot hold the FIFO forever. */
+export const TRANSLATION_TIMEOUT_MS = 30_000;
+
+export type ReasoningTranslationEntryV1 = {
+	version: 1;
+	sourceHash: string;
+	displayText: string;
+	targetLanguage: string;
+	translator: {
+		provider: string;
+		model: string;
+	};
+	usage?: Usage;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function isFiniteNonNegativeNumber(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function isUsage(value: unknown): value is Usage {
+	if (!isRecord(value) || !isRecord(value.cost)) return false;
+	const cost = value.cost;
+	const numericFields = ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const;
+	if (numericFields.some((field) => !isFiniteNonNegativeNumber(value[field]))) return false;
+	if (value.reasoning !== undefined && !isFiniteNonNegativeNumber(value.reasoning)) return false;
+	if (value.cacheWrite1h !== undefined && !isFiniteNonNegativeNumber(value.cacheWrite1h)) return false;
+	return ["input", "output", "cacheRead", "cacheWrite", "total"].every((field) =>
+		isFiniteNonNegativeNumber(cost[field]),
+	);
+}
+
+export function isReasoningTranslationEntry(value: unknown): value is ReasoningTranslationEntryV1 {
+	if (!isRecord(value) || value.version !== 1) return false;
+	if (typeof value.sourceHash !== "string" || !/^[a-f0-9]{64}$/iu.test(value.sourceHash)) return false;
+	if (!isNonEmptyString(value.displayText)) return false;
+	if (!isNonEmptyString(value.targetLanguage) || !isRecord(value.translator)) return false;
+	if (!isNonEmptyString(value.translator.provider) || !isNonEmptyString(value.translator.model)) return false;
+	return value.usage === undefined || isUsage(value.usage);
+}
+
+export function cloneUsage(usage: Usage | undefined): Usage | undefined {
+	return usage
+		? {
+			...usage,
+			cost: { ...usage.cost },
+		  }
+		: undefined;
+}

package/src/types.ts

@@ -4,6 +4,7 @@ import type { CompactionEntry, CompactionResult, ExtensionContext } from "@earen
 export const TOOLKIT_ID = "pi-openai-toolkit";
 export const COMPACTION_EXTENSION_ID = `${TOOLKIT_ID}:compaction`;
 export const WEB_SEARCH_EXTENSION_ID = `${TOOLKIT_ID}:web-search`;
+export const REASONING_TRANSLATION_EXTENSION_ID = `${TOOLKIT_ID}:reasoning-translation`;
 export const DEFAULT_ARTIFACT_ROOT = "~/.pi/agent/artifacts/pi-openai-toolkit/compaction";
 export const REDACTED_VALUE = "[REDACTED]";
 /**
@@ -71,9 +72,19 @@ export type WebSearchConfig = {
 	models: string[];
 };
 
+export type ReasoningTranslationConfig = {
+	enabled: boolean;
+	/** Exact provider/model keys whose thinking output may be translated. */
+	models: string[];
+	/** Separate provider/model-id used only for translation requests. */
+	model?: string;
+	targetLanguage: string;
+};
+
 export type ToolkitConfig = {
 	compaction: CompactionConfig;
 	webSearch: WebSearchConfig;
+	reasoningTranslation: ReasoningTranslationConfig;
 };
 
 export type LoadedToolkitConfig = {
@@ -345,7 +356,15 @@ export const DEFAULT_WEB_SEARCH_CONFIG: WebSearchConfig = {
 	models: [],
 };
 
+export const DEFAULT_REASONING_TRANSLATION_CONFIG: ReasoningTranslationConfig = {
+	enabled: true,
+	models: [],
+	model: undefined,
+	targetLanguage: "Simplified Chinese",
+};
+
 export const DEFAULT_TOOLKIT_CONFIG: ToolkitConfig = {
 	compaction: DEFAULT_COMPACTION_CONFIG,
 	webSearch: DEFAULT_WEB_SEARCH_CONFIG,
+	reasoningTranslation: DEFAULT_REASONING_TRANSLATION_CONFIG,
 };

package/tsconfig.check.json

@@ -14,6 +14,7 @@
   "include": [
     "extensions/compaction.ts",
     "extensions/web-search.ts",
+    "extensions/reasoning-translation.ts",
     "src/compact-client.ts",
     "src/config.ts",
     "src/debug.ts",
@@ -31,6 +32,12 @@
     "src/web-search/extension.ts",
     "src/web-search/payload.ts",
     "src/web-search/prompt.ts",
-    "src/web-search/types.ts"
+    "src/web-search/types.ts",
+    "src/reasoning-translation/client.ts",
+    "src/reasoning-translation/extension.ts",
+    "src/reasoning-translation/persistence.ts",
+    "src/reasoning-translation/segmenter.ts",
+    "src/reasoning-translation/state.ts",
+    "src/reasoning-translation/types.ts"
   ]
 }