agent-accelerator 0.5.9 → 0.6.5

package/src/scheduler/tool.ts

@@ -2,9 +2,8 @@
  * The two model-facing tools of scheduled actions: `scheduled_actions` (one
  * flat tool with a `command` field, a thin wrapper over the developer
  * functions) and `get_datetime`. The tool manual lives in
- * `scheduled-actions.md`, not in code.
+ * `src/prompts/scheduled-actions-tool.md`, not in code.
  */
-import { readFileSync } from "node:fs";
 import { z } from "zod";
 import type { Agent } from "../agent/agent.ts";
 import { tool } from "../tools/tool.ts";
@@ -23,15 +22,10 @@ import {
 } from "./scheduler.ts";
 import { readRun } from "./store.ts";
 import { formatDatetime } from "./time.ts";
+import { fillPrompt } from "../prompts/prompts.ts";
 
 const COMMANDS = ["create", "list", "get", "update", "delete", "run_now", "skip"] as const;
 
-let manual: string | undefined;
-/** Read on first use (not at import), so a program that never enables scheduling never touches the file. */
-function loadManual(): string {
-  return (manual ??= readFileSync(new URL("./scheduled-actions.md", import.meta.url), "utf8"));
-}
-
 /** Returns the machine's local date and time. Exported for any agent; auto-registered with the scheduling tools. */
 export const getDatetimeTool: ToolDefinition = tool({
   name: "get_datetime",
@@ -50,7 +44,12 @@ const scheduledActionSchema = z.object({
   startCookingInAdvance: z.string().optional().describe('Duration "DD:HH:MM" before delivery when the run starts.'),
   repeatEvery: z.string().optional().describe('Duration "DD:HH:MM" between deliveries. Omit to run once.'),
   retries: z.number().optional().describe("Extra attempts if a run fails."),
-  onMissed: z.enum(["skip", "run"]).optional().describe('If the host program was not running at delivery time: "skip" = move on to the next time, "run" = run when it is back. Omit to decide later.'),
+  onMissed: z
+    .enum(["skip", "run"])
+    .optional()
+    .describe(
+      'If the host program was not running at delivery time: "skip" = move on to the next time, "run" = run when it is back. Omit to decide later.'
+    ),
 });
 
 const describedId = "Full action id including its 6-character suffix (get, update, delete, run_now, skip).";
@@ -78,15 +77,25 @@ export function createScheduledActionsTool(agent: Agent): ToolDefinition {
 
   return tool({
     name: "scheduled_actions",
-    description: loadManual().replace("{{TOOLS}}", poolNames.length > 0 ? poolNames.join(", ") : "none (omit tools)"),
+    description: fillPrompt(agent.prompts.scheduledActionsTool, {
+      TOOLS: poolNames.length > 0 ? poolNames.join(", ") : "none (omit tools)",
+    }),
     input: z.object({
       command: z.enum(COMMANDS),
       id: z.string().optional().describe(describedId),
       role: z.string().optional().describe("Short persona for the worker."),
       instructions: z.string().optional().describe("The worker's system prompt (create, update)."),
       task: z.string().optional().describe("The concrete assignment for every run (create, update)."),
-      tools: z.array(z.string()).optional().describe(`Worker tools to grant, from: ${poolNames.join(", ") || "none"}.`),
-      timeoutMs: z.number().optional().describe("Stop a run that takes longer than this many ms (> 0). Omit it for no limit of your own; the host program may cap it."),
+      tools: z
+        .array(z.string())
+        .optional()
+        .describe(`Worker tools to grant, from: ${poolNames.join(", ") || "none"}.`),
+      timeoutMs: z
+        .number()
+        .optional()
+        .describe(
+          "Stop a run that takes longer than this many ms (> 0). Omit it for no limit of your own; the host program may cap it."
+        ),
       scheduled_action: scheduledActionSchema.optional(),
       force: z.boolean().optional().describe("delete: abort a run that is cooking. Ask the user first."),
       purge: z.boolean().optional().describe("delete: also delete past run files."),
@@ -96,14 +105,23 @@ export function createScheduledActionsTool(agent: Agent): ToolDefinition {
       const needId = (): string => {
         const id = a.id ?? sa.id;
         if (!id) {
-          throw new ToolError(`${a.command} needs "id" (the full id including its 6-character suffix; see list). Example: ${JSON.stringify({ command: a.command, id: "daily-ai-brief-d64aj2" })}`);
+          throw new ToolError(
+            `${a.command} needs "id" (the full id including its 6-character suffix; see list). Example: ${JSON.stringify({ command: a.command, id: "daily-ai-brief-d64aj2" })}`
+          );
         }
         return id;
       };
 
       switch (a.command) {
         case "create": {
-          const input = { role: a.role, instructions: a.instructions, task: a.task, tools: a.tools, timeoutMs: a.timeoutMs, scheduled_action: sa } as ScheduledActionInput;
+          const input = {
+            role: a.role,
+            instructions: a.instructions,
+            task: a.task,
+            tools: a.tools,
+            timeoutMs: a.timeoutMs,
+            scheduled_action: sa,
+          } as ScheduledActionInput;
           const problems = validateInput(input, poolTools, getScheduler(home).now(), { requireLead: true });
           if (problems.length > 0) {
             throw new ToolError(
@@ -134,7 +152,9 @@ export function createScheduledActionsTool(agent: Agent): ToolDefinition {
           };
           const changes = [a.role, a.instructions, a.task, a.tools, a.timeoutMs, ...Object.values(schedule)];
           if (changes.every((v) => v === undefined)) {
-            throw new ToolError(`update needs at least one field to change. Example: ${JSON.stringify({ command: "update", id, task: "The new assignment." })}`);
+            throw new ToolError(
+              `update needs at least one field to change. Example: ${JSON.stringify({ command: "update", id, task: "The new assignment." })}`
+            );
           }
           return updateScheduledAction(id, patch, { home });
         }
@@ -145,7 +165,9 @@ export function createScheduledActionsTool(agent: Agent): ToolDefinition {
         case "skip":
           return skipScheduledAction(needId(), { home });
         default:
-          throw new ToolError(`Unknown command ${JSON.stringify((a as { command?: unknown }).command)}. Use one of: ${COMMANDS.join(", ")}.`);
+          throw new ToolError(
+            `Unknown command ${JSON.stringify((a as { command?: unknown }).command)}. Use one of: ${COMMANDS.join(", ")}.`
+          );
       }
     },
   });

package/src/session/architecture.md

@@ -2,14 +2,15 @@
 
 Saving a conversation, its spending and its tool logs.
 
-| File | What it is |
-| :-- | :-- |
-| `store.ts` | Snapshot format (`session.json`, one line per field and per turn), load validation, `SessionTelemetry`, media extraction, journal replay (`replayJournal`), and `priceUsage` (the one cost model, integer micro-USD). |
-| `journal.ts` | `SessionJournal`: after each step appends one fsynced line to `journal.ndjson`; writes a fresh snapshot (new `epoch`) when history changed any other way or the journal passed 500 lines / 4 MB. |
-| `usage.ts` | Pure spending accounting: `UsageTotals`, `usageLine`, `buildUsageReport`. No Agent import. |
-| `tool-log.ts` | `ToolLogs`: one fsynced NDJSON file per tool call under `<session>/tool-logs/`. |
+| File          | What it is                                                                                                                                                                                                            |
+| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `store.ts`    | Snapshot format (`session.json`, one line per field and per turn), load validation, `SessionTelemetry`, media extraction, journal replay (`replayJournal`), and `priceUsage` (the one cost model, integer micro-USD). |
+| `journal.ts`  | `SessionJournal`: after each step appends one fsynced line to `journal.ndjson`; writes a fresh snapshot (new `epoch`) when history changed any other way or the journal passed 500 lines / 4 MB.                      |
+| `usage.ts`    | Pure spending accounting: `UsageTotals`, `usageLine`, `buildUsageReport`. No Agent import.                                                                                                                            |
+| `tool-log.ts` | `ToolLogs`: one fsynced NDJSON file per tool call under `<session>/tool-logs/`.                                                                                                                                       |
 
 ## Invariants
+
 - Layout: `<home>/sessions/<id>/{session.json, journal.ndjson, telemetry.ndjson, media/, tool-logs/, workers/}`. `telemetry.ndjson` is written by `telemetry-file.ts` (opt-in), not by the session code; a folder holding only that file is not a session.
 - A journal whose header epoch differs from the snapshot's is ignored on load.
 - Journal record types: `base`, `msg`, `meta`, `run`, `end`, `tool`, `pending`, `usage`. Replay ignores unknown types, drops a torn last line, and stops at earlier damage with `session.journal_corrupt`.

package/src/session/journal.ts

@@ -32,7 +32,15 @@ const EMPTY_PENDING = JSON.stringify({ steer: [], queue: [] });
 
 // One `tool` journal line; the result is saved as given (tool results are JSON-safe by the time the executor returns them); in: a finished tool call, out: the journal.
 function toolLine(t: SessionToolRecord): string {
-  return JSON.stringify({ t: "tool", call: t.id, name: t.name, result: t.result, ...(t.isError ? { isError: true } : {}), ...(t.stopped ? { stopped: true } : {}) });
+  return JSON.stringify({
+    t: "tool",
+    call: t.id,
+    name: t.name,
+    result: t.result,
+    ...(t.isError ? { isError: true } : {}),
+    ...(t.stopped ? { stopped: true } : {}),
+    ...(t.parts && t.parts.length > 0 ? { parts: t.parts } : {}),
+  });
 }
 
 /** Persists one session folder (`sessions/<id>/`) step by step. */
@@ -80,10 +88,13 @@ export class SessionJournal {
       return;
     }
     const records: string[] = [];
-    for (let i = this.count; i < messages.length; i++) records.push(JSON.stringify({ t: "msg", i, m: this.toDisk(messages[i]!) }));
-    for (let r = this.runCount; r < runs.length; r++) records.push(JSON.stringify({ t: "run", id: runs[r]!.id, i: runs[r]!.i, at: runs[r]!.at }));
+    for (let i = this.count; i < messages.length; i++)
+      records.push(JSON.stringify({ t: "msg", i, m: this.toDisk(messages[i]!) }));
+    for (let r = this.runCount; r < runs.length; r++)
+      records.push(JSON.stringify({ t: "run", id: runs[r]!.id, i: runs[r]!.i, at: runs[r]!.at }));
     for (const mark of runs) {
-      if (mark.end && !this.endsOnDisk.has(mark.id)) records.push(JSON.stringify({ t: "end", id: mark.id, status: mark.end }));
+      if (mark.end && !this.endsOnDisk.has(mark.id))
+        records.push(JSON.stringify({ t: "end", id: mark.id, status: mark.end }));
     }
     const tools = agent.toolRecords ?? [];
     const firstNewTool = this.toolCount > 0 && tools[this.toolCount - 1] === this.lastTool ? this.toolCount : 0; // a new run starts the list over
@@ -129,13 +140,19 @@ export class SessionJournal {
     const epoch = randomUUID();
     const target = path.join(this.dir, "session.json");
     if (this.epoch === undefined) quarantineIfCorrupt(target);
-    const data = buildSessionData({ ...agent, context: { ...agent.context, messages: messages.map((m) => this.toDisk(m)) } }, null);
+    const data = buildSessionData(
+      { ...agent, context: { ...agent.context, messages: messages.map((m) => this.toDisk(m)) } },
+      null
+    );
     writeFileDurable(target, serializeSession({ ...data, epoch }) + "\n");
     const pending = this.pendingOf(agent);
     const tools = agent.toolRecords ?? [];
     // Waiting prompts and the current run's finished tool results live only in the journal, so a new journal starts with them.
     const header =
-      JSON.stringify({ t: "base", e: epoch }) + "\n" + (pending === EMPTY_PENDING ? "" : `{"t":"pending","p":${pending}}\n`) + tools.map((t) => toolLine(t) + "\n").join("");
+      JSON.stringify({ t: "base", e: epoch }) +
+      "\n" +
+      (pending === EMPTY_PENDING ? "" : `{"t":"pending","p":${pending}}\n`) +
+      tools.map((t) => toolLine(t) + "\n").join("");
     writeFileDurable(path.join(this.dir, JOURNAL_FILE), header, { backup: false });
     this.epoch = epoch;
     this.pending = pending;
@@ -165,7 +182,8 @@ export class SessionJournal {
     if (!waiting || waiting.steer.length + waiting.queue.length === 0) return EMPTY_PENDING;
     const parts = (prompt: ContentPart[]): ContentPart[] => {
       let disk = this.promptOnDisk.get(prompt);
-      if (!disk) this.promptOnDisk.set(prompt, (disk = this.toDisk({ role: "user", content: prompt }).content as ContentPart[]));
+      if (!disk)
+        this.promptOnDisk.set(prompt, (disk = this.toDisk({ role: "user", content: prompt }).content as ContentPart[]));
       return disk;
     };
     const slim = (list: SessionPendingPrompt[]): SessionPendingPrompt[] =>
@@ -180,10 +198,15 @@ export class SessionJournal {
 
   // JSON of everything in the snapshot that is not a message, identity or totals; in: the live agent, out: change detection + the `meta` record.
   private metaOf(agent: SessionAgentLike): string {
-    const { version: _v, sessionId: _s, messages: _m, totals: _t, runs: _r, usage: _u, ...rest } = buildSessionData(
-      { ...agent, context: { ...agent.context, messages: [] } },
-      null
-    );
+    const {
+      version: _v,
+      sessionId: _s,
+      messages: _m,
+      totals: _t,
+      runs: _r,
+      usage: _u,
+      ...rest
+    } = buildSessionData({ ...agent, context: { ...agent.context, messages: [] } }, null);
     return JSON.stringify(rest);
   }
 
@@ -202,7 +225,11 @@ export class SessionJournal {
         const dest = path.join(this.dir, "media", file);
         if (!fs.existsSync(dest)) writeFileDurable(dest, found.bytes, { backup: false });
         changed = true;
-        return { ...(part as unknown as Record<string, unknown>), [found.key]: `media/${file}`, ...(found.mimeType ? { mimeType: found.mimeType } : {}) } as unknown as ContentPart;
+        return {
+          ...(part as unknown as Record<string, unknown>),
+          [found.key]: `media/${file}`,
+          ...(found.mimeType ? { mimeType: found.mimeType } : {}),
+        } as unknown as ContentPart;
       });
       if (changed) out = { ...slim, content };
     }

package/src/session/store.ts

@@ -30,7 +30,7 @@ import type { AgentResponse } from "../types/response.ts";
 import { base64ToBytes, bytesToBase64 } from "../utils/base64.ts";
 import { getModelFromCatalog } from "../models/catalog.ts";
 import type { SubAgentStep } from "../types/response.ts";
-import { SessionLoadError } from "../types/errors.ts";
+import { SecurityPolicyError, SessionLoadError, ValidationError } from "../types/errors.ts";
 import { createSessionId } from "../utils/session.ts";
 import { writeFileDurable, readWithBackup } from "../utils/durable.ts";
 import type { UsageTotals } from "./usage.ts";
@@ -83,6 +83,8 @@ export interface SessionToolRecord {
   isError?: boolean;
   /** The tool ended the run with `ctx.stop`. */
   stopped?: boolean;
+  /** Media the tool returned (inline data URLs). */
+  parts?: ContentPart[];
 }
 
 /** A prompt that was waiting when the process stopped (its options other than `additionalContext` are not saved). */
@@ -106,7 +108,7 @@ export interface PersistedAgentSession {
   thinkingLevel?: string;
   cache?: CacheOption;
   /** Legacy read-only: pre-compact files duplicated base instructions here;
-  * no longer written (`systemPrompt` already embeds them). */
+   * no longer written (`systemPrompt` already embeds them). */
   instructions?: string;
   systemPrompt?: string;
   messages: Message[];
@@ -230,7 +232,9 @@ export class SessionTelemetry {
   }
 
   /** Restores totals from a loaded session (tolerates legacy `metrics` shape). */
-  static fromSaved(saved?: PersistedAgentSession | { totals?: SessionTotals; metrics?: Record<string, number> } | null): SessionTelemetry {
+  static fromSaved(
+    saved?: PersistedAgentSession | { totals?: SessionTotals; metrics?: Record<string, number> } | null
+  ): SessionTelemetry {
     const raw: any = (saved as any)?.totals ?? (saved as any)?.metrics ?? null;
     if (!raw) return new SessionTelemetry();
     // Legacy metrics files used {input,output,cacheRead,cacheWrite,reasoning,cost}
@@ -279,15 +283,12 @@ export class SessionTelemetry {
    * Shows per-turn tokens + `turn-CH%`, session totals + `total-CH%`, cost, context %.
    * `thinkingLevel` defaults to the agent's level when omitted.
    */
-  formatBar(
-    res: AgentResponse,
-    opts?: { model?: string; thinkingLevel?: string }
-  ): string {
+  formatBar(res: AgentResponse, opts?: { model?: string; thinkingLevel?: string }): string {
     const inTok = res.usage.inputTokens ?? 0;
     const outTok = res.usage.outputTokens ?? 0;
     const crTok = res.usage.cachedTokens ?? res.usage.cacheReadTokens ?? 0;
     const cwTurnTok = res.usage.cacheWriteTokens ?? 0;
-    const turnRate = (this.turnHitRate(res.usage)).toFixed(1);
+    const turnRate = this.turnHitRate(res.usage).toFixed(1);
     const totalRate = this.totalHitRate().toFixed(1);
     const cwTurnLabel = cwTurnTok > 0 ? ` CW${formatSessionTokens(cwTurnTok)}` : "";
     const totCW = this.totals.cacheWrite;
@@ -350,7 +351,9 @@ export interface SessionAgentLike {
 }
 
 // Slims worker traces for the snapshot (one key per tracking id, repeated final text dropped, reasoning kept); in: buildSessionData, out: the `subagents` field.
-function snapshotSubagents(traces: Record<string, PersistedSubAgentTrace> | undefined): Record<string, PersistedSubAgentTrace> | undefined {
+function snapshotSubagents(
+  traces: Record<string, PersistedSubAgentTrace> | undefined
+): Record<string, PersistedSubAgentTrace> | undefined {
   if (!traces) return undefined;
   const keys = Object.keys(traces);
   if (keys.length === 0) return undefined;
@@ -376,12 +379,7 @@ function snapshotSubagents(traces: Record<string, PersistedSubAgentTrace> | unde
     // Reasoning is never dropped: `thinking`/`thoughtSignature` survive the
     // dedup so persisted worker steps keep their reasoning traces.
     const steps = (t.steps ?? []).map((s) => {
-      if (
-        s.type === "assistant" &&
-        typeof s.text === "string" &&
-        typeof t.text === "string" &&
-        s.text === t.text
-      ) {
+      if (s.type === "assistant" && typeof s.text === "string" && typeof t.text === "string" && s.text === t.text) {
         const marker: SubAgentStep = { turn: s.turn, type: s.type, timestamp: s.timestamp };
         if (typeof s.thinking === "string" && s.thinking) marker.thinking = s.thinking;
         const sig = (s as { thoughtSignature?: unknown }).thoughtSignature;
@@ -463,18 +461,20 @@ function inlineBinaryMedia(messages: Message[]): Message[] {
 }
 
 /** Builds a storable snapshot from a live agent + optional telemetry. */
-export function buildSessionData(agent: SessionAgentLike, telemetry?: SessionTelemetry | SessionTotals | null): PersistedAgentSession {
+export function buildSessionData(
+  agent: SessionAgentLike,
+  telemetry?: SessionTelemetry | SessionTotals | null
+): PersistedAgentSession {
   const rawModel = agent.modelStringOrSpec as any;
   const model = typeof rawModel === "string" ? rawModel : (rawModel?.id ?? String(rawModel ?? ""));
   const rawSub = agent.subagentModel as any;
-  const subagentModel =
-    typeof rawSub === "string" ? rawSub : rawSub?.model ?? rawSub?.id ?? undefined;
-  const totals = telemetry instanceof SessionTelemetry
-    ? telemetry.toJSON()
-    : telemetry ?? undefined;
+  const subagentModel = typeof rawSub === "string" ? rawSub : (rawSub?.model ?? rawSub?.id ?? undefined);
+  const totals = telemetry instanceof SessionTelemetry ? telemetry.toJSON() : (telemetry ?? undefined);
   const parentSessionId =
-    typeof (agent as any)?.parentSessionId === "string" ? (agent as any).parentSessionId as string : undefined;
-  const subagents = snapshotSubagents((agent as any)?.subagentTraces as Record<string, PersistedSubAgentTrace> | undefined);
+    typeof (agent as any)?.parentSessionId === "string" ? ((agent as any).parentSessionId as string) : undefined;
+  const subagents = snapshotSubagents(
+    (agent as any)?.subagentTraces as Record<string, PersistedSubAgentTrace> | undefined
+  );
   const messages = inlineBinaryMedia(stripRedundantRawArguments(agent.context.messages));
   // Field order is the on-disk layout contract: identity → config →
   // systemPrompt → totals → messages → lineage/traces. `instructions` is
@@ -494,7 +494,9 @@ export function buildSessionData(agent: SessionAgentLike, telemetry?: SessionTel
     ...(parentSessionId ? { parentSessionId } : {}),
     ...(subagents ? { subagents } : {}),
     ...(agent.runMarks && agent.runMarks.length > 0 ? { runs: agent.runMarks.map((r) => ({ ...r })) } : {}),
-    ...(agent.usageTotals && agent.usageTotals.turns > 0 ? { usage: JSON.parse(JSON.stringify(agent.usageTotals)) as UsageTotals } : {}),
+    ...(agent.usageTotals && agent.usageTotals.turns > 0
+      ? { usage: JSON.parse(JSON.stringify(agent.usageTotals)) as UsageTotals }
+      : {}),
   };
 }
 
@@ -563,7 +565,8 @@ const OVER_LIMIT = Symbol("session-over-limit");
 
 // Reads a stored `cache` field: a current string value, or a pre-0.5.1 `{ retention }` object (short=5m, medium=1h, long=12h); in: a parsed session file, out: `PersistedAgentSession.cache`.
 function toCacheOption(raw: unknown): CacheOption | undefined {
-  if (typeof raw === "string") return (CACHE_OPTIONS as readonly string[]).includes(raw) ? (raw as CacheOption) : undefined;
+  if (typeof raw === "string")
+    return (CACHE_OPTIONS as readonly string[]).includes(raw) ? (raw as CacheOption) : undefined;
   const legacy: Record<string, CacheOption> = { implicit: "implicit", short: "5m", medium: "1h", long: "12h" };
   const retention = (raw as { retention?: unknown } | null)?.retention;
   return typeof retention === "string" ? legacy[retention] : undefined;
@@ -753,14 +756,17 @@ export const writeFileAtomic = writeFileDurable;
 /** Session id grammar: no traversal, no slashes, no hidden files. */
 export function assertValidSessionId(sessionId: string): void {
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(sessionId)) {
-    throw new Error(`[Agent Accelerator] Invalid sessionId "${sessionId}": must match /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/`);
+    throw new ValidationError(
+      `[Agent Accelerator] Invalid sessionId "${sessionId}": must match /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/`
+    );
   }
 }
 
 /** Renames a genuinely corrupt snapshot to `*.corrupt-<ts>` before it is overwritten (a healthy one over the load limits is our own prior save and is just rewritten). */
 export function quarantineIfCorrupt(file: string): void {
   try {
-    if (inspectSessionPayload(fs.readFileSync(file, "utf8")).status === "corrupt") fs.renameSync(file, `${file}.corrupt-${Date.now()}`);
+    if (inspectSessionPayload(fs.readFileSync(file, "utf8")).status === "corrupt")
+      fs.renameSync(file, `${file}.corrupt-${Date.now()}`);
   } catch {
     // why: no file yet, or it cannot be read: nothing to quarantine.
   }
@@ -840,9 +846,12 @@ function extForMedia(mimeType?: string, filename?: string): string {
 }
 
 // Finds embedded media bytes in a part (binary, `data:` URL or raw base64); remote URLs and local paths are references and give undefined; in: any content part, out: extractMediaToDir and the session journal.
-export function embeddedMedia(part: ContentPart): { key: (typeof MEDIA_PART_KEYS)[number]; bytes: Uint8Array; mimeType?: string; ext: string } | undefined {
+export function embeddedMedia(
+  part: ContentPart
+): { key: (typeof MEDIA_PART_KEYS)[number]; bytes: Uint8Array; mimeType?: string; ext: string } | undefined {
   const p = part as unknown as Record<string, unknown> | null;
-  if (!p || typeof p["type"] !== "string" || !(MEDIA_PART_KEYS as readonly string[]).includes(p["type"])) return undefined;
+  if (!p || typeof p["type"] !== "string" || !(MEDIA_PART_KEYS as readonly string[]).includes(p["type"]))
+    return undefined;
   const key = p["type"] as (typeof MEDIA_PART_KEYS)[number];
   const raw = p[key];
   let bytes: Uint8Array;
@@ -858,7 +867,12 @@ export function embeddedMedia(part: ContentPart): { key: (typeof MEDIA_PART_KEYS
     } else if (looksLikeEmbeddedBase64(raw)) bytes = base64ToBytes(raw.replace(/\s/g, ""));
     else return undefined; // local path or short label: keep as reference
   } else return undefined;
-  return { key, bytes, ...(mimeType ? { mimeType } : {}), ext: extForMedia(mimeType, typeof p["filename"] === "string" ? (p["filename"] as string) : undefined) };
+  return {
+    key,
+    bytes,
+    ...(mimeType ? { mimeType } : {}),
+    ext: extForMedia(mimeType, typeof p["filename"] === "string" ? (p["filename"] as string) : undefined),
+  };
 }
 
 // Copy of the messages that keeps media bytes (structuredClone, else JSON); in: extractMediaToDir/resolveMediaPaths, out: a new array.
@@ -879,15 +893,12 @@ function cloneMessages(messages: Message[]): Message[] {
  * `<sessionDir>/media/` and rewrites those parts to relative `media/…`
  * paths. Remote URLs and filesystem paths are left as references.
  */
-export function extractMediaToDir(
-  messages: Message[],
-  sessionDir: string
-): { messages: Message[]; wrote: string[] } {
+export function extractMediaToDir(messages: Message[], sessionDir: string): { messages: Message[]; wrote: string[] } {
   const cloned = cloneMessages(messages);
   const root = path.resolve(sessionDir);
   const mediaDir = path.resolve(root, "media");
   if (!mediaDir.startsWith(root + path.sep) && mediaDir !== root) {
-    throw new Error("[Agent Accelerator] Media dir escapes session dir");
+    throw new SecurityPolicyError("[Agent Accelerator] Media dir escapes session dir");
   }
   try {
     fs.mkdirSync(mediaDir, { recursive: true, mode: 0o700 });
@@ -896,7 +907,9 @@ export function extractMediaToDir(
   try {
     for (const f of fs.readdirSync(mediaDir)) {
       if (/^(image|audio|video|file)-\d+\.[a-z0-9]{1,5}$/.test(f)) {
-        try { fs.unlinkSync(path.join(mediaDir, f)); } catch {}
+        try {
+          fs.unlinkSync(path.join(mediaDir, f));
+        } catch {}
       }
     }
   } catch {}
@@ -916,7 +929,9 @@ export function extractMediaToDir(
         const dest = path.resolve(mediaDir, file);
         if (!dest.startsWith(mediaDir + path.sep)) continue;
         fs.writeFileSync(dest, bytes, { mode: 0o600 });
-        try { fs.chmodSync(dest, 0o600); } catch {}
+        try {
+          fs.chmodSync(dest, 0o600);
+        } catch {}
       } catch {
         continue;
       }
@@ -963,7 +978,7 @@ export function sessionDirFor(rootDir: string, sessionId: string): string {
   const dir = path.resolve(root, sessionId);
   const rel = path.relative(root, dir);
   if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
-    throw new Error(`[Agent Accelerator] Session dir escapes root: ${sessionId}`);
+    throw new SecurityPolicyError(`[Agent Accelerator] Session dir escapes root: ${sessionId}`);
   }
   return dir;
 }
@@ -984,10 +999,7 @@ export function saveSessionDir(
     fs.mkdirSync(sessionDir, { recursive: true });
   } catch {}
   const { messages } = extractMediaToDir(agent.context.messages, sessionDir);
-  const data = buildSessionData(
-    { ...agent, context: { ...agent.context, messages } },
-    telemetry
-  );
+  const data = buildSessionData({ ...agent, context: { ...agent.context, messages } }, telemetry);
   try {
     const target = path.join(sessionDir, "session.json");
     quarantineIfCorrupt(target);
@@ -1002,7 +1014,15 @@ export function saveSessionDir(
 export const JOURNAL_FILE = "journal.ndjson";
 
 // Snapshot fields a `meta` journal record replaces (everything except messages, identity and totals).
-const JOURNAL_META_KEYS = ["model", "subagentModel", "thinkingLevel", "cache", "systemPrompt", "parentSessionId", "subagents"] as const;
+const JOURNAL_META_KEYS = [
+  "model",
+  "subagentModel",
+  "thinkingLevel",
+  "cache",
+  "systemPrompt",
+  "parentSessionId",
+  "subagents",
+] as const;
 
 // Applies a journal to its snapshot: records of the snapshot's own epoch only, `msg` by index (already-present ones skipped), `run` adds a run boundary, `end` closes one, `usage` replaces the agent's spending totals, `tool` keeps a finished tool result, `pending` replaces the waiting prompts, `meta` replaces config fields, unknown record types ignored; a torn last line is dropped, damage earlier stops the replay with a bus warning; in: the parsed snapshot + journal text, out: loadSessionDir.
 function replayJournal(snapshot: PersistedAgentSession, text: string, file: string): PersistedAgentSession {
@@ -1011,12 +1031,32 @@ function replayJournal(snapshot: PersistedAgentSession, text: string, file: stri
   const session: PersistedAgentSession = { ...snapshot, messages: [...snapshot.messages] };
   let sawHeader = false;
   const stop = (reason: string, line: number): void => {
-    telemetryBus.emitWarning("session.journal_corrupt", `[Agent Accelerator] ${path.basename(file)} line ${line + 1}: ${reason}; the rest of the journal is ignored.`, { file, line: line + 1 });
+    telemetryBus.emitWarning(
+      "session.journal_corrupt",
+      `[Agent Accelerator] ${path.basename(file)} line ${line + 1}: ${reason}; the rest of the journal is ignored.`,
+      { file, line: line + 1 }
+    );
   };
   for (let k = 0; k < lines.length; k++) {
     const line = lines[k]!.trim();
     if (!line) continue;
-    let rec: { t?: unknown; e?: unknown; i?: unknown; m?: unknown; p?: unknown; id?: unknown; at?: unknown; u?: unknown; status?: unknown; call?: unknown; name?: unknown; result?: unknown; isError?: unknown; stopped?: unknown };
+    let rec: {
+      t?: unknown;
+      e?: unknown;
+      i?: unknown;
+      m?: unknown;
+      p?: unknown;
+      id?: unknown;
+      at?: unknown;
+      u?: unknown;
+      status?: unknown;
+      call?: unknown;
+      name?: unknown;
+      result?: unknown;
+      isError?: unknown;
+      stopped?: unknown;
+      parts?: unknown;
+    };
     try {
       rec = JSON.parse(line);
     } catch {
@@ -1035,13 +1075,29 @@ function replayJournal(snapshot: PersistedAgentSession, text: string, file: stri
         break;
       }
       session.messages.push(rec.m as Message);
-    } else if (rec.t === "run" && typeof rec.id === "string" && typeof rec.i === "number" && typeof rec.at === "number") {
-      if (!session.runs?.some((r) => r.id === rec.id)) session.runs = [...(session.runs ?? []), { id: rec.id, i: rec.i, at: rec.at }];
+    } else if (
+      rec.t === "run" &&
+      typeof rec.id === "string" &&
+      typeof rec.i === "number" &&
+      typeof rec.at === "number"
+    ) {
+      if (!session.runs?.some((r) => r.id === rec.id))
+        session.runs = [...(session.runs ?? []), { id: rec.id, i: rec.i, at: rec.at }];
     } else if (rec.t === "end" && typeof rec.id === "string" && typeof rec.status === "string") {
       const mark = session.runs?.find((r) => r.id === rec.id);
       if (mark) session.runs = session.runs!.map((r) => (r === mark ? { ...r, end: rec.status as SessionRunEnd } : r));
     } else if (rec.t === "tool" && typeof rec.call === "string" && typeof rec.name === "string") {
-      session.tools = [...(session.tools ?? []).filter((x) => x.id !== rec.call), { id: rec.call, name: rec.name, result: rec.result, ...(rec.isError ? { isError: true } : {}), ...(rec.stopped ? { stopped: true } : {}) }];
+      session.tools = [
+        ...(session.tools ?? []).filter((x) => x.id !== rec.call),
+        {
+          id: rec.call,
+          name: rec.name,
+          result: rec.result,
+          ...(rec.isError ? { isError: true } : {}),
+          ...(rec.stopped ? { stopped: true } : {}),
+          ...(Array.isArray(rec.parts) ? { parts: rec.parts as ContentPart[] } : {}),
+        },
+      ];
     } else if (rec.t === "usage" && rec.u && typeof rec.u === "object") {
       session.usage = rec.u as UsageTotals; // latest record wins
     } else if (rec.t === "pending" && rec.p && typeof rec.p === "object") {
@@ -1148,11 +1204,9 @@ export const MAX_SESSION_MESSAGES = 50_000;
 /** Default max raw JSON size accepted when loading a session snapshot (override via `SessionLimits`). */
 export const MAX_SESSION_JSON_BYTES = 100 * 1024 * 1024;
 
-// A SessionLoadError-named Error with the SDK prefix; in: validateSessionData, out: the error.
-function sessionLoadError(message: string): Error {
-  const e = new Error(`[Agent Accelerator] Invalid session: ${message}`);
-  e.name = "SessionLoadError";
-  return e;
+// A SessionLoadError with the SDK prefix; in: validateSessionData, out: the error.
+function sessionLoadError(message: string): SessionLoadError {
+  return new SessionLoadError(`[Agent Accelerator] Invalid session: ${message}`);
 }
 
 /**
@@ -1245,12 +1299,12 @@ export function reportUsageAnomaly(detail: { type: string; [k: string]: unknown
  *   (reasoning is generated output); providers that omit one side are
  *   accepted, only impossible `thinking > output` with both present fails.
  *
- * Test helper: throws an Error describing the first violation, returns void
+ * Test helper: throws a ValidationError describing the first violation, returns void
  * when invariants hold. Not called in hot paths (validation only).
  */
 export function assertUsageInvariants(usage: TokenUsage): void {
   const fail = (msg: string): never => {
-    throw new Error(`[Agent Accelerator] Invalid usage: ${msg}`);
+    throw new ValidationError(`[Agent Accelerator] Invalid usage: ${msg}`);
   };
   const ints: Array<[string, unknown]> = [
     ["inputTokens", usage.inputTokens],
@@ -1356,7 +1410,14 @@ function toDollars(microUSD: number): number {
 function resolveEffectivePricing(
   spec: ModelSpec | undefined,
   inputTokens: number
-): { input: number; output: number; cacheRead: number | undefined; cacheWrite: number | undefined; audio: number; tier: string } {
+): {
+  input: number;
+  output: number;
+  cacheRead: number | undefined;
+  cacheWrite: number | undefined;
+  audio: number;
+  tier: string;
+} {
   const base = {
     input: spec?.pricing?.inputPerMillion ?? (spec?.cost?.input as number | undefined) ?? 0,
     output: spec?.pricing?.outputPerMillion ?? (spec?.cost?.output as number | undefined) ?? 0,
@@ -1380,7 +1441,12 @@ function resolveEffectivePricing(
   const tiers = spec.cost?.tiers;
   if (Array.isArray(tiers) && tiers.length > 0) {
     let best: { input: number; output: number; cache_read?: number; size: number } | undefined;
-    for (const t of tiers as Array<{ tier?: { type?: string; size?: number }; input?: number; output?: number; cache_read?: number }>) {
+    for (const t of tiers as Array<{
+      tier?: { type?: string; size?: number };
+      input?: number;
+      output?: number;
+      cache_read?: number;
+    }>) {
       const size = typeof t?.tier?.size === "number" ? t.tier.size : undefined;
       if (size === undefined || size > inputTokens) continue;
       const type = String(t?.tier?.type ?? "").toLowerCase();
@@ -1455,10 +1521,9 @@ export function priceUsage(
   const cachedTokens = usage.cachedTokens ?? usage.cacheReadTokens ?? 0;
   const cacheWriteTokens = usage.cacheWriteTokens ?? 0;
   const audioTokens =
-    (usage as { audioTokens?: unknown }).audioTokens ??
-    (usage as { inputAudioTokens?: unknown }).inputAudioTokens ??
-    0;
-  const audioCount = typeof audioTokens === "number" && Number.isFinite(audioTokens) && audioTokens > 0 ? Math.round(audioTokens) : 0;
+    (usage as { audioTokens?: unknown }).audioTokens ?? (usage as { inputAudioTokens?: unknown }).inputAudioTokens ?? 0;
+  const audioCount =
+    typeof audioTokens === "number" && Number.isFinite(audioTokens) && audioTokens > 0 ? Math.round(audioTokens) : 0;
   const pricing = resolveEffectivePricing(spec, inputTokens);
   if (!pricing.input && !pricing.output && !pricing.cacheRead && !pricing.cacheWrite && !pricing.audio) {
     return undefined;