privateer-agent 0.12.32 → 0.12.33

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.32",
+  "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;