auq-mcp-server 2.3.0 → 2.4.0

package/dist/src/cli/commands/sessions.js

@@ -0,0 +1,164 @@
+/**
+ * CLI Sessions Command — `auq sessions list` and `auq sessions dismiss`
+ * Manages listing and dismissing/archiving sessions.
+ */
+import { promises as fs } from "fs";
+import { join } from "path";
+import { SessionManager } from "../../session/SessionManager.js";
+import { getSessionDirectory } from "../../session/utils.js";
+import { loadConfig } from "../../config/ConfigLoader.js";
+import { formatAge, outputResult, parseFlags, resolveArchiveDirectory, } from "../utils.js";
+async function sessionsList(args) {
+    const { flags } = parseFlags(args);
+    const jsonMode = flags.json === true;
+    const filterStale = flags.stale === true;
+    const filterAll = flags.all === true;
+    // --pending is same as default
+    // Initialise SessionManager
+    const sessionManager = new SessionManager({
+        baseDir: getSessionDirectory(),
+    });
+    await sessionManager.initialize();
+    // Load staleThreshold from config
+    const config = loadConfig();
+    const staleThreshold = config.staleThreshold ?? 7200000;
+    // Get all session IDs
+    const sessionIds = await sessionManager.getAllSessionIds();
+    // Build entries
+    const entries = [];
+    for (const sessionId of sessionIds) {
+        const status = await sessionManager.getSessionStatus(sessionId);
+        if (!status)
+            continue;
+        const createdAt = status.createdAt;
+        const ageMs = Date.now() - new Date(createdAt).getTime();
+        const stale = ageMs > staleThreshold;
+        const age = formatAge(createdAt);
+        const isPending = status.status === "pending" || status.status === "in-progress";
+        // Apply filter
+        if (filterAll) {
+            // Show all statuses
+        }
+        else if (filterStale) {
+            // Only stale sessions that are pending/in-progress
+            if (!isPending || !stale)
+                continue;
+        }
+        else {
+            // Default / --pending: only pending/in-progress
+            if (!isPending)
+                continue;
+        }
+        const request = await sessionManager.getSessionRequest(sessionId);
+        const questionCount = request?.questions?.length ?? status.totalQuestions ?? 0;
+        entries.push({
+            sessionId,
+            status: status.status,
+            createdAt,
+            age,
+            stale,
+            questionCount,
+        });
+    }
+    // Sort by createdAt descending (newest first)
+    entries.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+    // Output
+    if (jsonMode) {
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+    }
+    if (entries.length === 0) {
+        console.log("No sessions found.");
+        return;
+    }
+    for (const entry of entries) {
+        const staleIndicator = entry.stale ? " ⚠" : "";
+        console.log(`${entry.sessionId}  ${entry.status}  ${entry.age}  questions: ${entry.questionCount}${staleIndicator}`);
+    }
+}
+// ── Sessions Dismiss ───────────────────────────────────────────────
+async function sessionsDismiss(args) {
+    const { flags, positionals } = parseFlags(args);
+    const jsonMode = flags.json === true;
+    const force = flags.force === true;
+    const sessionId = positionals[0];
+    // ── Validate sessionId ──────────────────────────────────────────
+    if (!sessionId) {
+        outputResult({
+            success: false,
+            error: "Missing session ID. Usage: auq sessions dismiss <sessionId> [--force] [--json]",
+        }, jsonMode);
+        process.exitCode = 1;
+        return;
+    }
+    // ── Initialise SessionManager ───────────────────────────────────
+    const sessionManager = new SessionManager({
+        baseDir: getSessionDirectory(),
+    });
+    await sessionManager.initialize();
+    // ── Verify session exists ──────────────────────────────────────
+    const exists = await sessionManager.sessionExists(sessionId);
+    if (!exists) {
+        outputResult({ success: false, error: `Session not found: ${sessionId}` }, jsonMode);
+        process.exitCode = 1;
+        return;
+    }
+    // ── Check stale status ─────────────────────────────────────────
+    const status = await sessionManager.getSessionStatus(sessionId);
+    const config = loadConfig();
+    const staleThreshold = config.staleThreshold ?? 7200000;
+    const ageMs = status
+        ? Date.now() - new Date(status.createdAt).getTime()
+        : 0;
+    const isStale = ageMs > staleThreshold;
+    if (!isStale && !force) {
+        outputResult({
+            success: false,
+            error: "Session is not stale. Use --force to dismiss anyway.",
+        }, jsonMode);
+        process.exitCode = 1;
+        return;
+    }
+    // ── Archive session ────────────────────────────────────────────
+    const archiveBase = resolveArchiveDirectory();
+    const archiveDir = join(archiveBase, sessionId);
+    await fs.mkdir(archiveDir, { recursive: true });
+    // Copy all files from session directory to archive
+    const sessionDir = join(getSessionDirectory(), sessionId);
+    const files = await fs.readdir(sessionDir);
+    for (const file of files) {
+        await fs.copyFile(join(sessionDir, file), join(archiveDir, file));
+    }
+    // ── Remove from active ─────────────────────────────────────────
+    await sessionManager.deleteSession(sessionId);
+    // ── Output ──────────────────────────────────────────────────────
+    outputResult({ success: true, sessionId, archivedTo: archiveDir }, jsonMode);
+    if (!jsonMode) {
+        console.log(`Session ${sessionId} dismissed and archived to ${archiveDir}.`);
+    }
+}
+// ── Sessions Command Dispatcher ────────────────────────────────────
+export async function runSessionsCommand(args) {
+    const subcommand = args[0];
+    switch (subcommand) {
+        case "list":
+            return sessionsList(args.slice(1));
+        case "dismiss":
+            return sessionsDismiss(args.slice(1));
+        default:
+            console.log("Usage: auq sessions <subcommand>", "\n");
+            console.log("Subcommands:");
+            console.log("  list [--pending|--stale|--all] [--json]  List sessions");
+            console.log("  dismiss <sessionId> [--force] [--json]    Dismiss/archive a session");
+            console.log("");
+            console.log("Examples:");
+            console.log("  auq sessions list");
+            console.log("  auq sessions list --stale --json");
+            console.log("  auq sessions dismiss <sessionId>");
+            console.log("  auq sessions dismiss <sessionId> --force");
+            if (subcommand !== undefined) {
+                process.exitCode = 1;
+            }
+            break;
+    }
+}

package/dist/src/cli/utils.js

@@ -0,0 +1,95 @@
+import { homedir } from "os";
+import { join } from "path";
+/**
+ * Parse CLI flags from an args array.
+ * Handles --flag (boolean) and --flag value patterns.
+ * Everything not starting with -- goes to positionals.
+ */
+export function parseFlags(args) {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith("--")) {
+            const key = arg.slice(2);
+            const next = args[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                flags[key] = next;
+                i++; // skip next arg — it was consumed as a value
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    return { flags, positionals };
+}
+/**
+ * Standard CLI output helper.
+ * - jsonMode: console.log(JSON.stringify(result, null, 2))
+ * - else: human-readable formatted output
+ */
+export function outputResult(result, jsonMode) {
+    if (jsonMode) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (!result.success) {
+        const message = typeof result.error === "string"
+            ? result.error
+            : typeof result.message === "string"
+                ? result.message
+                : "Unknown error";
+        console.error(`Error: ${message}`);
+        return;
+    }
+    // Human-readable: print each key=value pair (skip success)
+    for (const [key, value] of Object.entries(result)) {
+        if (key === "success")
+            continue;
+        if (typeof value === "object" && value !== null) {
+            console.log(`${key}:`);
+            for (const [subKey, subValue] of Object.entries(value)) {
+                console.log(`  ${subKey} = ${String(subValue)}`);
+            }
+        }
+        else {
+            console.log(`${key} = ${String(value)}`);
+        }
+    }
+}
+/**
+ * Format age from a timestamp to a human-readable string.
+ * Returns "Xm ago", "Xh ago", "Xd ago", etc.
+ */
+export function formatAge(createdAt) {
+    const now = Date.now();
+    const then = createdAt instanceof Date
+        ? createdAt.getTime()
+        : new Date(createdAt).getTime();
+    const diffMs = now - then;
+    if (diffMs < 0)
+        return "just now";
+    const seconds = Math.floor(diffMs / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0)
+        return `${days}d ago`;
+    if (hours > 0)
+        return `${hours}h ago`;
+    if (minutes > 0)
+        return `${minutes}m ago`;
+    return `${seconds}s ago`;
+}
+/**
+ * Resolve the archive directory for dismissed sessions.
+ * Uses the XDG data home standard: ~/.local/share/auq/archive
+ */
+export function resolveArchiveDirectory() {
+    const xdgDataHome = process.env.XDG_DATA_HOME || join(homedir(), ".local", "share");
+    return join(xdgDataHome, "auq", "archive");
+}

package/dist/src/config/__tests__/ConfigLoader.test.js

@@ -91,4 +91,45 @@ describe("ConfigLoader", () => {
             expect(paths.globalExists).toBe(true);
         });
     });
+    describe("stale/orphan session config options", () => {
+        it("should include stale config defaults when no config files exist", () => {
+            vi.mocked(fs.existsSync).mockReturnValue(false);
+            const config = loadConfig();
+            expect(config.staleThreshold).toBe(7200000);
+            expect(config.notifyOnStale).toBe(true);
+            expect(config.staleAction).toBe("warn");
+        });
+        it("should load staleThreshold from config file", () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ staleThreshold: 3600000 }));
+            const config = loadConfig();
+            expect(config.staleThreshold).toBe(3600000);
+        });
+        it("should load staleAction from config file", () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ staleAction: "archive" }));
+            const config = loadConfig();
+            expect(config.staleAction).toBe("archive");
+        });
+        it("should load notifyOnStale from config file", () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ notifyOnStale: false }));
+            const config = loadConfig();
+            expect(config.notifyOnStale).toBe(false);
+        });
+        it("should fall back to default for invalid staleAction value", () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ staleAction: "invalid_action" }));
+            const config = loadConfig();
+            // Invalid enum value should be ignored, default used
+            expect(config.staleAction).toBe(DEFAULT_CONFIG.staleAction);
+        });
+        it("should reject negative staleThreshold value", () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ staleThreshold: -1000 }));
+            const config = loadConfig();
+            // Negative value should be rejected by min(0), default used
+            expect(config.staleThreshold).toBe(DEFAULT_CONFIG.staleThreshold);
+        });
+    });
 });

package/dist/src/config/defaults.js

@@ -8,6 +8,9 @@ export const DEFAULT_CONFIG = {
     language: "auto",
     theme: "system",
     autoSelectRecommended: true,
+    staleThreshold: 7200000, // 2 hours in ms
+    notifyOnStale: true,
+    staleAction: "warn",
     notifications: {
         enabled: true,
         sound: true,

package/dist/src/config/types.js

@@ -21,6 +21,10 @@ export const AUQConfigSchema = z.object({
     language: z.string().default("auto"),
     theme: z.string().default("system"),
     autoSelectRecommended: z.boolean().default(true),
+    // Stale/Orphan Session Detection
+    staleThreshold: z.number().min(0).default(7200000), // 2 hours in ms
+    notifyOnStale: z.boolean().default(true),
+    staleAction: z.enum(["warn", "remove", "archive"]).default("warn"),
     // Notifications (OSC 9/99)
     notifications: NotificationConfigSchema.default({
         enabled: true,

package/dist/src/core/ask-user-questions.js

@@ -22,14 +22,15 @@ export const createAskUserQuestionsCore = (options = {}) => {
         title: question.title,
         multiSelect: question.multiSelect,
     }));
-    const ask = async (questions, callId, workingDirectory) => {
+    const ask = async (questions, callId, workingDirectory, signal) => {
         await ensureInitialized();
         const parsedQuestions = QuestionsSchema.parse(questions);
-        return sessionManager.startSession(normalizeQuestions(parsedQuestions), callId, workingDirectory);
+        return sessionManager.startSession(normalizeQuestions(parsedQuestions), callId, workingDirectory, signal);
     };
     return {
         ask,
         cleanupExpiredSessions: () => sessionManager.cleanupExpiredSessions(),
         ensureInitialized,
+        markAbandoned: (sessionId) => sessionManager.updateSessionStatus(sessionId, "abandoned"),
     };
 };

package/dist/src/i18n/locales/en.js

@@ -39,6 +39,7 @@ export const en = {
         copied: "Copied to clipboard",
         saved: "Saved",
         error: "Error",
+        staleSession: "Session \"{title}\" may be orphaned (created {hours}h ago)",
     },
     stepper: {
         submitting: "Submitting answers...",
@@ -72,4 +73,10 @@ export const en = {
     ui: {
         themeLabel: "theme:",
     },
+    abandoned: {
+        title: "AI Disconnected",
+        message: "The AI has disconnected. Do you still want to answer?",
+        continue: "Answer anyway",
+        cancel: "Cancel",
+    },
 };

package/dist/src/i18n/locales/ko.js

@@ -39,6 +39,7 @@ export const ko = {
         copied: "클립보드에 복사됨",
         saved: "저장됨",
         error: "오류",
+        staleSession: "세션 \"{title}\"이 고아 상태일 수 있습니다 ({hours}시간 전 생성)",
     },
     stepper: {
         submitting: "답변 제출 중...",
@@ -72,4 +73,10 @@ export const ko = {
     ui: {
         themeLabel: "테마:",
     },
+    abandoned: {
+        title: "AI 연결 끊김",
+        message: "AI가 disconnect되었습니다. 그래도 답변하시겠습니까?",
+        continue: "답변하기",
+        cancel: "취소",
+    },
 };

package/dist/src/server.js

@@ -3,6 +3,8 @@ import { randomUUID } from "crypto";
 import { AskUserQuestionsParametersSchema, createAskUserQuestionsCore, } from "./core/ask-user-questions.js";
 import { TOOL_DESCRIPTION } from "./shared/schemas.js";
 const askUserQuestionsCore = createAskUserQuestionsCore();
+// Track active requests with their AbortControllers for disconnect handling
+const activeRequests = new Map();
 const server = new FastMCP({
     name: "AskUserQuestions",
     instructions: "MCP server for asking users structured questions during AI execution. " +
@@ -41,22 +43,50 @@ server.addTool({
             }
             // Generate a per-tool-call ID and persist it with the session
             const callId = randomUUID();
+            // Create AbortController for this request to handle disconnects
+            const controller = new AbortController();
+            activeRequests.set(callId, { controller });
             // Capture working directory if available from MCP context
             // Note: MCP protocol does not currently expose client working directory
             // This field is reserved for future protocol enhancements
             const workingDirectory = ctx
                 .workingDirectory;
-            const { formattedResponse, sessionId } = await askUserQuestionsCore.ask(args.questions, callId, workingDirectory);
-            log.info("Session completed successfully", { sessionId, callId });
-            // Return formatted response to AI model
-            return {
-                content: [
-                    {
-                        text: formattedResponse,
-                        type: "text",
-                    },
-                ],
-            };
+            try {
+                const { formattedResponse, sessionId } = await askUserQuestionsCore.ask(args.questions, callId, workingDirectory, controller.signal);
+                // Update entry with sessionId for disconnect handler
+                const entry = activeRequests.get(callId);
+                if (entry) {
+                    entry.sessionId = sessionId;
+                }
+                log.info("Session completed successfully", { sessionId, callId });
+                // Return formatted response to AI model
+                return {
+                    content: [
+                        {
+                            text: formattedResponse,
+                            type: "text",
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                // Handle abort (AI client disconnected)
+                if (error instanceof Error && error.message === "ABORTED") {
+                    log.warn("Session aborted: AI client disconnected", { callId });
+                    return {
+                        content: [
+                            {
+                                text: "Session aborted: AI client disconnected",
+                                type: "text",
+                            },
+                        ],
+                    };
+                }
+                throw error; // Re-throw other errors to outer catch
+            }
+            finally {
+                activeRequests.delete(callId);
+            }
         }
         catch (error) {
             log.error("Session failed", { error: String(error) });
@@ -72,6 +102,29 @@ server.addTool({
     },
     parameters: AskUserQuestionsParametersSchema,
 });
+// Handle AI client disconnections gracefully
+// Note: FastMCP disconnect event support depends on the version.
+// If the event is not available, stale detection handles orphaned sessions as fallback.
+try {
+    server.on("disconnect", async () => {
+        for (const [callId, entry] of activeRequests.entries()) {
+            try {
+                entry.controller.abort();
+                if (entry.sessionId) {
+                    await askUserQuestionsCore.markAbandoned(entry.sessionId).catch(() => { });
+                }
+            }
+            catch {
+                // Silently ignore errors during disconnect cleanup
+            }
+            activeRequests.delete(callId);
+        }
+    });
+}
+catch {
+    // FastMCP version may not support disconnect events
+    // Graceful fallback: stale detection handles orphaned sessions
+}
 // Start the server with stdio transport
 server.start({
     transportType: "stdio",

package/dist/src/session/SessionManager.js

@@ -141,6 +141,29 @@ export class SessionManager {
     async getSessionAnswers(sessionId) {
         return this.readSessionFile(sessionId, SESSION_FILES.ANSWERS);
     }
+    /**
+     * Get all pending sessions, optionally including abandoned ones
+     */
+    async getPendingSessions(options) {
+        const sessionIds = await this.getAllSessionIds();
+        const pendingSessions = [];
+        for (const sessionId of sessionIds) {
+            try {
+                const status = await this.getSessionStatus(sessionId);
+                if (!status)
+                    continue;
+                const isPending = status.status === "pending" || status.status === "in-progress";
+                const isAbandoned = status.status === "abandoned";
+                if (isPending || (options?.includeAbandoned && isAbandoned)) {
+                    pendingSessions.push(sessionId);
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return pendingSessions;
+    }
     /**
      * Get session count
      */
@@ -160,6 +183,13 @@ export class SessionManager {
     async getSessionStatus(sessionId) {
         return this.readSessionFile(sessionId, SESSION_FILES.STATUS);
     }
+    /**
+     * Check if a session has been abandoned
+     */
+    async isAbandoned(sessionId) {
+        const status = await this.getSessionStatus(sessionId);
+        return status?.status === "abandoned";
+    }
     /**
      * Initialize the session manager - create base directories
      */
@@ -239,9 +269,21 @@ export class SessionManager {
      * @returns Object containing sessionId and formatted response text
      * @throws Error if timeout occurs, validation fails, or file operations fail
      */
-    async startSession(questions, callId, workingDirectory) {
+    async startSession(questions, callId, workingDirectory, signal) {
         // Step 1: Create the session
         const sessionId = await this.createSession(questions, workingDirectory);
+        // Step 1.5: Register abort handler if signal provided
+        let abortHandler;
+        if (signal) {
+            if (signal.aborted) {
+                await this.updateSessionStatus(sessionId, "abandoned");
+                throw new Error("ABORTED");
+            }
+            abortHandler = () => {
+                this.updateSessionStatus(sessionId, "abandoned").catch(() => { });
+            };
+            signal.addEventListener("abort", abortHandler, { once: true });
+        }
         // Optionally attach callId and workingDirectory metadata to request and status
         if (callId || workingDirectory) {
             try {
@@ -274,11 +316,23 @@ export class SessionManager {
                 : 0; // Also infinite if session is infinite
             // Step 3: Wait for answers with timeout
             try {
-                await this.waitForAnswers(sessionId, watcherTimeout, callId);
+                await this.waitForAnswers(sessionId, watcherTimeout, callId, signal);
             }
             catch (error) {
+                // Check if session was aborted (AI disconnected)
+                if (error instanceof Error && error.message === "ABORTED") {
+                    // Clean up abort handler
+                    if (abortHandler && signal) {
+                        signal.removeEventListener("abort", abortHandler);
+                    }
+                    throw error;
+                }
                 // Check if session was rejected by user
                 if (error instanceof Error && error.message === "SESSION_REJECTED") {
+                    // Clean up abort handler
+                    if (abortHandler && signal) {
+                        signal.removeEventListener("abort", abortHandler);
+                    }
                     // Get session status to retrieve rejection reason
                     const status = await this.getSessionStatus(sessionId);
                     const reason = status?.rejectionReason;
@@ -290,7 +344,6 @@ export class SessionManager {
                     else {
                         formattedResponse += "No reason provided.\n\n";
                     }
-                    // formattedResponse += "The user chose not to answer these questions at this time.";
                     return {
                         formattedResponse,
                         sessionId,
@@ -331,6 +384,10 @@ export class SessionManager {
             const formattedResponse = ResponseFormatter.formatUserResponse(answers, request.questions);
             // Step 7: Update final status
             await this.updateSessionStatus(sessionId, "completed");
+            // Clean up abort handler after successful completion
+            if (abortHandler && signal) {
+                signal.removeEventListener("abort", abortHandler);
+            }
             // Step 8: Return results
             return {
                 formattedResponse,
@@ -338,6 +395,10 @@ export class SessionManager {
             };
         }
         catch (error) {
+            // Clean up abort handler on error
+            if (abortHandler && signal) {
+                signal.removeEventListener("abort", abortHandler);
+            }
             // Ensure any errors are properly propagated with session context
             if (error instanceof Error) {
                 throw error;
@@ -416,7 +477,7 @@ export class SessionManager {
      * Wait for user answers to be submitted for a specific session
      * Returns the session ID when answers are detected, or rejects on timeout
      */
-    async waitForAnswers(sessionId, timeoutMs, expectedCallId) {
+    async waitForAnswers(sessionId, timeoutMs, expectedCallId, signal) {
         const sessionDir = this.getSessionDir(sessionId);
         const answersPath = join(sessionDir, SESSION_FILES.ANSWERS);
         const startTime = Date.now();
@@ -448,6 +509,10 @@ export class SessionManager {
             if (status && status.status === "rejected") {
                 throw new Error("SESSION_REJECTED");
             }
+            // Check for abort signal
+            if (signal?.aborted) {
+                throw new Error("ABORTED");
+            }
             // Check for timeout
             if (timeoutMs && timeoutMs > 0 && Date.now() - startTime > timeoutMs) {
                 throw new Error("Timeout waiting for user response");