auq-mcp-server 2.6.3 → 2.7.0

package/README.md

@@ -212,6 +212,38 @@ Whenever you need clarification on what you are working on, never guess, and cal
 
 When the AI asks questions, you'll see them appear in the AUQ TUI. Answer them **at your convenience**.
 
+### Renderer Selection
+
+AUQ supports two terminal rendering engines:
+
+| Renderer          | Description                                         | Status              |
+| ----------------- | --------------------------------------------------- | ------------------- |
+| **ink** (default) | React-based terminal renderer                       | Stable              |
+| **OpenTUI**       | Native Zig-based renderer with improved performance | Opt-in/Experimental |
+
+**To use OpenTUI**, set one of the following (in priority order):
+
+1. **Environment variable** (highest priority):
+
+   ```bash
+   AUQ_RENDERER=opentui auq
+   ```
+
+2. **Config file** (`.auqrc.json`):
+
+   ```json
+   {
+     "renderer": "opentui"
+   }
+   ```
+
+3. **CLI command**:
+   ```bash
+   auq config set renderer opentui
+   ```
+
+> **Note:** OpenTUI is currently opt-in and experimental. It provides native CJK character support, built-in markdown rendering with syntax highlighting, and mouse support. The environment variable overrides any config setting.
+
 ### Markdown rendering in question prompts
 
 Question prompts now support **Markdown formatting** in the `prompt` text.
@@ -240,6 +272,15 @@ It is recommended to **disable** the built-in questioning tool in your harness (
 | `Ctrl+R` | Quick Submit  | Auto-select recommended options for all questions and go to review |
 | `Esc`    | Reject        | Reject the whole question set and optionally explain why to the AI |
 | `Ctrl+T` | Theme         | Cycle through available color themes                               |
+| `[`/`]`  | Sessions      | Switch to previous/next session (OpenTUI: also click session dots) |
+
+**Mouse Support (OpenTUI renderer only):**
+
+| Action            | Description                                     |
+| ----------------- | ----------------------------------------------- |
+| Click option      | Select/toggle option                            |
+| Scroll            | Scroll through session picker or update overlay |
+| Click session dot | Switch to that session                          |
 
 <details>
 <summary><strong>More Commands (advanced)</strong></summary>
@@ -372,10 +413,21 @@ Update checks are automatically disabled in CI environments (`CI=true`).
 
 The `auq update` command always works regardless of these settings.
 
-### 🎨 Themes
+### Theme System
 
 AUQ supports **16 built-in color themes** with automatic persistence. Press `Ctrl+T` to cycle through themes.
 
+#### Theme Differences by Renderer
+
+| Feature          | ink                | OpenTUI                                   |
+| ---------------- | ------------------ | ----------------------------------------- |
+| Header text      | Gradient animation | Solid accent color                        |
+| Toast animations | `setTimeout` based | `useTimeline` based                       |
+| Markdown syntax  | Basic highlighting | Tree-sitter powered                       |
+| Mouse support    | No                 | Yes (click options, scroll, session dots) |
+
+> Both renderers support all 16 built-in themes and custom themes. Colors are consistent; only implementation details differ.
+
 <details>
 <summary><strong>Built-in Themes</strong></summary>
 
@@ -547,12 +599,13 @@ _Settings from local config override global config, which overrides defaults._
 
 ```json
 {
+  "renderer": "ink",
   "maxOptions": 5,
   "maxQuestions": 5,
   "recommendedOptions": 4,
   "recommendedQuestions": 4,
   "sessionTimeout": 0,
-  "retentionPeriod": 604800000, // 7 days
+  "retentionPeriod": 604800000,
   "language": "auto",
   "theme": "system",
   "autoSelectRecommended": true,
@@ -569,6 +622,7 @@ _Settings from local config override global config, which overrides defaults._
 
 | Setting                 | Type    | Default   | Range/Values                    | Description                                           |
 | ----------------------- | ------- | --------- | ------------------------------- | ----------------------------------------------------- |
+| `renderer`              | string  | "ink"     | "ink", "opentui"                | Terminal rendering engine (ink or OpenTUI)            |
 | `maxOptions`            | number  | 5         | 2-10                            | Maximum options per question                          |
 | `maxQuestions`          | number  | 5         | 1-10                            | Maximum questions per session                         |
 | `recommendedOptions`    | number  | 4         | 1-10                            | Suggested number of options (for AI guidance)         |

package/dist/bin/auq.js

@@ -21,10 +21,19 @@ Commands:
   sessions <sub> [flags] List/dismiss sessions
   config <sub> [flags]   Get/set configuration
   update                 Check for and install updates
+  fetch-answers [flags]  Fetch answers for non-blocking sessions
+  history [sub] [flags]  Browse session history
+
+Ask:
+  auq ask '<json>'
+  auq ask -                              (read JSON from stdin)
+  Format: {"questions":[{"prompt":"...","title":"...","options":[{"label":"..."}]}]}
 
 Answer:
-  auq answer <id> --answers '<json>'    Submit answers
-  auq answer <id> --reject [--reason]   Reject session
+  auq answer <id> --answers '<json>'         Submit answers
+  auq answer <id> --reject [--reason "text"]  Reject session
+  Format: --answers '{"0":{"selectedOption":"Label"}}'
+          Keys = question indices (0,1,2…); values: selectedOption, selectedOptions[], customText
   Flags: --force  --json
 
 Sessions:
@@ -32,9 +41,19 @@ Sessions:
   auq sessions show <id> [--json]
   auq sessions dismiss <id> [--force] [--json]
 
+Fetch Answers:
+  auq fetch-answers [session-id] [--blocking] [--json]
+  auq fetch-answers --unread [--json]
+
+History:
+  auq history [--all] [--json] [--limit N] [--unread] [--search TEXT]
+  auq history show <id> [--json]
+
 Config:
   auq config get [key] [--json]
   auq config set <key> <value> [--global] [--json]
+  Keys: maxOptions (2-10)  maxQuestions (1-10)  sessionTimeout (ms)
+        theme  language  renderer (ink|opentui)  staleAction (warn|remove|archive)
 
 Options:
   -h, --help      Show this help
@@ -46,7 +65,7 @@ Keys (TUI):
   [/] sessions  1-9 jump  Ctrl+S picker  Ctrl+T theme
 
 Config: ./.auqrc.json (local) > ~/.config/auq/.auqrc.json (global)
-Env:    AUQ_SESSION_DIR  XDG_CONFIG_HOME`);
+Env:    AUQ_SESSION_DIR  XDG_CONFIG_HOME  AUQ_RENDERER`);
     process.exit(0);
 }
 // Display version
@@ -214,6 +233,20 @@ if (command === "config") {
     await updateNotification;
     process.exit(0);
 }
+// Handle 'fetch-answers' command
+if (command === "fetch-answers") {
+    const { runFetchAnswersCommand } = await import("../src/cli/commands/fetch-answers.js");
+    await runFetchAnswersCommand(args.slice(1));
+    await updateNotification;
+    process.exit(0);
+}
+// Handle 'history' command
+if (command === "history") {
+    const { runHistoryCommand } = await import("../src/cli/commands/history.js");
+    await runHistoryCommand(args.slice(1));
+    await updateNotification;
+    process.exit(0);
+}
 // Default: Start TUI
 // Important: Lazy-load Ink/React so non-interactive commands (ask/server) don't pull them in.
 // Also force production mode before importing React/Ink to avoid perf_hooks measure accumulation warnings.

package/dist/bin/tui-app.js

@@ -1,6 +1,7 @@
 import { Box, render, Text, useInput } from "ink";
 import { promises as fs } from "fs";
 import React, { useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { DEFAULT_CONFIG } from "../src/config/defaults.js";
 import { ensureDirectoryExists, getSessionDirectory, } from "../src/session/utils.js";
 import { Header } from "../src/tui/components/Header.js";
 import { SessionDots } from "../src/tui/components/SessionDots.js";
@@ -11,10 +12,10 @@ import { Toast } from "../src/tui/components/Toast.js";
 import { WaitingScreen } from "../src/tui/components/WaitingScreen.js";
 import { createNotificationBatcher, showProgress, clearProgress, calculateProgress, checkLinuxDependencies, } from "../src/tui/notifications/index.js";
 import { createTUIWatcher } from "../src/tui/session-watcher.js";
-import { isSessionStale, isSessionAbandoned, formatStaleToastMessage, } from "../src/tui/utils/staleDetection.js";
+import { isSessionStale, isSessionAbandoned, formatStaleToastMessage, } from "../src/tui/shared/utils/staleDetection.js";
 import { ThemeProvider } from "../src/tui/ThemeProvider.js";
 import { ConfigProvider } from "../src/tui/ConfigContext.js";
-import { getAdjustedIndexAfterRemoval, getDirectJumpIndex, getNextSessionIndex, getPrevSessionIndex, } from "../src/tui/utils/sessionSwitching.js";
+import { getAdjustedIndexAfterRemoval, getDirectJumpIndex, getNextSessionIndex, getPrevSessionIndex, } from "../src/tui/shared/utils/sessionSwitching.js";
 import { UpdateChecker, fetchChangelog, installUpdate, detectPackageManager, readCache, writeCache, } from "../src/update/index.js";
 import { UpdateOverlay } from "../src/tui/components/UpdateOverlay.js";
 import { KEYS } from "../src/tui/constants/keybindings.js";
@@ -37,7 +38,7 @@ const App = ({ config }) => {
     const [installError, setInstallError] = useState(null);
     const [changelogContent, setChangelogContent] = useState(null);
     const [updateDismissed, setUpdateDismissed] = useState(false);
-    const [showAgentHint, setShowAgentHint] = useState(true);
+    const [isCheckingUpdate, setIsCheckingUpdate] = useState(false);
     // Get session directory for logging
     const sessionDir = getSessionDirectory();
     // Notification configuration from config
@@ -55,10 +56,6 @@ const App = ({ config }) => {
         }, 3000);
         return () => clearTimeout(timer);
     }, []);
-    // Show agent hint for exactly 1 render tick, then hide
-    useEffect(() => {
-        setShowAgentHint(false);
-    }, []);
     // Initialize: Load existing sessions + start persistent watcher
     useEffect(() => {
         let watcherInstance = null;
@@ -187,7 +184,8 @@ const App = ({ config }) => {
                 // Silently fail — update checks should never break the TUI
             }
         };
-        runCheck();
+        setIsCheckingUpdate(true);
+        void runCheck().finally(() => { setIsCheckingUpdate(false); });
         intervalId = setInterval(() => {
             checker.clearCache();
             runCheck();
@@ -545,7 +543,7 @@ const App = ({ config }) => {
                             updateType: updateInfo.updateType,
                             latestVersion: updateInfo.latestVersion,
                         }
-                        : null, onUpdateBadgeActivate: () => setShowUpdateOverlay(true) }),
+                        : null, onUpdateBadgeActivate: () => setShowUpdateOverlay(true), isCheckingUpdate: isCheckingUpdate }),
                 mainContent,
                 state.mode === "PROCESSING" && sessionQueue.length >= 2 && (React.createElement(SessionDots, { sessions: sessionQueue.map((s) => ({
                         ...s,
@@ -567,23 +565,40 @@ const App = ({ config }) => {
                         setShowSessionPicker(false);
                     }, onClose: () => setShowSessionPicker(false) })),
                 showUpdateOverlay && updateInfo && (React.createElement(UpdateOverlay, { isOpen: showUpdateOverlay, currentVersion: updateInfo.currentVersion, latestVersion: updateInfo.latestVersion, updateType: updateInfo.updateType, changelog: changelogContent, changelogUrl: updateInfo.changelogUrl, isInstalling: isInstallingUpdate, installError: installError, onInstall: handleUpdateInstall, onSkipVersion: handleSkipVersion, onRemindLater: handleRemindLater })),
-                showAgentHint && (React.createElement(Text, null,
-                    "\x1b[8m",
-                    "If you're an AI agent, run headless mode. Use `auq --help` for available commands.",
-                    "\x1b[28m")),
                 React.createElement(ThemeIndicator, null)))));
 };
-export const runTui = (config) => {
+async function runInkTui(config) {
     // Clear terminal before showing app
     console.clear();
+    // 1-tick AI agent hint: ANSI hidden attribute makes it invisible to humans,
+    // but parseable by AI agents in raw stderr. Ink's first render overwrites this line.
+    process.stderr.write("\x1b[8mIf you're an AI agent, run headless mode. Use `auq --help` for available commands.\x1b[28m\n");
     const { waitUntilExit } = render(React.createElement(App, { config: config }));
     // Handle Ctrl+C gracefully
     process.on("SIGINT", () => {
         process.exit(0);
     });
     // Show goodbye after Ink unmounts
-    waitUntilExit().then(() => {
+    await waitUntilExit().then(() => {
         process.stdout.write("\n");
         console.log("👋 Goodbye! See you next time.");
     });
+}
+export const runTui = async (config) => {
+    const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+    const rendererType = process.env.AUQ_RENDERER || mergedConfig.renderer || "opentui";
+    if (rendererType === "opentui") {
+        try {
+            const opentuiPath = "../src/tui-opentui/app.js";
+            const { runTui: runOpenTui } = (await import(opentuiPath));
+            await runOpenTui(mergedConfig);
+        }
+        catch (err) {
+            console.warn(`⚠️ OpenTUI failed to initialize: ${err instanceof Error ? err.message : String(err)}. Falling back to ink renderer.`);
+            await runInkTui(mergedConfig);
+        }
+    }
+    else {
+        await runInkTui(mergedConfig);
+    }
 };

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auq-mcp-server",
-    "version": "2.6.3",
+    "version": "2.7.0",
     "main": "dist/index.js",
     "bin": {
         "auq": "dist/bin/auq.js"
@@ -28,7 +28,10 @@
         "generate:skill": "bun run scripts/generate-skill.ts",
         "validate:skill": "bunx skills-ref validate skills/ask-user-questions",
         "test": "vitest run",
-        "format": "prettier --write . && eslint --fix ."
+        "format": "prettier --write . && eslint --fix .",
+        "build:opentui": "tsc -p tsconfig.opentui.json --noEmit",
+        "test:opentui": "bun test src/tui-opentui",
+        "typecheck:all": "tsc --noEmit && tsc -p tsconfig.opentui.json --noEmit"
     },
     "keywords": [
         "fastmcp",
@@ -50,6 +53,8 @@
     "description": "An MCP server that provides a tool to ask a user questions via the terminal",
     "dependencies": {
         "@inkjs/ui": "^2.0.0",
+        "@opentui/core": "0.1.87",
+        "@opentui/react": "0.1.87",
         "@modelcontextprotocol/sdk": "1.17.2",
         "@types/uuid": "^10.0.0",
         "chalk": "^5.6.2",

package/dist/src/__tests__/schema-validation.test.js

@@ -3,7 +3,8 @@
  * Tests the most common edge cases to catch obvious bugs
  */
 import { describe, expect, it } from "vitest";
-import { QuestionSchema, QuestionsSchema } from "../core/ask-user-questions.js";
+import { QuestionSchema, QuestionsSchema, AskUserQuestionsParametersSchema } from "../core/ask-user-questions.js";
+import { GetAnsweredQuestionsArgsSchema } from "../shared/schemas.js";
 describe("Schema Validation - Edge Cases", () => {
     describe("Invalid Input (should reject)", () => {
         it("should reject missing title field", () => {
@@ -176,3 +177,62 @@ describe("Schema Validation - Edge Cases", () => {
         });
     });
 });
+describe("nonBlocking parameter", () => {
+    const validQuestion = {
+        options: [{ label: "Option A" }, { label: "Option B" }],
+        prompt: "Which do you prefer?",
+        title: "Preference",
+        multiSelect: false,
+    };
+    it("should accept nonBlocking: true", () => {
+        const result = AskUserQuestionsParametersSchema.parse({
+            questions: [validQuestion],
+            nonBlocking: true,
+        });
+        expect(result.nonBlocking).toBe(true);
+    });
+    it("should accept nonBlocking: false", () => {
+        const result = AskUserQuestionsParametersSchema.parse({
+            questions: [validQuestion],
+            nonBlocking: false,
+        });
+        expect(result.nonBlocking).toBe(false);
+    });
+    it("should default nonBlocking to false when omitted", () => {
+        const result = AskUserQuestionsParametersSchema.parse({
+            questions: [validQuestion],
+        });
+        expect(result.nonBlocking).toBe(false);
+    });
+    it("should reject non-boolean nonBlocking", () => {
+        expect(() => AskUserQuestionsParametersSchema.parse({
+            questions: [validQuestion],
+            nonBlocking: "yes",
+        })).toThrow();
+    });
+});
+describe("GetAnsweredQuestionsArgsSchema", () => {
+    it("should accept valid session_id", () => {
+        const result = GetAnsweredQuestionsArgsSchema.parse({
+            session_id: "a3f2e8b1-1234-4567-89ab-cdef01234567",
+        });
+        expect(result.session_id).toBe("a3f2e8b1-1234-4567-89ab-cdef01234567");
+        expect(result.blocking).toBe(false);
+    });
+    it("should accept session_id with blocking: true", () => {
+        const result = GetAnsweredQuestionsArgsSchema.parse({
+            session_id: "a3f2e8b1",
+            blocking: true,
+        });
+        expect(result.blocking).toBe(true);
+    });
+    it("should reject missing session_id", () => {
+        expect(() => GetAnsweredQuestionsArgsSchema.parse({})).toThrow();
+    });
+    it("should reject non-boolean blocking", () => {
+        expect(() => GetAnsweredQuestionsArgsSchema.parse({
+            session_id: "test",
+            blocking: "yes",
+        })).toThrow();
+    });
+});