privateer-agent 0.12.2 → 0.12.5

package/README.md

@@ -390,6 +390,37 @@ the app are write-only — the app can name them but never read them back. Note
 live in plaintext in `config.json` on your machine, and every channel action is appended to
 `~/.privateer/channels-audit.log`.
 
+## Drive it from Buzz or Zed — ACP
+
+Privateer speaks the [Agent Client Protocol](https://agentclientprotocol.com) (ACP v1 over
+stdio). Any ACP host — [Buzz](https://buzz.xyz), Block's team messenger where agents are
+teammates, or the [Zed](https://zed.dev) editor — can spawn `privateer acp` and drive it:
+prompts stream back, tool activity shows live, and the host's model picker lists Privateer's
+catalog with TEE-backed models labelled **confidential (TEE)**.
+
+The part we care about: **the host renders the UI, but authority never leaves your machine.**
+
+- Every action is classified by Privateer's own permission gate — ACP's
+  `session/request_permission` only delivers the prompt.
+- The **tool ceiling** comes from your local config, not the host, and ships **read-only**
+  (`read`, `grep`, `find`, `ls`). The host cannot widen it.
+- Filesystem access is **confined to one directory root**; out-of-tree access is refused,
+  not prompted.
+- Every ambiguous outcome — unreachable host, cancelled dialog, unknown answer, aborted
+  turn — resolves to **deny**.
+- "Allow for this session" lives in memory and dies with the session; dangerous shell
+  (`curl … | sh` and friends) can never become standing permission.
+
+Zed setup (`settings.json`):
+
+```json
+{ "agent_servers": { "Privateer": { "command": "privateer", "args": ["acp"] } } }
+```
+
+Honest caveat for Buzz: **Buzz currently auto-approves permission prompts**, so under Buzz
+the tool ceiling *is* the control — which is exactly why the default is read-only. Full
+setup, config, and limitations: [`docs/acp.md`](docs/acp.md).
+
 ## Connectors — MCP
 
 Privateer is an **MCP client**. Point it at a [Model Context Protocol](https://modelcontextprotocol.io)
@@ -543,7 +574,8 @@ drop your own into `~/.privateer/agent/extensions/` and it loads the same way, g
 | `/update` · `/privateer` | update to the latest release / Privateer status and posture |
 
 Shell subcommands: `privateer` (interactive), `privateer update`, `privateer harbor …`,
-`privateer --no-quarter`, `privateer --version`.
+`privateer acp` (serve the agent to an ACP host like Buzz or Zed — see
+[`docs/acp.md`](docs/acp.md)), `privateer --no-quarter`, `privateer --version`.
 
 ## Develop
 

package/extensions/privateer-hints.ts

@@ -0,0 +1,132 @@
+// Rotating tips in the working line. While the agent streams, the "Working..."
+// loader is dead air for seconds at a time — the one spot a discoverability hint
+// costs no vertical space and interrupts nothing. So while a turn is active we
+// rotate short tips through it for the keys and commands nobody finds on their
+// own: ctrl+t to hide thinking text (the ask that prompted this), shift+tab for
+// the thinking level, @file mentions, /models, and so on.
+//
+// Mechanics: ctx.ui.setWorkingMessage(msg) both stores the message for the next
+// working indicator AND live-updates the one currently on screen (and ONLY the
+// "working" kind — Pi's guard means retry/compaction spinners are never touched),
+// so a timer can rotate the text mid-stream. Calling it with no argument restores
+// Pi's default "Working...", which is what agent_end does. Timers run strictly
+// inside agent_start → agent_end, so an idle terminal owns no message at all.
+//
+// Keys render through pi-coding-agent's keyText, which reads the LIVE keybindings
+// singleton the running app configured — a user remap shows the remapped key, and
+// each hint carries a fallback for an unbound action. The first tip waits a beat
+// (FIRST_MS) so short turns never see one; the cursor is module-lifetime so
+// back-to-back turns continue the rotation instead of repeating tip #1.
+//
+// /hints on|off persists { hints: { enabled } } in ~/.privateer/config.json (ours;
+// Pi never reads that file) — read-modify-write, preserving unrelated keys.
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { keyText } from "@earendil-works/pi-coding-agent";
+import { configPath, globalDir } from "../src/config/paths.ts";
+
+const FIRST_MS = 6_000; // a turn shorter than this never shows a tip
+const EVERY_MS = 12_000;
+
+// keyText returns "" for an unbound action and could throw if the keybindings
+// singleton isn't initialized yet (headless surfaces) — fall back either way.
+function key(binding: Parameters<typeof keyText>[0], fallback: string): string {
+  try {
+    return keyText(binding) || fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+// Lazy thunks, not strings: keys resolve at display time, after the app has
+// loaded (and possibly remapped) its keybindings.
+const HINTS: Array<() => string> = [
+  () => `${key("app.thinking.toggle", "ctrl+t")} hides thinking text — make it stick in /settings`,
+  () => `${key("app.thinking.cycle", "shift+tab")} cycles the thinking level`,
+  () => `${key("app.message.followUp", "alt+enter")} queues a follow-up without interrupting`,
+  () => `${key("app.tools.expand", "ctrl+o")} expands collapsed tool output`,
+  () => `type @ to reference a file in your prompt — Tab completes the path`,
+  () => `/models picks a model, with TEE/ZDR privacy shields`,
+  () => `/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`,
+  () => `these tips are /hints — /hints off silences them`,
+];
+
+// Default ON: absent file, absent block, or unreadable JSON all mean enabled.
+// Only an explicit { hints: { enabled: false } } turns the rotation off.
+function hintsEnabled(): boolean {
+  try {
+    return JSON.parse(readFileSync(configPath(), "utf8"))?.hints?.enabled !== false;
+  } catch {
+    return true;
+  }
+}
+
+function persistEnabled(enabled: boolean): void {
+  let cfg: any = {};
+  try {
+    cfg = JSON.parse(readFileSync(configPath(), "utf8"));
+  } catch {
+    /* no config yet */
+  }
+  if (typeof cfg !== "object" || cfg === null || Array.isArray(cfg)) cfg = {};
+  cfg.hints = { ...(cfg.hints ?? {}), enabled };
+  try {
+    mkdirSync(globalDir(), { recursive: true });
+    writeFileSync(configPath(), JSON.stringify(cfg, null, 2) + "\n");
+  } catch {
+    /* best effort — the toggle still holds for this session */
+  }
+}
+
+export default function privateerHints(pi: any): void {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let uiRef: any;
+  let cursor = 0;
+
+  const stop = (restoreDefault: boolean): void => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    if (restoreDefault) uiRef?.setWorkingMessage?.();
+  };
+
+  const showNext = (): void => {
+    const hint = HINTS[cursor % HINTS.length]();
+    cursor++;
+    uiRef?.setWorkingMessage?.(`Working... · tip: ${hint}`);
+    timer = setTimeout(showNext, EVERY_MS);
+  };
+
+  pi.on("agent_start", (_e: any, ctx: any) => {
+    if (!ctx?.hasUI) return; // headless (print/rpc/harbor): no loader to write to
+    uiRef = ctx.ui;
+    stop(false); // an interrupted turn can restart without an agent_end between
+    if (!hintsEnabled()) return;
+    timer = setTimeout(showNext, FIRST_MS);
+  });
+
+  pi.on("agent_end", () => stop(true));
+  pi.on("session_shutdown", () => stop(false));
+
+  pi.registerCommand?.("hints", {
+    description: "Rotating tips in the working line: /hints [on | off]",
+    handler: (args: string, ctx: any) => {
+      uiRef = ctx?.ui ?? uiRef;
+      const sub = String(args ?? "").trim().toLowerCase().split(/\s+/)[0];
+      if (sub === "on" || sub === "off") {
+        const enabled = sub === "on";
+        persistEnabled(enabled);
+        if (!enabled) stop(true); // takes effect mid-turn; "on" starts next turn
+        ctx?.ui?.notify?.(`Working-line tips ${enabled ? "on" : "off"}.`, "info");
+        return;
+      }
+      ctx?.ui?.notify?.(
+        `Working-line tips are ${hintsEnabled() ? "on" : "off"} — /hints on|off to change.`,
+        "info",
+      );
+    },
+  });
+}

package/extensions/privateer-speak.ts

@@ -0,0 +1,109 @@
+// Spoken responses AND voice input for the TUI: the generic privateer-speak (pi-speak)
+// extension, plus Privateer's own providers hooked into both its registries — the
+// account's confidential-compute TTS (/api/audio/speech, same path as the app's Audio
+// studio and generate_speech; today Tinfoil qwen3-tts in an attested enclave) and its
+// confidential STT (/api/audio/transcribe, same tinfoil/near routing the app's voice
+// features use). Both inherit the account's entitlement, caps and billing.
+//
+// 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
+// TTS, exactly the resolveSignedInModel pattern, with the model-persistence lesson
+// applied (a user who picked "local" stays on "local").
+//
+// HONEST FRAMING. "Confidential", never "private end-to-end": the utterance text leaves
+// the machine for the attested TTS enclave. That is the claim the label makes and the
+// only one it may make. And this only ever speaks in interactive UI sessions — pi-speak
+// gates on hasUI, so harbor/daemon/ACP surfaces stay silent by design (this extension is
+// manifest-only, like privateer-hints: buildMoat never includes it).
+//
+// VOICES. qwen3-tts speakers, mirrored from the server's TINFOIL_VOICES (the list is
+// static there too; first entry is the server-side default). Tinfoil requires the voice
+// param server-side, so the server applies "serena" when none is sent — leaving voice
+// unset here is always safe. If the account's default TTS model ever changes, update
+// this list with it.
+import { join } from "node:path";
+import { makePiSpeakExtension, registerSpeechProvider, registerTranscriptionProvider } from "privateer-speak";
+import { apiRequest, hasCredentials } from "../src/auth/privateer.ts";
+import { globalDir } from "../src/config/paths.ts";
+
+const QWEN3_TTS_VOICES = ["serena", "aiden", "dylan", "eric", "ono_anna", "ryan", "sohee", "uncle_fu", "vivian"];
+
+// Call an account audio endpoint and hand back the parsed JSON, throwing the server's
+// own (person-readable, localized) message on failure — same policy as media.ts's
+// callAccount: surface, never swallow.
+async function accountJson<T>(path: string, body: unknown, signal?: AbortSignal): Promise<T> {
+  let res: Response;
+  try {
+    res = await apiRequest(path, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      ...(signal ? { signal } : {}),
+    });
+  } catch (e) {
+    throw new Error(`could not reach Privateer: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (!res.ok) {
+    let message = `Privateer returned ${res.status}`;
+    try {
+      const err = (await res.json()) as { message?: string; error?: { message?: string } };
+      message = err?.message ?? err?.error?.message ?? message;
+    } catch {
+      /* non-JSON body — the status message stands */
+    }
+    throw new Error(message);
+  }
+  return (await res.json()) as T;
+}
+
+registerSpeechProvider(
+  {
+    id: "privateer",
+    label: "Privateer account TTS (attested enclave)",
+    privacy: "confidential",
+    defaultVoice: QWEN3_TTS_VOICES[0],
+    voices: () => QWEN3_TTS_VOICES,
+    available: () => hasCredentials(),
+    fetchSpeech: async (text, { voice, signal }) => {
+      const { audioBase64 } = await accountJson<{ audioBase64?: string }>(
+        "/api/audio/speech",
+        { text, ...(voice ? { voice } : {}) },
+        signal,
+      );
+      if (!audioBase64) throw new Error("Privateer returned no audio");
+      return { data: Buffer.from(audioBase64, "base64"), format: "mp3" };
+    },
+  },
+  { preferWhen: () => hasCredentials() },
+);
+
+registerTranscriptionProvider(
+  {
+    id: "privateer",
+    label: "Privateer account STT (attested enclave)",
+    privacy: "confidential",
+    available: () => hasCredentials(),
+    transcribe: async (audio, { language, signal }) => {
+      const { text } = await accountJson<{ text?: string }>(
+        "/api/audio/transcribe",
+        {
+          audioBase64: Buffer.from(audio.data).toString("base64"),
+          format: audio.format,
+          ...(language ? { language } : {}),
+        },
+        signal,
+      );
+      return typeof text === "string" ? text : "";
+    },
+  },
+  { preferWhen: () => hasCredentials() },
+);
+
+export default function privateerSpeak(pi: any): void {
+  // Ours, beside config.json — NOT ~/.pi/speak.json, so a user who also runs plain Pi
+  // with the generic package keeps two independent setups instead of a fought-over
+  // file. globalDir() is read here, not at module load, so PRIVATEER_HOME set around
+  // session creation (tests, the daemon) is honoured.
+  makePiSpeakExtension({ configFile: join(globalDir(), "speak.json") })(pi);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.2",
+  "version": "0.12.5",
   "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",
@@ -60,7 +60,8 @@
     "start": "tsx src/main.ts",
     "chat": "node --env-file=.env --import tsx src/cli/chat.ts",
     "channels": "node --env-file=.env --import tsx src/channels/run.ts",
-    "dev": "tsx watch src/main.ts",
+    "dev": "node bin/privateer-launch.mjs",
+    "dev:fresh": "PRIVATEER_HOME=\"$PWD/.dev-home\" node bin/privateer-launch.mjs",
     "typecheck": "tsc --noEmit",
     "test": "for f in tests/*.test.ts; do node --import tsx --test \"$f\" || exit 1; done"
   },
@@ -71,7 +72,6 @@
     "@earendil-works/pi-ai": "^0.80.3",
     "@earendil-works/pi-coding-agent": "0.80.3",
     "@earendil-works/pi-tui": "^0.80.3",
-    "@hypabolic/pi-hypa": "^0.1.6",
     "@juicesharp/rpiv-ask-user-question": "^2.2.0",
     "@juicesharp/rpiv-web-tools": "^1.20.0",
     "@noble/ciphers": "^2.1.1",
@@ -84,6 +84,7 @@
     "pi-privacy": "^0.11.0",
     "pi-subagents": "^0.34.0",
     "picomatch": "^4.0.4",
+    "privateer-speak": "0.1.0",
     "privateer-workflow": "^0.1.0",
     "tinfoil": "^1.1.11",
     "tsx": "^4.16.0",

package/src/auth/privateer.ts

@@ -451,8 +451,14 @@ export async function runDeviceLogin(opts: {
 // Pass the server's own message through so the user learns what to actually do.
 async function spawnFailure(res: Response): Promise<Error> {
   if (res.status === 401) {
-    clearCredentials();
-    notifySessionExpired();
+    // Announce only the signed-in → signed-out transition: concurrent launch-time
+    // spawns (warmSession + the account-channel seed) can both 401 on the same dead
+    // login, and whichever lands second must stay silent. Same guard as
+    // handleServerRevoke.
+    if (hasCredentials()) {
+      clearCredentials();
+      notifySessionExpired();
+    }
     return new Error("Your Privateer session expired. Run /login to sign in again.");
   }
   let message: string | undefined;

package/src/config/moatManifest.json

@@ -11,16 +11,16 @@
     { "name": "privateer-privacy", "entry": "extensions/privateer-privacy.ts", "note": "pi-privacy + account tier resolver" },
     { "name": "privateer-connect", "entry": "extensions/privateer-connect.ts", "note": "/connect — MCP connector manager" },
     { "name": "privateer-media", "entry": "extensions/privateer-media.ts", "note": "image/video/speech/music + ffmpeg compose" },
+    { "name": "privateer-hints", "entry": "extensions/privateer-hints.ts", "note": "rotating tips in the working line + /hints" },
+    { "name": "privateer-speak", "entry": "extensions/privateer-speak.ts", "note": "spoken responses (/speak) + voice input (/talk) — pi-speak + confidential account TTS/STT" },
     { "name": "rpiv-web-tools", "dep": ["@juicesharp/rpiv-web-tools", "index.ts"], "note": "private web tools (user's own provider key)" },
     { "name": "rpiv-ask-user-question", "dep": ["@juicesharp/rpiv-ask-user-question", "index.ts"], "note": "ask_user_question" },
     { "name": "pi-mcp-adapter", "dep": ["pi-mcp-adapter", "index.ts"], "note": "MCP servers as first-class tools" },
-    { "name": "pi-hypa", "dep": ["@hypabolic/pi-hypa", "extensions", "index.ts"], "note": "hypa pack" },
     { "name": "pi-subagents", "dep": ["pi-subagents", "src", "extension", "index.ts"], "note": "bounded parallel sub-agents" }
   ],
-  "retired": ["pi-privacy", "pi-web-access"],
+  "retired": ["pi-privacy", "pi-web-access", "pi-hypa"],
   "reservedAliases": [
     "@juicesharp/rpiv-web-tools",
-    "@juicesharp/rpiv-ask-user-question",
-    "@hypabolic/pi-hypa"
+    "@juicesharp/rpiv-ask-user-question"
   ]
 }

package/src/providers/account.ts

@@ -56,6 +56,10 @@ const DEFAULT_MODELS = [
   "anthropic/claude-sonnet-5",
   "openai/gpt-5.6-sol",
   "deepseek/deepseek-v4-flash",
+  // 2026-08 releases, confirmed live on OpenRouter (ZDR-covered ids reach the
+  // account catalog automatically; these seeds just make them resolve at launch).
+  "moonshotai/kimi-k3",
+  "z-ai/glm-5.2",
 ];
 
 function seedModel(id: string) {
@@ -816,7 +820,10 @@ export async function armAccountCredential(
     // so staying silent leaves the user to discover it as a bare "No API key found for
     // privateer" on their first prompt.
     const c = ctx as SeedContext;
-    if (opts.notify !== false && c?.hasUI) {
+    // If the credentials vanished during the call, the spawn hit a 401 and
+    // onSessionExpired already announced the sign-out — a second line here would
+    // just repeat it (we returned early above if we STARTED signed out).
+    if (opts.notify !== false && c?.hasUI && hasCredentials()) {
       c.ui?.notify?.(`Privateer account channel unavailable — ${(e as Error).message}`, "error");
     }
     return false;

package/src/providers/catalog.ts

@@ -59,7 +59,7 @@ export const PROVIDERS: ProviderEntry[] = [
     api: "openai-completions",
     keyEnv: "${DASHSCOPE_API_KEY}",
     compat: { thinkingFormat: "qwen" },
-    seedModels: ["qwen3-max", "qwen3-coder-plus", "qwen-max-latest"],
+    seedModels: ["qwen3.8-max-preview", "qwen3-max", "qwen3-coder-plus", "qwen-max-latest"],
   },
   { id: "ollama", source: "pi-privacy" },
   { id: "nearai", source: "pi-privacy" },

package/src/providers/genModelsJson.ts

@@ -36,6 +36,13 @@ export interface ModelsJson {
   providers: Record<string, ModelsJsonProvider>;
 }
 
+// Per-id context-window overrides for seeds whose real window is far from the
+// Appendix A.4 default (kept until the live listing refines them). Qwen3.8-Max
+// serves ~1M tokens (983,616 advertised at launch, 2026-08-03).
+const SEED_CONTEXT: Record<string, number> = {
+  "qwen3.8-max-preview": 1_000_000,
+};
+
 function seedModel(id: string, compat?: Record<string, unknown>): ModelsJsonModel {
   return {
     id,
@@ -43,7 +50,7 @@ function seedModel(id: string, compat?: Record<string, unknown>): ModelsJsonMode
     reasoning: false,
     input: ["text"],
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-    contextWindow: 128000,
+    contextWindow: SEED_CONTEXT[id] ?? 128000,
     maxTokens: 16384,
     ...(compat ? { compat } : {}),
   };