privateer-agent 0.12.31 → 0.12.33

package/bin/privateer-splash.mjs

@@ -37,8 +37,19 @@
 // never lands in front of real output.
 //
 // The wave is drawn on STDERR; stdout belongs to the TUI's canvas.
+//
+// WHY EVERY WRITE OF OURS IS fs.writeSync. On Windows a write to a TTY stream is
+// ASYNCHRONOUS — process.stderr.write only queues the bytes for the event loop — and the
+// whole point of this file is that Pi's boot never gives the event loop a turn. Through
+// process.stderr, every erase we issue during the wait would land after the output it was
+// meant to clear, and the cursor restore on `exit` would never flush at all: a Windows
+// console left with wave fragments in front of Pi's first frame and no cursor afterwards.
+// fs.writeSync goes straight to fd 2, which is also what the drawing thread uses, so the
+// two threads' output stays in the order it was issued. Pi's OWN stderr still goes
+// through the stream — that write belongs to the caller, return value and all.
 
 import { spawnSync } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 import { Worker } from "node:worker_threads";
 
@@ -62,6 +73,32 @@ if (enabled && process.platform === "win32") {
   }
 }
 
+// WHICH GLYPHS THE CONSOLE CAN ACTUALLY DRAW. Code page 65001 above settles the ENCODING;
+// it says nothing about the FONT. Legacy conhost — a plain cmd.exe or PowerShell window,
+// which is still what `privateer` gets when it isn't launched from Windows Terminal —
+// defaults to Lucida Console or a raster font, and those cover exactly the CP437 block
+// elements (█ ▄ ▀ ░ ▒ ▓) and nothing else. The eighth-block ramp, the anchor and the
+// ellipsis are all absent there, so the "wave" drew as a row of tofu boxes that changed
+// shape every frame. Every modern host announces itself in the environment (Windows
+// Terminal, VS Code, ConEmu/ANSICON, anything mintty-ish that sets TERM), and on those the
+// eighth blocks are the better picture, so the fallback is only for the ones that don't.
+const legacyConsole =
+  process.platform === "win32" &&
+  !(
+    process.env.WT_SESSION ||
+    process.env.WT_PROFILE_ID ||
+    process.env.TERM_PROGRAM ||
+    process.env.ConEmuANSI ||
+    process.env.ANSICON ||
+    process.env.TERM
+  );
+
+// Eight levels either way, so the wave keeps its shape: height where the font has the
+// eighth blocks, density where it only has the CP437 shades.
+const BLOCKS = legacyConsole ? " \u2591\u2591\u2592\u2592\u2593\u2593\u2588" : "\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588";
+const ANCHOR = legacyConsole ? "~" : "\u2693";
+const ELLIPSIS = legacyConsole ? "..." : "\u2026";
+
 // Bytes of stdout after TUI.start() that mean "this is the first frame, not a control
 // sequence". Everything Pi writes between raw mode and the frame is short (the paste
 // toggle, a Kitty protocol query, the cursor hide, an OSC window title — 42 bytes all
@@ -86,10 +123,17 @@ if (enabled) {
   const sab = new SharedArrayBuffer(4 * Int32Array.BYTES_PER_ELEMENT);
   const state = new Int32Array(sab);
 
-  // Room for "  ⚓ " + wave + message + elapsed, clamped so a narrow terminal doesn't
-  // wrap (a wrapped line survives our `\r\x1b[K` erase only on its last row).
+  // Room for "  ⚓ " + wave + " " + message + ellipsis + elapsed, clamped so a narrow
+  // terminal doesn't wrap (a wrapped line survives our `\r\x1b[K` erase only on its last
+  // row). The reserve is measured rather than guessed, because the pieces are no longer
+  // fixed: the anchor is TWO cells wherever ⚓ keeps its emoji presentation, one where it
+  // fell back to ASCII, and the ellipsis is one cell or three.
+  const MSGS = ["hoisting sail", "raising the colours"];
+  const anchorCells = ANCHOR === "\u2693" ? 2 : 1; // U+2693 carries emoji presentation
+  const reserve =
+    2 + anchorCells + 1 + 1 + Math.max(...MSGS.map((m) => m.length)) + ELLIPSIS.length + 5;
   const cols = err.columns && err.columns > 0 ? err.columns : 80;
-  const width = Math.max(6, Math.min(28, cols - 34));
+  const width = Math.max(6, Math.min(28, cols - reserve));
 
   // The worker source is plain logic with no escape sequences of its own — every ANSI
   // string is handed over in workerData, so nothing here has to survive two rounds of
@@ -122,7 +166,7 @@ if (enabled) {
       const secs = Math.round((Date.now() - t0) / 1000);
       const msg = w.msgs[Atomics.load(s, PHASE)];
       const age = secs >= 3 ? w.dim + " " + secs + "s" + w.off : "";
-      fs.writeSync(2, w.cr + "  " + w.anchor + " " + wave(frame++ * 0.35) + " " + w.dim + msg + "…" + w.off + age + w.clearEol);
+      fs.writeSync(2, w.cr + "  " + w.anchor + " " + wave(frame++ * 0.35) + " " + w.dim + msg + w.ellipsis + w.off + age + w.clearEol);
     }
 
     // Atomics.wait doubles as the sleep: an exact 80ms tick that the main thread can cut
@@ -146,9 +190,10 @@ if (enabled) {
         sab,
         width,
         hold: HOLD_MS,
-        blocks: "▁▂▃▄▅▆▇█",
-        msgs: ["hoisting sail", "raising the colours"],
-        anchor: "\x1b[38;5;69m⚓\x1b[0m",
+        blocks: BLOCKS,
+        msgs: MSGS,
+        ellipsis: ELLIPSIS,
+        anchor: `\x1b[38;5;69m${ANCHOR}\x1b[0m`,
         crest: "\x1b[38;5;109m",
         trough: "\x1b[38;5;67m",
         dim: "\x1b[2m",
@@ -176,8 +221,23 @@ if (enabled) {
     if (!Atomics.load(state, ACK)) Atomics.wait(state, ACK, 0, 50);
   }
 
+  // Our own control sequences, written straight to fd 2 and synchronously — see the note
+  // at the top of the file for why process.stderr will not do. A short write or an EAGAIN
+  // from a non-blocking tty is retried; anything else is swallowed, because a splash is
+  // never worth a crash.
+  function writeCtl(s) {
+    const buf = Buffer.from(s, "utf8");
+    for (let off = 0, tries = 0; off < buf.length && tries < 100; tries++) {
+      try {
+        off += fs.writeSync(2, buf, off);
+      } catch (e) {
+        if (e?.code !== "EAGAIN") return;
+      }
+    }
+  }
+
   function clearLine() {
-    if (Atomics.load(state, DREW)) errWrite("\r\x1b[K");
+    if (Atomics.load(state, DREW)) writeCtl("\r\x1b[K");
   }
 
   function stop() {
@@ -187,7 +247,7 @@ if (enabled) {
     clearLine();
     // Only give the cursor back if Pi hasn't deliberately hidden it — the TUI hides it
     // for the whole session and would never get the chance to hide it again.
-    if (Atomics.load(state, DREW) && !appHidCursor) errWrite("\x1b[?25h");
+    if (Atomics.load(state, DREW) && !appHidCursor) writeCtl("\x1b[?25h");
     process.stdout.write = outWrite;
     err.write = errWrite;
     worker.terminate();
@@ -246,10 +306,12 @@ if (enabled) {
       } catch (e) {
         if (e?.code !== "EIO") throw e;
         stop();
-        errWrite(
+        // writeCtl, not errWrite: process.exit() below does not flush a stream write that
+        // Windows has merely queued, and this message is the only thing the user gets.
+        writeCtl(
           [
             "",
-            "  ⚓ Privateer couldn't take the helm — this terminal stopped accepting keyboard",
+            `  ${ANCHOR} Privateer couldn't take the helm — this terminal stopped accepting keyboard`,
             "     control while the agent was still loading (setRawMode EIO).",
             "",
             "     That usually means the window, tab or ssh session it started in went away.",

package/extensions/privateer-brand.ts

@@ -36,7 +36,12 @@ import {
 } from "../src/providers/account.ts";
 import { resolveSignedInModel, savedPiDefaultSpec } from "../src/providers/defaultModel.ts";
 import { canOpenBrowser, openInBrowser } from "../src/util/openBrowser.ts";
-import { discoverContextFiles, onContextChanged } from "../src/context.ts";
+import {
+  contextStats,
+  estimateTokens,
+  fmtBytes,
+  onContextChanged,
+} from "../src/context.ts";
 import { onPackUpdatesChanged, pendingCliUpdate, pendingPackUpdates } from "../src/updates.ts";
 import { type Palette, paletteFor } from "../src/ui/palette.ts";
 
@@ -257,7 +262,7 @@ function packNotice(p: Palette): string {
 // quiet tease that /init scaffolds one. Reads the filesystem at render time, so it
 // reflects the current cwd and updates after /init (via onContextChanged → refresh).
 function contextLine(p: Palette): string {
-  const files = discoverContextFiles();
+  const { files, loadedBytes, truncated } = contextStats();
   if (files.length === 0) {
     return `${p.DIM}no PRIVATEER.md · ${p.INK}/init${p.DIM} to add project context${p.RESET}`;
   }
@@ -265,7 +270,14 @@ function contextLine(p: Palette): string {
   // with a "+N" so the header stays one line but the count isn't hidden.
   const nearest = shortPath(files[files.length - 1].path);
   const more = files.length > 1 ? `${p.DIM} +${files.length - 1}${p.RESET}` : "";
-  return `${p.GREEN}⚓${p.DIM} ${p.RESET}${p.INK}${nearest}${p.RESET}${more}`;
+  // What this costs on every single turn. A context file is the one thing a user adds to
+  // the agent whose price is charged per request and shown nowhere — so show it here, and
+  // say so loudly when a file was too big to load whole.
+  const tok = `${(estimateTokens(loadedBytes) / 1000).toFixed(1)}k`;
+  const cost = truncated
+    ? `${p.YELLOW} · too big, ${fmtBytes(loadedBytes)} loaded · ${p.INK}/context${p.RESET}`
+    : `${p.DIM} · ~${tok} tok/turn${p.RESET}`;
+  return `${p.GREEN}⚓${p.DIM} ${p.RESET}${p.INK}${nearest}${p.RESET}${more}${cost}`;
 }
 
 // ── "What's New" — a tiny in-banner changelog ────────────────────────────────

package/extensions/privateer-context.ts

@@ -15,9 +15,13 @@
 
 import {
   contextBlock,
+  contextStats,
+  estimateTokens,
+  fmtBytes,
   writeTemplate,
   emitContextChanged,
   CONTEXT_BLOCK_MARKER,
+  CONTEXT_MAX_BYTES_ENV,
   RUNTIME_GUIDELINES_MARKER,
   runtimeGuidelinesBlock,
 } from "../src/context.ts";
@@ -58,6 +62,44 @@ export default function privateerContext(pi: any): void {
     return { systemPrompt: prompt };
   });
 
+  // /context — what the project-context files cost, per turn.
+  //
+  // The cost of a context file is invisible: it is charged inside the system prompt of
+  // every request, so a file that grew to 117 KB reads as "the model got slow", never as
+  // "I am sending 34,000 tokens per tool call". This command is the answer to that — it
+  // names each file, what reaches the model, and what was left behind.
+  pi.registerCommand?.("context", {
+    description: "Show the PRIVATEER.md files loaded into every turn, and what they cost",
+    handler: (_args: string, ctx: any) => {
+      const { files, diskBytes, loadedBytes, truncated, maxBytes } = contextStats(process.cwd());
+      if (files.length === 0) {
+        ctx?.ui?.notify?.(
+          `No PRIVATEER.md found for ${process.cwd()} — /init writes a starter one.`,
+          "info",
+        );
+        return;
+      }
+      const lines = files.map((f) => {
+        const cost = `${fmtBytes(f.loadedBytes)} ≈ ${estimateTokens(f.loadedBytes).toLocaleString()} tokens/turn`;
+        const cut = f.truncated ? `  ⚠ TRUNCATED from ${fmtBytes(f.bytes)}` : "";
+        return `  ${f.path}\n    ${cost}${cut}`;
+      });
+      const cap = Number.isFinite(maxBytes)
+        ? `${fmtBytes(maxBytes)} per file (${CONTEXT_MAX_BYTES_ENV}=off to load them whole)`
+        : `none — ${CONTEXT_MAX_BYTES_ENV} disabled the cap`;
+      const total =
+        `Total on disk ${fmtBytes(diskBytes)} · sent every turn ${fmtBytes(loadedBytes)} ` +
+        `≈ ${estimateTokens(loadedBytes).toLocaleString()} tokens.`;
+      const advice = truncated
+        ? "\n\nA context file is re-sent in full on every tool call, and confidential (TEE) endpoints cannot cache it — so this is paid again on each one. Split the history out into an ARCHIVE.md the agent reads only when asked."
+        : "";
+      ctx?.ui?.notify?.(
+        `Project context loaded into every turn:\n${lines.join("\n")}\n\n${total}\nCap: ${cap}.${advice}`,
+        truncated ? "warning" : "info",
+      );
+    },
+  });
+
   // /init — scaffold a PRIVATEER.md in the working directory. Never clobbers an existing
   // one; on success we signal the banner so its "PRIVATEER.md loaded" line updates now
   // (the file is picked up automatically on the next turn — no reload needed).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.31",
+  "version": "0.12.33",
   "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",

package/src/context.ts

@@ -28,6 +28,101 @@ const CANDIDATES = ["PRIVATEER.md", "PRIVATEER.MD"];
 export interface ContextFile {
   path: string;
   content: string;
+  bytes: number; // full size on disk, before any budget is applied
+}
+
+// ── per-turn context budget ──────────────────────────────────────────────────
+//
+// A project-context file is not read once. It is re-sent, in full, inside the system
+// prompt of EVERY turn — so its size is not a one-off cost, it is a per-tool-call tax on
+// latency and on price. That is invisible from the outside, and it does not stay small on
+// its own: a PRIVATEER.md accretes changelogs and retired build notes until it is a
+// design document.
+//
+// Measured, and the reason this cap exists: a 117 KB PRIVATEER.md in a game project put
+// ~34,000 tokens into every request. On the confidential routes (Phala, Tinfoil, NEAR)
+// there is no prompt cache to read them back out of — an enclave answers statelessly — so
+// all 34,000 were re-processed from scratch on each of the 121 tool calls in a single
+// turn. The turn took 17 minutes, nearly all of it time-to-first-token.
+//
+// So: load the head of an oversized file and tell the model, in the block itself, where
+// the rest is. Truncation is loud (the banner and /context both say so) and it is
+// defeatable (PRIVATEER_CONTEXT_MAX_BYTES=off) — but the default has to be a number,
+// because the failure mode is a user who never learns why their agent got slow.
+export const DEFAULT_CONTEXT_MAX_BYTES = 32 * 1024; // ~8k tokens per turn
+export const CONTEXT_MAX_BYTES_ENV = "PRIVATEER_CONTEXT_MAX_BYTES";
+
+// Never cut below this, whatever the env says — a cap small enough to amputate the first
+// heading is worse than no cap at all.
+const MIN_CONTEXT_MAX_BYTES = 2 * 1024;
+
+/** The per-file byte budget: the env override when it parses, else the default. */
+export function contextMaxBytes(): number {
+  const raw = (process.env[CONTEXT_MAX_BYTES_ENV] ?? "").trim().toLowerCase();
+  if (raw === "") return DEFAULT_CONTEXT_MAX_BYTES;
+  if (raw === "off" || raw === "false" || raw === "0" || raw === "none") {
+    return Number.POSITIVE_INFINITY; // opt out: load whatever is on disk
+  }
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_CONTEXT_MAX_BYTES; // typo → default
+  return Math.max(n, MIN_CONTEXT_MAX_BYTES);
+}
+
+/** Rough token count for a byte size. ~4 bytes/token is close enough to budget with. */
+export function estimateTokens(bytes: number): number {
+  return Math.round(bytes / 4);
+}
+
+export interface BudgetedFile extends ContextFile {
+  loaded: string; // what actually goes into the prompt (the head, plus a footer, if cut)
+  loadedBytes: number; // size of the file's own content in `loaded`, footer excluded
+  truncated: boolean;
+}
+
+// Cut at a line boundary inside the budget so the model never sees half a sentence, and
+// keep the head rather than the tail: a context file opens with what the project IS.
+function budgetFile(file: ContextFile, max: number): BudgetedFile {
+  if (file.bytes <= max) {
+    return { ...file, loaded: file.content, loadedBytes: file.bytes, truncated: false };
+  }
+  const head = Buffer.from(file.content, "utf-8").subarray(0, max).toString("utf-8");
+  const lastBreak = head.lastIndexOf("\n");
+  const kept = lastBreak > max / 2 ? head.slice(0, lastBreak) : head;
+  const keptBytes = Buffer.byteLength(kept, "utf-8");
+  const footer =
+    `\n\n[Privateer loaded the first ${fmtBytes(keptBytes)} of this ${fmtBytes(file.bytes)} file. ` +
+    `A project-context file is re-sent to the model on EVERY turn, so the rest was left ` +
+    `out to keep turns fast — read ${file.path} directly if you need what is missing, and ` +
+    `tell the user the file is worth splitting.]`;
+  return { ...file, loaded: kept + footer, loadedBytes: keptBytes, truncated: true };
+}
+
+/** Human byte size for prompts, the banner and /context. */
+export function fmtBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(n < 10 * 1024 ? 1 : 0)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export interface ContextStats {
+  files: BudgetedFile[];
+  diskBytes: number; // what is on disk across every discovered file
+  loadedBytes: number; // what actually reaches the model each turn
+  truncated: boolean; // at least one file was cut
+  maxBytes: number; // the budget in force
+}
+
+/** Discovery + budget in one call — what the banner and /context both report on. */
+export function contextStats(cwd: string = process.cwd()): ContextStats {
+  const max = contextMaxBytes();
+  const files = discoverContextFiles(cwd).map((f) => budgetFile(f, max));
+  return {
+    files,
+    diskBytes: files.reduce((n, f) => n + f.bytes, 0),
+    loadedBytes: files.reduce((n, f) => n + f.loadedBytes, 0),
+    truncated: files.some((f) => f.truncated),
+    maxBytes: max,
+  };
 }
 
 // The global agent dir the launcher points Pi at (PRIVATEER_HOME/agent). We read the
@@ -46,7 +141,8 @@ function readCandidate(dir: string): ContextFile | null {
     const path = join(dir, name);
     if (existsSync(path)) {
       try {
-        return { path, content: readFileSync(path, "utf-8") };
+        const content = readFileSync(path, "utf-8");
+        return { path, content, bytes: Buffer.byteLength(content, "utf-8") };
       } catch {
         // unreadable (perms, races) — skip silently; the model just won't see it.
       }
@@ -100,6 +196,8 @@ export function runtimeGuidelinesBlock(): string {
 - Node.js environment: Node.js (v22+) is guaranteed to be available in Privateer. Prefer \`node -e "..."\` or small Node.js scripts for quick scripting, calculations, or JSON processing instead of assuming \`python\` or \`python3\` is installed.
 - Search fallback: If \`rg\` (ripgrep) is missing or returns "command not found", fall back to standard POSIX \`grep -rn <pattern> <path>\` or \`find <path>\`.
 - Missing system dependencies: If an essential external tool (e.g. \`git\`, \`python\`, \`rg\`) is missing and needed, check its presence (\`command -v <tool>\`), explain clearly what is missing, and offer to install it using the host package manager (e.g. \`brew install\`, \`xcode-select --install\`, \`winget install\`, \`apt install\`) upon user approval.
+- Shell calls share no state: every shell call runs in a fresh subshell rooted at the session's working directory, so a \`cd\` (or a variable, or an activated venv) in one call is gone by the next. Use absolute paths, or move and work in ONE call (\`cd <dir> && <command>\`). Never spend a call on \`cd\` alone.
+- Batch your steps: every tool call re-sends the whole conversation to the model, so a chain of one-line calls is far slower and more expensive than the same work combined into fewer calls. Group independent reads, searches and checks into one command; do not build test harnesses, scratch scripts or regression runs that the user did not ask for.
 </environment_guidelines>\n`;
 }
 
@@ -107,11 +205,11 @@ export function runtimeGuidelinesBlock(): string {
 // applies to AGENTS.md (see core/system-prompt.js), so the model can't tell the two
 // apart. Returns "" when there's nothing to inject.
 export function contextBlock(cwd: string = process.cwd()): string {
-  const files = discoverContextFiles(cwd);
+  const { files } = contextStats(cwd);
   if (files.length === 0) return "";
   let out = `\n\n${CONTEXT_BLOCK_MARKER}\n<project_context>\n\nProject-specific instructions and guidelines:\n\n`;
-  for (const { path, content } of files) {
-    out += `<project_instructions path="${path}">\n${content}\n</project_instructions>\n\n`;
+  for (const { path, loaded } of files) {
+    out += `<project_instructions path="${path}">\n${loaded}\n</project_instructions>\n\n`;
   }
   out += "</project_context>\n";
   return out;