privateer-agent 0.12.5 → 0.12.6

package/README.md

@@ -125,6 +125,10 @@ silently. The moat is swappable; the floor under it holds.
   shots stay continuous, cut them together, then score and narrate the result. Generated media
   is handed straight back as files on your machine; none of it is stored in our cloud. See
   [docs/media-generation.md](docs/media-generation.md).
+- **Talk to it.** `/speak on` reads answers aloud as they're written; **ctrl+x** is push-to-talk
+  and the mic closes when you stop talking. Your OS voice by default — nothing leaves the
+  machine — or your account's confidential-compute TTS/STT once you sign in. `/talk loop on`
+  makes it hands-free. See [Talk to it](#talk-to-it--voice-both-directions).
 - **MCP servers, sub-agents & skills.** Connect Model Context Protocol servers (local stdio
   or remote HTTP with OAuth) with [`/connect`](#connectors--mcp), delegate work to bounded
   parallel sub-agents, and drop in skills — all gated like everything else.
@@ -288,6 +292,42 @@ with `/signout`; manage linked terminals from the app.
 > to spend on your account. If someone sends you a code and asks you to approve it, don't —
 > that hands *them* a billed session on *your* account.
 
+## Talk to it — voice, both directions
+
+`/speak on` and answers are read aloud **as they are written**, sentence by sentence, with
+code blocks, tables and URLs stripped. Press **ctrl+x** and talk; the mic closes when you
+stop talking and the transcript lands in the composer for you to read before Enter sends it.
+
+```
+/speak on             read answers aloud    ctrl+x    push to talk (press again to send)
+/speak voice <name>   pick a speaker        /talk     the same thing, typed
+/speak rate <n>       0.5–3× pace           /talk loop on   conversation mode, hands-free
+/speak stream off     wait for the full answer instead of speaking as it arrives
+/speak provider       list engines (→ marks the active one); /talk provider does the same
+```
+
+Out of the box it uses your **OS voice** (`say`, `espeak-ng`, System.Speech) and nothing
+leaves the machine. Signed in, both directions quietly upgrade to your account's
+**confidential-compute TTS and STT** — attested-enclave models, the same ones the app's voice
+features use, inherited entitlement and billing. That is an upgrade, not a stomp: a provider
+you picked deliberately stays picked, and `/speak provider local` pins the offline voice for
+good. Be clear-eyed about the difference — the local voice never speaks to the network, while
+the account voice sends the utterance text to an enclave we can't read into but that is still
+off your machine.
+
+One caveat while the account endpoints catch up: `/speak rate` and `/talk vocab` are honored
+by the local and OpenAI-compatible engines, not yet by the account's TTS/STT.
+
+Voice is **off by default and interactive-only** — harbor, ACP and channel sessions never
+speak. The mic opens only on something you did (`/talk`, the push-to-talk key, or a
+conversation turn you switched on); there is no wake word, capture is hard-capped, audio is
+held in memory and never written to disk, and a mis-heard transcript is still just a prompt —
+every tool call it leads to hits the same permission gate as anything you type. Recording
+needs a capture tool on PATH: `sox` anywhere, or `arecord`/`parecord`/`ffmpeg` on Linux,
+`ffmpeg` on macOS. Everything is stored in `~/.privateer/speak.json`; the engine itself is the
+standalone [`privateer-speak`](https://www.npmjs.com/package/privateer-speak) package, usable
+in any Pi agent.
+
 ## The Privateer app
 
 The same account drives Privateer from **iOS, Android, [the web app](https://privateer.pro),
@@ -569,6 +609,7 @@ drop your own into `~/.privateer/agent/extensions/` and it loads the same way, g
 | `/signin` · `/signout` | sign in to a Privateer account (device flow) / sign out |
 | `/remote-access` | link this terminal to the app and allow it to drive (off by default) |
 | `/connect` · `/mcp` | add, enable, or remove MCP connectors / see what actually connected |
+| `/speak` · `/talk` | read answers aloud / voice input (**ctrl+x** is push-to-talk) |
 | `/extensions` | list loaded Pi extensions |
 | `/init` | scaffold a starter `PRIVATEER.md` in this directory |
 | `/update` · `/privateer` | update to the latest release / Privateer status and posture |

package/extensions/privateer-brand.ts

@@ -107,10 +107,80 @@ function buildMark(p: Palette): string[] {
   return rows;
 }
 
-// Visible width = characters after stripping SGR escapes. Everything we render inside
-// the box is ASCII or a BMP width-1 symbol, so a plain length is exact here.
+// Code points that terminals render two cells wide. Two groups matter to us: the CJK /
+// fullwidth ranges, and the symbols Unicode gives *emoji presentation by default* — the
+// second group is the trap, because they look like ordinary BMP dingbats. ⚓ (U+2693) is
+// one, and counting it as one cell pushed the banner's right border a column past the
+// frame on the PRIVATEER.md row. The list is the complete BMP Emoji_Presentation set plus
+// the astral emoji planes, so swapping in another glyph can't quietly reintroduce that.
+const WIDE_RANGES: Array<[number, number]> = [
+  [0x1100, 0x115f], [0x231a, 0x231b], [0x2329, 0x232a], [0x23e9, 0x23ec], [0x23f0, 0x23f0],
+  [0x23f3, 0x23f3], [0x25fd, 0x25fe], [0x2614, 0x2615], [0x2648, 0x2653], [0x267f, 0x267f],
+  [0x2693, 0x2693], [0x26a1, 0x26a1], [0x26aa, 0x26ab], [0x26bd, 0x26be], [0x26c4, 0x26c5],
+  [0x26ce, 0x26ce], [0x26d4, 0x26d4], [0x26ea, 0x26ea], [0x26f2, 0x26f3], [0x26f5, 0x26f5],
+  [0x26fa, 0x26fa], [0x26fd, 0x26fd], [0x2705, 0x2705], [0x270a, 0x270b], [0x2728, 0x2728],
+  [0x274c, 0x274c], [0x274e, 0x274e], [0x2753, 0x2755], [0x2757, 0x2757], [0x2795, 0x2797],
+  [0x27b0, 0x27b0], [0x27bf, 0x27bf], [0x2b1b, 0x2b1c], [0x2b50, 0x2b50], [0x2b55, 0x2b55],
+  [0x2e80, 0x303e], [0x3041, 0x33ff], [0x3400, 0x4dbf], [0x4e00, 0xa4cf], [0xa960, 0xa97f],
+  [0xac00, 0xd7a3], [0xf900, 0xfaff], [0xfe10, 0xfe19], [0xfe30, 0xfe6f], [0xff00, 0xff60],
+  [0xffe0, 0xffe6], [0x1f300, 0x1f64f], [0x1f680, 0x1f6ff], [0x1f900, 0x1f9ff],
+  [0x1fa70, 0x1faff],
+];
+
+function isWide(cp: number): boolean {
+  return WIDE_RANGES.some(([lo, hi]) => cp >= lo && cp <= hi);
+}
+
+// Visible width in terminal cells: SGR escapes are free, combining marks are free, and
+// wide glyphs cost two. A variation selector re-negotiates the *previous* glyph's
+// presentation (FE0F → emoji/wide, FE0E → text/narrow), so it adjusts the running total
+// rather than contributing width of its own.
 function vlen(s: string): number {
-  return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+  const plain = s.replace(/\x1b\[[0-9;]*m/g, "");
+  let w = 0;
+  let prevWide = false;
+  for (const ch of plain) {
+    const cp = ch.codePointAt(0)!;
+    if (cp === 0xfe0f) {
+      if (!prevWide) { w += 1; prevWide = true; }
+      continue;
+    }
+    if (cp === 0xfe0e) {
+      if (prevWide) { w -= 1; prevWide = false; }
+      continue;
+    }
+    // Combining marks and zero-width joiners/spaces stack onto the previous cell.
+    if ((cp >= 0x0300 && cp <= 0x036f) || cp === 0x200b || cp === 0x200d || cp === 0xfeff) continue;
+    prevWide = isWide(cp);
+    w += prevWide ? 2 : 1;
+  }
+  return w;
+}
+
+// Clip a colored line to `max` cells. The banner caps its inner width to the terminal, so
+// on a narrow window a long row (a deep cwd, a long update notice) would otherwise run
+// past the right border and wrap — the same broken frame, from the other direction. SGR
+// escapes are copied through free of charge and a RESET is appended so the truncation
+// can't leak a color into the border. A wide glyph straddling the boundary is dropped and
+// replaced by a space, so the count still lands exactly on `max`.
+function vclip(s: string, max: number, reset: string): string {
+  if (vlen(s) <= max) return s;
+  const parts = s.split(/(\x1b\[[0-9;]*m)/);
+  let out = "";
+  let w = 0;
+  for (const part of parts) {
+    if (part.startsWith("\x1b[")) {
+      out += part;
+      continue;
+    }
+    for (const ch of part) {
+      const cw = vlen(ch);
+      if (w + cw > max) return `${out}${w < max ? " " : ""}${reset}`;
+      out += ch;
+      w += cw;
+    }
+  }
+  return `${out}${reset}`;
 }
 
 // Strip ESC/C0/C1 control bytes from any value we did NOT author before it lands in a
@@ -256,8 +326,9 @@ function renderBanner(width: number, p: Palette, mark: string[], modelProvider?:
   const bar = "─".repeat(inner + 2);
   const out = [`${p.BORDER}╭${bar}╮${p.RESET}`];
   for (const row of rows) {
-    const pad = Math.max(0, inner - vlen(row));
-    out.push(`${p.BORDER}│${p.RESET} ${row}${" ".repeat(pad)} ${p.BORDER}│${p.RESET}`);
+    const line = vclip(row, inner, p.RESET);
+    const pad = Math.max(0, inner - vlen(line));
+    out.push(`${p.BORDER}│${p.RESET} ${line}${" ".repeat(pad)} ${p.BORDER}│${p.RESET}`);
   }
   out.push(`${p.BORDER}╰${bar}╯${p.RESET}`);
   return out;
@@ -267,7 +338,9 @@ function renderBanner(width: number, p: Palette, mark: string[], modelProvider?:
 // provider so the account line reflects the picked model, and the live theme so every
 // colour tracks the terminal background (dark ink on light, light ink on dark). The
 // palette and mark are resolved once here (per theme), not per frame.
-function headerComponent(theme: any, modelProvider?: string) {
+// Exported for tests/banner.test.ts, which renders the real banner and checks the frame
+// is square — the failure mode is a one-cell drift no typecheck can catch.
+export function headerComponent(theme: any, modelProvider?: string) {
   const p = paletteFor(theme);
   const mark = buildMark(p);
   return {

package/extensions/privateer-hints.ts

@@ -22,6 +22,7 @@
 // Pi never reads that file) — read-modify-write, preserving unrelated keys.
 
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
 import { keyText } from "@earendil-works/pi-coding-agent";
 import { configPath, globalDir } from "../src/config/paths.ts";
 
@@ -38,6 +39,19 @@ function key(binding: Parameters<typeof keyText>[0], fallback: string): string {
   }
 }
 
+// Push-to-talk is pi-speak's own binding, not a Pi keybinding action, so keyText
+// can't see it — it lives in speak.json beside config.json and /talk key rebinds
+// it. Read it the same defensive way (any failure = the default).
+function talkKey(): string {
+  try {
+    const shortcut = JSON.parse(readFileSync(join(globalDir(), "speak.json"), "utf8"))?.input?.shortcut;
+    // An explicit "" is "unbound", not "missing" — only an absent field defaults.
+    return typeof shortcut === "string" ? shortcut : "ctrl+x";
+  } catch {
+    return "ctrl+x";
+  }
+}
+
 // Lazy thunks, not strings: keys resolve at display time, after the app has
 // loaded (and possibly remapped) its keybindings.
 const HINTS: Array<() => string> = [
@@ -50,6 +64,12 @@ const HINTS: Array<() => string> = [
   () => `/init writes a PRIVATEER.md so the agent knows this project`,
   () => `/connect adds MCP connectors to this terminal`,
   () => `${key("app.editor.external", "ctrl+g")} drafts long prompts in your $EDITOR`,
+  () => {
+    const k = talkKey();
+    return k
+      ? `${k} is push-to-talk — /speak on reads the answer back`
+      : `/talk types what you say — /speak on reads the answer back`;
+  },
   () => `these tips are /hints — /hints off silences them`,
 ];
 

package/extensions/privateer-speak.ts

@@ -5,6 +5,21 @@
 // confidential STT (/api/audio/transcribe, same tinfoil/near routing the app's voice
 // features use). Both inherit the account's entitlement, caps and billing.
 //
+// STREAMING, AND WHAT IT COSTS. Since pi-speak 0.2.0 a turn is spoken while it is still
+// being written: the stream is cut at sentence boundaries and each piece is synthesized
+// a clip or two ahead of playback. For this provider that means SEVERAL /api/audio/speech
+// calls per answer instead of one — same characters, same billing basis, more round
+// trips — which is the trade that makes the reply start in about the time one sentence
+// takes to speak. /speak stream off puts it back to one call at the end of the turn.
+//
+// NOT WIRED, DELIBERATELY. pi-speak passes two hints this account path has nowhere to
+// put: `rate` (0.5–3× pace) and the transcriber's vocabulary `prompt`. /api/audio/speech
+// takes { text, voice, format, ttsModelId } and /api/audio/transcribe takes
+// { audioBase64, format, language, sttModelId } — neither has a speed or bias field — so
+// sending them would be dead weight on the wire (and, for the vocabulary hint, project
+// nouns leaving the machine to be ignored). They stay unsent until the endpoints grow
+// them; both work today on the local and openai-compatible providers.
+//
 // PROVIDER ATTUNEMENT, NOT STOMPING. The provider registers with preferWhen: signed-in,
 // which the registry ranks ABOVE the built-in local voice but BELOW a deliberate /speak
 // provider pick — sign in and speech quietly upgrades from the OS voice to confidential

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.5",
+  "version": "0.12.6",
   "description": "Privacy-first terminal coding agent — bring your own model across 20 providers (Anthropic, OpenAI, OpenRouter, Google, local Ollama…). Safe-by-default permissions, MCP, sub-agents, workflows, and verifiable TEE inference. Built on the Pi toolkit.",
   "type": "module",
   "license": "MIT",
@@ -84,7 +84,7 @@
     "pi-privacy": "^0.11.0",
     "pi-subagents": "^0.34.0",
     "picomatch": "^4.0.4",
-    "privateer-speak": "0.1.0",
+    "privateer-speak": "0.2.0",
     "privateer-workflow": "^0.1.0",
     "tinfoil": "^1.1.11",
     "tsx": "^4.16.0",