privateer-agent 0.12.21 → 0.12.23

package/src/providers/account.ts

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

package/src/providers/defaultModel.ts

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

package/src/providers/vision.ts

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

package/src/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();
   }
 }