privateer-agent 0.12.20 → 0.12.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.20",
+  "version": "0.12.22",
   "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,7 +68,7 @@ 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..c52ea80 100644
+index ce8a9a2..b7b339e 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";
@@ -174,7 +174,7 @@ index ce8a9a2..c52ea80 100644
          // Emit to extensions first
          await this._emitExtensionEvent(event);
          // Notify all listeners
-@@ -772,6 +854,15 @@ export class AgentSession {
+@@ -772,6 +854,25 @@ export class AgentSession {
                  finalError: msg.errorMessage,
              });
              this._retryAttempt = 0;
@@ -186,11 +186,21 @@ index ce8a9a2..c52ea80 100644
 +            // That re-entry is what produced the endless "retrying 1/3…2/3…3/3" loop
 +            // on a persistently-failing provider/tool. Context-overflow errors never
 +            // reach this branch (_isRetryableError → false), so compaction is untouched.
++            return false;
++        }
++        // Privateer patch: a first-attempt hard 4xx (a WAF 403, a 401, a 404) is also
++        // terminal. Stock Pi still falls through to compaction here because _retryAttempt
++        // is 0, and _checkCompaction will summarise a session that already has usage.
++        // That summary is another LLM call to the SAME blocked endpoint; retryAssistantCall
++        // classifies the raw HTML body as transient (it contains "500"/"502"), so the
++        // agent looks hung — retrying a compaction that can never succeed — until the
++        // summarizer budget burns. Context overflow never matches isHardHttpFailure.
++        if (msg.stopReason === "error" && isHardHttpFailure(msg.errorMessage)) {
 +            return false;
          }
          if (await this._checkCompaction(msg)) {
              return true;
-@@ -852,6 +943,14 @@ export class AgentSession {
+@@ -852,6 +953,14 @@ export class AgentSession {
              if (!hasConfiguredAuth) {
                  const isOAuth = this._modelRuntime.isUsingOAuth(this.model.provider);
                  if (isOAuth) {
@@ -205,7 +215,7 @@ index ce8a9a2..c52ea80 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 +2183,27 @@ export class AgentSession {
+@@ -2084,6 +2193,27 @@ export class AgentSession {
          // Context overflow is handled by compaction, not retry.
          if (isContextOverflow(message, this.model?.contextWindow ?? 0))
              return false;
@@ -1052,17 +1062,19 @@ index 6f7ed6a..b0ed0ae 100644
      getResourcePattern(item) {
          const scope = item.metadata.scope;
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js
-index 1d9f046..2a1fba8 100644
+index 1d9f046..c0326e3 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js
 +++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/components/footer.js
-@@ -1,5 +1,5 @@
+@@ -1,7 +1,6 @@
  import { isAbsolute, relative, resolve, sep } from "node:path";
 -import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 +import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
  import { areExperimentalFeaturesEnabled } from "../../../core/experimental.js";
- import { addUsageToTotals, createUsageTotals } from "../../../core/usage-totals.js";
+-import { addUsageToTotals, createUsageTotals } from "../../../core/usage-totals.js";
  import { theme } from "../theme/theme.js";
-@@ -14,6 +14,43 @@ function sanitizeStatusText(text) {
+ /**
+  * Sanitize text for display in a single-line status.
+@@ -14,6 +13,43 @@ function sanitizeStatusText(text) {
          .replace(/ +/g, " ")
          .trim();
  }
@@ -1106,7 +1118,182 @@ index 1d9f046..2a1fba8 100644
  /**
   * Format token counts for compact footer display.
   */
-@@ -212,9 +249,9 @@ export class FooterComponent {
+@@ -41,8 +77,11 @@ export function formatCwdForFooter(cwd, home) {
+     return relativeToHome === "" ? "~" : `~${sep}${relativeToHome}`;
+ }
+ /**
+- * Footer component that shows pwd, token stats, and context usage.
+- * Computes token/context stats from session, gets git branch and extension statuses from provider.
++ * Footer component that shows pwd (with git branch) and the active model.
++ *
++ * Privateer trimmed this: upstream also drew a second row of cumulative token
++ * counters, cache-hit rate, cost and a context gauge. Gets git branch and
++ * extension statuses from provider.
+  */
+ export class FooterComponent {
+     autoCompactEnabled = true;
+@@ -74,29 +113,9 @@ export class FooterComponent {
+     }
+     render(width) {
+         const state = this.session.state;
+-        // Calculate cumulative usage from ALL session entries (not just post-compaction messages)
+-        const usageTotals = createUsageTotals();
+-        let latestCacheHitRate;
+-        for (const entry of this.session.sessionManager.getEntries()) {
+-            if (entry.type === "message" && entry.message.role === "assistant") {
+-                addUsageToTotals(usageTotals, entry.message.usage);
+-                const latestPromptTokens = entry.message.usage.input + entry.message.usage.cacheRead + entry.message.usage.cacheWrite;
+-                latestCacheHitRate =
+-                    latestPromptTokens > 0 ? (entry.message.usage.cacheRead / latestPromptTokens) * 100 : undefined;
+-            }
+-            else if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.usage) {
+-                addUsageToTotals(usageTotals, entry.message.usage);
+-            }
+-            else if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) {
+-                addUsageToTotals(usageTotals, entry.usage);
+-            }
+-        }
+-        // Calculate context usage from session (handles compaction correctly).
+-        // After compaction, tokens are unknown until the next LLM response.
+-        const contextUsage = this.session.getContextUsage();
+-        const contextWindow = contextUsage?.contextWindow ?? state.model?.contextWindow ?? 0;
+-        const contextPercentValue = contextUsage?.percent ?? 0;
+-        const contextPercent = contextUsage?.percent !== null ? contextPercentValue.toFixed(1) : "?";
++        // Privateer: no token counters, cache-hit rate, cost or context gauge in the
++        // footer — so the accumulation that fed them is gone too. Upstream walked EVERY
++        // session entry on EVERY render to build numbers we no longer draw.
+         // Replace home directory with ~
+         let pwd = formatCwdForFooter(this.session.sessionManager.getCwd(), process.env.HOME || process.env.USERPROFILE);
+         // Add git branch if available
+@@ -109,56 +128,24 @@ export class FooterComponent {
+         if (sessionName) {
+             pwd = `${pwd} • ${sessionName}`;
+         }
+-        // Build stats line
+-        const statsParts = [];
+-        if (usageTotals.input)
+-            statsParts.push(`↑${formatTokens(usageTotals.input)}`);
+-        if (usageTotals.output)
+-            statsParts.push(`↓${formatTokens(usageTotals.output)}`);
+-        if (usageTotals.cacheRead)
+-            statsParts.push(`R${formatTokens(usageTotals.cacheRead)}`);
+-        if (usageTotals.cacheWrite)
+-            statsParts.push(`W${formatTokens(usageTotals.cacheWrite)}`);
+-        if ((usageTotals.cacheRead > 0 || usageTotals.cacheWrite > 0) && latestCacheHitRate !== undefined) {
+-            statsParts.push(`CH${latestCacheHitRate.toFixed(1)}%`);
+-        }
+-        // Kimi Coding is subscription-backed despite using API-key authentication.
+-        const usingSubscription = state.model
+-            ? state.model.provider === "kimi-coding" || this.session.modelRuntime.isUsingSubscription(state.model.provider)
+-            : false;
+-        if (usageTotals.cost || usingSubscription) {
+-            const costStr = `$${usageTotals.cost.toFixed(3)}${usingSubscription ? " (sub)" : ""}`;
+-            statsParts.push(costStr);
+-        }
+-        // Colorize context percentage based on usage
+-        let contextPercentStr;
+-        const autoIndicator = this.autoCompactEnabled ? " (auto)" : "";
+-        const contextPercentDisplay = contextPercent === "?"
+-            ? `?/${formatTokens(contextWindow)}${autoIndicator}`
+-            : `${contextPercent}%/${formatTokens(contextWindow)}${autoIndicator}`;
+-        if (contextPercentValue > 90) {
+-            contextPercentStr = theme.fg("error", contextPercentDisplay);
+-        }
+-        else if (contextPercentValue > 70) {
+-            contextPercentStr = theme.fg("warning", contextPercentDisplay);
+-        }
+-        else {
+-            contextPercentStr = contextPercentDisplay;
+-        }
+-        statsParts.push(contextPercentStr);
+-        if (areExperimentalFeaturesEnabled()) {
+-            statsParts.push(`${theme.fg("dim", "•")} ${theme.bold(theme.fg("warning", "xp"))}`);
+-        }
+-        let statsLeft = statsParts.join(" ");
++        // Privateer: ONE footer row — the working directory on the left, the model on
++        // the right. Upstream spent a second row on cumulative token counters, cache-hit
++        // rate and cost; those are session trivia that never change what you do next, and
++        // they made the busiest part of the screen the least useful. The `xp` flag stays:
++        // it warns that experimental features are live, which is not trivia.
++        const experimentalFlag = areExperimentalFeaturesEnabled()
++            ? ` ${theme.fg("dim", "•")} ${theme.bold(theme.fg("warning", "xp"))}`
++            : "";
++        let left = pwd + experimentalFlag;
+         // Add model name on the right side, plus thinking level if model supports it
+         const modelName = state.model?.id || "no-model";
+-        let statsLeftWidth = visibleWidth(statsLeft);
+-        // If statsLeft is too wide, truncate it
+-        if (statsLeftWidth > width) {
+-            statsLeft = truncateToWidth(statsLeft, width, "...");
+-            statsLeftWidth = visibleWidth(statsLeft);
++        let leftWidth = visibleWidth(left);
++        // If the left side is too wide, truncate it
++        if (leftWidth > width) {
++            left = truncateToWidth(left, width, "...");
++            leftWidth = visibleWidth(left);
+         }
+-        // Calculate available space for padding (minimum 2 spaces between stats and model)
++        // Calculate available space for padding (minimum 2 spaces between cwd and model)
+         const minPadding = 2;
+         // Add thinking level indicator if model supports reasoning
+         let rightSideWithoutProvider = modelName;
+@@ -171,50 +158,48 @@ export class FooterComponent {
+         let rightSide = rightSideWithoutProvider;
+         if (this.footerData.getAvailableProviderCount() > 1 && state.model) {
+             rightSide = `(${state.model.provider}) ${rightSideWithoutProvider}`;
+-            if (statsLeftWidth + minPadding + visibleWidth(rightSide) > width) {
++            if (leftWidth + minPadding + visibleWidth(rightSide) > width) {
+                 // Too wide, fall back
+                 rightSide = rightSideWithoutProvider;
+             }
+         }
+         const rightSideWidth = visibleWidth(rightSide);
+-        const totalNeeded = statsLeftWidth + minPadding + rightSideWidth;
+-        let statsLine;
++        const totalNeeded = leftWidth + minPadding + rightSideWidth;
++        let footerLine;
+         if (totalNeeded <= width) {
+             // Both fit - add padding to right-align model
+-            const padding = " ".repeat(width - statsLeftWidth - rightSideWidth);
+-            statsLine = statsLeft + padding + rightSide;
++            const padding = " ".repeat(width - leftWidth - rightSideWidth);
++            footerLine = left + padding + rightSide;
+         }
+         else {
+             // Need to truncate right side
+-            const availableForRight = width - statsLeftWidth - minPadding;
++            const availableForRight = width - leftWidth - minPadding;
+             if (availableForRight > 0) {
+                 const truncatedRight = truncateToWidth(rightSide, availableForRight, "");
+                 const truncatedRightWidth = visibleWidth(truncatedRight);
+-                const padding = " ".repeat(Math.max(0, width - statsLeftWidth - truncatedRightWidth));
+-                statsLine = statsLeft + padding + truncatedRight;
++                const padding = " ".repeat(Math.max(0, width - leftWidth - truncatedRightWidth));
++                footerLine = left + padding + truncatedRight;
+             }
+             else {
+                 // Not enough space for right side at all
+-                statsLine = statsLeft;
++                footerLine = left;
+             }
+         }
+-        // Apply dim to each part separately. statsLeft may contain color codes (for context %)
+-        // that end with a reset, which would clear an outer dim wrapper. So we dim the parts
+-        // before and after the colored section independently.
+-        const dimStatsLeft = theme.fg("dim", statsLeft);
+-        const remainder = statsLine.slice(statsLeft.length); // padding + rightSide
+-        const dimRemainder = theme.fg("dim", remainder);
+-        const pwdLine = truncateToWidth(theme.fg("dim", pwd), width, theme.fg("dim", "..."));
+-        const lines = [pwdLine, dimStatsLeft + dimRemainder];
++        // Apply dim to each part separately. `left` may carry the bold/warning-coloured
++        // xp flag, whose reset would clear an outer dim wrapper. So dim the parts before
++        // and after the coloured section independently.
++        const dimLeft = theme.fg("dim", left);
++        const remainder = footerLine.slice(left.length); // padding + rightSide
++        const lines = [dimLeft + theme.fg("dim", remainder)];
+         // Add extension statuses on a single line, sorted by key alphabetically
+         const extensionStatuses = this.footerData.getExtensionStatuses();
+         if (extensionStatuses.size > 0) {
              const sortedStatuses = Array.from(extensionStatuses.entries())
                  .sort(([a], [b]) => a.localeCompare(b))
                  .map(([, text]) => sanitizeStatusText(text));
@@ -1119,6 +1306,97 @@ index 1d9f046..2a1fba8 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
+--- 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 @@
+-import { Box, Container, getCapabilities, Image, Spacer, Text } from "@earendil-works/pi-tui";
++import { Box, Container, getCapabilities, Image, Spacer, visibleWidth, Text } from "@earendil-works/pi-tui";
+ import { createAllToolDefinitions } from "../../../core/tools/index.js";
+ import { getTextOutput as getRenderedTextOutput } from "../../../core/tools/render-utils.js";
+ import { convertToPng } from "../../../utils/image-convert.js";
+ import { theme } from "../theme/theme.js";
++/**
++ * Privateer: mark a failed tool call inline on its title line.
++ *
++ * Upstream's ONLY failure signal is the full-width red `toolErrorBg` wash behind
++ * the whole block. We flatten those washes (see dark.json / light.json) because
++ * large blocks of colour read as noise — but flattening the error one alone would
++ * make a failure indistinguishable from a success, which is a real regression.
++ *
++ * So we put the signal back where it costs nothing: a red glyph prefixed to the
++ * first line of whatever the tool's own renderCall produced. Wrapping the CALL
++ * component (not the Box) means Box still owns padding and width, and the marker
++ * works for every tool without touching seven per-tool renderers. Subsequent
++ * lines get a blank hanging indent so the title stays visually aligned.
++ */
++function markCallErrored(component, marker) {
++    const markerWidth = visibleWidth(marker);
++    const indent = " ".repeat(markerWidth);
++    return {
++        render(width) {
++            const lines = component.render(Math.max(1, width - markerWidth));
++            return lines.map((line, i) => (i === 0 ? marker + line : indent + line));
++        },
++        invalidate() {
++            component.invalidate?.();
++        },
++    };
++}
+ export class ToolExecutionComponent extends Container {
+     contentBox;
+     contentText;
+@@ -106,6 +133,13 @@ export class ToolExecutionComponent extends Container {
+     createCallFallback() {
+         return new Text(theme.fg("toolTitle", theme.bold(this.toolName)), 0, 0);
+     }
++    /** Privateer: red-flag a failed call, pass a pending/succeeded one straight through. */
++    decorateCall(component) {
++        if (!this.result?.isError || this.isPartial) {
++            return component;
++        }
++        return markCallErrored(component, theme.fg("error", "\u2717 "));
++    }
+     createResultFallback() {
+         const output = this.getTextOutput();
+         if (!output) {
+@@ -218,19 +252,22 @@ export class ToolExecutionComponent extends Container {
+             renderContainer.clear();
+             const callRenderer = this.getCallRenderer();
+             if (!callRenderer) {
+-                renderContainer.addChild(this.createCallFallback());
++                renderContainer.addChild(this.decorateCall(this.createCallFallback()));
+                 hasContent = true;
+             }
+             else {
+                 try {
+                     const component = callRenderer(this.args, theme, this.getRenderContext(this.callRendererComponent));
++                    // Store the RAW component: it comes back as `lastComponent` on the
++                    // next render and the tool's renderer calls its own methods on it,
++                    // so handing it a wrapper would break every stateful renderer.
+                     this.callRendererComponent = component;
+-                    renderContainer.addChild(component);
++                    renderContainer.addChild(this.decorateCall(component));
+                     hasContent = true;
+                 }
+                 catch {
+                     this.callRendererComponent = undefined;
+-                    renderContainer.addChild(this.createCallFallback());
++                    renderContainer.addChild(this.decorateCall(this.createCallFallback()));
+                     hasContent = true;
+                 }
+             }
+@@ -302,7 +339,8 @@ export class ToolExecutionComponent extends Container {
+         return getRenderedTextOutput(this.result, this.showImages);
+     }
+     formatToolExecution() {
+-        let text = theme.fg("toolTitle", theme.bold(this.toolName));
++        const errorMark = this.result?.isError && !this.isPartial ? theme.fg("error", "\u2717 ") : "";
++        let text = errorMark + theme.fg("toolTitle", theme.bold(this.toolName));
+         const content = JSON.stringify(this.args, null, 2);
+         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
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/interactive-mode.js
@@ -1269,6 +1547,40 @@ index 42e655d..d00bec9 100644
      }
      async getUserInput() {
          const queuedInput = this.pendingUserInputs.shift();
+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
++++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/theme/dark.json
+@@ -39,9 +39,9 @@
+ 		"customMessageBg": "customMsgBg",
+ 		"customMessageText": "text",
+ 		"customMessageLabel": "#9575cd",
+-		"toolPendingBg": "toolPendingBg",
+-		"toolSuccessBg": "toolSuccessBg",
+-		"toolErrorBg": "toolErrorBg",
++		"toolPendingBg": "",
++		"toolSuccessBg": "",
++		"toolErrorBg": "",
+ 		"toolTitle": "text",
+ 		"toolOutput": "gray",
+ 
+diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/theme/light.json b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/theme/light.json
+index 74ef3d1..709a21d 100644
+--- a/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/theme/light.json
++++ b/node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/theme/light.json
+@@ -38,9 +38,9 @@
+ 		"customMessageBg": "customMsgBg",
+ 		"customMessageText": "text",
+ 		"customMessageLabel": "#7e57c2",
+-		"toolPendingBg": "toolPendingBg",
+-		"toolSuccessBg": "toolSuccessBg",
+-		"toolErrorBg": "toolErrorBg",
++		"toolPendingBg": "",
++		"toolSuccessBg": "",
++		"toolErrorBg": "",
+ 		"toolTitle": "text",
+ 		"toolOutput": "mediumGray",
+ 
 diff --git a/node_modules/@earendil-works/pi-coding-agent/dist/package-manager-cli.js b/node_modules/@earendil-works/pi-coding-agent/dist/package-manager-cli.js
 index 4230b18..f47e80f 100644
 --- a/node_modules/@earendil-works/pi-coding-agent/dist/package-manager-cli.js

package/src/config/moat.ts

@@ -45,6 +45,7 @@ import type { GateController } from "../ext/permissionGate.ts";
 import type { SendFileBridge } from "../tools/sendFile.ts";
 import type { CargoSaveBridge } from "../tools/cargo.ts";
 import type { ChartOpBridge } from "../tools/charts.ts";
+import type { LibrarySaveBridge } from "../tools/saveToLibrary.ts";
 import type { AttachmentStore } from "../util/attachmentStore.ts";
 
 /** A Pi extension factory, as DefaultResourceLoader takes them. */
@@ -73,7 +74,10 @@ export interface MoatOptions {
    * its module-level bridge and stands them down inside the daemon, so a live spawn's own
    * pair is what the model gets (see tools/relayFileTools.ts).
    */
-  relayFiles?: { bridge: SendFileBridge & CargoSaveBridge & ChartOpBridge; attachments: AttachmentStore };
+  relayFiles?: {
+    bridge: SendFileBridge & CargoSaveBridge & ChartOpBridge & LibrarySaveBridge;
+    attachments: AttachmentStore;
+  };
   /**
    * THIS run's inbox-attachment staging area (routines/resultMedia.ts). Passed only by
    * a path whose result reaches the app's Inbox — a scheduled routine, a submitted

package/src/engine/errors.ts

@@ -134,6 +134,13 @@ export function isAccountCapCode(code: string | null | undefined): boolean {
 // patches/@earendil-works+pi-coding-agent+*.patch, which mirrors these two helpers):
 // squeeze the page down to the line a person can act on, and let the STATUS decide
 // retryability rather than a substring of the body.
+//
+// A first-attempt hard 4xx is also terminal for the post-run loop. Stock Pi still
+// falls through to compaction when _retryAttempt is 0, and a session that already
+// has usage will summarise — another LLM call to the same blocked endpoint. The
+// summarizer retries on the raw HTML (it contains "500"/"502"), so the agent looks
+// hung until that budget burns. The patch returns false from _handlePostAgentRun
+// before _checkCompaction when isHardHttpFailure matches.
 
 /** Hard cap on an error message we display, persist, or classify. */
 export const MAX_ERROR_CHARS = 2_000;

package/src/remote/librarySave.ts

@@ -0,0 +1,156 @@
+// The wire contract for CLI → app Library saves, shared by the modules that have
+// to agree on it: RelayClient (sends the frames), RemoteBridge (correlates the
+// reply), and the save_to_library tool (validates before either runs).
+//
+// WHY THE ROUND TRIP EXISTS AT ALL. The same reason save_cargo's does, and the
+// argument is worth restating because this path moves bytes rather than text and
+// the temptation to "just upload it" is correspondingly stronger. Everything in
+// the Library is ciphertext under the account master key — the picture, the
+// clip, the mesh, the document, and the filename and mime type sealed beside
+// them (treeview CLAUDE.md §5). The terminal deliberately holds no master key:
+// the device-grant login mints a session token and nothing else, and
+// crypto/accountVerify.ts says so out loud. So a CLI that POSTed
+// /api/chat/upload-file by itself could only put bytes on S3 that nothing can
+// ever open, and a row pointing at them that nothing can ever read.
+//
+// The app can. It is already signed in, already holds the key, and already has
+// the per-shelf save functions the Library's own screens call. So the CLI hands
+// it plaintext bytes over the relay the user already trusts to carry their
+// prompts and their approvals, and the app does the encrypting.
+//
+// WHY THE APP ALSO PICKS THE SHELF AND THE BACKEND. Two decisions travel with
+// the key, and neither is the terminal's to make:
+//
+//  - WHICH SHELF. An image belongs in Images, a clip in Audio, a mesh in Models,
+//    a report in Documents — each with its own registration route and its own
+//    on-device index. The app routes by the same classifier a dragged-in file
+//    goes through (client/utils/webFileDrop.ts), so an agent-saved file and a
+//    hand-dropped identical file land in the same place. A table on this side
+//    would be the second copy, and the drift would show up as the user's
+//    generated PNG filed under Documents.
+//  - CLOUD OR ON DEVICE. This is the one the tool's name invites a model to
+//    guess at, and it must never be a parameter. `resolveStorageBackend()`
+//    answers it from the account: a local-backend account's files live on the
+//    device and nothing reaches the server (CLAUDE.md §2). A terminal able to
+//    override that could put bytes on our servers for an account that chose
+//    device-only storage. The tool therefore takes no destination argument and
+//    REPORTS which one was used, rather than asking for one.
+//
+// WHAT THAT COSTS. The app has to be attached. A harbor is headless by design
+// and there is no controller to ask, so save_to_library is not registered there —
+// an unattended run still delivers a file the way it always has, as a sealed
+// attachment on its Inbox result (routines/resultMedia.ts). Don't "fix" that by
+// widening this.
+
+/** Which Library shelf the app filed a save on. Mirrors AgentSaveShelf app-side. */
+export const LIBRARY_SHELVES = ["image", "video", "audio", "model3d", "document"] as const;
+export type LibraryShelf = (typeof LIBRARY_SHELVES)[number];
+
+/**
+ * Ceiling on a save, in bytes — the plaintext file, before base64.
+ *
+ * Matches MAX_AGENT_SAVE_BYTES app-side (client/services/agentLibrarySave.ts),
+ * and the number is a WIRE decision rather than a storage one: these bytes cross
+ * a relay a phone may be holding over a mobile connection, inflated by a third
+ * and cut into 256 KB frames. Checked HERE as well as there, because a refusal
+ * that costs nothing to compute should not cost a 33 MB upload first — and
+ * because refusing on this side is the only way the message can name the file.
+ *
+ * Per-shelf server limits still apply UNDER this (an image caps at 10 MB) and
+ * are deliberately NOT restated: they live in services/ImageUpload.js, the app
+ * surfaces whatever the route says, and a copy here would be a third number to
+ * keep in step.
+ */
+export const MAX_LIBRARY_SAVE_BYTES = 25 * 1024 * 1024;
+
+/**
+ * Base64 characters of file per `library_chunk` frame.
+ *
+ * Same figure the file-send path uses and for the same reason: the relay caps a
+ * frame at 256 KB, and 3/4 of that leaves room for the frame's own JSON. Base64
+ * rather than raw bytes because the relay carries JSON text — a Library save may
+ * be a PNG or a GLB, so unlike a Cargo artifact there is nothing to be gained by
+ * sending the payload as a string.
+ */
+export const LIBRARY_CHUNK_CHARS = 180_000;
+
+/** A CLI-initiated Library save, relayed to the app to encrypt, file and store. */
+export interface LibrarySaveRequest {
+  /** File bytes, base64. */
+  base64: string;
+  /** Plaintext byte length, so the app can refuse before reassembling. */
+  size: number;
+  /** The name to file it under — the user's vocabulary, not a path. */
+  name: string;
+  mediaType: string;
+  /**
+   * Free-text provenance sealed into the row's encrypted metadata — the prompt
+   * that drew it, the command that produced it. Optional, and never a title:
+   * the Library titles a row from `name`.
+   */
+  note?: string;
+}
+
+/**
+ * The app's answer. `ok: false` carries a reason written for a person — a locked
+ * vault, full cloud storage, a guest session, a file type with no shelf —
+ * because the tool hands it straight to the model, and "save failed" is not
+ * something it can act on.
+ *
+ * `storageType` on the success arm is the point of the whole feature being
+ * REPORTED rather than requested: it is how the model learns whether the file
+ * went to the account's cloud or stayed on the device, so it can tell the user
+ * the truth about where their file is without ever having chosen.
+ */
+export type LibrarySaveResult =
+  | { ok: true; shelf: LibraryShelf; storageType: "cloud" | "local"; name: string; bytes: number }
+  | { ok: false; reason: string };
+
+/**
+ * Media type for a path, by extension. Deliberately a SUPERSET of the send-file
+ * table (tools/sendFile.ts): that one types a file for presentation in a feed,
+ * where an unknown extension falling to application/octet-stream costs nothing.
+ * Here the mime is one of the two things the app classifies on, so a .glb typed
+ * as octet-stream would still reach the mesh shelf (matched on extension) but a
+ * .txt typed that way would reach no shelf at all and be refused.
+ *
+ * Returns null rather than a fallback when the extension is unknown, so the tool
+ * can say which formats have a shelf instead of sending bytes the app will
+ * bounce.
+ */
+const LIBRARY_MEDIA: Record<string, string> = {
+  // Stills. Narrower than what the app calls an image elsewhere, because the
+  // upload route filters on the EXTENSION even for client-encrypted bodies —
+  // a HEIC is rejected at the door however well the device decodes it.
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
+  // Video.
+  mp4: "video/mp4", mov: "video/quicktime", webm: "video/webm", m4v: "video/x-m4v",
+  // Audio.
+  mp3: "audio/mpeg", wav: "audio/wav", m4a: "audio/mp4", aac: "audio/aac",
+  ogg: "audio/ogg", flac: "audio/flac",
+  // 3D. Matched app-side on the extension rather than this mime, but a mime is
+  // still sent so the stored metadata says something true.
+  glb: "model/gltf-binary", obj: "text/plain", fbx: "application/octet-stream",
+  usdz: "model/vnd.usdz+zip",
+  // Documents.
+  pdf: "application/pdf",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  csv: "text/csv",
+  // Text and code, all of which the app files as its `code` document type.
+  txt: "text/plain", md: "text/markdown", markdown: "text/markdown",
+  json: "application/json", yaml: "text/yaml", yml: "text/yaml", xml: "text/xml",
+  html: "text/html", css: "text/css", sql: "text/plain",
+  js: "text/javascript", ts: "text/plain", tsx: "text/plain", jsx: "text/plain",
+  py: "text/plain", rb: "text/plain", go: "text/plain", rs: "text/plain",
+  java: "text/plain", kt: "text/plain", swift: "text/plain", c: "text/plain",
+  cpp: "text/plain", h: "text/plain", cs: "text/plain", php: "text/plain",
+  sh: "text/plain",
+};
+
+export function libraryMediaTypeForPath(p: string): string | null {
+  const ext = p.split(".").pop()?.toLowerCase() ?? "";
+  return LIBRARY_MEDIA[ext] ?? null;
+}
+
+/** The extensions that have a shelf, for a refusal that tells the model what to do. */
+export const LIBRARY_EXTENSIONS = Object.keys(LIBRARY_MEDIA);

package/src/remote/relayClient.ts

@@ -23,6 +23,13 @@ import { MOAT_SHIMS, reservedNames } from "../config/moatManifest.ts";
 import type { EngineEvent } from "../engine/events.ts";
 import type { PermissionRequest } from "../permissions/gate.ts";
 import { CARGO_CHUNK_CHARS, type CargoSaveRequest, type CargoSaveResult } from "./cargoSave.ts";
+import {
+  LIBRARY_CHUNK_CHARS,
+  LIBRARY_SHELVES,
+  type LibraryShelf,
+  type LibrarySaveRequest,
+  type LibrarySaveResult,
+} from "./librarySave.ts";
 import { parseChartResult, type ChartOpRequest, type ChartOpResult } from "./chartOps.ts";
 
 // Display label for THIS running terminal. Deliberately NON-PII: we do NOT send
@@ -149,6 +156,13 @@ export interface RelayCallbacks {
   // chart_request simply never answers, which the bridge's bounded wait turns into a
   // clean "this app can't do charts yet" rather than a wedged tool call.
   onChartResult?: (id: string, result: ChartOpResult) => void;
+  // The app finished a CLI-initiated Library save (the id from requestLibrarySave):
+  // it classified the file, encrypted it under the account master key and filed it on
+  // the matching shelf — or refused. Optional for the same reason the two above are: a
+  // controller too old to understand library_begin simply never answers, which the
+  // bridge's bounded wait turns into a clean "this app can't save files yet" rather
+  // than a wedged tool call.
+  onLibrarySaved?: (id: string, result: LibrarySaveResult) => void;
   // The app's composer is autocompleting an `@file` mention — reply with the cwd
   // files/dirs matching `query` (a sendFileMatches frame, keyed by the same id).
   // Read-only; resolution of the picked path still happens on the prompt turn.
@@ -698,6 +712,11 @@ export class RelayClient {
       cargoId?: string;
       storageType?: string;
       reason?: string;
+      // library_saved (the app's verdict on a save_to_library round trip). `name`
+      // and `size` above are reused by file_begin, which is fine — every field on
+      // this type is optional and validated per case.
+      shelf?: string;
+      bytes?: number;
       // chart_result (the app's answer to a chart op). Left `unknown` on purpose —
       // it has four shapes and parseChartResult is what decides which one arrived.
       result?: unknown;
@@ -776,6 +795,37 @@ export class RelayClient {
         this.cb.onCargoSaved?.(frame.id, result);
         break;
       }
+      // The app's verdict on a Library save. Re-typed off the wire rather than
+      // trusted, for cargo_saved's reason and one more of its own: `shelf` and
+      // `storageType` are the two things the model REPEATS TO THE USER about where
+      // their file went, so a malformed frame must not be able to make it claim a
+      // file is in the cloud when it is on the device, or on a shelf it isn't on.
+      // Neither is defaulted — an unrecognised value collapses the whole frame to a
+      // refusal, because "saved, somewhere" is worse than "didn't save".
+      case "library_saved": {
+        if (typeof frame.id !== "string" || !frame.id) break;
+        const shelfOk =
+          typeof frame.shelf === "string" && (LIBRARY_SHELVES as readonly string[]).includes(frame.shelf);
+        const storageOk = frame.storageType === "local" || frame.storageType === "cloud";
+        const result: LibrarySaveResult =
+          frame.ok === true && shelfOk && storageOk
+            ? {
+                ok: true,
+                shelf: frame.shelf as LibraryShelf,
+                storageType: frame.storageType as "cloud" | "local",
+                name: typeof frame.name === "string" ? frame.name : "",
+                bytes: typeof frame.bytes === "number" && Number.isFinite(frame.bytes) ? frame.bytes : 0,
+              }
+            : {
+                ok: false,
+                reason:
+                  typeof frame.reason === "string" && frame.reason
+                    ? frame.reason
+                    : "the app refused the save without giving a reason",
+              };
+        this.cb.onLibrarySaved?.(frame.id, result);
+        break;
+      }
       // The app's answer to a chart op. Re-typed rather than trusted, for the same
       // reason cargo_saved is: the id keys a pending tool call and the payload is
       // quoted to the model.
@@ -1457,6 +1507,42 @@ export class RelayClient {
     this.rawSend({ type: "cargo_end", id });
   }
 
+  // Ask the app to save a file into the account's Library: it classifies the file,
+  // encrypts under the account master key (which this process does not have — see
+  // librarySave.ts) and files it on the matching shelf, then answers with a
+  // library_saved keyed by `id`.
+  //
+  // Chunked like sendFile and requestCargoSave, and for the relay's reason rather
+  // than the payload's: a frame caps at 256 KB and a file may be 25 MB. Ordering is
+  // the WS's, so the app can reject a seq gap as a dropped transfer rather than
+  // silently filing a truncated file — which for binary media means a row that opens
+  // to a broken image the user finds weeks later.
+  //
+  // Yields between frames of a multi-chunk send for sendFile's reason: a 25 MB file
+  // is ~140 frames, and pushing them in one synchronous burst starves the event loop
+  // for the whole transfer, including the heartbeat that keeps this socket up.
+  //
+  // NOT run through `safe()`. It redacts secrets, and redacting inside a file is
+  // corruption — a PNG with `[redacted]` spliced into its pixel data is not an
+  // image. Same call sendFile makes about its bytes; the tool decides what is safe
+  // to send.
+  async requestLibrarySave(id: string, req: LibrarySaveRequest): Promise<void> {
+    this.flushDeltas(); // land the save in order relative to buffered text
+    this.rawSend({
+      type: "library_begin",
+      id,
+      name: clip(req.name, 200),
+      mediaType: req.mediaType,
+      size: req.size,
+      note: req.note ? clip(req.note, 500) : undefined,
+    });
+    for (let off = 0, seq = 0; off < req.base64.length; off += LIBRARY_CHUNK_CHARS, seq++) {
+      this.rawSend({ type: "library_chunk", id, seq, data: req.base64.slice(off, off + LIBRARY_CHUNK_CHARS) });
+      if (req.base64.length > LIBRARY_CHUNK_CHARS) await new Promise((r) => setImmediate(r));
+    }
+    this.rawSend({ type: "library_end", id });
+  }
+
   // Ask the app to run a chart operation: it decrypts to read, encrypts to write, and
   // answers with a chart_result keyed by `id`. See chartOps.ts for why the round trip
   // is the feature rather than a convenience.

package/src/remote/remoteBridge.ts

@@ -16,6 +16,7 @@ import type { PermissionRequest } from "../permissions/gate.ts";
 import type { AskOutcome } from "../permissions/modeGate.ts";
 import type { RelayCallbacks } from "./relayClient.ts";
 import type { CargoSaveRequest, CargoSaveResult } from "./cargoSave.ts";
+import type { LibrarySaveRequest, LibrarySaveResult } from "./librarySave.ts";
 import type { ChartOpRequest, ChartOpResult } from "./chartOps.ts";
 
 // How much of a driven turn's reply we hold for possible outbox delivery. The
@@ -36,6 +37,14 @@ const cargoSaveTimeoutMs = (): number => Number(process.env.PRIVATEER_CARGO_TIME
 // work, not a round trip.
 const chartOpTimeoutMs = (): number => Number(process.env.PRIVATEER_CHART_TIMEOUT_MS) || 60_000;
 
+// How long the app gets to file a Library save. Longer than the two above, and the
+// difference is real work rather than slack: those move a document and a few cards,
+// this moves up to 25 MB across the relay and then puts it through an encrypt and an
+// S3 upload on the other side. A phone on a mobile connection can spend a minute on
+// that legitimately, and timing out on a save that then succeeds is the worst
+// outcome — the model tells the user it failed while the file is in their library.
+const librarySaveTimeoutMs = (): number => Number(process.env.PRIVATEER_LIBRARY_TIMEOUT_MS) || 180_000;
+
 // The outbound surface the bridge needs; RelayClient implements all of it.
 export interface RelayLike {
   requestApproval(id: string, req: PermissionRequest): void;
@@ -56,6 +65,9 @@ export interface RelayLike {
   sendSkills(payload: SkillsPayload): void;
   requestCargoSave(id: string, req: CargoSaveRequest): void;
   requestChartOp(id: string, req: ChartOpRequest): void;
+  // Async, unlike its two siblings: a multi-megabyte send yields between frames so it
+  // can't starve the event loop, so the transport has a promise to hand back.
+  requestLibrarySave(id: string, req: LibrarySaveRequest): Promise<void>;
 }
 
 // The installed-extensions snapshot relayed to the app's extensions manager.
@@ -158,6 +170,7 @@ export class RemoteBridge {
   private readonly pendingInputs = new Map<string, (v: string | null) => void>();
   private readonly pendingCargo = new Map<string, (r: CargoSaveResult) => void>();
   private readonly pendingCharts = new Map<string, (r: ChartOpResult) => void>();
+  private readonly pendingLibrary = new Map<string, (r: LibrarySaveResult) => void>();
   private pendingAttachments: RemoteAttachment[] = [];
   // The driven turn in flight, kept only so it can be delivered to the outbox if it
   // turns out nobody was watching (see settleTurn). Bounded: the outbox truncates at
@@ -253,6 +266,10 @@ export class RemoteBridge {
       const resolve = this.pendingCargo.get(id);
       if (resolve) resolve(result);
     },
+    onLibrarySaved: (id, result) => {
+      const resolve = this.pendingLibrary.get(id);
+      if (resolve) resolve(result);
+    },
     onChartResult: (id, result) => {
       const resolve = this.pendingCharts.get(id);
       if (resolve) resolve(result);
@@ -480,6 +497,53 @@ export class RemoteBridge {
     });
   };
 
+  // Hand a file to the app to classify, encrypt and file in the user's Library (the
+  // save_to_library tool), and wait for its verdict. Structurally the twin of
+  // saveCargoRemote — the app owns the master key, so this process cannot file
+  // anything itself — with two differences worth stating, because both change what a
+  // failure means:
+  //
+  //  - The send is AWAITED. requestLibrarySave yields between frames so a 25 MB
+  //    transfer can't starve the event loop, so unlike the cargo path the frames are
+  //    not all on the wire by the time we start waiting. A send that throws (the
+  //    socket died mid-transfer) settles as a refusal rather than leaving the tool
+  //    waiting out the full deadline for an answer to a message that never arrived.
+  //  - The deadline is longer (see librarySaveTimeoutMs). Timing out early here is
+  //    the expensive mistake: the app may still be uploading, and the model would
+  //    tell the user their file didn't save while it lands in their library.
+  saveToLibraryRemote = (req: LibrarySaveRequest, signal?: AbortSignal): Promise<LibrarySaveResult> => {
+    if (!this.relay) return Promise.resolve({ ok: false, reason: "remote access is not enabled — run /remote-access on and drive this terminal from the Privateer app" });
+    if (!this.relay.isConnected()) return Promise.resolve({ ok: false, reason: "the relay is not connected" });
+    if (this.relay.hasController && !this.relay.hasController()) {
+      return Promise.resolve({ ok: false, reason: "the Privateer app is not attached to this terminal — only the app holds the key that encrypts a file, so open it and attach before saving" });
+    }
+    const id = randomUUID();
+    return new Promise<LibrarySaveResult>((resolve) => {
+      const settle = (r: LibrarySaveResult) => {
+        if (!this.pendingLibrary.has(id)) return; // already settled (abort raced the reply)
+        this.pendingLibrary.delete(id);
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(r);
+      };
+      const onAbort = () => settle({ ok: false, reason: "the turn was interrupted before the app confirmed the save" });
+      const deadline = librarySaveTimeoutMs();
+      const timer = setTimeout(
+        () => settle({ ok: false, reason: `the app did not answer within ${Math.round(deadline / 1000)}s — it may be an older version that cannot save files from a terminal, or the upload is still running` }),
+        deadline,
+      );
+      timer.unref?.();
+      this.pendingLibrary.set(id, settle);
+      if (signal) {
+        if (signal.aborted) return onAbort();
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      void this.relay!.requestLibrarySave(id, req).catch((e) =>
+        settle({ ok: false, reason: `the transfer failed before the app could file it: ${(e as Error)?.message || "connection lost"}` }),
+      );
+    });
+  };
+
   // Run a chart operation on the app and wait for its answer. Structurally the twin of
   // saveCargoRemote — the app owns the master key, so reading a card and writing one are
   // both round trips — with one difference worth stating: this is the only place the CLI
@@ -545,5 +609,14 @@ export class RemoteBridge {
       resolve({ ok: false, reason: "the app disconnected before answering — some of the change may already have been applied; open the chart in the app to see what landed before trying again" });
     }
     this.pendingCharts.clear();
+    // A Library save whose controller vanished mid-flight gets the same honest
+    // "unknown" wording as a cargo save, and the stakes are the same shape: the app
+    // may have encrypted and filed the file before its socket dropped. Telling the
+    // model it failed invites a retry that leaves the user with the same picture in
+    // their library twice, under the same name, with no way to tell which is which.
+    for (const resolve of this.pendingLibrary.values()) {
+      resolve({ ok: false, reason: "the app disconnected before confirming the save — it may or may not have filed the file; check the library in the app before saving again" });
+    }
+    this.pendingLibrary.clear();
   }
 }

package/src/tools/relayFileTools.ts

@@ -15,6 +15,7 @@ import { makeSendFileTool, type SendFileBridge } from "./sendFile.ts";
 import { makeSaveAttachmentTool } from "./saveAttachment.ts";
 import { makeSaveCargoTool, type CargoSaveBridge } from "./cargo.ts";
 import { makeChartTools, type ChartOpBridge } from "./charts.ts";
+import { makeSaveToLibraryTool, type LibrarySaveBridge } from "./saveToLibrary.ts";
 import type { AttachmentStore } from "../util/attachmentStore.ts";
 
 // save_cargo rides with the file pair rather than with the media tools, because it
@@ -22,17 +23,27 @@ import type { AttachmentStore } from "../util/attachmentStore.ts";
 // account. Registering it in the moat's media block would put it in every harbor and
 // channels session, where there is no controller and every call would fail — see
 // remote/cargoSave.ts on why unattended runs deliver an artifact a different way.
+// save_to_library rides here for save_cargo's reason exactly — it needs a CONNECTED
+// APP rather than a signed-in account, because only the app holds the master key that
+// a Library row's ciphertext is under. Putting it in the moat's media block would give
+// it to every harbor and channels session, where there is no controller and every call
+// would fail; an unattended run already delivers a file a different way, as a sealed
+// attachment on its Inbox result (routines/resultMedia.ts).
 // The chart tools ride here too, for the same reason save_cargo does and one more of
 // their own. Same reason: they need a CONNECTED APP, not a signed-in account, so the
 // moat's media block would put them in every harbor and channels session where there is
 // no controller and every call would fail. Their own reason: unlike cargo they also READ
 // the user's stored content, so an unattended session that could call them would be a
 // terminal asking for decrypted chat content with nobody watching the request.
-export function makeRelayFileTools(bridge: SendFileBridge & CargoSaveBridge & ChartOpBridge, attachments: AttachmentStore) {
+export function makeRelayFileTools(
+  bridge: SendFileBridge & CargoSaveBridge & ChartOpBridge & LibrarySaveBridge,
+  attachments: AttachmentStore,
+) {
   return function relayFileTools(pi: any): void {
     pi.registerTool?.(makeSendFileTool(bridge));
     pi.registerTool?.(makeSaveAttachmentTool(attachments));
     pi.registerTool?.(makeSaveCargoTool(bridge));
+    pi.registerTool?.(makeSaveToLibraryTool(bridge));
     for (const tool of makeChartTools(bridge)) pi.registerTool?.(tool);
   };
 }

package/src/tools/saveToLibrary.ts

@@ -0,0 +1,181 @@
+// The `save_to_library` tool — put a file from disk into the user's Privateer
+// account, where it lives beside everything else they own and reaches every
+// device they have signed in.
+//
+// The interesting part is not this file, it's why the save is a round trip
+// through the app at all — src/remote/librarySave.ts has that (short version:
+// the terminal holds no master key, and every Library row is ciphertext). What
+// matters here is the shape that follows from it:
+//
+// TAKES A PATH, NOT CONTENT. Same call save_cargo makes, and here it isn't even
+// close: a file may be 25 MB, and no amount of it belongs in a tool call. The
+// model WRITES the file with its ordinary tools — or generates it, which is the
+// common case, since every generate_* tool already names an output path — and
+// passes that path. The two compose without either knowing about the other:
+// generate_image writes a PNG, save_to_library puts it in the user's pocket.
+//
+// DOES NOT CHOOSE WHERE IT LANDS, AND SAYS SO. There is deliberately no
+// `destination: 'local' | 'cloud'` parameter, and adding one would be a
+// privacy bug rather than a feature. Whether an account's files live on its
+// device or in our cloud is a setting the person owns (treeview CLAUDE.md §2);
+// a terminal that could override it could put bytes on our servers for someone
+// who chose device-only storage. So the app decides from the account, and this
+// tool REPORTS which one happened — the success line names it, so the model can
+// tell the user where their file actually is without ever having picked.
+//
+// Which SHELF it lands on is the app's call for a smaller reason: the app
+// classifies a file the same way it classifies one the user drags in, and a
+// second table on this side would drift into filing a generated PNG under
+// Documents. The result names the shelf so the model can say where to look.
+//
+// SAYS WHAT DID AND DIDN'T TRAVEL. Like save_cargo and unlike the generate_*
+// tools, this is genuinely end-to-end encrypted: the app encrypts before the
+// upload and the server stores ciphertext it cannot read. A model that can't
+// tell the two apart will describe generation with this one's guarantees, so
+// the description states it plainly and the success line repeats it.
+
+import { Type } from "typebox";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, isAbsolute, resolve } from "node:path";
+import {
+  MAX_LIBRARY_SAVE_BYTES,
+  libraryMediaTypeForPath,
+  type LibrarySaveRequest,
+  type LibrarySaveResult,
+} from "../remote/librarySave.ts";
+
+function text(t: string) {
+  return { content: [{ type: "text", text: t }], details: {} };
+}
+
+/** The bridge surface this tool needs; RemoteBridge implements it. */
+export interface LibrarySaveBridge {
+  saveToLibraryRemote(req: LibrarySaveRequest, signal?: AbortSignal): Promise<LibrarySaveResult>;
+}
+
+export const LIBRARY_TOOL_NAMES = ["save_to_library"] as const;
+
+/** Where the app filed it, in the words the app's own navigation uses. */
+const SHELF_LABEL: Record<string, string> = {
+  image: "Images",
+  video: "Videos",
+  audio: "Audio",
+  model3d: "Models",
+  document: "Documents",
+};
+
+export function makeSaveToLibraryTool(bridge: LibrarySaveBridge) {
+  return {
+    name: "save_to_library",
+    label: "Save to Library",
+    description:
+      "Save a file from disk into the user's Privateer account, so it appears in their Library on every " +
+      "device they're signed in on rather than only in this working directory. Use whenever the user asks " +
+      "to KEEP something you made or found — an image, a video, an audio clip, a 3D model, a report, a " +
+      "spreadsheet. Write or generate the file first with your normal tools and pass its path.\n" +
+      "Handles images (png/jpg/gif/webp), video (mp4/mov/webm), audio (mp3/wav/m4a/aac/ogg/flac), 3D " +
+      "models (glb/obj/fbx/usdz) and documents (pdf, docx, csv, and text or code files). Each lands on the " +
+      "matching shelf in the Library — you don't choose which, and the result tells you where it went so " +
+      "you can say. Max 25 MB; a bigger file, or a format not in that list, can still be handed over with " +
+      "send_file_to_client, which shows it on the user's device without filing it.\n" +
+      "You also do NOT choose whether it goes to the cloud or stays on the device — that follows the " +
+      "user's own storage setting, and the result reports which one happened. Say what it reports; don't " +
+      "assume cloud.\n" +
+      "Needs the Privateer app attached to this terminal: the app holds the key, and it encrypts the file " +
+      "on the device before storing it, so the contents are never readable by the server. That is a " +
+      "stronger guarantee than the generate_* tools have — do not describe those the same way.",
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Path of the file to save, relative to cwd or absolute (e.g. 'out/cover.png').",
+      }),
+      name: Type.Optional(
+        Type.String({
+          description:
+            "Name to file it under in the Library, WITH its extension. Say what the thing is, the way the " +
+            "user would name it ('Q3 Expenses.csv', 'Harbour at dusk.png') — not a build path. Defaults to " +
+            "the file's own name, which is usually worse.",
+        }),
+      ),
+      note: Type.Optional(
+        Type.String({
+          description:
+            "One line on where it came from — the prompt that drew it, the command that produced it. " +
+            "Stored encrypted alongside the file. Not a title: the Library titles the row from `name`.",
+        }),
+      ),
+    }),
+    async execute(
+      _toolCallId: string,
+      params: { path: string; name?: string; note?: string },
+      signal?: AbortSignal,
+      _onUpdate?: unknown,
+      ctx?: { cwd?: string },
+    ) {
+      if (!params.path) return text("Error: path is required — say which file to save.");
+      const cwd = ctx?.cwd ?? process.cwd();
+      const target = isAbsolute(params.path) ? params.path : resolve(cwd, params.path);
+
+      if (!existsSync(target)) return text(`File not found: ${params.path}`);
+      const stat = statSync(target);
+      if (stat.isDirectory()) return text(`${params.path} is a directory — save a single file.`);
+      if (stat.size === 0) return text(`${params.path} is empty — nothing to save.`);
+      if (stat.size > MAX_LIBRARY_SAVE_BYTES) {
+        return text(
+          `${params.path} is ${(stat.size / 1048576).toFixed(1)} MB; saving to the library caps at ` +
+            `${MAX_LIBRARY_SAVE_BYTES / 1048576} MB. Use send_file_to_client to hand it to the user's device instead.`,
+        );
+      }
+
+      // The NAME decides the shelf, not the path — the app classifies on the name,
+      // and the name is what the user will see. So the extension has to survive a
+      // rename, and a model asked for a human title will reliably drop it: told to
+      // name a file the way the user would, it answers 'Q3 Expenses', not
+      // 'Q3 Expenses.csv'. Borrowing the source file's extension is the honest
+      // repair — it keeps the name the model chose AND the type the bytes actually
+      // are. Refusing instead would reject a request that is right about everything
+      // that matters, and dropping the name silently would have the model tell the
+      // user about a file called something it isn't.
+      const named = params.name?.trim();
+      const fileName = named ? (extname(named) ? named : named + extname(target)) : basename(target);
+      const mediaType = libraryMediaTypeForPath(fileName);
+      if (!mediaType) {
+        const ext = extname(fileName);
+        return text(
+          `${fileName} can't go in the library: ${ext || "a file with no extension"} isn't a format it holds. ` +
+            `The library holds images (png/jpg/gif/webp), video (mp4/mov/webm), audio (mp3/wav/m4a/aac/ogg/flac), ` +
+            `3D models (glb/obj/fbx/usdz) and documents (pdf, docx, csv, text and code files). ` +
+            `To put any other file on the user's device, use send_file_to_client.`,
+        );
+      }
+      let bytes: Buffer;
+      try {
+        bytes = readFileSync(target);
+      } catch (e) {
+        return text(`Couldn't read ${params.path}: ${(e as Error).message}`);
+      }
+
+      const res = await bridge.saveToLibraryRemote(
+        {
+          base64: bytes.toString("base64"),
+          size: bytes.length,
+          name: fileName,
+          mediaType,
+          note: params.note?.trim() || undefined,
+        },
+        signal,
+      );
+
+      if (!res.ok) return text(`Couldn't save ${fileName} to the library: ${res.reason}`);
+
+      const shelf = SHELF_LABEL[res.shelf] ?? res.shelf;
+      const where =
+        res.storageType === "local"
+          ? "It is stored on this account's device, which is where this account keeps its files — it is not on our servers"
+          : "It went to the account's cloud storage, encrypted on the device first, so the server holds only ciphertext";
+      return text(
+        `Saved "${res.name}" to the Library under ${shelf} (${(res.bytes / 1024).toFixed(0)} KB). ` +
+          `${where}. The user can open, download and share it from the Library in the Privateer app.`,
+      );
+    },
+  };
+}