privateer-agent 0.12.57 → 0.13.0

package/README.md

@@ -126,6 +126,9 @@ silently. The moat is swappable; the floor under it holds.
   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).
+- **Named terminals.** The agent can open windows you watch — a dev server, a REPL, a second
+  agent — give each a name, and bring any of them to the front; `/term api` switches you there
+  yourself. macOS Terminal, iTerm2, and tmux anywhere. See [Named terminals](#named-terminals).
 - **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.
@@ -359,8 +362,9 @@ One caveat while the account endpoints catch up: `/speak rate` and `/talk vocab`
 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
+speak. The mic opens only on something you did (`/talk`, the push-to-talk key, a
+conversation turn you switched on, or switching to a window while dictation or conversation
+mode is 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,
@@ -368,6 +372,37 @@ needs a capture tool on PATH: `sox` anywhere, or `arecord`/`parecord`/`ffmpeg` o
 standalone [`privateer-speak`](https://www.npmjs.com/package/privateer-speak) package, usable
 in any Pi agent.
 
+## Named terminals
+
+Ask for "a terminal running the dev server" and the agent opens a new window, names it, and
+puts it in front of you. Every Privateer window names itself too (after its folder, or the
+name the agent gave it), so you and the agent can hop between them by name:
+
+```
+/term                  pick a terminal to switch to
+/term api              switch to "api"
+/term open api npm run dev    open one yourself
+/term name backend     rename this window
+/term close api        close it, ending what runs there
+/term list             every named terminal (← marks this one)
+```
+
+The agent does the same through its `terminal` tool. Opening a window with a command goes
+through the permission gate exactly like running that command in bash; switching and listing
+don't ask. The agent can't read what a window prints: that's what bash and background tasks
+are for. These windows are for you.
+
+Voice follows you between windows. Every window shares one voice setup, so with
+dictation or conversation mode on, the window you switch to listens for your next prompt,
+including a new agent the moment its window opens in front. The window you left pauses
+its mic. (That's [privateer-speak](https://www.npmjs.com/package/privateer-speak)'s focus
+awareness; it needs a terminal that reports focus.)
+
+Works in **macOS Terminal**, **iTerm2**, and inside **tmux** on any platform; other terminals
+get told so. macOS may ask once for permission to let the terminal control itself. Names are
+shared across every Privateer on the machine (`~/.privateer/terminals.json`), and a window
+that's been closed drops off the list on its own.
+
 ## The Privateer app
 
 The same account drives Privateer from **iOS, Android, [the web app](https://privateer.pro),

package/extensions/privateer-brand.ts

@@ -285,10 +285,10 @@ function contextLine(p: Palette): string {
 // or three things a returning user should notice. `cmd`, when present, is rendered in the
 // accent color so the actionable bit stands out from the prose. Trim this as it ages.
 const WHATS_NEW: Array<{ text: string; cmd?: string }> = [
+  { text: "Open and switch named terminals —", cmd: "/term" },
+  { text: "Voice follows the window you're in" },
   { text: "Searchable model picker —", cmd: "/models" },
   { text: "Start over with a new agent —", cmd: "/fresh" },
-  { text: "Text-only models can read images now" },
-  { text: "Live crypto prices and Solana wallets" },
 ];
 
 function whatsNewRows(p: Palette): string[] {

package/extensions/privateer-gate.ts

@@ -491,11 +491,25 @@ const approveInAppMs = isSubagentChild() ? 0 : Number(process.env.PRIVATEER_APPR
 // anything, and media.ts has no business in the TUI's startup graph.
 async function quoteMediaCall(tool: string, input: unknown, signal?: AbortSignal): Promise<number | null> {
   const { readMediaCapabilities, quoteMediaCallUsd } = await import("../src/tools/media.ts");
+  const { effectiveMediaModel } = await import("../src/config/mediaModels.ts");
   const a = (input && typeof input === "object" ? input : {}) as Record<string, unknown>;
-  const model = typeof a.model === "string" && a.model ? a.model : undefined;
-  const query = tool === "generate_video" || tool === "generate_sprite" ? { videoModel: model } : tool === "generate_model" ? { model } : {};
+  // Price the model the tool will actually SEND — its own `model`, else this machine's
+  // /image-model or /video-model choice — not the account default it would fall past.
+  let priced = a;
+  let query: { imageModel?: string; videoModel?: string; model?: string } = {};
+  if (tool === "generate_image") {
+    const imageModel = effectiveMediaModel("image", a.model);
+    priced = { ...a, model: imageModel };
+    query = { imageModel };
+  } else if (tool === "generate_video" || tool === "generate_sprite") {
+    const imageModel = tool === "generate_sprite" ? effectiveMediaModel("image", a.image_model) : undefined;
+    priced = tool === "generate_sprite" ? { ...a, image_model: imageModel } : a;
+    query = { videoModel: effectiveMediaModel("video", a.model), imageModel };
+  } else if (tool === "generate_model") {
+    query = { model: typeof a.model === "string" && a.model ? a.model : undefined };
+  }
   const caps = await readMediaCapabilities(query, signal);
-  return caps.ok ? quoteMediaCallUsd(tool, input, caps.data) : null;
+  return caps.ok ? quoteMediaCallUsd(tool, priced, caps.data) : null;
 }
 
 const cliLedger = cliGrant ? new CliSpendLedger(cliGrant, quoteMediaCall) : null;

package/extensions/privateer-media.ts

@@ -20,14 +20,20 @@
 // already on disk — no account, no network, no spend — so it stays useful to a
 // signed-out terminal, and to a child whose job is to cut together what its parent
 // generated.
+//
+// /image-model and /video-model are registered unconditionally too: they only write a
+// local preference, and a signed-out terminal is told to /login when it opens the
+// picker rather than finding the command missing.
 import { makeMediaTools } from "../src/tools/media.ts";
 import { makeComposeTools } from "../src/tools/videoCompose.ts";
 import { mediaEnabled } from "../src/config/hosted.ts";
 import { childHoldsSpendGrant } from "../src/permissions/childSpend.ts";
 import { isSubagentChild } from "../src/remote/subagentRelay.ts";
+import { registerMediaModelCommands } from "../src/tools/mediaModelCommands.ts";
 
 export default function privateerMedia(pi: any): void {
   const canSpend = !isSubagentChild() || childHoldsSpendGrant();
   if (mediaEnabled() && canSpend) makeMediaTools()(pi);
   makeComposeTools()(pi);
+  registerMediaModelCommands(pi);
 }

package/extensions/privateer-speak.ts

@@ -61,6 +61,7 @@ import {
 } from "privateer-speak";
 import { apiRequest, hasCredentials } from "../src/auth/privateer.ts";
 import { globalDir } from "../src/config/paths.ts";
+import { thisTerminalIsFront } from "../src/terminals/index.ts";
 import { VOICE_DESCRIPTIONS } from "./speak-voices.data.ts";
 
 const QWEN3_TTS_VOICES = ["serena", "aiden", "dylan", "eric", "ono_anna", "ryan", "sohee", "uncle_fu", "vivian"];
@@ -358,7 +359,14 @@ export default function privateerSpeak(pi: any): void {
   // voiceCommands: saying one of these AS THE WHOLE UTTERANCE runs /fresh (see
   // extensions/privateer-fresh.ts) instead of sending the words to the model. Whole
   // utterance only, so "why did the fresh start fail" is still a question.
-  makePiSpeakExtension({ configFile: join(globalDir(), "speak.json"), voiceCommands: VOICE_COMMANDS })(pi);
+  // isFocused: a window that has just started (say, one the agent opened with the
+  // terminal tool) asks Terminal/iTerm2 whether it's in front, so a hands-free mode
+  // carries on in the new agent without a keypress — see src/terminals/.
+  makePiSpeakExtension({
+    configFile: join(globalDir(), "speak.json"),
+    voiceCommands: VOICE_COMMANDS,
+    isFocused: thisTerminalIsFront,
+  })(pi);
 }
 
 const VOICE_COMMANDS: Record<string, string> = {

package/extensions/privateer-terminals.ts

@@ -0,0 +1,73 @@
+// Named terminals — the `terminal` tool and /term, so the agent can open windows the
+// user watches (a dev server, a REPL, a second agent) and either of them can switch
+// between those windows by name. See src/terminals/ for how windows are found and why
+// only tmux, macOS Terminal and iTerm2 are driven.
+//
+// Interactive only: the window registers itself at session start, which a harbor or ACP
+// host has no window to do, and the tool refuses without a UI.
+
+import { closeTerminal, describeListing, focusTerminal, openTerminal, renameSelf, terminalListing, backend, claimSelf } from "../src/terminals/index.ts";
+import { terminalToolDefinition } from "../src/tools/terminal.ts";
+
+const USAGE =
+  "/term — pick a terminal to switch to · /term <name> — switch · /term open <name> [command] · " +
+  "/term name <name> — rename this one · /term close <name> · /term list";
+
+export default function privateerTerminals(pi: any): void {
+  pi.registerTool?.(terminalToolDefinition);
+
+  // Name this window as soon as the session starts, so it can be switched back to from
+  // any other — not only after its first /term.
+  pi.on?.("session_start", (_e: any, ctx: any) => {
+    if (!ctx?.hasUI) return;
+    const b = backend();
+    if ("unsupported" in b) return;
+    void claimSelf(b, ctx.cwd ?? process.cwd()).catch(() => undefined);
+  });
+
+  pi.registerCommand?.("term", {
+    description: "Switch between named terminals, or open one",
+    handler: async (args: string, ctx: any) => {
+      const notify = (m: string, kind: "info" | "warning" | "error" = "info") => ctx?.ui?.notify?.(m, kind);
+      const cwd = ctx?.cwd ?? process.cwd();
+      const [sub = "", ...rest] = String(args ?? "").trim().split(/\s+/).filter(Boolean);
+      const report = (o: { ok: boolean; message: string }) => notify(o.message, o.ok ? "info" : "warning");
+
+      switch (sub.toLowerCase()) {
+        case "": {
+          const l = await terminalListing(cwd);
+          if ("unsupported" in l) return notify(l.unsupported, "warning");
+          const others = l.records.filter((r) => r.id !== l.selfId);
+          if (!others.length) return notify(`No other named terminals. ${USAGE}`);
+          if (typeof ctx?.ui?.select !== "function") return notify(describeListing(l));
+          const labels = others.map((r) => `${r.name}  ${r.command ?? r.cwd}`);
+          const picked = await ctx.ui.select("Switch to terminal", labels);
+          const rec = picked ? others[labels.indexOf(picked)] : undefined;
+          if (rec) report(await focusTerminal(rec.name, cwd));
+          return;
+        }
+        case "list": {
+          const l = await terminalListing(cwd);
+          return notify("unsupported" in l ? l.unsupported : describeListing(l), "unsupported" in l ? "warning" : "info");
+        }
+        case "open": {
+          const [name, ...cmd] = rest;
+          if (!name) return notify("Usage: /term open <name> [command]", "warning");
+          return report(await openTerminal({ name, cwd, ...(cmd.length ? { command: cmd.join(" ") } : {}) }));
+        }
+        case "name":
+        case "rename":
+          if (!rest.length) return notify("Usage: /term name <name>", "warning");
+          return report(await renameSelf(rest.join(" "), cwd));
+        case "close":
+          if (!rest.length) return notify("Usage: /term close <name>", "warning");
+          return report(await closeTerminal(rest.join(" "), cwd));
+        case "help":
+          return notify(USAGE);
+        default:
+          // Anything else is a name: /term api, /term "dev server".
+          return report(await focusTerminal([sub, ...rest].join(" "), cwd));
+      }
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.57",
+  "version": "0.13.0",
   "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",
@@ -86,7 +86,7 @@
     "pi-privacy": "0.14.1",
     "pi-subagents": "0.70.0",
     "picomatch": "4.0.5",
-    "privateer-speak": "0.6.0",
+    "privateer-speak": "0.7.0",
     "privateer-workflow": "0.1.0",
     "tinfoil": "1.1.11",
     "tsx": "4.23.0",

package/src/config/mediaModels.ts

@@ -0,0 +1,64 @@
+/**
+ * Which image and video models this machine's agent generates with, when the agent
+ * doesn't name one itself. Set by `/image-model` and `/video-model`
+ * (extensions/privateer-media.ts), stored as `media.imageModel` / `media.videoModel`
+ * in ~/.privateer/config.json.
+ *
+ * PER MACHINE, NOT PER ACCOUNT. The account already has a default for each (the app's
+ * own picker writes it, server-side), and that is what an unset value here falls through
+ * to. A terminal choice deliberately does not write back to it: picking a cheap video
+ * model for a batch of terminal drafts should not change what the phone renders with.
+ *
+ * PRECEDENCE, highest first: the tool call's own `model` → this file → the account
+ * default. The agent naming a model still wins, because it only does that when a job
+ * calls for a specific one (a 4K clip, a model that takes a last frame).
+ *
+ * Read at CALL time, like piiAllow.ts: a pick made in one terminal reaches a harbor or
+ * a second terminal on the same machine on its next generation, without a restart.
+ * Missing file, unreadable file and malformed JSON all mean "no choice" — the account
+ * default — never a crash in the middle of a tool call.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { configPath } from "./paths.ts";
+
+export type MediaKind = "image" | "video";
+
+const KEY: Record<MediaKind, "imageModel" | "videoModel"> = { image: "imageModel", video: "videoModel" };
+
+function readConfig(): Record<string, unknown> {
+  try {
+    const cfg = JSON.parse(readFileSync(configPath(), "utf8"));
+    return cfg && typeof cfg === "object" && !Array.isArray(cfg) ? cfg : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The chosen model id for `kind`, or undefined to use the account default. */
+export function mediaModelPref(kind: MediaKind): string | undefined {
+  const media = readConfig().media as Record<string, unknown> | undefined;
+  const v = media?.[KEY[kind]];
+  return typeof v === "string" && v.trim() ? v.trim() : undefined;
+}
+
+/**
+ * Set (or, with null, clear) the choice for `kind`. Every other key in config.json is
+ * preserved — it also holds webhooks, privacy and coauthor settings this must not drop.
+ */
+export function setMediaModelPref(kind: MediaKind, id: string | null): void {
+  const cfg = readConfig();
+  const media = { ...((cfg.media as Record<string, unknown>) ?? {}) };
+  const clean = id?.trim();
+  if (clean) media[KEY[kind]] = clean;
+  else delete media[KEY[kind]];
+  const next: Record<string, unknown> = { ...cfg, media };
+  if (Object.keys(media).length === 0) delete next.media;
+  mkdirSync(dirname(configPath()), { recursive: true });
+  writeFileSync(configPath(), JSON.stringify(next, null, 2) + "\n");
+}
+
+/** The model a call should send: its own `model`, else this machine's choice, else none. */
+export function effectiveMediaModel(kind: MediaKind, requested: unknown): string | undefined {
+  return typeof requested === "string" && requested.trim() ? requested.trim() : mediaModelPref(kind);
+}

package/src/config/moatManifest.json

@@ -20,6 +20,7 @@
     { "entry": "extensions/privateer-media.ts", "name": "privateer-media", "note": "image/video/speech/music + ffmpeg compose" },
     { "entry": "extensions/privateer-computer.ts", "name": "privateer-computer", "note": "screen control — screenshots, mouse and keyboard (off unless armed with --allow-computer-control)" },
     { "entry": "extensions/privateer-desktop.ts", "name": "privateer-desktop", "note": "/desktop — open the Privateer desktop app" },
+    { "entry": "extensions/privateer-terminals.ts", "name": "privateer-terminals", "note": "named terminal windows — the terminal tool + /term to switch between them" },
     { "entry": "extensions/privateer-hints.ts", "name": "privateer-hints", "note": "rotating tips in the working line + /hints" },
     { "entry": "extensions/privateer-update.ts", "name": "privateer-update", "note": "tool pack updates in place — banner flag + /update" },
     { "entry": "extensions/privateer-fresh.ts", "name": "privateer-fresh", "note": "/fresh — replace the agent with a new one and stop everything it started" },

package/src/permissions/classify.ts

@@ -648,6 +648,28 @@ export function classifyToolCall(
     };
   }
 
+  // terminal (src/tools/terminal.ts) — named windows the user watches. Opening one
+  // with a command RUNS that command, so it is bash-kind with the command as the
+  // detail: the same danger list, allowlist and plan-mode refusal as typing it into
+  // bash. A bare shell is bash-kind too (it puts a new window on the user's screen),
+  // and so is close, which ends whatever runs in the window. Focus and list only move
+  // a window to the front or read names: no gate, in any mode.
+  if (name === "terminal") {
+    const action = str(obj.action) || "list";
+    if (action === "focus" || action === "list") return null;
+    const label = str(obj.name);
+    if (action === "close") {
+      return { tool: toolName, kind: "bash", title: `Close terminal "${label}"`, detail: `close terminal ${label}` };
+    }
+    const command = str(obj.command).trim();
+    return {
+      tool: toolName,
+      kind: "bash",
+      title: command ? `Open terminal "${label}" running a command` : `Open terminal "${label}"`,
+      detail: command || `open a shell${obj.cwd ? ` in ${str(obj.cwd)}` : ""}`,
+    };
+  }
+
   // Network reads (web fetch / search / http).
   if (name.includes("fetch") || name.includes("web") || name.includes("http") || name.includes("url")) {
     return {