privateer-agent 0.12.8 → 0.12.11

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 { piAuthStore } from "./piAuthStore.ts";
 import {
   sealedEnabled,
   sealedProviderFor,
@@ -484,7 +485,7 @@ export const privateerOAuthProvider = {
 };
 
 // Confidential-compute prefixes in the account catalog: every model the server serves
-// out of a TEE. `near/` is the one we can attest end to end from here (the server
+// out of a TEE. `near/` is the one we can attest in full from here (the server
 // proxies a nonce'd quote); `tinfoil/` and `phala/` are equally real enclaves whose
 // attestation we cannot bind to THIS connection through the proxy — see accountPosture.
 const TEE_PREFIXES = ["near/", "tinfoil/", "phala/"];
@@ -780,16 +781,11 @@ async function accountCredential(): Promise<AccountCredential> {
   return slot.inFlight;
 }
 
-// `ctx` is Pi's ExtensionContext; the auth store hangs off its model registry (the same
-// path privateer-brand uses to DROP the credential on sign-out).
+// `ctx` is Pi's ExtensionContext. It used to carry the auth store too
+// (ctx.modelRegistry.authStorage) — pi 0.84 removed it, and the surviving
+// ModelRegistry facade has no credential surface at all, so the store is resolved
+// from piAuthStore() instead and `ctx` is now only ever consulted for UI.
 type SeedContext = {
-  modelRegistry?: {
-    authStorage?: {
-      set?: (provider: string, cred: unknown) => void;
-      get?: (provider: string) => unknown;
-      remove?: (provider: string) => void;
-    };
-  };
   model?: { provider?: string; id?: string };
   hasUI?: boolean;
   ui?: { notify?: (message: string, level: string) => void };
@@ -809,10 +805,12 @@ export async function armAccountCredential(
   opts: { notify?: boolean } = {},
 ): Promise<boolean> {
   if (!hasCredentials()) return false;
-  const store = (ctx as SeedContext)?.modelRegistry?.authStorage;
-  if (typeof store?.set !== "function") return false;
   try {
-    store.set("privateer", { type: "oauth", ...(await accountCredential()) });
+    // `modify` is the store's only write path: it hands us the current entry and
+    // takes the replacement back. We ignore the current one — a freshly minted
+    // child credential always supersedes whatever is on disk.
+    const cred = await accountCredential();
+    await (await piAuthStore()).modify("privateer", async () => ({ type: "oauth", ...cred }));
     return true;
   } catch (e) {
     // The account channel is NOT armed: a dead machine login (401 → credentials cleared
@@ -831,6 +829,17 @@ export async function armAccountCredential(
   }
 }
 
+// Write an already-acquired account credential into Pi's auth store.
+//
+// The entrypoints that mint their own child credential (chat, acp, harbor, the live
+// task session) used to poke `services.authStorage.set(...)` directly. pi 0.84 removed
+// that property and made the store's only write path an async `modify`, so the poke
+// lives here now — one place that knows the shape, next to the ownership rules that
+// govern the same entry.
+export async function persistAccountCredential(creds: AccountCredential): Promise<void> {
+  await (await piAuthStore()).modify("privateer", async () => ({ type: "oauth", ...creds }));
+}
+
 // Drop Pi's PERSISTED account credential (the `privateer` entry in auth.json) — but
 // ONLY when it's the one this process minted. Every exit path pairs a session revoke
 // with this drop (the contract in auth/privateer.ts): Pi reuses the persisted
@@ -849,31 +858,32 @@ export async function armAccountCredential(
 // machine's whole token family — every terminal's session included. Those callers have
 // also already wiped the local credentials, so the ownership memo is gone by then and an
 // ownership-checked drop would refuse and strand a dead entry on disk.
-export function dropPersistedAccountCredential(ctx: unknown, opts: { force?: boolean } = {}): boolean {
-  const store = (ctx as SeedContext)?.modelRegistry?.authStorage;
+export async function dropPersistedAccountCredential(
+  opts: { force?: boolean } = {},
+): Promise<boolean> {
+  const store = await piAuthStore();
   const mine = ownedAccountCredential()?.access;
   // Every caller revokes this process's session immediately before calling us, so drop
   // the memo whatever happens to the entry on disk — otherwise a later arm() in this
   // process (a harbor run's session_start, say) could re-persist the revoked token.
   armSlot().cred = undefined;
-  if (typeof store?.remove !== "function") return false;
   try {
-    if (opts.force) {
-      /* whole family revoked — the entry is dead for every terminal, drop it */
-    } else if (typeof store.get === "function") {
-      const persisted = store.get("privateer") as { access?: unknown } | undefined;
+    if (!opts.force) {
+      // Not force: read the entry back and only drop it if it is ours. This read is
+      // the whole safety property — it is what sees the entry a CONCURRENT terminal
+      // wrote, and auth.json is re-read from disk when its revision changes, so this
+      // observes other processes rather than a stale in-process copy.
+      const persisted = (await store.read("privateer")) as { access?: unknown } | undefined;
       if (!persisted) return false; // nothing persisted — nothing to drop
       // Some other terminal's session. Leave it: it's the key that terminal is using.
       if (typeof persisted.access === "string" && persisted.access !== mine) return false;
-    } else if (!mine) {
-      // Older Pi with no readable auth store AND we never minted anything — we have no
-      // basis to claim the entry, so leave it alone rather than break another terminal.
-      return false;
     }
-    store.remove("privateer");
+    // force: the whole token family is revoked, so the entry is dead for every
+    // terminal and ownership is irrelevant.
+    await store.delete("privateer");
     return true;
   } catch {
-    return false; // older Pi shape / unwritable store — the server TTL is the fallback
+    return false; // unwritable store — the server TTL is the fallback
   }
 }
 
@@ -889,12 +899,10 @@ export function dropPersistedAccountCredential(ctx: unknown, opts: { force?: boo
 // refresh path (refreshToken), and pre-empting it would mint a second session row.
 export async function ensureAccountArmed(ctx: unknown): Promise<void> {
   if (!hasCredentials()) return;
-  const store = (ctx as SeedContext)?.modelRegistry?.authStorage;
-  if (typeof store?.get !== "function") return; // can't tell — leave it to session_start
   try {
-    if (store.get("privateer")) return;
+    if (await (await piAuthStore()).read("privateer")) return;
   } catch {
-    return;
+    return; // can't tell — leave it to the next session_start
   }
   await armAccountCredential(ctx, { notify: false });
 }

package/src/providers/defaultModel.ts

@@ -71,7 +71,7 @@ export const ACCOUNT_DEFAULT_MODEL_ID = TINFOIL_MODEL_ID;
 export const ACCOUNT_DEFAULT_SPEC = `privateer/${ACCOUNT_DEFAULT_MODEL_ID}`;
 
 // The account channel's NEAR confidential-compute model — no longer the default, but
-// still the one account model we can attest end-to-end through the server proxy, so
+// still the one account model we can attest in full through the server proxy, so
 // it stays first in the seed catalog after the default. See providers/account.ts.
 export const ACCOUNT_NEAR_MODEL_ID = "near/zai-org/GLM-5.1-FP8";
 

package/src/providers/piAuthStore.ts

@@ -0,0 +1,129 @@
+// Access to Pi's credential store and model registry after the 0.84 refactor.
+//
+// pi-coding-agent 0.84 folded credential storage and the model registry into a single
+// `ModelRuntime` and removed both from `AgentSessionServices`. Two things that used to
+// hang off `services` no longer do:
+//
+//   services.authStorage   -> gone; the runtime owns a private CredentialStore
+//   services.modelRegistry -> gone; superseded by services.modelRuntime
+//
+// This module is the single place that knows about that change, so the account channel
+// and the entrypoints don't each grow their own workaround.
+//
+// ⚠️ NOTHING HERE MAY STATICALLY IMPORT PI. This module is pulled in by
+// providers/account.ts, which is itself statically imported by extensions and by the
+// harbor — and whose static graph is deliberately Pi-free, because Pi must not load
+// before boot.ts has installed the env and the dispatcher (the same contract session.ts
+// documents). So the one place a Pi class is genuinely needed loads it dynamically, and
+// everything else is duck-typed off objects Pi already handed us.
+
+import { join } from "node:path";
+
+import { agentDir as defaultAgentDir } from "../config/paths.ts";
+
+/** The agent dir Pi is actually using — boot pins PI_CODING_AGENT_DIR to ours. */
+function resolveAgentDir(agentDir?: string): string {
+  return agentDir ?? process.env.PI_CODING_AGENT_DIR ?? defaultAgentDir();
+}
+
+/** The subset of Pi's CredentialStore the account channel uses. All async in 0.84. */
+export type PiCredentialStore = {
+  read(providerId: string): Promise<unknown>;
+  modify(providerId: string, fn: (current: unknown) => Promise<unknown>): Promise<unknown>;
+  delete(providerId: string): Promise<void>;
+};
+
+let cached: { path: string; store: Promise<PiCredentialStore> } | undefined;
+let override: Promise<PiCredentialStore> | undefined;
+
+/**
+ * Pi's credential store for auth.json — the same file, format and class the ModelRuntime
+ * uses. `AuthStorage` IS that class: model-runtime.js defaults to
+ * `DefaultAuthStorage.create(authPath)`, where DefaultAuthStorage is this exact export,
+ * and it already implements the public CredentialStore interface. 0.84 merely stopped
+ * re-exporting it, so our pi patch puts the export back — which keeps us on Pi's own
+ * store and file format instead of reimplementing either.
+ *
+ * Why ModelRuntime isn't enough: it exposes login/logout/listCredentials but no way to
+ * WRITE an OAuth credential, and pi-ai exports only InMemoryCredentialStore. The account
+ * channel must write one, because Pi persists an OAuth credential only for a login IT
+ * drove — never for our device-code flow.
+ *
+ * Holding a second instance over the same path is safe and is not a shortcut: auth.json
+ * is machine-global and shared by every terminal on the box, so the store is already
+ * built for concurrent access (per-path shared read state, a file-revision check on
+ * read, serialized `modify` writes). A second instance in this process is just one more
+ * reader/writer, exactly like another terminal — which is the case the ownership check
+ * in account.ts exists to handle.
+ */
+export function piAuthStore(agentDir?: string): Promise<PiCredentialStore> {
+  if (override) return override;
+  const path = join(resolveAgentDir(agentDir), "auth.json");
+  if (cached?.path !== path) {
+    cached = {
+      path,
+      store: import("@earendil-works/pi-coding-agent").then((pi) => {
+        // `AuthStorage` reaches the index through OUR pi patch (0.84 stopped exporting
+        // it), and patches are best-effort — `bin/apply-patches.mjs` degrades to stock
+        // pi when it cannot write to node_modules, the `sudo npm i -g` case. This is
+        // the one place left that genuinely needs the patched export: only pi's own
+        // class knows auth.json's locking, revision checks and file format, and pi's
+        // package exports map blocks the deep path it still lives at. So say what
+        // happened. Unpatched, the alternative is `undefined.create is not a function`
+        // at whatever moment the account channel first writes a credential.
+        const ctor = (pi as { AuthStorage?: { create(p: string): PiCredentialStore } }).AuthStorage;
+        if (!ctor) {
+          throw new Error(
+            "pi's AuthStorage export is missing — the privateer patch for " +
+              "@earendil-works/pi-coding-agent has not been applied to this install. " +
+              "Run `privateer` once with write access to node_modules (a root-owned " +
+              "global install needs sudo), or reinstall with a release bundle.",
+          );
+        }
+        return ctor.create(path);
+      }),
+    };
+  }
+  return cached.store;
+}
+
+/**
+ * Substitute the store. Tests only.
+ *
+ * The account channel's ownership rules used to be testable by handing the functions a
+ * ctx with a fake store on it; the store is resolved internally now, so this is the seam
+ * that replaces it. Pass undefined to restore the real one.
+ */
+export function setPiAuthStoreForTests(store: PiCredentialStore | undefined): void {
+  override = store ? Promise.resolve(store) : undefined;
+  cached = undefined;
+}
+
+/** The registry-shaped reads our callers make. Matches the old ModelRegistry facade. */
+export type RegistryLike = {
+  find(provider: string, modelId: string): unknown;
+  getAll(): readonly unknown[];
+  getAvailable(): Promise<readonly unknown[]>;
+};
+
+/**
+ * A registry-shaped view of a session's services.
+ *
+ * 0.84 kept `ModelRegistry` as a synchronous facade over `ModelRuntime` (that is how
+ * extensions still see it) but stopped putting one on `services`. We deliberately do NOT
+ * construct one: importing the class would drag Pi into this module's static graph. The
+ * runtime is a live object Pi already gave us, so three delegating methods reproduce
+ * exactly the surface our callers used — `find` is `getModel` renamed.
+ */
+export function modelRegistryOf(services: { modelRuntime?: unknown } | null | undefined): RegistryLike {
+  const runtime = services?.modelRuntime as {
+    getModel(p: string, id: string): unknown;
+    getModels(): readonly unknown[];
+    getAvailable(): Promise<readonly unknown[]>;
+  } | undefined;
+  return {
+    find: (provider, modelId) => runtime?.getModel(provider, modelId),
+    getAll: () => runtime?.getModels() ?? [],
+    getAvailable: async () => (await runtime?.getAvailable()) ?? [],
+  };
+}

package/src/providers/sealedShim.ts

@@ -41,7 +41,7 @@ import { iterateSSE } from "./phala/sse.ts";
 export type SealedProvider = "tinfoil" | "phala";
 
 // Sealed mode is ON by default as of 2026-07-31, when the live checklist in
-// docs/tee-verified-tinfoil-ehbp.md passed end to end against the deployed relay:
+// docs/tee-verified-tinfoil-ehbp.md passed in full against the deployed relay:
 // both enclaves attest client-side (Tinfoil HPKE-key match; Phala report binding +
 // TDX quote), a sealed turn round-trips and streams incrementally, a bogus enclave is
 // refused rather than silently greened, and the server bills the turn.

package/src/remote/liveTaskSession.ts

@@ -20,7 +20,9 @@ import { agentVersion } from "../config/version.ts";
 import { createEngineEventAdapter } from "../bridge/engineAdapter.ts";
 import { isRemoteUnsafeTool, type GateController } from "../ext/permissionGate.ts";
 import { moatResourceOptions } from "../config/moat.ts";
-import { rememberAccountCredential, dropPersistedAccountCredential } from "../providers/account.ts";
+import { rememberAccountCredential, persistAccountCredential, dropPersistedAccountCredential } from "../providers/account.ts";
+// Pi-free static graph by design — see the header of piAuthStore.ts.
+import { modelRegistryOf } from "../providers/piAuthStore.ts";
 import { RelayClient, type TaskSpec } from "./relayClient.ts";
 import { RemoteBridge } from "./remoteBridge.ts";
 import { AttachmentStore, type StoredAttachment } from "../util/attachmentStore.ts";
@@ -70,7 +72,6 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
   let initialPromptSent = false;
   let stopped = false;
   let spawnedAccount = false;
-  let servicesRef: { authStorage?: { remove?: (p: string) => void; get?: (p: string) => unknown } } | null = null;
 
   let attachTimer: ReturnType<typeof setTimeout> | undefined;
   let lifeTimer: ReturnType<typeof setTimeout> | undefined;
@@ -117,7 +118,7 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
       try { await revokeAccountSession(); } catch { /* server TTL is the fallback */ }
       // Ownership-checked: auth.json is shared machine-wide, so a live task's teardown
       // must not delete an interactive terminal's entry (see providers/account.ts).
-      try { dropPersistedAccountCredential({ modelRegistry: { authStorage: servicesRef?.authStorage } }); } catch { /* nothing persisted */ }
+      try { await dropPersistedAccountCredential(); } catch { /* nothing persisted */ }
     }
     deps.onClosed(termId);
     deps.log(`live task ${termId} closed`);
@@ -218,13 +219,12 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
       })) as any),
     },
   });
-  servicesRef = services as any;
 
   const { provider, modelId } = deps.parseSpec(modelSpec);
   if (provider === "privateer") {
     try {
       const creds = await spawnAccountCredentials();
-      (services.authStorage as any).set("privateer", { type: "oauth", ...creds });
+      await persistAccountCredential(creds);
       rememberAccountCredential(creds); // claim it, so stop() drops OUR entry only
       spawnedAccount = true;
     } catch (e) {
@@ -236,7 +236,7 @@ export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps):
   // just spawned + closes the relay), or a throw would leak an orphaned account "device"
   // until its token TTL. Everything post-account-spawn runs under one guard.
   try {
-  const model = (services.modelRegistry as any).find(provider, modelId);
+  const model = (modelRegistryOf(services) as any).find(provider, modelId);
   if (!model) {
     throw new Error(`model ${provider}/${modelId} not found`);
   }

package/src/routines/delivery.ts

@@ -1,6 +1,7 @@
 import type { Routine } from "./schema.ts";
 import { webhookName } from "./schema.ts";
 import { writeRoutineOutput, addNotice } from "./store.ts";
+import type { StagedMedia } from "./resultMedia.ts";
 
 // A relay pusher, injected by the harbor. Given the finished result it either
 // forwards it to an attached controller immediately ("live") or persists it to the
@@ -14,7 +15,14 @@ export type RelayPusher = (routine: Routine, content: string) => "live" | "queue
 // "queued" when it was persisted for a later flush — either way the result is
 // durably accounted for. `status` is carried so the sealed envelope can render
 // ok/error without re-parsing the markdown body.
-export type CloudPusher = (routine: Routine, content: string, status: "ok" | "error") => Promise<"sent" | "queued">;
+// `media` is what the run staged for the Inbox (resultMedia.ts) — sealed and stored
+// alongside the message by the pusher, or named in the body when it can't travel.
+export type CloudPusher = (
+  routine: Routine,
+  content: string,
+  status: "ok" | "error",
+  media: StagedMedia[],
+) => Promise<"sent" | "queued">;
 
 // A named webhook endpoint from config `webhooks`.
 export interface WebhookTarget {
@@ -28,6 +36,11 @@ export interface DeliveryContext {
   // (e.g. not signed in) → the `cloud` channel falls back to a notice so the result
   // isn't silently lost.
   pushCloud?: CloudPusher;
+  // Files the run staged for the app's Inbox. Only the `cloud` channel carries them:
+  // a webhook receiver has no key to open a sealed blob, and the file channel already
+  // has the originals on disk — so for every other channel the body's own prose is
+  // what tells the reader an attachment exists.
+  media?: StagedMedia[];
   // Named endpoints for "webhook:<name>" delivery entries; results POST here.
   webhooks?: Record<string, WebhookTarget>;
   // Scrubs secrets from anything leaving the machine. Webhook bodies always pass
@@ -144,7 +157,7 @@ export async function deliver(
   // yet) and flushes later — both are durable. Only when no pusher is wired at all,
   // and nothing else keeps a durable record, do we fall back to a notice.
   if (wants.has("cloud")) {
-    const sent = ctx.pushCloud ? await ctx.pushCloud(routine, content, status) : undefined;
+    const sent = ctx.pushCloud ? await ctx.pushCloud(routine, content, status, ctx.media ?? []) : undefined;
     if (sent === "sent") delivered.push("cloud");
     else if (sent === "queued") delivered.push("cloud(queued)");
     else if (!wants.has("file") && !wants.has("notice") && !wants.has("relay")) {

package/src/routines/resultBrief.ts

@@ -0,0 +1,60 @@
+// The delivery brief — what an unattended run is told about where its answer lands.
+//
+// A routine's prompt is written by the user ("summarise my open PRs at 7am"). It says
+// what to do and nothing about the surface, so the model wrote for a terminal: paths,
+// scrollback references, "see above", a plan to run something else next. None of that
+// survives the trip. The result is sealed to the account outbox and read hours later
+// in the app's Inbox, by someone who was not there and cannot answer back.
+//
+// So we prepend this. It states the surface (markdown, in an app), what the surface can
+// render beyond prose (ONE fenced artifact, which the app turns into a Cargo card with
+// Preview / Download / Save), and how to hand over media (the attach_to_result tool —
+// only mentioned when it is actually registered, because a brief that advertises a tool
+// the run doesn't have is how a model ends up describing an attachment nobody gets).
+//
+// Deliberately short. It is prepended to every unattended turn, so every line costs
+// tokens on every run; anything that isn't load-bearing for the delivery is the user's
+// prompt's business, not ours.
+
+export interface BriefOptions {
+  /** The result reaches the app's Inbox (cloud delivery). False → no brief at all. */
+  inbox: boolean;
+  /** attach_to_result is registered for this run. */
+  canAttach: boolean;
+}
+
+const HEADER = "[Privateer delivery brief — how this answer will be read]";
+
+/**
+ * The brief for one run, or "" when it wouldn't help. Callers prepend it with
+ * `withBrief` rather than concatenating by hand.
+ */
+export function deliveryBrief(opts: BriefOptions): string {
+  if (!opts.inbox) return "";
+  const lines = [
+    HEADER,
+    "Nobody is at this terminal. Your final message is delivered to the user's Privateer Inbox in the app and read later, on a phone or in a browser, with no access to this machine.",
+    "",
+    "- Write the answer so it stands alone. No scrollback, no \"see above\", no next step you meant to run.",
+    "- It renders as Markdown: headings, lists, tables, links and code all work.",
+    "- A local file path is not something the user can open. Don't offer one as the way to see something.",
+    "- If the answer is better as something they can keep, open or share, end your message with ONE fenced artifact and describe it in prose above:",
+    "    ```html … ```               a complete standalone HTML document — page, slide deck or game. Inline all CSS and JS; it is opened with no network and no sibling files.",
+    "    ```md kind=pdf … ```        a document (also kind=docx, kind=md).",
+    "    ```csv kind=sheet … ```     a spreadsheet.",
+    "  The app turns that fence into an artifact card with Preview, Download and Save — so don't also paste the same content as prose.",
+  ];
+  if (opts.canAttach) {
+    lines.push(
+      "- To send an image, video, audio clip or document, call attach_to_result with its path. That is the only way bytes reach the user; base64 pasted into the answer is not rendered.",
+    );
+  }
+  return lines.join("\n");
+}
+
+/** Prepend the brief to a user prompt, fenced off so the two don't read as one instruction. */
+export function withBrief(prompt: string, opts: BriefOptions): string {
+  const brief = deliveryBrief(opts);
+  if (!brief) return prompt;
+  return `${brief}\n\n---\n\n${prompt}`;
+}

package/src/routines/resultMedia.ts

@@ -0,0 +1,131 @@
+// Media staged for ONE unattended result — the stills, clips and files an agent
+// wants the user to actually see in their Privateer Inbox, rather than describe.
+//
+// WHY THIS EXISTS. A routine can already generate media (src/tools/media.ts) and
+// compose it (videoCompose.ts), but until now the run could only ever say where it
+// put the file. Nobody is at that machine — that is the whole premise of an
+// unattended run — so "saved to ~/.privateer/media/still-3.png" is a result the
+// user cannot open from the surface they were handed. `send_file_to_client` doesn't
+// close that gap either: it needs a controller attached RIGHT NOW, which is exactly
+// what a 7am routine doesn't have.
+//
+// So the run stages files here (the attach_to_result tool — src/tools/attachResult.ts),
+// and delivery seals them to the account outbox alongside the message: small ones
+// inline in the envelope, larger ones as sealed blobs the app collects on the same
+// sync (src/outbox/cloudOutbox.ts). Store-and-forward, E2EE, no controller needed.
+//
+// The ceilings below are the honest part. They are checked at STAGE time, not at
+// delivery time, so the model learns "that clip is too big" while it can still do
+// something about it (re-encode, trim, attach a frame instead) rather than after the
+// turn has ended. A refusal is never traded against something already staged.
+
+import { existsSync, statSync } from "node:fs";
+import { basename, isAbsolute, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { mediaTypeForPath } from "../tools/sendFile.ts";
+
+/** Most files one result may carry. */
+export const MAX_ATTACHMENTS = 6;
+/** Largest single file, matching the server's per-blob ceiling. */
+export const MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024;
+/** Largest total per result — bounds one run's share of the account's mailbox. */
+export const MAX_TOTAL_ATTACHMENT_BYTES = 24 * 1024 * 1024;
+
+/** How the app should present an attachment. Derived from the media type. */
+export type MediaClass = "image" | "video" | "audio" | "file";
+
+export interface StagedMedia {
+  /** Per-result id; ties the envelope's metadata to its bytes. */
+  id: string;
+  /** Absolute path on THIS machine. Never leaves it — see the note in delivery. */
+  path: string;
+  name: string;
+  mediaType: string;
+  cls: MediaClass;
+  size: number;
+  caption?: string;
+}
+
+export function classifyMedia(mediaType: string): MediaClass {
+  if (mediaType.startsWith("image/")) return "image";
+  if (mediaType.startsWith("video/")) return "video";
+  if (mediaType.startsWith("audio/")) return "audio";
+  return "file";
+}
+
+export type StageResult =
+  | { ok: true; item: StagedMedia }
+  | { ok: false; reason: string };
+
+/**
+ * One run's staging area. Created per routine/task run and thrown away with it, so
+ * a file staged by yesterday's run can never ride along with today's.
+ */
+export class ResultMedia {
+  private items: StagedMedia[] = [];
+
+  /** Bytes staged so far. */
+  totalBytes(): number {
+    return this.items.reduce((n, m) => n + m.size, 0);
+  }
+
+  list(): StagedMedia[] {
+    return [...this.items];
+  }
+
+  clear(): void {
+    this.items = [];
+  }
+
+  /**
+   * Stage one file. `cwd` resolves a relative path the same way the run's other
+   * file tools do. Re-staging the same path REPLACES the earlier entry (a model
+   * that regenerates an image and attaches it again means the new one), which also
+   * stops a retry loop from eating the count cap.
+   */
+  stage(path: string, cwd: string, caption?: string): StageResult {
+    const abs = isAbsolute(path) ? path : resolve(cwd, path);
+    if (!existsSync(abs)) return { ok: false, reason: `File not found: ${path}` };
+    const stat = statSync(abs);
+    if (stat.isDirectory()) return { ok: false, reason: `${path} is a directory — attach a single file.` };
+    if (stat.size === 0) return { ok: false, reason: `${path} is empty — nothing to attach.` };
+    if (stat.size > MAX_ATTACHMENT_BYTES) {
+      return {
+        ok: false,
+        reason: `${basename(abs)} is ${mb(stat.size)} MB; the inbox caps one attachment at ${mb(MAX_ATTACHMENT_BYTES)} MB. Re-encode it smaller, trim it, or attach a single frame instead.`,
+      };
+    }
+
+    const existing = this.items.findIndex((m) => m.path === abs);
+    const others = existing >= 0 ? this.items.filter((_, i) => i !== existing) : this.items;
+    if (others.length >= MAX_ATTACHMENTS) {
+      return { ok: false, reason: `Already carrying ${MAX_ATTACHMENTS} attachments — that is the limit for one result.` };
+    }
+    const otherBytes = others.reduce((n, m) => n + m.size, 0);
+    if (otherBytes + stat.size > MAX_TOTAL_ATTACHMENT_BYTES) {
+      return {
+        ok: false,
+        reason: `That would put this result over the ${mb(MAX_TOTAL_ATTACHMENT_BYTES)} MB attachment budget (${mb(otherBytes)} MB already staged).`,
+      };
+    }
+
+    const mediaType = mediaTypeForPath(abs);
+    const item: StagedMedia = {
+      id: randomUUID(),
+      path: abs,
+      name: basename(abs),
+      mediaType,
+      cls: classifyMedia(mediaType),
+      size: stat.size,
+      // A caption is shown under the attachment in the app, so it is worth having
+      // and worth bounding — this is model-authored text heading for a UI.
+      ...(caption?.trim() ? { caption: caption.trim().slice(0, 200) } : {}),
+    };
+    this.items = [...others, item];
+    return { ok: true, item };
+  }
+}
+
+function mb(bytes: number): string {
+  return (bytes / 1048576).toFixed(1).replace(/\.0$/, "");
+}

package/src/routines/schema.ts

@@ -2,7 +2,7 @@ import { randomBytes } from "node:crypto";
 import { z } from "zod";
 
 // Where a routine's result is delivered after it runs. `file`/`relay`/`notice` stay
-// inside the user's trust boundary. `cloud` stores an END-TO-END-ENCRYPTED copy in
+// inside the user's trust boundary. `cloud` stores an ENCRYPTED copy in
 // the account's server outbox for the app to catch up on when it next opens (the
 // server only ever sees ciphertext — it can't read results — but does learn that a
 // result exists, plus its time and rough size). `email` and `webhook:<name>` cross

package/src/routines/store.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { globalDir } from "../config/paths.ts";
 import { Routine, RoutineFile } from "./schema.ts";
+import type { StagedMedia } from "./resultMedia.ts";
 
 // routines.json lives alongside config.json in the global dir. It can carry the
 // prompt text and (for email delivery) recipient hints, so it is written owner-only
@@ -223,6 +224,12 @@ export interface PendingCloud {
   // workflow run. Preserved so the flush re-seals with the right `kind` and the app
   // labels it correctly in the inbox.
   kind?: OutboxKind;
+  // Attachments the run staged for the Inbox (resultMedia.ts) — RECORDS, not bytes.
+  // The files are still on this machine, so a flush hours later re-reads them from
+  // these paths; one that has since been deleted is named in the delivered body
+  // instead. Copying megabytes into this queue would be the same content twice on
+  // the one box that already has it.
+  media?: StagedMedia[];
 }
 
 function pendingCloudPath(): string {