privateer-agent 0.14.3 → 0.14.4

package/extensions/privateer-gate.ts

@@ -640,10 +640,10 @@ export default function privateerControl(pi: any): void {
   // driving. The daemon no longer loads this file, so there is nothing to shadow.
   pi.registerTool?.(makeSendFileTool(bridge));
   pi.registerTool?.(makeSaveAttachmentTool(attachments));
-  // save_cargo belongs with them: it is the same bridge, the same "needs a connected
-  // app" precondition, and the same failure mode if it were registered anywhere the
-  // relay isn't this file's. Unlike the pair it hands the app PLAINTEXT to encrypt —
-  // the terminal has no master key, so the round trip is the feature (cargoSave.ts).
+  // save_cargo belongs with them: it tries this bridge's attached app first, which hands
+  // the app PLAINTEXT to encrypt — the terminal has no master key (cargoSave.ts). With no
+  // app attached (remote access off, or nobody driving) it queues the artifact sealed to
+  // the account instead, and the next app to open files it.
   pi.registerTool?.(makeSaveCargoTool(bridge));
   // The chart tools, for the same reasons and one more. Same: this bridge, the same
   // "needs a connected app" precondition, the same plaintext-out/app-encrypts round trip

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "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

@@ -306,6 +306,18 @@ export async function buildMoat(opts: MoatOptions): Promise<ExtensionFactory[]>
   if (opts.relayFiles) {
     const { makeRelayFileTools } = await import("../tools/relayFileTools.ts");
     factories.push(makeRelayFileTools(opts.relayFiles.bridge, opts.relayFiles.attachments));
+  } else {
+    // No relay of its own — a harbor run, a channels or ACP session — so no app can ever
+    // be attached. save_cargo still exists here, QUEUE-ONLY: it seals the artifact to the
+    // account and the next app to open files it (remote/cargoSave.ts). Signed-in only,
+    // because the queue is the account's; a signed-out session gets no tool rather than
+    // one that refuses every call. The rest of the relay set stays out: send_file needs
+    // a live app to receive bytes, and the chart tools READ decrypted content back.
+    const { hasCredentials } = await import("../auth/privateer.ts");
+    if (hasCredentials()) {
+      const { makeSaveCargoTool } = await import("../tools/cargo.ts");
+      factories.push((pi: any) => { pi.registerTool?.(makeSaveCargoTool()); });
+    }
   }
 
   if (opts.resultMedia) {

package/src/config/whatsNew.json

@@ -1,10 +1,10 @@
 {
   "$comment": "The banner's What's New list, newest first: the two to four things a returning user should notice, not a changelog. `reviewedFor` is the release this list was last looked at for. A release can't ship until it equals package.json's version (scripts/check-whats-new.mjs, run by `npm test` and by release.yml before anything builds), so every release, patches included, is a deliberate look at this list. If nothing new is worth a line, bumping `reviewedFor` alone is the answer. `since` is the release an entry arrived in. `cmd` is shown in the accent colour.",
-  "reviewedFor": "0.14.3",
+  "reviewedFor": "0.14.4",
   "items": [
+    { "text": "Save to Cargo with no app attached — it lands on your next app open", "since": "0.14.4" },
     { "text": "Several privateer -p runs at once no longer sign each other out", "since": "0.14.3" },
     { "text": "A reply cut off at the output limit picks back up on its own", "since": "0.14.2" },
-    { "text": "Chat channels as a login service: privateer channels install", "since": "0.14.1" },
-    { "text": "Hand off sensitive files: privateer --private", "since": "0.14.0" }
+    { "text": "Chat channels as a login service: privateer channels install", "since": "0.14.1" }
   ]
 }

package/src/outbox/cloudOutbox.ts

@@ -26,12 +26,13 @@
 // per-instance caches this replaced.
 
 import { readFileSync, existsSync, statSync } from "node:fs";
-import { apiRequest, defaultDeviceLabel } from "../auth/privateer.ts";
+import { apiRequest, defaultDeviceLabel, hasCredentials } from "../auth/privateer.ts";
 import { loadAccountSignKey } from "../crypto/accountTrust.ts";
 import { verifyOutboxKey } from "../crypto/accountVerify.ts";
 import { sealJson, seal, decodeAccountPublicKey } from "../crypto/outboxSeal.ts";
 import { routineRelayId, type OutboxKind } from "../routines/store.ts";
 import { MAX_ATTACHMENT_BYTES, type MediaClass, type StagedMedia } from "../routines/resultMedia.ts";
+import type { CargoSaveRequest } from "../remote/cargoSave.ts";
 
 export type { OutboxKind };
 
@@ -337,3 +338,77 @@ export async function postOutbox(
     return false;
   }
 }
+
+// ── Queued Cargo saves ───────────────────────────────────────────────────────
+//
+// `save_cargo` with no app attached (remote/cargoSave.ts has the why). Its own mailbox,
+// /api/outbox/cargo, not an outbox item: every shipped app acks every item it fetches,
+// so an artifact sent as one would be eaten — acked and never filed — by any device
+// still on an older build, and filing has to happen once per account, which needs the
+// server-side claim that mailbox has and this one doesn't.
+
+/** Ceiling on the sealed artifact, matching the server's MAX_CARGO_SEALED_BYTES. */
+export const MAX_QUEUED_CARGO_SEALED_BYTES = 2 * 1024 * 1024;
+
+/**
+ * The plaintext the app opens — treeview client/utils/queuedCargoParse.ts reads exactly
+ * this. `type` (not `kind`) names the envelope: `kind` is the artifact's, and the app's
+ * reader refuses anything that isn't a cargo envelope rather than guessing.
+ */
+export function queuedCargoEnvelope(req: CargoSaveRequest, at: Date, origin: { id: string; label: string }) {
+  return {
+    v: 1,
+    type: "cargo",
+    kind: req.kind,
+    ...(req.title ? { title: req.title } : {}),
+    content: req.content,
+    at: at.toISOString(),
+    origin,
+  };
+}
+
+export type QueuedCargoResult = { ok: true; id: string } | { ok: false; reason: string };
+
+/**
+ * Seal one artifact to the account and park it for the app to file. Never throws;
+ * every failure comes back as a reason written for the model to repeat.
+ */
+export async function postQueuedCargo(req: CargoSaveRequest): Promise<QueuedCargoResult> {
+  if (!hasCredentials()) {
+    return { ok: false, reason: "this terminal is not signed in to a Privateer account — run /signin, then save again" };
+  }
+  const pub = await ensureOutboxPub();
+  if (!pub) {
+    // No pinned account key, or one the published key doesn't verify against. Either way
+    // sealing would be to a key nobody has shown belongs to this account — fail closed.
+    return {
+      ok: false,
+      reason:
+        "the account's encryption key could not be verified from this terminal — open the Privateer app once (it publishes the key), " +
+        "or re-link this terminal from the app, then save again",
+    };
+  }
+  const sealed = sealJson(pub, queuedCargoEnvelope(req, new Date(), machineOrigin()));
+  if (Math.floor((sealed.length * 3) / 4) > MAX_QUEUED_CARGO_SEALED_BYTES) {
+    return { ok: false, reason: "the artifact is too large to queue — trim it below 512 KB" };
+  }
+  try {
+    const res = await apiRequest("/api/outbox/cargo", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ sealed }),
+    });
+    if (res.ok) {
+      const data = (await res.json().catch(() => ({}))) as { id?: unknown };
+      return { ok: true, id: typeof data.id === "string" ? data.id : "" };
+    }
+    if (res.status === 404) {
+      return { ok: false, reason: "the Privateer server does not accept queued artifacts yet — attach the app to this terminal and save again" };
+    }
+    const err = (await res.json().catch(() => ({}))) as { message?: unknown };
+    const message = typeof err.message === "string" && err.message ? err.message : `the server answered ${res.status}`;
+    return { ok: false, reason: `the server refused to queue it: ${message}` };
+  } catch (e) {
+    return { ok: false, reason: `the server could not be reached (${(e as Error).message})` };
+  }
+}

package/src/permissions/classify.ts

@@ -374,7 +374,7 @@ export function classifyToolCall(
       tool: toolName,
       kind: "write",
       title: protectedSrc ? "Save a protected file to Cargo in the app" : "Save to Cargo in the Privateer app",
-      detail: `${outside || protectedSrc ? abs : src}${kindNote}${titleNote} → the app encrypts it and stores it in Cargo`,
+      detail: `${outside || protectedSrc ? abs : src}${kindNote}${titleNote} → the app encrypts it and stores it in Cargo (queued, sealed, if no app is attached)`,
       protected: protectedSrc,
       outside,
       path: abs,

package/src/remote/cargoSave.ts

@@ -18,10 +18,21 @@
 // model-authored one does. Nothing new reaches the server, and no new endpoint
 // exists.
 //
-// WHAT THAT COSTS. The app has to be attached. A harbor is headless by design and
-// there is no controller to ask, so save_cargo is not registered there — an
-// unattended run still delivers an artifact the way it always has, as a fence in
-// its Inbox result (routines/resultBrief.ts). Don't "fix" that by widening this.
+// WHEN NO APP IS ATTACHED. The live round trip needs an app on the other end, and
+// requiring one made save_cargo useless exactly where it was wanted most: a terminal
+// nobody is driving, and every harbor. So with no app attached the artifact is QUEUED
+// instead (outbox/cloudOutbox.ts postQueuedCargo): sealed to the account's X25519
+// outbox public key — the same write-only sealed box Inbox results use, verified
+// against the account signing key pinned at link — and parked at /api/outbox/cargo.
+// The next app to sync opens it and files it through the very same saveCargo()
+// (treeview client/services/queuedCargoService.ts). The master key still never
+// leaves the app, the server still holds only ciphertext, and the stored row is the
+// one the live path would have made. What the queue cannot do is confirm: there is no
+// cargoId until an app files it, and the tool says exactly that.
+//
+// Only an UNATTACHED failure falls back (`unattached: true` below). An app that
+// refused, timed out, or dropped mid-transfer may already have stored the artifact,
+// and queueing it as well is how a user ends up with two copies.
 
 /** Cargo artifact kinds — mirrors client/utils/cargoKinds.ts CargoKind. */
 export const CARGO_KINDS = ["webpage", "slides", "game", "pdf", "docx", "md", "sheet"] as const;
@@ -102,4 +113,7 @@ export interface CargoSaveRequest {
  */
 export type CargoSaveResult =
   | { ok: true; cargoId: string; title: string; storageType: string }
-  | { ok: false; reason: string };
+  | { ok: false; reason: string; unattached?: true };
+
+/** Is this failure "there was no app to ask" — the one a queued save may follow? */
+export const isUnattached = (r: CargoSaveResult): boolean => !r.ok && r.unattached === true;

package/src/remote/remoteBridge.ts

@@ -522,12 +522,15 @@ export class RemoteBridge {
   //    way the gate wraps remoteAsk, so a silent or too-old app would wedge the turn
   //    forever without one.
   saveCargoRemote = (req: CargoSaveRequest, signal?: AbortSignal): Promise<CargoSaveResult> => {
-    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" });
+    // The three "nobody to ask" answers carry `unattached`, which is what lets the tool
+    // queue the artifact for the app instead (cargoSave.ts). Nothing was sent, so there is
+    // no chance a queued copy duplicates one the app stored.
+    if (!this.relay) return Promise.resolve({ ok: false, unattached: true, 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, unattached: true, reason: "the relay is not connected" });
     // hasController is optional on RelayLike; a transport that can't tell is treated as
     // attached, matching how the rest of the bridge reads it.
     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 an artifact, so open it and attach before saving" });
+      return Promise.resolve({ ok: false, unattached: true, reason: "the Privateer app is not attached to this terminal" });
     }
     const id = randomUUID();
     return new Promise<CargoSaveResult>((resolve) => {

package/src/tools/cargo.ts

@@ -2,10 +2,12 @@
 // Cargo: a titled, runnable artifact they can open, edit, download and share
 // from any of their devices, not a path that only exists on this machine.
 //
-// The interesting part is not this file, it's why the save is a round trip
-// through the app at all — src/remote/cargoSave.ts has that (short version: the
-// terminal holds no master key, and a Cargo row is ciphertext). What matters
-// here is the shape that follows from it:
+// The interesting part is not this file, it's why the save goes through the app
+// at all — src/remote/cargoSave.ts has that (short version: the terminal holds no
+// master key, and a Cargo row is ciphertext). Two routes follow from it: with an
+// app attached, a live round trip that comes back with the stored row's id; with
+// none, the artifact is sealed to the account and QUEUED for the next app to file.
+// What matters here is the shape that follows:
 //
 // TAKES A PATH, NOT CONTENT. An artifact runs to half a megabyte. Inlining that
 // into a tool call would spend the whole thing in tokens, twice — once when the
@@ -28,6 +30,11 @@
 // generation's posture (media.ts's header is blunt about that). A model that
 // can't tell the two apart will describe one with the other's guarantees, so the
 // description states this one plainly and the success line repeats it.
+//
+// AND WHAT HASN'T HAPPENED YET. A queued save is not a saved one: it is in no
+// Cargo list until an app opens and files it. The queued line says so in as many
+// words, because "saved" would send the user to look for something that isn't
+// there yet.
 
 import { Type } from "typebox";
 import { existsSync, readFileSync, statSync } from "node:fs";
@@ -39,9 +46,11 @@ import {
   isHtmlKind,
   kindForExtension,
   type CargoKind,
+  isUnattached,
   type CargoSaveRequest,
   type CargoSaveResult,
 } from "../remote/cargoSave.ts";
+import { postQueuedCargo, type QueuedCargoResult } from "../outbox/cloudOutbox.ts";
 
 function text(t: string) {
   return { content: [{ type: "text", text: t }], details: {} };
@@ -52,6 +61,9 @@ export interface CargoSaveBridge {
   saveCargoRemote(req: CargoSaveRequest, signal?: AbortSignal): Promise<CargoSaveResult>;
 }
 
+/** Where an artifact goes when no app is attached. Injectable for tests. */
+export type CargoQueue = (req: CargoSaveRequest) => Promise<QueuedCargoResult>;
+
 export const CARGO_TOOL_NAMES = ["save_cargo"] as const;
 
 /**
@@ -71,7 +83,11 @@ function kindMatchesExtension(kind: CargoKind, ext: string): boolean {
   return implied === "md" && (kind === "md" || kind === "pdf" || kind === "docx");
 }
 
-export function makeSaveCargoTool(bridge: CargoSaveBridge) {
+/**
+ * `bridge` is the live route — absent in a session with no relay of its own (a harbor
+ * run, a channels session), which then only ever queues. `queue` is the other route.
+ */
+export function makeSaveCargoTool(bridge?: CargoSaveBridge, queue: CargoQueue = postQueuedCargo) {
   return {
     name: "save_cargo",
     label: "Save to Cargo",
@@ -85,9 +101,11 @@ export function makeSaveCargoTool(bridge: CargoSaveBridge) {
       "inlined, since it opens with no network and no sibling files), .md (kind md, pdf or docx — the " +
       "kind picks what Download produces) and .csv (kind sheet). Max 512 KB; other file types cannot be " +
       "Cargo — use send_file_to_client to hand the user an image, video or PDF instead.\n" +
-      "Needs the Privateer app attached to this terminal: the app holds the key, and it encrypts the " +
-      "artifact on the device before storing it, so the content is never readable by the server. That is " +
-      "a stronger guarantee than the generate_* tools have — do not describe those the same way.",
+      "Works whether or not the Privateer app is attached. Attached: the app encrypts and stores it now. " +
+      "Not attached: the artifact is sealed to the user's account key and queued, and the app files it the " +
+      "next time it opens — it is NOT in Cargo until then, so say that rather than that it is saved. Either " +
+      "way only the user's app can read it; the server holds ciphertext. 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. 'build/tower-defence.html').",
@@ -165,11 +183,27 @@ export function makeSaveCargoTool(bridge: CargoSaveBridge) {
       }
       if (!content.trim()) return text(`${params.path} has no content to save.`);
 
-      const res = await bridge.saveCargoRemote(
-        { content, kind, title: params.title?.trim() || undefined },
-        signal,
-      );
+      const req: CargoSaveRequest = { content, kind, title: params.title?.trim() || undefined };
+      const res: CargoSaveResult = bridge
+        ? await bridge.saveCargoRemote(req, signal)
+        : { ok: false, unattached: true, reason: "no app is attached to this session" };
 
+      if (!res.ok && isUnattached(res)) {
+        const queued = await queue(req);
+        if (!queued.ok) {
+          return text(
+            `Couldn't save ${basename(target)} to Cargo. No Privateer app is attached (${res.reason}), ` +
+              `and queueing it for the app failed: ${queued.reason}.`,
+          );
+        }
+        const label = req.title ? `"${req.title}"` : basename(target);
+        return text(
+          `Queued ${label} for Cargo (${kind}, ${(stat.size / 1024).toFixed(0)} KB). No Privateer app is attached right now, ` +
+            `so it was sealed to the user's account key and parked on the server as ciphertext only their app can open. ` +
+            `It will appear in Cargo the next time the Privateer app opens on any of their devices — it is not there yet, ` +
+            `so tell the user that rather than that it is saved.`,
+        );
+      }
       if (!res.ok) return text(`Couldn't save ${basename(target)} to Cargo: ${res.reason}`);
       return text(
         `Saved "${res.title}" to Cargo (${kind}, ${(stat.size / 1024).toFixed(0)} KB, ${res.storageType} storage, id ${res.cargoId}). ` +

package/src/tools/relayFileTools.ts

@@ -18,18 +18,18 @@ 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
-// shares their precondition and not media's: it needs a CONNECTED APP, not a signed-in
-// 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
+// save_cargo rides with the file pair because, in a session that HAS a relay, it should
+// try the attached app first: that path comes back with the stored row. With no app
+// attached it queues the artifact for the next app to file instead (remote/cargoSave.ts),
+// which is also how a session with no relay at all gets it — config/moat.ts registers a
+// queue-only copy there.
+// save_to_library rides here because 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
+// The chart tools ride here too, for save_to_library's reason 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