@0xmaxma/claude-gateway 1.3.3 → 1.3.5

package/README.md

@@ -29,7 +29,7 @@ A self-hosted multi-agent gateway for Claude Code. Connect Claude agents to Tele
 - **App Store** — install, update, and host Docker-compose apps on the gateway; apps get a reverse proxy at `/app/:name/:portName/*`, optional Unix socket bridge for host scripts, and optional AI agent injection
 - **Self-update API** — check for newer versions of `claude-gateway` and `claude-code` and trigger an update via a single API call; no SSH or shell access needed
 - **Session persistence** — conversation history saved and restored across restarts
-- **PTY backend** — optional interactive pseudo-terminal backend (`gateway.headless: false`) for tools that require a real TTY; uses `TranscriptTailer` for reliable output instead of ANSI parsing; app-agents always stay headless
+- **PTY shell (wrap-shell mode)** — optional interactive pseudo-terminal backend (`gateway.headless: false`) for tools that require a real TTY; includes a live browser viewer (xterm.js) and a `/api/v1/sessions/:sessionId/screen` endpoint that returns the visible screen as plain text — agents can poll it to detect hang states, menus, or unexpected output without parsing ANSI escape codes; app-agents always stay headless
 
 ---
 

package/dist/agent/runner.d.ts

@@ -29,6 +29,8 @@ export declare class AgentRunner extends EventEmitter {
     private readonly sessionSpawnLocks;
     private readonly pendingImagePaths;
     private readonly pendingApiAttachments;
+    private readonly sessionHistory;
+    private readonly apiChatIds;
     private skillRegistry;
     private readonly configPath;
     private readonly historyDb;
@@ -133,6 +135,13 @@ export declare class AgentRunner extends EventEmitter {
     private writeTypingDone;
     private triggerSummaryAndRestart;
     private writeAutoForward;
+    /**
+     * Signal the channel receiver to render an interactive menu as native UI
+     * (inline buttons on Telegram/Discord). The receiver maps each option to a
+     * `choice:N` callback whose tap arrives back as a normal "N" message — the
+     * same as the user typing the number.
+     */
+    private writeMenuForward;
     private startIdleCleaner;
     start(): Promise<void>;
     updateAgentConfig(newConfig: AgentConfig): void;
@@ -145,6 +154,17 @@ export declare class AgentRunner extends EventEmitter {
     private _startCleanupScheduler;
     restart(): Promise<void>;
     isRunning(): boolean;
+    getSessionsSummary(): Array<{
+        chatId: string;
+        sessionId: string;
+        source: string;
+        mode: string;
+        model: string;
+        isRunning: boolean;
+        spawnedAt: number;
+        uptimeSec: number;
+        tokens: number;
+    }>;
     /**
      * Send a message to an API session and wait for the response.
      *
@@ -203,7 +223,12 @@ export declare class AgentRunner extends EventEmitter {
         name: string;
     }>>;
     listSessionsForChat(chatId: string, channel: 'telegram' | 'discord'): Promise<import('../types').SessionIndex>;
-    executeApiCommand(sessionId: string, chatId: string, command: string): Promise<Record<string, unknown>>;
+    executeApiCommand(sessionId: string, chatId: string, command: string, opts?: {
+        skipPersist?: boolean;
+    }): Promise<{
+        result: Record<string, unknown>;
+        responseText: string;
+    }>;
     setModel(newModel: string): Promise<void>;
     listApiSessions(chatId: string): Promise<import('../types').SessionIndex>;
     createApiSession(chatId: string, prompt?: string, name?: string): Promise<import('../types').SessionMeta>;

package/dist/agent/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/agent/runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/agent/runner.ts"],"names":[],"mappings":"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"}

package/dist/agent/runner.js

@@ -128,6 +128,12 @@ class AgentRunner extends events_1.EventEmitter {
         this.pendingImagePaths = new Map();
         // Buffers attachment file paths registered via api_reply tool for the current API session turn.
         this.pendingApiAttachments = new Map();
+        // Session history ring-buffer (last 10 spawned, newest first)
+        this.sessionHistory = [];
+        // For API sessions the map key is the sessionId, so the real caller chatId
+        // (e.g. the app/agent identifier) is not captured at spawn. Record it here
+        // keyed by sessionId so the dashboard can show the actual chat id.
+        this.apiChatIds = new Map();
         // Skill registry for detecting /skill-name commands in user messages
         this.skillRegistry = { skills: new Map() };
         // Cancel function for the daily history cleanup timer
@@ -619,6 +625,9 @@ class AgentRunner extends events_1.EventEmitter {
             // Auto-forward result text to channel if agent didn't call reply tool.
             let replyCalled = false;
             let replyToolUseId = null; // track id to detect failed tool calls
+            // Set when an interactive-menu prompt was rendered to the channel this turn,
+            // so the result's plain-text auto-forward is skipped (no duplicate message).
+            let menuSentThisTurn = false;
             let typingDoneTimer = null;
             const TYPING_DONE_DELAY_MS = 3000;
             const replyToolName = source === 'discord' ? 'mcp__gateway__discord_reply' : 'mcp__gateway__telegram_reply';
@@ -667,6 +676,31 @@ class AgentRunner extends events_1.EventEmitter {
                             }
                         }
                     }
+                    // Interactive select menu blocking the PTY: render it as channel-native
+                    // UI (inline buttons). This output handler only runs for Telegram/Discord
+                    // sessions; API uses a separate path and falls back to the result text's
+                    // numbered list (no buttons), as intended.
+                    if (obj['type'] === 'system' && obj['subtype'] === 'menu_prompt') {
+                        const promptText = typeof obj['prompt'] === 'string' ? obj['prompt'] : '';
+                        const rawOptions = Array.isArray(obj['options']) ? obj['options'] : [];
+                        const options = rawOptions
+                            .map((o) => ({ label: typeof o?.label === 'string' ? o.label : '' }))
+                            .filter((o) => o.label);
+                        if (promptText && options.length) {
+                            this.writeMenuForward(mapKey, promptText, options);
+                            menuSentThisTurn = true;
+                            // Persist the question to chat history so it's visible in the transcript.
+                            const channelSrc = this.channelSourceMap.get(mapKey) ?? 'telegram';
+                            this.historyDb.insertMessage({
+                                chatId: `${channelSrc}-${mapKey}`,
+                                sessionId: actualSessionId,
+                                source: channelSrc,
+                                role: 'assistant',
+                                content: promptText,
+                                ts: Date.now(),
+                            });
+                        }
+                    }
                     if (obj['type'] === 'result') {
                         proc.setProcessing(false);
                         // Telegram: accumulate image size via stat of local file (FIFO, one per turn)
@@ -699,7 +733,9 @@ class AgentRunner extends events_1.EventEmitter {
                         // Suppress the corrupted-thinking 400: the session auto-respawns to recover,
                         // so the raw API error must not reach the user's chat or the history DB.
                         const isThinkingCorruption = obj['is_error'] === true && process_1.SessionProcess.isThinkingCorruptionError(resultText);
-                        if (resultText.trim() && !proc.queryMode && !replyCalled && !isThinkingCorruption) {
+                        // Skip when a menu was rendered to buttons this turn — the result
+                        // text is the same numbered list and would duplicate the menu message.
+                        if (resultText.trim() && !proc.queryMode && !replyCalled && !isThinkingCorruption && !menuSentThisTurn) {
                             const text = resultText.trim();
                             const channelSrcForResult = this.channelSourceMap.get(mapKey) ?? 'telegram';
                             // Persist assistant reply to permanent history DB
@@ -721,6 +757,7 @@ class AgentRunner extends events_1.EventEmitter {
                         }
                         replyCalled = false; // reset for next turn
                         replyToolUseId = null;
+                        menuSentThisTurn = false;
                         // Delay typing done — agent may continue with more work
                         typingDoneTimer = setTimeout(() => {
                             this.writeTypingDone(mapKey);
@@ -775,6 +812,9 @@ class AgentRunner extends events_1.EventEmitter {
             });
         }
         this.sessions.set(mapKey, proc);
+        this.sessionHistory.unshift({ chatId: mapKey, sessionId: proc.sessionId, source: proc.source, mode: proc.backend, model: proc.model, spawnedAt: proc.spawnedAt });
+        if (this.sessionHistory.length > 10)
+            this.sessionHistory.length = 10;
         if (source === 'telegram' || source === 'discord') {
             this.channelSourceMap.set(mapKey, source);
         }
@@ -1112,6 +1152,27 @@ class AgentRunner extends events_1.EventEmitter {
             // Non-fatal
         }
     }
+    /**
+     * Signal the channel receiver to render an interactive menu as native UI
+     * (inline buttons on Telegram/Discord). The receiver maps each option to a
+     * `choice:N` callback whose tap arrives back as a normal "N" message — the
+     * same as the user typing the number.
+     */
+    writeMenuForward(chatId, text, options) {
+        const typingDir = this.getTypingDir(chatId);
+        try {
+            fs.mkdirSync(typingDir, { recursive: true });
+            // Write atomically (tmp + rename): the receiver polls this directory every
+            // second, so a non-atomic write could be read mid-flush as truncated JSON.
+            const finalPath = path.join(typingDir, `${chatId}.menu`);
+            const tmpPath = `${finalPath}.tmp`;
+            fs.writeFileSync(tmpPath, JSON.stringify({ text, options }));
+            fs.renameSync(tmpPath, finalPath);
+        }
+        catch {
+            // Non-fatal — the result text still carries the numbered list as a fallback.
+        }
+    }
     startIdleCleaner() {
         this.idleCleanerTimer = setInterval(async () => {
             for (const [id, proc] of this.sessions) {
@@ -1220,6 +1281,34 @@ class AgentRunner extends events_1.EventEmitter {
     isRunning() {
         return this.receiver?.isRunning() ?? false;
     }
+    getSessionsSummary() {
+        const now = Date.now();
+        // A single logical session can appear multiple times in the ring buffer: a
+        // restart / model-switch / error-recovery respawn pushes a fresh entry with
+        // the SAME sessionId but a new spawnedAt. History is newest-first (unshift),
+        // so the first occurrence of a (source, sessionId, chatId) is the current
+        // incarnation — collapse to it so the dashboard shows one row per session
+        // instead of duplicating it.
+        const seen = new Set();
+        const out = [];
+        for (const e of this.sessionHistory) {
+            const dedupKey = `${e.source}:${e.sessionId}:${e.chatId}`;
+            if (seen.has(dedupKey))
+                continue;
+            seen.add(dedupKey);
+            const proc = this.sessions.get(e.chatId);
+            // Running only when the live process IS this incarnation: a stale entry
+            // from before a respawn must not borrow the new process's running state.
+            const isRunning = !!proc && proc.spawnedAt === e.spawnedAt;
+            // For API sessions the ring-buffer chatId equals the sessionId (the map key);
+            // surface the real caller chatId instead when we have it.
+            const chatId = e.source === 'api' ? (this.apiChatIds.get(e.sessionId) ?? e.chatId) : e.chatId;
+            // Live context-window token usage from the running process (0 when stopped).
+            const tokens = isRunning ? (proc?.totalTokens ?? 0) : 0;
+            out.push({ ...e, chatId, isRunning, uptimeSec: Math.floor((now - e.spawnedAt) / 1000), tokens });
+        }
+        return out;
+    }
     /**
      * Send a message to an API session and wait for the response.
      *
@@ -1239,6 +1328,7 @@ class AgentRunner extends events_1.EventEmitter {
         });
         // Use model from request body if provided, otherwise use agent default
         const session = await this.getOrSpawnSession(sessionId, 'api', undefined, opts.model);
+        this.apiChatIds.set(sessionId, chatId);
         // Promote UI-uploaded files from staging to permanent per-session storage
         const finalMediaFiles = opts.mediaFiles?.length
             ? await promoteUiUploads(this.agentsBaseDir, this.agentConfig.id, sessionId, opts.mediaFiles, this.logger)
@@ -1302,8 +1392,9 @@ class AgentRunner extends events_1.EventEmitter {
             const done = (result) => {
                 cleanup();
                 const attachments = this.popApiAttachments(sessionId);
-                // Persist assistant reply
-                if (result.trim()) {
+                // Persist assistant reply. Image-only replies (empty text but attachments
+                // present) must also persist — otherwise the screenshot vanishes from history.
+                if (result.trim() || attachments.length) {
                     const apiAssistantTs = Date.now();
                     this.sessionStore
                         .appendMessage(this.agentConfig.id, sessionId, {
@@ -1318,6 +1409,7 @@ class AgentRunner extends events_1.EventEmitter {
                         source: 'api',
                         role: 'assistant',
                         content: result.trim(),
+                        mediaFiles: attachments.length ? attachments.map((a) => `media/${a.relPath}`) : undefined,
                         ts: apiAssistantTs,
                     });
                 }
@@ -1409,6 +1501,7 @@ class AgentRunner extends events_1.EventEmitter {
         });
         // Use model from request body if provided, otherwise use agent default
         const session = await this.getOrSpawnSession(sessionId, 'api', undefined, opts.model);
+        this.apiChatIds.set(sessionId, chatId);
         // Promote UI-uploaded files from staging to permanent per-session storage
         const finalMediaFilesStream = opts.mediaFiles?.length
             ? await promoteUiUploads(this.agentsBaseDir, this.agentConfig.id, sessionId, opts.mediaFiles, this.logger)
@@ -1449,8 +1542,10 @@ class AgentRunner extends events_1.EventEmitter {
             settled = true;
             cleanup();
             const attachments = this.popApiAttachments(sessionId);
-            // Persist assistant reply regardless of whether the SSE client is still connected
-            if (result.trim()) {
+            // Persist assistant reply regardless of whether the SSE client is still connected.
+            // Image-only replies (empty text but attachments present) must also persist —
+            // otherwise the screenshot vanishes from history once the stream ends.
+            if (result.trim() || attachments.length) {
                 const streamAssistantTs = Date.now();
                 this.sessionStore
                     .appendMessage(this.agentConfig.id, sessionId, {
@@ -1465,6 +1560,7 @@ class AgentRunner extends events_1.EventEmitter {
                     source: 'api',
                     role: 'assistant',
                     content: result.trim(),
+                    mediaFiles: attachments.length ? attachments.map((a) => `media/${a.relPath}`) : undefined,
                     ts: streamAssistantTs,
                 });
             }
@@ -1621,11 +1717,13 @@ class AgentRunner extends events_1.EventEmitter {
             if (!fs.existsSync(absPath))
                 return null;
             const rel = absPath.slice(mediaRoot.length).replace(/\\/g, '/');
-            return { type: 'image', url: `/v1/agents/${encodeURIComponent(this.agentConfig.id)}/media/${rel}` };
+            return { type: 'image', url: `/v1/agents/${encodeURIComponent(this.agentConfig.id)}/media/${rel}`, relPath: rel };
         })
             .filter((a) => a !== null);
     }
     cleanupApiSessionMediaDir(sessionId, source) {
+        // Always evict the chat-id mapping — safe no-op for non-api sessions.
+        this.apiChatIds.delete(sessionId);
         if (source !== 'api')
             return;
         const mediaDir = path.join(this.agentsBaseDir, this.agentConfig.id, 'media', `api-${sessionId}`);
@@ -1651,73 +1749,171 @@ class AgentRunner extends events_1.EventEmitter {
     async listSessionsForChat(chatId, channel) {
         return this.sessionStore.listSessions(this.agentConfig.id, chatId, channel);
     }
-    async executeApiCommand(sessionId, chatId, command) {
+    async executeApiCommand(sessionId, chatId, command, opts) {
         const agentId = this.agentConfig.id;
         const storeChatId = chatId; // sessionStore adds channel prefix internally
         const dbChatId = `api-${chatId}`; // historyDb uses full channel-chatId key
-        if (command === '/model') {
-            return { model: this.agentConfig.claude.model };
-        }
-        if (command === '/stop') {
-            const session = this.sessions.get(sessionId);
-            const stopped = session ? session.interrupt() : false;
-            return { stopped };
-        }
-        if (command === '/restart') {
-            this.restartProcess(sessionId).catch(() => { });
-            return { restarting: true };
-        }
-        if (command === '/session') {
-            const index = await this.sessionStore.listSessions(agentId, storeChatId, 'api').catch(() => null);
-            const meta = index?.sessions.find((s) => s.id === sessionId);
-            const effectiveModel = this.agentConfig.claude.model;
-            if (!meta)
-                return { sessionId, sessionName: null, messageCount: 0, archivedCount: 0, contextUsedPct: 0, model: effectiveModel };
-            const availableModels = this.gatewayConfig.gateway.models ?? exports.DEFAULT_MODELS;
-            const modelConfig = availableModels.find((m) => m.id === effectiveModel);
-            const contextWindow = modelConfig?.contextWindow ?? 200000;
-            const contextUsedPct = Math.round(((meta.lastInputTokens ?? 0) / contextWindow) * 100);
-            return {
-                sessionId,
-                sessionName: meta.name,
-                messageCount: meta.messageCount,
-                archivedCount: meta.archivedCount ?? 0,
-                contextUsedPct,
-                model: effectiveModel,
-            };
+        const skipPersist = opts?.skipPersist ?? false;
+        // Dispatch on the first token so commands with arguments (e.g. "/model sonnet",
+        // "/stop now") resolve to their base command instead of falling through to the
+        // unknown-command branch. The router gate is prefix-based, so these already pass.
+        const cmd = command.trim().split(/\s+/)[0] ?? '';
+        // Validate BEFORE persisting anything. Reuse the same api-channel gate as the router
+        // so an unknown command throws with nothing written — no orphan user row is left, and
+        // the router surfaces the error/500 exactly as before. After token dispatch + the
+        // /sessions branch below, this is only reachable on a direct caller passing garbage.
+        if (!AgentRunner.isApiBuiltinCommand(cmd)) {
+            throw new Error(`Unknown command: ${cmd}`);
+        }
+        // Register session in the api-{chatId} index on first use (same as sendApiMessageStream)
+        await this.sessionStore.ensureApiSession(agentId, storeChatId, sessionId).catch((err) => {
+            this.logger.warn('Failed to register API session in index for command', { agentId, chatId, sessionId, error: err.message });
+        });
+        // Persist a command message to the permanent history DB ONLY — not the model's session
+        // context (sessionStore). historyDb is what the web history endpoint reads, so this is
+        // all the display + spinner fix needs. Keeping commands out of the JSONL context means
+        // /model replies aren't replayed into the model, /compact counts stay accurate, /clear
+        // leaves no dangling turn, and the api channel matches telegram (which persists commands
+        // nowhere).
+        //
+        // skipPersist (wire param store_user_message=false) suppresses BOTH the user command and
+        // the assistant reply: programmatic REST callers leave no trace in chat history at all.
+        const persist = (role, content) => {
+            if (skipPersist || !content)
+                return;
+            this.historyDb.insertMessage({ chatId: dbChatId, sessionId, source: 'api', role, content, ts: Date.now() });
+        };
+        // Persist the full user command before executing so it appears in history.
+        // Skip for /clear — clearSession() below wipes the table anyway; only the response survives.
+        if (cmd !== '/clear') {
+            persist('user', command);
         }
-        if (command === '/clear') {
-            const ch = 'api';
-            await this.sessionStore.clearTelegramSessionHistory(agentId, storeChatId, sessionId, ch);
-            await this.sessionStore.updateSessionMeta(agentId, storeChatId, sessionId, {
-                totalTokensUsed: 0,
-                lastInputTokens: 0,
-                archivedCount: 0,
-                loadedAtSpawn: undefined,
-                messageCountAtSpawn: undefined,
-            }, ch);
-            const mediaPaths = this.historyDb.clearSession(dbChatId, sessionId);
-            media_store_1.MediaStore.deleteMediaFiles(this.agentsBaseDir, agentId, mediaPaths);
-            this.restartProcess(sessionId).catch(() => { });
-            return { success: true };
-        }
-        if (command === '/compact') {
-            const ch = 'api';
-            const compactEffectiveModel = this.agentConfig.claude.model;
-            const availableModels = this.gatewayConfig.gateway.models ?? exports.DEFAULT_MODELS;
-            const modelConfig = availableModels.find((m) => m.id === compactEffectiveModel);
-            const contextWindow = modelConfig?.contextWindow ?? 200000;
-            const compactor = new compactor_1.SessionCompactor(this.sessionStore);
-            const result = await compactor.compact(agentId, storeChatId, sessionId, compactEffectiveModel, contextWindow, ch);
-            await this.sessionStore.updateSessionMeta(agentId, storeChatId, sessionId, {
-                loadedAtSpawn: undefined,
-                archivedCount: undefined,
-                messageCountAtSpawn: undefined,
-            }, ch);
-            await this.restartProcess(sessionId);
-            return { success: true, keptMessages: result.afterMessages, archivedMessages: result.beforeMessages - result.afterMessages };
+        let result;
+        let responseText;
+        try {
+            if (cmd === '/model') {
+                const model = this.agentConfig.claude.model;
+                const hasArg = command.trim().includes(' ');
+                result = { model };
+                responseText = hasArg
+                    ? `Current model: ${model}\n(To switch models use the model picker or the /api/v1/agents/:id/model endpoint — argument ignored.)`
+                    : `Current model: ${model}`;
+            }
+            else if (cmd === '/stop') {
+                const session = this.sessions.get(sessionId);
+                const stopped = session ? session.interrupt() : false;
+                result = { stopped };
+                responseText = stopped ? 'Session interrupted.' : 'No active session to stop.';
+            }
+            else if (cmd === '/restart') {
+                this.restartProcess(sessionId).catch(() => { });
+                result = { restarting: true };
+                responseText = 'Session is restarting.';
+            }
+            else if (cmd === '/session') {
+                const index = await this.sessionStore.listSessions(agentId, storeChatId, 'api').catch(() => null);
+                const meta = index?.sessions.find((s) => s.id === sessionId);
+                const effectiveModel = this.agentConfig.claude.model;
+                // The api append path doesn't maintain the index messageCount, so count the flat store
+                // (the real conversation) directly rather than trusting meta.messageCount.
+                const messageCount = (await this.sessionStore.loadSession(agentId, sessionId).catch(() => [])).length;
+                if (!meta) {
+                    result = { sessionId, sessionName: null, messageCount, archivedCount: 0, contextUsedPct: 0, model: effectiveModel };
+                    responseText = `Session: (unnamed)\nMessages: ${messageCount}\nContext used: 0%\nModel: ${effectiveModel}`;
+                }
+                else {
+                    const availableModels = this.gatewayConfig.gateway.models ?? exports.DEFAULT_MODELS;
+                    const modelConfig = availableModels.find((m) => m.id === effectiveModel);
+                    const contextWindow = modelConfig?.contextWindow ?? 200000;
+                    const contextUsedPct = Math.round(((meta.lastInputTokens ?? 0) / contextWindow) * 100);
+                    result = { sessionId, sessionName: meta.name, messageCount, archivedCount: meta.archivedCount ?? 0, contextUsedPct, model: effectiveModel };
+                    responseText = [
+                        `Session: ${meta.name ?? '(unnamed)'}`,
+                        `Messages: ${messageCount}${(meta.archivedCount ?? 0) > 0 ? ` (${meta.archivedCount} archived)` : ''}`,
+                        `Context used: ${contextUsedPct}%`,
+                        `Model: ${effectiveModel}`,
+                    ].join('\n');
+                }
+            }
+            else if (cmd === '/sessions') {
+                // Advertised for the api channel (BUILTIN_COMMANDS), so handle it here — mirrors the
+                // telegram /sessions list. Marks the session this command runs in as (current).
+                const index = await this.sessionStore.listSessions(agentId, storeChatId, 'api').catch(() => null);
+                const list = index?.sessions ?? [];
+                // Count each session's flat store directly — the api append path doesn't keep the
+                // index messageCount in sync.
+                const withCounts = await Promise.all(list.map(async (s) => ({
+                    id: s.id,
+                    name: s.name,
+                    messageCount: (await this.sessionStore.loadSession(agentId, s.id).catch(() => [])).length,
+                    current: s.id === sessionId,
+                })));
+                result = { sessions: withCounts, count: withCounts.length };
+                if (!withCounts.length) {
+                    responseText = 'No sessions.';
+                }
+                else {
+                    const lines = withCounts.map((s) => {
+                        const n = s.messageCount;
+                        const marker = s.current ? ' (current)' : '';
+                        return `• ${s.name ?? '(unnamed)'} — ${n} message${n === 1 ? '' : 's'}${marker}`;
+                    });
+                    responseText = `Sessions (${withCounts.length}):\n${lines.join('\n')}`;
+                }
+            }
+            else if (cmd === '/clear') {
+                const ch = 'api';
+                await this.sessionStore.clearTelegramSessionHistory(agentId, storeChatId, sessionId, ch);
+                await this.sessionStore.updateSessionMeta(agentId, storeChatId, sessionId, {
+                    totalTokensUsed: 0,
+                    lastInputTokens: 0,
+                    archivedCount: 0,
+                    loadedAtSpawn: undefined,
+                    messageCountAtSpawn: undefined,
+                }, ch);
+                const mediaPaths = this.historyDb.clearSession(dbChatId, sessionId);
+                media_store_1.MediaStore.deleteMediaFiles(this.agentsBaseDir, agentId, mediaPaths);
+                this.restartProcess(sessionId).catch(() => { });
+                result = { success: true };
+                responseText = 'Session cleared.';
+            }
+            else if (cmd === '/compact') {
+                const ch = 'api';
+                const compactEffectiveModel = this.agentConfig.claude.model;
+                const availableModels = this.gatewayConfig.gateway.models ?? exports.DEFAULT_MODELS;
+                const modelConfig = availableModels.find((m) => m.id === compactEffectiveModel);
+                const contextWindow = modelConfig?.contextWindow ?? 200000;
+                const compactor = new compactor_1.SessionCompactor(this.sessionStore);
+                const compactResult = await compactor.compact(agentId, storeChatId, sessionId, compactEffectiveModel, contextWindow, ch);
+                await this.sessionStore.updateSessionMeta(agentId, storeChatId, sessionId, {
+                    loadedAtSpawn: undefined,
+                    archivedCount: undefined,
+                    messageCountAtSpawn: undefined,
+                }, ch);
+                await this.restartProcess(sessionId);
+                result = { success: true, keptMessages: compactResult.afterMessages, archivedMessages: compactResult.beforeMessages - compactResult.afterMessages };
+                responseText = `Session compacted. Kept ${compactResult.afterMessages} messages, archived ${compactResult.beforeMessages - compactResult.afterMessages}.`;
+            }
+            else {
+                // Passed the gate but has no dispatch branch — BUILTIN_COMMANDS drifted from this
+                // table. Throw so the failure surfaces (and ends history with an assistant turn via
+                // the catch below) rather than returning an empty response.
+                throw new Error(`Unhandled command: ${cmd}`);
+            }
+        }
+        catch (err) {
+            // Ensure history always ends with an assistant turn, even when execution fails midway
+            // (e.g. /compact throws after the user row is persisted). Otherwise the trailing user
+            // row re-triggers the web's stuck-spinner condition on reload. Rethrow so the router
+            // still emits its SSE error event / REST 500.
+            const errMsg = err instanceof Error ? err.message : String(err);
+            persist('assistant', `Command failed: ${errMsg}`);
+            throw err;
         }
-        throw new Error(`Unknown command: ${command}`);
+        // Persist the human-readable response as an assistant turn so the conversation ends with
+        // an assistant message (the web's computeIsPendingResponse needs last.role !== 'user').
+        persist('assistant', responseText);
+        return { result, responseText };
     }
     async setModel(newModel) {
         // Allow any model string through — BYOK/third-party models (openrouter/* etc.)