ask-user-question-plus 1.0.0 → 1.0.2

package/README.md

@@ -3,212 +3,200 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://img.shields.io/npm/v/ask-user-question-plus.svg)](https://www.npmjs.com/package/ask-user-question-plus)
 
-一个功能强大的 MCP (Model Context Protocol) 服务器，通过精美的 TUI 风格 Web 界面让 LLM（如 Claude）向用户提问。
+A MCP server (Streamable HTTP) for asking user questions via a web interface, inspired by the Claude Code AskUserQuestion Tool.
 
-![TUI Interface](./assets/screenshot.png)
+> 🌟 Supports Claude Code, Codex, and Gemini CLI!
+
+![Interface Screenshot](./assets/screenshot.png)
+
+<div align="center">
+
+[**English**](#english) | [**中文**](#chinese)
+
+</div>
+
+---
+
+<a id="chinese"></a>
 
 ## ✨ 特性
 
-- **🎨 TUI 风格界面**：浏览器中呈现像素级完美的类终端外观（暗/浅色主题）
-- **⌨️ 全键盘操作**：支持方向键、Tab、Space、Enter 快捷键
-- **📊 丰富交互**：单选、多选、推荐选项、自定义输入（Other）
-- **🔄 实时通信**：基于 WebSocket 的实时消息传递
-- **⏱️ 超时保护**：可配置超时（默认 10 分钟）
-- **📈 可扩展**：支持 1-20 个问题，每个问题选项数量不限
+- **🎨 精美界面**：Claude Code AskUserQuestions 风格样式，支持暗/浅色主题适配
+- **⌨️ 全键盘操作**：支持方向键、Tab、Space、Enter 快捷键，操作流畅
+- **📊 丰富交互**：支持单选、多选、推荐选项标记以及自定义输入（Other）
+- **🔄 实时通信**：基于 WebSocket 的实时消息传递，响应迅速
+- **⏱️ 超时保护**：可配置会话超时时间（默认 10 分钟）
+- **📈 高度可扩展**：支持 1-20 个问题，每个问题选项数量不限
 
-### Claude Code AskUserQuestion Tool vs AskUserQuestionPlus
+## 🚀 部署
 
-| 对比项       | AskUserQuestion (内置) | ask-user-question-plus (MCP) |
-| ------------ | ---------------------- | ---------------------------- |
-| 问题数量限制 | 1-4 个                 | 1-20 个                      |
-| 选项数量限制 | 2-4 个                 | 无限制                       |
+### 启动参数
 
-## 📦 安装
+| 参数               | 说明         | 默认值           | 示例               |
+| :----------------- | :----------- | :--------------- | :----------------- |
+| `--timeout=<毫秒>` | 会话超时时间 | 600000 (10 分钟) | `--timeout=300000` |
+| `--port=<端口>`    | 监听端口     | 3456             | `--port=8080`      |
 
-### 方式 1：直接安装（推荐）
+### 前台运行
 
 ```bash
-npm install -g ask-user-question-plus
+npx ask-user-question-plus
+
+# 自定义端口和超时
+npx ask-user-question-plus -- --port=3456 --timeout=600000
 ```
 
-### 方式 2：从源码构建
+### 后台运行（推荐）
+
+#### 使用 pm2
+
+> 需先安装 pm2: `npm install -g pm2`
 
 ```bash
-git clone https://github.com/JoJoJotarou/AskUserQuestionPlus.git
-cd AskUserQuestionPlus
-npm install
-npm run build
+pm2 start "npx ask-user-question-plus" --name ask-user-question-plus-service
+
+# 带参数启动
+pm2 start "npx ask-user-question-plus -- --port=3456 --timeout=600000" --name ask-user-question-plus-service
+
+# 停止服务
+pm2 stop ask-user-question-plus-service
+
+# Windows
+pm2 start cmd --name ask-user-question-plus-service -- /c npx ask-user-question-plus
 ```
 
-## 🚀 配置
+#### 使用 Docker
 
-将此服务器添加到你的 MCP 客户端配置文件（Claude Desktop 的 `claude_desktop_config.json` 或 Claude Code 配置）。
+```bash
+docker compose up -d
+```
 
-### Claude Desktop 配置
+## ⚙️ 配置
 
-**基础配置：**
+### Claude Code
 
-```json
-{
-  "mcpServers": {
-    "ask-user-question-plus": {
-      "command": "npx",
-      "args": ["ask-user-question-plus"]
-    }
-  }
-}
+```bash
+claude mcp add -s user -t http AskUserQuestionPlus http://localhost:3456/mcp
 ```
 
-**自定义超时（毫秒）：**
+### Codex
 
-```json
-{
-  "mcpServers": {
-    "ask-user-question-plus": {
-      "command": "npx",
-      "args": ["ask-user-question-plus", "--timeout=300000"]
-    }
-  }
-}
+在 `~/.codex/config.toml` 中添加配置：
+
+```toml
+experimental_use_rmcp_client = true
+
+[mcp_servers.AskUserQuestionPlus]
+url = "http://localhost:3456/mcp/"
 ```
 
-### 启动参数
+或者使用命令行：
 
-| 参数               | 说明           | 默认值           | 示例               |
-| ------------------ | -------------- | ---------------- | ------------------ |
-| `--timeout=<毫秒>` | 会话超时时间   | 600000 (10 分钟) | `--timeout=300000` |
-| `--port=<端口>`    | WebSocket 端口 | 3456             | `--port=8080`      |
+在 `~/.codex/config.toml` 中添加配置：
 
-## 📖 使用方法
+```toml
+experimental_use_rmcp_client = true
+```
+
+```bash
+codex mcp add AskUserQuestionsPlus --url http://localhost:3456/mcp/
+```
+
+### Gemini CLI
+
+```bash
+gemini mcp add AskUserQuestionPlus http://localhost:3456/mcp -s user --transport http
+```
+
+> **⚠️ 注意**：如果遇到 `[Error: Unrecognized key(s) in object: 'type']` 错误 (参见 [issue #15449](https://github.com/google-gemini/gemini-cli/issues/15449))：
+>
+> - 请在 `~/.gemini/settings.json` 中删除 `type` 字段
+> - 或等待 gemini cli `v0.23.0` 发布
+
+## 🕹️ 使用方法
 
 ### 基本流程
 
-1. 启动与 Claude 的对话
-2. 让 Claude 使用工具：`使用 ask_user_question_plus 工具问我 3 个问题`
-3. 浏览器自动打开问卷界面
-4. 使用键盘（方向键、Space、Enter）回答问题
-5. 提交后浏览器标签页自动关闭
+1.  启动与 Claude Code/Codex/Gemini 的对话。
+2.  模型调用工具：例如 `使用 ask_user_question_plus 工具问我 3 个问题`。
+3.  浏览器自动打开问卷界面。
+4.  使用键盘（方向键、Space、Enter）或鼠标回答问题。
+5.  提交后浏览器标签页自动关闭，结果返回给模型。
 
 ### 键盘快捷键
 
-| 快捷键             | 功能                          |
-| ------------------ | ----------------------------- |
-| `↑` `↓`            | 在选项之间移动 / 滚动问题内容 |
-| `←` `→` / `Tab`    | 在问题标签页之间切换          |
-| `Space`            | 选中/取消选中当前选项         |
-| `Cmd/Ctrl + Enter` | 进入审查模式 / 提交答案       |
+| 快捷键             | 功能                      |
+| :----------------- | :------------------------ |
+| `↑` `↓`            | 在选项之间移动 / 滚动页面 |
+| `←` `→` / `Tab`    | 在不同问题标签页之间切换  |
+| `Space` / `Enter`  | 选中/取消选中当前选项     |
+| `Cmd/Ctrl + Enter` | 进入提交 Tab / 提交答案   |
 
-## 🔧 工具 API
+## 🔧 工具定义 (Tools)
 
-### MCP 工具：`ask_user_question_plus`
+### `ask_user_question_plus`
 
-**输入 Schema：**
+**输入 Schema (Input):**
 
 ```typescript
 {
   questions: [
     {
       id: string;              // 问题唯一标识
-      header: string;          // 标签标题（≤12 字符推荐）
-      text: string;            // 问题文本
-      type: "single" | "multiple";  // 单选或多选
+      header: string;          // 标签标题（推荐 ≤12 字符）
+      text: string;            // 问题正文
+      type: "single" | "multiple";  // 问题类型：单选或多选
       options: [
         {
           value: string;        // 选项值
-          label: string;        // 选项标签
+          label: string;        // 选项显示文本
           description?: string; // 选项描述（可选）
-          recommended?: boolean;// 是否推荐（可选）
+          recommended?: boolean;// 是否标记为推荐（可选）
         }
       ]
     }
-  ]  // 最少 1 个，最多 20 个问题
+  ]  // 限制：1-20 个问题
 }
 ```
 
-**输出 Schema：**
+**输出 Schema (Output):**
 
 ```typescript
 {
-  [questionId: string]: string | string[]  // 单选为字符串，多选为数组
+  "answers": {
+    "questionId1": {"value" : "", "other":""},
+    "questionId2": {"value" : "", "other":""},
+  }
 }
 ```
 
-> **💡 提示**：前端会自动为每个问题添加 "Other (自定义输入)" 选项，无需手动指定。
+> **💡 提示**：前端界面会自动为每个问题追加 "Other (自定义输入)" 选项。
 
-### 使用示例
+## 🛠️ 开发指南
 
-**单选问题：**
+### 克隆项目
 
-```json
-{
-  "questions": [
-    {
-      "id": "framework",
-      "header": "Framework",
-      "text": "选择你的前端框架：",
-      "type": "single",
-      "options": [
-        {
-          "value": "react",
-          "label": "React",
-          "description": "用于构建用户界面的 JavaScript 库",
-          "recommended": true
-        },
-        {
-          "value": "vue",
-          "label": "Vue",
-          "description": "渐进式 JavaScript 框架"
-        }
-      ]
-    }
-  ]
-}
+```bash
+git clone https://github.com/JoJoJotarou/AskUserQuestionPlus.git && cd AskUserQuestionPlus
 ```
 
-**多选问题：**
+### 安装依赖
 
-```json
-{
-  "questions": [
-    {
-      "id": "features",
-      "header": "Features",
-      "text": "你需要哪些功能？（可多选）",
-      "type": "multiple",
-      "options": [
-        {
-          "value": "auth",
-          "label": "用户认证",
-          "description": "登录、注册、密码重置"
-        },
-        {
-          "value": "api",
-          "label": "REST API",
-          "description": "RESTful API 端点"
-        },
-        {
-          "value": "db",
-          "label": "数据库",
-          "description": "PostgreSQL/MySQL 支持"
-        }
-      ]
-    }
-  ]
-}
+```bash
+npm install
 ```
 
-## 🛠️ 开发
-
-### 运行开发模式
+### 开发模式
 
 ```bash
 npm run dev
 ```
 
-### 构建项目
+### 构建
 
 ```bash
 npm run build
+# npm start
 ```
 
 ### 目录结构
@@ -217,48 +205,220 @@ npm run build
 ask-user-question-plus/
 ├── src/
 │   ├── index.ts           # 主入口文件
-│   ├── ws-service.ts      # WebSocket 服务
-│   └── mcp-server.ts      # MCP 服务器逻辑
+│   ├── ws-service.ts      # WebSocket 服务逻辑
+│   └── mcp-server.ts      # MCP 服务器定义
 ├── public/
-│   └── index.html         # TUI 前端界面
-├── dist/                  # 编译输出目录
-└── package.json           # 项目配置
+│   └── index.html         # 前端 Web 界面
+├── dist/                  # 编译输出
+└── package.json
 ```
 
-### 技术栈
+## 🤝 贡献
+
+欢迎提交 [Issues](https://github.com/JoJoJotarou/AskUserQuestionPlus/issues) 或 Pull Requests 来改进这个项目。
 
-- **后端**：Node.js 20+, TypeScript, Express, ws, @modelcontextprotocol/sdk, Zod
-- **前端**：原生 HTML/CSS/JavaScript（单文件 1184 行）
+## 📄 许可证
+
+[MIT License](LICENSE)
 
-## 🐳 Docker 部署
+## 🔗 相关链接
+
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Codex Support for streamable HTTP MCP](https://github.com/openai/codex/pull/4317)
+
+---
+
+<a id="english"></a>
+
+## ✨ Features
+
+- **🎨 Beautiful Interface**: Replicates the Claude Code AskUserQuestions style with support for Dark/Light themes.
+- **⌨️ Full Keyboard Control**: Seamless navigation using Arrow keys, Tab, Space, and Enter.
+- **📊 Rich Interactions**: Supports single choice, multiple choice, recommended options, and custom input ("Other").
+- **🔄 Real-time Communication**: WebSocket-based messaging for instant feedback.
+- **⏱️ Timeout Protection**: Configurable session timeout (Default: 10 minutes).
+- **📈 Scalable**: Supports 1 to 20 questions with unlimited options per question.
+
+## 🚀 Deployment
+
+### Startup Parameters
+
+| Argument         | Description                     | Default          | Example            |
+| :--------------- | :------------------------------ | :--------------- | :----------------- |
+| `--timeout=<ms>` | Session timeout in milliseconds | 600000 (10 mins) | `--timeout=300000` |
+| `--port=<port>`  | Server port                     | 3456             | `--port=8080`      |
+
+### Foreground
 
 ```bash
-# 使用 Docker Compose
-docker-compose up -d
+npx ask-user-question-plus
 
-# 查看日志
-docker-compose logs -f
+# Custom port and timeout
+npx ask-user-question-plus -- --port=3456 --timeout=600000
+```
 
-# 停止服务
-docker-compose down
+### Background (Recommended)
+
+#### Using pm2
+
+> Install pm2 first: `npm install -g pm2`
+
+```bash
+pm2 start "npx ask-user-question-plus" --name ask-user-question-plus-service
+
+# With arguments
+pm2 start "npx ask-user-question-plus -- --port=3456 --timeout=600000" --name ask-user-question-plus-service
+
+# Stop service
+pm2 stop ask-user-question-plus-service
+
+# Windows
+pm2 start cmd --name ask-user-question-plus-service -- /c npx ask-user-question-plu
 ```
 
-## 🤝 贡献
+#### Using Docker
 
-欢迎贡献！请提交 [Issues](https://github.com/JoJoJotarou/AskUserQuestionPlus/issues) 或 Pull Requests。
+```bash
+docker compose up -d
+```
 
-## 📄 许可证
+## ⚙️ Configuration
 
-[MIT License](LICENSE)
+### Claude Code
 
-## 🔗 相关链接
+```bash
+claude mcp add -s user -t http AskUserQuestionPlus http://localhost:3456/mcp
+```
 
-- [GitHub 仓库](https://github.com/JoJoJotarou/AskUserQuestionPlus)
-- [npm 包](https://www.npmjs.com/package/ask-user-question-plus)
-- [问题反馈](https://github.com/JoJoJotarou/AskUserQuestionPlus/issues)
-- [Model Context Protocol](https://modelcontextprotocol.io/)
-- [Claude Code](https://github.com/anthropics/claude-code)
+### Codex
 
----
+Add to `~/.codex/config.toml`:
+
+```toml
+experimental_use_rmcp_client = true
+
+[mcp_servers.AskUserQuestionPlus]
+url = "http://localhost:3456/mcp/"
+```
+
+Or via CLI:
+
+Add to `~/.codex/config.toml` first:
+
+```toml
+experimental_use_rmcp_client = true
+```
+
+```bash
+codex mcp add AskUserQuestionsPlus --url http://localhost:3456/mcp/
+```
+
+### Gemini CLI
+
+```bash
+gemini mcp add AskUserQuestionPlus http://localhost:3456/mcp -s user --transport http
+```
+
+> **⚠️ Note**: If you encounter `[Error: Unrecognized key(s) in object: 'type']` ([Issue #15449](https://github.com/google-gemini/gemini-cli/issues/15449)):
+>
+> - Remove the `type` field in `~/.gemini/settings.json`.
+> - Or wait for gemini cli `v0.23.0`.
+
+## 🕹️ Usage
+
+### Basic Workflow
+
+1.  Start a conversation with Claude, Codex, or Gemini.
+2.  Ask the model to use the tool: e.g., "Use ask_user_question_plus to ask me 3 questions."
+3.  A browser tab will automatically open with the questionnaire.
+4.  Answer using your keyboard (Arrows, Space, Enter) or mouse.
+5.  Upon submission, the tab closes, and answers are sent back to the model.
+
+### Keyboard Shortcuts
+
+| Shortcut           | Function                      |
+| :----------------- | :---------------------------- |
+| `↑` `↓`            | Move between options / Scroll |
+| `←` `→` / `Tab`    | Switch between question tabs  |
+| `Space` / `Enter`  | Select/Deselect option        |
+| `Cmd/Ctrl + Enter` | Submit Tab / Submit answers   |
+
+## 🔧 Tools Definition
+
+### `ask_user_question_plus`
+
+**Input Schema:**
+
+```typescript
+{
+  questions: [
+    {
+      id: string;              // Unique identifier
+      header: string;          // Tab header (Rec. ≤12 chars)
+      text: string;            // Question text
+      type: "single" | "multiple";  // Question type
+      options: [
+        {
+          value: string;        // Option value
+          label: string;        // Option label
+          description?: string; // Option description (optional)
+          recommended?: boolean;// Recommended flag (optional)
+        }
+      ]
+    }
+  ]  // Limit: 1-20 questions
+}
+```
+
+**Output Schema:**
+
+```json
+{
+  "answers": {
+    "questionId1": { "value": "", "other": "" },
+    "questionId2": { "value": "", "other": "" }
+  }
+}
+```
+
+> **💡 Tip**: The "Other" (custom input) option is automatically added by the frontend.
+
+## 🛠️ Development
+
+### Clone
+
+```bash
+git clone https://github.com/JoJoJotarou/AskUserQuestionPlus.git && cd AskUserQuestionPlus
+```
+
+### Install Dependencies
 
-**注意**：此工具需要浏览器支持，确保系统可以自动打开默认浏览器。
+```bash
+npm install
+```
+
+### Run Dev Mode
+
+```bash
+npm run dev
+```
+
+### Build
+
+```bash
+npm run build
+# npm start
+```
+
+## 🤝 Contribution
+
+Contributions are welcome! Please submit [Issues](https://github.com/JoJoJotarou/AskUserQuestionPlus/issues) or Pull Requests.
+
+## 📄 License
+
+[MIT License](LICENSE)
+
+## 🔗 Related Links
+
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Codex Support for streamable HTTP MCP](https://github.com/openai/codex/pull/4317)

package/dist/mcp-server.js

@@ -22,37 +22,37 @@ export class MCPServerService {
     }
     registerTools(server) {
         server.registerTool("ask_user_question_plus", {
-            description: "一个基于 MCP 的用户交互工具，用于向用户提出结构化问题并收集反馈。该工具支持单选、多选类型的问题，允许标记推荐选项，并支持任意数量的问题与答案选项。前端会自动为每个问题添加 'Other'（自定义输入）选项，适用于复杂配置与决策流程。",
+            description: "An MCP-based user interaction tool for asking structured questions and collecting feedback. It supports single-choice and multiple-choice questions, marking recommended options, and flexible numbers of questions and options. An 'Other' (custom input) option is automatically added to each question, making it suitable for complex configuration and decision-making workflows.",
             inputSchema: {
                 questions: z
                     .array(z.object({
-                    id: z.string().describe("问题唯一标识"),
+                    id: z.string().describe("Unique identifier for the question"),
                     header: z
                         .string()
                         .max(12)
-                        .describe("问题标题（最多 12 个字符）"),
-                    text: z.string().describe("问题文本"),
+                        .describe("Short header for the question tab (max 12 chars)"),
+                    text: z.string().describe("Main text of the question"),
                     type: z
                         .enum(["single", "multiple"])
-                        .describe("问题类型：single（单选）或 multiple（多选）"),
+                        .describe("Question type: 'single' or 'multiple'"),
                     options: z
                         .array(z.object({
-                        value: z.string().describe("选项值"),
-                        label: z.string().describe("选项标签"),
+                        value: z.string().describe("Technical value of the option"),
+                        label: z.string().describe("Display label for the option"),
                         description: z
                             .string()
                             .optional()
-                            .describe("选项描述（可选）"),
+                            .describe("Additional description for the option"),
                         recommended: z
                             .boolean()
                             .optional()
-                            .describe("是否为推荐选项（可选）"),
+                            .describe("Whether this is a recommended option"),
                     }))
-                        .describe("选项列表（不限数量）。注意：前端会自动添加 'Other'（自定义输入）选项，用户可自定义输入。"),
+                        .describe("List of options. Note: An 'Other' option is automatically added for custom user input."),
                 }))
                     .min(1)
                     .max(20)
-                    .describe("问题列表（最多可支持 20 个问题）"),
+                    .describe("List of questions (up to 20 items)"),
             },
         }, async ({ questions }) => {
             console.error("[MCP] Tool invoked: ask_user_question_plus");

package/dist/ws-service.js

@@ -39,6 +39,11 @@ export class WebSocketService {
             clearTimeout(session.timeout);
             session.timeout = null;
         }
+        // Send session meta first so the client can start countdown when it receives NEW_QUESTION.
+        this.sendMessage(ws, {
+            type: "SESSION_META",
+            payload: { timeoutMs: this.sessionTimeoutMs },
+        });
         // Send questions to client
         this.sendMessage(ws, {
             type: "NEW_QUESTION",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ask-user-question-plus",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A TUI-style MCP server for asking user questions via a web interface.",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,7 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
+    "test": "echo 'No tests yet' && exit 0",
     "prepublishOnly": "npm run build"
   },
   "keywords": [

package/public/index.html

@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="zh-CN">
+<html lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
@@ -545,7 +545,7 @@
 
           <!-- GitHub Star -->
           <a
-            href="https://github.com/changjunjie/ask-user-question-plus"
+            href="https://github.com/JoJoJotarou/AskUserQuestionPlus"
             target="_blank"
             class="icon-btn"
             title="Star on GitHub"
@@ -575,10 +575,10 @@
       <div class="footer">
         <div class="key-hints">
           <div class="key-hint-item">
-            <span class="key-tag">↑↓</span> 选项/滚动
+            <span class="key-tag">↑↓</span> Select/Scroll
           </div>
           <div class="key-hint-item">
-            <span class="key-tag">← →/Tab</span> 切换问题
+            <span class="key-tag">← →/Tab</span> Switch
           </div>
           <div class="key-hint-item">
             <span class="key-tag">Enter/Space</span>
@@ -586,7 +586,7 @@
           </div>
         </div>
         <button class="submit-btn" id="submit-all" disabled>
-          Go Submit
+          Review & Submit
           <span class="submit-shortcut" id="submit-shortcut-text">⌘+Enter</span>
         </button>
       </div>
@@ -601,11 +601,57 @@
       let activeReviewIndex = 0;
       let shouldFocusOther = false;
       let ws = null;
+      let sessionTimeoutMs = null;
+      let countdownInterval = null;
+      let countdownEndsAt = null;
+      let hasReceivedQuestions = false;
       let sessionId =
         new URLSearchParams(window.location.search).get("sessionId") ||
         "default";
       const isMac = /Mac|iPod|iPhone|iPad/.test(navigator.platform);
 
+      function formatMmSs(ms) {
+        const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+        const minutes = String(Math.floor(totalSeconds / 60)).padStart(2, "0");
+        const seconds = String(totalSeconds % 60).padStart(2, "0");
+        return `${minutes}:${seconds}`;
+      }
+
+      function setSessionInfo(statusText) {
+        document.getElementById("session-info").textContent = statusText;
+      }
+
+      function setSessionInfoConnected() {
+        const base = `Session: ${sessionId} (Connected)`;
+        if (countdownEndsAt) {
+          const remaining = countdownEndsAt - Date.now();
+          setSessionInfo(`${base}  | Timeout in ${formatMmSs(remaining)}`);
+        } else {
+          setSessionInfo(base);
+        }
+      }
+
+      function stopCountdown() {
+        if (countdownInterval) {
+          clearInterval(countdownInterval);
+          countdownInterval = null;
+        }
+        countdownEndsAt = null;
+      }
+
+      function startCountdown(timeoutMs) {
+        stopCountdown();
+        countdownEndsAt = Date.now() + timeoutMs;
+
+        // Tick immediately to avoid showing stale text for up to 1s.
+        setSessionInfoConnected();
+        countdownInterval = setInterval(() => {
+          const remaining = countdownEndsAt - Date.now();
+          setSessionInfoConnected();
+          if (remaining <= 0) stopCountdown();
+        }, 1000);
+      }
+
       // --- WebSocket Logic ---
       function connectWS() {
         // Robust WS URL construction
@@ -628,9 +674,7 @@
 
         ws.onopen = () => {
           console.error("WS Open");
-          document.getElementById(
-            "session-info"
-          ).textContent = `Session: ${sessionId} (Connected)`;
+          setSessionInfoConnected();
           document.getElementById("session-info").style.color =
             "var(--green-color)";
           ws.send(JSON.stringify({ type: "GET_STATE" }));
@@ -649,6 +693,19 @@
           try {
             const message = JSON.parse(event.data);
 
+            if (message.type === "SESSION_META" && message.payload) {
+              sessionTimeoutMs =
+                typeof message.payload.timeoutMs === "number"
+                  ? message.payload.timeoutMs
+                  : null;
+
+              // For B: start countdown when we have received the questions.
+              if (hasReceivedQuestions && sessionTimeoutMs) {
+                startCountdown(sessionTimeoutMs);
+              }
+              return;
+            }
+
             if (
               message.type === "SYNC_STATE" ||
               message.type === "NEW_QUESTION"
@@ -660,6 +717,8 @@
 
               if (questions && questions.length > 0) {
                 QUESTIONS_DATA = questions;
+                hasReceivedQuestions = true;
+                if (sessionTimeoutMs) startCountdown(sessionTimeoutMs);
                 initAnswers();
                 activeQuestionIndex = 0;
                 activeOptionIndex = 0;
@@ -675,6 +734,7 @@
         };
 
         ws.onclose = () => {
+          stopCountdown();
           document.getElementById(
             "session-info"
           ).textContent = `Disconnected. Reconnecting...`;
@@ -799,7 +859,7 @@
                                 ${opt.label}
                                 ${
                                   opt.recommended
-                                    ? '<span class="recommended-tag">（推荐）</span>'
+                                    ? '<span class="recommended-tag">(Recommended)</span>'
                                     : ""
                                 }
                             </div>
@@ -833,7 +893,7 @@
                     <div class="question-header">
                         <span class="q-text">${q.text}${
           q.type === "multiple"
-            ? ' <span style="color:var(--dim-color); font-size:0.8em">（可多选）</span>'
+            ? ' <span style="color:var(--dim-color); font-size:0.8em">(Multi-select)</span>'
             : ""
         }</span>
                     </div>
@@ -875,7 +935,7 @@
 
           if (q.type === "single") {
             if (!ans.value) {
-              error = "未选择答案";
+              error = "No answer selected";
             } else {
               const opt = [
                 ...q.options,
@@ -885,7 +945,7 @@
                 displayValue = opt.label;
                 if (opt.isOther) {
                   if (!ans.otherText.trim()) {
-                    error = "请填写自定义内容";
+                    error = "Please provide custom input";
                     displayValue += ": [Empty]";
                   } else {
                     displayValue += `: ${ans.otherText}`;
@@ -895,7 +955,7 @@
             }
           } else {
             if (!ans.values || ans.values.length === 0) {
-              error = "请至少选择一项";
+              error = "Please select at least one option";
             } else {
               displayValue = ans.values
                 .map((v) => {
@@ -907,7 +967,7 @@
                   let label = opt.label;
                   if (opt.isOther) {
                     if (!ans.otherText.trim()) {
-                      error = "请填写自定义内容";
+                      error = "Please provide custom input";
                       label += ": [Empty]";
                     } else {
                       label += `: ${ans.otherText}`;
@@ -939,7 +999,7 @@
         container.innerHTML = `
                 <div class="question-block">
                     <div class="question-header">
-                        <span class="q-text">请检查您的回答，确认无误后提交！</span>
+                        <span class="q-text">Please review your answers before submitting!</span>
                     </div>
                     ${summaryHtml}
                 </div>
@@ -961,13 +1021,13 @@
         const shortcutText = isMac ? "⌘+Enter" : "Ctrl+Enter";
 
         if (isReview) {
-          submitBtn.innerHTML = `Submt Answers <span class="submit-shortcut" id="submit-shortcut-text">${shortcutText}</span>`;
+          submitBtn.innerHTML = `Submit Answers <span class="submit-shortcut" id="submit-shortcut-text">${shortcutText}</span>`;
           submitBtn.disabled = !isValid;
-          if (spaceHint) spaceHint.textContent = "跳转";
+          if (spaceHint) spaceHint.textContent = "Jump";
         } else {
-          submitBtn.innerHTML = `Go Submit <span class="submit-shortcut" id="submit-shortcut-text">${shortcutText}</span>`;
+          submitBtn.innerHTML = `Review & Submit <span class="submit-shortcut" id="submit-shortcut-text">${shortcutText}</span>`;
           submitBtn.disabled = QUESTIONS_DATA.length === 0;
-          if (spaceHint) spaceHint.textContent = "选择";
+          if (spaceHint) spaceHint.textContent = "Select";
         }
       }
 
@@ -1091,7 +1151,7 @@
           submitBtn.disabled = true;
 
           setTimeout(() => {
-            alert("提交成功！即将关闭...");
+            alert("Submitted successfully! Closing...");
             submitBtn.textContent = "DONE";
             window.close();
             document.body.innerHTML =