@micsushi/agent-hotline 0.5.1

package/packages/backend/skills/agent-hotline-spoken/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: agent-hotline-spoken
+description: >
+  Formats agent responses for Agent Hotline read-aloud TTS. Triggered when the
+  user says "hotline on", "read aloud on", "start read-aloud", or "spoken mode"
+  in this session. Stays active until "hotline off" or "stop read-aloud".
+---
+
+# Agent Hotline Spoken Skill
+
+When the read-aloud skill is active, structure every response in exactly this
+layout, in this order:
+
+```text
+Spoken:
+<2 to 6 short spoken sentences>
+
+==========
+
+Displayed:
+<full normal answer>
+```
+
+## Spoken Section
+
+- Use 2 to 6 short sentences of natural spoken English.
+- Do not include code, file paths, commands, symbols, or markdown.
+- Keep one idea at a time.
+- Ask at most one question.
+- Make this section stand on its own for a listener.
+
+## Displayed Section
+
+Use this for the full visible answer: code, commands, file paths, diffs, steps,
+and detail.
+
+## Required Format
+
+- `Spoken:` sits alone on its own line.
+- `Displayed:` sits alone on its own line.
+- `==========` sits alone on its own line between the two sections.
+- Both sections are always present while the skill is active.
+
+Agent Hotline reads only the `Spoken:` section. The `Displayed:` section stays
+visible in the chat and is never spoken.

package/packages/backend/src/audio-cache-store.js

@@ -0,0 +1,246 @@
+const fs = require("fs");
+const path = require("path");
+
+const { getDefaultDataDir } = require("./settings-store");
+
+const DEFAULT_MAX_BYTES = 1024 * 1024 * 1024;
+const CACHE_DIR_NAME = "audio-cache";
+const INDEX_FILE = "index.json";
+
+function sanitize(value) {
+  return String(value || "")
+    .replace(/[^A-Za-z0-9._-]/g, "_")
+    .slice(0, 120);
+}
+
+function keyFor(itemId, engine, voice) {
+  return `${sanitize(itemId)}__${sanitize(engine)}__${sanitize(voice)}`;
+}
+
+function emptyIndex() {
+  return { totalBytes: 0, entries: {} };
+}
+
+function safeReadJson(filePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    if (parsed && typeof parsed === "object" && parsed.entries) return parsed;
+  } catch {}
+  return emptyIndex();
+}
+
+function createAudioCacheStore(options = {}) {
+  const dataDir = options.dataDir || getDefaultDataDir();
+  const cacheDir = options.cacheDir || path.join(dataDir, CACHE_DIR_NAME);
+  const indexPath = path.join(cacheDir, INDEX_FILE);
+  const staticMax = Number.isFinite(options.maxBytes) ? options.maxBytes : DEFAULT_MAX_BYTES;
+  const getMax = typeof options.getMaxBytes === "function" ? options.getMaxBytes : () => staticMax;
+  function currentMax() {
+    const value = Number(getMax());
+    return Number.isFinite(value) && value > 0 ? value : DEFAULT_MAX_BYTES;
+  }
+  const now = options.now || (() => new Date().toISOString());
+
+  let index = loadAndReconcile();
+
+  function wavPath(key) {
+    return path.join(cacheDir, `${key}.wav`);
+  }
+
+  function loadAndReconcile() {
+    const loaded = safeReadJson(indexPath);
+    const entries = {};
+    let totalBytes = 0;
+    for (const [key, entry] of Object.entries(loaded.entries || {})) {
+      if (!entry || typeof entry !== "object") continue;
+      if (!fs.existsSync(path.join(cacheDir, `${key}.wav`))) continue;
+      entries[key] = entry;
+      totalBytes += Number(entry.bytes) || 0;
+    }
+    return { totalBytes, entries };
+  }
+
+  function persist() {
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const tempFile = `${indexPath}.${process.pid}.tmp`;
+    fs.writeFileSync(tempFile, `${JSON.stringify(index, null, 2)}\n`, "utf8");
+    fs.renameSync(tempFile, indexPath);
+  }
+
+  function recomputeTotal() {
+    index.totalBytes = Object.values(index.entries).reduce(
+      (sum, entry) => sum + (Number(entry.bytes) || 0),
+      0
+    );
+  }
+
+  function evictToFit(keepKey) {
+    const cap = currentMax();
+    const ordered = Object.values(index.entries)
+      .filter((entry) => entry.key !== keepKey)
+      .sort((a, b) => String(a.lastAccessedAt).localeCompare(String(b.lastAccessedAt)));
+
+    let i = 0;
+    while (index.totalBytes > cap && i < ordered.length) {
+      const victim = ordered[i];
+      i += 1;
+      removeKey(victim.key, { persist: false });
+    }
+  }
+
+  function enforceLimit() {
+    evictToFit(null);
+    persist();
+  }
+
+  function removeKey(key, { persist: shouldPersist = true } = {}) {
+    const entry = index.entries[key];
+    if (!entry) return false;
+    try {
+      fs.rmSync(wavPath(key), { force: true });
+    } catch {}
+    delete index.entries[key];
+    recomputeTotal();
+    if (shouldPersist) persist();
+    return true;
+  }
+
+  function touch(key) {
+    const entry = index.entries[key];
+    if (!entry) return;
+    entry.lastAccessedAt = now();
+    persist();
+  }
+
+  function has(itemId, engine, voice) {
+    return Boolean(index.entries[keyFor(itemId, engine, voice)]);
+  }
+
+  function getManifest(itemId, engine, voice) {
+    const key = keyFor(itemId, engine, voice);
+    const entry = index.entries[key];
+    if (!entry) return null;
+    touch(key);
+    return {
+      sampleRate: entry.sampleRate,
+      durationSec: entry.durationSec,
+      segments: Array.isArray(entry.segments) ? entry.segments : [],
+      wordAccurate: Boolean(entry.wordAccurate)
+    };
+  }
+
+  function getAudioPath(itemId, engine, voice) {
+    const key = keyFor(itemId, engine, voice);
+    const entry = index.entries[key];
+    if (!entry) return null;
+    const filePath = wavPath(key);
+    if (!fs.existsSync(filePath)) {
+      removeKey(key);
+      return null;
+    }
+    touch(key);
+    return filePath;
+  }
+
+  function put(itemId, engine, voice, payload) {
+    const wavBuffer = payload.wavBuffer;
+    if (!Buffer.isBuffer(wavBuffer) || wavBuffer.length === 0) {
+      throw new Error("wavBuffer must be a non-empty Buffer");
+    }
+    if (wavBuffer.length > currentMax()) {
+      return null;
+    }
+
+    const key = keyFor(itemId, engine, voice);
+    fs.mkdirSync(cacheDir, { recursive: true });
+    fs.writeFileSync(wavPath(key), wavBuffer);
+
+    const timestamp = now();
+    const existing = index.entries[key];
+    index.entries[key] = {
+      key,
+      itemId: String(itemId),
+      engine: String(engine),
+      voice: String(voice),
+      bytes: wavBuffer.length,
+      sampleRate: Number(payload.sampleRate) || 24000,
+      durationSec: Number(payload.durationSec) || 0,
+      wordAccurate: Boolean(payload.wordAccurate),
+      segments: Array.isArray(payload.segments) ? payload.segments : [],
+      createdAt: existing?.createdAt || timestamp,
+      lastAccessedAt: timestamp
+    };
+
+    recomputeTotal();
+    evictToFit(key);
+    persist();
+    return JSON.parse(JSON.stringify(index.entries[key]));
+  }
+
+  function removeOne(itemId, engine, voice) {
+    if (engine && voice) {
+      return removeKey(keyFor(itemId, engine, voice)) ? 1 : 0;
+    }
+    const id = String(itemId);
+    return removeWhere((entry) => entry.itemId === id);
+  }
+
+  function removeWhere(predicate) {
+    const keys = Object.values(index.entries)
+      .filter(predicate)
+      .map((entry) => entry.key);
+    let removed = 0;
+    for (const key of keys) {
+      if (removeKey(key, { persist: false })) removed += 1;
+    }
+    if (removed > 0) persist();
+    return removed;
+  }
+
+  function removeByItemIds(itemIds) {
+    const wanted = new Set(Array.from(itemIds || []).map(String));
+    return removeWhere((entry) => wanted.has(entry.itemId));
+  }
+
+  function clearAll() {
+    const count = Object.keys(index.entries).length;
+    for (const key of Object.keys(index.entries)) {
+      removeKey(key, { persist: false });
+    }
+    index = emptyIndex();
+    persist();
+    return count;
+  }
+
+  function list() {
+    return {
+      entries: Object.values(index.entries).map((entry) => ({ ...entry })),
+      totalBytes: index.totalBytes,
+      maxBytes: currentMax()
+    };
+  }
+
+  return {
+    cacheDir,
+    get maxBytes() {
+      return currentMax();
+    },
+    keyFor,
+    has,
+    getManifest,
+    getAudioPath,
+    put,
+    removeOne,
+    removeByItemIds,
+    removeWhere,
+    clearAll,
+    enforceLimit,
+    list
+  };
+}
+
+module.exports = {
+  createAudioCacheStore,
+  DEFAULT_MAX_BYTES,
+  keyFor
+};

package/packages/backend/src/hook-command.js

@@ -0,0 +1,320 @@
+const fs = require("fs");
+const { parseHookInput, SOURCE_APPS } = require("./hook-input-parser");
+const { filterSpeakableText } = require("./speakable-filter");
+const { createSpoolStore } = require("./spool-store");
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 4777;
+const REQUEST_TIMEOUT_MS = 750;
+
+function getDefaultBaseUrl(env = process.env) {
+  if (typeof env.AGENT_HOTLINE_URL === "string" && env.AGENT_HOTLINE_URL.trim()) {
+    return trimTrailingSlash(env.AGENT_HOTLINE_URL.trim());
+  }
+
+  const port = env.AGENT_HOTLINE_PORT || env.VOICE_QUESTION_LOOP_PORT || DEFAULT_PORT;
+  return `http://${DEFAULT_HOST}:${port}`;
+}
+
+async function readStdin(stream = process.stdin) {
+  stream.setEncoding("utf8");
+
+  let input = "";
+  for await (const chunk of stream) {
+    input += chunk;
+  }
+
+  return input;
+}
+
+async function runHookCommand(options = {}) {
+  const input = typeof options.input === "string" ? options.input : await readStdin(options.stdin);
+  const baseUrl = trimTrailingSlash(options.baseUrl || getDefaultBaseUrl(options.env));
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  const timeoutMs = options.timeoutMs || REQUEST_TIMEOUT_MS;
+  const env = options.env || process.env;
+  const spoolStore =
+    options.spoolStore ||
+    createSpoolStore({ dataDir: options.dataDir || env.AGENT_HOTLINE_DATA_DIR });
+
+  function bufferOffline(item, reason, message, error) {
+    try {
+      spoolStore.append(item);
+      return recoverable(reason, `${message} Buffered offline for the next backend start.`, error);
+    } catch (spoolError) {
+      return recoverable(reason, message, error || { message: spoolError.message });
+    }
+  }
+
+  if (typeof fetchImpl !== "function") {
+    return recoverable("fetch_unavailable", "This Node runtime does not expose fetch.");
+  }
+
+  const parsed = parseHookInput(input);
+  if (!parsed.ok) {
+    return skipped(parsed.reason, parsed.message);
+  }
+
+  if (!isSupportedSource(parsed.sourceApp)) {
+    return skipped("unsupported_source", "Hook source must be Codex or Claude.");
+  }
+
+  const filtered = filterSpeakableText(parsed.assistantText);
+  if (!filtered.shouldSpeak) {
+    return skipped(filtered.reason, "No speakable text after filtering.");
+  }
+  if (filtered.source !== "spoken") {
+    return skipped("skill_not_triggered", "No Spoken section; read-aloud skill is not active.");
+  }
+
+  const enqueueBody = {
+    rawSource: parsed.assistantText,
+    speakableText: filtered.text,
+    sourceApp: parsed.sourceApp,
+    threadId: parsed.threadId,
+    threadLabel: parsed.threadLabel,
+    sessionName: resolveSessionName(parsed),
+    projectPath: parsed.projectPath,
+    projectName: parsed.projectName,
+    userMessages: parsed.userMessages
+  };
+
+  const settingsResult = await requestJson(fetchImpl, `${baseUrl}/api/settings`, {
+    method: "GET",
+    timeoutMs
+  });
+  if (!settingsResult.ok) {
+    return bufferOffline(
+      enqueueBody,
+      "backend_unavailable",
+      "Agent Hotline backend is not available.",
+      settingsResult.error
+    );
+  }
+
+  const settings = settingsResult.body && settingsResult.body.settings;
+  if (!isSourceEnabled(settings, parsed.sourceApp)) {
+    return skipped("source_disabled", `${parsed.sourceApp} hook playback is disabled.`);
+  }
+
+  const enqueueResult = await requestJson(fetchImpl, `${baseUrl}/api/queue`, {
+    method: "POST",
+    timeoutMs,
+    body: enqueueBody
+  });
+  if (!enqueueResult.ok) {
+    return bufferOffline(
+      enqueueBody,
+      "enqueue_failed",
+      "Speakable text could not be queued.",
+      enqueueResult.error
+    );
+  }
+
+  return {
+    ok: true,
+    action: "enqueued",
+    sourceApp: parsed.sourceApp,
+    reason: filtered.reason,
+    item: enqueueResult.body && enqueueResult.body.item
+  };
+}
+
+async function requestJson(fetchImpl, url, options = {}) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs || REQUEST_TIMEOUT_MS);
+
+  try {
+    const response = await fetchImpl(url, {
+      method: options.method || "GET",
+      signal: controller.signal,
+      headers: options.body ? { "Content-Type": "application/json" } : undefined,
+      body: options.body ? JSON.stringify(options.body) : undefined
+    });
+    const body = await readResponseJson(response);
+
+    if (!response.ok) {
+      return {
+        ok: false,
+        status: response.status,
+        body,
+        error: responseError(response, body)
+      };
+    }
+
+    return { ok: true, status: response.status, body };
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        name: error.name,
+        message: error.message
+      }
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function readResponseJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+function responseError(response, body) {
+  const apiError = body && body.error;
+  if (apiError && typeof apiError.message === "string") {
+    return {
+      status: response.status,
+      code: apiError.code,
+      message: apiError.message
+    };
+  }
+
+  return {
+    status: response.status,
+    message: `HTTP ${response.status}`
+  };
+}
+
+function isSupportedSource(sourceApp) {
+  return (
+    sourceApp === SOURCE_APPS.CODEX ||
+    sourceApp === SOURCE_APPS.CLAUDE ||
+    sourceApp === SOURCE_APPS.ANTIGRAVITY
+  );
+}
+
+function isSourceEnabled(settings, sourceApp) {
+  if (!settings || typeof settings !== "object") {
+    return true;
+  }
+
+  if (sourceApp === SOURCE_APPS.CODEX) {
+    return settings.codexEnabled !== false;
+  }
+
+  if (sourceApp === SOURCE_APPS.CLAUDE) {
+    return settings.claudeEnabled !== false;
+  }
+
+  if (sourceApp === SOURCE_APPS.ANTIGRAVITY) {
+    return settings.antigravityEnabled !== false;
+  }
+
+  return false;
+}
+
+function skipped(reason, message) {
+  return {
+    ok: true,
+    action: "skipped",
+    reason,
+    message
+  };
+}
+
+function recoverable(reason, message, error) {
+  return {
+    ok: true,
+    action: "recoverable_failure",
+    reason,
+    message,
+    ...(error ? { error } : {})
+  };
+}
+
+function trimTrailingSlash(value) {
+  return String(value || "").replace(/\/+$/, "");
+}
+
+function resolveSessionName(parsed) {
+  if (parsed.sessionName) {
+    return truncateName(parsed.sessionName);
+  }
+  const transcriptPath = parsed.payload && parsed.payload.transcript_path;
+  if (typeof transcriptPath === "string" && transcriptPath) {
+    return truncateName(readFirstUserMessage(transcriptPath));
+  }
+  return undefined;
+}
+
+function truncateName(name) {
+  const clean = String(name || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!clean) return undefined;
+  return clean.length > 60 ? `${clean.slice(0, 57)}...` : clean;
+}
+
+function readFirstUserMessage(transcriptPath) {
+  try {
+    const fd = fs.openSync(transcriptPath, "r");
+    try {
+      const buffer = Buffer.alloc(262144);
+      const bytes = fs.readSync(fd, buffer, 0, buffer.length, 0);
+      const text = buffer.toString("utf8", 0, bytes);
+      for (const line of text.split(/\r?\n/)) {
+        if (!line.trim()) continue;
+        let entry;
+        try {
+          entry = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (!entry || entry.type !== "user" || !entry.message || entry.message.role !== "user") {
+          continue;
+        }
+        const content = entry.message.content;
+        let candidate = "";
+        if (typeof content === "string") {
+          candidate = content;
+        } else if (Array.isArray(content)) {
+          const part = content.find((p) => p && p.type === "text" && typeof p.text === "string");
+          candidate = part ? part.text : "";
+        }
+        if (candidate.trim()) return candidate.trim();
+      }
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {}
+  return "";
+}
+
+async function main(options = {}) {
+  const env = options.env || process.env;
+  const result = await runHookCommand({
+    ...options,
+    env
+  });
+
+  if (env.AGENT_HOTLINE_HOOK_DEBUG === "1" && result.action !== "enqueued") {
+    const stderr = options.stderr || process.stderr;
+    stderr.write(`agent-hotline-hook: ${result.action} ${result.reason}\n`);
+  }
+
+  return 0;
+}
+
+if (require.main === module) {
+  main()
+    .then((exitCode) => {
+      process.exitCode = exitCode;
+    })
+    .catch(() => {
+      process.exitCode = 0;
+    });
+}
+
+module.exports = {
+  getDefaultBaseUrl,
+  isSourceEnabled,
+  main,
+  readStdin,
+  requestJson,
+  runHookCommand
+};