npm - privateer-agent - Versions diffs - 0.12.13 → 0.12.14 - Mend

privateer-agent 0.12.13 → 0.12.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/bin/privateer-subagent.mjs +10 -2
package/extensions/privateer-gate.ts +7 -0
package/extensions/privateer-media.ts +17 -4
package/extensions/privateer-privacy.ts +13 -33
package/extensions/privateer-tools.ts +8 -3
package/package.json +1 -1
package/patches/@earendil-works+pi-coding-agent+0.84.1.patch +102 -5
package/src/acp/run.ts +29 -2
package/src/channels/run.ts +9 -0
package/src/cli/chat.ts +47 -0
package/src/config/moat.ts +6 -26
package/src/config/moatManifest.ts +5 -0
package/src/config/privacyPolicy.ts +97 -0
package/src/engine/errors.ts +97 -1
package/src/ext/permissionGate.ts +6 -0
package/src/harbor/index.ts +65 -11
package/src/outbox/cloudOutbox.ts +72 -4
package/src/permissions/childSpend.ts +105 -0
package/src/permissions/classify.ts +61 -3
package/src/permissions/modeGate.ts +39 -0
package/src/providers/account.ts +8 -1
package/src/providers/phala/measurements.ts +170 -0
package/src/providers/phala/pin.ts +98 -0
package/src/providers/phalaSeal.ts +131 -9
package/src/providers/sealedShim.ts +6 -1
package/src/remote/liveTaskSession.ts +8 -1
package/src/remote/relayClient.ts +21 -0
package/src/remote/remoteBridge.ts +9 -0
package/src/routines/store.ts +11 -0
package/src/tools/media.ts +516 -11
package/src/tools/routineResult.ts +146 -0
package/src/tools/videoCompose.ts +825 -7

package/src/engine/errors.ts CHANGED Viewed

@@ -117,6 +117,99 @@ export function isAccountCapCode(code: string | null | undefined): boolean {
   return typeof code === "string" && CAP_CODE.test(code);
 }
+// ── Oversized / non-API error bodies ─────────────────────────────────────────
+//
+// An inference endpoint does not always answer as an API. Put a WAF, a proxy or a
+// captive portal in front of one and a rejected request comes back as an HTML page,
+// which the provider SDK folds whole into `error.message` — status first, body after.
+//
+// The incident this exists for: the account channel's edge WAF answered a turn with a
+// 403 block page carrying three inline base64 web fonts, so `errorMessage` was 221 KB.
+// Pi printed it into the terminal in full, appended it to the session file on every
+// attempt (a 1.8 MB session), and ran its transient-error regex over it — and a
+// megabyte of base64 reliably contains "429", "500", "502", so a permanent 403 looked
+// retryable and burned the whole retry budget before the user saw anything.
+//
+// Both halves are fixed where Pi reads the message (see the patch in
+// patches/@earendil-works+pi-coding-agent+*.patch, which mirrors these two helpers):
+// squeeze the page down to the line a person can act on, and let the STATUS decide
+// retryability rather than a substring of the body.
+/** Hard cap on an error message we display, persist, or classify. */
+export const MAX_ERROR_CHARS = 2_000;
+/** How much of an HTML page's visible text is worth keeping. */
+const MAX_PAGE_TEXT_CHARS = 600;
+const HTML_DOC = /<!doctype html|<html[\s>]/i;
+/** Tags whose contents are never prose: markup, styling, or a logo. */
+const NON_PROSE = /<(script|style|svg|head|noscript)\b[\s\S]*?<\/\1\s*>/gi;
+const ENTITIES: Record<string, string> = {
+  amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", "#39": "'", "#x27": "'",
+};
+function plainText(html: string): string {
+  return html
+    .replace(/<[^>]*>/g, " ")
+    .replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (m, code: string) => {
+      const key = code.toLowerCase();
+      if (ENTITIES[key] !== undefined) return ENTITIES[key];
+      if (key.startsWith("#x")) return String.fromCodePoint(parseInt(key.slice(2), 16) || 0) || m;
+      if (key.startsWith("#")) return String.fromCodePoint(parseInt(key.slice(1), 10) || 0) || m;
+      return m;
+    })
+    .replace(/\s+/g, " ")
+    .trim();
+}
+/**
+ * Reduce a provider error message to something worth showing, storing and classifying.
+ *
+ * An HTML page collapses to its status, its <title> and its visible text — which is
+ * where a WAF puts the one detail the user needs to report ("Request ID: …"). Anything
+ * else over the cap is truncated. Text already short and non-HTML is returned unchanged,
+ * so ordinary provider errors pass through untouched.
+ */
+export function compactProviderError(raw: string): string {
+  const text = typeof raw === "string" ? raw : String(raw ?? "");
+  if (!HTML_DOC.test(text)) {
+    if (text.length <= MAX_ERROR_CHARS) return text;
+    return `${text.slice(0, MAX_ERROR_CHARS)}… [dropped ${text.length - MAX_ERROR_CHARS} chars]`;
+  }
+  const status = /^\s*(\d{3})\b/.exec(text)?.[1];
+  const title = plainText(/<title[^>]*>([\s\S]*?)<\/title>/i.exec(text)?.[1] ?? "");
+  const body = plainText(text.replace(NON_PROSE, " "));
+  const visible = [title, body].filter(Boolean).join(" — ").slice(0, MAX_PAGE_TEXT_CHARS);
+  return (
+    `${status ?? "HTTP error"} — an HTML page, not an API response (something in front of ` +
+    `the provider answered: a WAF, a proxy, or a captive portal): ` +
+    `${visible || "(no readable text)"} [dropped ${text.length} chars of HTML]`
+  );
+}
+// Client-error statuses that CAN clear on their own: a timeout, a lock conflict, an
+// early-data replay, a throttle. Every other 4xx is the request itself being wrong.
+const TRANSIENT_CLIENT_STATUS = new Set([408, 409, 425, 429]);
+/**
+ * True when the message opens with an HTTP status that retrying cannot clear.
+ *
+ * Both provider paths put the status first — the OpenAI-shaped SDK builds
+ * `"403 <body>"`, pi-messages builds `"403 Forbidden: <body>"` — so the status is a
+ * fact we can read, where a substring of the body is only a guess. 5xx and messages
+ * with no leading status are left to the caller's own classifier.
+ */
+export function isHardHttpFailure(text: string | null | undefined): boolean {
+  const m = /^\s*(\d{3})\b/.exec(typeof text === "string" ? text : "");
+  if (!m) return false;
+  const status = Number(m[1]);
+  return status >= 400 && status < 500 && !TRANSIENT_CLIENT_STATUS.has(status);
+}
 function rawMessage(err: unknown): string {
   if (err instanceof Error) return err.message;
   if (typeof err === "string") return err;
@@ -243,5 +336,8 @@ export function describeError(err: unknown): DescribedError {
     });
   }
-  return out({ message: text });
+  // Unrecognized: show the provider's own words rather than swallow them — but an
+  // unrecognized error is exactly where a WAF block page or a megabyte of markup
+  // arrives, so it goes through the compactor first.
+  return out({ message: compactProviderError(text) });
 }

package/src/ext/permissionGate.ts CHANGED Viewed

@@ -53,6 +53,11 @@ export interface GateController {
   // launch flag (env PRIVATEER_NO_QUARTER); when true the gate auto-allows every
   // action with no prompt.
   getSkipAllPermissions?(): boolean;
+  // Billing tools the operator authorized before this run started, so an unattended
+  // session can spend what it was told it may spend instead of denying every media
+  // call for want of a human. Lifts `alwaysAsk` and nothing else — see
+  // ModeGate.isSpendPreauthorized for the guards.
+  isSpendPreauthorized?(req: PermissionRequest): boolean;
   // Block a tool outright while the turn is remote-driven (only consulted when
   // getRemote() is true). For tools whose own prompts render on the host terminal
   // rather than the relay — e.g. pi-subagents — so a driven turn can't wedge on an
@@ -144,6 +149,7 @@ export async function decideToolCall(
     getNoQuarter: ctrl.getNoQuarter,
     getAutoApprove: ctrl.getAutoApprove,
     getSkipAllPermissions: ctrl.getSkipAllPermissions,
+    isSpendPreauthorized: ctrl.isSpendPreauthorized,
   });
   let decision: "allow" | "deny";

package/src/harbor/index.ts CHANGED Viewed

@@ -60,7 +60,7 @@ import { deliver, type RelayPusher, type CloudPusher } from "../routines/deliver
 import { ResultMedia, type StagedMedia } from "../routines/resultMedia.ts";
 import { withBrief } from "../routines/resultBrief.ts";
 import { ATTACH_RESULT_TOOL } from "../tools/attachResult.ts";
-import { postOutbox as sealToOutbox } from "../outbox/cloudOutbox.ts";
+import { postOutbox as sealToOutbox, type OutboxSource } from "../outbox/cloudOutbox.ts";
 import { redactText, collectSecrets } from "../util/redact.ts";
 import { startIpcServer, sendToHarbor, describeRelay, formatDuration, HarborAlreadyRunningError, type IpcRequest, type IpcResponse, type RelayStatus } from "./ipc.ts";
 import { serializeBuild } from "./buildLock.ts";
@@ -68,6 +68,8 @@ import { isHosted, publishRelayPub, webEnabled, mediaEnabled } from "../config/h
 import { WEB_TOOL_NAMES } from "../tools/web.ts";
 import { MEDIA_TOOL_NAMES } from "../tools/media.ts";
 import { COMPOSE_TOOL_NAMES } from "../tools/videoCompose.ts";
+import { BILLED_MEDIA_TOOLS } from "../permissions/classify.ts";
+import { grantChildSpend } from "../permissions/childSpend.ts";
 // The safe, read-only toolset for unattended runs — Pi builtins with no
 // write/edit/bash, so a routine firing with nobody watching can't mutate the
@@ -130,6 +132,11 @@ const GATE_TIMEOUT_MS = 5 * 60_000;
 const WARM_TIMEOUT_MS = Number(process.env.PRIVATEER_MCP_WARM_MS) || 30_000;
 const WARM_POLL_MS = 250;
+// Distinguishes concurrent runs in the child-spend registry. A counter rather than a
+// timestamp: two runs starting in the same millisecond would share a key, and the second
+// to finish would release a grant the first still holds.
+let runSeq = 0;
 interface HarborConfig {
   defaultModel: string;
   webhooks?: Record<string, { url: string; secret?: string; headers?: Record<string, string> }>;
@@ -212,6 +219,22 @@ function formatWorkflowResult(name: string, result: { status: string; output: Re
   return `${head}${body}${reason}`.trimEnd() + "\n";
 }
+// What a routine ASKED for, sealed into the outbox envelope beside what it answered.
+//
+// The app can then act on a finished run — "now do X with this" — with the routine's
+// own standing instruction and working directory in hand, instead of guessing from a
+// summary. The routine never leaves this machine except inside the sealed blob (the
+// server holds ciphertext), and cloudOutbox clips every field.
+function routineSource(routine: Routine): OutboxSource {
+  return {
+    routineId: routine.id,
+    prompt: routine.prompt,
+    cwd: routine.cwd,
+    model: routine.model,
+    schedule: routine.cron ?? routine.at,
+  };
+}
 // Canonical control-envelope args for a task_submit / task_spawn signature. MUST match
 // the app's signer (client/services/accountSign.ts) byte-for-byte: the SAME key set with
 // undefined → null, so the recursive-key-sorted JSON both sides sign is identical. A
@@ -292,12 +315,13 @@ export class Harbor {
   private readonly pushCloud: CloudPusher = async (routine, content, status, media = []) => {
     const at = new Date().toISOString();
-    if (await this.postOutbox(routine.name, at, status, content, "routine", media)) return "sent";
+    const source = routineSource(routine);
+    if (await this.postOutbox(routine.name, at, status, content, "routine", media, source)) return "sent";
     // The queued copy keeps the attachment RECORDS, not the bytes: the files are
     // still on this disk, so a flush hours later re-reads them (and says so in the
     // body for any that have since gone). Buffering megabytes into a JSON queue
     // would be the same content twice, on a box that already has it.
-    addPendingCloud({ routine: routine.name, at, status, content, ...(media.length ? { media } : {}) });
+    addPendingCloud({ routine: routine.name, at, status, content, source, ...(media.length ? { media } : {}) });
     return "queued";
   };
@@ -594,8 +618,9 @@ export class Harbor {
     content: string,
     kind: OutboxKind = "routine",
     media: StagedMedia[] = [],
+    source?: OutboxSource,
   ): Promise<boolean> {
-    return sealToOutbox(name, at, status, content, kind, media);
+    return sealToOutbox(name, at, status, content, kind, media, source);
   }
   private async flushPendingCloud(): Promise<void> {
@@ -606,7 +631,7 @@ export class Harbor {
     for (const p of queue) {
       if (
         remaining.length === 0 &&
-        (await this.postOutbox(p.routine, p.at, p.status, p.content, p.kind ?? "routine", p.media ?? []))
+        (await this.postOutbox(p.routine, p.at, p.status, p.content, p.kind ?? "routine", p.media ?? [], p.source))
       ) continue;
       remaining.push(p);
     }
@@ -771,8 +796,14 @@ export class Harbor {
   // activation, so the build is serialized (serializeBuild) and the previous value is
   // restored. "__none__" is its sentinel for "register none": an unattended run with
   // no connector selectors gets no direct tools, whatever a shared mcp.json says.
-  private buildSessionServices(cwd: string, directTools: string[], media?: ResultMedia): Promise<any> {
+  private buildSessionServices(
+    cwd: string,
+    directTools: string[],
+    media?: ResultMedia,
+    spendGrant: readonly string[] = [],
+  ): Promise<any> {
     return serializeBuild(async () => {
+      const granted = new Set(spendGrant);
       const gate: GateController = {
         getMode: () => "bypass",
         setMode: () => {},
@@ -783,6 +814,14 @@ export class Harbor {
         async localAsk() {
           return "deny";
         },
+        // The billing media tools THIS run was granted. Without this the run below is a
+        // contradiction: a routine may name generate_video (naming it is the operator's
+        // decision — see MEDIA_GEN_TOOLS above), the tool registers, and then every call
+        // is denied, because `alwaysAsk` outranks bypass and localAsk has nobody to ask.
+        // Scoped to this session's gate rather than a process-wide switch, so two
+        // concurrent runs can hold different grants. The gate still refuses to let a
+        // grant cover a call that leaves cwd or reads a protected file.
+        isSpendPreauthorized: (req) => granted.has(req.tool),
       };
       // Every extension this session gets, in the one canonical order — including the MCP
       // adapter (Phase 5), the web/media capability shaping, and the filter that ignores
@@ -927,8 +966,14 @@ export class Harbor {
     // is going to the user's own mailbox, which `delivery: cloud` already chose.
     const allowedTools = spec.media ? [...resolved.tools, ATTACH_RESULT_TOOL] : resolved.tools;
     const { directToolsEnv, notes } = resolved;
+    // The billing tools this run may use: the ones its own allow-list names, and no
+    // others. Authorizes the run's own calls (the gate, below) and its subagents' —
+    // children are a separate process and read the grant from the environment, released
+    // in the finally so it can never outlive the run that holds it.
+    const spendGrant = allowedTools.filter((t) => BILLED_MEDIA_TOOLS.has(t));
+    const releaseChildSpend = grantChildSpend(`run:${++runSeq}`, spendGrant);
     try {
-      const services = await this.buildSessionServices(spec.cwd, directToolsEnv, spec.media);
+      const services = await this.buildSessionServices(spec.cwd, directToolsEnv, spec.media, spendGrant);
       const { provider, modelId } = parseSpec(spec.model);
       if (provider === "privateer") {
@@ -978,6 +1023,9 @@ export class Harbor {
         // and its entry must survive a harbor run's teardown (see providers/account.ts).
         try { await dropPersistedAccountCredential(); } catch { /* nothing persisted */ }
       }
+      // Drop this run's child grant. Unconditional and last: a grant left behind would
+      // authorize the NEXT run's subagents for tools that run never named.
+      releaseChildSpend();
     }
     return { out, status, error, notes };
   }
@@ -1014,10 +1062,13 @@ export class Harbor {
       const content = redactText(formatTaskResult(title, out, status, error, modelSpec, notes), collectSecrets(config.providers));
       const at = new Date().toISOString();
       const staged = media.list();
+      // What was asked, carried with what came back — a submitted task is followed up
+      // on exactly like a routine run (the app's Inbox is the only place either is read).
+      const source: OutboxSource = { prompt: spec.prompt, cwd, model: modelSpec };
       // Durable delivery: seal to the outbox. If we can't seal yet (no verified pubkey /
       // offline), queue it with kind:"task" so the flush re-seals it correctly later.
-      const sealed = await this.postOutbox(title, at, status, content, "task", staged);
-      if (!sealed) addPendingCloud({ routine: title, at, status, content, kind: "task", ...(staged.length ? { media: staged } : {}) });
+      const sealed = await this.postOutbox(title, at, status, content, "task", staged, source);
+      if (!sealed) addPendingCloud({ routine: title, at, status, content, kind: "task", source, ...(staged.length ? { media: staged } : {}) });
       // Live mirror if a controller is attached (the outbox copy is the source of truth).
       if (this.controllerAttached) this.relay?.sendTaskResult(title, content);
       log(`  task "${title}" ${status}; ${sealed ? "sealed to outbox" : "queued for outbox"}`);
@@ -1046,8 +1097,11 @@ export class Harbor {
             void (async () => {
               const at = new Date().toISOString();
               const body = redactText(content, collectSecrets(loadHarborConfig().providers));
-              if (!(await this.postOutbox(title, at, status, body, "task"))) {
-                addPendingCloud({ routine: title, at, status, content: body, kind: "task" });
+              // An empty-prompt spawn (a bare agent to drive) packs to no source at all
+              // — cloudOutbox drops it rather than shipping an empty object.
+              const source: OutboxSource = { prompt: spec.prompt, cwd: spec.cwd, model: spec.model };
+              if (!(await this.postOutbox(title, at, status, body, "task", [], source))) {
+                addPendingCloud({ routine: title, at, status, content: body, kind: "task", source });
               }
             })();
           },

package/src/outbox/cloudOutbox.ts CHANGED Viewed

@@ -68,6 +68,62 @@ export interface OutboxMedia {
   blobId?: string;
 }
+/**
+ * What the run was ASKED to do, carried beside what it answered.
+ *
+ * A result on its own is a dead end: the app can show it, read it aloud and file
+ * it, but "now book the top one" needs the standing instruction the run was given,
+ * and the directory it ran in, or the follow-up starts from a summary with no idea
+ * what produced it. That context is the routine — it lives on this machine and the
+ * app has never seen it — so it rides inside the SEALED envelope (the server holds
+ * ciphertext either way, exactly like `origin`).
+ *
+ * Every field is optional and clipped: this travels on every result, and a routine
+ * prompt can be arbitrarily long. Absent → the app falls back to the result body
+ * alone, which is what results from older CLIs carry.
+ */
+export interface OutboxSource {
+  /** The saved routine's id, when one produced this. Absent for ad-hoc tasks. */
+  routineId?: string;
+  /** The instruction the run was given (a routine's `prompt`, a task's spec). */
+  prompt?: string;
+  /** Where the run executed — a follow-up belongs in the same directory. */
+  cwd?: string;
+  /** The "provider:model" the run resolved to. */
+  model?: string;
+  /** The trigger verbatim: a cron expression, or a one-off ISO datetime. */
+  schedule?: string;
+}
+/** Clip bounds for `source`. The prompt is the only field that can be long. */
+export const MAX_SOURCE_PROMPT = 2_000;
+const SOURCE_FIELD_CAPS: Record<keyof OutboxSource, number> = {
+  routineId: 200,
+  prompt: MAX_SOURCE_PROMPT,
+  cwd: 500,
+  model: 200,
+  schedule: 100,
+};
+/**
+ * Normalize a source for the envelope: trim, clip, drop empties — and return
+ * undefined when nothing survives, so a workflow (or an empty-prompt live spawn)
+ * doesn't ship an empty object and bump the envelope version for nothing.
+ * Exported for the round-trip test.
+ */
+export function packSource(source?: OutboxSource): OutboxSource | undefined {
+  if (!source) return undefined;
+  const out: OutboxSource = {};
+  for (const [key, cap] of Object.entries(SOURCE_FIELD_CAPS) as [keyof OutboxSource, number][]) {
+    const raw = source[key];
+    if (typeof raw !== "string") continue;
+    const value = raw.trim();
+    if (!value) continue;
+    out[key] = value.length > cap ? value.slice(0, cap) + "…" : value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
 let outboxPub: Uint8Array | undefined;
 let originCache: { id: string; label: string } | undefined;
@@ -216,6 +272,9 @@ function undeliveredNote(names: string[]): string {
  * BEFORE the message, so a message that lands always references bytes that exist;
  * if the message then fails, the blobs are dropped again and the caller's queued
  * retry re-uploads from the same paths on disk.
+ *
+ * `source` is what the run was asked to do (see OutboxSource) — the context a
+ * follow-up needs, sealed alongside the answer.
  */
 export async function postOutbox(
   name: string,
@@ -224,20 +283,28 @@ export async function postOutbox(
   content: string,
   kind: OutboxKind = "routine",
   staged: StagedMedia[] = [],
+  source?: OutboxSource,
 ): Promise<boolean> {
   const pub = await ensureOutboxPub();
   if (!pub) return false;
   let body = content.length > MAX_CLOUD_PLAINTEXT ? content.slice(0, MAX_CLOUD_PLAINTEXT) + "\n…truncated" : content;
+  // Packed before the media budget is struck, because it spends the same envelope:
+  // attachments must not be sized against room the source has already taken.
+  const packedSource = packSource(source);
+  const sourceCost = packedSource ? JSON.stringify(packedSource).length : 0;
   const { media, blobIds, undelivered } = staged.length
-    ? await packMedia(pub, staged, MAX_ENVELOPE_PLAINTEXT - body.length - 2_000)
+    ? await packMedia(pub, staged, MAX_ENVELOPE_PLAINTEXT - body.length - sourceCost - 2_000)
     : { media: [] as OutboxMedia[], blobIds: [] as string[], undelivered: [] as string[] };
   body += undeliveredNote(undelivered);
-  // v2 adds `media`. Older apps ignore the field and still render the body, which is
-  // why the note above names undelivered files in prose rather than only in metadata.
+  // v2 adds `media`, v3 `source`. Both are additive: an older app ignores the field
+  // and still renders the body, which is why the note above names undelivered files
+  // in prose rather than only in metadata, and why a follow-up degrades to "the
+  // result text alone" rather than failing when `source` is missing.
   const envelope: Record<string, unknown> = {
-    v: media.length > 0 ? 2 : 1,
+    v: packedSource ? 3 : media.length > 0 ? 2 : 1,
     kind,
     name,
     status,
@@ -245,6 +312,7 @@ export async function postOutbox(
     content: body,
     origin: machineOrigin(),
     ...(media.length > 0 ? { media } : {}),
+    ...(packedSource ? { source: packedSource } : {}),
   };
   let sealed = sealJson(pub, envelope);

package/src/permissions/childSpend.ts ADDED Viewed

@@ -0,0 +1,105 @@
+// Handing an unattended run's SPEND AUTHORIZATION down to its subagent children.
+//
+// THE PROBLEM. A subagent is a fresh headless `pi` subprocess (pi-subagents, spawned
+// through bin/privateer-subagent.mjs), so it inherits nothing from its parent except the
+// environment and the `-e` moat the wrapper injects. Its gate therefore runs in bypass
+// with a fail-closed asker: ordinary writes go through, and every `alwaysAsk` tool — which
+// is every billing media tool — is denied, because there is no human on the other end of
+// a headless child's stdin. So "one subagent per shot" worked in a terminal, where the
+// child's ask relays up to the parent's TUI, and quietly could not work at all in the one
+// place it matters most: a routine that fires at 3am to build a film.
+//
+// WHAT IS HANDED DOWN, AND WHY THAT IS NOT A HOLE. Only the names of billing tools the
+// operator already authorized for this run, by naming them when they saved the routine —
+// media generation is deliberately absent from the harbor's default allow-list precisely
+// so that granting it is a decision someone made. The child gets no more than its parent
+// has, and the gate still refuses to let a pre-authorization cover a call that leaves the
+// working directory or touches a protected file (see ModeGate.isSpendPreauthorized).
+//
+// HONOURED ONLY IN A CHILD. `PRIVATEER_CHILD_SPEND` sitting in a developer's shell must
+// never turn a TERMINAL into a session that bills without asking, so the child side reads
+// it only when pi-subagents has marked this process as a child. A top-level session always
+// asks its human, however cheap the call.
+//
+// CONCURRENCY, AND WHY THE UNION WOULD BE WRONG. The harbor daemon can have two unattended
+// runs in flight at once (a scheduled routine and an app-submitted task), and children read
+// the environment when they spawn — one process-wide variable, two different grants. Taking
+// the union would let run B's child spend on a tool only run A was granted. So the exported
+// value is the INTERSECTION of every grant currently in flight: exact when one run holds a
+// grant (the overwhelmingly common case), and narrowing — fail-closed, with the gate's
+// ordinary denial message — when two overlap. A child denied that way reports it plainly;
+// a child over-granted would bill silently.
+import { isSubagentChild } from "../remote/subagentRelay.ts";
+/** The env var carrying a run's spend grant to its (possibly nested) children. */
+export const CHILD_SPEND_ENV = "PRIVATEER_CHILD_SPEND";
+// Grants currently in flight, keyed by the run that holds one. Module-level because the
+// value it projects is process-wide (the environment) — one registry per daemon.
+const active = new Map<string, ReadonlySet<string>>();
+function publish(): void {
+  if (active.size === 0) {
+    delete process.env[CHILD_SPEND_ENV];
+    return;
+  }
+  const sets = [...active.values()];
+  const shared = [...sets[0]].filter((tool) => sets.every((s) => s.has(tool)));
+  if (shared.length === 0) delete process.env[CHILD_SPEND_ENV];
+  else process.env[CHILD_SPEND_ENV] = [...new Set(shared)].sort().join(",");
+}
+/**
+ * Advertise `tools` to children spawned while this run is in flight, and return the
+ * release. ALWAYS call the release in a `finally`: a grant that outlives its run would
+ * authorize the next one's children, which is the whole thing this is careful about.
+ * An empty/absent `tools` registers nothing, so a run with no media grant neither widens
+ * nor narrows what a concurrent run advertises.
+ */
+export function grantChildSpend(runKey: string, tools: Iterable<string> | undefined): () => void {
+  const set = new Set([...(tools ?? [])].filter((t) => typeof t === "string" && t.trim() !== ""));
+  if (set.size === 0) return () => {};
+  active.set(runKey, set);
+  publish();
+  return () => {
+    active.delete(runKey);
+    publish();
+  };
+}
+/** Test seam: forget every in-flight grant (and the env var it projects). */
+export function resetChildSpend(): void {
+  active.clear();
+  delete process.env[CHILD_SPEND_ENV];
+}
+/**
+ * The grant this process inherited — empty unless we ARE a subagent child, so a stray
+ * env var can never lower a terminal's gate. Parsed defensively: unknown names simply
+ * never match a tool, and the gate's own guards bound what a match can authorize.
+ */
+export function inheritedChildSpend(env: NodeJS.ProcessEnv = process.env): ReadonlySet<string> {
+  if (!isSubagentChild()) return new Set();
+  const raw = env[CHILD_SPEND_ENV];
+  if (!raw) return new Set();
+  return new Set(
+    raw
+      .split(",")
+      .map((t) => t.trim())
+      .filter(Boolean),
+  );
+}
+/**
+ * Is `tool` pre-authorized for this process? False everywhere but a child that was
+ * granted it. Shape matches GateController.isSpendPreauthorized's needs.
+ */
+export function childSpendAllows(tool: string): boolean {
+  return inheritedChildSpend().has(tool);
+}
+/** Does this child hold any spend grant at all — i.e. should billing tools exist here? */
+export function childHoldsSpendGrant(): boolean {
+  return inheritedChildSpend().size > 0;
+}

package/src/permissions/classify.ts CHANGED Viewed

@@ -118,6 +118,14 @@ function str(v: unknown): string {
   return typeof v === "string" ? v : v == null ? "" : String(v);
 }
+// A path from a list entry that may be a bare string or an object carrying one —
+// video_compose's `tracks` and `images` take both, and the tools open whichever arrives,
+// so the classifier has to resolve whichever arrives. Miss the object form and
+// `tracks: [{path: "~/.ssh/id_rsa"}]` reads a key with `outside` left false.
+function nestedPath(entry: unknown): string {
+  return entry && typeof entry === "object" ? str((entry as Record<string, unknown>).path) : str(entry);
+}
 function firstPath(input: Record<string, unknown>): string {
   return str(input.path ?? input.file_path ?? input.file ?? input.filename ?? input.dir ?? input.directory);
 }
@@ -166,8 +174,10 @@ const BASH_TOOLS = new Set(["bash", "shell", "run", "exec", "sh"]);
 const MEDIA_TOOLS = new Set([
   "generate_image",
   "generate_video",
+  "generate_model",
   "generate_speech",
   "generate_music",
+  "generate_sfx",
   "media_capabilities",
   "video_compose",
 ]);
@@ -181,17 +191,30 @@ const MEDIA_TOOLS = new Set([
 // remembered, so every generation is a fresh human decision. video_compose is
 // excluded on purpose — it is local ffmpeg, no egress and no spend — and
 // media_capabilities is a read.
-const MEDIA_GEN_TOOLS = new Set([
+// Exported because it is the definition of "this call bills, so a human decides": the
+// harbor reads it to work out which of a routine's granted tools its pre-authorization
+// has to cover (harbor/index.ts), and a second hand-written copy of this list there
+// would be one that drifts.
+export const BILLED_MEDIA_TOOLS: ReadonlySet<string> = new Set([
   "generate_image",
   "generate_video",
+  "generate_model",
   "generate_speech",
   "generate_music",
+  "generate_sfx",
 ]);
 const MEDIA_TITLES: Record<string, string> = {
   generate_image: "Generate an image (billed to your Privateer account)",
   generate_video: "Generate a video (billed to your Privateer account)",
+  // The dearest of these per call, and the one whose price moves with the
+  // options, so the title says so out loud rather than leaving the human to
+  // work it out from a JSON blob of flags.
+  generate_model: "Generate a 3D model (billed; $0.14-$2.41 a mesh depending on the model)",
   generate_speech: "Generate speech (billed to your Privateer account)",
   generate_music: "Generate music (billed; music prompts have no zero-retention option)",
+  // Cheap per call and therefore the one most likely to be called twenty times in a
+  // row for a single cut, which is the number the title should let a human weigh.
+  generate_sfx: "Generate a sound effect (billed ~$0.02; effect models are non-ZDR)",
   video_compose: "Compose video/audio locally",
   media_capabilities: "Read media capabilities",
 };
@@ -225,6 +248,28 @@ export function classifyToolCall(
     };
   }
+  // Reading a routine back (src/tools/routineResult.ts): its stored instruction and
+  // its latest result. A READ, and it must be classified as one — the unknown-tool
+  // branch at the bottom would call it bash-kind, which prompts with a JSON blob and
+  // denies outright in plan/readonly, the very posture where "what did last night's
+  // run find?" is the most reasonable question there is.
+  //
+  // It still asks in default mode rather than returning null: the files live in
+  // ~/.privateer (outside any cwd) and can hold whatever the run collected, so
+  // pulling one into a session is the user's call, exactly as reading the file by
+  // hand would be. It takes a NAME, not a path, so there is no target to resolve —
+  // `outside` is therefore left unset (setting it would force a prompt even under
+  // acceptEdits for a read the user just asked for).
+  if (name === "read_routine_result") {
+    const label = str(obj.name);
+    return {
+      tool: toolName,
+      kind: "read",
+      title: "Read a routine's saved result",
+      detail: label ? `routine "${label}" (instruction + latest result)` : "list saved routines",
+    };
+  }
   // Media generation (src/tools/media.ts) and local composition (videoCompose.ts).
   //
   // Left to the unknown-tool branch at the bottom these classify as bash-kind, which
@@ -243,9 +288,22 @@ export function classifyToolCall(
       ...(Array.isArray(obj.inputs) ? (obj.inputs as unknown[]).map(str) : []),
       str(obj.input),
       str(obj.audio),
-      ...(Array.isArray(obj.images) ? (obj.images as unknown[]).map(str) : []),
+      // `images` is a list of paths for generate_video's reference stills and a list of
+      // OBJECTS for video_compose overlay_image's layers — both shapes have to resolve, or
+      // the nested one is a path the gate never judges.
+      ...(Array.isArray(obj.images) ? (obj.images as unknown[]).map(nestedPath) : []),
       str(obj.firstFrame),
       str(obj.lastFrame),
+      // video_compose mix_audio carries its paths INSIDE objects — one per placed
+      // track — and a nested path is one the gate would never judge: `tracks:
+      // [{path: "~/.ssh/id_rsa"}]` would read a key outside scope with `outside`
+      // left false. Bare strings are accepted here too because the tool accepts
+      // them, and the classifier must see whatever the tool will open.
+      ...(Array.isArray(obj.tracks) ? (obj.tracks as unknown[]).map(nestedPath) : []),
+      // overlay_text renders a font file into the frame, and burn_subtitles reads a whole
+      // subtitle file into it, so an out-of-scope or protected one is a read like any other.
+      str(obj.fontFile),
+      str(obj.subtitles),
     ].filter(Boolean);
     // Resolve each input once, then flag the two ways an input is sensitive: it leaves
     // the working directory, or it is a guarded file (.env, keys, credentials, …). The
@@ -297,7 +355,7 @@ export function classifyToolCall(
       detail: `${outputOutside ? absOut : outPath}${inputNote}`,
       protected: isProtectedPath(absOut) || protectedInputs.length > 0,
       outside,
-      alwaysAsk: MEDIA_GEN_TOOLS.has(name),
+      alwaysAsk: BILLED_MEDIA_TOOLS.has(name),
       path: absOut,
     };
   }