privateer-agent 0.12.21 → 0.12.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.21",
+  "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/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/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.`,
+      );
+    },
+  };
+}