privateer-agent 0.12.21 → 0.12.23

package/src/tools/media.ts

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

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.`,
+      );
+    },
+  };
+}