privateer-agent 0.12.22 → 0.12.23

package/bin/privateer-launch.mjs

@@ -405,11 +405,11 @@ else {
   const signedIn = fs.existsSync(CRED);
   // Mirrors TINFOIL_MODEL_ID in src/providers/defaultModel.ts — keep them in step; that
   // file carries the measurements behind the choice.
-  const ACCOUNT_MODEL = "privateer/tinfoil/gpt-oss-120b";
+  const ACCOUNT_MODEL = "privateer/tinfoil/gemma4-31b";
   const MODEL = process.env.PRIVATEER_MODEL
     ? process.env.PRIVATEER_MODEL
     : haveTinfoilKey()
-      ? "tinfoil/gpt-oss-120b"
+      ? "tinfoil/gemma4-31b"
       : signedIn
         ? ACCOUNT_MODEL
         : haveKey("ANTHROPIC_API_KEY")

package/extensions/privateer-privacy.ts

@@ -24,19 +24,20 @@
 // display/resolution + routing list — posture and attestation are dispatcher-bound and
 // unaffected by the model set.
 import { registerAccountModels } from "../src/providers/account.ts";
+import { visionInput } from "../src/providers/vision.ts";
 import { privacyExtension } from "../src/config/privacyPolicy.ts";
 
-// Tinfoil's live chat models (inference.tinfoil.sh/v1/models), kimi-k2-6 first — the
-// launcher's default. Non-chat endpoints (embeddings, tts, whisper, websearch,
+// Tinfoil's live chat models (inference.tinfoil.sh/v1/models), gemma4-31b first — the
+// launcher's default, and the only one here that can see an image. Non-chat endpoints (embeddings, tts, whisper, websearch,
 // doc-upload) are intentionally omitted. Refresh from the live catalog if Tinfoil adds
 // models; this static list just needs to cover what we default to and commonly pick.
 const TINFOIL_MODELS = [
+  "gemma4-31b",
   "kimi-k2-6",
   "glm-5-2",
   "deepseek-v4-pro",
   "gpt-oss-120b",
   "gpt-oss-safeguard-120b",
-  "gemma4-31b",
   "llama3-3-70b",
 ];
 
@@ -45,7 +46,10 @@ function tinfoilModel(id: string) {
     id,
     name: id,
     reasoning: false,
-    input: ["text"] as ("text" | "image")[],
+    // Tinfoil ids are bare here (`gemma4-31b`), so scope it before asking — the
+    // allowlist is written against full `provider/model` ids. Getting this wrong is
+    // not cosmetic: `input` is what Pi checks before it will send an image at all.
+    input: visionInput(`tinfoil/${id}`),
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 128000,
     maxTokens: 4096,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.22",
+  "version": "0.12.23",
   "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/patches/@earendil-works+pi-coding-agent+0.84.1.patch

@@ -68,10 +68,10 @@ index 4600b23..075ecae 100644
  export const ENV_AGENT_DIR = `${APP_NAME.toUpperCase()}_CODING_AGENT_DIR`;
  export const ENV_SESSION_DIR = `${APP_NAME.toUpperCase()}_CODING_AGENT_SESSION_DIR`;
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js b/node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js
-index ce8a9a2..b7b339e 100644
+index ce8a9a2..679e584 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js
 +++ b/node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js
-@@ -38,6 +38,70 @@ import { createLocalBashOperations } from "./tools/bash.js";
+@@ -38,6 +38,111 @@ import { createLocalBashOperations } from "./tools/bash.js";
  import { createAllToolDefinitions } from "./tools/index.js";
  import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
  import { addUsageToTotals, createUsageTotals } from "./usage-totals.js";
@@ -138,11 +138,61 @@ index ce8a9a2..b7b339e 100644
 +        return false;
 +    const status = Number(m[1]);
 +    return status >= 400 && status < 500 && !PV_TRANSIENT_CLIENT_STATUS.has(status);
++}
++// Privateer patch: throttle handling. Mirrors isThrottleFailure / retryAfterMs /
++// retryDelayMs in src/engine/errors.ts — see the incident note there.
++export function isThrottleFailure(text) {
++    return /^\s*429\b/.test(typeof text === "string" ? text : "");
++}
++const PV_MAX_RETRY_DELAY_MS = 60_000;
++const PV_RETRY_AFTER_PATTERNS = [
++    /retry-after(?:-ms)?["'\s:=]+(\d+(?:\.\d+)?)/i,
++    /(?:retry|try) again in (\d+(?:\.\d+)?)\s*(m?s|seconds?|minutes?)/i,
++    /retry after (\d+(?:\.\d+)?)\s*(m?s|seconds?|minutes?)/i,
++];
++export function retryAfterMs(text) {
++    const s = typeof text === "string" ? text : "";
++    for (const re of PV_RETRY_AFTER_PATTERNS) {
++        const m = re.exec(s);
++        if (!m)
++            continue;
++        const value = Number.parseFloat(m[1]);
++        if (!Number.isFinite(value) || value <= 0)
++            continue;
++        const unit = (m[2] ?? "").toLowerCase();
++        const ms = unit === "ms" || /retry-after-ms/i.test(m[0])
++            ? value
++            : unit.startsWith("m") && unit !== "ms"
++                ? value * 60_000
++                : value * 1000;
++        return Math.min(Math.max(Math.round(ms), 1_000), PV_MAX_RETRY_DELAY_MS);
++    }
++    return null;
++}
++// A server-stated delay wins outright — it is the only number here that is a fact.
++// The jitter is the point of the rest: without it every parallel request that tripped
++// the same limit wakes at the identical millisecond and trips it again.
++export function retryDelayMs(errorText, attempt, baseDelayMs) {
++    const stated = retryAfterMs(errorText);
++    if (stated != null)
++        return stated;
++    const n = Math.max(1, Math.floor(attempt));
++    const backoff = Math.min(baseDelayMs * 2 ** (n - 1), PV_MAX_RETRY_DELAY_MS);
++    return Math.round(backoff * (1 - Math.random() * 0.25));
 +}
  /**
   * Parse a skill block from message text.
   * Returns null if the text doesn't contain a skill block.
-@@ -186,6 +250,14 @@ export class AgentSession {
+@@ -102,6 +207,8 @@ export class AgentSession {
+     // Retry state
+     _retryAbortController = undefined;
+     _retryAttempt = 0;
++    // Privateer patch: when the provider last exhausted the retry budget on a 429.
++    _pvThrottledAt = 0;
+     // Bash execution state
+     _bashAbortControllers = new Set();
+     _pendingBashMessages = [];
+@@ -186,6 +293,14 @@ export class AgentSession {
          }
          const isOAuth = this._modelRuntime.isUsingOAuth(model.provider);
          if (isOAuth) {
@@ -157,7 +207,7 @@ index ce8a9a2..b7b339e 100644
              throw new Error(`Authentication failed for "${model.provider}". ` +
                  `Credentials may have expired or network is unavailable. ` +
                  `Run '/login ${model.provider}' to re-authenticate.`);
-@@ -360,6 +432,16 @@ export class AgentSession {
+@@ -360,6 +475,16 @@ export class AgentSession {
                  }
              }
          }
@@ -174,10 +224,18 @@ index ce8a9a2..b7b339e 100644
          // Emit to extensions first
          await this._emitExtensionEvent(event);
          // Notify all listeners
-@@ -772,6 +854,25 @@ export class AgentSession {
+@@ -772,6 +897,33 @@ export class AgentSession {
                  finalError: msg.errorMessage,
              });
              this._retryAttempt = 0;
++            // Privateer patch: remember that the endpoint is throttling us. The
++            // pre-prompt compaction in prompt() is an LLM call to this same endpoint,
++            // and firing it now just spends the summarizer budget on another 429 —
++            // which is what answered the user's next message with "Auto-compaction
++            // cancelled" instead of a reply. See the guard in prompt().
++            if (isThrottleFailure(msg.errorMessage)) {
++                this._pvThrottledAt = Date.now();
++            }
 +            // Privateer patch: a transient error that survived the full retry budget
 +            // is terminal. Ending the turn here (instead of falling through to
 +            // compaction / queued-message continuation) prevents the agent loop from
@@ -200,7 +258,7 @@ index ce8a9a2..b7b339e 100644
          }
          if (await this._checkCompaction(msg)) {
              return true;
-@@ -852,6 +953,14 @@ export class AgentSession {
+@@ -852,6 +1004,14 @@ export class AgentSession {
              if (!hasConfiguredAuth) {
                  const isOAuth = this._modelRuntime.isUsingOAuth(this.model.provider);
                  if (isOAuth) {
@@ -215,7 +273,22 @@ index ce8a9a2..b7b339e 100644
                      throw new Error(`Authentication failed for "${this.model.provider}". ` +
                          `Credentials may have expired or network is unavailable. ` +
                          `Run '/login ${this.model.provider}' to re-authenticate.`);
-@@ -2084,6 +2193,27 @@ export class AgentSession {
+@@ -861,7 +1021,13 @@ export class AgentSession {
+             // Check if we need to compact before sending (catches aborted responses).
+             // The user's new prompt is sent below, so do not call agent.continue() here.
+             const lastAssistant = this._findLastAssistantMessage();
+-            if (lastAssistant) {
++            // Privateer patch: skip this while the provider is still throttling us.
++            // Compaction here is another LLM call to the endpoint that just spent our
++            // whole retry budget on 429s; it cannot succeed, and its failure is reported
++            // as "Auto-compaction cancelled" — burying the user's actual prompt. One
++            // rate-limit window of patience, then we try again as normal. The context is
++            // not lost: the next turn re-checks compaction once the window has passed.
++            if (lastAssistant && Date.now() - this._pvThrottledAt >= PV_MAX_RETRY_DELAY_MS) {
+                 await this._checkCompaction(lastAssistant, false);
+             }
+             // Build messages array (custom message if any, then user message)
+@@ -2084,6 +2250,27 @@ export class AgentSession {
          // Context overflow is handled by compaction, not retry.
          if (isContextOverflow(message, this.model?.contextWindow ?? 0))
              return false;
@@ -243,6 +316,19 @@ index ce8a9a2..b7b339e 100644
          return isRetryableAssistantError(message);
      }
      /**
+@@ -2129,7 +2316,11 @@ export class AgentSession {
+             this._retryAttempt--;
+             return false;
+         }
+-        const delayMs = settings.baseDelayMs * 2 ** (this._retryAttempt - 1);
++        // Privateer patch: honour a server-stated `retry-after` and jitter the fallback.
++        // Stock Pi's fixed 2s/4s/8s ladder spends its whole budget inside a rate-limit
++        // window it was never long enough to outlast, and fires every parallel retry at
++        // the same instant. See retryDelayMs above.
++        const delayMs = retryDelayMs(message.errorMessage, this._retryAttempt, settings.baseDelayMs);
+         this._emit({
+             type: "auto_retry_start",
+             attempt: this._retryAttempt,
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/core/auth-guidance.js b/node_modules/@earendil-works/pi-coding-agent/dist/core/auth-guidance.js
 index 197bccc..bc9ac3f 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/core/auth-guidance.js
@@ -681,7 +767,7 @@ index 97af6cd..74d5d52 100644
          }
          const globalPath = join(this.agentDir, "APPEND_SYSTEM.md");
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/core/settings-manager.js b/node_modules/@earendil-works/pi-coding-agent/dist/core/settings-manager.js
-index cb06c10..930a0de 100644
+index cb06c10..41fb90c 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/core/settings-manager.js
 +++ b/node_modules/@earendil-works/pi-coding-agent/dist/core/settings-manager.js
 @@ -2,7 +2,7 @@ import { randomUUID } from "crypto";
@@ -822,6 +908,23 @@ index cb06c10..930a0de 100644
          const dir = dirname(path);
          let release;
          try {
+@@ -568,7 +672,15 @@ export class SettingsManager {
+     getProviderRetrySettings() {
+         return {
+             timeoutMs: this.settings.retry?.provider?.timeoutMs,
+-            maxRetries: this.settings.retry?.provider?.maxRetries,
++            // Privateer patch: give the provider-level retry a real default. pi-ai's
++            // retryProviderRequest is the only layer that reads `retry-after` and jitters,
++            // but it takes `options.maxRetries ?? 0` and stock Pi hands it `undefined` — so
++            // it ran ZERO retries and every throttle fell through to the session-level loop
++            // (3 attempts, fixed 2s/4s/8s, no retry-after), which cannot outlast a 60s rate
++            // limit window. A bare `429` from the account edge exhausted the budget in ~14s.
++            // 2 here is deliberately small: it is a *per-attempt* budget that nests inside
++            // the session retry, and each of its waits already honours the server's number.
++            maxRetries: this.settings.retry?.provider?.maxRetries ?? 2,
+             maxRetryDelayMs: this.settings.retry?.provider?.maxRetryDelayMs ?? 60000,
+         };
+     }
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/core/skills.js b/node_modules/@earendil-works/pi-coding-agent/dist/core/skills.js
 index 4e7e784..7383a2b 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/core/skills.js
@@ -1307,7 +1410,7 @@ index 1d9f046..c0326e3 100644
          return lines;
      }
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/tool-execution.js b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/tool-execution.js
-index 3f93cc6..bbe2c10 100644
+index 3f93cc6..50a2a99 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/tool-execution.js
 +++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/tool-execution.js
 @@ -1,8 +1,35 @@
@@ -1347,7 +1450,23 @@ index 3f93cc6..bbe2c10 100644
  export class ToolExecutionComponent extends Container {
      contentBox;
      contentText;
-@@ -106,6 +133,13 @@ export class ToolExecutionComponent extends Container {
+@@ -43,8 +70,13 @@ export class ToolExecutionComponent extends Container {
+         // Always create all shell variants. contentBox is used for default renderer-based composition.
+         // selfRenderContainer is used when the tool renders its own framing.
+         // contentText is reserved for generic fallback rendering when no tool definition exists.
+-        this.contentBox = new Box(1, 1, (text) => theme.bg("toolPendingBg", text));
+-        this.contentText = new Text("", 1, 1, (text) => theme.bg("toolPendingBg", text));
++        // Privateer: paddingY is 0 because we flatten the tool-box washes (dark.json /
++        // light.json). With no background to fill, upstream's paddingY=1 reads as a blank
++        // line above AND below every call, stacking with the Spacer(1) into three empty
++        // rows between consecutive tools. 0 leaves exactly the one Spacer row, which also
++        // matches what the self-render path above emits (a single lines.push("")).
++        this.contentBox = new Box(1, 0, (text) => theme.bg("toolPendingBg", text));
++        this.contentText = new Text("", 1, 0, (text) => theme.bg("toolPendingBg", text));
+         this.selfRenderContainer = new Container();
+         if (this.hasRendererDefinition()) {
+             this.addChild(this.getRenderShell() === "self" ? this.selfRenderContainer : this.contentBox);
+@@ -106,6 +138,13 @@ export class ToolExecutionComponent extends Container {
      createCallFallback() {
          return new Text(theme.fg("toolTitle", theme.bold(this.toolName)), 0, 0);
      }
@@ -1361,7 +1480,7 @@ index 3f93cc6..bbe2c10 100644
      createResultFallback() {
          const output = this.getTextOutput();
          if (!output) {
-@@ -218,19 +252,22 @@ export class ToolExecutionComponent extends Container {
+@@ -218,19 +257,22 @@ export class ToolExecutionComponent extends Container {
              renderContainer.clear();
              const callRenderer = this.getCallRenderer();
              if (!callRenderer) {
@@ -1387,7 +1506,7 @@ index 3f93cc6..bbe2c10 100644
                      hasContent = true;
                  }
              }
-@@ -302,7 +339,8 @@ export class ToolExecutionComponent extends Container {
+@@ -302,7 +344,8 @@ export class ToolExecutionComponent extends Container {
          return getRenderedTextOutput(this.result, this.showImages);
      }
      formatToolExecution() {
@@ -1398,7 +1517,7 @@ index 3f93cc6..bbe2c10 100644
          if (content) {
              text += `\n\n${content}`;
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
-index 42e655d..d00bec9 100644
+index 42e655d..606c7cc 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
 +++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
 @@ -10,7 +10,7 @@ import * as TuiLayouts from "@earendil-works/pi-tui";
@@ -1424,7 +1543,62 @@ index 42e655d..d00bec9 100644
      if (!sessionManager.usesDefaultSessionDir()) {
          args.push("--session-dir", quoteIfNeeded(sessionManager.getSessionDir()));
      }
-@@ -405,9 +410,15 @@ export class InteractiveMode {
+@@ -207,6 +212,54 @@ export function createInteractiveTuiReference(getTui) {
+         getPrototypeOf: () => Reflect.getPrototypeOf(getTui()),
+     });
+ }
++// Privateer patch: describe an error we only have the TEXT of. Mirrors
++// describeErrorText in src/engine/errors.ts — see the incident note there.
++const PV_RETRY_AFTER_PATTERNS = [
++    /retry-after(?:-ms)?["'\s:=]+(\d+(?:\.\d+)?)/i,
++    /(?:retry|try) again in (\d+(?:\.\d+)?)\s*(m?s|seconds?|minutes?)/i,
++    /retry after (\d+(?:\.\d+)?)\s*(m?s|seconds?|minutes?)/i,
++];
++function pvRetryAfterMs(text) {
++    const s = typeof text === "string" ? text : "";
++    for (const re of PV_RETRY_AFTER_PATTERNS) {
++        const m = re.exec(s);
++        if (!m)
++            continue;
++        const value = Number.parseFloat(m[1]);
++        if (!Number.isFinite(value) || value <= 0)
++            continue;
++        const unit = (m[2] ?? "").toLowerCase();
++        const ms = unit === "ms" || /retry-after-ms/i.test(m[0])
++            ? value
++            : unit.startsWith("m") && unit !== "ms"
++                ? value * 60_000
++                : value * 1000;
++        return Math.min(Math.max(Math.round(ms), 1_000), 60_000);
++    }
++    return null;
++}
++function pvDescribeErrorText(text) {
++    const s = typeof text === "string" ? text : "";
++    const status = Number(/^\s*(\d{3})\b/.exec(s)?.[1] ?? NaN);
++    if (!Number.isFinite(status))
++        return null;
++    if (status === 429) {
++        const stated = pvRetryAfterMs(s);
++        return {
++            message: "Rate limited (429).",
++            hint: stated
++                ? `The provider asked for ${Math.ceil(stated / 1000)}s. Wait that long and send it again.`
++                : "Wait a moment and send it again — or run /model to switch to another provider.",
++        };
++    }
++    if (status === 401 || status === 403)
++        return { message: s, hint: "Check your credentials — run /login to re-authenticate." };
++    if (status === 404)
++        return { message: s, hint: "Check the model id — run /model to switch." };
++    if (status >= 500)
++        return { message: s, hint: "Usually transient — retry shortly." };
++    return null;
++}
+ export class InteractiveMode {
+     runtimeHost;
+     renderer;
+@@ -405,9 +458,15 @@ export class InteractiveMode {
      }
      getBuiltInCommandConflictDiagnostics(extensionRunner) {
          const builtinNames = new Set(BUILTIN_SLASH_COMMANDS.map((command) => command.name));
@@ -1441,7 +1615,7 @@ index 42e655d..d00bec9 100644
              .map((command) => ({
              type: "warning",
              message: command.invocationName === command.name
-@@ -754,20 +765,18 @@ export class InteractiveMode {
+@@ -754,20 +813,18 @@ export class InteractiveMode {
                  this.showNewVersionNotification(newRelease);
              }
          });
@@ -1474,7 +1648,7 @@ index 42e655d..d00bec9 100644
          // Check tmux keyboard setup asynchronously
          this.checkTmuxKeyboardSetup().then((warning) => {
              if (warning) {
-@@ -2310,7 +2319,17 @@ export class InteractiveMode {
+@@ -2310,7 +2367,17 @@ export class InteractiveMode {
              if (text === "/model" || text.startsWith("/model ")) {
                  const searchTerm = text.startsWith("/model ") ? text.slice(7).trim() : undefined;
                  this.editor.setText("");
@@ -1493,7 +1667,7 @@ index 42e655d..d00bec9 100644
                  return;
              }
              if (text === "/export" || text.startsWith("/export ")) {
-@@ -2376,12 +2395,42 @@ export class InteractiveMode {
+@@ -2376,12 +2443,42 @@ export class InteractiveMode {
              if (text === "/login" || text.startsWith("/login ")) {
                  const providerRef = text.startsWith("/login ") ? text.slice(7).trim() : undefined;
                  this.editor.setText("");
@@ -1538,7 +1712,7 @@ index 42e655d..d00bec9 100644
                  return;
              }
              if (text === "/new") {
-@@ -3024,7 +3073,7 @@ export class InteractiveMode {
+@@ -3024,7 +3121,7 @@ export class InteractiveMode {
          if (this.chatContainer.children.length > 0) {
              this.chatContainer.addChild(new Spacer(1));
          }
@@ -1547,6 +1721,25 @@ index 42e655d..d00bec9 100644
      }
      async getUserInput() {
          const queuedInput = this.pendingUserInputs.shift();
+@@ -3363,7 +3460,17 @@ export class InteractiveMode {
+     }
+     showError(errorMessage) {
+         this.chatContainer.addChild(new Spacer(1));
+-        this.chatContainer.addChild(new Text(theme.fg("error", `Error: ${errorMessage}`), this.outputPad, 0));
++        // Privateer patch: by the time an error reaches here it is only a string — the
++        // structured fields describeError() reads are long gone, so the user was shown
++        // the SDK's own words ("429 status code (no body)"), which say nothing about
++        // what to do. The status is still readable at the front of that string; recover
++        // it and say what describeError would. Mirrors describeErrorText in
++        // src/engine/errors.ts. Anything without a leading status prints unchanged.
++        const described = pvDescribeErrorText(errorMessage);
++        this.chatContainer.addChild(new Text(theme.fg("error", `Error: ${described?.message ?? errorMessage}`), this.outputPad, 0));
++        if (described?.hint) {
++            this.chatContainer.addChild(new Text(theme.fg("muted", described.hint), this.outputPad, 0));
++        }
+         this.ui.requestRender();
+     }
+     showWarning(warningMessage) {
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/theme/dark.json b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/theme/dark.json
 index 9db9cbd..b370180 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/theme/dark.json

package/src/engine/errors.ts

@@ -348,3 +348,133 @@ export function describeError(err: unknown): DescribedError {
   // arrives, so it goes through the compactor first.
   return out({ message: compactProviderError(text) });
 }
+
+// ── Throttles: waiting the right amount, and only once ───────────────────────
+//
+// The incident this exists for: the account channel's edge answered a burst of
+// turns with a bare `429` — no body, no JSON, just the status. Two retry layers
+// exist and the wrong one was live. pi-ai's `retryProviderRequest` is the good
+// one (it reads `retry-after`, jitters, caps at 60s) but it takes `maxRetries ??
+// 0` and Pi's settings gave it no default, so it ran ZERO retries. All the
+// patience came from the session-level loop: 3 attempts at 2s/4s/8s, no
+// `retry-after`, no jitter — ~14 seconds against a window that is conventionally
+// 60. Exhaustion was arithmetic, not bad luck. Then the pre-prompt compaction
+// fired the summarizer into the same throttled endpoint and died there too, so
+// the user's next message was answered with "Auto-compaction cancelled".
+//
+// The fix is three-part and mirrored into the Pi patch: give the provider layer a
+// real retry budget, make the session layer's backoff honour a server-stated
+// delay and jitter, and don't summarise into an endpoint that just throttled us.
+
+/** A throttle can clear on its own — but only after the server's stated window. */
+export function isThrottleFailure(text: string | null | undefined): boolean {
+  return /^\s*429\b/.test(typeof text === "string" ? text : "");
+}
+
+/** Longest we will sit on a single backoff. Past this the user deserves the turn back. */
+export const MAX_RETRY_DELAY_MS = 60_000;
+
+// A bare 429 carries nothing, but a provider that bothers to explain itself puts the
+// number in the text one of a few ways. Read it where it is offered; guess otherwise.
+const RETRY_AFTER_PATTERNS = [
+  /retry-after(?:-ms)?["'\s:=]+(\d+(?:\.\d+)?)/i,
+  /(?:retry|try) again in (\d+(?:\.\d+)?)\s*(m?s|seconds?|minutes?)/i,
+  /retry after (\d+(?:\.\d+)?)\s*(m?s|seconds?|minutes?)/i,
+];
+
+/**
+ * The server's requested delay in ms, or null when it did not state one.
+ *
+ * `retry-after` is seconds by convention and `retry-after-ms` is milliseconds; a
+ * prose "try again in 30 seconds" carries its own unit. Values are clamped rather
+ * than rejected — a provider asking for an hour gets our ceiling, not a crash.
+ */
+export function retryAfterMs(text: string | null | undefined): number | null {
+  const s = typeof text === "string" ? text : "";
+  for (const re of RETRY_AFTER_PATTERNS) {
+    const m = re.exec(s);
+    if (!m) continue;
+    const value = Number.parseFloat(m[1]);
+    if (!Number.isFinite(value) || value <= 0) continue;
+    const unit = (m[2] ?? "").toLowerCase();
+    const ms =
+      unit === "ms" || /retry-after-ms/i.test(m[0])
+        ? value
+        : unit.startsWith("m") && unit !== "ms"
+          ? value * 60_000
+          : value * 1000;
+    return Math.min(Math.max(Math.round(ms), 1_000), MAX_RETRY_DELAY_MS);
+  }
+  return null;
+}
+
+/**
+ * How long the session-level retry should wait before attempt `attempt` (1-based).
+ *
+ * A server-stated delay wins outright — it is the only number here that is a fact.
+ * Otherwise back off exponentially from `baseDelayMs`, capped, and then jitter DOWN
+ * by up to 25%. The jitter is the point of the exercise: without it every parallel
+ * request that tripped the same limit wakes at the identical millisecond and trips
+ * it again, which is how one throttled turn becomes a throttled session.
+ *
+ * `rand` is injectable so the schedule can be asserted in a test.
+ */
+export function retryDelayMs(
+  errorText: string | null | undefined,
+  attempt: number,
+  baseDelayMs: number,
+  rand: () => number = Math.random,
+): number {
+  const stated = retryAfterMs(errorText);
+  if (stated != null) return stated;
+  const n = Math.max(1, Math.floor(attempt));
+  const backoff = Math.min(baseDelayMs * 2 ** (n - 1), MAX_RETRY_DELAY_MS);
+  return Math.round(backoff * (1 - rand() * 0.25));
+}
+
+/**
+ * Describe an error we only have the TEXT of, for the one place that has nothing else.
+ *
+ * `describeError` above reads structured fields off the error object; by the time a
+ * message reaches the TUI's `showError` those are gone and all that survives is a
+ * string the SDK built status-first ("429 status code (no body)"). That string is
+ * what the user was shown six times during the incident. Recover the status from it
+ * and say the same thing `describeError` would. Returns null when there is no leading
+ * status to read, so ordinary messages print unchanged.
+ */
+export function describeErrorText(text: string | null | undefined): DescribedError | null {
+  const s = typeof text === "string" ? text : "";
+  const status = Number(/^\s*(\d{3})\b/.exec(s)?.[1] ?? NaN);
+  if (!Number.isFinite(status)) return null;
+
+  if (status === 429) {
+    const stated = retryAfterMs(s);
+    return {
+      message: redactText(`Rate limited (429).`),
+      hint: stated
+        ? `The provider asked for ${Math.ceil(stated / 1000)}s. Wait that long and send it again.`
+        : "Wait a moment and send it again — or run /model to switch to another provider.",
+      retryable: true,
+    };
+  }
+  if (status === 401 || status === 403) {
+    return {
+      message: redactText(compactProviderError(s)),
+      hint: "Check your credentials — run /login to re-authenticate.",
+    };
+  }
+  if (status === 404) {
+    return {
+      message: redactText(compactProviderError(s)),
+      hint: "Check the model id — run /model to switch.",
+    };
+  }
+  if (status >= 500) {
+    return {
+      message: redactText(compactProviderError(s)),
+      hint: "Usually transient — retry shortly.",
+      retryable: true,
+    };
+  }
+  return null;
+}

package/src/permissions/classify.ts

@@ -175,6 +175,7 @@ const MEDIA_TOOLS = new Set([
   "generate_image",
   "generate_video",
   "generate_model",
+  "generate_sprite",
   "generate_speech",
   "generate_music",
   "generate_sfx",
@@ -199,6 +200,7 @@ export const BILLED_MEDIA_TOOLS: ReadonlySet<string> = new Set([
   "generate_image",
   "generate_video",
   "generate_model",
+  "generate_sprite",
   "generate_speech",
   "generate_music",
   "generate_sfx",
@@ -210,6 +212,11 @@ const MEDIA_TITLES: Record<string, string> = {
   // options, so the title says so out loud rather than leaving the human to
   // work it out from a JSON blob of flags.
   generate_model: "Generate a 3D model (billed; $0.14-$2.41 a mesh depending on the model)",
+  // The one whose price is a MULTIPLE rather than a rate: it renders a video per
+  // facing, so approving it can be approving five video generations at once. The
+  // title says the multiplier out loud, because "generate a sprite" reads like
+  // one cheap call and it is not.
+  generate_sprite: "Generate a sprite animation (billed; 1, 3 or 5 video generations depending on facings)",
   generate_speech: "Generate speech (billed to your Privateer account)",
   generate_music: "Generate music (billed; music prompts have no zero-retention option)",
   // Cheap per call and therefore the one most likely to be called twenty times in a
@@ -410,7 +417,13 @@ export function classifyToolCall(
     const outsideInputs = resolvedInputs.filter((a) => isOutsideScope(scope, a));
     const protectedInputs = resolvedInputs.filter((a) => isProtectedPath(a));
 
-    const outPath = str(obj.path ?? obj.output);
+    // `dir` is generate_sprite's output: it unpacks a whole bundle (sheet, frames
+    // and the .tres) into a DIRECTORY rather than writing one named file. Without
+    // it here the gate finds no output path and fails safe — which reads to the
+    // user as an unexplained denial on a tool that is in fact just writing where
+    // they asked. The directory is the right thing to show and to judge for
+    // scope: everything the tool writes lands inside it.
+    const outPath = str(obj.path ?? obj.output ?? obj.dir);
     // `probe` reads and writes nothing; so does any composition call with no output
     // (which the tool itself rejects). Gate those only when they touch a sensitive input.
     if (!outPath) {

package/src/providers/account.ts

@@ -28,6 +28,7 @@ import { globalDir } from "../config/paths.ts";
 import { canOpenBrowser, openInBrowser } from "../util/openBrowser.ts";
 import { interpretReport, teePosture, tierFromTeePosture, type PrivacyTier } from "pi-privacy";
 import { ACCOUNT_DEFAULT_MODEL_ID, ACCOUNT_NEAR_MODEL_ID, ensurePiDefaultModel } from "./defaultModel.ts";
+import { visionInput } from "./vision.ts";
 import { piAuthStore } from "./piAuthStore.ts";
 import {
   sealedEnabled,
@@ -49,10 +50,11 @@ import type { PhalaEnclaveIdentity } from "./phalaSeal.ts";
 const DEFAULT_MODELS = [
   ACCOUNT_DEFAULT_MODEL_ID,
   ACCOUNT_NEAR_MODEL_ID,
-  // Both former defaults (see TINFOIL_MODEL_ID for the dates). They stay in the floor
-  // so a user who saved either as their own default still resolves it synchronously at
-  // launch, rather than falling through to "first model with configured auth" — the BYO
-  // dead end this seed list exists to prevent.
+  // All three former defaults (see TINFOIL_MODEL_ID for the dates). They stay in the
+  // floor so a user who saved any of them as their own default still resolves it
+  // synchronously at launch, rather than falling through to "first model with
+  // configured auth" — the BYO dead end this seed list exists to prevent.
+  "tinfoil/gpt-oss-120b",
   "tinfoil/kimi-k2-6",
   "tinfoil/glm-5-2",
   "anthropic/claude-opus-5",
@@ -78,7 +80,10 @@ function seedModel(id: string) {
     // reasoning + how to steer it, for the enclave models where we verified the
     // control shape live; `reasoning: false` (Pi's "not a thinking model") for the rest.
     ...(thinkingProfile(id) ?? { reasoning: false as const }),
-    input: ["text"] as ("text" | "image")[],
+    // Honest modalities. This was hardcoded to text for the whole catalog, which made
+    // Pi strip every image from every account request — including the ones `read`
+    // attaches when the user points at a screenshot. See providers/vision.ts.
+    input: visionInput(id),
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow: 128000,
     maxTokens: 16384,

package/src/providers/defaultModel.ts

@@ -15,15 +15,16 @@ import { join } from "node:path";
 import { hasCredentials } from "../auth/privateer.ts";
 import { agentDir } from "../config/paths.ts";
 
-// A capable Tinfoil chat model, and Privateer's default everywhere. Tinfoil runs it
-// inside an attestable TEE (the serving enclave's quote is published and the live TLS
-// key is bound to it), which is the strongest privacy tier we offer — so a capable
-// model on that tier is what a privacy-first agent should boot on.
+// A capable MULTIMODAL Tinfoil chat model, and Privateer's default everywhere. Tinfoil
+// runs it inside an attestable TEE (the serving enclave's quote is published and the
+// live TLS key is bound to it), which is the strongest privacy tier we offer — so a
+// capable model on that tier is what a privacy-first agent should boot on.
 // One definition, three consumers: this resolver, providers/account.ts's seed catalog,
 // and bin/privateer-launch.mjs (which mirrors the id — keep them in step).
 //
-// This has moved twice. The history matters, because both moves were about the same
-// two axes — first-token latency and reasoning control — pulling in opposite directions:
+// This has moved three times. The history matters, because the first two moves were
+// about the same two axes — first-token latency and reasoning control — pulling in
+// opposite directions, and the third added a third axis that outranks both:
 //
 //   • until 2026-08-01 — glm-5-2.
 //   • 2026-08-01 → 2026-08-06 — kimi-k2-6, a LATENCY swap, not a capability one. Over
@@ -55,10 +56,41 @@ import { agentDir } from "../config/paths.ts";
 //     three that gives the user a working dial. It is a smaller model than GLM 5.2 and
 //     Kimi K2.6; that capability trade was made knowingly. It also serves from NEAR as
 //     well as Tinfoil — the only capable model here with two attested homes.
+//   • 2026-08-27 — gemma4-31b, on SIGHT. Every model above is text-only, and the
+//     default is what a signed-in user actually runs, so the agent could be pointed at
+//     a screenshot, a design mock or a sheet it had just generated and would answer
+//     about a picture it was never sent (Pi drops image blocks a model doesn't declare
+//     — see providers/vision.ts). "Reads what you show it" beats a reasoning dial on a
+//     tool whose whole job is looking at the user's work.
+//
+//     The candidate set is small: of the account catalog's confidential-compute
+//     models, only Gemma 4 (Tinfoil, NEAR and Phala all serve it) and
+//     near/Qwen/Qwen3-VL-30B-A3B-Instruct take images at all. Gemma 4 31B wins on the
+//     invariant below — it is in Tinfoil's own catalog, so the direct and subscription
+//     routes stay the SAME model, which Qwen3-VL (NEAR only) would have broken.
+//
+//     Two things this costs, both knowingly:
+//       - the reasoning dial. thinkingProfile() annotates gpt-oss and the GLM/Qwen
+//         chat-template family and nothing else, so Gemma registers `reasoning: false`
+//         — as would Qwen3-VL, whose `-Instruct` id is the non-thinking variant. No
+//         vision model in the confidential tier has a dial we have verified, so this
+//         was not a choice between sight and thinking control; there was no option
+//         with both.
+//       - size. 31B against gpt-oss-120b, continuing the trade the 2026-08-06 entry
+//         started.
+//
+//     NOT re-measured for latency: the daily message cap (25/day, free tier) refused
+//     every probe on 2026-08-27 with 429 DAILY_CAP_HIT, so the TTFT table above has no
+//     gemma4-31b row. It is the same enclave provider and transport as the two models
+//     that never stalled, which is the reason to expect it behaves like them and not
+//     like glm-5-2 — but that is an expectation, not a measurement. Run the probe when
+//     the cap allows and record the row here.
 //
 // Re-measure before moving this again. The stall behaviour is a property of a
 // provider's deployment, not of a model, and it has already changed under us twice.
-export const TINFOIL_MODEL_ID = "tinfoil/gpt-oss-120b";
+// And whatever replaces it must still accept images: acceptsImages() in
+// providers/vision.ts is the test, and defaultModel.test.ts asserts it.
+export const TINFOIL_MODEL_ID = "tinfoil/gemma4-31b";
 
 // Same model, reached two ways:
 //   - TINFOIL_DEFAULT_SPEC — direct to inference.tinfoil.sh with the user's own
@@ -175,8 +207,9 @@ export function resolveDefaultModel(opts: ResolveDefaultModelOptions = {}): stri
 // A terminal launched with a BYO key (or an explicit --model) is pinned to whatever it
 // resolved at launch; without an in-session switch a mid-session /login changes nothing
 // visible and the user is left wondering what signing in bought them. This resolves the
-// model sign-in should activate RIGHT AWAY: Tinfoil GLM 5.2, direct when a Tinfoil key
-// is present and over the subscription otherwise — no BYO key needed.
+// model sign-in should activate RIGHT AWAY: TINFOIL_MODEL_ID, direct when a Tinfoil key
+// is present and over the subscription otherwise — no BYO key needed. Being signed in
+// is what buys sight, so this is also the switch that makes images work mid-session.
 // PRIVATEER_MODEL still wins — a deliberate override is never stomped.
 // `saved: null` on purpose: this is the sign-in TARGET, and the target is always the
 // confidential model. Whether to actually move a session that sits on a deliberate

package/src/providers/vision.ts

@@ -0,0 +1,95 @@
+// Which models can actually LOOK at an image — the one place that answers it, for
+// every catalog we register.
+//
+// The bug this fixes: every model we register — the whole 270-model account catalog
+// (providers/account.ts seedModel) and Tinfoil's direct catalog
+// (extensions/privateer-privacy.ts tinfoilModel) — declared `input: ["text"]`,
+// copied from pi-privacy's own seed shape. That field is not decoration. Pi gates
+// image handling on it in four places:
+//
+//   • pi-coding-agent core/tools/read.js — reading a PNG appends "[Current model does
+//     not support images. The image will be omitted from this request.]" and drops it;
+//   • pi-ai api/openai-completions.js — `hasImages && model.input.includes("image")`,
+//     so image blocks are stripped from the request body;
+//   • api/transform-messages.js and api/openai-responses-shared.js — same test again.
+//
+// So a signed-in user could point the agent at a screenshot, a design mock, or a
+// generated sprite sheet and get a confident answer about a picture the model was
+// never sent. Not a refusal — a silent omission, which is worse. Declaring the
+// modality honestly is what makes `read` on an image, and every media tool that hands
+// one back, actually reach the model.
+//
+// WHY AN ALLOWLIST AND NOT A SERVER FIELD: `GET /api/models` returns
+// `{ modelId, displayName, provider, rate*, enabled, privacy: { tier } }` and no
+// modality at all (checked against the live listing, 273 models, 2026-08-27). Until it
+// carries one, the client has to decide, and the two failure directions are NOT
+// symmetric:
+//
+//   • miss a vision model → images are dropped, i.e. exactly today's behaviour;
+//   • claim one that isn't → pi-ai sends image_url blocks the upstream rejects and the
+//     whole turn 400s.
+//
+// So this list is deliberately conservative: a family goes in when the id itself says
+// vision (`-vl-`, a trailing `v` on a GLM), or when every member of that family has
+// shipped multimodal. Anything uncertain stays out and keeps the old behaviour.
+
+// Ids arrive in three shapes and all three must match the same rules:
+//   `anthropic/claude-opus-5`            — account catalog, vendor/model
+//   `near/Qwen/Qwen3-VL-30B-A3B-Instruct` — account catalog, tee/vendor/model
+//   `gemma4-31b`                          — Tinfoil's direct catalog, bare id
+// Callers holding a bare id should prefix it with its provider (see visionInput's use
+// in privateer-privacy.ts); the patterns below are anchored loosely enough that a
+// bare `gemma4-31b` still matches on its own.
+const VISION_PATTERNS: RegExp[] = [
+  // ── Named in the id ────────────────────────────────────────────────────────
+  // Qwen's vision line (qwen3-vl-*, qwen2.5-vl-72b, near/Qwen/Qwen3-VL-30B-A3B) and
+  // Baidu's (ernie-4.5-vl-424b). Qwen ships VL as a SEPARATE line, which is also why
+  // the plain qwen3.x ids below are deliberately absent.
+  /-vl[-_.]/i,
+  // Z.ai marks vision with a trailing v on the version: glm-4.5v, glm-4.6v,
+  // glm-5v-turbo. Same reasoning — the unsuffixed glm-5.x are their text siblings.
+  /\bglm-\d+(?:\.\d+)?v\b/i,
+  // ByteDance's GUI agent reads screenshots; that is the whole point of it.
+  /\bui-tars\b/i,
+
+  // ── Families that are multimodal throughout ────────────────────────────────
+  // Every Claude from 3 onwards takes images, and 3 is the oldest in the catalog.
+  /(^|\/)anthropic\/claude-/i,
+  // Gemini has been multimodal since 1.0.
+  /(^|\/)google\/gemini-/i,
+  // Gemma from 3 on is multimodal; gemma-2 is not, so the version is part of the
+  // match. Covers google/gemma-3-27b-it, google/gemma-4-31b-it, tinfoil/gemma4-31b,
+  // near/google/gemma-4-31B-it, phala/google/gemma-4-31b-it and the Phala
+  // gemma-4 derivatives.
+  /gemma-?[34]/i,
+  // gpt-4o, gpt-4.1 and the whole gpt-5 line. Deliberately NOT `openai/gpt-4`
+  // (the original is text-only), not gpt-3.5, and not gpt-oss — the open-weights
+  // models are text-only, which is what our own default was until this change.
+  /(^|\/)openai\/gpt-(?:4o|4\.1|5)/i,
+  // Llama 4 (maverick, scout) is natively multimodal; 3.x is not.
+  /(^|\/)meta-llama\/llama-4-/i,
+  // Nova lite/pro/premier take images; nova-micro is text-only.
+  /(^|\/)amazon\/nova-(?:2-)?(?:lite|pro|premier)/i,
+  // Grok 4 and up.
+  /(^|\/)x-ai\/grok-4/i,
+  // Mistral's multimodal tiers: small 3.2 and the medium 3 line.
+  /(^|\/)mistralai\/mistral-(?:small-3\.2|medium-3)/i,
+];
+
+/** Whether `modelId` can be sent an image. See the note above on why it's an allowlist. */
+export function acceptsImages(modelId: string): boolean {
+  return VISION_PATTERNS.some((re) => re.test(modelId));
+}
+
+/**
+ * The `input` modality array for a registered model entry.
+ *
+ * pi-ai's ModelData only knows `"text" | "image"` — there is no video or pdf modality
+ * to declare, so a clip or a document reaches the model through a TOOL (media.ts's
+ * generators, `read` for a file) rather than as an input block. Image is therefore the
+ * whole of what this field can say, and saying it correctly is what lets `read` attach
+ * a screenshot instead of quietly dropping it.
+ */
+export function visionInput(modelId: string): ("text" | "image")[] {
+  return acceptsImages(modelId) ? ["text", "image"] : ["text"];
+}

package/src/tools/media.ts

@@ -47,6 +47,7 @@ export const MEDIA_TOOL_NAMES = [
   "generate_image",
   "generate_video",
   "generate_model",
+  "generate_sprite",
   "generate_speech",
   "generate_music",
   "generate_sfx",
@@ -63,6 +64,12 @@ const VIDEO_POLL_INTERVAL_MS = 5_000;
 // id is reported on timeout so the caller can resume the poll rather than pay
 // for a second generation.
 const MESH_POLL_TIMEOUT_MS = Number(process.env.PRIVATEER_MESH_TIMEOUT_MS) || 10 * 60_000;
+// A sprite job renders one clip per BILLED facing, sequentially, so an eight-way
+// set waits on five video generations rather than one. The ceiling is
+// correspondingly generous; as with video, the job id is reported on timeout so
+// the caller can resume the poll rather than pay for another run.
+const SPRITE_POLL_TIMEOUT_MS = Number(process.env.PRIVATEER_SPRITE_TIMEOUT_MS) || 25 * 60_000;
+const SPRITE_POLL_INTERVAL_MS = 6_000;
 const MESH_POLL_INTERVAL_MS = 5_000;
 // Four reference views at 8 MB each would be ~43 MB of base64 — past the
 // server's own body limit, so the request would be refused by a JSON parser with
@@ -1036,6 +1043,297 @@ export const mediaCapabilitiesToolDefinition = {
   },
 };
 
+interface SpriteSubmitResponse {
+  id?: string;
+  status?: string;
+  billed_facings?: number;
+  mirrored_facings?: number;
+  animations?: number;
+  message?: string;
+}
+
+interface SpriteStatusResponse {
+  id?: string;
+  status?: string;
+  zip_base64?: string;
+  bytes?: number;
+  sheet?: { width: number; height: number; columns: number; rows: number; frame_width: number; frame_height: number };
+  animations?: { name: string; direction: string; origin: string }[];
+  res_path?: string;
+  key_residue?: number;
+  error?: { message?: string };
+  message?: string;
+}
+
+/**
+ * Unpack the bundle into a directory.
+ *
+ * A hand-rolled reader rather than a dependency, and it is about thirty lines
+ * because the archive is STORED — Privateer writes no compressed entries (the
+ * payload is already PNG, so deflating it twice buys nothing), which means every
+ * entry is a header followed by its bytes verbatim.
+ *
+ * ZIP-SLIP: entry names come off the wire, so each resolved path is checked to
+ * be inside the destination before anything is written. A `..` segment here
+ * would let a generated archive write anywhere the agent can reach, which on an
+ * unattended run is the user's whole machine.
+ */
+export function extractStoredZip(zip: Buffer, destDir: string): string[] {
+  const written: string[] = [];
+  const root = resolve(destDir);
+  let at = 0;
+
+  while (at + 30 <= zip.length && zip.readUInt32LE(at) === 0x04034b50) {
+    const method = zip.readUInt16LE(at + 8);
+    const size = zip.readUInt32LE(at + 18);
+    const nameLen = zip.readUInt16LE(at + 26);
+    const extraLen = zip.readUInt16LE(at + 28);
+    const name = zip.toString("utf8", at + 30, at + 30 + nameLen);
+    const dataAt = at + 30 + nameLen + extraLen;
+
+    if (method !== 0) throw new Error(`archive entry "${name}" is compressed; only stored entries are expected`);
+    if (dataAt + size > zip.length) throw new Error(`archive entry "${name}" is truncated`);
+
+    const target = resolve(root, name);
+    if (target !== root && !target.startsWith(root + "/")) {
+      throw new Error(`archive entry "${name}" escapes the destination directory`);
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, zip.subarray(dataAt, dataAt + size));
+    written.push(name);
+
+    at = dataAt + size;
+  }
+
+  if (!written.length) throw new Error("the archive contained no files");
+  return written;
+}
+
+/**
+ * Guess the res:// path from where the files are being written.
+ *
+ * The .tres refers to its sheet by an absolute res:// path, so getting it wrong
+ * means the caller opens Godot and edits a line by hand. In the overwhelmingly
+ * common case the agent is running AT the project root, so the directory
+ * relative to cwd IS the res:// path — deriving it is right far more often than
+ * a fixed default would be. Returns undefined when the target is outside cwd,
+ * where the guess would be worse than letting the server default.
+ */
+export function guessResPath(cwd: string, dir: string): string | undefined {
+  const target = resolve(abs(cwd, dir));
+  const root = resolve(cwd);
+  if (target === root || !target.startsWith(root + "/")) return undefined;
+  return `res://${target.slice(root.length + 1).split("\\").join("/")}/`;
+}
+
+export const generateSpriteToolDefinition = {
+  name: "generate_sprite",
+  label: "Generate Sprite Animation",
+  description:
+    "Generate a 2D SPRITE ANIMATION for a game engine — a packed sprite sheet, the individual frame " +
+    "PNGs, and a Godot 4 SpriteFrames .tres resource — from ONE picture of a character plus a " +
+    "description of how it moves. The files are written straight into your project directory, so an " +
+    "AnimatedSprite2D can use them without any further conversion. There is no text-to-sprite here: " +
+    "generate or find the character art first (generate_image works), look at it, and pass that path " +
+    "as `image` — every facing is derived from that one picture, which is what stops the character " +
+    "changing between frames.\n" +
+    "HOW IT IS BILLED, because it is not one generation: the motion is rendered as a short video per " +
+    "FACING and then sampled into frames. `directions: 'one'` costs one video generation, 'four' " +
+    "costs THREE, and 'eight' costs FIVE — the left-facing animations are mirrored from the " +
+    "right-facing ones rather than rendered, which is why eight animations cost five clips and not " +
+    "eight. Each clip is charged at the account's video rate, so an eight-way set is genuinely " +
+    "expensive; say the total to the user before batching characters.\n" +
+    "It takes several minutes (the clips render sequentially) and this tool waits. Frame count, cell " +
+    "size and frame rate are chosen here and cost nothing extra. AVAILABILITY: this needs a video " +
+    "decoder on the Privateer API and some deployments do not have one — call media_capabilities and " +
+    "check `sprites.available` before spending, or you will get a clear refusal instead of a sheet. " +
+    "PRIVACY: video and image models have no zero-retention option, so this is gated the way 3D is — " +
+    "a ZDR account must have enabled non-ZDR media.",
+  parameters: Type.Object({
+    image: Type.String({
+      description:
+        "Path to ONE picture of the character, ideally full-body, centred and facing the viewer. " +
+        "Every other facing is generated as an edit of this image, so its framing sets the framing of " +
+        "the whole sheet.",
+    }),
+    prompt: Type.String({
+      description:
+        "How the character MOVES, not what it looks like — 'walking at a steady pace', 'swinging a " +
+        "sword overhead', 'idle, breathing'. The appearance comes from `image`; describing it again " +
+        "here only competes with the picture.",
+    }),
+    dir: Type.String({
+      description:
+        "Directory to write the sheet, frames and .tres into, relative to cwd or absolute " +
+        "(e.g. 'sprites/knight'). It is created if missing. When it sits inside cwd, the res:// path " +
+        "baked into the .tres is derived from it, so running at your Godot project root means the " +
+        "resource resolves with nothing to edit.",
+    }),
+    action: Type.Optional(
+      Type.String({
+        description:
+          "The animation-name stem, e.g. 'walk' — GDScript will play \"walk_down\", \"walk_left\" and so " +
+          "on. Defaults to 'anim'. Keep it lowercase and ASCII; it ends up in game code.",
+      }),
+    ),
+    directions: Type.Optional(
+      Type.String({
+        description:
+          "'one' (default, one animation, ONE clip billed), 'four' (down/right/up/left, THREE billed) " +
+          "or 'eight' (adds the diagonals, FIVE billed). Four is the usual choice for a top-down or " +
+          "2.5D character; eight only if the game actually turns that finely.",
+      }),
+    ),
+    frames: Type.Optional(
+      Type.Number({
+        description:
+          "Frames per animation, 2-24 (default 8). Sampled out of the rendered clip, so this costs " +
+          "nothing extra and can be chosen for the look: 8 is a classic walk cycle, 12+ is smoother " +
+          "and makes a larger sheet.",
+      }),
+    ),
+    frame_size: Type.Optional(
+      Type.Number({
+        description:
+          "Cell size in pixels, 8-512 (default 64). Frames are downscaled with nearest-neighbour, so " +
+          "pixel art stays crisp. Pick the size the game actually draws at.",
+      }),
+    ),
+    fps: Type.Optional(
+      Type.Number({ description: "Playback rate written into the resource, 1-120 (default 12)." }),
+    ),
+    loop: Type.Optional(
+      Type.Boolean({ description: "Whether the animations loop (default true)." }),
+    ),
+    name: Type.Optional(
+      Type.String({ description: "Name for the sprite; sets the file names. Defaults to `action`." }),
+    ),
+    res_path: Type.Optional(
+      Type.String({
+        description:
+          "Override the res:// folder the .tres points at, e.g. 'res://art/mobs/'. Only needed when " +
+          "`dir` is not inside your Godot project root — otherwise it is derived from `dir`.",
+      }),
+    ),
+    model: Type.Optional(
+      Type.String({ description: "Video model id to render the motion with. Omit for the account default." }),
+    ),
+  }),
+  async execute(
+    _toolCallId: string,
+    params: {
+      image: string; prompt: string; dir: string; action?: string; directions?: string;
+      frames?: number; frame_size?: number; fps?: number; loop?: boolean;
+      name?: string; res_path?: string; model?: string;
+    },
+    signal?: AbortSignal,
+    _onUpdate?: unknown,
+    ctx?: { cwd?: string },
+  ) {
+    const cwd = ctx?.cwd ?? process.cwd();
+    if (!params.image) return text("Error: image is required — sprite generation derives every facing from one picture.");
+    if (!params.prompt?.trim()) return text("Error: prompt is required — describe how the character moves.");
+    if (!params.dir) return text("Error: dir is required — say where to write the sheet and the .tres.");
+
+    let seed: { data: string; mimeType: string };
+    try {
+      seed = readInputImage(cwd, params.image);
+    } catch (e) {
+      return text(`Error: ${e instanceof Error ? e.message : String(e)}`);
+    }
+
+    const submitted = await callAccount<SpriteSubmitResponse>("/api/agent/media/sprites", {
+      method: "POST",
+      signal,
+      body: {
+        image: seed.data,
+        prompt: params.prompt,
+        ...(params.action ? { action: params.action } : {}),
+        ...(params.name ? { name: params.name } : {}),
+        ...(params.directions ? { directions: params.directions } : {}),
+        ...(params.frames != null ? { frames: params.frames } : {}),
+        ...(params.frame_size != null ? { frame_size: params.frame_size } : {}),
+        ...(params.fps != null ? { fps: params.fps } : {}),
+        ...(params.loop != null ? { loop: params.loop } : {}),
+        // The caller's own res:// wins; otherwise derive it from where the files
+        // are going, which is right whenever the agent runs at the project root.
+        ...(params.res_path
+          ? { res_path: params.res_path }
+          : (() => {
+            const guessed = guessResPath(cwd, params.dir);
+            return guessed ? { res_path: guessed } : {};
+          })()),
+        ...(params.model ? { model: params.model } : {}),
+      },
+    });
+    if (!submitted.ok) return text(`Sprite generation failed: ${submitted.message}`);
+    const jobId = submitted.data.id;
+    if (!jobId) return text("Sprite generation failed: Privateer did not return a job id.");
+
+    const billed = submitted.data.billed_facings;
+    const deadline = Date.now() + SPRITE_POLL_TIMEOUT_MS;
+    // The clips are charged as they land, so an abandoned poll still costs money —
+    // hence every exit below names the job id and says so plainly.
+    const cancelled = () =>
+      text(`Sprite job ${jobId} was submitted but the wait was cancelled. Its ${billed ?? "queued"} clip(s) are still rendering and will still be billed.`);
+
+    for (;;) {
+      if (signal?.aborted) return cancelled();
+      await sleep(SPRITE_POLL_INTERVAL_MS, signal);
+      if (signal?.aborted) return cancelled();
+
+      const poll = await callAccount<SpriteStatusResponse>(
+        `/api/agent/media/sprites/${encodeURIComponent(jobId)}`,
+        { method: "GET", signal },
+      );
+      if (!poll.ok) return text(`Sprite job ${jobId} could not be polled: ${poll.message}`);
+
+      const status = String(poll.data.status ?? "").toLowerCase();
+      if (status === "failed") {
+        return text(`Sprite generation failed: ${poll.data.error?.message ?? poll.data.message ?? "the provider reported a failure"}.`);
+      }
+      if (status === "completed") {
+        if (!poll.data.zip_base64) {
+          return text(`Sprite job ${jobId} already delivered its bytes on an earlier poll; they were not saved. Generate again if the files are missing.`);
+        }
+        const destination = abs(cwd, params.dir);
+        let written: string[];
+        try {
+          written = extractStoredZip(Buffer.from(poll.data.zip_base64, "base64"), destination);
+        } catch (e) {
+          return text(`Sprite job ${jobId} rendered but the bundle could not be unpacked: ${e instanceof Error ? e.message : String(e)}`);
+        }
+
+        const tres = written.find((f) => f.endsWith(".tres"));
+        const anims = poll.data.animations ?? [];
+        const mirrored = anims.filter((a) => a.origin === "mirrored").length;
+        const sheet = poll.data.sheet;
+
+        const lines = [
+          `Generated sprite animation: ${written.length} files in ${destination}`,
+          sheet ? `Sheet ${sheet.width}x${sheet.height}px, ${sheet.frame_width}x${sheet.frame_height} cells, ${sheet.columns}x${sheet.rows} grid.` : "",
+          anims.length ? `Animations: ${anims.map((a) => a.name).join(", ")}${mirrored ? ` (${mirrored} mirrored, not billed)` : ""}.` : "",
+          tres ? `Set an AnimatedSprite2D's Sprite Frames to ${poll.data.res_path ?? "res://"}${tres.split("/").pop()}.` : "",
+          "Set the sheet's texture Filter to Nearest in the Import dock, or the pixel art imports blurry.",
+          // Surfaced rather than swallowed: the flat backdrop the clip was asked
+          // for is a prompt the model can ignore, and when it does the key leaves
+          // a rim. The caller can see it here instead of finding it in-game.
+          poll.data.key_residue != null && poll.data.key_residue > 0.08
+            ? `NOTE: the background did not key cleanly (residue ${poll.data.key_residue.toFixed(2)}) — the frames may have a fringe. Re-run, or clean them up before shipping.`
+            : "",
+        ].filter(Boolean);
+        return text(lines.join("\n"));
+      }
+      if (Date.now() > deadline) {
+        return text(
+          `Sprite job ${jobId} is still ${status || "running"} after ${Math.round(SPRITE_POLL_TIMEOUT_MS / 60000)} minutes. ` +
+            "It will still complete and still be billed; nothing was saved here.",
+        );
+      }
+    }
+  },
+};
+
 /**
  * Extension factory registering every account-backed media tool. Used by the surfaces
  * that build their session from an explicit `extensionFactories` list (harbor, channels,
@@ -1051,6 +1349,7 @@ export function makeMediaTools() {
     pi.registerTool?.(generateImageToolDefinition);
     pi.registerTool?.(generateVideoToolDefinition);
     pi.registerTool?.(generateModelToolDefinition);
+    pi.registerTool?.(generateSpriteToolDefinition);
     pi.registerTool?.(generateSpeechToolDefinition);
     pi.registerTool?.(generateMusicToolDefinition);
     pi.registerTool?.(generateSfxToolDefinition);