@micsushi/agent-hotline 0.5.2 → 1.0.0

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@micsushi/agent-hotline",
-  "version": "0.5.2",
+  "version": "1.0.0",
   "description": "Local read-aloud hooks and tray app for AI coding agents.",
   "bin": {
     "ah": "packages/backend/bin/agent-hotline.js",
     "agent-hotline": "packages/backend/bin/agent-hotline.js",
-    "agent-hotline-hook": "packages/backend/bin/agent-hotline-hook.js"
+    "agent-hotline-hook": "packages/backend/bin/agent-hotline-hook.js",
+    "agent-hotline-mcp": "packages/backend/bin/agent-hotline-mcp.js"
   },
   "files": [
     "README.md",

package/packages/backend/bin/agent-hotline-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../src/mcp-server.mjs").then(({ runStdioServer }) => runStdioServer());

package/packages/backend/package.json

@@ -7,14 +7,19 @@
   "bin": {
     "ah": "bin/agent-hotline.js",
     "agent-hotline": "bin/agent-hotline.js",
-    "agent-hotline-hook": "bin/agent-hotline-hook.js"
+    "agent-hotline-hook": "bin/agent-hotline-hook.js",
+    "agent-hotline-mcp": "bin/agent-hotline-mcp.js"
   },
   "scripts": {
     "start": "node src/server.js",
-    "test": "node --test test/*.test.js",
-    "check": "node --check src/server.js && node --check src/settings-store.js && node --check src/speech-queue-store.js && node --check src/audio-cache-store.js && node --check src/installer.js && node --check src/hook-input-parser.js && node --check src/hook-command.js && node --check src/run-command.js && node --check src/speakable-filter.js && node --check bin/agent-hotline.js && node --check bin/agent-hotline-hook.js && node --check test/settings-store.test.js && node --check test/speech-queue-store.test.js && node --check test/audio-cache-store.test.js && node --check test/audio-endpoints.test.js && node --check test/installer.test.js && node --check test/run-command.test.js && node --check test/speakable-filter.test.js && node --check test/hook-input-parser.test.js && node --check test/hook-command.test.js && node --check test/server-endpoints.test.js"
+    "test": "node --test test/*.test.js test/*.test.mjs",
+    "check": "node --check src/server.js && node --check src/settings-store.js && node --check src/speech-queue-store.js && node --check src/audio-cache-store.js && node --check src/installer.js && node --check src/hook-input-parser.js && node --check src/hook-command.js && node --check src/run-command.js && node --check src/speakable-filter.js && node --check src/mcp-server.mjs && node --check bin/agent-hotline.js && node --check bin/agent-hotline-hook.js && node --check bin/agent-hotline-mcp.js && node --check test/settings-store.test.js && node --check test/speech-queue-store.test.js && node --check test/audio-cache-store.test.js && node --check test/audio-endpoints.test.js && node --check test/installer.test.js && node --check test/run-command.test.js && node --check test/speakable-filter.test.js && node --check test/hook-input-parser.test.js && node --check test/hook-command.test.js && node --check test/server-endpoints.test.js && node --check test/mcp-server.test.mjs"
   },
   "engines": {
     "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
   }
 }

package/packages/backend/src/mcp-server.mjs

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+const require = createRequire(import.meta.url);
+const { createAudioCacheStore } = require("./audio-cache-store.js");
+const { createSettingsStore } = require("./settings-store.js");
+const { createSpeechQueueStore } = require("./speech-queue-store.js");
+
+function textResult(value) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+      }
+    ]
+  };
+}
+
+function sessionKeyOf(item) {
+  return item.sessionKey || item.threadId || `app:${item.sourceApp}`;
+}
+
+function projectKeyOf(item) {
+  if (!item.projectPath) return `direct:${item.sourceApp}`;
+  return String(item.projectPath).replace(/[\\/]/g, "").toLowerCase();
+}
+
+function projectLabelOf(item) {
+  if (!item.projectPath) return item.sourceApp || "Direct";
+  const raw = item.projectName || item.projectPath || "";
+  return (
+    String(raw)
+      .replace(/[\\/]+$/, "")
+      .split(/[\\/]/)
+      .pop() ||
+    item.sourceApp ||
+    "Direct"
+  );
+}
+
+function sessionLabelOf(item) {
+  const id = item.threadId ? item.threadId.slice(0, 8) : "";
+  if (item.sessionName && id) return `${item.sessionName} - ${id}`;
+  if (item.sessionName) return item.sessionName;
+  if (id) return id;
+  return `${item.sourceApp} - direct`;
+}
+
+function visibleItems(queueStore) {
+  return queueStore.getState().items.filter((item) => item.speakableText && !item.trashedAt);
+}
+
+function trashedItems(queueStore) {
+  return queueStore.getState().items.filter((item) => item.speakableText && item.trashedAt);
+}
+
+function compactItem(item) {
+  return {
+    id: item.id,
+    sourceApp: item.sourceApp,
+    projectKey: projectKeyOf(item),
+    projectName: projectLabelOf(item),
+    sessionKey: sessionKeyOf(item),
+    sessionName: sessionLabelOf(item),
+    threadId: item.threadId || null,
+    createdAt: item.timestamps?.createdAt || null,
+    status: item.status,
+    trashedAt: item.trashedAt || null,
+    preview: String(item.speakableText || "")
+      .replace(/\s+/g, " ")
+      .trim()
+      .slice(0, 220)
+  };
+}
+
+function groupItems(items) {
+  const projects = new Map();
+  for (const item of items) {
+    const projectKey = projectKeyOf(item);
+    if (!projects.has(projectKey)) {
+      projects.set(projectKey, {
+        key: projectKey,
+        label: projectLabelOf(item),
+        sessions: new Map(),
+        itemCount: 0
+      });
+    }
+    const project = projects.get(projectKey);
+    project.itemCount += 1;
+    const sessionKey = sessionKeyOf(item);
+    if (!project.sessions.has(sessionKey)) {
+      project.sessions.set(sessionKey, {
+        key: sessionKey,
+        label: sessionLabelOf(item),
+        itemCount: 0,
+        latestAt: ""
+      });
+    }
+    const session = project.sessions.get(sessionKey);
+    session.itemCount += 1;
+    session.latestAt = item.timestamps?.createdAt || session.latestAt;
+  }
+  return [...projects.values()].map((project) => ({
+    ...project,
+    sessions: [...project.sessions.values()]
+  }));
+}
+
+function normalize(value) {
+  return String(value || "")
+    .replace(/\s+/g, " ")
+    .toLowerCase();
+}
+
+function searchItems(items, query) {
+  const terms = normalize(query).split(/\s+/).filter(Boolean);
+  if (terms.length === 0) return [];
+  return items
+    .filter((item) => {
+      const haystack = normalize(
+        [
+          item.id,
+          item.threadId,
+          item.threadLabel,
+          item.sessionName,
+          projectLabelOf(item),
+          sessionLabelOf(item),
+          item.speakableText,
+          ...(Array.isArray(item.userMessages) ? item.userMessages : [])
+        ].join(" ")
+      );
+      return terms.every((term) => haystack.includes(term));
+    })
+    .map(compactItem);
+}
+
+function queueTargetSchema() {
+  return {
+    itemIds: z.array(z.string()).optional(),
+    projectKey: z.string().optional(),
+    sessionKey: z.string().optional(),
+    all: z.boolean().optional()
+  };
+}
+
+function applyTarget(queueStore, args, mode) {
+  if (Array.isArray(args.itemIds)) {
+    return mode === "trash"
+      ? queueStore.trashItems(args.itemIds)
+      : queueStore.restoreItems(args.itemIds);
+  }
+  if (args.projectKey) {
+    return mode === "trash"
+      ? queueStore.trashByProject(args.projectKey)
+      : queueStore.restoreByProject(args.projectKey);
+  }
+  if (args.sessionKey) {
+    return mode === "trash"
+      ? queueStore.trashBySession(args.sessionKey)
+      : queueStore.restoreBySession(args.sessionKey);
+  }
+  if (args.all === true) {
+    return mode === "trash" ? queueStore.trashAll() : queueStore.restoreAll();
+  }
+  throw new Error("Provide itemIds, projectKey, sessionKey, or all=true.");
+}
+
+function idsByProject(queueStore, projectKey) {
+  return visibleItems(queueStore)
+    .filter((item) => projectKeyOf(item) === projectKey)
+    .map((item) => item.id);
+}
+
+function idsBySession(queueStore, sessionKey) {
+  return visibleItems(queueStore)
+    .filter((item) => sessionKeyOf(item) === sessionKey)
+    .map((item) => item.id);
+}
+
+function registerAgentHotlineTools(server, { queueStore, settingsStore, audioCacheStore }) {
+  server.registerTool(
+    "get_state",
+    {
+      title: "Get Agent Hotline State",
+      description: "Return settings plus compact visible and trashed chat counts."
+    },
+    async () =>
+      textResult({
+        settings: settingsStore.load(),
+        visibleCount: visibleItems(queueStore).length,
+        trashedCount: trashedItems(queueStore).length,
+        pending: queueStore.getPending().map(compactItem),
+        current: queueStore.getCurrent() ? compactItem(queueStore.getCurrent()) : null,
+        latest: queueStore.getLatest() ? compactItem(queueStore.getLatest()) : null
+      })
+  );
+
+  server.registerTool(
+    "list_projects",
+    {
+      title: "List Projects",
+      description: "List visible Agent Hotline projects and sessions."
+    },
+    async () => textResult(groupItems(visibleItems(queueStore)))
+  );
+
+  server.registerTool(
+    "list_messages",
+    {
+      title: "List Messages",
+      description: "List visible messages, optionally scoped to a project/session.",
+      inputSchema: {
+        projectKey: z.string().optional(),
+        sessionKey: z.string().optional(),
+        limit: z.number().int().min(1).max(200).default(50)
+      }
+    },
+    async ({ projectKey, sessionKey, limit }) => {
+      let items = visibleItems(queueStore);
+      if (projectKey) items = items.filter((item) => projectKeyOf(item) === projectKey);
+      if (sessionKey) items = items.filter((item) => sessionKeyOf(item) === sessionKey);
+      return textResult(items.slice(-limit).map(compactItem));
+    }
+  );
+
+  server.registerTool(
+    "read_message",
+    {
+      title: "Read Message",
+      description: "Read one full visible or trashed message by id.",
+      inputSchema: { itemId: z.string() }
+    },
+    async ({ itemId }) => {
+      const item = queueStore.getState().items.find((entry) => entry.id === itemId);
+      if (!item) throw new Error(`Message not found: ${itemId}`);
+      return textResult({
+        ...compactItem(item),
+        speakableText: item.speakableText,
+        userMessages: item.userMessages || []
+      });
+    }
+  );
+
+  server.registerTool(
+    "search_messages",
+    {
+      title: "Search Messages",
+      description:
+        "Search visible messages by keyword, project, session, id, prompt, or spoken text.",
+      inputSchema: { query: z.string().min(1), limit: z.number().int().min(1).max(100).default(25) }
+    },
+    async ({ query, limit }) =>
+      textResult(searchItems(visibleItems(queueStore), query).slice(0, limit))
+  );
+
+  server.registerTool(
+    "list_trash",
+    {
+      title: "List Trash",
+      description: "List trashed Agent Hotline projects, sessions, and messages."
+    },
+    async () =>
+      textResult({
+        groups: groupItems(trashedItems(queueStore)),
+        messages: trashedItems(queueStore).map(compactItem)
+      })
+  );
+
+  server.registerTool(
+    "move_to_trash",
+    {
+      title: "Move Chats To Trash",
+      description: "Move messages/projects/sessions to trash and delete their saved audio.",
+      inputSchema: queueTargetSchema()
+    },
+    async (args) => {
+      const ids = applyTarget(queueStore, args, "trash");
+      const removedAudio = audioCacheStore.removeByItemIds(ids);
+      return textResult({ trashed: ids, removedAudio });
+    }
+  );
+
+  server.registerTool(
+    "restore_from_trash",
+    {
+      title: "Restore Chats From Trash",
+      description: "Restore trashed messages/projects/sessions.",
+      inputSchema: queueTargetSchema()
+    },
+    async (args) => textResult({ restored: applyTarget(queueStore, args, "restore") })
+  );
+
+  server.registerTool(
+    "list_audio_cache",
+    {
+      title: "List Audio Cache",
+      description: "List saved audio recordings."
+    },
+    async () => textResult(audioCacheStore.list())
+  );
+
+  server.registerTool(
+    "delete_audio_cache",
+    {
+      title: "Delete Audio Cache",
+      description: "Delete saved audio only, leaving chats visible.",
+      inputSchema: {
+        itemId: z.string().optional(),
+        projectKey: z.string().optional(),
+        sessionKey: z.string().optional(),
+        all: z.boolean().optional()
+      }
+    },
+    async ({ itemId, projectKey, sessionKey, all }) => {
+      let removed;
+      if (itemId) removed = audioCacheStore.removeOne(itemId);
+      else if (projectKey)
+        removed = audioCacheStore.removeByItemIds(idsByProject(queueStore, projectKey));
+      else if (sessionKey)
+        removed = audioCacheStore.removeByItemIds(idsBySession(queueStore, sessionKey));
+      else if (all === true) removed = audioCacheStore.clearAll();
+      else throw new Error("Provide itemId, projectKey, sessionKey, or all=true.");
+      return textResult({ removed });
+    }
+  );
+
+  server.registerTool(
+    "get_settings",
+    {
+      title: "Get Settings",
+      description: "Read Agent Hotline settings."
+    },
+    async () => textResult(settingsStore.load())
+  );
+
+  server.registerTool(
+    "update_settings",
+    {
+      title: "Update Settings",
+      description: "Update safe Agent Hotline settings.",
+      inputSchema: {
+        readBehavior: z.enum(["manual", "auto"]).optional(),
+        mute: z.boolean().optional(),
+        engine: z.enum(["webview", "kokoro", "kokoro-ts"]).optional(),
+        voice: z.string().optional(),
+        audioOutputDeviceId: z.string().optional(),
+        kokoroVoice: z.string().optional(),
+        rate: z.number().min(0.1).max(10).optional(),
+        volume: z.number().min(0).max(1).optional(),
+        notifyOnNewReply: z.boolean().optional(),
+        notificationOpens: z.enum(["full", "mini"]).optional(),
+        highlightSpokenText: z.boolean().optional(),
+        audioCacheLimitMb: z.number().min(10).max(100000).optional()
+      }
+    },
+    async (args) => textResult(settingsStore.update(args))
+  );
+}
+
+export async function createAgentHotlineMcpServer(options = {}) {
+  const settingsStore = options.settingsStore || createSettingsStore({ dataDir: options.dataDir });
+  const queueStore = options.queueStore || createSpeechQueueStore({ dataDir: options.dataDir });
+  const audioCacheStore =
+    options.audioCacheStore ||
+    createAudioCacheStore({
+      dataDir: options.dataDir,
+      getMaxBytes: () => Number(settingsStore.load().audioCacheLimitMb) * 1024 * 1024
+    });
+  const server = new McpServer({ name: "agent-hotline", version: "0.1.0" });
+  registerAgentHotlineTools(server, { queueStore, settingsStore, audioCacheStore });
+  return server;
+}
+
+export async function runStdioServer() {
+  const server = await createAgentHotlineMcpServer();
+  await server.connect(new StdioServerTransport());
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runStdioServer().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}

package/packages/backend/src/server.js

@@ -280,7 +280,7 @@ function sendBinary(res, status, buffer, contentType) {
 }
 
 function sessionKeyForItem(item) {
-  return item.threadId || `app:${item.sourceApp}`;
+  return item.sessionKey || item.threadId || `app:${item.sourceApp}`;
 }
 
 // Stable project identity from a (possibly inconsistently-shaped) path. Stripping
@@ -305,6 +305,7 @@ function validateSettingsPatch(patch) {
     "mute",
     "engine",
     "voice",
+    "audioOutputDeviceId",
     "kokoroVoice",
     "rate",
     "volume",
@@ -339,6 +340,9 @@ function validateSettingsPatch(patch) {
     errors.push("engine must be webview or kokoro");
   }
   if ("voice" in patch && typeof patch.voice !== "string") errors.push("voice must be string");
+  if ("audioOutputDeviceId" in patch && typeof patch.audioOutputDeviceId !== "string") {
+    errors.push("audioOutputDeviceId must be string");
+  }
   if ("kokoroVoice" in patch && typeof patch.kokoroVoice !== "string") {
     errors.push("kokoroVoice must be string");
   }
@@ -410,6 +414,51 @@ function queueState(queueStore) {
   };
 }
 
+function visibleQueueItems(queueStore) {
+  return queueStore.getState().items.filter((item) => !item.trashedAt);
+}
+
+function trashedQueueItems(queueStore) {
+  return queueStore.getState().items.filter((item) => item.trashedAt);
+}
+
+function queueItemIdsByProject(queueStore, projectKey, { trashed = false } = {}) {
+  const items = trashed ? trashedQueueItems(queueStore) : visibleQueueItems(queueStore);
+  return items.filter((item) => projectKeyForItem(item) === projectKey).map((item) => item.id);
+}
+
+function queueItemIdsBySession(queueStore, sessionKey, { trashed = false } = {}) {
+  const items = trashed ? trashedQueueItems(queueStore) : visibleQueueItems(queueStore);
+  return items.filter((item) => sessionKeyForItem(item) === sessionKey).map((item) => item.id);
+}
+
+function applyQueueTarget(queueStore, body, mode) {
+  requirePlainObject(body, "Queue target must be a JSON object");
+  if (Array.isArray(body.itemIds)) {
+    return mode === "trash"
+      ? queueStore.trashItems(body.itemIds)
+      : queueStore.restoreItems(body.itemIds);
+  }
+  if (typeof body.projectKey === "string" && body.projectKey.trim()) {
+    return mode === "trash"
+      ? queueStore.trashByProject(body.projectKey)
+      : queueStore.restoreByProject(body.projectKey);
+  }
+  if (typeof body.sessionKey === "string" && body.sessionKey.trim()) {
+    return mode === "trash"
+      ? queueStore.trashBySession(body.sessionKey)
+      : queueStore.restoreBySession(body.sessionKey);
+  }
+  if (body.all === true) {
+    return mode === "trash" ? queueStore.trashAll() : queueStore.restoreAll();
+  }
+  throw createHttpError(
+    400,
+    "invalid_request",
+    "Provide itemIds, projectKey, sessionKey, or all=true"
+  );
+}
+
 function getPathname(req) {
   return new URL(req.url, "http://127.0.0.1").pathname;
 }
@@ -422,12 +471,21 @@ function page() {
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>Agent Hotline</title>
   <style>
-    :root { color-scheme: light dark; font-family: Inter, Segoe UI, system-ui, sans-serif; }
+    :root {
+      color-scheme: light dark;
+      --font-ui: "Segoe UI Variable", "Segoe UI", system-ui, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Arial, sans-serif;
+      --type-body: 0.8125rem;
+      --type-ui: 0.875rem;
+      --type-title: 1.875rem;
+      --line-copy: 1.45;
+      font-family: var(--font-ui);
+    }
+    body { font-size: var(--type-body); }
     body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: #101418; color: #eef2f4; }
     main { width: min(860px, calc(100vw - 32px)); }
     .panel { border: 1px solid #2b343c; border-radius: 8px; padding: 24px; background: #171d22; box-shadow: 0 20px 60px rgba(0,0,0,.25); }
-    .stage { color: #8fb7ff; font-size: 14px; margin-bottom: 16px; }
-    h1 { font-size: 30px; line-height: 1.2; margin: 0 0 16px; letter-spacing: 0; }
+    .stage { color: #8fb7ff; font-size: var(--type-ui); margin-bottom: 16px; }
+    h1 { font-size: var(--type-title); line-height: 1.2; margin: 0 0 16px; letter-spacing: 0; }
     .rec { color: #c7d0d8; border-left: 3px solid #58c48d; padding-left: 12px; margin: 18px 0; }
     textarea { width: 100%; min-height: 130px; box-sizing: border-box; border-radius: 6px; border: 1px solid #34404a; background: #0f1418; color: #eef2f4; padding: 12px; font: inherit; resize: vertical; }
     .row { display: flex; flex-wrap: wrap; gap: 10px; margin-top: 14px; align-items: center; }
@@ -436,7 +494,7 @@ function page() {
     button:disabled { opacity: .5; cursor: not-allowed; }
     a { color: #9fc4ff; text-decoration: none; }
     a:hover { text-decoration: underline; }
-    .meta { color: #9ba8b2; font-size: 13px; margin-top: 16px; }
+    .meta { color: #9ba8b2; font-size: var(--type-body); margin-top: 16px; }
     .done { color: #8ee6b0; }
   </style>
 </head>
@@ -626,6 +684,7 @@ function createServer(options = {}) {
           rawSource: body.rawSource,
           speakableText: body.speakableText,
           sourceApp: body.sourceApp,
+          sessionKey: body.sessionKey,
           threadId: body.threadId,
           threadLabel: body.threadLabel,
           sessionName: body.sessionName,
@@ -670,6 +729,21 @@ function createServer(options = {}) {
         return;
       }
 
+      if (req.method === "POST" && pathname === "/api/queue/trash") {
+        const body = await readJsonBody(req);
+        const ids = applyQueueTarget(queueStore, body, "trash");
+        const removedAudio = audioCacheStore.removeByItemIds(ids);
+        sendJson(res, 200, { trashed: ids, removedAudio, queue: queueState(queueStore) });
+        return;
+      }
+
+      if (req.method === "POST" && pathname === "/api/queue/restore") {
+        const body = await readJsonBody(req);
+        const ids = applyQueueTarget(queueStore, body, "restore");
+        sendJson(res, 200, { restored: ids, queue: queueState(queueStore) });
+        return;
+      }
+
       const replayMatch = pathname.match(/^\/api\/queue\/([^/]+)\/replay$/);
       if (req.method === "POST" && replayMatch) {
         const item = queueStore.replayItem(decodeURIComponent(replayMatch[1]));
@@ -728,33 +802,36 @@ function createServer(options = {}) {
 
       if (req.method === "GET" && pathname === "/api/audio-cache") {
         const { entries, totalBytes, maxBytes } = audioCacheStore.list();
-        const itemsById = new Map(queueStore.getState().items.map((item) => [item.id, item]));
-        const enriched = entries.map((entry) => {
+        const itemsById = new Map(visibleQueueItems(queueStore).map((item) => [item.id, item]));
+        const enriched = entries.flatMap((entry) => {
           const item = itemsById.get(entry.itemId);
-          return {
-            itemId: entry.itemId,
-            engine: entry.engine,
-            voice: entry.voice,
-            bytes: entry.bytes,
-            durationSec: entry.durationSec,
-            wordAccurate: entry.wordAccurate,
-            createdAt: entry.createdAt,
-            lastAccessedAt: entry.lastAccessedAt,
-            sourceApp: item ? item.sourceApp : null,
-            threadId: item ? item.threadId || null : null,
-            sessionName: item ? item.sessionName || item.threadLabel || null : null,
-            sessionKey: item ? sessionKeyForItem(item) : "app:unknown",
-            projectPath: item ? item.projectPath || null : null,
-            projectName: item ? item.projectName || null : null,
-            projectKey: item ? projectKeyForItem(item) : "direct:unknown",
-            itemCreatedAt: item ? item.timestamps && item.timestamps.createdAt : null,
-            preview: item
-              ? String(item.speakableText || "")
-                  .replace(/\s+/g, " ")
-                  .trim()
-                  .slice(0, 80)
-              : ""
-          };
+          if (!item) return [];
+          return [
+            {
+              itemId: entry.itemId,
+              engine: entry.engine,
+              voice: entry.voice,
+              bytes: entry.bytes,
+              durationSec: entry.durationSec,
+              wordAccurate: entry.wordAccurate,
+              createdAt: entry.createdAt,
+              lastAccessedAt: entry.lastAccessedAt,
+              sourceApp: item.sourceApp,
+              threadId: item.threadId || null,
+              sessionName: item.sessionName || item.threadLabel || null,
+              sessionKey: sessionKeyForItem(item),
+              projectPath: item.projectPath || null,
+              projectName: item.projectName || null,
+              projectKey: projectKeyForItem(item),
+              itemCreatedAt: item.timestamps && item.timestamps.createdAt,
+              preview: item
+                ? String(item.speakableText || "")
+                    .replace(/\s+/g, " ")
+                    .trim()
+                    .slice(0, 80)
+                : ""
+            }
+          ];
         });
         sendJson(res, 200, { entries: enriched, totalBytes, maxBytes });
         return;
@@ -777,19 +854,13 @@ function createServer(options = {}) {
         }
         const session = query.get("session");
         if (session) {
-          const ids = queueStore
-            .getState()
-            .items.filter((item) => sessionKeyForItem(item) === session)
-            .map((item) => item.id);
+          const ids = queueItemIdsBySession(queueStore, session);
           sendJson(res, 200, { removed: audioCacheStore.removeByItemIds(ids) });
           return;
         }
         const project = query.get("project");
         if (project) {
-          const ids = queueStore
-            .getState()
-            .items.filter((item) => projectKeyForItem(item) === project)
-            .map((item) => item.id);
+          const ids = queueItemIdsByProject(queueStore, project);
           sendJson(res, 200, { removed: audioCacheStore.removeByItemIds(ids) });
           return;
         }

package/packages/backend/src/settings-store.js

@@ -14,6 +14,7 @@ const DEFAULT_SETTINGS = Object.freeze({
   mute: false,
   engine: "webview",
   voice: "",
+  audioOutputDeviceId: "",
   kokoroVoice: "af_heart",
   rate: 0.92,
   volume: 1,
@@ -90,6 +91,7 @@ function normalizeSettings(input) {
     mute: booleanOrDefault(source.mute, defaults.mute),
     engine: TTS_ENGINES.has(source.engine) ? source.engine : defaults.engine,
     voice: stringOrDefault(source.voice, defaults.voice),
+    audioOutputDeviceId: stringOrDefault(source.audioOutputDeviceId, defaults.audioOutputDeviceId),
     kokoroVoice: stringOrDefault(source.kokoroVoice, defaults.kokoroVoice),
     rate: numberInRangeOrDefault(source.rate, defaults.rate, 0.1, 10),
     volume: numberInRangeOrDefault(source.volume, defaults.volume, 0, 1),

package/packages/backend/src/speech-queue-store.js

@@ -144,6 +144,46 @@ function createSpeechQueueStore(options = {}) {
     return value.map((entry) => (typeof entry === "string" ? entry.trim() : "")).filter(Boolean);
   }
 
+  function isVisible(item) {
+    return !item.trashedAt;
+  }
+
+  function sessionKeyForItem(item) {
+    return item.sessionKey || item.threadId || `app:${item.sourceApp}`;
+  }
+
+  function projectKeyForItem(item) {
+    if (!item.projectPath) return `direct:${item.sourceApp}`;
+    return String(item.projectPath).replace(/[\\/]/g, "").toLowerCase();
+  }
+
+  function trashMatching(predicate) {
+    const timestamp = now();
+    const ids = [];
+    for (const item of state.items) {
+      if (item.trashedAt || !predicate(item)) continue;
+      item.trashedAt = timestamp;
+      touch(item, timestamp);
+      ids.push(item.id);
+    }
+    if (ids.length) persist();
+    return ids;
+  }
+
+  function restoreMatching(predicate) {
+    const timestamp = now();
+    const ids = [];
+    for (const item of state.items) {
+      if (!item.trashedAt || !predicate(item)) continue;
+      delete item.trashedAt;
+      item.timestamps.restoredAt = timestamp;
+      touch(item, timestamp);
+      ids.push(item.id);
+    }
+    if (ids.length) persist();
+    return ids;
+  }
+
   function enqueue(input) {
     const timestamp = now();
     const item = {
@@ -160,6 +200,8 @@ function createSpeechQueueStore(options = {}) {
 
     const threadId = optionalString(input.threadId);
     if (threadId) item.threadId = threadId;
+    const sessionKey = optionalString(input.sessionKey);
+    if (sessionKey) item.sessionKey = sessionKey;
     const threadLabel = optionalString(input.threadLabel);
     if (threadLabel) item.threadLabel = threadLabel;
     const sessionName = optionalString(input.sessionName);
@@ -181,16 +223,17 @@ function createSpeechQueueStore(options = {}) {
   }
 
   function getPending() {
-    return clone(state.items.filter((item) => item.status === "pending"));
+    return clone(state.items.filter((item) => isVisible(item) && item.status === "pending"));
   }
 
   function getCurrent() {
-    const current = state.items.find((item) => item.status === "playing") || null;
+    const current =
+      state.items.find((item) => isVisible(item) && item.status === "playing") || null;
     return current ? clone(current) : null;
   }
 
   function getLatest() {
-    const latest = state.items[state.items.length - 1] || null;
+    const latest = [...state.items].reverse().find(isVisible) || null;
     return latest ? clone(latest) : null;
   }
 
@@ -249,6 +292,7 @@ function createSpeechQueueStore(options = {}) {
       }
     };
     if (source.threadId) item.threadId = source.threadId;
+    if (source.sessionKey) item.sessionKey = source.sessionKey;
     if (source.threadLabel) item.threadLabel = source.threadLabel;
     if (source.sessionName) item.sessionName = source.sessionName;
     if (source.projectPath) item.projectPath = source.projectPath;
@@ -265,18 +309,52 @@ function createSpeechQueueStore(options = {}) {
   function replayLatest() {
     const latest = [...state.items]
       .reverse()
-      .find((item) => item.speakableText && item.status !== "skipped");
+      .find((item) => isVisible(item) && item.speakableText && item.status !== "skipped");
     return latest ? pushReplay(latest) : null;
   }
 
   function replayItem(id) {
     const source = findItem(id);
-    if (!source || !source.speakableText) {
+    if (!source || source.trashedAt || !source.speakableText) {
       return null;
     }
     return pushReplay(source);
   }
 
+  function trashItems(ids) {
+    const idSet = new Set((Array.isArray(ids) ? ids : []).filter((id) => typeof id === "string"));
+    return trashMatching((item) => idSet.has(item.id));
+  }
+
+  function trashByProject(projectKey) {
+    return trashMatching((item) => projectKeyForItem(item) === projectKey);
+  }
+
+  function trashBySession(sessionKey) {
+    return trashMatching((item) => sessionKeyForItem(item) === sessionKey);
+  }
+
+  function trashAll() {
+    return trashMatching(() => true);
+  }
+
+  function restoreItems(ids) {
+    const idSet = new Set((Array.isArray(ids) ? ids : []).filter((id) => typeof id === "string"));
+    return restoreMatching((item) => idSet.has(item.id));
+  }
+
+  function restoreByProject(projectKey) {
+    return restoreMatching((item) => projectKeyForItem(item) === projectKey);
+  }
+
+  function restoreBySession(sessionKey) {
+    return restoreMatching((item) => sessionKeyForItem(item) === sessionKey);
+  }
+
+  function restoreAll() {
+    return restoreMatching(() => true);
+  }
+
   function clearQueue() {
     state = { items: [] };
     persist();
@@ -298,6 +376,14 @@ function createSpeechQueueStore(options = {}) {
     markSkipped,
     replayLatest,
     replayItem,
+    trashItems,
+    trashByProject,
+    trashBySession,
+    trashAll,
+    restoreItems,
+    restoreByProject,
+    restoreBySession,
+    restoreAll,
     clearQueue,
     getState
   };
@@ -313,7 +399,8 @@ function isValidPersistedItem(item) {
     STATUSES.has(item.status) &&
     item.timestamps &&
     typeof item.timestamps.createdAt === "string" &&
-    typeof item.timestamps.updatedAt === "string"
+    typeof item.timestamps.updatedAt === "string" &&
+    (!("trashedAt" in item) || typeof item.trashedAt === "string")
   );
 }