pi-web-voice 0.1.0

package/lib/context.cjs

@@ -0,0 +1,312 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+/**
+ * Recognition vocabulary derived from what you have actually been talking
+ * about, instead of a list you have to maintain by hand.
+ *
+ * pi stores every session as JSONL under
+ *   <agent dir>/sessions/<encoded cwd>/<timestamp>_<session id>.jsonl
+ * so the session id from the browser is enough to find the current
+ * conversation, and its sibling files are that project's history.
+ *
+ * Only user and assistant prose is read. Thinking blocks, tool arguments and
+ * tool results are skipped: they are noisy, and they are where secrets live.
+ */
+
+const CACHE_TTL_MS = 20_000;
+const cache = new Map();
+
+function agentDir() {
+  return process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+}
+
+/** Locates the JSONL file for a session id and the project it belongs to. */
+function resolveSession(sessionId) {
+  if (!/^[\w-]{6,}$/.test(sessionId || "")) return null;
+  const root = path.join(agentDir(), "sessions");
+  let projects;
+  try {
+    projects = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const project of projects) {
+    if (!project.isDirectory()) continue;
+    const dir = path.join(root, project.name);
+    let files;
+    try {
+      files = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    const match = files.find((name) => name.endsWith(`${sessionId}.jsonl`));
+    if (match) return { file: path.join(dir, match), dir };
+  }
+  return null;
+}
+
+/**
+ * Locates a project's session directory from its working directory.
+ *
+ * The directory name is an encoding of the path, but rather than depend on
+ * that encoding this reads the `cwd` recorded in the first line of each
+ * session file, which is part of the on-disk session format.
+ */
+let projectIndex = { expires: 0, byCwd: new Map() };
+
+function resolveProject(cwd) {
+  if (!cwd) return null;
+  const now = Date.now();
+  if (projectIndex.expires <= now) {
+    const byCwd = new Map();
+    const root = path.join(agentDir(), "sessions");
+    let projects = [];
+    try {
+      projects = fs.readdirSync(root, { withFileTypes: true });
+    } catch {
+      /* no sessions yet */
+    }
+    for (const project of projects) {
+      if (!project.isDirectory()) continue;
+      const dir = path.join(root, project.name);
+      try {
+        const newest = fs
+          .readdirSync(dir)
+          .filter((name) => name.endsWith(".jsonl"))
+          .sort()
+          .pop();
+        if (!newest) continue;
+        const header = JSON.parse(readTail(path.join(dir, newest), 4096).split("\n")[0] || "{}");
+        // The tail may start mid-file, so fall back to reading the head.
+        const recorded = header.cwd ?? readHeaderCwd(path.join(dir, newest));
+        if (recorded) byCwd.set(recorded, dir);
+      } catch {
+        /* skip unreadable projects */
+      }
+    }
+    projectIndex = { expires: now + 60_000, byCwd };
+  }
+  const dir = projectIndex.byCwd.get(cwd);
+  return dir ? { dir, file: null } : null;
+}
+
+function readHeaderCwd(file) {
+  try {
+    const buffer = Buffer.alloc(512);
+    const handle = fs.openSync(file, "r");
+    try {
+      fs.readSync(handle, buffer, 0, 512, 0);
+    } finally {
+      fs.closeSync(handle);
+    }
+    const line = buffer.toString("utf8").split("\n")[0];
+    return JSON.parse(line).cwd ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Reads the last `maxBytes` of a file, dropping the partial first line. */
+function readTail(file, maxBytes) {
+  let handle;
+  try {
+    const { size } = fs.statSync(file);
+    const start = Math.max(0, size - maxBytes);
+    const length = size - start;
+    if (length <= 0) return "";
+    const buffer = Buffer.alloc(length);
+    handle = fs.openSync(file, "r");
+    fs.readSync(handle, buffer, 0, length, start);
+    const text = buffer.toString("utf8");
+    return start === 0 ? text : text.slice(text.indexOf("\n") + 1);
+  } catch {
+    return "";
+  } finally {
+    if (handle !== undefined) fs.closeSync(handle);
+  }
+}
+
+// ── candidate extraction ───────────────────────────────────────────────────
+
+// Shapes a speech model tends to get wrong and a plain dictionary will not fix.
+const PATTERNS = [
+  /`([^`\n]{2,40})`/g, // `inline code`
+  /\b([A-Za-z][a-z0-9]*(?:[A-Z][a-z0-9]+)+)\b/g, // camelCase, PascalCase
+  /\b([A-Za-z][A-Za-z0-9]*(?:[-_][A-Za-z0-9]+)+)\b/g, // kebab-case, snake_case
+  /\b([A-Za-z][\w-]*\.(?:[a-z]{2,5}))\b/g, // package.json, hook.cjs
+  /\b([\w.-]+\/[\w./-]+)\b/g, // spec/lock.yml, docs/probing.md
+  /\b([A-Z]{3,8})\b/g, // MCP, USWDS, SSE
+];
+
+// Ordinary words that happen to be written in caps or wrapped in backticks.
+// Boosting them wastes a slot; a speech model already gets them right.
+const STOPWORDS = new Set([
+  "AND", "THE", "FOR", "NOT", "YOU", "ALL", "ANY", "CAN", "GET", "SET", "NEW",
+  "USE", "ADD", "RUN", "ONE", "TWO", "YES", "WILL", "MUST", "MAY", "SHOULD",
+  "NOTE", "TODO", "WARNING", "REQUIRED", "OPTIONAL", "DEFINED", "RECOMMENDED",
+  "HTTP", "HTTPS", "JSON", "HTML", "TEXT", "NULL", "TRUE", "FALSE",
+]);
+
+/**
+ * Only terms with a distinctive written form are worth boosting: mixed case,
+ * a separator, a digit, or an acronym. A plain lowercase word like "host" adds
+ * nothing and crowds out the vocabulary budget.
+ */
+function hasShape(term) {
+  return (
+    /[a-z][A-Z]/.test(term) ||
+    /[-_./]/.test(term) ||
+    /^[A-Z]{3,8}$/.test(term) ||
+    /\d/.test(term)
+  );
+}
+
+/**
+ * Conservative secret filter. Anything that looks like a credential is dropped
+ * before it can reach a speech provider.
+ */
+function looksLikeSecret(term) {
+  if (term.includes("@") || term.includes("://")) return true;
+  if (/^(sk|ghp|gho|ghs|github_pat|xox[abprs]|AKIA|ASIA|AIza|glpat|dop_v1)[-_]/i.test(term)) return true;
+  if (/^[0-9a-f]{16,}$/i.test(term)) return true; // hex digest
+  if (/^[A-Za-z0-9+/]{24,}={0,2}$/.test(term) && /\d/.test(term)) return true; // base64-ish
+  // Long, separator-free, mixed letters and digits: almost always a token.
+  if (term.length >= 24 && /[A-Za-z]/.test(term) && /\d/.test(term) && !/[-_./]/.test(term)) return true;
+  return false;
+}
+
+function acceptable(term) {
+  if (term.length < 3 || term.length > 40) return false;
+  if (STOPWORDS.has(term.toUpperCase())) return false;
+  if (/^\d+$/.test(term)) return false;
+  if (!/[A-Za-z]/.test(term)) return false;
+  // Single words only. A phrase list counts words, not entries, so a
+  // two-word entry silently costs two slots out of a very small budget —
+  // and multi-word candidates are mostly backtick spans of shell anyway.
+  if (/\s/.test(term)) return false;
+  if (/[{}"'|$<>`]/.test(term)) return false;
+  if (!hasShape(term)) return false;
+  if (looksLikeSecret(term)) return false;
+  return true;
+}
+
+function harvest(text, weight, scores) {
+  for (const pattern of PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const term = match[1].trim().replace(/[.,;:)]+$/, "");
+      if (!acceptable(term)) continue;
+      scores.set(term, (scores.get(term) ?? 0) + weight);
+
+      // "spec/lock.yml" is rarely spoken whole; the basename usually is.
+      if (term.includes("/")) {
+        const base = term.slice(term.lastIndexOf("/") + 1);
+        if (acceptable(base)) scores.set(base, (scores.get(base) ?? 0) + weight * 0.5);
+      }
+    }
+  }
+}
+
+/** Pulls prose out of one session file and scores the terms inside it. */
+function scoreSession(file, weight, scores, maxBytes) {
+  const messages = [];
+  for (const line of readTail(file, maxBytes).split("\n")) {
+    if (!line.startsWith("{")) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry.type !== "message") continue;
+
+    const role = entry.message?.role;
+    if (role !== "user" && role !== "assistant") continue;
+
+    const content = entry.message?.content;
+    const texts =
+      typeof content === "string"
+        ? [content]
+        : Array.isArray(content)
+          ? content.filter((block) => block?.type === "text" && typeof block.text === "string").map((block) => block.text)
+          : [];
+    if (texts.length > 0) messages.push({ role, texts });
+  }
+
+  // Frequency across the whole conversation, not recency. Recency was tried
+  // and measured worse: a conversation that drifts onto some side topic for a
+  // few turns would evict the project's durable vocabulary from the very
+  // small budget a phrase list has.
+  for (const message of messages) {
+    // What you said yourself is the strongest signal for what you will say next.
+    const roleWeight = weight * (message.role === "user" ? 1.5 : 1);
+    for (const text of message.texts) harvest(text, roleWeight, scores);
+  }
+}
+
+function recentProjectSessions(dir, currentFile, limit) {
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((name) => name.endsWith(".jsonl"))
+      .map((name) => path.join(dir, name))
+      .filter((file) => file !== currentFile)
+      .map((file) => ({ file, mtime: fs.statSync(file).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime)
+      .slice(0, limit)
+      .map((entry) => entry.file);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Returns the ranked vocabulary for a request, mined from the conversation and
+ * capped at `limit`.
+ *
+ * `sessionId` pins it to the exact conversation the tab is showing. `cwd` is
+ * the fallback for a session that does not exist yet, where the project's
+ * earlier conversations are still the right vocabulary.
+ */
+function collectTerms(sessionId, cwd, config, limit) {
+  const key = `${sessionId || ""}|${cwd || ""}`;
+  const cached = cache.get(key);
+  const now = Date.now();
+
+  if (cached && cached.expires > now) return cached.terms.slice(0, limit);
+
+  const found = resolveSession(sessionId) ?? resolveProject(cwd);
+  if (!found) return [];
+
+  const scores = new Map();
+  // The conversation you are in outweighs the project's older ones, and when
+  // there is no conversation yet the project's history is all there is.
+  if (found.file) scoreSession(found.file, 3, scores, config.context.bytes);
+  for (const file of recentProjectSessions(found.dir, found.file, config.context.sessions)) {
+    scoreSession(file, 1, scores, Math.min(config.context.bytes, 128 * 1024));
+  }
+
+  const mined = [...scores.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([term]) => term)
+    .slice(0, config.context.maxTerms);
+
+  cache.set(key, { expires: now + CACHE_TTL_MS, terms: mined });
+  return mined.slice(0, limit);
+}
+
+module.exports = {
+  collectTerms,
+  resolveSession,
+  resolveProject,
+  looksLikeSecret,
+  __cache: cache,
+  __resetIndex: () => {
+    projectIndex = { expires: 0, byCwd: new Map() };
+  },
+};

package/lib/doctor.cjs

@@ -0,0 +1,126 @@
+"use strict";
+
+const fs = require("node:fs");
+const { loadConfig, ENV_FILE } = require("./config.cjs");
+const { transcribe, termBudget } = require("./providers.cjs");
+const { collectTerms } = require("./context.cjs");
+
+/**
+ * Preflight for the configured speech backend.
+ *
+ *   pi-web-voice doctor [recording.wav]
+ *
+ * With no file it sends a one-second tone. The transcript will be empty, which
+ * is expected: the point is to prove that the key, region, endpoint and model
+ * name are right before you go looking for a microphone bug that isn't there.
+ */
+
+function toneWav(seconds = 1, sampleRate = 16000) {
+  const samples = seconds * sampleRate;
+  const buffer = Buffer.alloc(44 + samples * 2);
+  buffer.write("RIFF", 0);
+  buffer.writeUInt32LE(36 + samples * 2, 4);
+  buffer.write("WAVEfmt ", 8);
+  buffer.writeUInt32LE(16, 16);
+  buffer.writeUInt16LE(1, 20);
+  buffer.writeUInt16LE(1, 22);
+  buffer.writeUInt32LE(sampleRate, 24);
+  buffer.writeUInt32LE(sampleRate * 2, 28);
+  buffer.writeUInt16LE(2, 32);
+  buffer.writeUInt16LE(16, 34);
+  buffer.write("data", 36);
+  buffer.writeUInt32LE(samples * 2, 40);
+  for (let i = 0; i < samples; i += 1) {
+    buffer.writeInt16LE(Math.round(3000 * Math.sin((2 * Math.PI * 440 * i) / sampleRate)), 44 + i * 2);
+  }
+  return buffer;
+}
+
+function mask(value) {
+  if (!value) return "(missing)";
+  return value.length <= 8 ? "***" : `${value.slice(0, 4)}…${value.slice(-2)}`;
+}
+
+function describe(config) {
+  switch (config.provider) {
+    case "azure-speech":
+      return [
+        ["endpoint", config.azureSpeech.endpoint || "(missing)"],
+        ["key", mask(config.azureSpeech.key)],
+        ["model", config.azureSpeech.model],
+      ];
+    case "azure-openai":
+      return [
+        ["endpoint", config.azureOpenAI.endpoint || "(missing)"],
+        ["key", mask(config.azureOpenAI.key)],
+        ["deployment", config.azureOpenAI.deployment],
+      ];
+    case "openai":
+      return [
+        ["base url", config.openai.baseUrl],
+        ["key", mask(config.openai.key)],
+        ["model", config.openai.model],
+      ];
+    default:
+      return [];
+  }
+}
+
+/** Turns provider failures into the thing that is actually wrong. */
+function diagnose(message) {
+  if (/\b401\b|Unauthorized|Access denied/i.test(message)) {
+    return "the key is wrong, or it belongs to a different resource";
+  }
+  if (/\b403\b/.test(message)) return "the key is valid but not allowed to call this operation";
+  if (/\b404\b/.test(message)) {
+    return "endpoint or deployment not found — check the resource name, and that the region offers this model";
+  }
+  if (/\b400\b/.test(message)) {
+    return "the request was rejected — usually a model name the region does not serve, or an unsupported audio format";
+  }
+  if (/\b429\b/.test(message)) return "rate limited — the credentials work, try again shortly";
+  if (/ENOTFOUND|EAI_AGAIN|fetch failed/i.test(message)) return "cannot reach the endpoint — check the URL and your network";
+  if (/aborted/i.test(message)) return "timed out";
+  return "";
+}
+
+async function doctor(argv) {
+  const config = loadConfig();
+  const file = argv[0];
+
+  console.log(`provider   ${config.provider}`);
+  console.log(`env file   ${config.envFile || `(none at ${ENV_FILE})`}`);
+  for (const [label, value] of describe(config)) {
+    console.log(`${label.padEnd(11)}${value}`);
+  }
+
+  const cwd = process.cwd();
+  const limit = Math.min(config.context.maxTerms, termBudget(config.provider));
+  const terms = collectTerms("", cwd, config, limit);
+  console.log(`context    ${terms.length} terms`);
+  if (terms.length > 0) console.log(`           ${terms.slice(0, 12).join(", ")}${terms.length > 12 ? " …" : ""}`);
+
+  const audio = file ? fs.readFileSync(file) : toneWav();
+  console.log(`audio      ${file ?? "generated 1s tone"} (${audio.length} bytes)`);
+
+  const started = Date.now();
+  try {
+    const text = await transcribe(audio, config, terms);
+    const ms = Date.now() - started;
+    console.log(`\nok         ${ms} ms`);
+    console.log(`transcript ${text ? JSON.stringify(text) : "(empty)"}`);
+    if (!text && !file) {
+      console.log("\nAn empty transcript from a tone is expected. Credentials, region and\nmodel are working. Pass a real recording to check accuracy.");
+    }
+    return 0;
+  } catch (error) {
+    const message = error.message ?? String(error);
+    console.error(`\nfailed     ${Date.now() - started} ms`);
+    console.error(`           ${message.slice(0, 400)}`);
+    const hint = diagnose(message);
+    if (hint) console.error(`\nlikely     ${hint}`);
+    return 1;
+  }
+}
+
+module.exports = { doctor, toneWav };

package/lib/patch.cjs

@@ -0,0 +1,204 @@
+"use strict";
+
+const http = require("node:http");
+const { StringDecoder } = require("node:string_decoder");
+
+/**
+ * Attaches to every HTTP server in this process without touching pi-web.
+ *
+ * `http.Server.prototype.emit` is patched rather than `http.createServer`,
+ * because that catches both `createServer(handler)` and `server.on("request")`
+ * styles regardless of how the framework wires things up.
+ */
+
+// Give up buffering an HTML response after this much text and flush it
+// unmodified, so a pathological response can never be held in memory.
+const MAX_BUFFERED_HTML = 1024 * 1024;
+
+function install({ prefix, tag, handleRoute, onError = () => {}, onListen = () => {} }) {
+  const proto = http.Server.prototype;
+  if (proto.__piWebVoicePatched) return;
+  proto.__piWebVoicePatched = true;
+
+  // pi-web's launcher spawns `next start` as a child, so the hook is loaded in
+  // both processes. Only the one that actually listens is interesting.
+  const originalListen = proto.listen;
+  let announced = false;
+  proto.listen = function listen(...args) {
+    if (!announced) {
+      announced = true;
+      try {
+        onListen();
+      } catch (error) {
+        onError(error);
+      }
+    }
+    return originalListen.apply(this, args);
+  };
+
+  const originalEmit = proto.emit;
+
+  proto.emit = function emit(event, ...args) {
+    if (event === "request") {
+      const [req, res] = args;
+      try {
+        if (typeof req?.url === "string" && req.url.startsWith(`${prefix}/`)) {
+          Promise.resolve(handleRoute(req, res)).catch((error) => {
+            onError(error);
+            if (!res.headersSent) res.writeHead(500, { "content-type": "text/plain" });
+            res.end("pi-web-voice route failed");
+          });
+          return true; // handled here; upstream listeners never see it
+        }
+
+        // Identity encoding keeps HTML greppable. Loopback traffic, so the
+        // extra bytes cost nothing, and the browser still gets compression
+        // from any real proxy sitting in front.
+        delete req.headers["accept-encoding"];
+
+        injectIntoHtml(res, tag, onError);
+      } catch (error) {
+        onError(error);
+      }
+    }
+    return originalEmit.apply(this, [event, ...args]);
+  };
+}
+
+/**
+ * Wraps a response so that the first `</head>` (or `<body>`) in an HTML body
+ * gains one script tag. Non-HTML responses — SSE, JSON, static assets — are
+ * passed straight through untouched and unbuffered.
+ */
+function injectIntoHtml(res, tag, onError) {
+  const originalWriteHead = res.writeHead;
+  const originalWrite = res.write;
+  const originalEnd = res.end;
+
+  // unknown → not yet classified, html → buffering, plain → pass through,
+  // done → already injected or gave up
+  let mode = "unknown";
+  let buffered = "";
+  let decoder = null;
+
+  function headerValue(headers, name) {
+    if (!headers || Array.isArray(headers)) return undefined;
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === name) return headers[key];
+    }
+    return undefined;
+  }
+
+  function dropHeader(headers, name) {
+    if (!headers || Array.isArray(headers)) return;
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === name) delete headers[key];
+    }
+  }
+
+  function classify(headersFromWriteHead) {
+    if (mode !== "unknown") return mode;
+    const contentType =
+      headerValue(headersFromWriteHead, "content-type") ?? res.getHeader("content-type");
+    mode = typeof contentType === "string" && /text\/html/i.test(contentType) ? "html" : "plain";
+    if (mode === "html") {
+      // The body grows by the tag, and streamed HTML has no length anyway.
+      res.removeHeader("content-length");
+      dropHeader(headersFromWriteHead, "content-length");
+    }
+    return mode;
+  }
+
+  function asText(chunk) {
+    if (chunk === null || chunk === undefined) return "";
+    if (typeof chunk === "string") return chunk;
+    if (!Buffer.isBuffer(chunk)) return String(chunk);
+    // A decoder keeps multi-byte characters intact across chunk boundaries.
+    decoder ??= new StringDecoder("utf8");
+    return decoder.write(chunk);
+  }
+
+  function withTag(html) {
+    const head = html.toLowerCase().indexOf("</head>");
+    if (head >= 0) return html.slice(0, head) + tag + html.slice(head);
+    const body = /<body[^>]*>/i.exec(html);
+    if (body) {
+      const at = body.index + body[0].length;
+      return html.slice(0, at) + tag + html.slice(at);
+    }
+    return null;
+  }
+
+  res.writeHead = function writeHead(status, reasonOrHeaders, maybeHeaders) {
+    try {
+      const headers =
+        reasonOrHeaders && typeof reasonOrHeaders === "object" ? reasonOrHeaders : maybeHeaders;
+      classify(headers);
+    } catch (error) {
+      onError(error);
+      mode = "plain";
+    }
+    return originalWriteHead.apply(res, arguments);
+  };
+
+  res.write = function write(chunk, encoding, callback) {
+    if (typeof encoding === "function") {
+      callback = encoding;
+      encoding = undefined;
+    }
+    try {
+      if (classify() !== "html") return originalWrite.call(res, chunk, encoding, callback);
+
+      buffered += asText(chunk);
+
+      const injected = withTag(buffered);
+      if (injected !== null) {
+        mode = "done";
+        buffered = "";
+        return originalWrite.call(res, injected, "utf8", callback);
+      }
+
+      if (buffered.length > MAX_BUFFERED_HTML) {
+        mode = "done";
+        const flush = buffered;
+        buffered = "";
+        return originalWrite.call(res, flush, "utf8", callback);
+      }
+
+      if (callback) process.nextTick(callback);
+      return true;
+    } catch (error) {
+      onError(error);
+      mode = "done";
+      return originalWrite.call(res, chunk, encoding, callback);
+    }
+  };
+
+  res.end = function end(chunk, encoding, callback) {
+    if (typeof chunk === "function") {
+      callback = chunk;
+      chunk = undefined;
+      encoding = undefined;
+    } else if (typeof encoding === "function") {
+      callback = encoding;
+      encoding = undefined;
+    }
+    try {
+      if (classify() !== "html" || (mode === "done" && !buffered)) {
+        return originalEnd.call(res, chunk, encoding, callback);
+      }
+
+      const tail = buffered + asText(chunk) + (decoder ? decoder.end() : "");
+      buffered = "";
+      mode = "done";
+      // Last resort: a script appended after the markup still executes.
+      const out = withTag(tail) ?? tail + tag;
+      return originalEnd.call(res, out, "utf8", callback);
+    } catch (error) {
+      onError(error);
+      return originalEnd.call(res, chunk, encoding, callback);
+    }
+  };
+}
+
+module.exports = { install };